ipchains - IP firewall administration
ipchains -[ADC] chain rule-specification
ipchains -[RI] chain rulenum rule-specification
ipchains -D chain rulenum [options]
ipchains -[LFZNX] [chain] [options]
ipchains -P chain target [options]
ipchains -M [ -L | -S ] [options]
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
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
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; 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_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.
The options that are recognized by ipchains
can be divided into several different groups.
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
- -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
- -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
- -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 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 (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.
The following parameters make up a rule
specification (as used in the add, delete, replace, append and
- -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] [!]
- 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
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 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
The following additional options can be
- -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
- -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.
- When listing rules, add line numbers to the beginning of each
rule, corresponding to that rule's position in the chain.
- Disable all warnings.
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.
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
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
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
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
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
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
There is no way to specify an interface by address: use its
Rusty Russell <email@example.com>. Thanks
also to Hans Persson for detailed proofreading; I want him to read
all my future documents!