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”.
Rules for every snippet
Section titled “Rules for every snippet”- A snippet holds exactly one JSON object.
- Never put a
uuidin 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
lanandwan, and addresses from the documentation ranges (192.0.2.0/24, 198.51.100.0/24, 2001:db8::/32) andexample.com. Change them to match your devices.
Jump to a type:
- Firewall:
ALIAS,RULE - DNS:
UNBOUND_HOST_OVERRIDE,UNBOUND_DOMAIN_FORWARD,UNBOUND_HOST_ALIAS,UNBOUND_ACL - Accounts:
USER,GROUP - Authentication:
AUTH_SERVER,AUTH_ORDER - Certificates:
TRUST_CA,TRUST_CERT - Monitoring:
ZABBIX_SETTINGS,ZABBIX_USERPARAMETER,ZABBIX_ALIAS - Security:
CROWDSEC_SETTINGS
ALIAS
An OPNsense firewall alias: a named list of hosts, networks, ports, URLs and so on that rules refer to by name.
Required keys
nametype
Value rules
typeis one ofhost,network,port,url,urltable,urljson,geoip,networkgroup,mac,asn,dynipv6host,authgroup,internalorexternal.internalaliases belong to the system, so there is no example for it.- For
authgroup,contentholds 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 stockadminsgid,1999. There is no example for it. namestarts 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, andcontent, 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
contentlist with newlines.
Preconditions
- A
networkgroupcan only list aliases that exist on the device, so deliver them in the same sync or beforehand. - An
interfacevalue, such aslan, 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.
| Key | Default | Values |
|---|---|---|
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,interfaceincluded, and so is a boolean such as"log": true: write"1"or"0". actionispass,blockorreject.- Always set
interface,source_netanddestination_net. The defaults are any to any withquickon. - Keys that only appear in pulled content are ignored; see the key list.
- A rule's
sequenceis 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
actionhas 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.
| Key | Default | Values |
|---|---|---|
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
hostnamedomain
Value rules
rris the record type and defaults toA.AandAAAAuseserver;MXusesmxandmxprio;TXTusestxtdata.enableddefaults 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
%…,sequenceandtemplates.
Left out
- On the device:
enabled(on),rr(A),hostname,domainanddescriptionare always sent. - From agent 1.30.2, a missing
server,mx,mxprio,ttlortxtdatais cleared, even on an existing entry. Older agents kept the device's value. - From agent 1.30.2, a missing
addptrmeans on, so the override publishes a reverse (PTR) record. For split-horizon DNS, set"addptr": "0". addptris 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
domainserver
Value rules
typeisforwardfor plain DNS ordotfor DNS over TLS. Adotforward also takesportandverify, the server name its certificate must carry.dotneeds agent 1.29.2 or later; older agents store it as a plain forward.enableddefaults to on.- Values are strings. A boolean is accepted only on
enabled,forward_tcp_upstreamandforward_first, and a list is refused. - Keys the type doesn't know are ignored, and so are the pulled-only keys
%…,sequenceandtemplates.
Left out
- On the device:
enabled,type,domain,serveranddescriptionare always sent. - From agent 1.30.2, a missing
portorverifyis cleared. Older agents kept the device's value. - A missing
forward_tcp_upstreamorforward_firstmeans"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
hostnamedomainparent_hostnameandparent_domain: optional when you save, but the entry fails at sync with "parent host override not found" without them
Value rules
enableddefaults 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
%…,sequenceandtemplates.
Left out
- On the device:
enabledmissing means on.
Preconditions
- The host override named by
parent_hostnameandparent_domainhas 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
nameactionnetworks: optional when you save, but the device's model requires it, so the entry needs it to be accepted
Value rules
actionis one ofallow,deny,refuse,allow_snoop,deny_non_localorrefuse_non_local.networksis a list, or a comma-separated string. Saving does not check the CIDR notation.enableddefaults to on.- Values are strings. A boolean is accepted only on
enabled.networksis the only key that accepts a list. - Keys the type doesn't know are ignored, and so are the pulled-only keys
%…,sequenceandtemplates.
Left out
- On the device:
networksis 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
namepassword: 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,privandtemplates, spelled exactly. An unknown key is refused when you save, with a hint at the closest valid key.uuidand 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. groupsandprivare lists of strings.
Left out
- On the device: leaving out
disabledmeans false, so a disabled account is re-enabled. Leaving outscopemeansuser. Leaving outdescrclears the description. - A missing
passwordon an update keeps the device's password. - From agent 1.30.2, a missing
shell,authorizedkeys,expires,email,comment,languageorlanding_pageis cleared, and a missingprivmeans no privileges. A clearedexpiresmakes an expired account usable again, and a clearedauthorizedkeysremoves its SSH keys. Older agents kept the device's values. - The user's groups are the ones its
groupslists plus every group whoseGROUPsnippet lists it as a member; it leaves any other group, except one whoseGROUPsnippet is external or refused. See Users and groups. - A group in
groupsthat the device doesn't have, and that the same sync doesn't create, or whoseGROUPsnippet is refused in that sync, refuses that user withUSER_GROUP_UNKNOWN. - A user whose
expiresdate has passed is written at every sync, so OPNsense keeps it locked.
Preconditions
- A group named in
groupsshould 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_networksandexternal_members. An unknown key is refused when you save, with a hint at the closest valid key. The description key isdescription, notdescr. privandmembersare lists of names. For none, write[]or leave the key out.external_membersis a JSON boolean, andtrueneedsmembersto be absent or empty. It is for the members a directory server provides.adminsandnetdefense-readonlyare refused as names.
Left out
- On the device: leaving out
privorsource_networksclears them. - From agent 1.30.2, the group's members are the ones its
memberslists plus everyUSERsnippet that names the group; any other account is removed from it. A missingmembersadds no one of its own. A key the agent doesn't know, or amembersorprivthat is neither a list of names nor empty, refuses the group withGROUP_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
membershas 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
nametype(ldap)hostldap_port(a string, 1 to 65535)ldap_urltypeldap_protver(3)ldap_scope(oneorsubtree)ldap_basednldap_authcnldap_attr_user
Value rules
- A strict set of keys, all shown in the full example. LDAP is the only server type.
ldap_urltypeisSSL - Encrypted,StartTLSorTCP - Standard. CleartextTCP - Standardalso needs"nd_allow_cleartext_ldap": true, or the save is refused.ldap_binddnandldap_bindpwcome together or not at all: set both for an authenticated bind, or leave both out for an anonymous one.ldap_bindpwhas to be exactly one variable,"${name}". A literal password is refused.ldap_sync_memberof: trueneedsldap_read_properties: trueand a non-emptyldap_sync_memberof_groups.ldap_sync_create_local_users: trueneeds memberOf sync orldap_sync_default_groups.nameis 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 DatabaseandLocal APIare 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_constraintmeans true, on servers that already exist too: memberOf sync keeps only the groups inside the server's authentication containers. Set it tofalseto 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. orderlists authentication source names, such asLocal Databaseand 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 Databasehas to come first, andLocal APIis 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
namecrt
Value rules
- No other keys. The
uuidis generated. nameis 1 to 255 bytes, with no leading or trailing whitespace and no control characters.crtis 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
namecrtkey
Value rules
- No other keys. The
uuidis generated. nameis 1 to 255 bytes, with no leading or trailing whitespace and no control characters.crtis exactly one PEM certificate, or exactly one variable. A${anywhere else is refused.keyhas 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,
trueorfalse. Saving checks onlyenable_remote_commandsandsudo_rootas booleans andserver_listandactive_check_serversas lists; a wrong type on any other boolean fails the sync on the device. - Numbers are strings.
encryption_pskshould 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
enabledturns the agent off, and one withoutenable_active_checksturns active checks on. ThehostnamebecomesZabbix agent,listen_ip0.0.0.0, the server list127.0.0.1and the timeout 3 seconds, andsource_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_commandsorsudo_rootneeds 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
keystarts withnd-. The device checks this at sync, not when you save.accept_paramsis a JSON boolean.commandis optional when you save, but an item without one does nothing.
Left out
- On the device: from agent 1.30.2, leaving out
enabledmeans on; older agents created the entry disabled. Leaving outaccept_paramsmeans false.
Preconditions
- The
commandfield 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
keystarts withnd-and has no dot. The device checks this at sync, not when you save.source_keyis optional when you save, but an alias without one points at nothing.accept_paramsis a JSON boolean.
Left out
- On the device: from agent 1.30.2, leaving out
enabledmeans on; older agents created the entry disabled. Leaving outaccept_paramsmeans 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_verboseandenroll_key. An unknown key,uuidincluded, is refused with a hint at the closest valid key. - Booleans have to be JSON booleans.
rules_tagandenroll_keytake 1 to 63 ASCII letters or digits, an empty value, or a variable placeholder.enroll_keyshould 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_enabledandrules_enabledare on,rules_logandcrowdsec_firewall_verboseare off, andrules_tagandenroll_keyare 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": ""}