NAME
    ferm - a firewall rule parser for linux

SYNOPSIS
    ferm *options* *inputfile*

DESCRIPTION
    ferm is a frontend for iptables. It reads the rules from a structured
    configuration file and calls iptables(8) to insert them into the running
    kernel.

    ferm's goal is to make firewall rules easy to write and easy to read. It
    tries to reduce the tedious task of writing down rules, thus enabling
    the firewall administrator to spend more time on developing good rules
    than the proper implementation of the rule.

    To achieve this, ferm uses a simple but powerful configuration language,
    which allows variables, functions, arrays, blocks. It also allows you to
    include other files, allowing you to create libraries of commonly used
    structures and functions.

    ferm, pronounced "firm", stands for "For Easy Rule Making".

CAUTION
    This manual page does *not* indend to teach you how firewalling works
    and how to write good rules. There is already enough documentation on
    this topic.

INTRODUCTION
    Let's start with a simple example:

        chain INPUT {
            proto tcp ACCEPT;
        }

    This will add a rule to the predefined input chain, matching and
    accepting all tcp packets. Ok, let's make it more complicated:

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

    This will insert 4 rules, namely 2 in chain input, and 2 in chain
    output, matching and accepting both udp and tcp packets. Normally you
    would type this:

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

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

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

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

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

    It would aid the reader if the resulting firewall rules were placed here
    for reference. Also, you could include the nested version with better
    readability.

    Try using comments to show what you are doing:

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

    You will be thankful for it later!

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

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

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

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

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

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

STRUCTURE OF A FIREWALL FILE
    The structure of a proper firewall file looks like simplified C-code.
    Only a few syntactic characters are used in ferm- configuration files.
    Besides these special caracters, ferm uses 'keys' and 'values', think of
    them as options and parameters, or as variables and values, whatever.

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

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

        iptables --protocol tcp

    In ferm, this will become:

        protocol tcp;

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

        iptables --protocol tcp -j ACCEPT

    Or, translated to ferm:

        protocol tcp ACCEPT;

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

        protocol tcp
          ACCEPT;

    Here's a list of the special characters:

    ;       This character finalizes a rule.

            Separated by semicolons, you may write multiple rules in one
            line, although this decreases readability:

                protocol tcp ACCEPT; protocol udp DROP;

    {}      The nesting symbol defines a 'block' of rules.

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

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

            Example:

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

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

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

            There can be multiple nesting levels:

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

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

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

    $       Variable expansion. Replaces '$FOO' by the value of the
            variable. See the section *VARIABLES* for details.

    &       Function call. See the section *FUNCTIONS* for details.

    ()      The array symbol. Using the parentheses, you can define a 'list'
            of values that should be applied for the key to the left of it.

            Example:

                protocol ( tcp udp icmp )

            this will result in three rules:

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

            Only values can be 'listed', so you cannot do something like
            this:

                proto tcp ( ACCEPT LOG );

            but you can do this:

                chain (INPUT OUTPUT FORWARD) proto (icmp udp tcp) DROP;

            (which will result in nine rules!)

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

    " # "   The comment symbol. Anything that follows this symbol up to the
            end of line is ignored.

    `command`
            Execute the command in a shell, and insert the process output.
            See the section *backticks* for details.

    'string'
            Quote a string which may contain whitespaces, the dollar sign
            etc.

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

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

                DNAT to "$myhost:$myport";

  Keywords
    In the previous section, we already introduced some basic keywords like
    "chain", "protocol" and "ACCEPT". Let's explore their nature.

    There are three kinds of keywords:

    *       location keywords define where a rule will be created. Example:
            "table", "chain".

    *       match keywords perform a test on all passing packets. The
            current rule is without effect if one (or more) of the matches
            does not pass. Example: "proto", "daddr".

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

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

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

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

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

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

  Parameters
    Many keywords take parameters. These can be specified as literals,
    variable references or lists (arrays):

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

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

        proto !esp;
        proto udp dport !domain;

    Keywords which take no parameters are negated by a prefixed '!':

        proto tcp !syn;

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

