ipchains



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 cate-
       gories:  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 tar-
       get,  which can be the name of a user-defined chain, or one of the spe-
       cial 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 indi-
       cating that the packet was dropped.  (Note that DENY and REJECT are the
       same for ICMP packets). [Note:  this  is  incorrect;  setting  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, 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_TRANSPAR-
       ENT_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 combina-
              tion.

       -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 des-
              tination 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  coun-
              ters  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  ref-
              erences  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  sec-
              tion 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 connec-
              tions (in conjuction 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 (inter-
              face) 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 speci-
              fied protocol can be one of tcp, udp, icmp, or all, or it can be
              a  numeric  value, representing one of these protocols or a dif-
              ferent  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 net-
              work name, or a plain IP address.  The mask can be either a net-
              work 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 specifica-
              tion 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 speci-
              fication or an ICMP type.  An inclusive range can also be speci-
              fied, 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 conve-
              nient 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 incre-
              mented.

       -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 frag-
              ments  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  multipli-
              ers  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 appli-
              cable).

       -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 cur-
              rently 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 hexadec-
              imal  8-bit  values.   As the LSB of the TOS field must be unal-
              tered (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 mean-
              ingful 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  inad-
       vertantly 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 speci-
       fied 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(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)

Man(1) output converted with man2html