Computer Science
IPFW(4) IPFW(4)
NAME
ipfw - IP firewall
SYNOPSIS
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <linux/ip.h>
#include <linux/tcp.h>
#include <linux/udp.h>
#include <linux/icmp.h>
#include <linux/if.h>
#include <linux/ip_fwchains.h>
int setsockopt (int socket, IPPROTO_IP, int command, void
*data, int length)
DESCRIPTION
The IP firewall facilities in the Linux kernel provide
mechanisms for accounting IP packets, for building fire-
walls based on packet-level filtering, for building fire-
walls using transparent proxy servers (by redirecting
packets to local sockets), and for masquerading forwarded
packets. The administration of these functions is main-
tained in the kernel as a series of separated table (here-
after referred to as chains) each containing zero or more
rules. There are three builtin chains which are called
input, forward and output which always exist. All other
chains are user defined. A chain is a sequence of rules;
each rule contains specific information about source and
destination addresses, protocols, port numbers, and some
other characteristics. Information about what to do if a
packet matches the rule is also contained. A packet will
match with a rule when the characteristics of the rule
match those of the IP packet.
A packet always traverses a chain starting at rule number
1. Each rule specifies what to do when a packet matches.
If a packet does not match a rule, the next rule in that
chain is tried. If the end of a builtin chain is reached
the a default policy for that chain is returned. If the
end of a user defined chain is reached then the rule after
the rule which branched to that chain is tried. The pur-
pose of the three builtin chains are
Input firewall
These rules regulate the acceptance of incoming IP
packets. All packets coming in via one of the
local network interfaces are checked against the
input firewall rules (locally-generate packets are
considered to come from the loopback interface). A
rule which matches a packet will cause the rule's
packet and byte counters to be incremented appro-
priately.
Forwarding firewall
These rules define the permissions for forwarding
IP packets. All packets sent by a remote host hav-
ing another remote host as destination are checked
against the forwarding firewall rules. A rule
which matches will cause the rule's packet and byte
counters to be incremented appropriately.
Output firewall
These rules define the permissions for sending IP
packets. All packets that are ready to be be sent
via one of the local network interfaces are checked
against the output firewall rules. A rule which
matches will cause the rule's packet and byte coun-
ters to be incremented appropriately.
Each of the firewall rules contains either a branch name
or a policy, which specifies what action has to be taken
when a packet matches with the rule. There are 5 differ-
ent policies possible: ACCEPT (let the packet pass the
firewall), REJECT (do not accept the packet and send an
ICMP host unreachable message back to the sender as noti-
fication), DENY (sometimes referred to as block) (ignore
the packet without sending any notification), REDIRECT
(redirected to a local socket - input rules only) and MASQ
(pass the packet, but perform IP masquerading - forwarding
rules only)
The last two are special; for REDIRECT, the packet will be
received by a local process, even if it was sent to
another host and/or another port number. This function
only applies to TCP or UDP packets.
For MASQ, the sender address in the IP packets is replaced
by the address of the local host and the source port in
the TCP or UDP header is replaced by a locally generated
(temporary) port number before being forwarded. Because
this administration is kept in the kernel, reverse packets
(sent to the temporary port number on the local host) are
recognized automatically. The destination address and
port number of these packets will be replaced by the orig-
inal address and port number that was saved when the first
packet was masqueraded. This function only applies to TCP
or UDP packets.
There is also a special target RETURN which is equivalent
to falling off the end of the chain.
This paragraph describes the way a packet goes through the
firewall. Packets received via one of the local network
interface will pass the following chains:
input firewall (incoming device) Here, the device
(network interface) that is used when trying to
match a rule with an IP packet is listed between
brackets. After this step, a packet will option-
ally be redirected to a local socket. When a
packet has to be forwarded to a remote host, it
will also pass the next set of rules: forwarding
firewall (outgoing device) After this step, a
packet will optionally be masqueraded. Responses
to masqueraded packets will never pass the forward-
ing firewall (but they will pass both the input and
output firewalls). All packets sent via one of the
local network interfaces, either locally generated
or being forwarded, will pass the following sets of
rules: output firewall (outgoing device)
When a packet enters one of the three above chains rules
are traversed from the first rule in order. When
analysing a rule one of three things may occur.
Rule unmatched:
If a rules is unmatched then the next rule in that
chain is analysed. If there are no more rules for
that chain the default policy for that chain is
returned (or traversal continues back at the call-
ing chain, in the case of a user-defined chain).
Rule matched (with branch to chain):
When a rule is matched by a packet and the rule
contains a branch field then a jump/branch to that
chain is made. Jumps can only be made to user
defined chains. As described above, when the end
of a builtin chain is reached then a default policy
is returned. If the end of a used defined chain is
reached then we return to the rule from whence we
came.
There is a reference counter at the head of each
chain which determines the number of references to
that chain. The reference count of a chain must be
zero before it can be deleted to ensure that no
branches are effected. To ensure the builtin
chains are never deleted their reference count is
initialised to one. Also since no branches to
builtin chains can be made, their reference counts
are always one. The reference count on user
defined chains are initialised to zero and are
changed accordingly when rules are inserted,
deleted etc.
Multiple jumps to different chains are possible
which unfortunately make loops possible. Loop
detection is therefore provided. Loops are
detected when a packet tries to re-enter a chain it
is already traversing. An example of a simple loop
that could be created is if we set up two user
defined chains called "test1" and "test2". We
firstly insert a rule in the "input" chain which
jumps to "test1". We then create a rule in the
"test1" chain which points to "test2" and a rule in
"test2" which points to "test1". Here we have
obviously created a loop. When a packet then
enters the input chain it will branch to the
"test1" chain and then to the "test2" chain. From
here it will try to branch back to the "test1"
chain. A message in the syslog will be recorded
along with the path which the packet traversed, to
assist in debugging firewall rules.
Rule matched (special branch):
The special labels ACCEPT, DENY, REJECT, REDIRECT,
MASQ or RETURN can be given which specify the imme-
diate fate of the packet as discussed above. If no
of labels is specified then the next rule in the
chain is analysed.
Using this last option (no label) an accounting
chain can be created. If each of the rules in this
accounting chain have no branch or label then the
packet will always fall through to the end of the
chain and then return to the calling chain. Each
rule that matches in the accounting chain will have
its byte and packet counters incremented as
expected. This accounting chain can be branched to
from any other chain (eg input, forward or output
chain). This is a very neat way of performing
packet accounting.
The firewall administration can be changed via calls to
setsockopt(2). The existing rules can be inspected by
looking at 2 files in the /proc/net directory:
ip_fwchains, ip_fwnames. The current administration
related to masqueraded sessions can be found in the file
ip_masquerade in the same directory
COMMANDS
Command for changing and setting up chains and rules is
ipchains(8) Most commands require some additional data to
be passed. A pointer to this data and the length of the
data are passed as option value and option length argu-
ments to setsockopt. The following commands are avail-
able:
IP_FW_INSERT
This command allows a rule to be inserted in a
chain at a given position (where 1 is considered
the start of the chain). If there is already a
rule in that position, it is moved one slot, as are
any preceding rules in that chain. The reference
count of any chains referenced by this inserted
rule are incremented appropriately. The data
passed with this command is an ip_fwnew structure,
defining the position, chain and contents of the
new rule.
IP_FW_DELETE
Remove the first rule matching the specification
from the given chain. The data passed with this
command is an ip_fwchange structure, defining the
rule to be deleted and its chain. The reference
count of any chains referenced by this deleted rule
are decremented appropriately. Note that the
fw_mark field is currently ignored in rule compar-
isons (see the BUGS section).
IP_FW_DELETE_NUM
Remove a rule from one of the chains at a given
rule number (where 1 means the first rule). The
data passed with this command is an ip_fwdelnum
structure, defining the rule number of the rule to
be deleted and its chain. The reference count of
any chains referenced by this deleted rule are
decremented appropriately.
IP_FW_ZERO
Reset the packet and byte counters in all rules of
a chain. The data passed with this command is an
ip_chainlabel which defines the chain which is to
be operated on. See also the description of the
/proc/net files for a way to atomically list and
reset the counters.
IP_FW_FLUSH
Remove all rules from a chain. The data passed
with this command is a ip_chainlabel which defines
the chain to be operated on.
IP_FW_REPLACE
Replace a rule in a chain. The new rule overwrites
the rule in the given position. Any chains refer-
enced by the new rule are incremented and chains
referenced by the overwritten rule are decremented.
The data passed with this command is an ip_fwnew
structure, defining the contents of the new rule,
the the chain name and the position of the rule in
that chain.
IP_FW_APPEND
Insert a rule at the end of one of the chains. The
data passed with this command is an ip_fwchange
structure, defining the contents of the new rule
and the chain to which it is to be appended. Any
chains referenced by this new rule have their ref-
count incremented.
IP_FW_MASQ_TIMEOUTS
Set the timeout values used for masquerading. The
data passed with this command is a structure con-
taining 3 fields of type int, representing the
timeout values (in jiffies, 1/HZ second) 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.
IP_FW_CHECK
Check whether a packet would be accepted, denied,
rejected, redirected or masqueraded by a chain.
The data passed with this command is an ip_fwtest
structure, defining the packet to be tested and the
chain which it is to be test on. Both builtin and
user defined chains can be tested.
IP_FW_CREATECHAIN
Create a chain. The data passed with this command
is an ip_chainlabel defining the name of the chain
to be created. Two chains can not have the same
name.
IP_FW_DELETECHAIN
Delete a chain. The data passed with this command
is an ip_chainlabel defining the name of the chain
to be deleted. The chain must not be referenced by
any rule (ie. refcount must be zero). The chain
must also be empty which can be achieved using
IP_FW_FLUSH.
IP_FW_POLICY
Changes the default policy on a builtin rule. The
data passed with this command is an ip_fwpolicy
structure, defining the chain whose policy is to be
changed and the new policy. The chain must be a
builtin chain as user-defined chains don't have
default policies.
STRUCTURES
The ip_fw structure contains the following relevant fields
to be filled in for adding or replacing a rule:
struct in_addr fw_src, fw_dst
Source and destination IP addresses.
struct in_addr fw_smsk, fw_dmsk
Masks for the source and destination IP addresses.
Note that a mask of 0.0.0.0 will result in a match
for all hosts.
char fw_vianame[IFNAMSIZ]
Name of the interface via which a packet is
received by the system or is going to be sent by
the system. If the option IP_FW_F_WILDIF is speci-
fied, then the fw_vianame need only match the
packet interface up to the first NUL character in
fw_vianame. This allows wildcard-like effects.
The empty string has a special meaning: it will
match with all device names.
__u16 fw_flg
Flags for this rule. The flags for the different
options can be bitwise or'ed with each other.
The options are: IP_FW_F_TCPSYN (only matches with
TCP packets when the SYN bit is set and both the
ACK and RST bits are cleared in the TCP header,
invalid with other protocols), The option
IP_FW_F_MARKABS is described under the fw_mark
entry. The option IP_FW_F_PRN can be used to list
some information about a matching packet via
printk(). The option IP_FW_F_FRAG can be used to
specify a rule which applies only to second and
succeeding fragments (initial fragments can be
treated like normal packets for the sake of fire-
walling). Non-fragmented packets and initial frag-
ments will never match such a rule. Fragments do
not contain the complete information assumed for
most firewall rules, notably ICMP type and code,
UDP/TCP port numbers, or TCP SYN or ACK bits.
Rules which try to match packets by these criteria
will never match a (non-first) fragment. The
option IP_FW_F_NETLINK can be specified if the ker-
nel has been compiled with CONFIG_IP_FIRE-
WALL_NETLINK enabled. This means that all matching
packets will be sent out the firewall netlink
device (character device, major number 36, minor
number 3). The output of this device is four bytes
indicating the mark value of the packet (as
describe under fw_mark above), a string of IFNAMSIZ
characters containing the interface name for the
packet, and then the packet itself. The packet is
truncated to fw_outputsize bytes if it is longer.
__u16 fw_invflg
This field is a set of flags used to negate the
meaning of other fields, eg. to specify that a
packet must NOT be on an interface. The valid
flags are IP_FW_INV_SRCIP (invert the meaning of
the fw_src field) IP_FW_INV_DSTIP (invert the mean-
ing of fw_dst) IP_FW_INV_PROTO (invert the meaning
of fw_proto) IP_FW_INV_SRCPT (invert the meaning of
fw_spts) IP_FW_INV_DSTPT (invert the meaning of
fw_dpts) IP_FW_INV_VIA (invert the meaning of
fw_vianame) IP_FW_INV_SYN (invert the meaning of
fw_flg & IP_FW_F_TCPSYN) IP_FW_INV_FRAG (invert the
meaning of fw_flg & IP_FW_F_FRAG). It is illegal
(and useless) to specify a rule that can never be
matched, by inverting an all-inclusive set. Note
also, that a fragment will never pass any test on
ports or SYN, even an inverted one.
__u16 fw_proto
The protocol that this rule applies to. The proto-
col number 0 is used to mean `any protocol'.
__u16 fw_spts[2], fw_dpts[2]
These fields specify the range of source ports, and
the range of destination ports respectively. The
first array element is the inclusive minimum, and
the second is the inclusive maximum. Unless the
rule specifies a protocol of TCP, UDP or ICMP, the
port range must be 0 to 65535. For ICMP, the
fw_spts field is used to check the ICMP type, and
the fw_dpts field is used to check the ICMP code.
__u16 fw_redirpt
This field must be zero unless the target of the
rule is "REDIRECT". Otherwise, if this redirection
port is 0, the destination port of a packet will be
used as the redirection port.
__u32 fw_mark
This field indicates a value to mark the skbuff
with (which contains the administration data for
the matching packet). This is currently unused,
but could be used to control how individual packets
are treated. If the IP_FW_F_MARKABS flag is set
then the value in fw_mark simply replaces the cur-
rent mark in the skbuff, rather than being added to
the current mark value which is normally done. To
subtract a value, simply use a large number for
fw_mark and 32-bit wrap-around will occur.
__u8 fw_tosand, fw_tosxor
These 8-bit masks define how the TOS field in the
IP header should be changed when a packet is
accepted by the firewall rule. The TOS field is
first bitwise and'ed with fw_tosand and the result
of this will be bitwise xor'ed with fw_tosxor.
Obviously, only packets which match the rule have
their TOS effected. It is the responsibility of
the user that packets with invalid TOS bits are not
created using this option.
The ip_fwuser structure, used when calling some of the
above commands contains the following fields:
struct ip_fw ipfw
See above
ip_chainlabel label This is the label of the chain which
is to be operated on.
The ip_fwpkt structure, used when checking a packet, con-
tains the following fields:
struct iphdr fwp_iph
The IP header. See <linux/ip.h> for a detailed
description of the iphdr structure.
struct tcphdr fwp_protoh.fwp_tcph
struct udphdr fwp_protoh.fwp_udph
struct icmphdr fwp_protoh.fwp_icmph
The TCP, UDP, or ICMP header, combined in a union
named fwp_protoh. See <linux/tcp.h>,
<linux/udp.h>, or <linux/icmp.h> for a detailed
description of the respective structures.
struct in_addr fwp_via
The interface address via which the packet is pre-
tended to be received or sent.
CHANGES
The ability to add in extra chains other than just the
standard input, output and forward chains is very power-
ful. The ability to branch to any chain makes the repli-
cation of rules unnecessary. Accounting becomes automatic
as a single chain can be referenced by all builtin chains
to do the accounting.
Fragments must now be handled explicitly; previously sec-
ond and succeeding fragments were passed automatically.
The lowest TOS bit (MBZ) could not be effected previously;
the kernel used to silently mask out any attempted manipu-
lation of the lowest TOS bit. (``So now you know how to
do it - DON'T.'').
The packet and byte counters are now 64-bit on 32-bit
machines (actually presented as 2 32-bit values).
The ability to specify an interface by an IP address was
obsoleted by the ability to specify it by name; the combi-
nation of the two was error-prone and so only an interface
name can now be used.
The old IP_FW_F_TCPACK flag was made obsolete by the abil-
ity to invert the IP_FW_F_TCPSYN flag.
The old IP_FW_F_BIDIR flag made the kernel code complex
and is no longer supported.
The ability to specify several ports in one rule was messy
and didn't win much, so has been removed.
RETURN VALUE
On success (or a straightforward packet accept for the
CHECK options), zero is returned. On error, -1 is
returned and errno is set appropriately. See setsock-
opt(2) for a list of possible error values. ENOENT indi-
cates that given chain name doesn't exist. When the check
packet command is used, zero is returned when the packet
would be accepted without redirection or masquerading.
Otherwise, -1 is returned and errno is set to ECONNABORTED
(packet would be accepted using redirection), ECONNRESET
(packet would be accepted using masquerading), ETIMEDOUT
(packet would be denied), ECONNREFUSED (packet would be
rejected), ELOOP (packet got into a loop), ENFILE
(packet fell off end of chain (only occurs for used
defined chains)).
LISTING RULES
In the directory /proc/net there are 2 entries to list the
currently defined rules and chains: ip_fwnames (for IP
firewall chain names) One line per chain. Contains the
chain name, policy, the number of references to that chain
and the packet and byte counters which have matched the
policy (represented as two pairs of 32-bit numbers; most
significant 32-bits first). ip_fwchains (for IP firewall
chains) One line per rule; rules are listed one chain at a
time (from first to last as they appear in
/proc/net/ip_fwnames) and in order from first to last down
each chain.
The fields are: the chain name for that rule, source
address and mask, destination address and mask, interface
name (or "-"), the fw_flg field, the fw_invflg field, pro-
tocol number, packet and byte counters, the source and
destination port ranges, the TOS and-mask, the TOS xor-
mask, the fw_redirpt field, the fw_mark field, and the
target (label). The IP addresses and masks are listed as
8 hexadecimal digits, the TOS masks are listed as 2 hex-
adecimal digits preceded by the letters A and X, respec-
tively, the fw_mark, fw_flg and fw_invflg fields are
listed in hex, and the other values are represented in
decimal format. The packet and bytes counters are repre-
sented as two space-separated 32-bit numbers, representing
the most and least significant words respectively. Indi-
vidual fields are separated by white space, by a "/" (the
address and the corresponding mask), by "->" (the source
and destination address/mask pairs), or "-" (the ranges
for source and destination ports).
The files may also be opened in read/write mode (only root
is allowed to do this). In that case, the packet and byte
counters in all the rules of that category will be reset
to zero after listing their current values.
The file /proc/net/ip_masquerade contains the kernel
administration related to masquerading. After a header
line, each masqueraded session is described on a separate
line with the following entries, separated by white space
or by ':' (the address/port number pairs): protocol name
("TCP" or "UDP"), source IP address and port number, des-
tination IP address and port number, the new port number,
the initial sequence number for adding a delta value, the
delta value, the previous delta value, and the expire time
in jiffies (1/HZ second). All addresses and numeric val-
ues are in hexadecimal format, except the last 3 entries,
being represented in decimal format.
FILES
/proc/net/ip_fwchains
/proc/net/ip_fwnames
/proc/net/ip_masquerade
BUGS
The setsockopt(2) interface is a crock. This should be
put under /proc/sys/net/ipv4 and the world would be a bet-
ter place.
There is no way to read and reset a single chain; stop
packets traversing the chain and then list, reset and
restore traffic.
The packet and byte counters should be presented in /proc
as a single 64-bit value, not two 32-bit values.
The "fw_mark" field isn't used for deletions of matching
rules. This is to facilitate the ipfwadm compatibility
script. Similarly, the IP_FW_F_MARKABS flag is ignored in
comparisons.
SEE ALSO
setsockopt(2), socket(2), ipchains(8)
November 4, 1997 1
Back to the index