BASIC KEYWORDS
  Location keywords
    domain [ip|ip6]
            Set the domain. "ip" is default and means "IPv4" (iptables).
            "ip6" is for IPv6 support, using "ip6tables".

    table [filter|nat|mangle]
            Specifies which netfilter table this rule will be inserted to:
            "filter" (default), "nat" or "mangle".

    chain [chain-name]
            Specifies the netfilter chain (within the current table) this
            rule will be inserted to. Common predefined chain names are
            "INPUT", "OUTPUT", "FORWARD", "PREROUTING", "POSTROUTING",
            depending on the table. See the netfilter documentation for
            details.

            If you specify a non-existing chain here, ferm will add the rule
            to a custom chain with that name.

    policy [ACCEPT|DROP|..]
            Specifies the default policy for the current chain (built-in
            only). Can be one of the built-in targets (ACCEPT, DROP, REJECT,
            ...). A packet that matches no rules in a chain will be treated
            as specified by the policy.

            To avoid ambiguity, always specify the policies of all
            predefined chains explicitly.

    @subchain ["CHAIN-NAME"] { ... }
            Works like the normal block operators (i.e. without the
            *@subchain* keyword), except that ferm moves rules within the
            curly braces into a new custom chain. The name for this chain is
            chosen automatically by ferm.

            In many cases, this is faster than just a block, because the
            kernel may skip a huge block of rules when a precondition is
            false. Imagine the following example:

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

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

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

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

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

            The name can either be a quoted string literal, or an expanded
            ferm expression such as @cat("interface_", $iface) or
            @substr($var,0,20).

            You can achieve the same by explicitly declaring a custom chain,
            but you may feel that using @subchain requires less typing.

  Basic iptables match keywords
    interface [interface-name]
            Define the interface name, your outside network card, like eth0,
            or dialup like ppp1, or whatever device you want to match for
            passing packets. It is equivalent to the "-i" switch in
            iptables(8).

    outerface [interface-name]
            Same as interface, only for matching the outgoing interface for
            a packet, as in iptables(8).

    protocol [protocol-name|protocol-number]
            Currently supported by the kernel are tcp, udp and icmp, or
            their respective numbers.

    saddr|daddr [address-spec]
            Matches on packets originating from the specified address
            (saddr) or targeted at the address (daddr).

            Examples:

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

    fragment
            Specify that only fragmented IP packets should be matched. When
            packets are larger that the maximum packet size your system can
            handle (called Maximum Transmission Unit or MTU) they will be
            chopped into bits and sent one by one as single packets. See
            ifconfig(8) if you want to find the MTU for your system (the
            default is usually 1500 bytes).

            Fragments are frequently used in DOS attacks, because there is
            no way of finding out the origin of a fragment packet.

    sport|dport [port-spec]
            Matches on packets on the specified TCP or UDP port. "sport"
            matches the source port, and dport matches the destination port.

            This match can be used only after you specified "protocol tcp"
            or "protocol udp", because only these two protocols actually
            have ports.

            And some examples of valid ports/ranges:

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

    syn     Specify that the SYN flag in a tcp package should be matched,
            which are used to build new tcp connections. You can identify
            incoming connections with this, and decide wether you want to
            allow it or not. Packets that do not have this flag are probably
            from an already established connection, so it's considered
            reasonably safe to let these through.

    module [module-name]
            Load an iptables module. Most modules provide more match
            keywords. We'll get to that later.

  Basic target keywords
    jump [custom-chain-name]
            Jumps to a custom chain. If no rule in the custom chain matched,
            netfilter returns to the next rule in the previous chain.

    realgoto [custom-chain-name]
            Go to a custom chain. Unlike the jump option, RETURN will not
            continue processing in this chain but instead in the chain that
            called us via jump.

            The keyword realgoto was chosen during the transition period,
            because goto (already deprecated) used to be an alias for jump.

    ACCEPT  Accepts matching packets.

    DROP    Drop matching packets without further notice.

    REJECT  Rejects matching packets, i.e. send an ICMP packet to the
            sender, which is port-unreachable by default. You may specify
            another ICMP type.

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

            Type "iptables -j REJECT -h" for details.

    RETURN  Finish the current chain and return to the calling chain (if
            "jump [custom-chain-name]" was used).

    NOP     No action at all.

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

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

                mod account aname mynetwork aaddr 192.168.1.0/24 ashort NOP;

    addrtype
            Check the address type; either source address or destination
            address.

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

            Type "iptables -m addrtype -h" for details.

    ah      Checks the SPI header in an AH packet.

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

            Additional arguments for IPv6:

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

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

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

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

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

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

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

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

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

                mod connlimit connlimit-above 4 REJECT;
                mod connlimit connlimit-above !4 ACCEPT;
                mod connlimit connlimit-above 4 connlimit-mask 24 REJECT;

    connmark
            Check the mark field associated with the connection, set by the
            CONNMARK target.

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

    conntrack
            Check connection tracking information.

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

            Type "iptables -m conntrack -h" for details.

    dccp    Check DCCP (Datagram Congestion Control Protocol) specific
            attributes. This module is automatically loaded when you use
            "protocol dccp".

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

    dscp    Match the 6 bit DSCP field within the TOS field.

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

    ecn     Match the ECN bits of an IPv4 TCP header.

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

            Type "iptables -m ecn -h" for details.

    esp     Checks the SPI header in an ESP packet.

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

    eui64   "This module matches the EUI-64 part of a stateless
            autoconfigured IPv6 address. It compares the EUI-64 derived from
            the source MAC address in Ehternet frame with the lower 64 bits
            of the IPv6 source address. But "Universal/Local" bit is not
            compared. This module doesn't match other link layer frame, and
            is only valid in the PREROUTING, INPUT and FORWARD chains."

                mod eui64 ACCEPT;

    fuzzy   "This module matches a rate limit based on a fuzzy logic
            controller [FLC]."

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

    hbh     Matches the Hop-by-Hop Options header (ip6).

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

    hl      Matches the Hop Limit field (ip6).

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

    helper  Checks which conntrack helper module tracks this connection. The
            port may be specified with "-portnr".

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

    icmp    Check ICMP specific attributes. This module is automatically
            loaded when you use "protocol icmp".

                proto icmp icmp-type echo-request ACCEPT;

            This option can also be used in be *ip6* domain, although this
            is called icmpv6 in ip6tables.

            Use "iptables -p icmp "-h"" to obtain a list of valid ICMP
            types.

    iprange Match a range of IPv4 addresses.

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

    ipv4options
            Match on IPv4 header options like source routing, record route,
            timestamp and router-alert.

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

    ipv6header
            Matches the IPv6 extension header (ip6).

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

    hashlimit
            Similar to 'mod limit', but adds the ability to add
            per-destination or per-port limits managed in a hash table.

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

            Possible values for hashlimit-mode: dstip dstport srcip srcport
            (or a list with more than one of these).

            There are more possible settings, type "iptables -m hashlimit
            -h" for documentation.

    length  Check the package length.

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

    limit   Limits the packet rate.

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

            Type "iptables -m limit -h" for details.

    mac     Match the source MAC address.

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

    mark    Matches packets based on their netfilter mark field. This may be
            a 32 bit integer between 0 and 4294967295.

                mod mark mark 42;

    mh      Matches the mobility header (domain *ip6*).

                proto mh mh-type binding-update ACCEPT;

    multiport
            Match a set of source or destination ports (UDP and TCP only).

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

            This rule has a big advantage over "dport" and "sport": it
            generates only one rule for up to 15 ports instead of one rule
            for every port.

    nth     Match every 'n'th packet.

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

            Type "iptables -m nth -h" for details.

    osf     Match packets depending on the operating system of the sender.

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

            Type "iptables -m osf -h" for details.

    owner   Check information about the packet creator, namely user id,
            group id, process id, session id and command name.

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

            ("cmd-owner", "pid-owner" and "sid-owner" require special kernel
            patches not included in the vanilla Linux kernel)

    physdev Matches the physical device on which a packet entered or is
            about to leave the machine. This is useful for bridged
            interfaces.

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

    pkttype Check the link-layer packet type.

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

    policy  Matches IPsec policy being applied to this packet.

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

            Note that the keyword *proto* is also used as a shorthand
            version of *protocol* (built-in match module). You can fix this
            conflict by always using the long keyword *protocol*.

    psd     Detect TCP/UDP port scans.

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

    quota   Implements network quotas by decrementing a byte counter with
            each packet.

                mod quota quota 65536 ACCEPT;

    random  Match a random percentage of all packets.

                mod random average 70;

    realm   Match the routing realm. Useful in environments using BGP.

                mod realm realm 3;

    recent  Temporarily mark source IP addresses.

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

            This netfilter module has a design flaw: although it is
            implemented as a match module, it has target-like behaviour when
            using the "set" keyword.

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

    rt      Match the IPv6 routing header (ip6 only).

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

    sctp    Check SCTP (Stream Control Transmission Protocol) specific
            attributes. This module is automatically loaded when you use
            "protocol sctp".

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

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

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

                mod set set badguys src DROP;

            See <http://ipset.netfilter.org/> for more information.

    state   Checks the connection tracking state.

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

            Type "iptables -m state -h" for details.

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

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

    string  Matches a string.

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

    tcp     Checks TCP specific attributes. This module is automatically
            loaded when you use "protocol tcp".

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

            Type "iptables -p tcp -h" for details.

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

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

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

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

            Type "iptables -m time -h" for details.

    tos     Matches a packet on the specified TOS-value.

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

            Type "iptables -m tos -h" for details.

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

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

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

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

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

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

    CLASSIFY
            Set the CBQ class.

                CLASSIFY set-class 3:50;

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

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

    CONNMARK
            Sets the netfilter mark value associated with a connection.

                CONNMARK set-mark 42;
                CONNMARK save-mark;
                CONNMARK restore-mark;
                CONNMARK save-mark mask 0x7fff;
                CONNMARK restore-mark mask 0x8000;

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

                CONNSECMARK save;
                CONNSECMARK restore;

    DNAT to [ip-address|ip-range|ip-port-range]
            Change the destination address of the packet.

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

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

                ECN ecn-tcp-remove;

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

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

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

                IPV4OPTSSTRIP;

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

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

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

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

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

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

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

                MIRROR;

    NETMAP  Map a whole network onto another network in the nat table.

                NETMAP to 192.168.2.0/24;

    NOTRACK Disable connection tracking for all packets matching that rule.

                proto tcp dport (135:139 445) NOTRACK;

    NFLOG   Log packets over netlink; this is the successor of *ULOG*.

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

    NFQUEUE Userspace queueing, requires nfnetlink_queue kernel support.

                proto tcp dport ftp NFQUEUE queue-num 20;

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

                proto tcp dport ftp QUEUE;

    REDIRECT to-ports [ports]
            Transparent proxying: alter the destination IP of the packet to
            the machine itself.

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

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

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

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

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

    SET [add-set|del-set] [setname] [flag(s)]
            Add the IP to the specified set. See
            <http://ipset.netfilter.org/>

                proto icmp icmp-type echo-request SET add-set badguys src;

    SNAT to [ip-address|ip-range|ip-port-range]
            Change the source address of the packet.

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

    TCPMSS  Alter the MSS value of TCP SYN packets.

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

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

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

            Type "iptables -j TOS -h" for details.

    TTL     Modify the TTL header field.

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

    ULOG    Log packets to a userspace program.

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

