FERM(1)

📦

version 2.7 · 10 versions

2.7 · alpine 3.23, alpine 3.24 (latest)
2.7 · nixos 26.05, nixpkgs unstable
2.7 · alpine 3.22
2.7 · arch rolling
2.7 · ubuntu stonking
2.5.1 · ubuntu jammy
2.5.1 · debian bookworm
2.5.1 · ubuntu noble
2.7 · ubuntu resolute
2.5.1 · debian trixie, ubuntu questing

, in alpine 3.23, alpine 3.24

💖 ferm(1) — Firewall Rules Made Easy 💖

okay bestie, this is ferm(1) — the title card literally reads FIREWALL RULES MADE EASY 😌 so let's get into it.

🌸 NAME 🌸

ferm — a firewall rule parser for linux ✨

✨ SYNOPSIS ✨

ferm options inputfile

💜 DESCRIPTION 💜

okay so picture this: ferm is a frontend for iptables. it reads the rules from a structured configuration file and then calls iptables(8) to insert them into the running kernel. that's the pipeline 💅

ferm's goal is to make firewall rules easy to write and easy to read. it tries to reduce the tedious task of writing down rules, which means the firewall administrator gets to spend more time on developing good rules than on the proper implementation of the rule. no cap.

to pull that off, ferm uses a simple but powerful configuration language, and that language allows variables, functions, arrays, and blocks. it also allows you to include other files, so you can create libraries of commonly used structures and functions. obsessed.

ferm, pronounced "firm", stands for "For Easy Rule Making". cute, right? 💖

🚨 CAUTION 🚨

bestie, this manual page does not intend to teach you how firewalling works and how to write good rules. there is already enough documentation on this topic. so don't treat this page as Firewalling 101 🙈

🦋 INTRODUCTION 🦋

let's start with a simple example:

chain INPUT {
    proto tcp ACCEPT;
}

this will add a rule to the predefined input chain, matching and accepting all TCP packets. slay.

ok, let's make it more complicated:

chain (INPUT OUTPUT) {
    proto (udp tcp) ACCEPT;
}

this will insert 4 rules, namely 2 in chain input, and 2 in chain output, matching and accepting both UDP and TCP packets. normally you would type this:

iptables -A INPUT -p tcp -j ACCEPT
iptables -A OUTPUT -p tcp -j ACCEPT
iptables -A INPUT -p udp -j ACCEPT
iptables -A OUTPUT -p udp -j ACCEPT

notice how much less typing we need to do? :-) 💅

basically, this is all there is to it, although you can make it quite more complex. something to look at:

chain INPUT {
    policy ACCEPT;
    daddr 10.0.0.0/8 proto tcp dport ! ftp jump mychain sport :1023 TOS 4 settos 8 mark 2;
    daddr 10.0.0.0/8 proto tcp dport ftp REJECT;
}

my point here is that you need to make nice rules, keep them readable to you and others, and not make it into a mess. periodt.

it would aid the reader if the resulting firewall rules were placed here for reference. also, you could include the nested version with better readability. ngl that's a flex.

try using comments to show what you are doing:

# this line enables transparent http-proxying for the internal network:
proto tcp if eth0 daddr ! 192.168.0.0/255.255.255.0
    dport http REDIRECT to-ports 3128;

you will be thankful for it later! fr fr

chain INPUT {
    policy ACCEPT;
    interface (eth0 ppp0) {
        # deny access to notorious hackers, return here if no match
        # was found to resume normal firewalling
        jump badguys;

        protocol tcp jump fw_tcp;
        protocol udp jump fw_udp;
    }
}

the more you nest, the better it looks. make sure the order you specify is correct, because you would not want to do this:

chain FORWARD {
    proto ! udp DROP;
    proto tcp dport ftp ACCEPT;
}

because the second rule will never match. the best way is to first specify everything that is allowed, and then deny everything else. look at the examples for more good snapshots. most people do something like this:

proto tcp {
    dport (
        ssh http ftp
    ) ACCEPT;
    dport 1024:65535 ! syn ACCEPT;
    DROP;
}

🌈 STRUCTURE OF A FIREWALL FILE 🌈

the structure of a proper firewall file looks like simplified C-code. only a few syntactic characters are used in ferm configuration files. besides these special characters, ferm uses 'keys' and 'values'; think of them as options and parameters, or as variables and values, whatever. 💅

with these words, you define the characteristics of your firewall. every firewall consists of two things: first, look if network traffic matches certain conditions, and second, what to do with that traffic.

you may specify conditions that are valid for the kernel interface program you are using, probably iptables(8). for instance, in iptables, when you are trying to match TCP packets, you would say:

iptables --protocol tcp

in ferm, this will become:

protocol tcp;

just typing this in ferm doesn't do anything — you need to tell ferm (actually, you need to tell iptables(8) and the kernel) what to do with any traffic that matches this condition:

iptables --protocol tcp -j ACCEPT

or, translated to ferm:

protocol tcp ACCEPT;

the ; character is at the end of every ferm rule. ferm ignores line breaks, meaning the above example is identical to the following:

protocol tcp
  ACCEPT;

here's a list of the special characters:

; — this character finalizes a rule.

separated by semicolons, you may write multiple rules in one line, although this decreases readability: protocol tcp ACCEPT; protocol udp DROP;

{} — the nesting symbol defines a 'block' of rules.

the curly brackets contain any number of nested rules. all matches before the block are carried forward to these.

the closing curly bracket finalizes the rule set. you should not write a ; after that because that would be an empty rule.

example:

chain INPUT proto icmp {
    icmp-type echo-request ACCEPT;
    DROP;
}

this block shows two rules inside a block, which will both be merged with anything in front of it so you will get two rules:

iptables -A INPUT -p icmp --icmp-type echo-request -j ACCEPT
iptables -A INPUT -p icmp -j DROP

there can be multiple nesting levels:

chain INPUT {
    proto icmp {
        icmp-type echo-request ACCEPT;
        DROP;
    }
    daddr 172.16.0.0/12 REJECT;
}

note that the 'REJECT' rule is not affected by 'proto icmp', although there is no ';' after the closing curly brace. translated to iptables:

iptables -A INPUT -p icmp --icmp-type echo-request -j ACCEPT
iptables -A INPUT -p icmp -j DROP
iptables -A INPUT -d 172.16.0.0/12 -j REJECT

$ — variable expansion. replaces $FOO by the value of the variable. see the section VARIABLES for details.
& — function call. see the section FUNCTIONS for details.
() — the array symbol. using the parentheses, you can define a 'list' of values that should be applied for the key to the left of it.

example: protocol ( tcp udp icmp )

this will result in three rules:

... -p tcp ...
... -p udp ...
... -p icmp ...

only values can be 'listed', so you cannot do something like this: proto tcp ( ACCEPT LOG );

but you can do this: chain (INPUT OUTPUT FORWARD) proto (icmp udp tcp) DROP;

