Skip to content

Snippet format

This page describes the JSON content of every snippet type. For each type it gives what the snippet manages, the keys it needs, the rules for its values, what happens to a key you leave out, what has to be in place first, and examples you can start from. Two kinds of rule appear: what NetDefense refuses when you save the snippet, and what the device does when it applies the snippet, which the “Left out” lists call out as “On the device”.

  • A snippet holds exactly one JSON object.
  • Never put a uuid in the content. NetDefense adds it.
  • Keep secrets out of the content. Write "${name}" and keep the value in a secret variable.
  • Examples use the common interface names lan and wan, and addresses from the documentation ranges (192.0.2.0/24, 198.51.100.0/24, 2001:db8::/32) and example.com. Change them to match your devices.

Jump to a type:

ALIAS

An OPNsense firewall alias: a named list of hosts, networks, ports, URLs and so on that rules refer to by name.

Required keys

  • name
  • type

Value rules

  • type is one of host, network, port, url, urltable, urljson, geoip, networkgroup, mac, asn, dynipv6host, authgroup, internal or external. internal aliases belong to the system, so there is no example for it.
  • For authgroup, content holds the local group's gid, not its name. A gid is specific to the device, so pull it from a device. The only portable value is the stock admins gid, 1999. There is no example for it.
  • name starts with a letter or a single underscore, uses only letters, digits and underscores, and is at most 31 characters.
  • Any field of the device's OPNsense alias model can be set; the full key list is below.
  • Every value is a string. The exceptions are enabled, which may be a string or a JSON boolean, and content, which may be a string or a list of strings. A list anywhere else is refused when you save, and so is a boolean such as "counters": true: write "1" or "0".
  • Keys that only appear in pulled content are ignored; see the key list.

Left out

  • On the device: a key you leave out is reset to the OPNsense default, even on an alias that already exists, so a snippet describes the whole alias.
  • A key the device's OPNsense version doesn't have refuses the whole object.
  • The device joins a content list with newlines.

Preconditions

  • A networkgroup can only list aliases that exist on the device, so deliver them in the same sync or beforehand.
  • An interface value, such as lan, has to exist on the device.

Examples

Host list (host)

{
"enabled": true,
"name": "example_hosts",
"type": "host",
"content": [
"192.0.2.10",
"192.0.2.11"
],
"description": "Example hosts"
}

Network list (network)

{
"enabled": true,
"name": "example_networks",
"type": "network",
"content": [
"192.0.2.0/24",
"198.51.100.0/24"
],
"description": "Example networks"
}

Port list (port)

{
"enabled": true,
"name": "example_ports",
"type": "port",
"content": [
"80",
"443",
"8000:8100"
],
"description": "Example ports"
}

URL of IPs (url)

{
"enabled": true,
"name": "example_url",
"type": "url",
"content": [
"https://example.com/addresses.txt"
],
"description": "Example URL list"
}

URL table (urltable)

{
"enabled": true,
"name": "example_urltable",
"type": "urltable",
"content": [
"https://example.com/addresses.txt"
],
"updatefreq": "1",
"description": "Example URL table"
}

URL table (JSON) (urljson)

{
"enabled": true,
"name": "example_urljson",
"type": "urljson",
"content": [
"https://example.com/addresses.json"
],
"path_expression": "data.address",
"updatefreq": "1",
"description": "Example JSON URL table"
}

Countries (GeoIP) (geoip)

{
"enabled": true,
"name": "example_countries",
"type": "geoip",
"content": [
"NL",
"SE"
],
"proto": "IPv4,IPv6",
"description": "Example countries"
}

Network group (networkgroup)

Needs: the example Host list (ALIAS), or an equivalent object on the device; the example Network list (ALIAS), or an equivalent object on the device.

{
"enabled": true,
"name": "example_group",
"type": "networkgroup",
"content": [
"example_hosts",
"example_networks"
],
"description": "Example network group"
}

MAC addresses (mac)

{
"enabled": true,
"name": "example_macs",
"type": "mac",
"content": [
"00:00:5e:00:53:01"
],
"description": "Example MAC address"
}

BGP ASN (asn)

