IPFILTER-DEFS(5)                                                File Formats Manual                                               IPFILTER-DEFS(5)

NAME

       /etc/netscript/ipfilter-defs - netscript ipfilter-defs compile definitions directory.

DESCRIPTION

       This  manual  page  documents  briefly  the  compile  definition files that are used by the netscript-compile(8) command from the netscript
       router/firewall network configuration package.  This compiler creates a compiled iptables rules file  in  /etc/netscript/ipfilter-defs.conf
       (it  is  a  shell  script portion) that is sourced by the netscript netscript(8) command to configure the iptables(8) firewall rules in the
       kernel.

STARTUP COMPILATION

       The rules can be compiled and automatically loaded on boot by setting the IPV4_CONFIGURE_SWITCH switch in network.conf(5) to the  value  of
       the  function  used  to  configure  the  kernel.   Net-compile(8) creates this function as Configure.  If this switch is set, the netscript
       startup will run netscript-compile(8) to make sure everything is up to date and load the rules from /etc/netscript/ipfilter-defs.conf,  and
       the  relevant settings in network.conf(5) which are used to establish packet grooming and configure the built in kernel netfilter INPUT and
       FORWARD chains in the filter table. If compilation fails, the previous  rule  set  is  not  replaced  and  it  is  used  instead.  See  the
       netscript(8) manpage to see how to load and use backup copies of the rule set.

CHAIN STRUCTURE

       Each  chain  in the iptables(8) filter table is set up by a corresponding coonstruction function of the same name as the chain.  The chains
       are laced into the iplcl (which is laced in to the INPUT chain) and ipfwd (laced into FORWARD) chains respectively, and the forwarding con-
       trol  chains  are set up to take traffic in both directions, with the destination network/interface and source network/interface being used
       in  the lacing chain, and network protocol and port being tied down in each specific chain.

       For the new in kernel Linux IPSEC, traffic to and from the VPN can be controlled via the iptables policy  match  module,  if  you  have  it
       patched  and  compiled into your kernel and iptables.  Future versions of the kernel and iptables should have this included in the distrib-
       uted source.

FILE STRUCTURE

       All the files defining the rules set are in the /etc/netscript/ipfilter-defs directory.  The  network-defs  file  is  used  to  define  the
       regions and network blocks used in the rest of the rules.  The prototypes-defs file is used to define protoype rules that can be referenced
       elsewhere in the rule set.  The prototypes.sh file is used to construct shell functions for the netscript-compile(8) command  that  can  be
       used  in  the  definitions  files.  DNAT and SNAT are set up in the dnat-defs and masq-defs files respectively.  Any file ending in .def is
       taken as general rule set input for netscript-compile(8).

       The files generally take the form of tables, with the columns tab or space seperated.  The '#' character is supported for  commenting,  and
       comments  can  be  on a line by themselves, or at the end of a configuration line.  Everything after the '#' is treated as a comment by the
       netscript-compile(8) compiler.