(which will result in nine rules!)

values are separated by spaces. the array symbol is both left- and right-associative, in contrast with the nesting block, which is left-associative only.

" # " — the comment symbol. anything that follows this symbol up to the end of the line is ignored.
`command` — execute the command in a shell, and insert the process output. see the section backticks for details.
'string' — quote a string which may contain whitespaces, the dollar sign etc.

LOG log-prefix ' hey, this is my log prefix!';

"string" — quote a string (see above), but variable references with a dollar sign are evaluated:

DNAT to "$myhost:$myport";

🔑 Keywords 🔑

in the previous section, we already introduced some basic keywords like "chain", "protocol" and "ACCEPT". let's explore their nature. 👑

there are three kinds of keywords:

location keywords define where a rule will be created. example: "table", "chain".
match keywords perform a test on all passing packets. the current rule is without effect if one (or more) of the matches does not pass. example: "proto", "daddr".

most matches are followed by a parameter: "proto tcp", "daddr 172.16.0.0/12".

target keywords state what to do with a packet. example: "ACCEPT", "REJECT", "jump".

some targets define more keywords to specify details: "REJECT reject-with icmp-net-unreachable".

every rule consists of a location and a target, plus any number of matches:

table filter                  # location
proto tcp dport (http https)  # match
ACCEPT;                       # target