{
"enabled": true,
"name": "example_asn",
"type": "asn",
"content": [
"64496"
],
"proto": "IPv4,IPv6",
"description": "Example autonomous system"
}

Dynamic IPv6 host (dynipv6host)

{
"enabled": true,
"name": "example_dynamic6",
"type": "dynipv6host",
"content": [
"::1000"
],
"interface": "lan",
"description": "Example dynamic IPv6 host"
}

External (external)

{
"enabled": true,
"name": "example_external",
"type": "external",
"description": "Example external alias"
}

All alias keys

Every key of the OPNsense alias model, with its default, as of OPNsense 26.7. The keys current_items, last_updated, eval_match, eval_nomatch, in_block_*, in_pass_*, out_block_*, out_pass_*, categories_uuid and any key starting with % are ignored at sync. counters is settable.

KeyDefaultValues
enabled 1
name empty
type none one of 14 values
path_expression empty
proto none IPv4, IPv6
interface device-specific a name that exists on the device
counters 0
updatefreq empty
content device-specific a name that exists on the device
password empty
username empty
authtype none (empty), Basic, Bearer, Header
expire empty
categories empty
current_items empty
last_updated empty
eval_nomatch empty
eval_match empty
in_block_p empty
in_block_b empty
in_pass_p empty
in_pass_b empty
out_block_p empty
out_block_b empty
out_pass_p empty
out_pass_b empty
description empty

RULE

An OPNsense firewall rule.

Required keys

  • action

Value rules

  • Any field of the device's OPNsense rule model can be set; the full key list is below.
  • Every value is a string. The one exception is enabled, which may be a string or a JSON boolean. A list is refused when you save, interface included, and so is a boolean such as "log": true: write "1" or "0".
  • action is pass, block or reject.
  • Always set interface, source_net and destination_net. The defaults are any to any with quick on.
  • Keys that only appear in pulled content are ignored; see the key list.
  • A rule's sequence is ignored. Where the rule lands comes from its template's position: PREPEND puts it before the device's own rules, APPEND after them. The snippet's priority decides order only among rules with the same position, lower number first (default 1000). A snippet in several templates is PREPEND if any of them is. OPNsense still evaluates floating rules before interface-group rules, and those before single-interface rules, whatever the position. See Where rules land on the device.

Left out

  • On the device: a key you leave out is reset to the OPNsense default, even on a rule that already exists.
  • A rule with only an action has an empty interface, which OPNsense treats as a floating rule, and with the defaults it passes or blocks everything.
  • A key the device's OPNsense version doesn't have refuses the whole object.

Preconditions

  • An alias named as a source or destination has to exist on the device, so deliver it in the same sync or beforehand.
  • Rules are evaluated in priority order; see Priority and Where rules land on the device.

Examples

Pass LAN to host and port

{
"enabled": true,
"action": "pass",
"interface": "lan",
"direction": "in",
"ipprotocol": "inet",
"protocol": "TCP",
"source_net": "lan",
"destination_net": "192.0.2.10",
"destination_port": "443",
"description": "Pass LAN to 192.0.2.10 port 443"
}

Block from alias

Needs: the example Network list (ALIAS), or an equivalent object on the device.

{
"enabled": true,
"action": "block",
"interface": "wan",
"direction": "in",
"ipprotocol": "inet",
"protocol": "any",
"source_net": "example_networks",
"destination_net": "any",
"log": "1",
"description": "Block inbound from example_networks"
}

Pass DNS to firewall

{
"enabled": true,
"action": "pass",
"interface": "lan",
"direction": "in",
"ipprotocol": "inet",
"protocol": "TCP/UDP",
"source_net": "lan",
"destination_net": "(self)",
"destination_port": "53",
"description": "Pass LAN DNS to the firewall"
}

Pass ping

{
"enabled": true,
"action": "pass",
"interface": "lan",
"direction": "in",
"ipprotocol": "inet",
"protocol": "ICMP",
"icmptype": "echoreq",
"source_net": "lan",
"destination_net": "any",
"description": "Pass ping from LAN"
}

All rule keys

Every key of the OPNsense rule model, with its default, as of OPNsense 26.7. OPNsense 26.1.0 and 26.1.1 lack only tcpflags_any; it is present from 26.1.2.

