FIREWALLD.RICHLANG(5)

📦
version 2.5.2 · 12 versions
, in arch rolling, nixpkgs unstable, ubuntu stonking

💖 firewalld.richlanguage(5) — the rich language, bestie edition ✨

okay so this is the manual for firewalld.richlanguage, and it's giving Rich Language Documentation. get comfy, grab a boba, we're gonna make firewall rules together and it's gonna slay 🫶

🌸 NAME 🌸

firewalld.richlanguage — Rich Language Documentation. yes that's literally it. that's the name. iconique.

✨ DESCRIPTION ✨

so with the rich language you can build way more complex firewall rules, and the whole point is that it stays easy to understand. it uses keywords with values, and it's basically an abstract little representation of ip*tables rules. cute, right? 💅

here's the tea: the rich language takes the zone elements you already know — service, port, icmp-block, icmp-type, masquerade, forward-port and source-port — and levels them up with extra source and destination addresses, logging, actions and limits for logs and actions. character development fr fr.

this page describes the rich language as it's used in the command line client and the D-Bus interface. if you want the rich language representation used in the zone configuration files, go peek at firewalld.zone(5) instead. different vibe, same family 💜

a rule is part of a zone. one zone can contain several rules. and if some rules interact or contradict each other? the first rule that matches "wins". no takebacks, no redo. 👑

🌈 General rule structure

rule
  [source]
  [destination]
  service|port|protocol|icmp-block|icmp-type|masquerade|forward-port|source-port
  [log|nflog]
  [audit]
  [accept|reject|drop|mark]

the complete rule is provided as a single line string. a destination is allowed here as long as it does not conflict with the destination of a service.

🦋 Rule structure for source black or white listing

rule
  source
  [log|nflog]
  [audit]
  accept|reject|drop|mark

this one is the girlboss of access control: it's used to grant or limit access from a source to this machine, or to machines that are reachable by this machine. heads up tho — a destination is not allowed here. nope. not invited. 🙅‍♀️

🎀 Important information about element options

options for elements in a rule need to be added exactly after the element. that's the rule. if you put the option somewhere else, it might get used for another element — as long as it matches that other element's options — or it'll just straight up result in a rule error. so like, keep your options next to their element, bestie. ✨

⭐ Rule

rule [family="ipv4|ipv6"] [priority="priority"]

if the rule family is provided, it can be either "ipv4" or "ipv6", and that limits the rule to IPv4 or IPv6. if you don't provide a rule family, the rule gets added for both IPv4 and IPv6. 🎉

if source or destination addresses are used in a rule, then the rule family needs to be provided. same deal for port/packet forwarding. no family, no vibes. 😤

