6 # ferm, a firewall setup program that makes firewall rules easy!
8 # Copyright (C) 2001-2007 Auke Kok, Max Kellermann
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 You can achieve the same by explicitly declaring a custom chain, but
446 you may feel that using B<@subchain> requires less typing.
452 =head2 Basic iptables match keywords
456 =item B<interface [interface-name]>
458 Define the interface name, your outside network card, like eth0,
459 or dialup like ppp1, or whatever device you want to match for
460 passing packets. It is equivalent to the C<-i> switch in
463 =item B<outerface [interface-name]>
465 Same as interface, only for matching the outgoing interface
466 for a packet, as in iptables(8).
468 =item B<protocol [protocol-name|protocol-number]>
470 Currently supported by the kernel are tcp, udp and icmp, or
471 their respective numbers.
473 =item B<saddr|daddr [address-spec]>
475 Matches on packets originating from the specified address (saddr) or
476 targeted at the address (daddr).
480 saddr 192.168/8 ACCEPT; # (identical to the next one:)
481 saddr 192.168.0.0/255.255.255.0 ACCEPT;
482 daddr my.domain.com ACCEPT;
486 Specify that only fragmented IP packets should be matched.
487 When packets are larger that the maximum packet size your
488 system can handle (called Maximum Transmission Unit or MTU)
489 they will be chopped into bits and sent one by one as single
490 packets. See ifconfig(8) if you want to find the MTU for
491 your system (the default is usually 1500 bytes).
493 Fragments are frequently used in DOS attacks, because there
494 is no way of finding out the origin of a fragment packet.
496 =item B<sport|dport [port-spec]>
498 Matches on packets on the specified TCP or UDP port. "sport" matches
499 the source port, and dport matches the destination port.
501 This match can be used only after you specified "protocol tcp" or
502 "protocol udp", because only these two protocols actually have ports.
504 And some examples of valid ports/ranges:
508 dport ssh:http ACCEPT;
509 dport 0:1023 ACCEPT; # equivalent to :1023
510 dport 1023:65535 ACCEPT;
514 Specify that the SYN flag in a tcp package should be matched,
515 which are used to build new tcp connections. You can identify
516 incoming connections with this, and decide wether you want
517 to allow it or not. Packets that do not have this flag are
518 probably from an already established connection, so it's
519 considered reasonably safe to let these through.
521 =item B<module [module-name]>
523 Load an iptables module. Most modules provide more match
524 keywords. We'll get to that later.
529 =head2 Basic target keywords
533 =item B<jump [custom-chain-name]>
535 Jumps to a custom chain. If no rule in the custom chain matched,
536 netfilter returns to the next rule in the previous chain.
538 =item B<realgoto [custom-chain-name]>
540 Go to a custom chain. Unlike the B<jump> option, B<RETURN> will not
541 continue processing in this chain but instead in the chain that called
544 The keyword B<realgoto> was chosen during the transition period,
545 because B<goto> (already deprecated) used to be an alias for B<jump>.
549 Accepts matching packets.
553 Drop matching packets without further notice.
557 Rejects matching packets, i.e. send an ICMP packet to the sender,
558 which is port-unreachable by default. You may specify another ICMP
561 REJECT; # default to icmp-port-unreachable
562 REJECT reject-with icmp-net-unreachable;
564 Type "iptables -j REJECT -h" for details.
568 Finish the current chain and return to the calling chain (if "jump
569 [custom-chain-name]" was used).
578 =head1 ADDITIONAL KEYWORDS
580 Netfilter is modular. Modules may provide additional targets and match
581 keywords. The list of netfilter modules is constantly growing, and
582 ferm tries to keep up with supporting them all. This chapter describes
583 modules which are currently supported.
586 =head2 iptables match modules
592 Account traffic for all hosts in defined network/netmask. This is one
593 of the match modules which behave like a target, i.e. you will mostly
594 have to use the B<NOP> target.
596 mod account aname mynetwork aaddr 192.168.1.0/24 ashort NOP;
600 Check the address type; either source address or destination address.
602 mod addrtype src-type BROADCAST;
603 mod addrtype dst-type LOCAL;
605 Type "iptables -m addrtype -h" for details.
609 Checks the SPI header in an AH packet.
612 mod ah ahspi ! 0x200:0x2ff;
614 Additional arguments for IPv6:
616 mod ah ahlen 32 ACCEPT;
617 mod ah ahlen !32 ACCEPT;
622 Adds a comment of up to 256 characters to a rule, without an effect.
623 Note that unlike ferm comments ('#'), this one will show up in
626 mod comment comment "This is my comment." ACCEPT;
630 Matches if a value in /proc/net/ipt_condition/NAME is 1 (path is
631 /proc/net/ip6t_condition/NAME for the ip6 domain).
633 mod condition condition (abc def) ACCEPT;
634 mod condition condition !foo ACCEPT;
638 Match by how many bytes or packets a connection (or one of the two
639 flows constituting the connection) have tranferred so far, or by
640 average bytes per packet.
642 mod connbytes connbytes 65536: connbytes-dir both connbytes-mode bytes ACCEPT;
643 mod connbytes connbytes !1024:2048 connbytes-dir reply connbytes-mode packets ACCEPT;
645 Valid values for I<connbytes-dir>: I<original>, I<reply>, I<both>; for
646 I<connbytes-mode>: I<packets>, I<bytes>, I<avgpkt>.
650 Allows you to restrict the number of parallel TCP connections to a
651 server per client IP address (or address block).
653 mod connlimit connlimit-above 4 REJECT;
654 mod connlimit connlimit-above !4 ACCEPT;
655 mod connlimit connlimit-above 4 connlimit-mask 24 REJECT;
659 Check the mark field associated with the connection, set by the
662 mod connmark mark 64;
663 mod connmark mark 6/7;
667 Check connection tracking information.
669 mod conntrack ctstate (ESTABLISHED RELATED);
670 mod conntrack ctproto tcp;
671 mod conntrack ctorigsrc 192.168.0.2;
672 mod conntrack ctorigdst 1.2.3.0/24;
673 mod conntrack ctreplsrc 2.3.4.5;
674 mod conntrack ctrepldst ! 3.4.5.6;
675 mod conntrack ctstatus ASSURED;
676 mod conntrack ctexpire 60;
677 mod conntrack ctexpire 180:240;
679 Type "iptables -m conntrack -h" for details.
683 Check DCCP (Datagram Congestion Control Protocol) specific attributes.
684 This module is automatically loaded when you use "protocol dccp".
686 proto dccp sport 1234 dport 2345 ACCEPT;
687 proto dccp dccp-types (SYNCACK ACK) ACCEPT;
688 proto dccp dccp-types !REQUEST DROP;
689 proto dccp dccp-option 2 ACCEPT;
693 Match the 6 bit DSCP field within the TOS field.
696 mod dscp dscp-class AF41;
700 Matches the Destination Options header (ip6).
702 mod dst dst-len 8 ACCEPT;
703 mod dst dst-len !8 ACCEPT;
704 mod dst dst-opts (1:4 2:8) ACCEPT;
708 Match the ECN bits of an IPv4 TCP header.
712 mod ecn ecn-ip-ect 2;
714 Type "iptables -m ecn -h" for details.
718 Checks the SPI header in an ESP packet.
720 mod esp espspi 0x101;
721 mod esp espspi ! 0x200:0x2ff;
725 "This module matches the EUI-64 part of a stateless autoconfigured
726 IPv6 address. It compares the EUI-64 derived from the source MAC
727 address in Ehternet frame with the lower 64 bits of the IPv6 source
728 address. But "Universal/Local" bit is not compared. This module
729 doesn't match other link layer frame, and is only valid in the
730 PREROUTING, INPUT and FORWARD chains."
736 Matches the Fragment header (ip6).
738 mod frag fragid 123:456 ACCEPT;
739 mod frag fragid !123:456 ACCEPT;
740 mod frag fragres ACCEPT;
741 mod frag fragfirst ACCEPT;
742 mod frag fragmore ACCEPT;
743 mod frag fraglast ACCEPT;
747 "This module matches a rate limit based on a fuzzy logic controller [FLC]."
749 mod fuzzy lower-limit 10 upper-limit 20 ACCEPT;
753 Matches the Hop-by-Hop Options header (ip6).
755 mod hbh hbh-len 8 ACCEPT;
756 mod hbh hbh-len !8 ACCEPT;
757 mod hbh hbh-opts (1:4 2:8) ACCEPT;
761 Matches the Hop Limit field (ip6).
763 mod hl hl-eq (8 10) ACCEPT;
764 mod hl hl-eq !5 ACCEPT;
765 mod hl hl-gt 15 ACCEPT;
766 mod hl hl-lt 2 ACCEPT;
770 Checks which conntrack helper module tracks this connection. The port
771 may be specified with "-portnr".
773 mod helper helper irc ACCEPT;
774 mod helper helper ftp-21 ACCEPT;
778 Check ICMP specific attributes. This module is automatically loaded
779 when you use "protocol icmp".
781 proto icmp icmp-type echo-request ACCEPT;
783 This option can also be used in be I<ip6> domain, although this is
784 called B<icmpv6> in F<ip6tables>.
786 Use "iptables -p icmp C<-h>" to obtain a list of valid ICMP types.
790 Match a range of IPv4 addresses.
792 mod iprange src-range 192.168.2.0-192.168.3.255;
793 mod iprange dst-range ! 192.168.6.0-192.168.6.255;
797 Match on IPv4 header options like source routing, record route,
798 timestamp and router-alert.
800 mod ipv4options ssrr ACCEPT;
801 mod ipv4options lsrr ACCEPT;
802 mod ipv4options no-srr ACCEPT;
803 mod ipv4options !rr ACCEPT;
804 mod ipv4options !ts ACCEPT;
805 mod ipv4options !ra ACCEPT;
806 mod ipv4options !any-opt ACCEPT;
810 Matches the IPv6 extension header (ip6).
812 mod ipv6header header !(hop frag) ACCEPT;
813 mod ipv6header header (auth dst) ACCEPT;
817 Similar to 'mod limit', but adds the ability to add per-destination or
818 per-port limits managed in a hash table.
820 mod hashlimit hashlimit 10/minute hashlimit-burst 30/minute
821 hashlimit-mode dstip hashlimit-name foobar ACCEPT;
823 Possible values for hashlimit-mode: dstip dstport srcip srcport.
825 There are more possible settings, type "iptables -m hashlimit -h" for
830 Check the package length.
832 mod length length 128; # exactly 128 bytes
833 mod length length 512:768; # range
834 mod length length ! 256; # negated
838 Limits the packet rate.
840 mod limit limit 1/second;
841 mod limit limit 15/minute limit-burst 10;
843 Type "iptables -m limit -h" for details.
847 Match the source MAC address.
849 mod mac mac-source 01:23:45:67:89;
853 Matches packets based on their netfilter mark field. This may be a 32
854 bit integer between 0 and 4294967295.
860 Matches the mobility header (domain I<ip6>).
862 proto mh mh-type binding-update ACCEPT;
866 Match a set of source or destination ports (UDP and TCP only).
868 mod multiport source-ports (https ftp);
869 mod multiport destination-ports (mysql domain);
871 This rule has a big advantage over "dport" and "sport": it generates
872 only one rule for up to 15 ports instead of one rule for every port.
876 Match every 'n'th packet.
879 mod nth counter 5 every 2;
880 mod nth start 2 every 3;
881 mod nth start 5 packet 2 every 6;
883 Type "iptables -m nth -h" for details.
887 Check information about the packet creator, namely user id, group id,
888 process id, session id and command name.
890 mod owner uid-owner 0;
891 mod owner gid-owner 1000;
892 mod owner pid-owner 5432;
893 mod owner sid-owner 6543;
894 mod owner cmd-owner "sendmail";
896 ("cmd-owner", "pid-owner" and "sid-owner" require special kernel
897 patches not included in the vanilla Linux kernel)
901 Matches the physical device on which a packet entered or is about to
902 leave the machine. This is useful for bridged interfaces.
904 mod physdev physdev-in ppp1;
905 mod physdev physdev-out eth2;
906 mod physdev physdev-is-in;
907 mod physdev physdev-is-out;
908 mod physdev physdev-is-bridged;
912 Check the link-layer packet type.
914 mod pkttype pkt-type unicast;
915 mod pkttype pkt-type broadcase;
916 mod pkttype pkt-type multicast;
920 Matches IPsec policy being applied to this packet.
922 mod policy dir out pol ipsec ACCEPT;
923 mod policy strict reqid 23 spi 0x10 proto ah ACCEPT;
924 mod policy mode tunnel tunnel-src 192.168.1.2 ACCEPT;
925 mod policy mode tunnel tunnel-dst 192.168.2.1 ACCEPT;
926 mod policy strict next reqid 24 spi 0x11 ACCEPT;
930 Detect TCP/UDP port scans.
932 mod psd psd-weight-threshold 21 psd-delay-threshold 300
933 psd-lo-ports-weight 3 psd-hi-ports-weight 1 DROP;
937 Implements network quotas by decrementing a byte counter with each packet.
939 mod quota quota 65536 ACCEPT;
943 Match a random percentage of all packets.
945 mod random average 70;
949 Match the routing realm. Useful in environments using BGP.
955 Temporarily mark source IP addresses.
958 mod recent rcheck seconds 60;
959 mod recent set rsource name "badguy";
960 mod recent set rdest;
961 mod recent rcheck rsource name "badguy" seconds 60;
962 mod recent update seconds 120 hitcount 3 rttl;
964 This netfilter module has a design flaw: although it is implemented as
965 a match module, it has target-like behaviour when using the "set"
968 L<http://snowman.net/projects/ipt_recent/>
972 Match the IPv6 routing header (ip6 only).
974 mod rt rt-type 2 rt-len 20 ACCEPT;
975 mod rt rt-type !2 rt-len !20 ACCEPT;
976 mod rt rt-segsleft 2:3 ACCEPT;
977 mod rt rt-segsleft !4:5 ACCEPT;
978 mod rt rt-0-res rt-0-addrs (::1 ::2) rt-0-not-strict ACCEPT;
982 Check SCTP (Stream Control Transmission Protocol) specific attributes.
983 This module is automatically loaded when you use "protocol sctp".
985 proto sctp sport 1234 dport 2345 ACCEPT;
986 proto sctp chunk-types only DATA:Be ACCEPT;
987 proto sctp chunk-types any (INIT INIT_ACK) ACCEPT;
988 proto sctp chunk-types !all (HEARTBEAT) ACCEPT;
990 Use "iptables -p sctp C<-h>" to obtain a list of valid chunk types.
994 Checks the source or destination IP/Port/MAC against a set.
996 mod set set badguys src DROP;
998 See L<http://ipset.netfilter.org/> for more information.
1002 Checks the connection tracking state.
1004 mod state state INVALID DROP;
1005 mod state state (ESTABLISHED RELATED) ACCEPT;
1007 Type "iptables -m state -h" for details.
1011 Successor of B<nth> and B<random>, currently undocumented in the
1012 iptables(8) man page.
1014 mod statistic mode random probability 0.8 ACCEPT;
1015 mod statistic mode nth every 5 packet 0 DROP;
1021 mod string string "foo bar" ACCEPT;
1022 mod string algo kmp from 64 to 128 hex-string "deadbeef" ACCEPT;
1026 Checks TCP specific attributes. This module is automatically loaded
1027 when you use "protocol tcp".
1029 proto tcp sport 1234;
1030 proto tcp dport 2345;
1031 proto tcp tcp-flags (SYN ACK) SYN;
1032 proto tcp tcp-flags ! (SYN ACK) SYN;
1033 proto tcp tcp-flags ALL (RST ACK);
1035 proto tcp tcp-option 2;
1038 Type "iptables -p tcp -h" for details.
1042 Check the TCP MSS field of a SYN or SYN/ACK packet.
1044 mod tcpmss mss 123 ACCEPT;
1045 mod tcpmss mss 234:567 ACCEPT;
1049 Check if the time a packet arrives is in given range.
1051 mod time timestart 12:00;
1052 mod time timestop 13:30;
1053 mod time days (Mon Wed Fri);
1054 mod time datestart 2005:01:01;
1055 mod time datestart 2005:01:01:23:59:59;
1056 mod time datestop 2005:04:01;
1057 mod time monthday (30 31);
1058 mod time weekdays (Wed Thu);
1059 mod time timestart 12:00 utc;
1060 mod time timestart 12:00 localtz;
1062 Type "iptables -m time -h" for details.
1066 Matches a packet on the specified TOS-value.
1068 mod tos tos Minimize-Cost ACCEPT;
1069 mod tos tos !Normal-Service ACCEPT;
1071 Type "iptables -m tos -h" for details.
1075 Matches the ttl (time to live) field in the IP header.
1077 mod ttl ttl-eq 12; # ttl equals
1078 mod ttl ttl-gt 10; # ttl greater than
1079 mod ttl ttl-lt 16; # ttl less than
1083 Compares raw data from the packet. You can specify more than one
1084 filter in a ferm list; these are not expanded into multiple rules.
1086 mod u32 u32 '6&0xFF=1' ACCEPT;
1087 mod u32 u32 ('27&0x8f=7' '31=0x527c4833') DROP;
1091 Matches packets which seem malformed or unusual. This match has no
1097 =head2 iptables target modules
1099 The following additional targets are available in ferm, provided that
1100 you enabled them in your kernel:
1108 CLASSIFY set-class 3:50;
1112 Configure a simple cluster of nodes that share a certain IP and MAC
1113 address. Connections are statically distributed between the nodes.
1115 CLUSTERIP new hashmode sourceip clustermac 00:12:34:45:67:89
1116 total-nodes 4 local-node 2 hash-init 12345;
1120 Sets the netfilter mark value associated with a connection.
1122 CONNMARK set-mark 42;
1124 CONNMARK restore-mark;
1125 CONNMARK save-mark mask 0x7fff;
1126 CONNMARK restore-mark mask 0x8000;
1128 =item B<CONNSECMARK>
1130 This module copies security markings from packets to connections (if
1131 unlabeled), and from connections back to packets (also only if
1132 unlabeled). Typically used in conjunction with SECMARK, it is only
1133 valid in the mangle table.
1136 CONNSECMARK restore;
1138 =item B<DNAT to [ip-address|ip-range|ip-port-range]>
1140 Change the destination address of the packet.
1143 DNAT to 10.0.0.4:80;
1144 DNAT to 10.0.0.4:1024-2048;
1145 DNAT to 10.0.1.1-10.0.1.20;
1149 This target allows to selectively work around known ECN blackholes.
1150 It can only be used in the mangle table.
1156 Modify the IPv6 Hop Limit field (ip6/mangle only).
1162 =item B<IPV4OPTSSTRIP>
1164 Strip all the IP options from a packet. This module does not take any
1171 Log all packets that match this rule in the kernel log. Be carefull
1172 with log flooding. Note that this is a "non-terminating target",
1173 i.e. rule traversal continues at the next rule.
1175 LOG log-level warning log-prefix "Look at this: ";
1176 LOG log-tcp-sequence log-tcp-options;
1181 Sets the netfilter mark field for the packet (a 32 bit integer between
1192 Masquerades matching packets. Optionally followed by a port or
1193 port-range for iptables. Specify as "123", "123-456" or "123:456".
1194 The port range parameter specifies what local ports masqueraded
1195 connections should originate from.
1198 MASQUERADE to-ports 1234:2345;
1199 MASQUERADE to-ports 1234:2345 random;
1203 Experimental demonstration target which inverts the source and
1204 destination fields in the IP header.
1210 Map a whole network onto another network in the B<nat> table.
1212 NETMAP to 192.168.2.0/24;
1216 Disable connection tracking for all packets matching that rule.
1218 proto tcp dport (135:139 445) NOTRACK;
1222 Log packets over netlink; this is the successor of I<ULOG>.
1224 NFLOG nflog-group 5 nflog-prefix "Look at this: ";
1225 NFLOG nflog-range 256;
1226 NFLOG nflog-threshold 10;
1230 Userspace queueing, requires nfnetlink_queue kernel support.
1232 proto tcp dport ftp NFQUEUE queue-num 20;
1236 Userspace queueing, the predecessor to B<NFQUEUE>. All packets go to
1239 proto tcp dport ftp QUEUE;
1241 =item B<REDIRECT to-ports [ports]>
1243 Transparent proxying: alter the destination IP of the packet to the
1246 proto tcp dport http REDIRECT to-ports 3128;
1247 proto tcp dport http REDIRECT to-ports 3128 random;
1251 Similar to SNAT, but a client is mapped to the same source IP for all
1254 SAME to 1.2.3.4-1.2.3.7;
1255 SAME to 1.2.3.8-1.2.3.15 nodst;
1256 SAME to 1.2.3.16-1.2.3.31 random;
1260 This is used to set the security mark value associated with the packet
1261 for use by security subsystems such as SELinux. It is only valid in
1264 SECMARK selctx "system_u:object_r:httpd_packet_t:s0";
1266 =item B<SET [add-set|del-set] [setname] [flag(s)]>
1268 Add the IP to the specified set. See L<http://ipset.netfilter.org/>
1270 proto icmp icmp-type echo-request SET add-set badguys src;
1272 =item B<SNAT to [ip-address|ip-range|ip-port-range]>
1274 Change the source address of the packet.
1277 SNAT to 1.2.3.4:20000-30000;
1278 SNAT to 1.2.3.4 random;
1282 Alter the MSS value of TCP SYN packets.
1284 TCPMSS set-mss 1400;
1285 TCPMSS clamp-mss-to-pmtu;
1287 =item B<TOS set-tos [value]>
1289 Set the tcp package Type Of Service bit to this value. This will be
1290 used by whatever traffic scheduler is willing to, mostly your own
1291 linux-machine, but maybe more. The original tos-bits are blanked and
1292 overwritten by this value.
1294 TOS set-tos Maximize-Throughput;
1299 Type "iptables -j TOS -h" for details.
1303 Modify the TTL header field.
1306 TTL ttl-dec 1; # decrease by 1
1307 TTL ttl-inc 4; # increase by 4
1311 Log packets to a userspace program.
1313 ULOG ulog-nlgroup 5 ulog-prefix "Look at this: ";
1314 ULOG ulog-cprange 256;
1315 ULOG ulog-qthreshold 10;
1319 =head1 OTHER DOMAINS
1321 Since verison 2.0, B<ferm> supports not only I<ip> and I<ip6>, but
1322 also I<arp> (ARP tables) and I<eb> (ethernet bridging tables). The
1323 concepts are similar to I<iptables>.
1325 =head2 arptables keywords
1329 =item B<source-ip>, B<destination-ip>
1331 Matches the source or destination IPv4 address. Same as B<saddr> and
1332 B<daddr> in the I<ip> domain.
1334 =item B<source-mac>, B<destination-mac>
1336 Matches the source or destination MAC address.
1338 =item B<interface>, B<outerface>
1340 Input and output interface.
1344 Hardware length of the packet.
1346 chain INPUT h-length 64 ACCEPT;
1350 Operation code, for details see the iptables(8).
1364 proto-type 0x800 ACCEPT;
1368 The keywords B<mangle-ip-s>, B<mangle-ip-d>, B<mangle-mac-s>,
1369 B<mangle-mac-d>, B<mangle-target> may be used for ARP mangling. See
1370 iptables(8) for details.
1374 =head2 ebtables keywords
1380 Matches the protocol which created the frame, e.g. I<IPv4> or B<PPP>.
1381 For a list, see F</etc/ethertypes>.
1383 =item B<interface>, B<outerface>
1385 Physical input and output interface.
1387 =item B<logical-in>, B<logical-out>
1389 The logical bridge interface.
1391 =item B<saddr>, B<daddr>
1393 Matches source or destination MAC address.
1397 =head1 ADVANCED FEATURES
1401 In complex firewall files, it is helpful to use variables, e.g. to
1402 give a network interface a meaningful name.
1404 To set variables, write:
1406 @def $DEV_INTERNET = eth0;
1407 @def $PORTS = (http ftp);
1408 @def $MORE_PORTS = ($PORTS 8080);
1410 In the real ferm code, variables are used like any other keyword
1413 chain INPUT interface $DEV_INTERNET proto tcp dport $MORE_PORTS ACCEPT;
1415 Note that variables can only be used in keyword parameters
1416 ("192.168.1.1", "http"); they cannot contain ferm keywords like
1417 "proto" or "interface".
1419 Variables are only valid in the current block:
1421 @def $DEV_INTERNET = eth1;
1424 @def $DEV_INTERNET = ppp0;
1425 interface $DEV_INTERNET dport http ACCEPT;
1427 interface $DEV_INTERNET DROP;
1430 will be expanded to:
1434 interface ppp0 dport http ACCEPT;
1436 interface eth1 DROP;
1439 The "def $DEV_INTERNET = ppp0" is only valid in the "proto tcp" block;
1440 the parent block still knows "set $DEV_INTERNET = eth1".
1442 Include files are special - variables declared in an included file are
1443 still available in the calling block. This is useful when you include
1444 a file which only declares variables.
1446 =head2 Automatic variables
1448 Some variables are set internally by ferm. Ferm scripts can use them
1449 just like any other variable.
1455 The current domain. One of I<ip>, I<ip6>, I<arp>, I<eb>.
1459 The current netfilter table.
1463 The current netfilter chain.
1469 Functions are similar to variables, except that they may have
1470 parameters, and they provide ferm commands, not values.
1472 @def &FOO() = proto (tcp udp) dport domain;
1475 @def &TCP_TUNNEL($port, $dest) = {
1476 table filter chain FORWARD interface ppp0 proto tcp dport $port daddr $dest outerface eth0 ACCEPT;
1477 table nat chain PREROUTING interface ppp0 proto tcp dport $port daddr 1.2.3.4 DNAT to $dest;
1480 &TCP_TUNNEL(http, 192.168.1.33);
1481 &TCP_TUNNEL(ftp, 192.168.1.30);
1482 &TCP_TUNNEL((ssh smtp), 192.168.1.2);
1484 A function call which contains a block (like '{...}') must be the last
1485 command in a ferm rule, i.e. it must be followed by ';'. The '&FOO()'
1486 example does not contain a block, thus you may write 'ACCEPT' after
1487 the call. To circumvent this, you can reorder the keywords:
1489 @def &IPSEC() = { proto (esp ah); proto udp dport 500; }
1490 chain INPUT ACCEPT &IPSEC();
1494 With backticks, you may use the output of an external command:
1496 @def $DNSSERVERS = `grep nameserver /etc/resolv.conf | awk '{print $2}'`;
1497 chain INPUT proto tcp saddr $DNSSERVERS ACCEPT;
1499 The command is executed with the shell (F</bin/sh>), just like
1500 backticks in perl. ferm does not do any variable expansion here.
1502 The output is then tokenized, and saved as a ferm list (array). Lines
1503 beginning with '#' are ignored; the other lines may contain any number
1504 of values, separated by whitespace.
1508 The B<@include> keyword allows you to include external files:
1510 @include 'vars.ferm';
1512 The file name is relative to the calling file, e.g. when including
1513 from F</etc/ferm/ferm.conf>, the above statement includes
1514 F</etc/ferm/vars.ferm>. Variables and functions declared in an
1515 included file are still available in the calling file.
1517 B<include> works within a block:
1520 @include 'input.ferm';
1523 If you specify a directory (with a trailing '/'), all files in this
1524 directory are included, sorted alphabetically:
1530 The keyword B<@if> introduces a conditional expression:
1532 @if $condition DROP;
1534 A value is evaluated true just like in Perl: zero, empty list, empty
1535 string are false, everything else is true. Examples for true values:
1537 (a b); 1; 'foo'; (0 0)
1539 Examples for false values:
1543 There is also B<@else>:
1545 @if $condition DROP; @else REJECT;
1547 Note the semicolon before the B<@else>.
1549 It is possible to use curly braces after either B<@if> or B<@else>:
1558 Since the closing curly brace also finishes the command, there is no
1561 There is no B<@elsif>, use B<@else @if> instead.
1565 To run custom commands, you may install hooks:
1567 hook pre "echo 0 >/proc/sys/net/ipv4/conf/eth0/forwarding";
1568 hook post "echo 1 >/proc/sys/net/ipv4/conf/eth0/forwarding";
1570 The specified command is executed using the shell. "pre" means run
1571 the command before applying the firewall rules, and "post" means run
1572 the command afterwards. You may install any number of hooks.
1576 There are several built-in functions which you might find useful.
1578 =head2 @resolve((hostname1 hostname2 ...))
1580 Usually, host names are resolved by iptables. To let ferm resolve
1581 host names, use the function @resolve:
1583 saddr @resolve(my.host.foo) proto tcp dport ssh ACCEPT;
1584 saddr @resolve((another.host.foo third.host.foo)) proto tcp dport openvpn ACCEPT;
1586 Note the double parentheses in the second line: the inner pair for
1587 creating a ferm list, and the outer pair as function parameter
1590 This function currently only resolves B<A> records (i.e. IPv4
1591 addresses), rendering it useless for the I<ip6> domain.
1593 Be careful with resolved host names in firewall configuration. DNS
1594 requests may block the firewall configuration for a long time, leaving
1595 the machine vulnerable, or they may fail.
1599 The F<./examples/> directory contains numerous ferm configuration
1600 which can be used to begin a new firewall. This sections contains more
1601 samples, recipes and tricks.
1603 =head2 Easy port forwarding
1605 Ferm function make routine tasks quick and easy:
1607 @def &FORWARD_TCP($proto, $port, $dest) = {
1608 table filter chain FORWARD interface $DEV_WORLD outerface $DEV_DMZ daddr $dest proto $proto dport $port ACCEPT;
1609 table nat chain PREROUTING interface $DEV_WORLD daddr $HOST_STATIC proto $proto dport $port DNAT to $dest;
1612 &FORWARD_TCP(tcp, http, 192.168.1.2);
1613 &FORWARD_TCP(tcp, smtp, 192.168.1.3);
1614 &FORWARD_TCP((tcp udp), domain, 192.168.1.4);
1616 =head2 Remote B<ferm>
1618 If the target machine is not able to run B<ferm> for some reason
1619 (maybe an embedded device without Perl), you can edit the B<ferm>
1620 configuration file on another computer and let B<ferm> generate a
1623 Example for OpenWRT:
1625 ferm --remote --shell mywrt/ferm.conf >mywrt/firewall.user
1626 chmod +x mywrt/firewall.user
1627 scp mywrt/firewall.user mywrt.local.net:/etc/
1628 ssh mywrt.local.net /etc/firewall.user
1630 =head1 TRANSITION FROM FERM 1.1
1632 ferm 1.2 aims to be 100% compatible with ferm 1.1, i.e. old
1633 configuration files should work as expected. For a "clean" ferm 1.2
1634 configuration without warnings, here is a list of the most important
1639 =item I<ipfwadm and ipchains>
1641 Support for these has been removed.
1643 =item I<options B<clearall>, B<flushall>, B<flushchains>, B<createchains>>
1645 All these options are always implied. There is no option anymore to
1648 =item I<option automod>
1650 Automatic module loading is deprecated. It still works for now, at
1651 least for modules which were already supported by ferm 1.1, but it is
1652 expected to be removed in ferm 1.3.
1654 =item I<option location>
1656 ferm assumes that the iptables utilities are always installed in
1659 =item I<Chain policies>
1661 Chain policies should be written in a dedicated statement; ferm 1.1:
1663 chain INPUT policy DROP {
1676 The concept of variables has been overhauled in ferm 1.2; you can now
1677 declare functions which take parameters. Besides that, you should use
1680 @def $FOO = (http ssh);
1681 chain INPUT proto tcp dport $FOO ACCEPT;
1685 Arrays used to be specified with commas separating the items. In ferm
1686 1.2, you separate array items only by whitespace.
1688 =item I<Misc syntax changes>
1690 Other small syntax changes:
1696 built-in target names must be upper case; chains are lower case
1700 MASQUERADE, not MASQ
1704 A lot of shortcuts are deprecated, since they are polluting the namespace, e.g. "mac", "tosrc".
1708 "source addr $A port $B" is deprecated, use "sdaddr $A sport $B"
1709 instead. The same for "destination".
1721 Do not execute the iptables(8) commands, but skip instead. This way
1722 you can parse your data, use B<--lines> to view the output.
1726 Clears the firewall rules and sets the policy of all chains to ACCEPT.
1727 B<ferm> needs a configuration file for that to determine which domains
1728 and tables are affected.
1732 Show the firewall lines that were generated from the rules. They
1733 will be shown just before they are executed, so if you get error
1734 messages from iptables(8) etc., you can see which rule caused
1737 =item B<--interactive>
1739 Apply the firewall rules and ask the user for confirmation. Reverts
1740 to the previous ruleset if there is no valid user response within 30
1741 seconds. This is useful for remote firewall administration: you can
1742 test the rules without fearing to lock yourself out.
1746 Show a brief list of available commandline options.
1750 Shows the version number of the program.
1754 Enable fast mode: ferm generates an iptables-save(8) file, and
1755 installs it with iptables-restore(8). This is much faster, because
1756 ferm calls iptables(8) once for every rule by default.
1758 Watch out for iptables versions older than 1.3, they might not work
1759 with this option due to quoting bugs.
1763 Generate a shell script which calls iptables-restore(8) and prints it.
1764 Implies --fast --lines.
1768 Generate rules for a remote machine. Implies B<--noexec> and
1769 B<--lines>. Can be combined with B<--shell>.
1771 =item B<--domain {ip|ip6}>
1773 Handle only the specified domain. B<ferm> output may be empty if the
1774 domain is not configured in the input file.
1776 =item B<--def '$name=value'>
1778 Override a variable defined in the configuration file.
1790 =head2 Operating system
1792 Linux 2.4 or newer, with netfilter support and all netfilter modules
1793 used by your firewall script
1797 iptables and perl 5.6
1803 If you find a bug, please tell us: ferm@foo-projects.org
1807 Copyright (C) 2001-2007 Auke Kok <sofar@foo-projects.org>, Max
1808 Kellermann <max@foo-projects.org>
1810 This program is free software; you can redistribute it and/or modify
1811 it under the terms of the GNU General Public License as published by
1812 the Free Software Foundation; either version 2 of the License, or (at
1813 your option) any later version.
1815 This program is distributed in the hope that it will be useful, but
1816 WITHOUT ANY WARRANTY; without even the implied warranty of
1817 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1818 General Public License for more details.
1820 You should have received a copy of the GNU General Public License
1821 along with this program; if not, write to the Free Software
1822 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
1827 Auke Kok <sofar@foo-projects.org>, Max Kellermann
1828 <max@foo-projects.org>