These keys are ignored at sync, not settable: sequence, sort_order, prio_group, audit, category_colors, legacy, is_automatic, ref, seq, #priority, any key starting with % and any starting with alias_meta_. Where a rule lands is set by its template, not by sequence; see the rules above.

KeyDefaultValues
enabled 1
statetype keep keep, sloppy, modulate, synproxy, none
state-policy none (empty), if-bound, floating
sequence 200
sort_order empty
prio_group empty
action pass pass, block, reject
quick 1
interfacenot 0
interface device-specific a name that exists on the device
direction in in, out, any
ipprotocol inet inet, inet6, inet46
protocol any one of 133 values
icmptype none one of 25 values
icmp6type none one of 19 values
source_net any
source_not 0
source_port empty
destination_net any
destination_not 0
destination_port empty
divert-to device-specific a name that exists on the device
gateway device-specific a name that exists on the device
replyto device-specific a name that exists on the device
disablereplyto 0
log 0
allowopts 0
nosync 0
nopfsync 0
statetimeout empty
udp-first empty
udp-multiple empty
udp-single empty
max-src-nodes empty
max-src-states empty
max-src-conn empty
max empty
max-src-conn-rate empty
max-src-conn-rates empty
overload none (empty), bogons, bogonsv6, 221f3268-0000-4000-8000-00000000a001, sshlockout, virusprot, __lan_network, __lo0_network, __wan_network, __wireguard_network
adaptivestart empty
adaptiveend empty
prio none (empty), 1, 0, 2, 3, 4, 5, 6, 7
set-prio none (empty), 1, 0, 2, 3, 4, 5, 6, 7
set-prio-low none (empty), 1, 0, 2, 3, 4, 5, 6, 7
tag empty
tagged empty
tcpflags1 none syn, ack, fin, rst, psh, urg, ece, cwr
tcpflags2 none syn, ack, fin, rst, psh, urg, ece, cwr
tcpflags_any 0
categories empty
sched device-specific a name that exists on the device
tos none one of 284 values
shaper1 device-specific a name that exists on the device
shaper2 device-specific a name that exists on the device
description empty

UNBOUND_HOST_OVERRIDE

A host override in the Unbound DNS resolver: a name that answers with an address or record you choose.

Required keys

  • hostname
  • domain

Value rules

  • rr is the record type and defaults to A. A and AAAA use server; MX uses mx and mxprio; TXT uses txtdata.
  • enabled defaults to on.
  • Values are strings. A boolean is accepted only on enabled, and a list is refused.
  • Keys the type doesn't know are ignored, and so are the pulled-only keys %…, sequence and templates.

Left out

  • On the device: enabled (on), rr (A), hostname, domain and description are always sent.
  • From agent 1.30.2, a missing server, mx, mxprio, ttl or txtdata is cleared, even on an existing entry. Older agents kept the device's value.
  • From agent 1.30.2, a missing addptr means on, so the override publishes a reverse (PTR) record. For split-horizon DNS, set "addptr": "0".
  • addptr is absent from OPNsense 26.1 and 26.1.2 and present by 26.1.11.

Preconditions

None.

Examples

Host override (A) (A)

{
"enabled": true,
"hostname": "app",
"domain": "example.com",
"rr": "A",
"server": "192.0.2.10",
"addptr": "1",
"description": "Example A record"
}

Host override (AAAA) (AAAA)

{
"enabled": true,
"hostname": "app6",
"domain": "example.com",
"rr": "AAAA",
"server": "2001:db8::10",
"addptr": "1",
"description": "Example AAAA record"
}

Host override (MX) (MX)

{
"enabled": true,
"hostname": "mail",
"domain": "example.com",
"rr": "MX",
"mx": "mx1.example.com",
"mxprio": "10",
"description": "Example MX record"
}

Host override (TXT) (TXT)

{
"enabled": true,
"hostname": "txt",
"domain": "example.com",
"rr": "TXT",
"txtdata": "v=spf1 -all",
"description": "Example TXT record"
}

UNBOUND_DOMAIN_FORWARD

A query forward in the Unbound DNS resolver: queries for one domain go to the DNS server you name.

Required keys

  • domain
  • server

