IPFW(4)
NAME
ipfw - IP firewall and accounting
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_fw.h>>
int setsockopt (int socket, IPPROTO_IP, int command, void
*data, int length)
DESCRIPTION
The IP firewall and accounting facilities in the Linux
kernel provide mechanisms for accounting IP packets, for
building firewalls based on packet-level filtering, for
building firewalls using transparent proxy servers (by
redirecting packets to local sockets), and for masquerad-
ing forwarded packets. The administration of these func-
tions is maintained in the kernel as 4 separate lists,
each containing zero or more rules. Each rule contains
specific information about source and destination
addresses, protocols, port numbers, and some other charac-
teristics. A packet will match with a rule when the char-
acteristics of the rule match those of the IP packet. The
4 categories of rules are:
Accounting
The accounting rules are used for all IP packets
that are sent or received via one of the local net-
work interfaces. Every packet will be compared
with all rules in this list, and every match will
cause an increment of the packet and byte counters
associated with that rule.
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. The first rule that matches
with a packet determines the policy to use and will
also cause the rule's packet en byte counters being
adapted. When no matching rule is found, the
default policy for the input firewall is used.
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. The first rule
that matches with a packet determines the policy to
use and will also cause the rule's packet and byte
counters being adapted. When no matching rule is
found, the default policy for the output firewall
is used.
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. The first
rule that matches with a packet determines the pol-
icy to use and will also cause the rule's packet
and byte counters being adapted. When no matching
rule is found, the default policy for the forward-
ing firewall is used.
Each of the firewall rules (not the accounting rules) con-
tains a policy, which specifies what action has to be
taken when a packet matches with the rule. There are 3
different 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
notification), and deny (ignore the packet without sending
any notification). For all 3 types of firewalls there
also exists a default policy, which applies to all packets
for which none of the rules match.
The input rules also define whether or not packets should
be redirected to a local socket after being accepted by
the input firewall. In this case, 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.
The forwarding rules also define whether or not packets
should be masqueraded when being forwarded. In that case,
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 (tempo-
rary) 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.
This paragraph describes the way a packet goes through the
firewall and accounting rules. Packets received via one
of the local network interface will pass the following
sets of rules:
accounting (incoming device)
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 optionally 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 for-
warding 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 for-
warded, will pass the following sets of rules:
output firewall (outgoing device)
accounting (outgoing device)
Note that masqueraded packets will pass the output fire-
wall and accounting rules with the new packet headers
(after passing the input and forwarding firewall with the
original headers). Also, responses to masqueraded packets
will have different headers when passing the input and
output firewall rules.
The firewall and accounting administration can be changed
via calls to setsockopt(2). The existing rules can be
inspected by looking at 4 files in the /proc/net direc-
tory: ip_acct, ip_input, ip_output, and ip_forward. The
current administration related to masqueraded sessions can
be found in the file ip_masquerade in the same directory
(note that the rules specifying which sessions should be
masqueraded are in ip_forward).
COMMANDS
Commands for changing the lists of rules or the default
policies have to be given as options to the setsockopt(2)
system call, working on a raw IP socket. 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 arguments to setsockopt. The fol-
lowing commands are available:
IP_ACCT_APPEND
IP_FW_APPEND_IN
IP_FW_APPEND_OUT
IP_FW_APPEND_FWD
Add a rule to one of the accounting or firewall
lists. Depending on the command, the rule is added
to the list for accounting, input firewall, output
firewall, or forwarding firewall, repectively. The
new rule rule is appended to the end of the list.
The data passed with this command is an ip_fw
structure, defining the contents of the new rule.
IP_ACCT_INSERT
IP_FW_INSERT_IN
IP_FW_INSERT_OUT
IP_FW_INSERT_FWD
These commands are equal to the append commands,
except that the new rule is inserted at the begin-
ning of the list.
IP_ACCT_DELETE
IP_FW_DELETE_IN
IP_FW_DELETE_OUT
IP_FW_DELETE_FWD
Remove a rule from one of the accounting or fire-
wall lists. Depending on the command, the rule
will be removed from the list for accounting, input
firewall, output firewall, or forwarding firewall,
repectively. The data passed with this command is
an ip_fw structure, defining the contents of the
rule to be removed. The first rule conforming to
the given definition is removed from the list.
IP_ACCT_ZERO
IP_FW_ZERO_IN
IP_FW_ZERO_OUT
IP_FW_ZERO_FWD
Reset the packet and byte counters in all rules of
the list for accounting, input firewall, output
firewall, or forwarding firewall, repectively.
Note that a (dummy) integer has to be passed as
data with this command. See also the description
of the /proc/net files for a way to atomically list
and reset the counters.
IP_ACCT_FLUSH
IP_FW_FLUSH_IN
IP_FW_FLUSH_OUT
IP_FW_FLUSH_FWD
Remove all rules from the list for accounting,
input firewall, output firewall, or forwarding
firewall, repectively. Note that a (dummy) integer
has to be passed as data with this command.
IP_FW_POLICY_IN
IP_FW_POLICY_OUT
IP_FW_POLICY_FWD
Change the default policy for the input firewall,
output firewall, or the forwarding firewall. The
new policy is passed as integer data with the fol-
lowing possible values: IP_FW_F_ACCEPT (accept a
packet), IP_FW_F_ICMPRPL (reject a packet by send-
ing an ICMP host unreachable message back to the
sender), or 0 (deny a packet, without any further
notification). The policy is used when none of the
available firewall rules in the appropriate list
matches the packet being screened. For the for-
warding firewall, the given policy may also be
IP_FW_F_ACCEPT | IP_FW_F_MASQ (R)(accept a packet
to be forwarded, but also use masquerading for TCP
and UDP packets).
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, repectively. A timeout
value 0 means that the current timeout value of the
corresponding entry is preserved.
IP_FW_CHECK_IN
IP_FW_CHECK_OUT
IP_FW_CHECK_FWD
Check whether a packet would be accepted, denied,
or rejected by the input firewall (IP_FW_CHECK_IN),
the output firewall (IP_FW_CHECK_OUT), or the for-
warding firewall (IP_FW_CHECK_FWD). The data
passed with this command is an ip_fwpkt structure,
defining the packet headers and the interface
address.
STRUCTURES
The ip_fw structure contains the following relevant fields
to be filled in for adding or deleting 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.
struct in_addr fw_via
IP address of the interface via which a packet is
received by the system or is going to be sent by
the system. The address 0.0.0.0 has a special
meaning: it will match with all interface
addresses.
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. The empty string has a special mean-
ing: it will match with all device names.
unsigned short fw_flg
Flags for this rule. The flags for the different
options can be bitwise or'ed with each other.
The protocol (mandatory). Possible values are
IP_FW_F_TCP (TCP), IP_FW_F_UDP (UDP), IP_FW_F_ICMP
(ICMP), or IP_FW_F_ALL (all protocols, which
defines a universal firewall/accounting rule).
The policy to be used when a packet matches with
this rule. This policy can be IP_FW_F_ACCEPT
(accept the packet), IP_FW_F_ICMPRPL (reject the
packet by sending an ICMP host unreachable message
back to the sender). When none of these flags is
specified, the packet is denied without any notifi-
cation. Note that the policy is ignored in
accounting rules.
Redirection and masquerading are also defined with
2 flags. IP_FW_F_REDIR redirects an accepted
packet to a local socket (specified by a port num-
ber, see below). It is only valid in input fire-
wall rules and can only be used when the kernel is
compiled with CONFIG_IP_TRANSPARENT_PROXY defined.
IP_FW_F_MASQ masquerades an accepted packet. It is
only valid in forwarding firewall rules and can
only be used when the kernel is compiled with CON-
FIG_IP_MASQUERADE defined.
The other options are: IP_FW_F_BIDIR (bidirectional
rule, matching in both directions), IP_FW_F_TCPACK
(only matches with TCP packets when the ACK bit is
set in the TCP header, ignored with other proto-
cols), IP_FW_F_TCPSYN (only matches with TCP pack-
ets when the SYN bit is set and the ACK bit is
cleared in the TCP header, ignored with other pro-
tocols), IP_FW_F_ACCTIN and IP_FW_F_ACCTOUT (only
match incoming or outgoing packets, respectively;
these options only have effect in accounting
rules), IP_FW_F_SRNG, and IP_FW_F_DRNG (see below
for a description of these flags). The option
IP_FW_F_PRN can be used to list some information
about a matching packet via printk(). This option
will only be effective when the kernel is compiled
with CONFIG_IP_FIREWALL_VERBOSE defined.
unsigned short fw_nsp, fw_ndp, fw_pts[IP_FW_MAX_PORTS]
These fields specify the number of source ports,
the number of destination ports, and the array in
which these ports are stored, respectively. The
array starts with the source ports, directly fol-
lowed by the destination ports. If the option
IP_FW_F_REDIR is used, these ports are followed by
the redirection port. If this redirection port is
0, the destination port of a packet will be used as
the redirection port. The total number of ports is
limited to IP_FW_MAX_PORTS (currently 10). Both
the list of source and destination ports may con-
tain at most one range. In that case, the first 2
port numbers of the list are taken as the minimum
and maximum values of the range. For ICMP packets,
source ports are interpreted as ICMP types and des-
tination ports are ignored. Because the second and
further fragments of a TCP or UDP packet do not
contain port numbers, these IP packets are treated
in accounting rules as if both port numbers are
equal to 65535. For the same reason, all second
and further fragments of an ICMP packet are treated
in accounting rules as if the ICMP message type is
255. Furthermore, all second and further fragments
of TCP, UDP, or ICMP packets will be accepted by
any of the 3 firewalls. The flags IP_FW_F_SRNG and
IP_FW_F_DRNG in the fw_flg field specify whether or
not a source and/or destination range is specified.
unsigned char 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. The
fields are ignored in accounting rules or in fire-
wall rules for rejecting or denying a packet.
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.
RETURN VALUE
On success, zero is returned. On error, -1 is returned
and errno is set appropriately. See setsockopt(2) for a
list of possible error values. When one of the 2 check
packet commands 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), or ECONNREFUSED (packet would be
rejected).
LISTING RULES
In the directory /proc/net there are 4 entries to list the
currently defined rules for each of the categories:
ip_acct (for IP accounting rules), ip_input (for IP input
firewall rules), ip_output (for IP output firewall rules),
and ip_forward (for IP forwarding firewall rules). Read-
ing these files results in a header line and one line for
each defined rule. For all 3 types of firewall, the
header line includes at the end a decimal representation
of the corresponding default policy (one of
IP_FW_F_ACCEPT, IP_FW_F_ICMPRPL, and 0; the policy of the
forwarding firewall may also be IP_FW_F_ACCEPT |
IP_FW_F_MASQ).
Each following line lists the contents of a rule in the
following order: source address and mask, destination
address and mask, interface address, flags, number of
source and destination ports, packet and byte counters,
the list of ports, a TOS and-mask, and a TOS xor-mask.
The IP addresses and masks are listed as 8 hexadecimal
digits, the TOS masks are listed as 2 hexadecimal digits
preceeded by the letter A and X, repectively, and the
other values are represented in decimal format. Individ-
ual fields are seperated by white space, by a '/' (the
address and the corresponding mask), or by "->" (the
source and destination address/mask pairs).
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_acct
/proc/net/ip_input
/proc/net/ip_output
/proc/net/ip_forward
/proc/net/ip_masquerade
SEE ALSO
setsockopt(2) socket(2) ipfwadm(8)