RULE STRUCTURE

       The structure of the rule sets is thus.  Each chain is started by calling a shell compilation function, (generally  ipv4_compile_chain)  to
       create the chain, with the chain name and source/destination regions as arguments, and each rule in the chain by starting a fresh line with
       the chain name in the first column.

       Regions are defined as network interface tuples, and are set up in network-defs.  They are syntactically the same  as  shell  script  vari-
       ables,  and  are  used  the same way in the .def rule set files. Technically this magic is achieved by using eval within the netscript-com-
       pile(8) shell script.

       Any  interface name can have either of the keywords =clear or =ipsec tied to them by using the `=' character on the end  of  the  interface
       name.   This is used to specifically match IPSEC traffic, or non-IPSEC traffic going over the interface.  Typically you would use this when
       defining a region, though the syntax is valid elsewhere as well. It is recommended that you use this feature to  prevent  packet  injection
       from adjacent external sources when setting up iptables rules for VPN tunnel traffic.

       The  regions are given as arguments to the compilation function, with the region always being 2 arguments in network/interface order to the
       function.

       Each chain rule in the chain is defined by giving first of all the chain name, then the rule type, and its direction.   All  columns  after
       the 3rd one are specific to and are defined by the rule type.  The direction may have a '-' in it.

       The rules produced by the compiler use the iptables connection based state tracking.  Packet by packet rules will be added later.

EXAMPLE

       Here is an example of part of a .def file:

              # Access from Office to internet
              #          - only allow outgoing tcp and UDP
              # and ping traffic - anything else is most
              # like a tunneling protocol.
              # We have VPNs for tunneling
              ipv4_compile_chain -p 90 offcInet droplog $OFFICE_REGN $INTERNET_REGN
              offcInet       ACCEPT_EST      BOTH
              offcInet       ACCEPT_PING     L2R
              offcInet       ACCEPT_TCP      L2R     1:65535
              offcInet       ACCEPT_UDP      L2R     1:65535

       The ACCEPT_EST line accepts packets for ESTABLISHED and RELATED connections to the new ones already accepted.  New connections are accepted
       by the ACCEPT_PING, ACCEPT_TCP, and ACCEPT_UDP rules.  Please see the iptables(8) manpage for the details on stateful filtering.

COMPILE FUNCTIONS

       Unless a function is defined in prototypes.sh, there is only one function provided.  However this is not limiting as there  is  a  facility
       for rule macros, as well as the ability to tell the function to use one of the default base rule sets.

       If  you  do  define  a function in prototypes.sh, be careful to handle all errors to function and command calls as otherwise netscript-com-
       pile(8) will break, as it runs with set -e set.

       The only defined compile function for IPv4 is:

       ipv4_compile_chain [-i] [-n] [-b base-chain] [-p priority] [-s slave-chain] <chain-name> <default-target>  <from-net>  <from-if>  [<to-net>
       <to-if>]

       You can see the source region and destination region on the end of it.  The default-target is one of RETURN, DROP, droplog, or log.

       The options to this function are as follows:

       -i     Create an input chain for attaching to iplcl instead of the default forward chain for attaching to ipfwd.

       -n     Don't lace the chain into iplcl or ipfwd.

       -b base-chain
              Specify an alternate ruleset chain to use.

       -s slave-chain
              Configure/deconfigure  this  chain  as  well as the one specified.  Useful for adjusting input rule set when manipulating the access
              chain for an IPsec VPN.

       -p priority
              Specify the priority of the chain in the lacing rule set.  Priority is between 00 and 99, with 00 at the top of  the  lacing  chain,
              and  99  at  the bottom. This is useful for making sure that host specific rule sets occur before more general network related ones,
              and for putting Internet related ones at the bottom of the lacing chain.

DIRECTION STATEMENTS

       The direction is as per FreeS/WAN - it uses left and right terminology.

       The possible directions are as follows:

       L2R|LEFT2RIGHT|INTERNAL2EXTERNAL|INTERN2EXTERN|I2E|INT2EXT
              Left to Right, Internal to External

       R2L|RIGHT2LEFT|EXTERNAL2INTERNAL|EXTERN2INTERN|E2I|EXT2INT
              Right to Left, External to Internal

       BOTH|- Both directions, aka none or '-'.

AVAILABLE CHAIN RULES

       Here are the valid chain rules, and the arguments they expect.

       COMMENT [word1] [word2] ...
              Insert a comment into the compile shell script.  Fill the 3rd column direction in with '-'.

       MACRO <macro-name>
              Specify a macro rule set.  Rule set must name start with `MACRO_'. Direction again should be `-'.

       LOG [word1] [word2] ...
              Insert a logging rule using the given log meesage, or if none given, using the curretlog message for the chain.

       LOG_MSG [word1] [word2] ...
              Set the log message for the chain away from the default of `Chain: <chain-name>' or from previous LOG_MSG setting. Up to 26  letters
              can be used until truncation limit is reached.

       RESET_LOG_MSG
              Reset log message to the default of `Chain: <chain-name>'.

       REJECT_SMB
              Jump to smb control chain. Creates smb chain if it does not already exist.

       DROP_MARTIANS
              Jump to martian source address control chain.  Creates chain if it does not already exist.

       LOG_PORTSCAN
              Use the psd module to detect and log portscans.  Creates portscan log chain (if not already there) which puts `PORTSCAN DETECTED - '
              in the log.

       DROP_BROADCAST
              Drop ethernet broadcast packets.

       LOG_BROADCAST
              Log ethernet broadcast packets with the current log messages for the chain.

       ACCEPT_EST
              Accept ESTABLISH,RELATED packets via the iptables(8) state module.

       ACCEPT_RELATED
              Accept RELATED packets via the iptables(8) state module. Useful for ICMP type 3 packets used for maximum MTU detection.

       ACCEPT_PROTO <protocol>
              Accept NEW connections for a  protocol.  Accepts one argument in the 4th column which is the protocol name  from  /etc/protocols  or
              the protocol number between 0 and 255.

       REJECT_PROTO <protocol>
              Reject  NEW connections for a  protocol with ICMP reject packets.  Accepts one argument in the 4th column which is the protocol name
              from /etc/protocols or the protocol number between 0 and 255.

       DROP_PROTO <protocol>
              Drop all packets for a  protocol with nothing in reply.  Accepts one argument in the 4th column which  is  the  protocol  name  from
              /etc/protocols or the protocol number between 0 and 255.

       LOG_PROTO <protocol>
              Log  NEW connections for a protocol with the current log message for the chain.  Accepts one argument in the 4th column which is the
              protocol name from /etc/protocols or the protocol number between 0 and 255.

       ACCEPT_TCP [src-port-range] <dst-port-range>
              Accept NEW TCP connections.  If one argument given, it is the destinaion port (range).  If 2 arguments, the first is the source port
              (range), and second the destination port (range).  Port ranges are specified by separating them with a `:' character, and ports must
              be in the /etc/services file, or a number between 0 and 65535.

       REJECT_TCP [src-port-range] <dst-port-range>
              Reject NEW TCP connections with an ICMP REJECT packet.  If one argument given, it is the destination port(range).  If  2  arguments,
              the  first is the source port (range), and second the destination port (range).  Port ranges are specified by separating them with a
              `:' character, and ports must be in the /etc/services file, or a number between 0 and 65535.

       DROP_TCP [src-port-range] <dst-port-range>
              Drop all tcp packets, returning nothing at all.  If one argument given, it is the destinaion port  (range).   If  2  arguments,  the
              first  is the source port (range), and second the destination port (range).  Port ranges are specified by separating them with a `:'
              character, and ports must be in the /etc/services file, or a number between 0 and 65535.

       LOG_TCP [src-port-range] <dst-port-range>
              Log NEW TCP connections with the current log text for the chain.  If one argument given, it is the destination  port(range).   If  2
              arguments,  the  first is the source  port (range), and second the destination port (range). Port ranges are specified by separating
              them with a `:' character, and ports must be in the /etc/services file, or a number between 0 and 65535.

       ACCEPT_UDP [src-port-range] <dst-port-range>
              Accept NEW UDP connections.  If one argument given, it is the destinaion port (range).  If 2 arguments, the first is the source port
              (range), and second the destination port (range).  Port ranges are specified by separating them with a `:' character, and ports must
              be in the /etc/services file, or a number between 0 and 65535.

       REJECT_UDP [src-port-range] <dst-port-range>
              Reject NEW UDP connections with an ICMP REJECT packet.  If one argument given, it is the destination port(range).  If  2  arguments,
              the  first is the source port (range), and second the destination port (range).  Port ranges are specified by separating them with a
              `:' character, and ports must be in the /etc/services file, or a number between 0 and 65535.

       DROP_UDP [src-port-range] <dst-port-range>
              DROP all UDP packets, returning nothing at all.  If one argument given, it is the destinaion port  (range).   If  2  arguments,  the
              first  is the source port (range), and second the destination port (range).  Port ranges are specified by separating them with a `:'
              character, and ports must be in the /etc/services file, or a number between 0 and 65535.

       LOG_UDP [src-port-range] <dst-port-range>
              Log NEW UDP connections with the current log message for the chain.  If one argument given, it is the destination port(range).  If 2
              arguments,  the  first is the source port (range), and second the destination port (range).  Port ranges are specified by separating
              them with a `:' character, and ports must be in the /etc/services file, or a number between 0 and 65535.

       ACCEPT_PING
              Accept ICMP type 8 echo request packets for network diagnosis.

       DROP_PING
              Drop ICMP type 8 packets with no reply.

       LOG_PING
              Log an ICMP echo request with the current log message for the chain.

       ACCEPT_TCP_NET [src_network [src-port-range]] <dst-network> <dst-port-range>
              Accept NEW TCP connections from given source (optional) to destination.  Network is given in IPv4 address/netmask or address/masklen
              format.  Port ranges are specified by separating them with a `:' character, and ports must be in the /etc/services file, or a number
              between 0 and 65535.

       REJECT_TCP_NET [src_network [src-port-range]] <dst-network> <dst-port-range>
              Reject NEW TCP conections with an ICMP reject packet which come from a given source (optional), going to given destination.  Network
              is  given  in IPv4 address/netmask or address/masklen format. Port ranges are specified by separating them with a `:' character, and
              ports must be in the /etc/services file, or a number between 0 and 65535.

       DROP_TCP_NET [src_network [src-port-range]] <dst-network> <dst-port-range>
              Drop all TCP packets which come from a given source (optional), going to given destination.  Network is given in  IPv4  address/net-
              mask  or  address/masklen  format.  Port  ranges  are  specified  by  separating them with a `:' character, and ports must be in the
              /etc/services file, or a number between 0 and 65535.

       LOG_TCP_NET [src_network [src-port-range]] <dst-network> <dst-port-range>
              Log all NEW TCP connections from given source (optional) to destination, with the current log message for  the  chain.   Network  is
              given  in  IPv4  address/netmask  or  address/masklen format. Port ranges are specified by separating them with a `:' character, and
              ports must be in the /etc/services file, or a number between 0 and 65535.

       ACCEPT_UDP_NET [src_network [src-port-range]] <dst-network> <dst-port-range>
              Accept NEW UDP connections from given source (optional) to destination.  Network is given in IPv4 address/netmask or address/masklen
              format.  Port ranges are specified by separating them with a `:' character, and ports must be in the /etc/services file, or a number
              between 0 and 65535.

       REJECT_UDP_NET [src_network [src-port-range]] <dst-network> <dst-port-range>
              Reject NEW UDP conections with an ICMP reject packet which come from a given source (optional), going to given destination.  Network
              is  given  in IPv4 address/netmask or address/masklen format. Port ranges are specified by separating them with a `:' character, and
              ports must be in the /etc/services file, or a number between 0 and 65535.

       DROP_UDP_NET [src_network [src-port-range]] <dst-network> <dst-port-range>
              Drop all UDP packets which come from a given source (optional), going to given destination.  Network is given in  IPv4  address/net-
              mask  or  address/masklen  format.  Port  ranges  are  specified  by  separating them with a `:' character, and ports must be in the
              /etc/services file, or a number between 0 and 65535.

       LOG_UDP_NET [src_network [src-port-range]] <dst-network> <dst-port-range>
              Log all NEW UDP connections from given source (optional) to destination, with the current log message for  the  chain.   Network  is
              given  in  IPv4  address/netmask  or  address/masklen format. Port ranges are specified by separating them with a `:' character, and
              ports must be in the /etc/services file, or a number between 0 and 65535.

       ACCEPT_IFACE <interface>
              Accept all incoming NEW connections from an incoming interface.

       REJECT_IFACE <interface>
              Reject all incoming NEW conections with an ICMP reject packet, from an interface.

       DROP_IFACE <interface>
              Drop all incoming packets from an interface.

       LOG_IFACE <interface>
              Log all incoming NEW conections from an interface.

       ACCEPT_NET <network>
              Accept all NEW connections from network.  Network is given in IPv4 address/netmask or address/masklen format.

       REJECT_NET <network>
              Reject all NEW conections from network with an ICMP reject packet.  Network is given in IPv4 address/netmask or address/masklen for-
              mat.

       DROP_NET <network>
              Drop all packets from network.  Network is given in IPv4 address/netmask or address/masklen format.

       LOG_NET <network>
              Log all NEW conections from network.  Network is given in IPv4 address/netmask or address/masklen format.

FILES

       /etc/netscript/ipfilter-defs.conf,
       /etc/netscript/ipfilter-defs-compiled.conf,
       /etc/netscript/ipfilter-defs directory.

SEE ALSO

       netscript-compile(8), iptables(8), ip6tables(8), netscript(8).

AUTHOR

       This manual page was written by Matthew Grant <grantma@anathoth.gen.nz>, for the Debian GNU/Linux system (but may be used by others).

BUGS

       I wrote this manpage when I was not half asleep...

       Some things are missing from this manpage...

       Dnat documentation is missing but obvious from configuration file.

       SNAT documentation is missing but obvious from configuration file.

                                                                  March 25, 2003                                                  IPFILTER-DEFS(5)