Value rules

  • type is forward for plain DNS or dot for DNS over TLS. A dot forward also takes port and verify, the server name its certificate must carry.
  • dot needs agent 1.29.2 or later; older agents store it as a plain forward.
  • enabled defaults to on.
  • Values are strings. A boolean is accepted only on enabled, forward_tcp_upstream and forward_first, and a list is refused.
  • Keys the type doesn't know are ignored, and so are the pulled-only keys %…, sequence and templates.

Left out

  • On the device: enabled, type, domain, server and description are always sent.
  • From agent 1.30.2, a missing port or verify is cleared. Older agents kept the device's value.
  • A missing forward_tcp_upstream or forward_first means "0".

Preconditions

None.

Examples

Domain forward (forward)

{
"enabled": true,
"type": "forward",
"domain": "corp.example.com",
"server": "192.0.2.53",
"description": "Example domain forward"
}

Domain forward (DNS over TLS) (dot)

{
"enabled": true,
"type": "dot",
"domain": "secure.example.com",
"server": "192.0.2.53",
"port": "853",
"verify": "dns.example.com",
"description": "Example DNS over TLS forward"
}

UNBOUND_HOST_ALIAS

An alias of a host override in the Unbound DNS resolver: a second name for an existing override.

Required keys

  • hostname
  • domain
  • parent_hostname and parent_domain: optional when you save, but the entry fails at sync with "parent host override not found" without them

Value rules

  • enabled defaults to on.
  • Values are strings. A boolean is accepted only on enabled, and a list is refused.
  • Keys the type doesn't know are ignored, and so are the pulled-only keys %…, sequence and templates.

Left out

  • On the device: enabled missing means on.

Preconditions

  • The host override named by parent_hostname and parent_domain has to exist on the device, so deliver it in the same sync or beforehand.

Examples

Host alias

Needs: the example Host override (A) (UNBOUND_HOST_OVERRIDE), or an equivalent object on the device.

{
"enabled": true,
"hostname": "www",
"domain": "example.com",
"parent_hostname": "app",
"parent_domain": "example.com",
"description": "Example host alias"
}

UNBOUND_ACL

An access list in the Unbound DNS resolver: which networks may query it, and what happens to the rest.

Required keys

  • name
  • action
  • networks: optional when you save, but the device's model requires it, so the entry needs it to be accepted

Value rules

  • action is one of allow, deny, refuse, allow_snoop, deny_non_local or refuse_non_local.
  • networks is a list, or a comma-separated string. Saving does not check the CIDR notation.
  • enabled defaults to on.
  • Values are strings. A boolean is accepted only on enabled. networks is the only key that accepts a list.
  • Keys the type doesn't know are ignored, and so are the pulled-only keys %…, sequence and templates.

Left out

  • On the device: networks is always sent, so leaving it out sends an empty value.

Preconditions

None.

Examples

ACL (allow) (allow)

{
"enabled": true,
"name": "example-clients",
"action": "allow",
"networks": [
"192.0.2.0/24"
],
"description": "Example allowed clients"
}

ACL (deny) (deny)

{
"enabled": true,
"name": "example-blocked",
"action": "deny",
"networks": [
"198.51.100.0/24"
],
"description": "Example denied clients"
}

USER

A local user account on the firewall.

Required keys

  • name
  • password: optional when you save, but the device requires it for a user it doesn't have yet

Value rules

  • Write the password as a secret variable, "${name}". A password hash is refused.
  • The description key is descr.
  • A closed set of keys: name, password, disabled, scope, descr, shell, authorizedkeys, expires, email, comment, language, landing_page, groups, priv and templates, spelled exactly. An unknown key is refused when you save, with a hint at the closest valid key. uuid and a ${variable} used as a key name are unknown keys too.
  • A user snippet stored before this check is not changed. From agent 1.30.2, any other key refuses that user at sync with USER_CONTENT_INVALID, and the user is not changed. The rest of the sync applies, and the task fails until the key is fixed. The snippet is refused again on its next edit until it is fixed.
  • groups and priv are lists of strings.

