6 # ferm, a firewall setup program that makes firewall rules easy!
8 # Copyright (C) 2001-2011 Max Kellermann, Auke Kok
10 # Comments, questions, greetings and additions to this program
11 # may be sent to <ferm@foo-projects.org>
15 # This program is free software; you can redistribute it and/or modify
16 # it under the terms of the GNU General Public License as published by
17 # the Free Software Foundation; either version 2 of the License, or
18 # (at your option) any later version.
20 # This program is distributed in the hope that it will be useful,
21 # but WITHOUT ANY WARRANTY; without even the implied warranty of
22 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23 # GNU General Public License for more details.
25 # You should have received a copy of the GNU General Public License
26 # along with this program; if not, write to the Free Software
27 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
32 B<ferm> - a firewall rule parser for linux
36 B<ferm> I<options> I<inputfile>
40 B<ferm> is a frontend for B<iptables>. It reads the rules from a
41 structured configuration file and calls iptables(8) to insert them
42 into the running kernel.
44 B<ferm>'s goal is to make firewall rules easy to write and easy to
45 read. It tries to reduce the tedious task of writing down rules, thus
46 enabling the firewall administrator to spend more time on developing
47 good rules than the proper implementation of the rule.
49 To achieve this, B<ferm> uses a simple but powerful configuration
50 language, which allows variables, functions, arrays, blocks. It also
51 allows you to include other files, allowing you to create libraries of
52 commonly used structures and functions.
54 B<ferm>, pronounced "firm", stands for "For Easy Rule Making".
59 This manual page does I<not> indend to teach you how firewalling works
60 and how to write good rules. There is already enough documentation on
66 Let's start with a simple example:
72 This will add a rule to the predefined input chain, matching and
73 accepting all tcp packets. Ok, let's make it more complicated:
75 chain (INPUT OUTPUT) {
76 proto (udp tcp) ACCEPT;
79 This will insert 4 rules, namely 2 in chain input, and 2 in chain
80 output, matching and accepting both udp and tcp packets. Normally you
83 iptables -A INPUT -p tcp -j ACCEPT
84 iptables -A OUTPUT -p tcp -j ACCEPT
85 iptables -A INPUT -p udp -j ACCEPT
86 iptables -A OUTPUT -p udp -j ACCEPT
88 Note how much less typing we need to do? :-)
90 Basically, this is all there is to it, although you can make it quite
91 more complex. Something to look at:
95 daddr 10.0.0.0/8 proto tcp dport ! ftp jump mychain sport :1023 TOS 4 settos 8 mark 2;
96 daddr 10.0.0.0/8 proto tcp dport ftp REJECT;
99 My point here is, that *you* need to make nice rules, keep
100 them readable to you and others, and not make it into a mess.
102 It would aid the reader if the resulting firewall rules were placed
103 here for reference. Also, you could include the nested version with
106 Try using comments to show what you are doing:
108 # this line enables transparent http-proxying for the internal network:
109 proto tcp if eth0 daddr ! 192.168.0.0/255.255.255.0
110 dport http REDIRECT to-ports 3128;
112 You will be thankful for it later!
116 interface (eth0 ppp0) {
117 # deny access to notorius hackers, return here if no match
118 # was found to resume normal firewalling
121 protocol tcp jump fw_tcp;
122 protocol udp jump fw_udp;
126 The more you nest, the better it looks. Make sure the order you
127 specify is correct, you would not want to do this:
131 proto tcp dport ftp ACCEPT;
134 because the second rule will never match. Best way is to specify
135 first everyting that is allowed, and then deny everything else.
136 Look at the examples for more good snapshots. Most people do
143 dport 1024:65535 ! syn ACCEPT;
147 =head1 STRUCTURE OF A FIREWALL FILE
149 The structure of a proper firewall file looks like simplified
150 C-code. Only a few syntactic characters are used in ferm-
151 configuration files. Besides these special caracters, ferm
152 uses 'keys' and 'values', think of them as options and
153 parameters, or as variables and values, whatever.
155 With these words, you define the characteristics of your firewall.
156 Every firewall consists of two things: First, look if network
157 traffic matches certain conditions, and second, what to do
160 You may specify conditions that are valid for the kernel
161 interface program you are using, probably iptables(8). For
162 instance, in iptables, when you are trying to match tcp
163 packets, you would say:
165 iptables --protocol tcp
167 In ferm, this will become:
171 Just typing this in ferm doesn't do anything, you need to tell
172 ferm (actually, you need to tell iptables(8) and the kernel) what
173 to do with any traffic that matches this condition:
175 iptables --protocol tcp -j ACCEPT
177 Or, translated to B<ferm>:
181 The B<;> character is at the end of every ferm rule. Ferm ignores line
182 breaks, meaning the above example is identical to the following:
187 Here's a list of the special characters:
193 This character finalizes a rule.
195 Separated by semicolons, you may write multiple rules in one line,
196 although this decreases readability:
198 protocol tcp ACCEPT; protocol udp DROP;
202 The nesting symbol defines a 'block' of rules.
204 The curly brackets contain any number of nested rules. All matches
205 before the block are carried forward to these.
207 The closing curly bracket finalizes the rule set. You should not write
208 a ';' after that, because that would be an empty rule.
212 chain INPUT proto icmp {
213 icmp-type echo-request ACCEPT;
217 This block shows two rules inside a block, which will both be merged
218 with anything in front of it, so you will get two rules:
220 iptables -A INPUT -p icmp --icmp-type echo-request -j ACCEPT
221 iptables -A INPUT -p icmp -j DROP
223 There can be multiple nesting levels:
227 icmp-type echo-request ACCEPT;
230 daddr 172.16.0.0/12 REJECT;
233 Note that the 'REJECT' rule is not affected by 'proto icmp', although
234 there is no ';' after the closing curly brace. Translated to iptables:
236 iptables -A INPUT -p icmp --icmp-type echo-request -j ACCEPT
237 iptables -A INPUT -p icmp -j DROP
238 iptables -A INPUT -d 172.16.0.0/12 -j REJECT
242 Variable expansion. Replaces '$FOO' by the value of the variable. See
243 the section I<VARIABLES> for details.
247 Function call. See the section I<FUNCTIONS> for details.
251 The array symbol. Using the parentheses, you can define
252 a 'list' of values that should be applied for the key to the
257 protocol ( tcp udp icmp )
259 this will result in three rules:
265 Only values can be 'listed', so you cannot do something like this:
267 proto tcp ( ACCEPT LOG );
271 chain (INPUT OUTPUT FORWARD) proto (icmp udp tcp) DROP;
273 (which will result in nine rules!)
275 Values are separated by spaces. The array symbol is both left- and
276 right-associative, in contrast with the nesting block, which is
277 left-associative only.
281 The comment symbol. Anything that follows this symbol up to
282 the end of line is ignored.
286 Execute the command in a shell, and insert the process output. See the
287 section I<backticks> for details.
291 Quote a string which may contain whitespaces, the dollar sign etc.
293 LOG log-prefix ' hey, this is my log prefix!';
297 Quote a string (see above), but variable references with a dollar sign
300 DNAT to "$myhost:$myport";
307 In the previous section, we already introduced some basic keywords
308 like "chain", "protocol" and "ACCEPT". Let's explore their nature.
310 There are three kinds of keywords:
316 B<location> keywords define where a rule will be created. Example:
321 B<match> keywords perform a test on all passing packets. The current
322 rule is without effect if one (or more) of the matches does not
323 pass. Example: "proto", "daddr".
325 Most matches are followed by a parameter: "proto tcp", "daddr
330 B<target> keywords state what to do with a packet. Example: "ACCEPT",
333 Some targets define more keywords to specify details: "REJECT
334 reject-with icmp-net-unreachable".
338 Every rule consists of a B<location> and a B<target>, plus any number
341 table filter # location
342 proto tcp dport (http https) # match
345 Strictly speaking, there is a fourth kind: B<ferm> keywords (which
346 control ferm's internal behaviour), but they will be explained later.
351 Many keywords take parameters. These can be specified as literals,
352 variable references or lists (arrays):
355 saddr $TRUSTED_HOSTS;
356 proto tcp dport (http https ssh);
357 LOG log-prefix "funky wardriver alert: ";
359 Some of them can be negated (lists cannot be negated):
362 proto udp dport !domain;
364 Keywords which take no parameters are negated by a prefixed '!':
368 Read iptables(8) to see where the B<!> can be used.
371 =head1 BASIC KEYWORDS
374 =head2 Location keywords
378 =item B<domain [ip|ip6]>
380 Set the domain. "ip" is default and means "IPv4" (iptables). "ip6" is
381 for IPv6 support, using "ip6tables".
383 =item B<table [filter|nat|mangle]>
385 Specifies which netfilter table this rule will be inserted to:
386 "filter" (default), "nat" or "mangle".
388 =item B<chain [chain-name]>
390 Specifies the netfilter chain (within the current table) this rule
391 will be inserted to. Common predefined chain names are "INPUT",
392 "OUTPUT", "FORWARD", "PREROUTING", "POSTROUTING", depending on the
393 table. See the netfilter documentation for details.
395 If you specify a non-existing chain here, ferm will add the rule to a
396 custom chain with that name.
398 =item B<policy [ACCEPT|DROP|..]>
400 Specifies the default policy for the current chain (built-in
401 only). Can be one of the built-in targets (ACCEPT, DROP, REJECT,
402 ...). A packet that matches no rules in a chain will be treated as
403 specified by the policy.
405 To avoid ambiguity, always specify the policies of all predefined
408 =item B<@subchain ["CHAIN-NAME"] { ... }>
410 Works like the normal block operators (i.e. without the I<@subchain>
411 keyword), except that B<ferm> moves rules within the curly braces into
412 a new custom chain. The name for this chain is chosen automatically by
415 In many cases, this is faster than just a block, because the kernel
416 may skip a huge block of rules when a precondition is false. Imagine
417 the following example:
419 table filter chain INPUT {
420 saddr (1.2.3.4 2.3.4.5 3.4.5.6 4.5.6.7 5.6.7.8) {
421 proto tcp dport (http https ssh) ACCEPT;
422 proto udp dport domain ACCEPT;
426 This generates 20 rules. When a packet arrives which does not pass the
427 B<saddr> match, it nonetheless checks all 20 rules. With B<@subchain>,
428 this check is done once, resulting in faster network filtering and
431 table filter chain INPUT {
432 saddr (1.2.3.4 2.3.4.5 3.4.5.6 4.5.6.7 5.6.7.8) @subchain {
433 proto tcp dport (http https ssh) ACCEPT;
434 proto udp dport domain ACCEPT;
438 Optionally, you may define the name of the sub chain:
440 saddr (1.2.3.4 2.3.4.5 3.4.5.6) @subchain "foobar" {
441 proto tcp dport (http https ssh) ACCEPT;
442 proto udp dport domain ACCEPT;
445 The name can either be a quoted string literal, or an expanded ferm
446 expression such as @cat("interface_", $iface) or @substr($var,0,20).
448 You can achieve the same by explicitly declaring a custom chain, but
449 you may feel that using B<@subchain> requires less typing.
455 =head2 Basic iptables match keywords
459 =item B<interface [interface-name]>
461 Define the interface name, your outside network card, like eth0,
462 or dialup like ppp1, or whatever device you want to match for
463 passing packets. It is equivalent to the C<-i> switch in
466 =item B<outerface [interface-name]>
468 Same as interface, only for matching the outgoing interface
469 for a packet, as in iptables(8).
471 =item B<protocol [protocol-name|protocol-number]>
473 Currently supported by the kernel are tcp, udp and icmp, or
474 their respective numbers.
476 =item B<saddr|daddr [address-spec]>
478 Matches on packets originating from the specified address (saddr) or
479 targeted at the address (daddr).
483 saddr 192.168/8 ACCEPT; # (identical to the next one:)
484 saddr 192.168.0.0/255.255.255.0 ACCEPT;
485 daddr my.domain.com ACCEPT;
489 Specify that only fragmented IP packets should be matched.
490 When packets are larger that the maximum packet size your
491 system can handle (called Maximum Transmission Unit or MTU)
492 they will be chopped into bits and sent one by one as single
493 packets. See ifconfig(8) if you want to find the MTU for
494 your system (the default is usually 1500 bytes).
496 Fragments are frequently used in DOS attacks, because there
497 is no way of finding out the origin of a fragment packet.
499 =item B<sport|dport [port-spec]>
501 Matches on packets on the specified TCP or UDP port. "sport" matches
502 the source port, and dport matches the destination port.
504 This match can be used only after you specified "protocol tcp" or
505 "protocol udp", because only these two protocols actually have ports.
507 And some examples of valid ports/ranges:
511 dport ssh:http ACCEPT;
512 dport 0:1023 ACCEPT; # equivalent to :1023
513 dport 1023:65535 ACCEPT;
517 Specify that the SYN flag in a tcp package should be matched,
518 which are used to build new tcp connections. You can identify
519 incoming connections with this, and decide wether you want
520 to allow it or not. Packets that do not have this flag are
521 probably from an already established connection, so it's
522 considered reasonably safe to let these through.
524 =item B<module [module-name]>
526 Load an iptables module. Most modules provide more match
527 keywords. We'll get to that later.
532 =head2 Basic target keywords
536 =item B<jump [custom-chain-name]>
538 Jumps to a custom chain. If no rule in the custom chain matched,
539 netfilter returns to the next rule in the previous chain.
541 =item B<realgoto [custom-chain-name]>
543 Go to a custom chain. Unlike the B<jump> option, B<RETURN> will not
544 continue processing in this chain but instead in the chain that called
547 The keyword B<realgoto> was chosen during the transition period,
548 because B<goto> (already deprecated) used to be an alias for B<jump>.
552 Accepts matching packets.
556 Drop matching packets without further notice.
560 Rejects matching packets, i.e. send an ICMP packet to the sender,
561 which is port-unreachable by default. You may specify another ICMP
564 REJECT; # default to icmp-port-unreachable
565 REJECT reject-with icmp-net-unreachable;
567 Type "iptables -j REJECT -h" for details.
571 Finish the current chain and return to the calling chain (if "jump
572 [custom-chain-name]" was used).
581 =head1 ADDITIONAL KEYWORDS
583 Netfilter is modular. Modules may provide additional targets and match
584 keywords. The list of netfilter modules is constantly growing, and
585 ferm tries to keep up with supporting them all. This chapter describes
586 modules which are currently supported.
589 =head2 iptables match modules
595 Account traffic for all hosts in defined network/netmask. This is one
596 of the match modules which behave like a target, i.e. you will mostly
597 have to use the B<NOP> target.
599 mod account aname mynetwork aaddr 192.168.1.0/24 ashort NOP;
603 Check the address type; either source address or destination address.
605 mod addrtype src-type BROADCAST;
606 mod addrtype dst-type LOCAL;
608 Type "iptables -m addrtype -h" for details.
612 Checks the SPI header in an AH packet.
615 mod ah ahspi ! 0x200:0x2ff;
617 Additional arguments for IPv6:
619 mod ah ahlen 32 ACCEPT;
620 mod ah ahlen !32 ACCEPT;
625 Adds a comment of up to 256 characters to a rule, without an effect.
626 Note that unlike ferm comments ('#'), this one will show up in
629 mod comment comment "This is my comment." ACCEPT;
633 Matches if a value in /proc/net/ipt_condition/NAME is 1 (path is
634 /proc/net/ip6t_condition/NAME for the ip6 domain).
636 mod condition condition (abc def) ACCEPT;
637 mod condition condition !foo ACCEPT;
641 Match by how many bytes or packets a connection (or one of the two
642 flows constituting the connection) have tranferred so far, or by
643 average bytes per packet.
645 mod connbytes connbytes 65536: connbytes-dir both connbytes-mode bytes ACCEPT;
646 mod connbytes connbytes !1024:2048 connbytes-dir reply connbytes-mode packets ACCEPT;
648 Valid values for I<connbytes-dir>: I<original>, I<reply>, I<both>; for
649 I<connbytes-mode>: I<packets>, I<bytes>, I<avgpkt>.
653 Allows you to restrict the number of parallel TCP connections to a
654 server per client IP address (or address block).
656 mod connlimit connlimit-above 4 REJECT;
657 mod connlimit connlimit-above !4 ACCEPT;
658 mod connlimit connlimit-above 4 connlimit-mask 24 REJECT;
662 Check the mark field associated with the connection, set by the
665 mod connmark mark 64;
666 mod connmark mark 6/7;
670 Check connection tracking information.
672 mod conntrack ctstate (ESTABLISHED RELATED);
673 mod conntrack ctproto tcp;
674 mod conntrack ctorigsrc 192.168.0.2;
675 mod conntrack ctorigdst 1.2.3.0/24;
676 mod conntrack ctorigsrcport 67;
677 mod conntrack ctorigdstport 22;
678 mod conntrack ctreplsrc 2.3.4.5;
679 mod conntrack ctrepldst ! 3.4.5.6;
680 mod conntrack ctstatus ASSURED;
681 mod conntrack ctexpire 60;
682 mod conntrack ctexpire 180:240;
684 Type "iptables -m conntrack -h" for details.
688 Check DCCP (Datagram Congestion Control Protocol) specific attributes.
689 This module is automatically loaded when you use "protocol dccp".
691 proto dccp sport 1234 dport 2345 ACCEPT;
692 proto dccp dccp-types (SYNCACK ACK) ACCEPT;
693 proto dccp dccp-types !REQUEST DROP;
694 proto dccp dccp-option 2 ACCEPT;
698 Match the 6 bit DSCP field within the TOS field.
701 mod dscp dscp-class AF41;
705 Match the ECN bits of an IPv4 TCP header.
709 mod ecn ecn-ip-ect 2;
711 Type "iptables -m ecn -h" for details.
715 Checks the SPI header in an ESP packet.
717 mod esp espspi 0x101;
718 mod esp espspi ! 0x200:0x2ff;
722 "This module matches the EUI-64 part of a stateless autoconfigured
723 IPv6 address. It compares the EUI-64 derived from the source MAC
724 address in Ehternet frame with the lower 64 bits of the IPv6 source
725 address. But "Universal/Local" bit is not compared. This module
726 doesn't match other link layer frame, and is only valid in the
727 PREROUTING, INPUT and FORWARD chains."
733 "This module matches a rate limit based on a fuzzy logic controller [FLC]."
735 mod fuzzy lower-limit 10 upper-limit 20 ACCEPT;
739 Matches the Hop-by-Hop Options header (ip6).
741 mod hbh hbh-len 8 ACCEPT;
742 mod hbh hbh-len !8 ACCEPT;
743 mod hbh hbh-opts (1:4 2:8) ACCEPT;
747 Matches the Hop Limit field (ip6).
749 mod hl hl-eq (8 10) ACCEPT;
750 mod hl hl-eq !5 ACCEPT;
751 mod hl hl-gt 15 ACCEPT;
752 mod hl hl-lt 2 ACCEPT;
756 Checks which conntrack helper module tracks this connection. The port
757 may be specified with "-portnr".
759 mod helper helper irc ACCEPT;
760 mod helper helper ftp-21 ACCEPT;
764 Check ICMP specific attributes. This module is automatically loaded
765 when you use "protocol icmp".
767 proto icmp icmp-type echo-request ACCEPT;
769 This option can also be used in be I<ip6> domain, although this is
770 called B<icmpv6> in F<ip6tables>.
772 Use "iptables -p icmp C<-h>" to obtain a list of valid ICMP types.
776 Match a range of IPv4 addresses.
778 mod iprange src-range 192.168.2.0-192.168.3.255;
779 mod iprange dst-range ! 192.168.6.0-192.168.6.255;
783 Match on IPv4 header options like source routing, record route,
784 timestamp and router-alert.
786 mod ipv4options ssrr ACCEPT;
787 mod ipv4options lsrr ACCEPT;
788 mod ipv4options no-srr ACCEPT;
789 mod ipv4options !rr ACCEPT;
790 mod ipv4options !ts ACCEPT;
791 mod ipv4options !ra ACCEPT;
792 mod ipv4options !any-opt ACCEPT;
796 Matches the IPv6 extension header (ip6).
798 mod ipv6header header !(hop frag) ACCEPT;
799 mod ipv6header header (auth dst) ACCEPT;
803 Similar to 'mod limit', but adds the ability to add per-destination or
804 per-port limits managed in a hash table.
806 mod hashlimit hashlimit 10/minute hashlimit-burst 30/minute
807 hashlimit-mode dstip hashlimit-name foobar ACCEPT;
809 Possible values for hashlimit-mode: dstip dstport srcip srcport.
811 There are more possible settings, type "iptables -m hashlimit -h" for
816 Check the package length.
818 mod length length 128; # exactly 128 bytes
819 mod length length 512:768; # range
820 mod length length ! 256; # negated
824 Limits the packet rate.
826 mod limit limit 1/second;
827 mod limit limit 15/minute limit-burst 10;
829 Type "iptables -m limit -h" for details.
833 Match the source MAC address.
835 mod mac mac-source 01:23:45:67:89;
839 Matches packets based on their netfilter mark field. This may be a 32
840 bit integer between 0 and 4294967295.
846 Matches the mobility header (domain I<ip6>).
848 proto mh mh-type binding-update ACCEPT;
852 Match a set of source or destination ports (UDP and TCP only).
854 mod multiport source-ports (https ftp);
855 mod multiport destination-ports (mysql domain);
857 This rule has a big advantage over "dport" and "sport": it generates
858 only one rule for up to 15 ports instead of one rule for every port.
862 Match every 'n'th packet.
865 mod nth counter 5 every 2;
866 mod nth start 2 every 3;
867 mod nth start 5 packet 2 every 6;
869 Type "iptables -m nth -h" for details.
873 Check information about the packet creator, namely user id, group id,
874 process id, session id and command name.
876 mod owner uid-owner 0;
877 mod owner gid-owner 1000;
878 mod owner pid-owner 5432;
879 mod owner sid-owner 6543;
880 mod owner cmd-owner "sendmail";
882 ("cmd-owner", "pid-owner" and "sid-owner" require special kernel
883 patches not included in the vanilla Linux kernel)
887 Matches the physical device on which a packet entered or is about to
888 leave the machine. This is useful for bridged interfaces.
890 mod physdev physdev-in ppp1;
891 mod physdev physdev-out eth2;
892 mod physdev physdev-is-in;
893 mod physdev physdev-is-out;
894 mod physdev physdev-is-bridged;
898 Check the link-layer packet type.
900 mod pkttype pkt-type unicast;
901 mod pkttype pkt-type broadcase;
902 mod pkttype pkt-type multicast;
906 Matches IPsec policy being applied to this packet.
908 mod policy dir out pol ipsec ACCEPT;
909 mod policy strict reqid 23 spi 0x10 proto ah ACCEPT;
910 mod policy mode tunnel tunnel-src 192.168.1.2 ACCEPT;
911 mod policy mode tunnel tunnel-dst 192.168.2.1 ACCEPT;
912 mod policy strict next reqid 24 spi 0x11 ACCEPT;
914 Note that the keyword I<proto> is also used as a shorthand version of
915 I<protocol> (built-in match module). You can fix this conflict by
916 always using the long keyword I<protocol>.
920 Detect TCP/UDP port scans.
922 mod psd psd-weight-threshold 21 psd-delay-threshold 300
923 psd-lo-ports-weight 3 psd-hi-ports-weight 1 DROP;
927 Implements network quotas by decrementing a byte counter with each packet.
929 mod quota quota 65536 ACCEPT;
933 Match a random percentage of all packets.
935 mod random average 70;
939 Match the routing realm. Useful in environments using BGP.
945 Temporarily mark source IP addresses.
948 mod recent rcheck seconds 60;
949 mod recent set rsource name "badguy";
950 mod recent set rdest;
951 mod recent rcheck rsource name "badguy" seconds 60;
952 mod recent update seconds 120 hitcount 3 rttl;
954 This netfilter module has a design flaw: although it is implemented as
955 a match module, it has target-like behaviour when using the "set"
958 L<http://snowman.net/projects/ipt_recent/>
962 Match the IPv6 routing header (ip6 only).
964 mod rt rt-type 2 rt-len 20 ACCEPT;
965 mod rt rt-type !2 rt-len !20 ACCEPT;
966 mod rt rt-segsleft 2:3 ACCEPT;
967 mod rt rt-segsleft !4:5 ACCEPT;
968 mod rt rt-0-res rt-0-addrs (::1 ::2) rt-0-not-strict ACCEPT;
972 Check SCTP (Stream Control Transmission Protocol) specific attributes.
973 This module is automatically loaded when you use "protocol sctp".
975 proto sctp sport 1234 dport 2345 ACCEPT;
976 proto sctp chunk-types only DATA:Be ACCEPT;
977 proto sctp chunk-types any (INIT INIT_ACK) ACCEPT;
978 proto sctp chunk-types !all (HEARTBEAT) ACCEPT;
980 Use "iptables -p sctp C<-h>" to obtain a list of valid chunk types.
984 Checks the source or destination IP/Port/MAC against a set.
986 mod set set badguys src DROP;
988 See L<http://ipset.netfilter.org/> for more information.
992 Checks the connection tracking state.
994 mod state state INVALID DROP;
995 mod state state (ESTABLISHED RELATED) ACCEPT;
997 Type "iptables -m state -h" for details.
1001 Successor of B<nth> and B<random>, currently undocumented in the
1002 iptables(8) man page.
1004 mod statistic mode random probability 0.8 ACCEPT;
1005 mod statistic mode nth every 5 packet 0 DROP;
1011 mod string string "foo bar" ACCEPT;
1012 mod string algo kmp from 64 to 128 hex-string "deadbeef" ACCEPT;
1016 Checks TCP specific attributes. This module is automatically loaded
1017 when you use "protocol tcp".
1019 proto tcp sport 1234;
1020 proto tcp dport 2345;
1021 proto tcp tcp-flags (SYN ACK) SYN;
1022 proto tcp tcp-flags ! (SYN ACK) SYN;
1023 proto tcp tcp-flags ALL (RST ACK);
1025 proto tcp tcp-option 2;
1028 Type "iptables -p tcp -h" for details.
1032 Check the TCP MSS field of a SYN or SYN/ACK packet.
1034 mod tcpmss mss 123 ACCEPT;
1035 mod tcpmss mss 234:567 ACCEPT;
1039 Check if the time a packet arrives is in given range.
1041 mod time timestart 12:00;
1042 mod time timestop 13:30;
1043 mod time days (Mon Wed Fri);
1044 mod time datestart 2005:01:01;
1045 mod time datestart 2005:01:01:23:59:59;
1046 mod time datestop 2005:04:01;
1047 mod time monthday (30 31);
1048 mod time weekdays (Wed Thu);
1049 mod time timestart 12:00 utc;
1050 mod time timestart 12:00 localtz;
1052 Type "iptables -m time -h" for details.
1056 Matches a packet on the specified TOS-value.
1058 mod tos tos Minimize-Cost ACCEPT;
1059 mod tos tos !Normal-Service ACCEPT;
1061 Type "iptables -m tos -h" for details.
1065 Matches the ttl (time to live) field in the IP header.
1067 mod ttl ttl-eq 12; # ttl equals
1068 mod ttl ttl-gt 10; # ttl greater than
1069 mod ttl ttl-lt 16; # ttl less than
1073 Compares raw data from the packet. You can specify more than one
1074 filter in a ferm list; these are not expanded into multiple rules.
1076 mod u32 u32 '6&0xFF=1' ACCEPT;
1077 mod u32 u32 ('27&0x8f=7' '31=0x527c4833') DROP;
1081 Matches packets which seem malformed or unusual. This match has no
1087 =head2 iptables target modules
1089 The following additional targets are available in ferm, provided that
1090 you enabled them in your kernel:
1098 CLASSIFY set-class 3:50;
1102 Configure a simple cluster of nodes that share a certain IP and MAC
1103 address. Connections are statically distributed between the nodes.
1105 CLUSTERIP new hashmode sourceip clustermac 00:12:34:45:67:89
1106 total-nodes 4 local-node 2 hash-init 12345;
1110 Sets the netfilter mark value associated with a connection.
1112 CONNMARK set-mark 42;
1114 CONNMARK restore-mark;
1115 CONNMARK save-mark mask 0x7fff;
1116 CONNMARK restore-mark mask 0x8000;
1118 =item B<CONNSECMARK>
1120 This module copies security markings from packets to connections (if
1121 unlabeled), and from connections back to packets (also only if
1122 unlabeled). Typically used in conjunction with SECMARK, it is only
1123 valid in the mangle table.
1126 CONNSECMARK restore;
1128 =item B<DNAT to [ip-address|ip-range|ip-port-range]>
1130 Change the destination address of the packet.
1133 DNAT to 10.0.0.4:80;
1134 DNAT to 10.0.0.4:1024-2048;
1135 DNAT to 10.0.1.1-10.0.1.20;
1139 This target allows to selectively work around known ECN blackholes.
1140 It can only be used in the mangle table.
1146 Modify the IPv6 Hop Limit field (ip6/mangle only).
1152 =item B<IPV4OPTSSTRIP>
1154 Strip all the IP options from a packet. This module does not take any
1161 Log all packets that match this rule in the kernel log. Be carefull
1162 with log flooding. Note that this is a "non-terminating target",
1163 i.e. rule traversal continues at the next rule.
1165 LOG log-level warning log-prefix "Look at this: ";
1166 LOG log-tcp-sequence log-tcp-options;
1171 Sets the netfilter mark field for the packet (a 32 bit integer between
1182 Masquerades matching packets. Optionally followed by a port or
1183 port-range for iptables. Specify as "123", "123-456" or "123:456".
1184 The port range parameter specifies what local ports masqueraded
1185 connections should originate from.
1188 MASQUERADE to-ports 1234:2345;
1189 MASQUERADE to-ports 1234:2345 random;
1193 Experimental demonstration target which inverts the source and
1194 destination fields in the IP header.
1200 Map a whole network onto another network in the B<nat> table.
1202 NETMAP to 192.168.2.0/24;
1206 Disable connection tracking for all packets matching that rule.
1208 proto tcp dport (135:139 445) NOTRACK;
1212 Log packets over netlink; this is the successor of I<ULOG>.
1214 NFLOG nflog-group 5 nflog-prefix "Look at this: ";
1215 NFLOG nflog-range 256;
1216 NFLOG nflog-threshold 10;
1220 Userspace queueing, requires nfnetlink_queue kernel support.
1222 proto tcp dport ftp NFQUEUE queue-num 20;
1226 Userspace queueing, the predecessor to B<NFQUEUE>. All packets go to
1229 proto tcp dport ftp QUEUE;
1231 =item B<REDIRECT to-ports [ports]>
1233 Transparent proxying: alter the destination IP of the packet to the
1236 proto tcp dport http REDIRECT to-ports 3128;
1237 proto tcp dport http REDIRECT to-ports 3128 random;
1241 Similar to SNAT, but a client is mapped to the same source IP for all
1244 SAME to 1.2.3.4-1.2.3.7;
1245 SAME to 1.2.3.8-1.2.3.15 nodst;
1246 SAME to 1.2.3.16-1.2.3.31 random;
1250 This is used to set the security mark value associated with the packet
1251 for use by security subsystems such as SELinux. It is only valid in
1254 SECMARK selctx "system_u:object_r:httpd_packet_t:s0";
1256 =item B<SET [add-set|del-set] [setname] [flag(s)]>
1258 Add the IP to the specified set. See L<http://ipset.netfilter.org/>
1260 proto icmp icmp-type echo-request SET add-set badguys src;
1262 =item B<SNAT to [ip-address|ip-range|ip-port-range]>
1264 Change the source address of the packet.
1267 SNAT to 1.2.3.4:20000-30000;
1268 SNAT to 1.2.3.4 random;
1272 Alter the MSS value of TCP SYN packets.
1274 TCPMSS set-mss 1400;
1275 TCPMSS clamp-mss-to-pmtu;
1277 =item B<TOS set-tos [value]>
1279 Set the tcp package Type Of Service bit to this value. This will be
1280 used by whatever traffic scheduler is willing to, mostly your own
1281 linux-machine, but maybe more. The original tos-bits are blanked and
1282 overwritten by this value.
1284 TOS set-tos Maximize-Throughput;
1289 Type "iptables -j TOS -h" for details.
1293 Modify the TTL header field.
1296 TTL ttl-dec 1; # decrease by 1
1297 TTL ttl-inc 4; # increase by 4
1301 Log packets to a userspace program.
1303 ULOG ulog-nlgroup 5 ulog-prefix "Look at this: ";
1304 ULOG ulog-cprange 256;
1305 ULOG ulog-qthreshold 10;
1309 =head1 OTHER DOMAINS
1311 Since version 2.0, B<ferm> supports not only I<ip> and I<ip6>, but
1312 also I<arp> (ARP tables) and I<eb> (ethernet bridging tables). The
1313 concepts are similar to I<iptables>.
1315 =head2 arptables keywords
1319 =item B<source-ip>, B<destination-ip>
1321 Matches the source or destination IPv4 address. Same as B<saddr> and
1322 B<daddr> in the I<ip> domain.
1324 =item B<source-mac>, B<destination-mac>
1326 Matches the source or destination MAC address.
1328 =item B<interface>, B<outerface>
1330 Input and output interface.
1334 Hardware length of the packet.
1336 chain INPUT h-length 64 ACCEPT;
1340 Operation code, for details see the iptables(8).
1354 proto-type 0x800 ACCEPT;
1358 The keywords B<mangle-ip-s>, B<mangle-ip-d>, B<mangle-mac-s>,
1359 B<mangle-mac-d>, B<mangle-target> may be used for ARP mangling. See
1360 iptables(8) for details.
1364 =head2 ebtables keywords
1370 Matches the protocol which created the frame, e.g. I<IPv4> or B<PPP>.
1371 For a list, see F</etc/ethertypes>.
1373 =item B<interface>, B<outerface>
1375 Physical input and output interface.
1377 =item B<logical-in>, B<logical-out>
1379 The logical bridge interface.
1381 =item B<saddr>, B<daddr>
1383 Matches source or destination MAC address.
1385 =item B<Match modules>
1387 The following match modules are supported: 802.3, arp, ip, mark_m,
1388 pkttype, stp, vlan, log.
1390 =item B<Target extensions>
1392 The following target extensions are supported: arpreply, dnat, mark,
1395 Please note that there is a conflict between I<--mark> from the
1396 I<mark_m> match module and I<-j mark>. Since both would be
1397 implemented with the ferm keyword B<mark>, we decided to solve this by
1398 writing the target's name in uppercase, like in the other domains.
1399 The following example rewrites mark 1 to 2:
1405 =head1 ADVANCED FEATURES
1409 In complex firewall files, it is helpful to use variables, e.g. to
1410 give a network interface a meaningful name.
1412 To set variables, write:
1414 @def $DEV_INTERNET = eth0;
1415 @def $PORTS = (http ftp);
1416 @def $MORE_PORTS = ($PORTS 8080);
1418 In the real ferm code, variables are used like any other keyword
1421 chain INPUT interface $DEV_INTERNET proto tcp dport $MORE_PORTS ACCEPT;
1423 Note that variables can only be used in keyword parameters
1424 ("192.168.1.1", "http"); they cannot contain ferm keywords like
1425 "proto" or "interface".
1427 Variables are only valid in the current block:
1429 @def $DEV_INTERNET = eth1;
1432 @def $DEV_INTERNET = ppp0;
1433 interface $DEV_INTERNET dport http ACCEPT;
1435 interface $DEV_INTERNET DROP;
1438 will be expanded to:
1442 interface ppp0 dport http ACCEPT;
1444 interface eth1 DROP;
1447 The "def $DEV_INTERNET = ppp0" is only valid in the "proto tcp" block;
1448 the parent block still knows "set $DEV_INTERNET = eth1".
1450 Include files are special - variables declared in an included file are
1451 still available in the calling block. This is useful when you include
1452 a file which only declares variables.
1454 =head2 Automatic variables
1456 Some variables are set internally by ferm. Ferm scripts can use them
1457 just like any other variable.
1463 The name of the configuration file relative to the directory ferm was
1468 The base name of the configuration file.
1472 The directory of the configuration file.
1476 The current domain. One of I<ip>, I<ip6>, I<arp>, I<eb>.
1480 The current netfilter table.
1484 The current netfilter chain.
1488 The line of the current script. It can be used like this:
1491 LOG log-prefix "rule=$msg:$LINE ";
1496 &log("log message");
1502 Functions are similar to variables, except that they may have
1503 parameters, and they provide ferm commands, not values.
1505 @def &FOO() = proto (tcp udp) dport domain;
1508 @def &TCP_TUNNEL($port, $dest) = {
1509 table filter chain FORWARD interface ppp0 proto tcp dport $port daddr $dest outerface eth0 ACCEPT;
1510 table nat chain PREROUTING interface ppp0 proto tcp dport $port daddr 1.2.3.4 DNAT to $dest;
1513 &TCP_TUNNEL(http, 192.168.1.33);
1514 &TCP_TUNNEL(ftp, 192.168.1.30);
1515 &TCP_TUNNEL((ssh smtp), 192.168.1.2);
1517 A function call which contains a block (like '{...}') must be the last
1518 command in a ferm rule, i.e. it must be followed by ';'. The '&FOO()'
1519 example does not contain a block, thus you may write 'ACCEPT' after
1520 the call. To circumvent this, you can reorder the keywords:
1522 @def &IPSEC() = { proto (esp ah); proto udp dport 500; }
1523 chain INPUT ACCEPT &IPSEC();
1527 With backticks, you may use the output of an external command:
1529 @def $DNSSERVERS = `grep nameserver /etc/resolv.conf | awk '{print $2}'`;
1530 chain INPUT proto tcp saddr $DNSSERVERS ACCEPT;
1532 The command is executed with the shell (F</bin/sh>), just like
1533 backticks in perl. ferm does not do any variable expansion here.
1535 The output is then tokenized, and saved as a ferm list (array). Lines
1536 beginning with '#' are ignored; the other lines may contain any number
1537 of values, separated by whitespace.
1541 The B<@include> keyword allows you to include external files:
1543 @include 'vars.ferm';
1545 The file name is relative to the calling file, e.g. when including
1546 from F</etc/ferm/ferm.conf>, the above statement includes
1547 F</etc/ferm/vars.ferm>. Variables and functions declared in an
1548 included file are still available in the calling file.
1550 B<include> works within a block:
1553 @include 'input.ferm';
1556 If you specify a directory (with a trailing '/'), all files in this
1557 directory are included, sorted alphabetically:
1561 With a trailing pipe symbol, B<ferm> executes a program and parses its
1564 @include '/root/generate_ferm_rules.sh $HOSTNAME|'
1568 The keyword B<@if> introduces a conditional expression:
1570 @if $condition DROP;
1572 A value is evaluated true just like in Perl: zero, empty list, empty
1573 string are false, everything else is true. Examples for true values:
1575 (a b); 1; 'foo'; (0 0)
1577 Examples for false values:
1581 There is also B<@else>:
1583 @if $condition DROP; @else REJECT;
1585 Note the semicolon before the B<@else>.
1587 It is possible to use curly braces after either B<@if> or B<@else>:
1596 Since the closing curly brace also finishes the command, there is no
1599 There is no B<@elsif>, use B<@else @if> instead.
1603 @def $have_ipv6 = `test -f /proc/net/ip6_tables_names && echo 1 || echo`;
1612 To run custom commands, you may install hooks:
1614 @hook pre "echo 0 >/proc/sys/net/ipv4/conf/eth0/forwarding";
1615 @hook post "echo 1 >/proc/sys/net/ipv4/conf/eth0/forwarding";
1616 @hook flush "echo 0 >/proc/sys/net/ipv4/conf/eth0/forwarding";
1618 The specified command is executed using the shell. "pre" means run
1619 the command before applying the firewall rules, and "post" means run
1620 the command afterwards. "flush" hooks are run after ferm has flushed
1621 the firewall rules (option --flush). You may install any number of
1624 =head1 BUILT-IN FUNCTIONS
1626 There are several built-in functions which you might find useful.
1630 Tests two values for equality. Example:
1632 @if @eq($DOMAIN, ip6) DROP;
1636 Similar to @eq, this tests for non-equality.
1640 Negates a boolean value.
1642 =head2 @resolve((hostname1 hostname2 ...), [type])
1644 Usually, host names are resolved by iptables. To let ferm resolve
1645 host names, use the function @resolve:
1647 saddr @resolve(my.host.foo) proto tcp dport ssh ACCEPT;
1648 saddr @resolve((another.host.foo third.host.foo)) proto tcp dport openvpn ACCEPT;
1649 daddr @resolve(ipv6.google.com, AAAA) proto tcp dport http ACCEPT;
1651 Note the double parentheses in the second line: the inner pair for
1652 creating a ferm list, and the outer pair as function parameter
1655 The second parameter is optional, and specifies the DNS record type.
1658 Be careful with resolved host names in firewall configuration. DNS
1659 requests may block the firewall configuration for a long time, leaving
1660 the machine vulnerable, or they may fail.
1662 =head2 @cat(a, b, ...)
1664 Concatenate all parameters into one string.
1666 =head2 @substr(expression, offset, length)
1668 Extracts a substring out of expression and returns it. First
1669 character is at offset 0. If OFFSET is negative, starts that far from
1670 the end of the string.
1672 =head2 @length(expression)
1674 Returns the length in characters of the value of EXPR.
1676 =head2 @basename(path)
1678 Return the base name of the file for a given path
1679 (File::Spec::splitpath).
1681 =head2 @dirname(path)
1683 Return the name of the last directory for a given path, assuming the
1684 last component is a file name (File::Spec::splitpath).
1686 =head2 @ipfilter(list)
1688 Filters out the IP addresses that obviously do not match the current
1689 domain. That is useful to create common variables and rules for IPv4
1692 @def $TRUSTED_HOSTS = (192.168.0.40 2001:abcd:ef::40);
1694 domain (ip ip6) chain INPUT {
1695 saddr @ipfilter($TRUSTED_HOSTS) proto tcp dport ssh ACCEPT;
1700 The F<./examples/> directory contains numerous ferm configuration
1701 which can be used to begin a new firewall. This sections contains more
1702 samples, recipes and tricks.
1704 =head2 Easy port forwarding
1706 Ferm function make routine tasks quick and easy:
1708 @def &FORWARD_TCP($proto, $port, $dest) = {
1709 table filter chain FORWARD interface $DEV_WORLD outerface $DEV_DMZ daddr $dest proto $proto dport $port ACCEPT;
1710 table nat chain PREROUTING interface $DEV_WORLD daddr $HOST_STATIC proto $proto dport $port DNAT to $dest;
1713 &FORWARD_TCP(tcp, http, 192.168.1.2);
1714 &FORWARD_TCP(tcp, smtp, 192.168.1.3);
1715 &FORWARD_TCP((tcp udp), domain, 192.168.1.4);
1717 =head2 Remote B<ferm>
1719 If the target machine is not able to run B<ferm> for some reason
1720 (maybe an embedded device without Perl), you can edit the B<ferm>
1721 configuration file on another computer and let B<ferm> generate a
1724 Example for OpenWRT:
1726 ferm --remote --shell mywrt/ferm.conf >mywrt/firewall.user
1727 chmod +x mywrt/firewall.user
1728 scp mywrt/firewall.user mywrt.local.net:/etc/
1729 ssh mywrt.local.net /etc/firewall.user
1737 Do not execute the iptables(8) commands, but skip instead. This way
1738 you can parse your data, use B<--lines> to view the output.
1742 Clears the firewall rules and sets the policy of all chains to ACCEPT.
1743 B<ferm> needs a configuration file for that to determine which domains
1744 and tables are affected.
1748 Show the firewall lines that were generated from the rules. They
1749 will be shown just before they are executed, so if you get error
1750 messages from iptables(8) etc., you can see which rule caused
1753 =item B<--interactive>
1755 Apply the firewall rules and ask the user for confirmation. Reverts
1756 to the previous ruleset if there is no valid user response within 30
1757 seconds. This is useful for remote firewall administration: you can
1758 test the rules without fearing to lock yourself out.
1762 Show a brief list of available commandline options.
1766 Shows the version number of the program.
1770 Enable fast mode: ferm generates an iptables-save(8) file, and
1771 installs it with iptables-restore(8). This is much faster, because
1772 ferm calls iptables(8) once for every rule by default.
1774 Fast mode is enabled by default since B<ferm> 2.0, deprecating this
1779 Disable fast mode, i.e. run iptables(8) for every rule, and don't use
1780 iptables-restore(8).
1784 Generate a shell script which calls iptables-restore(8) and prints it.
1785 Implies --fast --lines.
1789 Generate rules for a remote machine. Implies B<--noexec> and
1790 B<--lines>. Can be combined with B<--shell>.
1792 =item B<--domain {ip|ip6}>
1794 Handle only the specified domain. B<ferm> output may be empty if the
1795 domain is not configured in the input file.
1797 =item B<--def '$name=value'>
1799 Override a variable defined in the configuration file.
1811 =head2 Operating system
1813 Linux 2.4 or newer, with netfilter support and all netfilter modules
1814 used by your firewall script
1818 iptables and perl 5.6
1824 If you find a bug, please tell us: ferm@foo-projects.org
1828 Copyright (C) 2001-2011 Max Kellermann <max@foo-projects.org>, Auke
1829 Kok <sofar@foo-projects.org>
1831 This program is free software; you can redistribute it and/or modify
1832 it under the terms of the GNU General Public License as published by
1833 the Free Software Foundation; either version 2 of the License, or (at
1834 your option) any later version.
1836 This program is distributed in the hope that it will be useful, but
1837 WITHOUT ANY WARRANTY; without even the implied warranty of
1838 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1839 General Public License for more details.
1841 You should have received a copy of the GNU General Public License
1842 along with this program; if not, write to the Free Software
1843 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
1848 Max Kellermann <max@foo-projects.org>, Auke Kok
1849 <sofar@foo-projects.org>