IPCHAINS(8)                                           IPCHAINS(8)

NAME
       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 the 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).
       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.
       If  the  end of a user-defined chain is reached, or a rule
       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
              effected by the other arguments given.

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

       -Z, --zero
              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 masqerading parameters
              (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.

       -h     Help.  Give a (currently very brief) description of
              the command syntax.

   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 [!] 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 specifi-
              cation or an ICMP type.  An inclusive range is  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.  The flag --src is a convenience
              alias for this option.

       --source-port [!] [port[:port]]
              This  allows  separate  specifiction  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 [!] 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.
              The flag --dst is  a  convenience  alias  for  this
              option.

       --destination-port [!] [port[:port]]
              This  allows  separate  specifiction  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  to 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, or via which is packet  is  going  to  be
              sent.   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
              furthur 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
              sense is inverted.

   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.

       -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
              how  they are handled internally.  If you are not a
              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  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 relevent 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.

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

BUGS
       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 input -j acctin
        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 ( -k) is no longer supported;  the
       combination of !  and -y will give the equivalent).

       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 <Paul.Russell@rustcorp.com.au>

                         February 8, 1998                       1