Left out

  • On the device: leaving out disabled means false, so a disabled account is re-enabled. Leaving out scope means user. Leaving out descr clears the description.
  • A missing password on an update keeps the device's password.
  • From agent 1.30.2, a missing shell, authorizedkeys, expires, email, comment, language or landing_page is cleared, and a missing priv means no privileges. A cleared expires makes an expired account usable again, and a cleared authorizedkeys removes its SSH keys. Older agents kept the device's values.
  • The user's groups are the ones its groups lists plus every group whose GROUP snippet lists it as a member; it leaves any other group, except one whose GROUP snippet is external or refused. See Users and groups.
  • A group in groups that the device doesn't have, and that the same sync doesn't create, or whose GROUP snippet is refused in that sync, refuses that user with USER_GROUP_UNKNOWN.
  • A user whose expires date has passed is written at every sync, so OPNsense keeps it locked.

Preconditions

  • A group named in groups should exist on the device, so deliver it in the same sync or beforehand.
  • The variable that holds the password has to exist for every device that receives the snippet.
  • Content that gives an account administrator rights, or lets the device run commands, needs a Superuser signed in interactively. See Snippets that grant administrator rights.

Examples

User

Needs: a variable named example_user_password.

{
"name": "example-user",
"descr": "Example user",
"password": "${example_user_password}",
"scope": "user",
"disabled": false
}

User in a group

Needs: the example Group (GROUP), or an equivalent object on the device; a variable named example_member_password.

{
"name": "example-member",
"descr": "Example group member",
"password": "${example_member_password}",
"scope": "user",
"disabled": false,
"groups": [
"example-staff"
]
}

GROUP

A local group on the firewall, with its privileges and members.

Required keys

  • name

Value rules

  • A closed set of keys: name, description, priv, members, source_networks and external_members. An unknown key is refused when you save, with a hint at the closest valid key. The description key is description, not descr.
  • priv and members are lists of names. For none, write [] or leave the key out.
  • external_members is a JSON boolean, and true needs members to be absent or empty. It is for the members a directory server provides.
  • admins and netdefense-readonly are refused as names.

Left out

  • On the device: leaving out priv or source_networks clears them.
  • From agent 1.30.2, the group's members are the ones its members lists plus every USER snippet that names the group; any other account is removed from it. A missing members adds no one of its own. A key the agent doesn't know, or a members or priv that is neither a list of names nor empty, refuses the group with GROUP_CONTENT_INVALID. See Users and groups.
  • A member that is neither an account on the device nor a user the same sync creates refuses the group with GROUP_MEMBER_UNKNOWN, and the group is not changed.
  • With external_members: true, the device never writes the members, so a directory server can fill them. Mark every group a directory fills this way, or each sync empties it.

Preconditions

  • A user named in members has to exist on the device, so deliver it in the same sync or beforehand.
  • Content that gives an account administrator rights, or lets the device run commands, needs a Superuser signed in interactively. See Snippets that grant administrator rights.

Examples

Group

{
"name": "example-staff",
"description": "Example staff",
"priv": [
"page-diagnostics-ping"
]
}

Group (all keys)

Needs: the example User (USER), or an equivalent object on the device.

{
"name": "example-team",
"description": "Example team",
"priv": [
"page-diagnostics-ping",
"page-diagnostics-traceroute"
],
"members": [
"example-user"
],
"source_networks": "192.0.2.0/24",
"external_members": false
}

Group (directory members) (external)

{
"name": "example-directory-staff",
"description": "Example directory staff",
"priv": [
"page-diagnostics-ping"
],
"external_members": true
}

AUTH_SERVER

An LDAP directory server the firewall signs users in against. See Authentication servers.

Required keys

  • name
  • type (ldap)
  • host
  • ldap_port (a string, 1 to 65535)
  • ldap_urltype
  • ldap_protver (3)
  • ldap_scope (one or subtree)
  • ldap_basedn
  • ldap_authcn
  • ldap_attr_user

