ipchains - IP firewall administration


SYNOPSIS

       ipchains -[ADC] chain rule-specification [options]
       ipchains -[RI] chain rulenum rule-specification [options]
       ipchains -D chain rulenum [options]
       ipchains -[LFZNX] [chain] [options]
       ipchains -P chain target [options]
       ipchains -M [ -L | -S ] [options]


DESCRIPTION

       Ipchains  is  used to set up, maintain, and inspect the IP
       firewall rules in the Linux kernel.  These  rules  can  be
       divided  into  4 different categories: the IP input chain,
       the IP output chain, the IP  forwarding  chain,  and  user
       defined chains.

       For each of these categories, a separate table of rules is
       maintained, any of which might refer to one of  the  user-
       defined chains.  See ipfw(4) for more details.


TARGETS

       A  firewall  rule  specifies  criteria for a packet, and a
       target.  If the packet does not match, the  next  rule  in
       the  chain  is  then  examined; if it does match, then the
       next rule is specified by the value of the  target,  which
       can  be  the  name  of a user-defined chain, or one of the
       special values ACCEPT, DENY, REJECT,  MASQ,  REDIRECT,  or
       RETURN.
       ACCEPT  means  to  let  the packet through.  DENY means to
       drop the packet on the floor.  REJECT means  the  same  as
       drop,  but  is  more  polite and easier to debug, since an
       ICMP message is sent back to the  sender  indicating  that
       the  packet  was  dropped.  (Note that DENY and REJECT are
       the same for ICMP packets). [Note: this is incorrect; set­
       ting  ICMP  to REJECT will cause ICMP port unreachables to
       be sent!]
       MASQ is only  legal  for  the  forward  and  user  defined
       chains,  and  can only be used when the kernel is compiled
       with CONFIG_IP_MASQUERADE  defined.   With  this,  packets
       will  be  masqueraded as if they originated from the local
       host.  Furthermore, reverse packets will be recognized  as
       such and they will be demasqueraded automatically, bypass­
       ing the forwarding chain.
       REDIRECT is only legal  for  the  input  and  user-defined
       chains  and can only be used when the Linux kernel is com­
       piled  with  CONFIG_IP_TRANSPARENT_PROXY  defined.    With
       this,  packets  will be redirected to a local socket, even
       if they were sent to a  remote  host.   If  the  specified
       redirection  port  is  0,  which is the default value, the
       destination port of a packet will be used as the  redirec­
       tion  port.   When  this target is used, an optional extra
       argument (the port number) can be supplied.

       with  target  RETURN is matched, then the next rule in the
       previous (calling) chain is examined.  If  the  end  of  a
       builtin  chain  is  reached,  or a rule in a builtin chain
       with target RETURN is matched, the target specified by the
       chain policy determines the fate of the packet.