OTHER DOMAINS
    Since version 2.0, ferm supports not only *ip* and *ip6*, but also *arp*
    (ARP tables) and *eb* (ethernet bridging tables). The concepts are
    similar to *iptables*.

  arptables keywords
    source-ip, destination-ip
            Matches the source or destination IPv4 address. Same as saddr
            and daddr in the *ip* domain.

    source-mac, destination-mac
            Matches the source or destination MAC address.

    interface, outerface
            Input and output interface.

    h-length
            Hardware length of the packet.

                chain INPUT h-length 64 ACCEPT;

    opcode  Operation code, for details see the iptables(8).

                opcode 9 ACCEPT;

    h-type  Hardware type.

                h-type 1 ACCEPT;

    proto-type
            Protocol type.

                proto-type 0x800 ACCEPT;

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

  ebtables keywords
    proto   Matches the protocol which created the frame, e.g. *IPv4* or
            PPP. For a list, see /etc/ethertypes.

    interface, outerface
            Physical input and output interface.

    logical-in, logical-out
            The logical bridge interface.

    saddr, daddr
            Matches source or destination MAC address.

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

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

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

                mark 1 MARK 2;

ADVANCED FEATURES
  Variables
    In complex firewall files, it is helpful to use variables, e.g. to give
    a network interface a meaningful name.

    To set variables, write:

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

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

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

    Note that variables can only be used in keyword parameters
    ("192.168.1.1", "http"); they cannot contain ferm keywords like "proto"
    or "interface".

    Variables are only valid in the current block:

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

    will be expanded to:

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

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

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

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

    $FILENAME
            The name of the configuration file relative to the directory
            ferm was started in.

    $FILEBNAME
            The base name of the configuration file.

    $DIRNAME
            The directory of the configuration file.

    $DOMAIN The current domain. One of *ip*, *ip6*, *arp*, *eb*.

    $TABLE  The current netfilter table.

    $CHAIN  The current netfilter chain.

    $LINE   The line of the current script. It can be used like this:

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

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

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

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

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

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

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

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

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

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

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

  Includes
    The @include keyword allows you to include external files:

        @include 'vars.ferm';

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

    include works within a block:

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

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

        @include 'ferm.d/';

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

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

  Conditionals
    The keyword @if introduces a conditional expression:

        @if $condition DROP;

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

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

    Examples for false values:

        (); 0; '0'; ''

    There is also @else:

        @if $condition DROP; @else REJECT;

    Note the semicolon before the @else.

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

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

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

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

    Example:

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

  Hooks
    To run custom commands, you may install hooks:

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

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