Value rules

  • A strict set of keys, all shown in the full example. LDAP is the only server type.
  • ldap_urltype is SSL - Encrypted, StartTLS or TCP - Standard. Cleartext TCP - Standard also needs "nd_allow_cleartext_ldap": true, or the save is refused.
  • ldap_binddn and ldap_bindpw come together or not at all: set both for an authenticated bind, or leave both out for an anonymous one. ldap_bindpw has to be exactly one variable, "${name}". A literal password is refused.
  • ldap_sync_memberof: true needs ldap_read_properties: true and a non-empty ldap_sync_memberof_groups. ldap_sync_create_local_users: true needs memberOf sync or ldap_sync_default_groups.
  • name is 1 to 128 characters of letters, digits and _+.- , with no leading or trailing space. It can be renamed: change the order's entry in the same change, as described in Renaming a server. Local Database and Local API are reserved names.

Left out

  • The key set is strict, so leave out only the keys that the examples leave out.
  • From agent 1.30.2, a missing ldap_sync_memberof_constraint means true, on servers that already exist too: memberOf sync keeps only the groups inside the server's authentication containers. Set it to false to keep every group. See Authentication servers.

Preconditions

  • The variable that holds the bind password has to be a secret variable, and exist for every device that receives the snippet. See Authentication servers.
  • Needs a Superuser signed in interactively.
  • Cannot be pulled from a device.

Examples

LDAP over TLS (SSL - Encrypted)

Needs: a variable named ldap_bind_password.

{
"name": "Example Directory",
"type": "ldap",
"host": "ldap.example.com",
"ldap_port": "636",
"ldap_urltype": "SSL - Encrypted",
"ldap_protver": "3",
"ldap_scope": "subtree",
"ldap_basedn": "DC=example,DC=com",
"ldap_authcn": "OU=Users,DC=example,DC=com",
"ldap_attr_user": "sAMAccountName",
"ldap_binddn": "CN=svc-netdefense,OU=Service Accounts,DC=example,DC=com",
"ldap_bindpw": "${ldap_bind_password}",
"caseInSensitiveUsernames": true
}

LDAP with StartTLS (StartTLS)

Needs: a variable named ldap_bind_password.

{
"name": "Example OpenLDAP",
"type": "ldap",
"host": "ldap.example.com",
"ldap_port": "389",
"ldap_urltype": "StartTLS",
"ldap_protver": "3",
"ldap_scope": "subtree",
"ldap_basedn": "dc=example,dc=com",
"ldap_authcn": "ou=people,dc=example,dc=com",
"ldap_attr_user": "uid",
"ldap_binddn": "cn=netdefense,dc=example,dc=com",
"ldap_bindpw": "${ldap_bind_password}"
}

LDAP over TLS (all keys) (SSL - Encrypted)

Needs: a variable named ldap_bind_password.

{
"name": "Example Directory Full",
"type": "ldap",
"host": "ldap.example.com",
"ldap_port": "636",
"ldap_urltype": "SSL - Encrypted",
"ldap_protver": "3",
"ldap_scope": "subtree",
"ldap_basedn": "DC=example,DC=com",
"ldap_authcn": "OU=Users,DC=example,DC=com",
"ldap_extended_query": "memberOf=CN=Staff,OU=Groups,DC=example,DC=com",
"ldap_attr_user": "sAMAccountName",
"ldap_binddn": "CN=svc-netdefense,OU=Service Accounts,DC=example,DC=com",
"ldap_bindpw": "${ldap_bind_password}",
"caseInSensitiveUsernames": true,
"ldap_read_properties": false,
"ldap_sync_memberof": false,
"ldap_sync_memberof_constraint": true,
"ldap_attr_memberof": "memberOf",
"ldap_sync_memberof_groups": "",
"ldap_sync_default_groups": "",
"ldap_sync_create_local_users": false,
"nd_allow_cleartext_ldap": false
}

AUTH_ORDER

The order in which the firewall tries its authentication sources when someone signs in to the WebAdmin.

Required keys

  • facilities

Value rules

  • The shape is {"facilities": {"webadmin": {"order": [...]}}}, and nothing else.
  • order lists authentication source names, such as Local Database and the name of a directory server. It has 1 to 8 entries, no two the same (compared without regard to case), and no entry contains a comma.
  • Local Database has to come first, and Local API is refused.

Left out

  • The key set is strict. If the snippet stops reaching a device, the device keeps the order last written and NetDefense stops touching it; see Absent means untouched.

