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  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.
       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
	      affected 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 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.

       -h, --help
	      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.

       --source-port [!] [port[:port]]
	      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
	      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.  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
	      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 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

DIAGNOSTICS
       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 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 (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!



			 February 8, 1998	      IPCHAINS(8)