BUILT-IN FUNCTIONS
    There are several built-in functions which you might find useful.

  @eq(a,b)
    Tests two values for equality. Example:

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

  @ne(a,b)
    Similar to @eq, this tests for non-equality.

  @not(x)
    Negates a boolean value.

  @resolve((hostname1 hostname2 ...), [type])
    Usually, host names are resolved by iptables. To let ferm resolve host
    names, use the function @resolve:

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

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

    The second parameter is optional, and specifies the DNS record type. The
    default is "A".

    Be careful with resolved host names in firewall configuration. DNS
    requests may block the firewall configuration for a long time, leaving
    the machine vulnerable, or they may fail.

  @cat(a, b, ...)
    Concatenate all parameters into one string.

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

  @length(expression)
    Returns the length in characters of the value of EXPR.

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

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

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

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

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

RECIPES
    The ./examples/ directory contains numerous ferm configuration which can
    be used to begin a new firewall. This sections contains more samples,
    recipes and tricks.

  Easy port forwarding
    Ferm function make routine tasks quick and easy:

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

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

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

    Example for OpenWRT:

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

OPTIONS
    --noexec    Do not execute the iptables(8) commands, but skip instead.
                This way you can parse your data, use --lines to view the
                output.

    --flush     Clears the firewall rules and sets the policy of all chains
                to ACCEPT. ferm needs a configuration file for that to
                determine which domains and tables are affected.

    --lines     Show the firewall lines that were generated from the rules.
                They will be shown just before they are executed, so if you
                get error messages from iptables(8) etc., you can see which
                rule caused the error.

    --interactive
                Apply the firewall rules and ask the user for confirmation.
                Reverts to the previous ruleset if there is no valid user
                response within 30 seconds (see --timeout). This is useful
                for remote firewall administration: you can test the rules
                without fearing to lock yourself out.

    --timeout S If --interactive is used, then roll back if there is no
                valid user response after this number of seconds. The
                default is 30.

    --help      Show a brief list of available commandline options.

    --version   Shows the version number of the program.

    --fast      Enable fast mode: ferm generates an iptables-save(8) file,
                and installs it with iptables-restore(8). This is much
                faster, because ferm calls iptables(8) once for every rule
                by default.

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

    --slow      Disable fast mode, i.e. run iptables(8) for every rule, and
                don't use iptables-restore(8).

    --shell     Generate a shell script which calls iptables-restore(8) and
                prints it. Implies --fast --lines.

    --remote    Generate rules for a remote machine. Implies --noexec and
                --lines. Can be combined with --shell.

    --domain {ip|ip6}
                Handle only the specified domain. ferm output may be empty
                if the domain is not configured in the input file.

    --def '$name=value'
                Override a variable defined in the configuration file.

SEE ALSO
    iptables(8)

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

  Software
    iptables and perl 5.6

BUGS
    Bugs? What bugs?

    If you find a bug, please tell us: ferm@foo-projects.org

COPYRIGHT
    Copyright (C) 2001-2012 Max Kellermann <max@foo-projects.org>, Auke Kok
    <sofar@foo-projects.org>

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

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

    You should have received a copy of the GNU General Public License along
    with this program; if not, write to the Free Software Foundation, Inc.,
    59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

AUTHOR
    Max Kellermann <max@foo-projects.org>, Auke Kok <sofar@foo-projects.org>