Preconditions

  • Every name in the list has to exist on the device, so deliver the directory server in the same sync or beforehand.
  • Needs a Superuser signed in interactively.
  • Cannot be pulled from a device.

Examples

Local database only

{
"facilities": {
"webadmin": {
"order": [
"Local Database"
]
}
}
}

Local database, then directory

Needs: the example LDAP over TLS (AUTH_SERVER), or an equivalent object on the device.

{
"facilities": {
"webadmin": {
"order": [
"Local Database",
"Example Directory"
]
}
}
}

TRUST_CA

A certificate authority that the firewall trusts. See Certificates.

Required keys

  • name
  • crt

Value rules

  • No other keys. The uuid is generated.
  • name is 1 to 255 bytes, with no leading or trailing whitespace and no control characters.
  • crt is exactly one PEM certificate, or exactly one variable, "${name}". A ${ anywhere else is refused.
  • Private key material is refused anywhere in the content.

Left out

  • Both keys are required.

Preconditions

  • Needs a Superuser signed in interactively.
  • Cannot be pulled from a device.

Examples

CA from a variable

Needs: a variable named example_ca_crt.

{
"name": "Example Variable CA",
"crt": "${example_ca_crt}"
}

TRUST_CERT

A certificate and its private key, installed on the firewall. See Certificates.

Required keys

  • name
  • crt
  • key

Value rules

  • No other keys. The uuid is generated.
  • name is 1 to 255 bytes, with no leading or trailing whitespace and no control characters.
  • crt is exactly one PEM certificate, or exactly one variable. A ${ anywhere else is refused.
  • key has to be exactly one variable, "${name}", written as the whole value. A private key never appears in the snippet, and private key material is refused anywhere in the content.

Left out

  • All three keys are required.

Preconditions

  • The variable that holds the private key has to be a secret variable, and exist for every device that receives the snippet.
  • Needs a Superuser signed in interactively.
  • Cannot be pulled from a device.

Examples

Certificate with key

Needs: a variable named example_cert_crt; a variable named example_cert_key.

{
"name": "Example Certificate",
"crt": "${example_cert_crt}",
"key": "${example_cert_key}"
}

ZABBIX_SETTINGS

The settings of the Zabbix agent plugin on the firewall.

Required keys

  • No key is required, but send the full set in the example plus a hostname: see "Left out" below.

Value rules

  • One configuration per device. When several snippets of this type reach a device, the one with the lowest priority number applies, and a tie at the lowest number fails the sync.
  • Booleans have to be JSON booleans, true or false. Saving checks only enable_remote_commands and sudo_root as booleans and server_list and active_check_servers as lists; a wrong type on any other boolean fails the sync on the device.
  • Numbers are strings.
  • encryption_psk should be a secret variable.
  • Give every snippet its hostname. A snippet several devices share can use a variable, such as "hostname": "${zabbix_hostname}". Give that variable a value for each device, as a Device-scope variable, or every device reports the same hostname. A variable with no value at any scope fails the device's sync build as undefined.

Left out

  • On the device, from agent 1.30.2: a key you leave out takes the plugin's fresh-install value. A snippet without enabled turns the agent off, and one without enable_active_checks turns active checks on. The hostname becomes Zabbix agent, listen_ip 0.0.0.0, the server list 127.0.0.1 and the timeout 3 seconds, and source_ip, the encryption identity and the PSK are cleared. If you use encryption, spell out the PSK and the identity.
  • Older agents sent a missing boolean as false and kept the device's text values.

Preconditions

  • Turning on enable_remote_commands or sudo_root needs a Superuser signed in interactively.

Examples

Zabbix agent (all keys)

Needs: a variable named zabbix_hostname.

{
"hostname": "${zabbix_hostname}",
"enabled": true,
"server_list": [
"192.0.2.50"
],
"listen_port": "10050",
"listen_ip": [
"0.0.0.0"
],
"source_ip": "",
"listen_backlog": "",
"syslog_enable": true,
"log_file_size": "100",
"debug_level": "3",
"sudo_root": false,
"start_agents": "3",
"buffer_send": "5",
"buffer_size": "100",
"max_lines_per_second": "20",
"timeout": "3",
"enable_active_checks": true,
"active_check_servers": [
"192.0.2.50"
],
"refresh_active_checks": "120",
"enable_remote_commands": false,
"log_remote_commands": false,
"encryption": "0",
"encryption_identity": "",
"encryption_psk": ""
}

Zabbix agent with PSK (all keys)

Needs: a variable named zabbix_hostname; a variable named zabbix_psk.

{
"hostname": "${zabbix_hostname}",
"enabled": true,
"server_list": [
"192.0.2.50"
],
"listen_port": "10050",
"listen_ip": [
"0.0.0.0"
],
"source_ip": "",
"listen_backlog": "",
"syslog_enable": true,
"log_file_size": "100",
"debug_level": "3",
"sudo_root": false,
"start_agents": "3",
"buffer_send": "5",
"buffer_size": "100",
"max_lines_per_second": "20",
"timeout": "3",
"enable_active_checks": true,
"active_check_servers": [
"192.0.2.50"
],
"refresh_active_checks": "120",
"enable_remote_commands": false,
"log_remote_commands": false,
"encryption": "1",
"encryption_identity": "nd-example",
"encryption_psk": "${zabbix_psk}"
}

ZABBIX_USERPARAMETER

A custom item the Zabbix agent can report: a key that runs a command on the firewall.

Required keys

  • key

Value rules

  • key starts with nd-. The device checks this at sync, not when you save.
  • accept_params is a JSON boolean.
  • command is optional when you save, but an item without one does nothing.

Left out

  • On the device: from agent 1.30.2, leaving out enabled means on; older agents created the entry disabled. Leaving out accept_params means false.

Preconditions

  • The command field needs a Superuser signed in interactively, and a device that accepts dangerous snippets (the device's "reject dangerous snippets" setting off). See Device-Side Protection.

Examples

Zabbix user parameter

{
"enabled": true,
"key": "nd-example-uptime",
"command": "/usr/bin/uptime",
"accept_params": false
}

ZABBIX_ALIAS

A second name for an item the Zabbix agent already reports.

Required keys

  • key

Value rules

  • key starts with nd- and has no dot. The device checks this at sync, not when you save.
  • source_key is optional when you save, but an alias without one points at nothing.
  • accept_params is a JSON boolean.

Left out

  • On the device: from agent 1.30.2, leaving out enabled means on; older agents created the entry disabled. Leaving out accept_params means false.

Preconditions

None.

Examples

Zabbix item key alias

{
"enabled": true,
"key": "nd-example-load",
"source_key": "system.cpu.load[all,avg1]",
"accept_params": false
}

CROWDSEC_SETTINGS

The settings of the CrowdSec plugin on the firewall. See CrowdSec.

Required keys

  • At least one key: an empty object is refused.

Value rules

  • One configuration per device. When several snippets of this type reach a device, the one with the lowest priority number applies, and a tie at the lowest number fails the sync.
  • A closed set of eight keys, all in the full example: agent_enabled, lapi_enabled, firewall_bouncer_enabled, rules_enabled, rules_log, rules_tag, crowdsec_firewall_verbose and enroll_key. An unknown key, uuid included, is refused with a hint at the closest valid key.
  • Booleans have to be JSON booleans.
  • rules_tag and enroll_key take 1 to 63 ASCII letters or digits, an empty value, or a variable placeholder. enroll_key should be a secret variable.

Left out

  • From agent 1.30.2, a key you leave out takes the plugin's default: agent_enabled, lapi_enabled, firewall_bouncer_enabled and rules_enabled are on, rules_log and crowdsec_firewall_verbose are off, and rules_tag and enroll_key are cleared. Older agents kept the device's value. See What a sync does.

Preconditions

  • The CrowdSec plugin on the device; see CrowdSec.

Examples

CrowdSec protection

{
"agent_enabled": true,
"lapi_enabled": true,
"firewall_bouncer_enabled": true,
"rules_enabled": true
}

CrowdSec (all keys)

{
"agent_enabled": true,
"lapi_enabled": true,
"firewall_bouncer_enabled": true,
"rules_enabled": true,
"rules_log": false,
"rules_tag": "netdefense",
"crowdsec_firewall_verbose": false,
"enroll_key": ""
}