OPTIONS

       The options that are recognized by ipchains can be divided
       into several different groups.

   COMMANDS
       These options specify the specific action to perform; only
       one  of  them can be specified on the command line, unless
       otherwise specified below.  For all the long  versions  of
       the  command and option names, you only need to use enough
       letters to ensure that ipchains can differentiate it  from
       all other options.

       -A, --append
              Append one or more rules to the end of the selected
              chain.  When the source  and/or  destination  names
              resolve  to  more  than one address, a rule will be
              added for each possible address combination.

       -D, --delete
              Delete one or more rules from the  selected  chain.
              There  are  two  versions of this command: the rule
              can be specified as a number in the chain (starting
              at 1 for the first rule) or a rule to match.

       -R, --replace
              Replace  a  rule  in  the  selected  chain.  If the
              source and/or destination names resolve to multiple
              addresses,  the  command will fail.  Rules are num­
              bered starting at 1.

       -I, --insert
              Insert one or more rules in the selected  chain  as
              the  given  rule number.  So, if the rule number is
              1, the rule or rules are inserted at  the  head  of
              the chain.

       -L, --list
              List  all rules in the selected chain.  If no chain
              is selected, all chains are listed.  It is legal to
              specify the -Z (zero) option as well, in which case
              no chain may be specified.   The  exact  output  is
              affected by the other arguments given.

       -F, --flush
              Flush  the  selected  chain.  This is equivalent to
              deleting all the rules one by one.

              Zero the packet and byte counters  in  all  chains.
              It is legal to specify the -L, --list (list) option
              as well, to see  the  counters  immediately  before
              they are cleared; if this is done, then no specific
              chain can be specified (they will all be  displayed
              and cleared).

       -N, --new-chain
              Create  a new user-defined chain of the given name.
              There must be no target of that name already.

       -X, --delete-chain
              Delete the  specified  user-defined  chain.   There
              must  be  no  references to the chain (if there are
              you must delete  or  replace  the  referring  rules
              before  the  chain can be deleted).  If no argument
              is given, it will  attempt  to  delete  every  non-
              builtin chain.

       -P, --policy
              Set  the  policy for the chain to the given target.
              See the section  TARGETS  for  the  legal  targets.
              Only  non-userdefined chains can have policies, and
              neither built-in nor  user-defined  chains  can  be
              policy targets.

       -M, --masquerading
              This  option  allows  viewing of the currently mas­
              queraded connections (in  conjuction  with  the  -L
              option)  or  to set the kernel masquerading parame­
              ters (with the -S option).

       -S, --set tcp tcpfin udp
              Change the timeout values  used  for  masquerading.
              This  command always takes 3 parameters, represent­
              ing the timeout values (in seconds)  for  TCP  ses­
              sions,  TCP  sessions after receiving a FIN packet,
              and UDP packets, respectively.  A timeout  value  0
              means  that the current timeout value of the corre­
              sponding entry is preserved.  This option  is  only
              allowed in combination with the -M flag.

       -C, --check
              Check  the given packet against the selected chain.
              This is extremely useful for testing, as  the  same
              kernel  routines used to check "real" network pack­
              ets are used to check this packet.  It can be  used
              to check user-defined chains as well as the builtin
              ones.  The same arguments used to specify  firewall
              rules  are  used  to  construct  the  packet  to be
              tested.  In particular, the -s (source), -d (desti­
              nation),  -p  (protocol),  and -i (interface) flags
              are compulsory.

              Give a (currently very brief)  description  of  the
              command syntax.  If followed by the word icmp, then
              a list of ICMP names is listed.

       -V, --version
              Simply output the ipchains version number.

   PARAMETERS
       The following parameters make up a rule specification  (as
       used  in  the  add, delete, replace, append and check com­
       mands).

       -p, --protocol[!] protocol
              The protocol of the rule or of the packet to check.
              The  specified  protocol  can  be  one of tcp, udp,
              icmp, or all, or it can be a numeric value,  repre­
              senting  one of these protocols or a different one.
              Also  a  protocol  name  from   /etc/protocols   is
              allowed.    A  "!"  argument  before  the  protocol
              inverts the test.  The number zero is equivalent to
              all.   Protocol  all  will match with all protocols
              and is taken as default when this option  is  omit­
              ted.   All  may  not be used in in combination with
              the check command.

       -s, --source, --src [!] address[/mask] [!] [port[:port]]
              Source specification.   Address  can  be  either  a
              hostname,  a  network  name, or a plain IP address.
              The mask can be either a network mask  or  a  plain
              number,  specifying  the  number of 1's at the left
              side of the network mask.  Thus, a mask  of  24  is
              equivalent to 255.255.255.0.  A "!" argument before
              the address specification inverts the sense of  the
              address.
              The source may include a port specification or ICMP
              type.  This can either be a service  name,  a  port
              number,  a  numeric  ICMP  type, or one of the ICMP
              type names shown by the command
               ipchains -h icmp
              Note that many of these ICMP names refer to both  a
              type  and code, meaning that an ICMP code after the
              -d flag is illegal.  In the rest of this paragraph,
              a port means either a port specification or an ICMP
              type.  An inclusive range can  also  be  specified,
              using  the  format port:port.  If the first port is
              omitted, "0" is assumed; if the  last  is  omitted,
              "65535" is assumed.
              Ports may only be specified in combination with the
              tcp, udp, or icmp protocols.  A "!" before the port
              specification  inverts  the  sense.  When the check
              command is specified, exactly one port is required,
              and  if  the  -f  (fragment)  flag is specified, no
              ports are allowed.

              This allows separate specification  of  the  source
              port  or port range.  See the description of the -s
              flag above for details.The flag --sport is an alias
              for this option.

       -d, --destination, --dst [!] address[/mask] [!]
              [port[:port]]
              Destination specification.  See the  desciption  of
              the  -s (source) flag for a detailed description of
              the syntax.  For ICMP, which does not have ports, a
              "destination port" refers to the numeric ICMP code.

       --destination-port [!] [port[:port]]
              This allows separate specification  of  the  ports.
              See  the  description  of  the -s flag for details.
              The flag --dport is an alias for this option.

       --icmp-type [!] typename
              This allows specification of the ICMP type (use the
              -h icmp option to see valid ICMP type names).  This
              is often more convenient than appending it  to  the
              destination specification.

       -j, --jump target
              This  specifies the target of the rule; ie. what to
              do if the packet matches it.  The target can  be  a
              user-defined chain (not the one this rule is in) or
              one of the special targets which decide the fate of
              the  packet immediately.  If this option is omitted
              in a rule, then matching  the  rule  will  have  no
              effect  on  the  packet's fate, but the counters on
              the rule will be incremented.

       -i, --interface [!] name
              Optional name of an interface via which a packet is
              received (for packets entering the input chain), or
              via which is packet is going to be sent (for  pack­
              ets  entering  the forward or output chains).  When
              this  option  is  omitted,  the  empty  string   is
              assumed, which has a special meaning and will match
              with any interface name.  When the "!"  argument is
              used  before  the  interface  name,  the  sense  is
              inverted.  If the interface name  ends  in  a  "+",
              then any interface which begins with this name will
              match.

       [!]  -f, --fragment
              This means that the rule only refers to second  and
              further  fragments  of  fragmented  packets.  Since
              there is no way to tell the source  or  destination
              ports  of  such  a  packet  (or  ICMP type), such a
              packet will not match any rules which specify them.
              When  the  "!" argument precedes the "-f" flag, the


   OTHER OPTIONS
       The following additional options can be specified:

       -b, --bidirectional
              Bidirectional mode.  The rule will  match  with  IP
              packets  in  both  directions;  this  has  the same
              effect as repeating the rule with the source & des­
              tination  reversed.   Note  that this does NOT mean
              that if you allow TCP syn packets out, the -b  rule
              will  allow  non-SYN  packets  back in: the reverse
              rule is exactly the same as the rule  you  entered.
              This means that it's usually better to simply avoid
              the -b flag and spell the rules out explicitly.

       -v, --verbose
              Verbose output.  This option makes the list command
              show  the  interface  address, the rule options (if
              any), and the TOS masks.  The packet and byte coun­
              ters  are  also listed, with the suffix 'K', 'M' or
              'G' for 1000, 1,000,000 and 1,000,000,000 multipli­
              ers  respectively  (but  see  the -x flag to change
              this).  When used in combination with -M,  informa­
              tion related to delta sequence numbers will also be
              listed.  For  appending,  insertion,  deletion  and
              replacement,  this  causes  detailed information on
              the rule or rules to be printed.

       -n, --numeric
              Numeric output.  IP addresses and port numbers will
              be printed in numeric format.  By default, the pro­
              gram will try to display them as host  names,  net­
              work names, or services (whenever applicable).

       -l, --log
              Turn  on  kernel logging of matching packets.  When
              this option is set for a  rule,  the  Linux  kernel
              will print some information of all matching packets
              (like most IP header fields) via printk().

       -o, --output [maxsize]
              Copy matching  packets  to  the  userspace  device.
              This is currently mainly for developers who want to
              play with firewalling effects  in  userspace.   The
              optional  maxsize argument can be used to limit the
              maximum number of bytes from the packet  which  are
              to  be  copied.   This  option is only valid if the
              kernel  has  been  compiled  with   CONFIG_IP_FIRE­
              WALL_NETLINK set.

       -m, --mark markvalue
              Mark  matching packets.  Packets can be marked with
              a 32-bit unsigned value which may (one day)  change

              kernel hacker you are unlikely to care about  this.
              If  the string markvalue begins with a + or -, then
              this value will be added  or  subtracted  from  the
              current marked value of the packet (which starts at
              zero).

       -t, --TOS andmask xormask
              Masks used for modifying the TOS field  in  the  IP
              header.   When  a  packet  matches  a rule, its TOS
              field is first bitwise and'ed with first  mask  and
              the  result of this will be bitwise xor'ed with the
              second mask.  The masks should be specified as hex­
              adecimal 8-bit values.  As the LSB of the TOS field
              must be unaltered  (RFC  1349),  TOS  values  which
              would  cause  it to be altered are rejected, as are
              any rules which always set more than one  TOS  bit.
              Rules which might set multiple TOS bits for certain
              packets result in warnings (sent to  stdout)  which
              can  be ignored if you know that packets with those
              TOS values will never reach that rule.   Obviously,
              manipulating  the  TOS  is a meaningless gesture if
              the rule's target is DENY or REJECT.

       -x, --exact
              Expand numbers.  Display the  exact  value  of  the
              packet  and  byte  counters,  instead  of  only the
              rounded number in K's (multiples of 1000) M's (mul­
              tiples of 1000K) or G's (multiples of 1000M).  This
              option is only relevant for the -L command.

       [!] -y, --syn
              Only match TCP packets with the SYN bit set and the
              ACK and FIN bits cleared.  Such packets are used to
              request TCP  connection  initiation;  for  example,
              blocking  such  packets coming in an interface will
              prevent incoming TCP connections, but outgoing  TCP
              connections  will  be  unaffected.   This option is
              only meaningful when the protocol type  is  set  to
              TCP.   If the "!" flag precedes the "-y", the sense
              of the option is inverted.

       --line-numbers
              When listing rules, add line numbers to the  begin­
              ning  of  each  rule,  corresponding to that rule's
              position in the chain.

       --no-warnings
              Disable all warnings.


