Provided by: ipchains_1.3.10-16_i386 bug

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.)
       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,  bypassing  the
       forwarding chain.
       REDIRECT  is  only  legal for the input and user-defined chains and can
       only   be   used   when   the   Linux   kernel   is    compiled    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  redirection  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 numbered 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  masqueraded
              connections (in conjunction with the -L option) or  to  set  the
              kernel masquerading parameters (with the -S option).

       -S, --set tcp tcpfin udp
              Change  the  timeout values used for masquerading.  This command
              always takes 3 parameters, representing the timeout  values  (in
              seconds)  for  TCP  sessions, TCP sessions after receiving a FIN
              packet, and UDP packets, respectively.  A timeout value 0  means
              that  the  current  timeout  value of the corresponding 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 packets 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  (destination),  -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 commands).

       -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, representing 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
              omitted.  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  description  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 packets 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 & destination 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 counters are also listed,  with  the  suffix
              ’K’,   ’M’   or   ’G’  for  1000,  1,000,000  and  1,000,000,000
              multipliers respectively (but see the -x flag to  change  this).
              When  used  in combination with -M, information 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 program will try to display
              them  as  host  names,  network  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_FIREWALL_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
              hexadecimal 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 (multiples 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  beginning  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
       inadvertently 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 functionality 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 respectively) will cause a message
       to the syslog and the packet to be dropped.

       The old behaviour of SYN and ACK matching (which was previously 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  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 specifications reversed.

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

SEE ALSO

       ipfw_chains(4), ipchains-save(8), ipchains-restore(8)

AUTHOR

       Rusty Russell.  Thanks also to Hans Persson for detailed  proofreading;
       I want him to read all my future documents!

                               February 8, 1998                    IPCHAINS(8)