if the rule priority is provided, it can be in the range of -32768 to 32767, where lower values have higher precedence. rich rules get sorted by priority. ordering for rules with the same priority value is undefined (💀 literally a coin flip, don't rely on it).

  • a negative priority value will be executed before other firewalld primitives.
  • a positive priority value will be executed after other firewalld primitives.
  • a priority value of 0 will place the rule in a chain based on the action, as per the "Information about logging and actions" section below 👇

🍓 Source

source [not] address="address[/mask]"|mac="mac-address"|ipset="ipset"

with the source address, the origin of a connection attempt can be limited to the source address. an address is either a single IP address, a network IP address, a MAC address or an IPSet. the address has to match the rule family (IPv4/IPv6). 🔍

subnet mask is expressed in either dot-decimal (/x.x.x.x) or prefix (/x) notations for IPv4, and in prefix notation (/x) for IPv6 network addresses.

and the fun part: it's possible to invert the sense of an address by adding not before address. all but the specified address will match then. flipped u, flipped the whole thing 💅

🌸 Destination

destination [not] address="address[/mask]"|ipset="ipset"

with the destination address, the target can be limited to the destination address. the destination address uses the same syntax as the source address. twins!

the use of source and destination addresses is optional, and the use of a destination address is not possible with all elements. this depends on the use of destination addresses — for example, in service entries. so like, read the room before you commit. 🙈

💜 Service

service name="service name"

the service service name will be added to the rule. the service name is one of the firewalld provided services. to get a list of the supported services, use firewall-cmd --get-services. go get that list bestie, it's right there 👑

if a service provides a destination address, it will conflict with a destination address in the rule and will result in an error. the services using destination addresses internally are mostly services using multicast. so that's the drama. 😭

🦋 Port

port port="port value" protocol="tcp|udp|sctp|dccp"

the port port value can either be a single port number portid or a port range portid-portid. the protocol can either be tcp, udp, sctp or dccp. pick your fighter.

✨ Protocol

protocol value="protocol value"

the protocol value can be either a protocol id number or a protocol name. for the allowed protocol entries, please have a look at /etc/protocols. it's all in there, no guessing. 📖

🎀 Tcp-Mss-Clamp

tcp-mss-clamp="value=pmtu|value=number >= 536|None"

the tcp-mss-clamp sets the maximum segment size in the rule.

tcp-mss-clamp has an optional attribute value, which can either be set to "pmtu" or a number greater than or equal to 536. if the attribute value is not present, then the maximum segment size is automatically set to "pmtu". automatic, like your bestie remembering your order 🫶

💀 ICMP-Block

icmp-block name="icmptype name"

the icmptype is one of the icmp types firewalld supports. to get a listing of supported icmp types: firewall-cmd --get-icmptypes

it is not allowed to specify an action here. icmp-block uses the action reject internally. it said "I got this" and it does. 🙅‍♀️

👑 Masquerade

masquerade

turn on masquerading in the rule. a source and also a destination address can be provided to limit masquerading to this area.

it is not allowed to specify an action here.

⚠️ Note: IP forwarding will be implicitly enabled. it's happening whether you asked or not, bestie.

🌈 ICMP-Type

icmp-type name="icmptype name"

the icmptype is one of the icmp types firewalld supports. to get a listing of supported icmp types: firewall-cmd --get-icmptypes. yes this is the same command as before. yes it's still iconic. ✨

🔥 Forward-Port

forward-port port="port value" protocol="tcp|udp|sctp|dccp" to-port="port value" to-addr="address"

forward port/packets from local port value with protocol "tcp" or "udp" to either another port locally, or to another machine, or to another port on another machine. so many destinations, so little time. 🦋

the port value can either be a single port number or a port range portid-portid. the to-addr is an IP address. the protocol can either be tcp, udp, sctp or dccp.

it is not allowed to specify an action here. forward-port uses the action accept internally.

⚠️ Note: IP forwarding will be implicitly enabled if to-addr is specified.
⚠️ Note: When this option is used with --policy, it's impossible for the firewall backend to determine the egress zone. See section UNKNOWN DESTINATIONS in firewall-cmd(1) for more information. go read it, i'm not kidding 😭

🧚 Source-Port

source-port port="port value" protocol="tcp|udp|sctp|dccp"

the source-port port value can either be a single port number portid or a port range portid-portid. the protocol can either be tcp, udp, sctp or dccp. the mirrored sibling of port, we love symmetry 💅

🍓 Log

log [prefix="prefix text"] [level="log level"] [limit value="rate/duration"]

log new connection attempts to the rule with kernel logging — for example in syslog. 📝

you can define a prefix text with a maximum length of 127 characters that will be added to the log message as a prefix.

log level can be one of "emerg", "alert", "crit", "error", "warning", "notice", "info" or "debug", where the default (i.e. if there's not one specified) is "warning". see syslog(3) for description of levels. see the Limit section for description of the limit tag.

⚠️ Note: The iptables backend truncates prefix to 29 characters. 127? 29? yeah. it's giving betrayal.

⭐ NFLog

nflog [group="group id"] [prefix="prefix text"] [queue-size="threshold"] [limit value="rate/duration"]

log new connection attempts to the rule using kernel logging to pass the packets through a 'netlink' socket to users or applications monitoring the multicast group. 🌐

the minimum and default value for group is 0, and the maximum value is 65535. see NETLINK_NETFILTER in netlink(7) and NFLOG in both iptables-extensions(8) and nft(8) man pages for a more detailed description — they went deep on this one.

you can define a prefix text with a maximum length of 127 characters that will be added to the log message as a prefix.

the queue-size option can be set to increase the queue threshold, which can help limit context switching (we love efficiency 💅). the default value for queue-size is 1, and the maximum value is 65535. see iptables-extensions(8) and nft(8) for more details.

see the Limit section for description of the limit tag.

⚠️ Note: The iptables backend truncates prefix to 63 characters. different number than log, don't mix them up bestie.

🌸 Audit

audit [limit value="rate/duration"]

audit provides an alternative way for logging using audit records sent to the service auditd. the audit type will be discovered from the rule action automatically (she's self-sufficient 👑). use of audit is optional. see the Limit section for description of the limit tag.

💜 Action

an action can be one of accept, reject, drop or mark.

the rule can either contain an element or also a source only. if the rule contains an element, then new connection matching the element will be handled with the action. if the rule does not contain an element, then everything from the source address will be handled with the action. no element, no filter, whole source gets the treatment. 💅

accept [limit value="rate/duration"]

reject [type="reject type"] [limit value="rate/duration"]

drop [limit value="rate/duration"]

mark set="mark[/mask]" [limit value="rate/duration"]

with accept, all new connection attempts will be granted. 🎉

with reject, they will not be accepted, and their source will get a reject ICMP(v6) message. the reject type can be set to specify the appropriate ICMP(v6) error message. for valid reject types see --reject-with type in the iptables-extensions(8) man page. because reject types are different for IPv4 and IPv6, you have to specify the rule family when using reject type. don't skip that step, it matters ⚠️

with drop, all packets will be dropped immediately, and there is no information sent to the source. silence. absolute silence. 💀

with mark, all packets will be marked in the PREROUTING chain in the mangle table with the mark and mask combination.

see the Limit section for description of the limit tag.

🔥 Limit

limit value="rate/duration"

it is possible to limit Log, NFLog, Audit and Action. a rule using this tag will match until this limit is reached.

the rate is a natural positive number [1, ..]. the duration is of "s", "m", "h", "d". "s" means seconds, "m" minutes, "h" hours and "d" days.

the maximum limit value is "2/d", which means at maximum two matches per day. that's the ceiling, bestie. 🎀

🌈 Information about logging and actions

logging can be done with the log, nflog and audit actions. a new chain is added to all zones: zone_log. this will be jumped into before the deny chain, to be able to have a proper ordering. order matters, always. 👑

the rules, or parts of them, are placed in separate chains according to the priority and action of the rule:

zone_pre
zone_log
zone_deny
zone_allow
zone_post

when priority < 0, the rich rule will be placed in the zone_pre chain.

Okay so more chain tea — this part is about where your rules actually get dropped. 💅

When priority == 0, literally all the logging rules go into the zone_log chain. All the reject and drop rules? They go in zone_deny, which gets walked after the log chain. And all accept rules go in zone_allow, which gets walked after the deny chain. If a rule has log AND also deny or allow actions, the parts get split up and placed in the matching chains. ✨

When priority > 0, the rich rule goes in the zone_post chain. That's it, that's the placement.

🎀 EXAMPLES 🎀

Okay bestie these are literally the receipts — examples of how to specify rich language rules. This format (one string that describes the whole entire rule, no cap) is what firewall-cmd --add-rich-rule uses (see firewall-cmd(1)) as well as the D-Bus interface. 🦋

Example 1 🔥

Enable new IPv4 and IPv6 connections for protocol 'ah'

rule protocol value="ah" accept

Example 2 💖

Allow new IPv4 and IPv6 connections for service ftp and log 1 per minute using audit

rule service name="ftp" log limit value="1/m" audit accept

Example 3 🌸

Allow new IPv4 connections from address 192.168.0.0/24 for service tftp and log 1 per minutes using syslog

rule family="ipv4" source address="192.168.0.0/24" service name="tftp" log prefix="tftp" level="info" limit value="1/m" accept

Example 4 🌈

New IPv6 connections from 1:2:3:4:6:: to service radius are all rejected and logged at a rate of 3 per minute. New IPv6 connections from other sources are accepted.

rule family="ipv6" source address="1:2:3:4:6::" service name="radius" log prefix="dns" level="info" limit value="3/m" reject
rule family="ipv6" service name="radius" accept

Example 5 🧚

Forward IPv6 port/packets receiving from 1:2:3:4:6:: on port 4011 with protocol tcp to 1::2:3:4:7 on port 4012

rule family="ipv6" source address="1:2:3:4:6::" forward-port to-addr="1::2:3:4:7" to-port="4012" protocol="tcp" port="4011"

Example 6 👑

White-list source address to allow all connections from 192.168.2.2

rule family="ipv4" source address="192.168.2.2" accept

Example 7 💀

Black-list source address to reject all connections from 192.168.2.3

rule family="ipv4" source address="192.168.2.3" reject type="icmp-admin-prohibited"

Example 8 🙈

Black-list source address to drop all connections from 192.168.2.4

rule family="ipv4" source address="192.168.2.4" drop

🫶 SEE ALSO 🫶

firewall-applet(1), firewalld(1), firewall-cmd(1), firewall-config(1), firewalld.conf(5), firewalld.direct(5), firewalld.dbus(5), firewalld.icmptype(5), firewall-offline-cmd(1), firewalld.richlanguage(5), firewalld.service(5), firewalld.zone(5), firewalld.zones(5), firewalld.policy(5), firewalld.policies(5), firewalld.ipset(5), firewalld.helper(5)

(yes that's a whole friend group, go read them all, iykyk 📚✨)

⭐ NOTES ⭐

firewalld home page:

http://firewalld.org

💜 AUTHORS 💜

  • Thomas Woerner <twoerner@redhat.com> — Developer
  • Jiri Popelka <jpopelka@redhat.com> — Developer
  • Eric Garver <eric@garver.life> — Developer

and that's the whole page bestie!! 🌸 this masterpiece is from firewalld 2.5.2, and you just read FIREWALLD.RICHLANG(5) — go forth and rich-rule responsibly, mwah 💅💖

📦 where this page comes from