FILES

       /proc/net/ip_fwchains
       /proc/net/ip_masquerade

       Various error messages are printed to standard error.  The
       exit  code  is  0  for  correct functioning.  Errors which
       appear to be caused by  invalid  or  abused  command  line
       parameters cause an exit code of 2, and other errors cause
       an exit code of 1.


BUGS

       If input is a terminal, and a  rule  is  inserted  in,  or
       appended to, the forward chain, and IP forwarding does not
       seem to be enabled, and --no-warnings is not specified,  a
       message  is  printed  to  standard output, warning that no
       forwarding will occur until this is rectified.  This is to
       help users unaware of the requirement (which did not exist
       in the 2.0 kernels).

       There is no way to reset the packet and byte  counters  in
       one chain only.  This is a kernel limitation.

       Loop  detection is not done in ipchains; packets in a loop
       get dropped and logged, but that's the first  you'll  find
       out about it if you inadvertantly create a loop.

       The  explanation  of  what  effect marking a packet has is
       intentionally vague until documentation describing the new
       2.1 kernel's packet scheduling routines is released.

       There  is no way to zero the policy counters (ie. those on
       the built-in chains).


NOTES

       This ipchains is very different from the  ipfwadm  by  Jos
       Vos,  as it uses the new IP firewall trees.  Its function­
       ality is a superset of ipfwadm, and there is  generally  a
       1:1  mapping of commands.  I believe the new command names
       are more rational.  There are, however, a few  changes  of
       which you should be aware.

       Fragments  are  handled  differently.  All fragments after
       the first used to be let through (which is usually  safe);
       they  can  now  be  filtered.   This means that you should
       probably add an explicit rule to accept fragments  if  you
       are  converting over.  Also, look for old accounting rules
       which check for source and  destination  ports  of  0xFFFF
       (0xFF  for  ICMP  packets)  which was the old way of doing
       accounting on fragments.

       Accounting rules are now simply integrated into the  input
       and output chains; you can simulate the old behaviour like
       so:
        ipchains -N acctin
        ipchains -N acctout
        ipchains -N acctio
        ipchains -I input -j acctio

        ipchains -I output -j acctio
        ipchains -I output -j acctout
       This creates three user-defined  chains,  acctin,  acctout
       and  acctio,  which  are  to  contain any accounting rules
       (these rules should be specified without  a  -j  flag,  so
       that the packets simply pass through them unscathed).

       A MASQ or REDIRECT target encountered by the kernel out of
       place (ie. not during a  forward  or  input  rule  respec­
       tively)  will cause a message to the syslog and the packet
       to be dropped.

       The old behaviour of SYN and ACK matching (which was  pre­
       viously  ignored for non-TCP packets) has changed; the SYN
       option is not valid for non-TCP-specific rules.

       The ACK matching option (the -k flag) is  no  longer  sup­
       ported; the combination of !  and -y will give the equiva­
       lent).

       It is now illegal to specify a TOS mask which will set  or
       alter  the least significant TOS bit; previously TOS masks
       were silently altered by the kernel if they  tried  to  do
       this.

       The -b flag is now handled by simply inserting or deleting
       a pair of rules, one with the source and destination spec­
       ifications reversed.

       There  is  no  way to specify an interface by address: use
       its name.


SEE ALSO

       ipfw(4)


AUTHOR

       Rusty Russell <rusty@linuxcare.com>.  Thanks also to  Hans
       Persson  for detailed proofreading; I want him to read all
       my future documents!


Man(1) output converted with man2html