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.
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-
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
(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
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.
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
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)