1FERM(1) FIREWALL RULES MADE EASY FERM(1)
2
6 ferm - a firewall rule parser for linux
7
9 ferm options inputfile
10
12 ferm is a frontend for iptables. It reads the rules from a structured
13 configuration file and calls iptables(8) to insert them into the
14 running kernel.
15 ferm's goal is to make firewall rules easy to write and easy to read.
17 It tries to reduce the tedious task of writing down rules, thus
18 enabling the firewall administrator to spend more time on developing
19 good rules than the proper implementation of the rule.
20 To achieve this, ferm uses a simple but powerful configuration
22 language, which allows variables, functions, arrays, blocks. It also
23 allows you to include other files, allowing you to create libraries of
24 commonly used structures and functions.
25 ferm, pronounced "firm", stands for "For Easy Rule Making".
27
29 This manual page does not indend to teach you how firewalling works and
30 how to write good rules. There is already enough documentation on this
31 topic.
32
34 Let's start with a simple example:
35 chain INPUT {
37 proto tcp ACCEPT;
38 }
39 This will add a rule to the predefined input chain, matching and
41 accepting all tcp packets. Ok, let's make it more complicated:
42 chain (INPUT OUTPUT) {
44 proto (udp tcp) ACCEPT;
45 }
46 This will insert 4 rules, namely 2 in chain input, and 2 in chain
48 output, matching and accepting both udp and tcp packets. Normally you
49 would type this:
50 iptables -A INPUT -p tcp -j ACCEPT
52 iptables -A OUTPUT -p tcp -j ACCEPT
53 iptables -A INPUT -p udp -j ACCEPT
54 iptables -A OUTPUT -p udp -j ACCEPT
55 Note how much less typing we need to do? :-)
57 Basically, this is all there is to it, although you can make it quite
59 more complex. Something to look at:
60 chain INPUT {
62 policy ACCEPT;
63 daddr 10.0.0.0/8 proto tcp dport ! ftp jump mychain sport :1023 TOS 4 settos 8 mark 2;
64 daddr 10.0.0.0/8 proto tcp dport ftp REJECT;
65 }
66 My point here is, that *you* need to make nice rules, keep them
68 readable to you and others, and not make it into a mess.
69 It would aid the reader if the resulting firewall rules were placed
71 here for reference. Also, you could include the nested version with
72 better readability.
73 Try using comments to show what you are doing:
75 # this line enables transparent http-proxying for the internal network:
77 proto tcp if eth0 daddr ! 192.168.0.0/255.255.255.0
78 dport http REDIRECT to-ports 3128;
79 You will be thankful for it later!
81 chain INPUT {
83 policy ACCEPT;
84 interface (eth0 ppp0) {
85 # deny access to notorius hackers, return here if no match
86 # was found to resume normal firewalling
87 jump badguys;
88 protocol tcp jump fw_tcp;
90 protocol udp jump fw_udp;
91 }
92 }
93 The more you nest, the better it looks. Make sure the order you specify
95 is correct, you would not want to do this:
96 chain FORWARD {
98 proto ! udp DROP;
99 proto tcp dport ftp ACCEPT;
100 }
101 because the second rule will never match. Best way is to specify first
103 everyting that is allowed, and then deny everything else. Look at the
104 examples for more good snapshots. Most people do something like this:
105 proto tcp {
107 dport (
108 ssh http ftp
109 ) ACCEPT;
110 dport 1024:65535 ! syn ACCEPT;
111 DROP;
112 }
113
115 The structure of a proper firewall file looks like simplified C-code.
116 Only a few syntactic characters are used in ferm- configuration files.
117 Besides these special caracters, ferm uses 'keys' and 'values', think
118 of them as options and parameters, or as variables and values,
119 whatever.
120 With these words, you define the characteristics of your firewall.
122 Every firewall consists of two things: First, look if network traffic
123 matches certain conditions, and second, what to do with that traffic.
124 You may specify conditions that are valid for the kernel interface
126 program you are using, probably iptables(8). For instance, in iptables,
127 when you are trying to match tcp packets, you would say:
128 iptables --protocol tcp
130 In ferm, this will become:
132 protocol tcp;
134 Just typing this in ferm doesn't do anything, you need to tell ferm
136 (actually, you need to tell iptables(8) and the kernel) what to do with
137 any traffic that matches this condition:
138 iptables --protocol tcp -j ACCEPT
140 Or, translated to ferm:
142 protocol tcp ACCEPT;
144 The ; character is at the end of every ferm rule. Ferm ignores line
146 breaks, meaning the above example is identical to the following:
147 protocol tcp
149 ACCEPT;
150 Here's a list of the special characters:
152 ; This character finalizes a rule.
154 Separated by semicolons, you may write multiple rules in one
156 line, although this decreases readability:
157 protocol tcp ACCEPT; protocol udp DROP;
159 {} The nesting symbol defines a 'block' of rules.
161 The curly brackets contain any number of nested rules. All
163 matches before the block are carried forward to these.
164 The closing curly bracket finalizes the rule set. You should
166 not write a ';' after that, because that would be an empty
167 rule.
168 Example:
170 chain INPUT proto icmp {
172 icmp-type echo-request ACCEPT;
173 DROP;
174 }
175 This block shows two rules inside a block, which will both be
177 merged with anything in front of it, so you will get two rules:
178 iptables -A INPUT -p icmp --icmp-type echo-request -j ACCEPT
180 iptables -A INPUT -p icmp -j DROP
181 There can be multiple nesting levels:
183 chain INPUT {
185 proto icmp {
186 icmp-type echo-request ACCEPT;
187 DROP;
188 }
189 daddr 172.16.0.0/12 REJECT;
190 }
191 Note that the 'REJECT' rule is not affected by 'proto icmp',
193 although there is no ';' after the closing curly brace.
194 Translated to iptables:
195 iptables -A INPUT -p icmp --icmp-type echo-request -j ACCEPT
197 iptables -A INPUT -p icmp -j DROP
198 iptables -A INPUT -d 172.16.0.0/12 -j REJECT
199 $ Variable expansion. Replaces '$FOO' by the value of the
201 variable. See the section VARIABLES for details.
202 & Function call. See the section FUNCTIONS for details.
204 () The array symbol. Using the parentheses, you can define a
206 'list' of values that should be applied for the key to the left
207 of it.
208 Example:
210 protocol ( tcp udp icmp )
212 this will result in three rules:
214 ... -p tcp ...
216 ... -p udp ...
217 ... -p icmp ...
218 Only values can be 'listed', so you cannot do something like
220 this:
221 proto tcp ( ACCEPT LOG );
223 but you can do this:
225 chain (INPUT OUTPUT FORWARD) proto (icmp udp tcp) DROP;
227 (which will result in nine rules!)
229 Values are separated by spaces. The array symbol is both left-
231 and right-associative, in contrast with the nesting block,
232 which is left-associative only.
233 " # " The comment symbol. Anything that follows this symbol up to the
235 end of line is ignored.
236 "`command`"
238 Execute the command in a shell, and insert the process output.
239 See the section backticks for details.
240 'string'
242 Quote a string which may contain whitespaces, the dollar sign
243 etc.
244 LOG log-prefix ' hey, this is my log prefix!';
246 "string"
248 Quote a string (see above), but variable references with a
249 dollar sign are evaluated:
250 DNAT to "$myhost:$myport";
252 Keywords
254 In the previous section, we already introduced some basic keywords like
255 "chain", "protocol" and "ACCEPT". Let's explore their nature.
256 There are three kinds of keywords:
258 · location keywords define where a rule will be created. Example:
260 "table", "chain".
261 · match keywords perform a test on all passing packets. The
263 current rule is without effect if one (or more) of the matches
264 does not pass. Example: "proto", "daddr".
265 Most matches are followed by a parameter: "proto tcp", "daddr
267 172.16.0.0/12".
268 · target keywords state what to do with a packet. Example:
270 "ACCEPT", "REJECT", "jump".
271 Some targets define more keywords to specify details: "REJECT
273 reject-with icmp-net-unreachable".
274 Every rule consists of a location and a target, plus any number of
276 matches:
277 table filter # location
279 proto tcp dport (http https) # match
280 ACCEPT; # target
281 Strictly speaking, there is a fourth kind: ferm keywords (which control
283 ferm's internal behaviour), but they will be explained later.
284 Parameters
286 Many keywords take parameters. These can be specified as literals,
287 variable references or lists (arrays):
288 proto udp
290 saddr $TRUSTED_HOSTS;
291 proto tcp dport (http https ssh);
292 LOG log-prefix "funky wardriver alert: ";
293 Some of them can be negated (lists cannot be negated):
295 proto !esp;
297 proto udp dport !domain;
298 Keywords which take no parameters are negated by a prefixed '!':
300 proto tcp !syn;
302 Read iptables(8) to see where the ! can be used.
304
306 Location keywords
307 domain [ip|ip6]
308 Set the domain. "ip" is default and means "IPv4" (iptables).
309 "ip6" is for IPv6 support, using "ip6tables".
310 table [filter|nat|mangle]
312 Specifies which netfilter table this rule will be inserted to:
313 "filter" (default), "nat" or "mangle".
314 chain [chain-name]
316 Specifies the netfilter chain (within the current table) this
317 rule will be inserted to. Common predefined chain names are
318 "INPUT", "OUTPUT", "FORWARD", "PREROUTING", "POSTROUTING",
319 depending on the table. See the netfilter documentation for
320 details.
321 If you specify a non-existing chain here, ferm will add the
323 rule to a custom chain with that name.
324 policy [ACCEPT|DROP|..]
326 Specifies the default policy for the current chain (built-in
327 only). Can be one of the built-in targets (ACCEPT, DROP,
328 REJECT, ...). A packet that matches no rules in a chain will be
329 treated as specified by the policy.
330 To avoid ambiguity, always specify the policies of all
332 predefined chains explicitly.
333 @subchain ["CHAIN-NAME"] { ... }
335 Works like the normal block operators (i.e. without the
336 @subchain keyword), except that ferm moves rules within the
337 curly braces into a new custom chain. The name for this chain
338 is chosen automatically by ferm.
339 In many cases, this is faster than just a block, because the
341 kernel may skip a huge block of rules when a precondition is
342 false. Imagine the following example:
343 table filter chain INPUT {
345 saddr (1.2.3.4 2.3.4.5 3.4.5.6 4.5.6.7 5.6.7.8) {
346 proto tcp dport (http https ssh) ACCEPT;
347 proto udp dport domain ACCEPT;
348 }
349 }
350 This generates 20 rules. When a packet arrives which does not
352 pass the saddr match, it nonetheless checks all 20 rules. With
353 @subchain, this check is done once, resulting in faster network
354 filtering and less CPU load:
355 table filter chain INPUT {
357 saddr (1.2.3.4 2.3.4.5 3.4.5.6 4.5.6.7 5.6.7.8) @subchain {
358 proto tcp dport (http https ssh) ACCEPT;
359 proto udp dport domain ACCEPT;
360 }
361 }
362 Optionally, you may define the name of the sub chain:
364 saddr (1.2.3.4 2.3.4.5 3.4.5.6) @subchain "foobar" {
366 proto tcp dport (http https ssh) ACCEPT;
367 proto udp dport domain ACCEPT;
368 }
369 The name can either be a quoted string literal, or an expanded
371 ferm expression such as @cat("interface_", $iface) or
372 @substr($var,0,20).
373 You can achieve the same by explicitly declaring a custom
375 chain, but you may feel that using @subchain requires less
376 typing.
377 Basic iptables match keywords
379 interface [interface-name]
380 Define the interface name, your outside network card, like
381 eth0, or dialup like ppp1, or whatever device you want to match
382 for passing packets. It is equivalent to the "-i" switch in
383 iptables(8).
384 outerface [interface-name]
386 Same as interface, only for matching the outgoing interface for
387 a packet, as in iptables(8).
388 protocol [protocol-name|protocol-number]
390 Currently supported by the kernel are tcp, udp and icmp, or
391 their respective numbers.
392 saddr|daddr [address-spec]
394 Matches on packets originating from the specified address
395 (saddr) or targeted at the address (daddr).
396 Examples:
398 saddr 192.168/8 ACCEPT; # (identical to the next one:)
400 saddr 192.168.0.0/255.255.255.0 ACCEPT;
401 daddr my.domain.com ACCEPT;
402 fragment
404 Specify that only fragmented IP packets should be matched.
405 When packets are larger that the maximum packet size your
406 system can handle (called Maximum Transmission Unit or MTU)
407 they will be chopped into bits and sent one by one as single
408 packets. See ifconfig(8) if you want to find the MTU for your
409 system (the default is usually 1500 bytes).
410 Fragments are frequently used in DOS attacks, because there is
412 no way of finding out the origin of a fragment packet.
413 sport|dport [port-spec]
415 Matches on packets on the specified TCP or UDP port. "sport"
416 matches the source port, and dport matches the destination
417 port.
418 This match can be used only after you specified "protocol tcp"
420 or "protocol udp", because only these two protocols actually
421 have ports.
422 And some examples of valid ports/ranges:
424 dport 80 ACCEPT;
426 dport http ACCEPT;
427 dport ssh:http ACCEPT;
428 dport 0:1023 ACCEPT; # equivalent to :1023
429 dport 1023:65535 ACCEPT;
430 syn Specify that the SYN flag in a tcp package should be matched,
432 which are used to build new tcp connections. You can identify
433 incoming connections with this, and decide wether you want to
434 allow it or not. Packets that do not have this flag are
435 probably from an already established connection, so it's
436 considered reasonably safe to let these through.
437 module [module-name]
439 Load an iptables module. Most modules provide more match
440 keywords. We'll get to that later.
441 Basic target keywords
443 jump [custom-chain-name]
444 Jumps to a custom chain. If no rule in the custom chain
445 matched, netfilter returns to the next rule in the previous
446 chain.
447 realgoto [custom-chain-name]
449 Go to a custom chain. Unlike the jump option, RETURN will not
450 continue processing in this chain but instead in the chain that
451 called us via jump.
452 The keyword realgoto was chosen during the transition period,
454 because goto (already deprecated) used to be an alias for jump.
455 ACCEPT Accepts matching packets.
457 DROP Drop matching packets without further notice.
459 REJECT Rejects matching packets, i.e. send an ICMP packet to the
461 sender, which is port-unreachable by default. You may specify
462 another ICMP type.
463 REJECT; # default to icmp-port-unreachable
465 REJECT reject-with icmp-net-unreachable;
466 Type "iptables -j REJECT -h" for details.
468 RETURN Finish the current chain and return to the calling chain (if
470 "jump [custom-chain-name]" was used).
471 NOP No action at all.
473
475 Netfilter is modular. Modules may provide additional targets and match
476 keywords. The list of netfilter modules is constantly growing, and ferm
477 tries to keep up with supporting them all. This chapter describes
478 modules which are currently supported.
479 iptables match modules
481 account Account traffic for all hosts in defined network/netmask. This
482 is one of the match modules which behave like a target, i.e.
483 you will mostly have to use the NOP target.
484 mod account aname mynetwork aaddr 192.168.1.0/24 ashort NOP;
486 addrtype
488 Check the address type; either source address or destination
489 address.
490 mod addrtype src-type BROADCAST;
492 mod addrtype dst-type LOCAL;
493 Type "iptables -m addrtype -h" for details.
495 ah Checks the SPI header in an AH packet.
497 mod ah ahspi 0x101;
499 mod ah ahspi ! 0x200:0x2ff;
500 Additional arguments for IPv6:
502 mod ah ahlen 32 ACCEPT;
504 mod ah ahlen !32 ACCEPT;
505 mod ah ahres ACCEPT;
506 comment Adds a comment of up to 256 characters to a rule, without an
508 effect. Note that unlike ferm comments ('#'), this one will
509 show up in "iptables -L".
510 mod comment comment "This is my comment." ACCEPT;
512 condition
514 Matches if a value in /proc/net/ipt_condition/NAME is 1 (path
515 is /proc/net/ip6t_condition/NAME for the ip6 domain).
516 mod condition condition (abc def) ACCEPT;
518 mod condition condition !foo ACCEPT;
519 connbytes
521 Match by how many bytes or packets a connection (or one of the
522 two flows constituting the connection) have tranferred so far,
523 or by average bytes per packet.
524 mod connbytes connbytes 65536: connbytes-dir both connbytes-mode bytes ACCEPT;
526 mod connbytes connbytes !1024:2048 connbytes-dir reply connbytes-mode packets ACCEPT;
527 Valid values for connbytes-dir: original, reply, both; for
529 connbytes-mode: packets, bytes, avgpkt.
530 connlimit
532 Allows you to restrict the number of parallel TCP connections
533 to a server per client IP address (or address block).
534 mod connlimit connlimit-above 4 REJECT;
536 mod connlimit connlimit-above !4 ACCEPT;
537 mod connlimit connlimit-above 4 connlimit-mask 24 REJECT;
538 connmark
540 Check the mark field associated with the connection, set by the
541 CONNMARK target.
542 mod connmark mark 64;
544 mod connmark mark 6/7;
545 conntrack
547 Check connection tracking information.
548 mod conntrack ctstate (ESTABLISHED RELATED);
550 mod conntrack ctproto tcp;
551 mod conntrack ctorigsrc 192.168.0.2;
552 mod conntrack ctorigdst 1.2.3.0/24;
553 mod conntrack ctorigsrcport 67;
554 mod conntrack ctorigdstport 22;
555 mod conntrack ctreplsrc 2.3.4.5;
556 mod conntrack ctrepldst ! 3.4.5.6;
557 mod conntrack ctstatus ASSURED;
558 mod conntrack ctexpire 60;
559 mod conntrack ctexpire 180:240;
560 Type "iptables -m conntrack -h" for details.
562 dccp Check DCCP (Datagram Congestion Control Protocol) specific
564 attributes. This module is automatically loaded when you use
565 "protocol dccp".
566 proto dccp sport 1234 dport 2345 ACCEPT;
568 proto dccp dccp-types (SYNCACK ACK) ACCEPT;
569 proto dccp dccp-types !REQUEST DROP;
570 proto dccp dccp-option 2 ACCEPT;
571 dscp Match the 6 bit DSCP field within the TOS field.
573 mod dscp dscp 11;
575 mod dscp dscp-class AF41;
576 ecn Match the ECN bits of an IPv4 TCP header.
578 mod ecn ecn-tcp-cwr;
580 mod ecn ecn-tcp-ece;
581 mod ecn ecn-ip-ect 2;
582 Type "iptables -m ecn -h" for details.
584 esp Checks the SPI header in an ESP packet.
586 mod esp espspi 0x101;
588 mod esp espspi ! 0x200:0x2ff;
589 eui64 "This module matches the EUI-64 part of a stateless
591 autoconfigured IPv6 address. It compares the EUI-64 derived
592 from the source MAC address in Ehternet frame with the lower 64
593 bits of the IPv6 source address. But "Universal/Local" bit is
594 not compared. This module doesn't match other link layer
595 frame, and is only valid in the PREROUTING, INPUT and FORWARD
596 chains."
597 mod eui64 ACCEPT;
599 fuzzy "This module matches a rate limit based on a fuzzy logic
601 controller [FLC]."
602 mod fuzzy lower-limit 10 upper-limit 20 ACCEPT;
604 hbh Matches the Hop-by-Hop Options header (ip6).
606 mod hbh hbh-len 8 ACCEPT;
608 mod hbh hbh-len !8 ACCEPT;
609 mod hbh hbh-opts (1:4 2:8) ACCEPT;
610 hl Matches the Hop Limit field (ip6).
612 mod hl hl-eq (8 10) ACCEPT;
614 mod hl hl-eq !5 ACCEPT;
615 mod hl hl-gt 15 ACCEPT;
616 mod hl hl-lt 2 ACCEPT;
617 helper Checks which conntrack helper module tracks this connection.
619 The port may be specified with "-portnr".
620 mod helper helper irc ACCEPT;
622 mod helper helper ftp-21 ACCEPT;
623 icmp Check ICMP specific attributes. This module is automatically
625 loaded when you use "protocol icmp".
626 proto icmp icmp-type echo-request ACCEPT;
628 This option can also be used in be ip6 domain, although this is
630 called icmpv6 in ip6tables.
631 Use "iptables -p icmp "-h"" to obtain a list of valid ICMP
633 types.
634 iprange Match a range of IPv4 addresses.
636 mod iprange src-range 192.168.2.0-192.168.3.255;
638 mod iprange dst-range ! 192.168.6.0-192.168.6.255;
639 ipv4options
641 Match on IPv4 header options like source routing, record route,
642 timestamp and router-alert.
643 mod ipv4options ssrr ACCEPT;
645 mod ipv4options lsrr ACCEPT;
646 mod ipv4options no-srr ACCEPT;
647 mod ipv4options !rr ACCEPT;
648 mod ipv4options !ts ACCEPT;
649 mod ipv4options !ra ACCEPT;
650 mod ipv4options !any-opt ACCEPT;
651 ipv6header
653 Matches the IPv6 extension header (ip6).
654 mod ipv6header header !(hop frag) ACCEPT;
656 mod ipv6header header (auth dst) ACCEPT;
657 hashlimit
659 Similar to 'mod limit', but adds the ability to add per-
660 destination or per-port limits managed in a hash table.
661 mod hashlimit hashlimit 10/minute hashlimit-burst 30/minute
663 hashlimit-mode dstip hashlimit-name foobar ACCEPT;
664 Possible values for hashlimit-mode: dstip dstport srcip srcport
666 (or a list with more than one of these).
667 There are more possible settings, type "iptables -m hashlimit
669 -h" for documentation.
670 length Check the package length.
672 mod length length 128; # exactly 128 bytes
674 mod length length 512:768; # range
675 mod length length ! 256; # negated
676 limit Limits the packet rate.
678 mod limit limit 1/second;
680 mod limit limit 15/minute limit-burst 10;
681 Type "iptables -m limit -h" for details.
683 mac Match the source MAC address.
685 mod mac mac-source 01:23:45:67:89;
687 mark Matches packets based on their netfilter mark field. This may
689 be a 32 bit integer between 0 and 4294967295.
690 mod mark mark 42;
692 mh Matches the mobility header (domain ip6).
694 proto mh mh-type binding-update ACCEPT;
696 multiport
698 Match a set of source or destination ports (UDP and TCP only).
699 mod multiport source-ports (https ftp);
701 mod multiport destination-ports (mysql domain);
702 This rule has a big advantage over "dport" and "sport": it
704 generates only one rule for up to 15 ports instead of one rule
705 for every port.
706 nth Match every 'n'th packet.
708 mod nth every 3;
710 mod nth counter 5 every 2;
711 mod nth start 2 every 3;
712 mod nth start 5 packet 2 every 6;
713 Type "iptables -m nth -h" for details.
715 osf Match packets depending on the operating system of the sender.
717 mod osf genre Linux;
719 mod osf ! genre FreeBSD ttl 1 log 1;
720 Type "iptables -m osf -h" for details.
722 owner Check information about the packet creator, namely user id,
724 group id, process id, session id and command name.
725 mod owner uid-owner 0;
727 mod owner gid-owner 1000;
728 mod owner pid-owner 5432;
729 mod owner sid-owner 6543;
730 mod owner cmd-owner "sendmail";
731 ("cmd-owner", "pid-owner" and "sid-owner" require special
733 kernel patches not included in the vanilla Linux kernel)
734 physdev Matches the physical device on which a packet entered or is
736 about to leave the machine. This is useful for bridged
737 interfaces.
738 mod physdev physdev-in ppp1;
740 mod physdev physdev-out eth2;
741 mod physdev physdev-is-in;
742 mod physdev physdev-is-out;
743 mod physdev physdev-is-bridged;
744 pkttype Check the link-layer packet type.
746 mod pkttype pkt-type unicast;
748 mod pkttype pkt-type broadcase;
749 mod pkttype pkt-type multicast;
750 policy Matches IPsec policy being applied to this packet.
752 mod policy dir out pol ipsec ACCEPT;
754 mod policy strict reqid 23 spi 0x10 proto ah ACCEPT;
755 mod policy mode tunnel tunnel-src 192.168.1.2 ACCEPT;
756 mod policy mode tunnel tunnel-dst 192.168.2.1 ACCEPT;
757 mod policy strict next reqid 24 spi 0x11 ACCEPT;
758 Note that the keyword proto is also used as a shorthand version
760 of protocol (built-in match module). You can fix this conflict
761 by always using the long keyword protocol.
762 psd Detect TCP/UDP port scans.
764 mod psd psd-weight-threshold 21 psd-delay-threshold 300
766 psd-lo-ports-weight 3 psd-hi-ports-weight 1 DROP;
767 quota Implements network quotas by decrementing a byte counter with
769 each packet.
770 mod quota quota 65536 ACCEPT;
772 random Match a random percentage of all packets.
774 mod random average 70;
776 realm Match the routing realm. Useful in environments using BGP.
778 mod realm realm 3;
780 recent Temporarily mark source IP addresses.
782 mod recent set;
784 mod recent rcheck seconds 60;
785 mod recent set rsource name "badguy";
786 mod recent set rdest;
787 mod recent rcheck rsource name "badguy" seconds 60;
788 mod recent update seconds 120 hitcount 3 rttl;
789 This netfilter module has a design flaw: although it is
791 implemented as a match module, it has target-like behaviour
792 when using the "set" keyword.
793 <http://snowman.net/projects/ipt_recent/>
795 rt Match the IPv6 routing header (ip6 only).
797 mod rt rt-type 2 rt-len 20 ACCEPT;
799 mod rt rt-type !2 rt-len !20 ACCEPT;
800 mod rt rt-segsleft 2:3 ACCEPT;
801 mod rt rt-segsleft !4:5 ACCEPT;
802 mod rt rt-0-res rt-0-addrs (::1 ::2) rt-0-not-strict ACCEPT;
803 sctp Check SCTP (Stream Control Transmission Protocol) specific
805 attributes. This module is automatically loaded when you use
806 "protocol sctp".
807 proto sctp sport 1234 dport 2345 ACCEPT;
809 proto sctp chunk-types only DATA:Be ACCEPT;
810 proto sctp chunk-types any (INIT INIT_ACK) ACCEPT;
811 proto sctp chunk-types !all (HEARTBEAT) ACCEPT;
812 Use "iptables -p sctp "-h"" to obtain a list of valid chunk
814 types.
815 set Checks the source or destination IP/Port/MAC against a set.
817 mod set set badguys src DROP;
819 See <http://ipset.netfilter.org/> for more information.
821 state Checks the connection tracking state.
823 mod state state INVALID DROP;
825 mod state state (ESTABLISHED RELATED) ACCEPT;
826 Type "iptables -m state -h" for details.
828 statistic
830 Successor of nth and random, currently undocumented in the
831 iptables(8) man page.
832 mod statistic mode random probability 0.8 ACCEPT;
834 mod statistic mode nth every 5 packet 0 DROP;
835 string Matches a string.
837 mod string string "foo bar" ACCEPT;
839 mod string algo kmp from 64 to 128 hex-string "deadbeef" ACCEPT;
840 tcp Checks TCP specific attributes. This module is automatically
842 loaded when you use "protocol tcp".
843 proto tcp sport 1234;
845 proto tcp dport 2345;
846 proto tcp tcp-flags (SYN ACK) SYN;
847 proto tcp tcp-flags ! (SYN ACK) SYN;
848 proto tcp tcp-flags ALL (RST ACK);
849 proto tcp syn;
850 proto tcp tcp-option 2;
851 proto tcp mss 512;
852 Type "iptables -p tcp -h" for details.
854 tcpmss Check the TCP MSS field of a SYN or SYN/ACK packet.
856 mod tcpmss mss 123 ACCEPT;
858 mod tcpmss mss 234:567 ACCEPT;
859 time Check if the time a packet arrives is in given range.
861 mod time timestart 12:00;
863 mod time timestop 13:30;
864 mod time days (Mon Wed Fri);
865 mod time datestart 2005:01:01;
866 mod time datestart 2005:01:01:23:59:59;
867 mod time datestop 2005:04:01;
868 mod time monthday (30 31);
869 mod time weekdays (Wed Thu);
870 mod time timestart 12:00 utc;
871 mod time timestart 12:00 localtz;
872 Type "iptables -m time -h" for details.
874 tos Matches a packet on the specified TOS-value.
876 mod tos tos Minimize-Cost ACCEPT;
878 mod tos tos !Normal-Service ACCEPT;
879 Type "iptables -m tos -h" for details.
881 ttl Matches the ttl (time to live) field in the IP header.
883 mod ttl ttl-eq 12; # ttl equals
885 mod ttl ttl-gt 10; # ttl greater than
886 mod ttl ttl-lt 16; # ttl less than
887 u32 Compares raw data from the packet. You can specify more than
889 one filter in a ferm list; these are not expanded into multiple
890 rules.
891 mod u32 u32 '6&0xFF=1' ACCEPT;
893 mod u32 u32 ('27&0x8f=7' '31=0x527c4833') DROP;
894 unclean Matches packets which seem malformed or unusual. This match has
896 no further parameters.
897 iptables target modules
899 The following additional targets are available in ferm, provided that
900 you enabled them in your kernel:
901 CLASSIFY
903 Set the CBQ class.
904 CLASSIFY set-class 3:50;
906 CLUSTERIP
908 Configure a simple cluster of nodes that share a certain IP and
909 MAC address. Connections are statically distributed between
910 the nodes.
911 CLUSTERIP new hashmode sourceip clustermac 00:12:34:45:67:89
913 total-nodes 4 local-node 2 hash-init 12345;
914 CONNMARK
916 Sets the netfilter mark value associated with a connection.
917 CONNMARK set-mark 42;
919 CONNMARK save-mark;
920 CONNMARK restore-mark;
921 CONNMARK save-mark mask 0x7fff;
922 CONNMARK restore-mark mask 0x8000;
923 CONNSECMARK
925 This module copies security markings from packets to
926 connections (if unlabeled), and from connections back to
927 packets (also only if unlabeled). Typically used in
928 conjunction with SECMARK, it is only valid in the mangle table.
929 CONNSECMARK save;
931 CONNSECMARK restore;
932 DNAT to [ip-address|ip-range|ip-port-range]
934 Change the destination address of the packet.
935 DNAT to 10.0.0.4;
937 DNAT to 10.0.0.4:80;
938 DNAT to 10.0.0.4:1024-2048;
939 DNAT to 10.0.1.1-10.0.1.20;
940 ECN This target allows to selectively work around known ECN
942 blackholes. It can only be used in the mangle table.
943 ECN ecn-tcp-remove;
945 HL Modify the IPv6 Hop Limit field (ip6/mangle only).
947 HL hl-set 5;
949 HL hl-dec 2;
950 HL hl-inc 1;
951 IPV4OPTSSTRIP
953 Strip all the IP options from a packet. This module does not
954 take any options.
955 IPV4OPTSSTRIP;
957 LOG Log all packets that match this rule in the kernel log. Be
959 carefull with log flooding. Note that this is a "non-
960 terminating target", i.e. rule traversal continues at the next
961 rule.
962 LOG log-level warning log-prefix "Look at this: ";
964 LOG log-tcp-sequence log-tcp-options;
965 LOG log-ip-options;
966 MARK Sets the netfilter mark field for the packet (a 32 bit integer
968 between 0 and 4294967295):
969 MARK set-mark 42;
971 MARK set-xmark 7/3;
972 MARK and-mark 31;
973 MARK or-mark 1;
974 MARK xor-mark 12;
975 MASQUERADE
977 Masquerades matching packets. Optionally followed by a port or
978 port-range for iptables. Specify as "123", "123-456" or
979 "123:456". The port range parameter specifies what local ports
980 masqueraded connections should originate from.
981 MASQUERADE;
983 MASQUERADE to-ports 1234:2345;
984 MASQUERADE to-ports 1234:2345 random;
985 MIRROR Experimental demonstration target which inverts the source and
987 destination fields in the IP header.
988 MIRROR;
990 NETMAP Map a whole network onto another network in the nat table.
992 NETMAP to 192.168.2.0/24;
994 NOTRACK Disable connection tracking for all packets matching that rule.
996 proto tcp dport (135:139 445) NOTRACK;
998 NFLOG Log packets over netlink; this is the successor of ULOG.
1000 NFLOG nflog-group 5 nflog-prefix "Look at this: ";
1002 NFLOG nflog-range 256;
1003 NFLOG nflog-threshold 10;
1004 NFQUEUE Userspace queueing, requires nfnetlink_queue kernel support.
1006 proto tcp dport ftp NFQUEUE queue-num 20;
1008 QUEUE Userspace queueing, the predecessor to NFQUEUE. All packets go
1010 to queue 0.
1011 proto tcp dport ftp QUEUE;
1013 REDIRECT to-ports [ports]
1015 Transparent proxying: alter the destination IP of the packet to
1016 the machine itself.
1017 proto tcp dport http REDIRECT to-ports 3128;
1019 proto tcp dport http REDIRECT to-ports 3128 random;
1020 SAME Similar to SNAT, but a client is mapped to the same source IP
1022 for all its connections.
1023 SAME to 1.2.3.4-1.2.3.7;
1025 SAME to 1.2.3.8-1.2.3.15 nodst;
1026 SAME to 1.2.3.16-1.2.3.31 random;
1027 SECMARK This is used to set the security mark value associated with the
1029 packet for use by security subsystems such as SELinux. It is
1030 only valid in the mangle table.
1031 SECMARK selctx "system_u:object_r:httpd_packet_t:s0";
1033 SET [add-set|del-set] [setname] [flag(s)]
1035 Add the IP to the specified set. See
1036 <http://ipset.netfilter.org/>
1037 proto icmp icmp-type echo-request SET add-set badguys src;
1039 SNAT to [ip-address|ip-range|ip-port-range]
1041 Change the source address of the packet.
1042 SNAT to 1.2.3.4;
1044 SNAT to 1.2.3.4:20000-30000;
1045 SNAT to 1.2.3.4 random;
1046 TCPMSS Alter the MSS value of TCP SYN packets.
1048 TCPMSS set-mss 1400;
1050 TCPMSS clamp-mss-to-pmtu;
1051 TOS set-tos [value]
1053 Set the tcp package Type Of Service bit to this value. This
1054 will be used by whatever traffic scheduler is willing to,
1055 mostly your own linux-machine, but maybe more. The original
1056 tos-bits are blanked and overwritten by this value.
1057 TOS set-tos Maximize-Throughput;
1059 TOS and-tos 7;
1060 TOS or-tos 1;
1061 TOS xor-tos 4;
1062 Type "iptables -j TOS -h" for details.
1064 TTL Modify the TTL header field.
1066 TTL ttl-set 16;
1068 TTL ttl-dec 1; # decrease by 1
1069 TTL ttl-inc 4; # increase by 4
1070 ULOG Log packets to a userspace program.
1072 ULOG ulog-nlgroup 5 ulog-prefix "Look at this: ";
1074 ULOG ulog-cprange 256;
1075 ULOG ulog-qthreshold 10;
1076
1078 Since version 2.0, ferm supports not only ip and ip6, but also arp (ARP
1079 tables) and eb (ethernet bridging tables). The concepts are similar to
1080 iptables.
1081 arptables keywords
1083 source-ip, destination-ip
1084 Matches the source or destination IPv4 address. Same as saddr
1085 and daddr in the ip domain.
1086 source-mac, destination-mac
1088 Matches the source or destination MAC address.
1089 interface, outerface
1091 Input and output interface.
1092 h-length
1094 Hardware length of the packet.
1095 chain INPUT h-length 64 ACCEPT;
1097 opcode Operation code, for details see the iptables(8).
1099 opcode 9 ACCEPT;
1101 h-type Hardware type.
1103 h-type 1 ACCEPT;
1105 proto-type
1107 Protocol type.
1108 proto-type 0x800 ACCEPT;
1110 Mangling
1112 The keywords mangle-ip-s, mangle-ip-d, mangle-mac-s, mangle-
1113 mac-d, mangle-target may be used for ARP mangling. See
1114 iptables(8) for details.
1115 ebtables keywords
1117 proto Matches the protocol which created the frame, e.g. IPv4 or PPP.
1118 For a list, see /etc/ethertypes.
1119 interface, outerface
1121 Physical input and output interface.
1122 logical-in, logical-out
1124 The logical bridge interface.
1125 saddr, daddr
1127 Matches source or destination MAC address.
1128 Match modules
1130 The following match modules are supported: 802.3, arp, ip,
1131 mark_m, pkttype, stp, vlan, log.
1132 Target extensions
1134 The following target extensions are supported: arpreply, dnat,
1135 mark, redirect, snat.
1136 Please note that there is a conflict between --mark from the
1138 mark_m match module and -j mark. Since both would be
1139 implemented with the ferm keyword mark, we decided to solve
1140 this by writing the target's name in uppercase, like in the
1141 other domains. The following example rewrites mark 1 to 2:
1142 mark 1 MARK 2;
1144
1146 Variables
1147 In complex firewall files, it is helpful to use variables, e.g. to give
1148 a network interface a meaningful name.
1149 To set variables, write:
1151 @def $DEV_INTERNET = eth0;
1153 @def $PORTS = (http ftp);
1154 @def $MORE_PORTS = ($PORTS 8080);
1155 In the real ferm code, variables are used like any other keyword
1157 parameter:
1158 chain INPUT interface $DEV_INTERNET proto tcp dport $MORE_PORTS ACCEPT;
1160 Note that variables can only be used in keyword parameters
1162 ("192.168.1.1", "http"); they cannot contain ferm keywords like "proto"
1163 or "interface".
1164 Variables are only valid in the current block:
1166 @def $DEV_INTERNET = eth1;
1168 chain INPUT {
1169 proto tcp {
1170 @def $DEV_INTERNET = ppp0;
1171 interface $DEV_INTERNET dport http ACCEPT;
1172 }
1173 interface $DEV_INTERNET DROP;
1174 }
1175 will be expanded to:
1177 chain INPUT {
1179 proto tcp {
1180 interface ppp0 dport http ACCEPT;
1181 }
1182 interface eth1 DROP;
1183 }
1184 The "def $DEV_INTERNET = ppp0" is only valid in the "proto tcp" block;
1186 the parent block still knows "set $DEV_INTERNET = eth1".
1187 Include files are special - variables declared in an included file are
1189 still available in the calling block. This is useful when you include a
1190 file which only declares variables.
1191 Automatic variables
1193 Some variables are set internally by ferm. Ferm scripts can use them
1194 just like any other variable.
1195 $FILENAME
1197 The name of the configuration file relative to the directory
1198 ferm was started in.
1199 $FILEBNAME
1201 The base name of the configuration file.
1202 $DIRNAME
1204 The directory of the configuration file.
1205 $DOMAIN The current domain. One of ip, ip6, arp, eb.
1207 $TABLE The current netfilter table.
1209 $CHAIN The current netfilter chain.
1211 $LINE The line of the current script. It can be used like this:
1213 @def &log($msg) = {
1215 LOG log-prefix "rule=$msg:$LINE ";
1216 }
1217 .
1218 .
1219 .
1220 &log("log message");
1221 Functions
1223 Functions are similar to variables, except that they may have
1224 parameters, and they provide ferm commands, not values.
1225 @def &FOO() = proto (tcp udp) dport domain;
1227 &FOO() ACCEPT;
1228 @def &TCP_TUNNEL($port, $dest) = {
1230 table filter chain FORWARD interface ppp0 proto tcp dport $port daddr $dest outerface eth0 ACCEPT;
1231 table nat chain PREROUTING interface ppp0 proto tcp dport $port daddr 1.2.3.4 DNAT to $dest;
1232 }
1233 &TCP_TUNNEL(http, 192.168.1.33);
1235 &TCP_TUNNEL(ftp, 192.168.1.30);
1236 &TCP_TUNNEL((ssh smtp), 192.168.1.2);
1237 A function call which contains a block (like '{...}') must be the last
1239 command in a ferm rule, i.e. it must be followed by ';'. The '&FOO()'
1240 example does not contain a block, thus you may write 'ACCEPT' after the
1241 call. To circumvent this, you can reorder the keywords:
1242 @def &IPSEC() = { proto (esp ah); proto udp dport 500; }
1244 chain INPUT ACCEPT &IPSEC();
1245 Backticks
1247 With backticks, you may use the output of an external command:
1248 @def $DNSSERVERS = `grep nameserver /etc/resolv.conf | awk '{print $2}'`;
1250 chain INPUT proto tcp saddr $DNSSERVERS ACCEPT;
1251 The command is executed with the shell (/bin/sh), just like backticks
1253 in perl. ferm does not do any variable expansion here.
1254 The output is then tokenized, and saved as a ferm list (array). Lines
1256 beginning with '#' are ignored; the other lines may contain any number
1257 of values, separated by whitespace.
1258 Includes
1260 The @include keyword allows you to include external files:
1261 @include 'vars.ferm';
1263 The file name is relative to the calling file, e.g. when including from
1265 /etc/ferm/ferm.conf, the above statement includes /etc/ferm/vars.ferm.
1266 Variables and functions declared in an included file are still
1267 available in the calling file.
1268 include works within a block:
1270 chain INPUT {
1272 @include 'input.ferm';
1273 }
1274 If you specify a directory (with a trailing '/'), all files in this
1276 directory are included, sorted alphabetically:
1277 @include 'ferm.d/';
1279 With a trailing pipe symbol, ferm executes a shell command and parses
1281 its output:
1282 @include '/root/generate_ferm_rules.sh $HOSTNAME|'
1284 Conditionals
1286 The keyword @if introduces a conditional expression:
1287 @if $condition DROP;
1289 A value is evaluated true just like in Perl: zero, empty list, empty
1291 string are false, everything else is true. Examples for true values:
1292 (a b); 1; 'foo'; (0 0)
1294 Examples for false values:
1296 (); 0; '0'; ''
1298 There is also @else:
1300 @if $condition DROP; @else REJECT;
1302 Note the semicolon before the @else.
1304 It is possible to use curly braces after either @if or @else:
1306 @if $condition {
1308 MARK set-mark 2;
1309 RETURN;
1310 } @else {
1311 MARK set-mark 3;
1312 }
1313 Since the closing curly brace also finishes the command, there is no
1315 need for semicolon.
1316 There is no @elsif, use @else @if instead.
1318 Example:
1320 @def $have_ipv6 = `test -f /proc/net/ip6_tables_names && echo 1 || echo`;
1322 @if $have_ipv6 {
1323 domain ip6 {
1324 # ....
1325 }
1326 }
1327 Hooks
1329 To run custom commands, you may install hooks:
1330 @hook pre "echo 0 >/proc/sys/net/ipv4/conf/eth0/forwarding";
1332 @hook post "echo 1 >/proc/sys/net/ipv4/conf/eth0/forwarding";
1333 @hook flush "echo 0 >/proc/sys/net/ipv4/conf/eth0/forwarding";
1334 The specified command is executed using the shell. "pre" means run the
1336 command before applying the firewall rules, and "post" means run the
1337 command afterwards. "flush" hooks are run after ferm has flushed the
1338 firewall rules (option --flush). You may install any number of hooks.
1339
1341 There are several built-in functions which you might find useful.
1342 @eq(a,b)
1344 Tests two values for equality. Example:
1345 @if @eq($DOMAIN, ip6) DROP;
1347 @ne(a,b)
1349 Similar to @eq, this tests for non-equality.
1350 @not(x)
1352 Negates a boolean value.
1353 @resolve((hostname1 hostname2 ...), [type])
1355 Usually, host names are resolved by iptables. To let ferm resolve host
1356 names, use the function @resolve:
1357 saddr @resolve(my.host.foo) proto tcp dport ssh ACCEPT;
1359 saddr @resolve((another.host.foo third.host.foo)) proto tcp dport openvpn ACCEPT;
1360 daddr @resolve(ipv6.google.com, AAAA) proto tcp dport http ACCEPT;
1361 Note the double parentheses in the second line: the inner pair for
1363 creating a ferm list, and the outer pair as function parameter
1364 delimiters.
1365 The second parameter is optional, and specifies the DNS record type.
1367 The default is "A".
1368 Be careful with resolved host names in firewall configuration. DNS
1370 requests may block the firewall configuration for a long time, leaving
1371 the machine vulnerable, or they may fail.
1372 @cat(a, b, ...)
1374 Concatenate all parameters into one string.
1375 @substr(expression, offset, length)
1377 Extracts a substring out of expression and returns it. First character
1378 is at offset 0. If OFFSET is negative, starts that far from the end of
1379 the string.
1380 @length(expression)
1382 Returns the length in characters of the value of EXPR.
1383 @basename(path)
1385 Return the base name of the file for a given path
1386 (File::Spec::splitpath).
1387 @dirname(path)
1389 Return the name of the last directory for a given path, assuming the
1390 last component is a file name (File::Spec::splitpath).
1391 @ipfilter(list)
1393 Filters out the IP addresses that obviously do not match the current
1394 domain. That is useful to create common variables and rules for IPv4
1395 and IPv6:
1396 @def $TRUSTED_HOSTS = (192.168.0.40 2001:abcd:ef::40);
1398 domain (ip ip6) chain INPUT {
1400 saddr @ipfilter($TRUSTED_HOSTS) proto tcp dport ssh ACCEPT;
1401 }
1402
1404 The ./examples/ directory contains numerous ferm configuration which
1405 can be used to begin a new firewall. This sections contains more
1406 samples, recipes and tricks.
1407 Easy port forwarding
1409 Ferm function make routine tasks quick and easy:
1410 @def &FORWARD_TCP($proto, $port, $dest) = {
1412 table filter chain FORWARD interface $DEV_WORLD outerface $DEV_DMZ daddr $dest proto $proto dport $port ACCEPT;
1413 table nat chain PREROUTING interface $DEV_WORLD daddr $HOST_STATIC proto $proto dport $port DNAT to $dest;
1414 }
1415 &FORWARD_TCP(tcp, http, 192.168.1.2);
1417 &FORWARD_TCP(tcp, smtp, 192.168.1.3);
1418 &FORWARD_TCP((tcp udp), domain, 192.168.1.4);
1419 Remote ferm
1421 If the target machine is not able to run ferm for some reason (maybe an
1422 embedded device without Perl), you can edit the ferm configuration file
1423 on another computer and let ferm generate a shell script there.
1424 Example for OpenWRT:
1426 ferm --remote --shell mywrt/ferm.conf >mywrt/firewall.user
1428 chmod +x mywrt/firewall.user
1429 scp mywrt/firewall.user mywrt.local.net:/etc/
1430 ssh mywrt.local.net /etc/firewall.user
1431
1433 --noexec Do not execute the iptables(8) commands, but skip instead.
1434 This way you can parse your data, use --lines to view the
1435 output.
1436 --flush Clears the firewall rules and sets the policy of all chains
1438 to ACCEPT. ferm needs a configuration file for that to
1439 determine which domains and tables are affected.
1440 --lines Show the firewall lines that were generated from the rules.
1442 They will be shown just before they are executed, so if you
1443 get error messages from iptables(8) etc., you can see which
1444 rule caused the error.
1445 --interactive
1447 Apply the firewall rules and ask the user for confirmation.
1448 Reverts to the previous ruleset if there is no valid user
1449 response within 30 seconds (see --timeout). This is useful
1450 for remote firewall administration: you can test the rules
1451 without fearing to lock yourself out.
1452 --timeout S If --interactive is used, then roll back if there is no
1454 valid user response after this number of seconds. The
1455 default is 30.
1456 --help Show a brief list of available commandline options.
1458 --version Shows the version number of the program.
1460 --fast Enable fast mode: ferm generates an iptables-save(8) file,
1462 and installs it with iptables-restore(8). This is much
1463 faster, because ferm calls iptables(8) once for every rule
1464 by default.
1465 Fast mode is enabled by default since ferm 2.0, deprecating
1467 this option.
1468 --slow Disable fast mode, i.e. run iptables(8) for every rule, and
1470 don't use iptables-restore(8).
1471 --shell Generate a shell script which calls iptables-restore(8) and
1473 prints it. Implies --fast --lines.
1474 --remote Generate rules for a remote machine. Implies --noexec and
1476 --lines. Can be combined with --shell.
1477 --domain {ip|ip6}
1479 Handle only the specified domain. ferm output may be empty
1480 if the domain is not configured in the input file.
1481 --def '$name=value'
1483 Override a variable defined in the configuration file.
1484
1486 iptables(8)
1487
1489 Operating system
1490 Linux 2.4 or newer, with netfilter support and all netfilter modules
1491 used by your firewall script
1492 Software
1494 iptables and perl 5.6
1495
1497 Bugs? What bugs?
1498 If you find a bug, please tell us: ferm@foo-projects.org
1500
1502 Copyright (C) 2001-2012 Max Kellermann <max@foo-projects.org>, Auke Kok
1503 <sofar@foo-projects.org>
1504 This program is free software; you can redistribute it and/or modify it
1506 under the terms of the GNU General Public License as published by the
1507 Free Software Foundation; either version 2 of the License, or (at your
1508 option) any later version.
1509 This program is distributed in the hope that it will be useful, but
1511 WITHOUT ANY WARRANTY; without even the implied warranty of
1512 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1513 General Public License for more details.
1514 You should have received a copy of the GNU General Public License along
1516 with this program; if not, write to the Free Software Foundation, Inc.,
1517 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
1518
1520 Max Kellermann <max@foo-projects.org>, Auke Kok
1521 <sofar@foo-projects.org>
1522ferm 2.2 2012-12-17 FERM(1)