strictly speaking, there is a fourth kind: ferm keywords (which control ferm's internal behaviour), but they will be explained later. iykyk.

🎀 Parameters 🎀

many keywords take parameters. these can be specified as literals, variable references or lists (arrays):

proto udp
saddr $TRUSTED_HOSTS;
proto tcp dport (http https ssh);
LOG log-prefix "funky wardriver alert: ";

some of them can be negated (lists cannot be negated):

proto !esp;
proto udp dport !domain;

keywords which take no parameters are negated by a prefixed !:

proto tcp !syn;

read iptables(8) to see where the ! can be used. 🌸

✨ BASIC KEYWORDS ✨

Okay bestie, this is where the ferm glow-up really starts — these are the core keywords you’ll be typing all the time. Let’s go 💅

📍 Location keywords 📍

domain [ip|ip6] — Sets the domain, bestie. ip means “IPv4” (iptables) and ip6 is for IPv6 support, using ip6tables. The default is whatever you set with --domain, or ip if you didn’t specify that option at all.
table [filter|nat|mangle] — Tells ferm which netfilter table this rule gets inserted into: filter (default), nat, or mangle.
chain [chain-name] — Picks the netfilter chain (inside the current table) this rule goes into. Common predefined chain names are INPUT, OUTPUT, FORWARD, PREROUTING, and POSTROUTING, depending on the table. Check the netfilter docs for the details, iykyk. If you name a chain that doesn’t exist here, ferm will add the rule to a custom chain with that name.
policy [ACCEPT|DROP|..] — Sets the default policy for the current chain (built-in only). It can be one of the built-in targets (ACCEPT, DROP, REJECT, ...). A packet that matches no rules in a chain gets treated however the policy says. To avoid ambiguity, always specify the policies of all predefined chains explicitly. No vibes-based guessing, okay?
@subchain ["CHAIN-NAME"] { ... } — Works like the normal block operators (i.e. without the @subchain keyword), except ferm moves the rules inside the curly braces into a new custom chain. Ferm picks the name for this chain automatically. In many cases this is faster than just a block, because the kernel may skip a huge block of rules when a precondition is false. Imagine this example, bestie:

table filter chain INPUT {
    saddr (1.2.3.4 2.3.4.5 3.4.5.6 4.5.6.7 5.6.7.8) {
        proto tcp dport (http https ssh) ACCEPT;
        proto udp dport domain ACCEPT;
    }
}

This generates 20 rules. When a packet arrives that does not pass the saddr match, it nonetheless checks all 20 rules. With @subchain, this check is done once, resulting in faster network filtering and less CPU load:

table filter chain INPUT {
    saddr (1.2.3.4 2.3.4.5 3.4.5.6 4.5.6.7 5.6.7.8) @subchain {
        proto tcp dport (http https ssh) ACCEPT;
        proto udp dport domain ACCEPT;
    }
}

Optionally, you may define the name of the sub chain:

saddr (1.2.3.4 2.3.4.5 3.4.5.6) @subchain "foobar" {
    proto tcp dport (http https ssh) ACCEPT;
    proto udp dport domain ACCEPT;
}

The name can either be a quoted string literal, or an expanded ferm expression such as @cat("interface_", $iface) or @substr($var,0,20). You can achieve the same thing by explicitly declaring a custom chain, but you may feel that using @subchain requires less typing. Iconic, honestly.

@gotosubchain ["CHAIN-NAME"] { ... } — Works like @subchain except that instead of using jump target it uses goto target. See the discussion below for the difference between these two targets.
@preserve — Preserves existing rules of the current chain:

chain (foo bar) @preserve;

With this option, ferm loads the previous rule set using iptables-save, extracts all “preserved” chains, and inserts their data into the output.

“Preserved” chains must not be modified with ferm: no rules and no policies. Like, do not touch. 🫶

If the chain name starts and ends with a slash, ferm will interpret it as a Perl regular expression and preserve all matching chains. For example, the following preserves all chains with the prefix KUBE-SEP-:

chain "/^KUBE-SEP-.*/" @preserve;

🎀 Basic iptables match keywords 🎀

interface [interface-name] — Defines the interface name — your outside network card like eth0, or dialup like ppp1, or whatever device you want to match for passing packets. It is equivalent to the -i switch in iptables(8).
outerface [interface-name] — Same as interface, only for matching the outgoing interface for a packet, as in iptables(8).
protocol [protocol-name|protocol-number] — Currently supported by the kernel are TCP, UDP, and ICMP, or their respective numbers. Instead of protocol, you can also use the shortcut proto.
saddr|daddr [address-spec] — Matches on packets originating from the specified address (saddr) or targeted at the address (daddr). Examples, bestie:

saddr 192.168.0.0/24 ACCEPT; # (identical to the next one:)
saddr 192.168.0.0/255.255.255.0 ACCEPT;
daddr my.domain.com ACCEPT;

fragment — Specifies that only fragmented IP packets should be matched. When packets are larger than the maximum packet size your system can handle (called Maximum Transmission Unit or MTU) they will be chopped into bits and sent one by one as single packets. See ifconfig(8) if you want to find the MTU for your system (the default is usually 1500 bytes). Fragments are frequently used in DOS attacks because there is no way of finding out the origin of a fragment packet. 💀 Not cute.
sport|dport [port-spec] — Matches on packets on the specified TCP or UDP port. sport matches the source port, and dport matches the destination port. This match can be used only after you specified protocol tcp or protocol udp, because only these two protocols actually have ports. And some examples of valid ports/ranges:

dport 80 ACCEPT;
dport http ACCEPT;
dport ssh:http ACCEPT;
dport 0:1023 ACCEPT; # equivalent to :1023
dport 1023:65535 ACCEPT;

syn — Specifies that the SYN flag in a TCP package should be matched, which are used to build new TCP connections. You can identify incoming connections with this, and decide whether you want to allow it or not. Packets that do not have this flag are probably from an already established connection, so it’s considered reasonably safe to let these through.
module [module-name] — Loads an iptables module. Most modules provide more match keywords. We’ll get to that later. Instead of module, you can also use the shortcut mod.

💥 Basic target keywords 💥

jump [custom-chain-name] — Jumps to a custom chain. If no rule in the custom chain matched, netfilter returns to the next rule in the previous chain.
goto [custom-chain-name] — Go to a custom chain. Unlike the jump option, RETURN will not continue processing in this chain but instead in the chain that called us via jump.
ACCEPT — Accepts matching packets.
DROP — Drops matching packets without further notice.
REJECT — Rejects matching packets, i.e. sends an ICMP packet to the sender, which is port-unreachable by default. You may specify another ICMP type.

REJECT; # default to icmp-port-unreachable
REJECT reject-with icmp-net-unreachable;

Type iptables -j REJECT -h for details.

RETURN — Finishes the current chain and returns to the calling chain (if jump [custom-chain-name] was used).
NOP — No action at all.

🌈 ADDITIONAL KEYWORDS 🌈

Netfilter is modular, bestie. Modules may provide additional targets and match keywords. The list of netfilter modules is constantly growing, and ferm tries to keep up with supporting them all. This chapter describes modules which are currently supported.

🧚 iptables match modules 🧚

account — Accounts traffic for all hosts in defined network/netmask. This is one of the match modules which behave like a target, i.e. you will mostly have to use the NOP target.

mod account aname mynetwork aaddr 192.168.1.0/24 ashort NOP;

addrtype — Checks the address type; either source address or destination address.

mod addrtype src-type BROADCAST;
mod addrtype dst-type LOCAL;

Type iptables -m addrtype -h for details.

ah — Checks the SPI header in an AH packet.

mod ah ahspi 0x101;
mod ah ahspi ! 0x200:0x2ff;

Additional arguments for IPv6:

mod ah ahlen 32 ACCEPT;
mod ah ahlen !32 ACCEPT;
mod ah ahres ACCEPT;

bpf — Matches using Linux Socket Filter.

mod bpf bytecode "4,48 0 0 9,21 0 1 6,6 0 0 1,6 0 0 0";

cgroup — Matches using cgroupsv2 hierarchy or legacy net_cls cgroup.

mod cgroup path ! example/path ACCEPT;

The path is relative to the root of the cgroupsv2 hierarchy and is compared against the initial portion of a process’ path in the hierarchy.

mod cgroup cgroup 10:10 DROP;
mod cgroup cgroup 1048592 DROP;

Matches against the value of net_cls.classid set on the process’ legacy net_cls cgroup. The class may be specified as a hexadecimal major:minor pair (see tc(8)), or as a decimal, so those two rules are equivalent.

comment — Adds a comment of up to 256 characters to a rule, without an effect. Note that unlike ferm comments (#), this one will show up in iptables -L.

mod comment comment "This is my comment." ACCEPT;

The mod comment can be omitted, because ferm inserts it automatically.

condition — Matches if a value in /proc/net/ipt_condition/NAME is 1 (path is /proc/net/ip6t_condition/NAME for the ip6 domain).

mod condition condition (abc def) ACCEPT;
mod condition condition !foo ACCEPT;

connbytes — Matches by how many bytes or packets a connection (or one of the two flows constituting the connection) have transferred so far, or by average bytes per packet.

mod connbytes connbytes 65536: connbytes-dir both connbytes-mode bytes ACCEPT;
mod connbytes connbytes !1024:2048 connbytes-dir reply connbytes-mode packets ACCEPT;

Valid values for connbytes-dir: original, reply, both; for connbytes-mode: packets, bytes, avgpkt.

connlabel — Module matches or adds connlabels to a connection.

mod connlabel label "name";
mod connlabel label "name" set;

connlimit — Allows you to restrict the number of parallel TCP connections to a server per client IP address (or address block).

`connlimit`

caps how many connections one host can have open at the same time — like a bouncer counting heads at the door 💅

mod connlimit connlimit-above 4 REJECT;
mod connlimit connlimit-above !4 ACCEPT;
mod connlimit connlimit-above 4 connlimit-mask 24 REJECT;
mod connlimit connlimit-upto 4 connlimit-saddr REJECT;
mod connlimit connlimit-above 4 connlimit-daddr REJECT;

`connmark`

peeks at the mark field that's attached to the connection (set by the CONNMARK target, iykyk) ✨

mod connmark mark 64;
mod connmark mark 6/7;

`conntrack`

the connection-tracking info inspection station, no cap 🫶

mod conntrack ctstate (ESTABLISHED RELATED);
mod conntrack ctproto tcp;
mod conntrack ctorigsrc 192.168.0.2;
mod conntrack ctorigdst 1.2.3.0/24;
mod conntrack ctorigsrcport 67;
mod conntrack ctorigdstport 22;
mod conntrack ctreplsrc 2.3.4.5;
mod conntrack ctrepldst ! 3.4.5.6;
mod conntrack ctstatus ASSURED;
mod conntrack ctexpire 60;
mod conntrack ctexpire 180:240;

type iptables -m conntrack -h for the full deets 💖

`cpu`

matches on which CPU handled this packet — like, which sibling grabbed the mail 📬

mod cpu cpu 0;

`dccp`

checks the DCCP (Datagram Congestion Control Protocol) specific attributes. bestie this one loads itself automatically the second you use protocol dccp, it's giving self-sufficient queen 👑

proto dccp sport 1234 dport 2345 ACCEPT;
proto dccp dccp-types (SYNCACK ACK) ACCEPT;
proto dccp dccp-types !REQUEST DROP;
proto dccp dccp-option 2 ACCEPT;

`dscp`

matches the 6-bit DSCP field hiding inside the TOS field 🕵️‍♀️

mod dscp dscp 11;
mod dscp dscp-class AF41;

`dst`

matches the params in the Destination Options header (IPv6 girlies rise) 🌈

mod dst dst-len 10;
mod dst dst-opts (type1 type2 ...);

`ecn`

matches the ECN bits of an IPv4 TCP header, periodt

mod ecn ecn-tcp-cwr;
mod ecn ecn-tcp-ece;
mod ecn ecn-ip-ect 2;

type iptables -m ecn -h for the details 💜

`esp`

checks the SPI header in an ESP packet — very VPN of it 🔐

mod esp espspi 0x101;
mod esp espspi ! 0x200:0x2ff;

`eui64`

so the original literally says: it matches the EUI-64 part of a stateless autoconfigured IPv6 address. it compares the EUI-64 derived from the source MAC address in the Ethernet frame with the lower 64 bits of the IPv6 source address. but the "Universal/Local" bit is not compared. it also doesn't match other link layer frames, and it's only valid in the PREROUTING, INPUT and FORWARD chains. okay so it's a picky little icon, we respect it 🎀

mod eui64 ACCEPT;

`fuzzy`

rate-limits based on a fuzzy logic controller [FLC] — yes really, chaos with math vibes 🌸

mod fuzzy lower-limit 10 upper-limit 20 ACCEPT;

`geoip`

matches packets by their geological location (you need an installed GeoDB for this one, no GeoDB no slay) 🌍

mod geoip src-cc "CN,VN,KR,BH,BR,AR,TR,IN,HK" REJECT;
mod geoip dst-cc "DE,FR,CH,AT" ACCEPT;

`hbh`

matches the Hop-by-Hop Options header (ip6) 🦋

mod hbh hbh-len 8 ACCEPT;
mod hbh hbh-len !8 ACCEPT;
mod hbh hbh-opts (1:4 2:8) ACCEPT;

`hl`

matches the Hop Limit field (ip6) — lowkey a little TTL cousin ✨

mod hl hl-eq (8 10) ACCEPT;
mod hl hl-eq !5 ACCEPT;
mod hl hl-gt 15 ACCEPT;
mod hl hl-lt 2 ACCEPT;

`helper`

checks which conntrack helper module is tracking this connection. the port can be specified with -portnr 💅

mod helper helper irc ACCEPT;
mod helper helper ftp-21 ACCEPT;

`icmp`

checks ICMP specific attributes, and yes it auto-loads when you use protocol icmp — main character energy honestly 🎀

proto icmp icmp-type echo-request ACCEPT;

this option also works in the ip6 domain, even though over in ip6tables it's called icmpv6 (name change, same vibe).

use iptables -p icmp "-h" to get the full list of valid ICMP types, because there are a lot 💖

`iprange`

matches a whole range of IPv4 addresses instead of one sad little single IP 🫶

mod iprange src-range 192.168.2.0-192.168.3.255;
mod iprange dst-range ! 192.168.6.0-192.168.6.255;

`ipv4options`

matches on IPv4 header options like source routing, record route, timestamp and router-alert ⭐

mod ipv4options ssrr ACCEPT;
mod ipv4options lsrr ACCEPT;
mod ipv4options no-srr ACCEPT;
mod ipv4options !rr ACCEPT;
mod ipv4options !ts ACCEPT;
mod ipv4options !ra ACCEPT;
mod ipv4options !any-opt ACCEPT;

`ipv6header`

matches the IPv6 extension header (ip6) 🌈

mod ipv6header header !(hop frag) ACCEPT;
mod ipv6header header (auth dst) ACCEPT;

`hashlimit`

literally mod limit's cooler older sister — same idea, but now with per-destination or per-port limits managed in a hash table 👑

mod hashlimit  hashlimit 10/minute  hashlimit-burst 30/minute
  hashlimit-mode dstip  hashlimit-name foobar  ACCEPT;

possible values for hashlimit-mode: dstip, dstport, srcip, srcport (or a whole list with more than one of these, go off).

there are more possible settings, so type iptables -m hashlimit -h for the documentation 🦋

`ipvs`

matches IPVS connection properties — and the original left the little comments so we keep them, darling:

mod ipvs ipvs ACCEPT; # packet belongs to an IPVS connection
mod ipvs vproto tcp ACCEPT; # VIP protocol to match; by number or name, e.g. "tcp
mod ipvs vaddr 1.2.3.4/24 ACCEPT; # VIP address to match
mod ipvs vport http ACCEPT; # VIP port to match
mod ipvs vdir ORIGINAL ACCEPT; # flow direction of packet
mod ipvs vmethod GATE ACCEPT; # IPVS forwarding method used
mod ipvs vportctl 80; # VIP port of the controlling connection to match

`length`

checks the packet length, simple as that 📏

mod length length 128; # exactly 128 bytes
mod length length 512:768; # range
mod length length ! 256; # negated

`limit`

limits the packet rate — the classic "chill out bestie" module 💅

mod limit limit 1/second;
mod limit limit 15/minute limit-burst 10;

type iptables -m limit -h for details ✨

`mac`

matches the source MAC address 🎀

mod mac mac-source 01:23:45:67:89;

`mark`

matches packets based on their netfilter mark field. this may be a 32 bit integer between 0 and 4294967295 🔥

mod mark mark 42;

`mh`

matches the mobility header (domain ip6) 🦋

proto mh mh-type binding-update ACCEPT;

`multiport`

matches a whole set of source or destination ports (UDP and TCP only, sorry to the rest) 🌸

mod multiport source-ports (https ftp);
mod multiport destination-ports (mysql domain);

this rule has a big advantage over dport and sport: it generates only one rule for up to 15 ports instead of one rule for every port. efficiency ate, fr fr 👑

as a shortcut you can use sports and dports (without mod multiport) — like this:

sports (https ftp);
dports (mysql domain);

`nfacct`

adds packet accounting (bytes + packets). see also the user space tool nfacct 🧾

mod nfacct nfacct-name my-nfacct-object;

`nth`

matches every n'th packet — the "every third one gets searched" energy 🙈

mod nth every 3;
mod nth counter 5 every 2;
mod nth start 2 every 3;
mod nth start 5 packet 2 every 6;

type iptables -m nth -h for details 💜

`osf`

matches packets depending on the operating system of the sender — yes it's judging their OS 😭

mod osf genre Linux;
mod osf ! genre FreeBSD ttl 1 log 1;

type iptables -m osf -h for details 🫶

`owner`

checks info about the packet creator, namely user id, group id, process id, session id and command name 🕵️‍♀️

mod owner uid-owner 0;
mod owner gid-owner 1000;
mod owner pid-owner 5432;
mod owner sid-owner 6543;
mod owner cmd-owner "sendmail";

heads up bestie: cmd-owner, pid-owner and sid-owner require special kernel patches that are not included in the vanilla Linux kernel. so like, don't come for me if they don't work 💀

`physdev`

matches the physical device a packet entered on, or is about to leave from. super useful for bridged interfaces 🌉

mod physdev physdev-in ppp1;
mod physdev physdev-out eth2;
mod physdev physdev-is-in;
mod physdev physdev-is-out;
mod physdev physdev-is-bridged;

`pkttype`

checks the link-layer packet type 📦

mod pkttype pkt-type unicast;
mod pkttype pkt-type broadcast;
mod pkttype pkt-type multicast;

`policy`

matches the IPsec policy being applied to this packet 🔐

mod policy dir out pol ipsec ACCEPT;
mod policy strict reqid 23 spi 0x10 proto ah ACCEPT;
mod policy mode tunnel tunnel-src 192.168.1.2 ACCEPT;
mod policy mode tunnel tunnel-dst 192.168.2.1 ACCEPT;
mod policy strict next reqid 24 spi 0x11 ACCEPT;

okay so tiny drama: the keyword proto is also used as a shorthand version of protocol (the built-in match module). you can fix this conflict by always using the long keyword protocol 👀

`psd`

detects TCP/UDP port scans — the nosy-neighbour detector 🚨

mod psd psd-weight-threshold 21 psd-delay-threshold 300
  psd-lo-ports-weight 3 psd-hi-ports-weight 1 DROP;

`quota`

implements network quotas by decrementing a byte counter with each packet — very "you've had enough screen time" of it 📉

mod quota quota 65536 ACCEPT;

`random`

matches a random percentage of all packets — chaos, but make it ✨measured✨

mod random average 70;

`realm`

matches the routing realm. useful in environments using BGP 🌍

mod realm realm 3;

`recent`

temporarily marks source IP addresses 💅

mod recent set;
mod recent rcheck seconds 60;
mod recent set rsource name "badguy";
mod recent set rdest;
mod recent rcheck rsource name "badguy" seconds 60;
mod recent update seconds 120 hitcount 3 rttl;
mod recent mask 255.255.255.0 reap;

ngl this netfilter module has a design flaw: although it's implemented as a match module, it has target-like behaviour when using the set keyword. icon behaviour honestly, but still 😭

http://snowman.net/projects/ipt_recent/

`rpfilter`

checks whether a reply to the packet would be sent back out the same interface it arrived on. packets from the loopback interface are always permitted, no questions asked 🫶

mod rpfilter proto tcp loose RETURN;
mod rpfilter validmark accept-local RETURN;
mod rpfilter invert DROP;

okay so this netfilter module? it's literally the preferred way to do reverse path filtering for IPv6, and a powerful alternative to the checks controlled by sysctl net.ipv4.conf.*.rp_filter. slay. 💅

rt

Matches the IPv6 routing header (ip6 only).

mod rt rt-type 2 rt-len 20 ACCEPT;
mod rt rt-type !2 rt-len !20 ACCEPT;
mod rt rt-segsleft 2:3 ACCEPT;
mod rt rt-segsleft !4:5 ACCEPT;
mod rt rt-0-res rt-0-addrs (::1 ::2) rt-0-not-strict ACCEPT;

sctp

Checks SCTP (Stream Control Transmission Protocol) specific attributes. This module auto-loads when you use protocol sctp, bestie. ✨

proto sctp sport 1234 dport 2345 ACCEPT;
proto sctp chunk-types only DATA:Be ACCEPT;
proto sctp chunk-types any (INIT INIT_ACK) ACCEPT;
proto sctp chunk-types !all (HEARTBEAT) ACCEPT;

Use iptables -p sctp "-h" to get a list of valid chunk types.

set

Checks the source or destination IP/Port/MAC against a set.

mod set set badguys src DROP;

See http://ipset.netfilter.org/ for more info. 🫶

state

Checks the connection tracking state.

mod state state INVALID DROP;
mod state state (ESTABLISHED RELATED) ACCEPT;

Type iptables -m state -h for details.

statistic

Successor of nth and random, currently undocumented in the iptables(8) man page.

mod statistic mode random probability 0.8 ACCEPT;
mod statistic mode nth every 5 packet 0 DROP;

string

Matches a string.

mod string string "foo bar" ACCEPT;
mod string algo kmp from 64 to 128 hex-string "deadbeef" ACCEPT;

tcp

Checks TCP specific attributes. This module is automatically loaded when you use protocol tcp. no cap. 🧚

proto tcp sport 1234;
proto tcp dport 2345;
proto tcp tcp-flags (SYN ACK) SYN;
proto tcp tcp-flags ! (SYN ACK) SYN;
proto tcp tcp-flags ALL (RST ACK);
proto tcp syn;
proto tcp tcp-option 2;
proto tcp mss 512;

Type iptables -p tcp -h for details.

tcpmss

Checks the TCP MSS field of a SYN or SYN/ACK packet.

mod tcpmss mss 123 ACCEPT;
mod tcpmss mss 234:567 ACCEPT;

time

Checks if the time a packet arrives is in the given range.

mod time timestart 12:00;
mod time timestop 13:30;
mod time timestart 22:00 timestop 07:00 contiguous;
mod time days (Mon Wed Fri);
mod time datestart 2005:01:01;
mod time datestart 2005:01:01:23:59:59;
mod time datestop 2005:04:01;
mod time monthday (30 31);
mod time weekdays (Wed Thu);
mod time timestart 12:00;
mod time timestart 12:00 kerneltz;

Type iptables -m time -h for details.

tos

Matches a packet on the specified TOS-value.

mod tos tos Minimize-Cost ACCEPT;
mod tos tos !Normal-Service ACCEPT;

Type iptables -m tos -h for details.

ttl

Matches the TTL (time to live) field in the IP header.

mod ttl ttl-eq 12; # ttl equals
mod ttl ttl-gt 10; # ttl greater than
mod ttl ttl-lt 16; # ttl less than

u32

Compares raw data from the packet. You can specify more than one filter in a ferm list; these are not expanded into multiple rules.

mod u32 u32 '6&0xFF=1' ACCEPT;
mod u32 u32 ('27&0x8f=7' '31=0x527c4833') DROP;

unclean

Matches packets which seem malformed or unusual. This match has no further parameters.

🎯 iptables target modules 🎯

The following additional targets are available in ferm, provided that you enabled them in your kernel:

CHECKSUM

Computes packet checksum.

CHECKSUM checksum-fill;

CLASSIFY

Sets the CBQ class.

CLASSIFY set-class 3:50;

CLUSTERIP

Configures a simple cluster of nodes that share a certain IP and MAC address. Connections are statically distributed between the nodes.

CLUSTERIP new hashmode sourceip clustermac 00:12:34:45:67:89
  total-nodes 4 local-node 2 hash-init 12345;

CONNMARK

Sets the netfilter mark value associated with a connection.

CONNMARK set-xmark 42/0xff;
CONNMARK set-mark 42;
CONNMARK save-mark;
CONNMARK restore-mark;
CONNMARK save-mark nfmask 0xff ctmask 0xff;
CONNMARK save-mark mask 0x7fff;
CONNMARK restore-mark mask 0x8000;
CONNMARK and-mark 0x7;
CONNMARK or-mark 0x4;
CONNMARK xor-mark 0x7;
CONNMARK and-mark 0x7;

CONNSECMARK

This module copies security markings from packets to connections (if unlabeled), and from connections back to packets (also only if unlabeled). Typically used in conjunction with SECMARK, it is only valid in the mangle table.

CONNSECMARK save;
CONNSECMARK restore;

CT

Sets connection tracking parameters.

CT notrack;
CT helper ftp;
CT ctevents new,related;
CT expevents new;
CT zone 1;
CT zone mark;
CT zone-orig mark;
CT zone-reply mark;
CT timeout 180;

DNAT `to [ip-address|ip-range|ip-port-range]`

Changes the destination address of the packet.

DNAT to 10.0.0.4;
DNAT to 10.0.0.4:80;
DNAT to 10.0.0.4:1024-2048;
DNAT to 10.0.1.1-10.0.1.20;

DNPT

Provides stateless destination IPv6-to-IPv6 Network Prefix Translation.

DNPT src-pfx 2001:42::/16 dst-pfx 2002:42::/16;

ECN

This target allows you to selectively work around known ECN blackholes. It can only be used in the mangle table. ⚠️

ECN ecn-tcp-remove;

HL

Modifies the IPv6 Hop Limit field (ip6/mangle only).

HL hl-set 5;
HL hl-dec 2;
HL hl-inc 1;

HMARK

Like MARK, i.e. sets the fwmark, but the mark is calculated from hashing packet selector at choice.

HMARK hmark-tuple "src" hmark-mod "1" hmark-offset "1"
  hmark-src-prefix 192.168.1.0/24 hmark-dst-prefix 192.168.2.0/24
  hmark-sport-mask 0x1234 hmark-dport-mask 0x2345
  hmark-spi-mask 0xdeadbeef hmark-proto-mask 0x42 hmark-rnd 0xcoffee;

IDLETIMER

This target can be used to identify when interfaces have been idle for a certain period of time.

IDLETIMER timeout 60 label "foo";

IPV4OPTSSTRIP

Strips all the IP options from a packet. This module does not take any options.

IPV4OPTSSTRIP;

JOOL

Hands off packets for stateful NAT64 translation via JOOL. Target requires JOOL to be installed on the system and the jool kernel module to be loaded.

JOOL instance "foo";

JOOL_SIIT

Hands off packets for Stateless IP/ICMP Translation (SIIT) via JOOL. Target requires JOOL to be installed on the system and the jool_siit kernel module to be loaded.

JOOL_SIIT instance "foo";

LED

This creates an LED-trigger that can then be attached to system indicator lights, to blink or illuminate them when certain packets pass through the system.

LED led-trigger-id "foo" led-delay 100 led-always-blink;

LOG

Logs all packets that match this rule in the kernel log. Be careful with log flooding, bestie. Note that this is a non-terminating target, i.e. rule traversal continues at the next rule.

LOG log-level warning log-prefix "Look at this: ";
LOG log-tcp-sequence log-tcp-options;
LOG log-ip-options;

MARK

Sets the netfilter mark field for the packet (a 32-bit integer between 0 and 4294967295):

MARK set-mark 42;
MARK set-xmark 7/3;
MARK and-mark 31;
MARK or-mark 1;
MARK xor-mark 12;

MASQUERADE

Masquerades matching packets. Optionally followed by a port or port-range for iptables. Specify as "123", "123-456" or "123:456". The port range parameter specifies what local ports masqueraded connections should originate from.

MASQUERADE;
MASQUERADE to-ports 1234:2345;
MASQUERADE to-ports 1234:2345 random;
MASQUERADE to-ports 1234:2345 random-fully;

MIRROR

Experimental demonstration target which inverts the source and destination fields in the IP header.

MIRROR;

NETMAP

Maps a whole network onto another network in the nat table.

NETMAP to 192.168.2.0/24;

NOTRACK

Disables connection tracking for all packets matching that rule.

proto tcp dport (135:139 445) NOTRACK;

RATEEST

The page drops these examples and doesn't say more, so here they are, untouched:

RATEEST rateest-name "foo" rateest-interval 60s rateest-ewmalog 100;
proto tcp dport (135:139 445) NOTRACK;

NFLOG

Logs packets over netlink; this is the successor of ULOG.

NFLOG nflog-group 5 nflog-prefix "Look at this: ";
NFLOG nflog-range 256;
NFLOG nflog-threshold 10;

NFQUEUE

Userspace queueing, requires nfnetlink_queue kernel support.

proto tcp dport ftp NFQUEUE queue-num 20;

QUEUE

Userspace queueing, the predecessor to NFQUEUE. All packets go to queue 0.

proto tcp dport ftp QUEUE;

REDIRECT `to-ports [ports]`

Transparent proxying: alters the destination IP of the packet to the machine itself.

proto tcp dport http REDIRECT to-ports 3128;
proto tcp dport http REDIRECT to-ports 3128 random;

SAME

Similar to SNAT, but a client is mapped to the same source IP for all its connections.

SAME to 1.2.3.4-1.2.3.7;
SAME to 1.2.3.8-1.2.3.15 nodst;
SAME to 1.2.3.16-1.2.3.31 random;

SECMARK

This is used to set the security mark value associated with the packet for use by security subsystems such as SELinux. It is only valid in the mangle table.

SECMARK selctx "system_u:object_r:httpd_packet_t:s0";

SET `[add-set|del-set] [setname] [flag(s)]`

Adds the IP to the specified set. See http://ipset.netfilter.org/

…and for SET the carry-over examples are literally:

proto icmp icmp-type echo-request SET add-set badguys src;
SET add-set "foo" timeout 60 exist;

SNAT to [ip-address|ip-range|ip-port-range] — changes the source address of the packet. Slay:

SNAT to 1.2.3.4;
SNAT to 1.2.3.4:20000-30000;
SNAT to 1.2.3.4 random;

SNPT — provides stateless source IPv6-to-IPv6 Network Prefix Translation:

SNPT src-pfx 2001:42::/16 dst-pfx 2002:42::/16;

SYNPROXY — TCP 3-way handshake proxy: let the firewall handle the TCP 3-way handshake and only establish a connection with the server socket once the client handshake has finished. Iconic behavior tbh:

SYNPROXY wscale 7 mss 1460 timestamp sack-perm

TCPMSS — alter the MSS value of TCP SYN packets:

TCPMSS set-mss 1400;
TCPMSS clamp-mss-to-pmtu;

TCPOPTSTRIP — this target will strip TCP options off a TCP packet:

TCPOPTSTRIP strip-options (option1 option2 ...);

TOS set-tos [value] — set the TCP package Type Of Service bit to this value. This will be used by whatever traffic scheduler is willing to, mostly your own Linux-machine, but maybe more. The original TOS-bits are blanked and overwritten by this value:

TOS set-tos Maximize-Throughput;
TOS and-tos 7;
TOS or-tos 1;
TOS xor-tos 4;

Type iptables -j TOS -h for details.

TTL — modify the TTL header field:

TTL ttl-set 16;
TTL ttl-dec 1; # decrease by 1
TTL ttl-inc 4; # increase by 4

ULOG — log packets to a userspace program:

ULOG ulog-nlgroup 5 ulog-prefix "Look at this: ";
ULOG ulog-cprange 256;
ULOG ulog-qthreshold 10;

🌈 OTHER DOMAINS 🌈

Since version 2.0, ferm supports not only ip and ip6, but also arp (ARP tables) and eb (ethernet bridging tables). The concepts are similar to iptables. Bestie, it’s giving expanded universe.

🦋 arptables keywords 🦋

source-ip, destination-ip — matches the source or destination IPv4 address. Same as saddr and daddr in the ip domain.
source-mac, destination-mac — matches the source or destination MAC address.
interface, outerface — input and output interface.
h-length — hardware length of the packet:

chain INPUT h-length 64 ACCEPT;

opcode — operation code, for details, see iptables(8):

opcode 9 ACCEPT;

h-type — hardware type:

h-type 1 ACCEPT;

proto-type — protocol type:

proto-type 0x800 ACCEPT;

🫶 Mangling 🫶

The keywords mangle-ip-s, mangle-ip-d, mangle-mac-s, mangle-mac-d, mangle-target may be used for ARP mangling. See iptables(8) for details.

🌸 ebtables keywords 🌸

proto — matches the protocol which created the frame, e.g. IPv4 or PPP. For a list, see /etc/ethertypes.
interface, outerface — physical input and output interface.
logical-in, logical-out — the logical bridge interface.
saddr, daddr — matches source or destination MAC address.

Match modules

The following match modules are supported: 802.3, arp, ip, mark_m, pkttype, stp, vlan, log.

Target extensions

The following target extensions are supported: arpreply, dnat, mark, redirect, snat.

Please note that there is a conflict between --mark from the mark_m match module and -j mark. Since both would be implemented with the ferm keyword mark, we decided to solve this by writing the target’s name in uppercase, like in the other domains. The following example rewrites mark 1 to 2:

mark 1 MARK 2;

👑 ADVANCED FEATURES 👑

💜 Variables

In complex firewall files, it is helpful to use variables, e.g. to give a network interface a meaningful name. To set variables, write:

@def $DEV_INTERNET = eth0;
@def $PORTS = (http ftp);
@def $MORE_PORTS = ($PORTS 8080);

In the real ferm code, variables are used like any other keyword parameter:

chain INPUT interface $DEV_INTERNET proto tcp dport $MORE_PORTS ACCEPT;

Note that variables can only be used in keyword parameters ("192.168.1.1", "http"); they cannot contain ferm keywords like "proto" or "interface". Variables are only valid in the current block:

@def $DEV_INTERNET = eth1;
chain INPUT {
    proto tcp {
        @def $DEV_INTERNET = ppp0;
        interface $DEV_INTERNET dport http ACCEPT;
    }
    interface $DEV_INTERNET DROP;
}

will be expanded to:

chain INPUT {
    proto tcp {
        interface ppp0 dport http ACCEPT;
    }
    interface eth1 DROP;
}

The "def $DEV_INTERNET = ppp0" is only valid in the "proto tcp" block; the parent block still knows "set $DEV_INTERNET = eth1".

Include files are special — variables declared in an included file are still available in the calling block. This is useful when you include a file which only declares variables.

⭐ Automatic variables

Some variables are set internally by ferm. Ferm scripts can use them just like any other variable.

$FILENAME — the name of the configuration file relative to the directory ferm was started in.
$FILEBNAME — the base name of the configuration file.
$DIRNAME — the directory of the configuration file.
$DOMAIN — the current domain. One of ip, ip6, arp, eb.
$TABLE — the current netfilter table.
$CHAIN — the current netfilter chain.
$LINE — the line of the current script. It can be used like this:

@def &log($msg) = {
         LOG log-prefix "rule=$msg:$LINE ";
}
.
.
.
&log("log message");

🧚 Functions

Functions are similar to variables, except that they may have parameters, and they provide ferm commands, not values.

@def &FOO() = proto (tcp udp) dport domain;
&FOO() ACCEPT;

@def &TCP_TUNNEL($port, $dest) = {
    table filter chain FORWARD interface ppp0 proto tcp dport $port daddr $dest outerface eth0 ACCEPT;
    table nat chain PREROUTING interface ppp0 proto tcp dport $port daddr 1.2.3.4 DNAT to $dest;
}

&TCP_TUNNEL(http, 192.168.1.33);
&TCP_TUNNEL(ftp, 192.168.1.30);
&TCP_TUNNEL((ssh smtp), 192.168.1.2);

A function call which contains a block (like '{...}') must be the last command in a ferm rule, i.e. it must be followed by ';'. The '&FOO()' example does not contain a block, thus you may write 'ACCEPT' after the call. To circumvent this, you can reorder the keywords:

@def &IPSEC() = { proto (esp ah); proto udp dport 500; }
chain INPUT ACCEPT &IPSEC();

🎀 Backticks

With backticks, you may use the output of an external command:

@def $DNSSERVERS = `grep nameserver /etc/resolv.conf | awk '{print $2}'`;
chain INPUT proto tcp saddr $DNSSERVERS ACCEPT;

The command is executed with the shell (/bin/sh), just like backticks in Perl. ferm does not do any variable expansion here.

The output is then tokenized and saved as a ferm list (array). Lines beginning with '#' are ignored; the other lines may contain any number of values, separated by whitespace.

🦋 Includes

The @include keyword allows you to include external files:

@include 'vars.ferm';

The file name is relative to the calling file, e.g. when including from /etc/ferm/ferm.conf, the above statement includes /etc/ferm/vars.ferm. Variables and functions declared in an included file are still available in the calling file.

include works within a block:

chain INPUT {
    @include 'input.ferm';
}

If you specify a directory (with a trailing '/'), all files in this directory are included, sorted alphabetically:

@include 'ferm.d/';

The function @glob can be used to expand wildcards:

@include @glob('*.include');

With a trailing pipe symbol, ferm executes a shell command and parses its output:

@include "/root/generate_ferm_rules.sh $HOSTNAME|"

ferm aborts, if return code is not 0.

💅 Conditionals

The keyword @if introduces a conditional expression:

@if $condition DROP;

A value is evaluated true just like in Perl: zero, empty list, empty string are false, everything else is true. Examples for true values:

(a b); 1; 'foo'; (0 0)

Examples for false values:

(); 0; '0'; ''

There is also @else:

@if $condition DROP; @else REJECT;

Note the semicolon before the @else.

It is possible to use curly braces after either @if or @else:

@if $condition {
    MARK set-mark 2;
    RETURN;
} @else {
    MARK set-mark 3;
}

Since the closing curly brace also finishes the command, there is no need for a semicolon.

There is no @elsif, use @else @if instead.

Example:

@def $have_ipv6 = `test -f /proc/net/ip6_tables_names && echo 1 || echo`;
@if $have_ipv6 {
    domain ip6 {
        # ....
    }
}

🫶 Hooks

To run custom commands, you may install hooks:

@hook pre "echo 0 >/proc/sys/net/ipv4/conf/eth0/forwarding";
@hook post "echo 1 >/proc/sys/net/ipv4/conf/eth0/forwarding";
@hook flush "echo 0 >/proc/sys/net/ipv4/conf/eth0/forwarding";

The specified command is executed using the shell. "pre" means run the command before applying the firewall rules, and "post" means run the command afterwards. "flush" hooks are run after ferm has flushed the firewall rules (option --flush). You may install any number of hooks.

✨ BUILT-IN FUNCTIONS ✨

okay so there are several built-in functions which you might find useful, and honestly they’re lowkey iconic for keeping your ferm config cute and DRY 💅

🎯 `@defined($name)`, `@defined(&name)` 🎯

Tests if the variable or function is defined. bestie this is your vibe check for “does this thing even exist rn?”

@def $a = 'foo';
@if @defined($a) good;
@if @not(@defined($a)) bad;
@if @defined(&funcname) good;

🧪 `@eq(a,b)` 🧪

Tests two values for equality. Example:

@if @eq($DOMAIN, ip6) DROP;

🌸 `@ne(a,b)` 🌸

Similar to @eq, this tests for non-equality.

🙃 `@not(x)` 🙃

Negates a boolean value.

🌐 `@resolve((hostname1 hostname2 ...), [type])` 🌐

Usually, hostnames are resolved by iptables. To let ferm resolve hostnames, use the function @resolve:

saddr @resolve(my.host.foo) proto tcp dport ssh ACCEPT;
saddr @resolve((another.host.foo third.host.foo)) proto tcp dport openvpn ACCEPT;
daddr @resolve(ipv6.google.com, AAAA) proto tcp dport http ACCEPT;

Note the double parentheses in the second line: the inner pair for creating a ferm list, and the outer pair as function parameter delimiters.

The second parameter is optional and specifies the DNS record type. The default is "A" for domain ip and "AAAA" for domain ip6.

⚠️ Be careful with resolved hostnames in the firewall configuration. DNS requests may block the firewall configuration for a long time, leaving the machine vulnerable, or they may fail. no cap, this is the “handle with care” part 😭

🧵 `@cat(a, b, ...)` 🧵

Concatenate all parameters into one string.

🎀 `@join(separator, a, b, ...)` 🎀

Join all parameters into one string, separated by the given separator string.

✂️ `@substr(expression, offset, length)` ✂️

Extracts a substring out of expression and returns it. First character is at offset 0. If OFFSET is negative, starts that far from the end of the string.

📏 `@length(expression)` 📏

Returns the length in characters of the value of EXPR.

🗂️ `@basename(path)` 🗂️

Return the base name of the file for a given path (File::Spec::splitpath).

📁 `@dirname(path)` 📁

Return the name of the last directory for a given path, assuming the last component is a file name (File::Spec::splitpath).

🐚 `@glob(path)` 🐚

Expand shell wildcards in the given paths (assumed to be relative to the current script). Returns a list of matching files. This function is useful as a parameter of @include.

🛡️ `@ipfilter(list)` 🛡️

Filters out the IP addresses that obviously do not match the current domain. That is useful to create common variables and rules for IPv4 and IPv6:

@def $TRUSTED_HOSTS = (192.168.0.40 2001:abcd:ef::40);

domain (ip ip6) chain INPUT {
    saddr @ipfilter($TRUSTED_HOSTS) proto tcp dport ssh ACCEPT;
}

🍓 RECIPES 🍓

The ./examples/ directory contains numerous ferm configuration which can be used to begin a new firewall. This section contains more samples, recipes and tricks. it’s giving “copy-paste but make it informed” ✨

💫 Easy port forwarding 💫

Ferm functions make routine tasks quick and easy:

@def &FORWARD_TCP($proto, $port, $dest) = {
    table filter chain FORWARD interface $DEV_WORLD outerface $DEV_DMZ daddr $dest proto $proto dport $port ACCEPT;
    table nat chain PREROUTING interface $DEV_WORLD daddr $HOST_STATIC proto $proto dport $port DNAT to $dest;
}

&FORWARD_TCP(tcp, http, 192.168.1.2);
&FORWARD_TCP(tcp, smtp, 192.168.1.3);
&FORWARD_TCP((tcp udp), domain, 192.168.1.4);

📡 Remote ferm 📡

If the target machine is not able to run ferm for some reason (maybe an embedded device without Perl), you can edit the ferm configuration file on another computer and let ferm generate a shell script there.

Example for OpenWRT:

ferm --remote --shell mywrt/ferm.conf >mywrt/firewall.user
chmod +x mywrt/firewall.user
scp mywrt/firewall.user mywrt.local.net:/etc/
ssh mywrt.local.net /etc/firewall.user

🎀 OPTIONS 🎀

--noexec — Do not execute the iptables(8) commands, but skip instead. This way you can parse your data, use --lines to view the output.
--flush — Clears the firewall rules and sets the policy of all chains to ACCEPT. ferm needs a configuration file for that to determine which domains and tables are affected.
--lines — Show the firewall lines that were generated from the rules. They will be shown just before they are executed, so if you get error messages from iptables(8) etc., you can see which rule caused the error.
--interactive — Apply the firewall rules and ask the user for confirmation. Reverts to the previous ruleset if there is no valid user response within 30 seconds (see --timeout). This is useful for remote firewall administration: you can test the rules without fearing to lock yourself out.
--timeout S — If --interactive is used, then roll back if there is no valid user response after this number of seconds. The default is 30.
--help — Show a brief list of available command-line options.
--version — Shows the version number of the program.
--fast — Enable fast mode: ferm generates an iptables-save(8) file and installs it with iptables-restore(8). This is much faster because ferm calls iptables(8) once for every rule by default.

Fast mode is enabled by default since ferm 2.0, deprecating this option.

--slow — Disable fast mode, i.e. run iptables(8) for every rule, and don't use iptables-restore(8).
--shell — Generate a shell script which calls iptables-restore(8) and prints it. Implies --fast --lines.
--remote — Generate rules for a remote machine. Implies --noexec and --lines. Can be combined with --shell.
--domain {ip|ip6} — Handle only the specified domain and choose it as default domain for rules where none is specified. ferm output may be empty if the domain is not configured in the input file.
--def '$name=value' — Override a variable defined in the configuration file.

🌈 SEE ALSO 🌈

iptables(8)

🧚 REQUIREMENTS 🧚

💻 Operating system 💻

Linux 2.4 or newer, with netfilter support and all netfilter modules used by your firewall script

🧰 Software 🧰

iptables and perl 5.6

💀 BUGS 💀

Bugs? What bugs?

If you find a bug, please report it on GitHub: https://github.com/MaxKellermann/ferm/issues

👑 COPYRIGHT 👑

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

💜 AUTHOR 👑

Max Kellermann <max.kellermann@gmail.com>, Auke Kok <sofar@foo-projects.org>

this iconic lil page is ferm 2.7, dated 2023-01-31, and it's FERM(1) — periodt bestie, go configure something slay 💅✨

📦 where this page comes from

alpine 3.23: ferm-doc 2.7-r1 · GPL-2.0-or-later
alpine 3.24: ferm-doc 2.7-r1 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms