Computer Science
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 the 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, 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
effected 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 masqerading parameters
(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.
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 [!] 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 specifi-
cation or an ICMP type. An inclusive range is 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. The flag --src is a convenience
alias for this option.
--source-port [!] [port[:port]]
This allows separate specifiction 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 [!] 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.
The flag --dst is a convenience alias for this
option.
--destination-port [!] [port[:port]]
This allows separate specifiction 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 to 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, or via which is packet is going to be
sent. 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
furthur 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.
-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 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 relevent 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.
FILES
/proc/net/ip_fwchains
/proc/net/ip_masquerade
BUGS
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 ( -k) 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 spec-
ifications reversed.
There is no way to specify an interface by address: use
its name.
SEE ALSO
ipfw(4)
AUTHOR
Rusty Russell <Paul.Russell@rustcorp.com.au>
February 8, 1998 1
Back to the index
