Provided by:
ipfwadm_2.3.0-4_i386 
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 masquerading
forwarded packets. The administration of these functions 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 characteristics. A
packet will match with a rule when the characteristics 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 network 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 having another remote host as
destination are checked against the forwarding 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 forwarding firewall is used.
Each of the firewall rules (not the accounting rules) contains 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
(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 original 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 forwarding 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)
accounting (outgoing device)
Note that masqueraded packets will pass the output firewall 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 directory: 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
following 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, respectively. 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 beginning 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 firewall 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 following possible values:
IP_FW_F_ACCEPT (accept a packet), IP_FW_F_ICMPRPL (reject a
packet by sending 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
forwarding firewall, the given policy may also be IP_FW_F_ACCEPT
| IP_FW_F_MASQ ®(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 containing 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 forwarding 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 meaning: 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
notification. 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 number, see below). It is only valid in
input firewall 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 CONFIG_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 protocols), IP_FW_F_TCPSYN (only matches with TCP
packets when the SYN bit is set and the ACK bit is cleared in
the TCP header, ignored with other protocols), 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 followed 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 contain 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 destination 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 firewall rules for
rejecting or denying a packet.
The ip_fwpkt structure, used when checking a packet, contains 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 pretended 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). Reading 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 preceded by the letter A and
X, repectively, and the other values are represented in decimal format.
Individual fields are separated 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, destination 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 values 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)
June 17, 1996 IPFW(4)