ipfw
Hurricane Electric Internet Services
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 a mechanism for accounting IP packets and
for building firewalls based on packet-level filtering.
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 three 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 4
different policies possible: accept (let the packet pass
the firewall in a normal way), masquerade (let the packet
pass the firewall using masquerading; this policy is only
valid for forwarding rules), 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 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/number that was saved when the first packet
was masqueraded.
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 (interface address) that is used when
trying to match a rule with an IP packet is listed between
brackets. When a packet has to be forwarded to a remote
host, it will also pass:
forwarding firewall (incoming 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 for-
warded, will pass:
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 anf 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 three 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 direc-
tory (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 firewalls, 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. For
unknown reasons, a (dummy) integer has to be passed
as data with this command. See also the descrip-
tion 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. For unknown reasons, 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_ACCEPT | IP_FW_F_MASQ (accept the
packet and additionally use masquerading),
IP_FW_F_ICMRPL (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 fire-
wall rules in the appropriate list matches the
packet being screened.
IP_FW_CHECK_IN
IP_FW_CHECK_OUT
IP_FW_CHECK_FWD
Check whether a packet would be accepted (with or
without masquerading), denied, or rejected by the
input firewall (IP_FW_CHECK_IN), the output fire-
wall (IP_FW_CHECK_OUT), or the forwarding firewall
(IP_FW_CHECK_FWD). The data passed with this com-
mand 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_ACCEPT | IP_FW_F_MASQ
(accept the packet and additionally use masquerad-
ing), or IP_FW_F_ICMRPL (reject the packet by send-
ing 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.
There are some other options that can be specified:
IP_FW_F_BIDIR (bidirectional rule, matching in both
directions), IP_FW_F_TCPACK (only matches when the
ACK bit is set in the TCP header), IP_FW_F_TCPSYN
(only matches when the SYN bit is set and the ACK
bit is cleared in the TCP header), 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_FIRE-
WALL_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. 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 two port numbers of the list are taken as the
minimum and maximum values of a 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 as if both port numbers are equal to zero.
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 (with or without masquerading) 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, 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 masquerading). Otherwise, -1
is returned and errno is set to ECONNRESET (packet would
be accepted using massquerading), 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_ACCEPT | IP_FW_F_MASQ,
IP_FW_F_ICMPRPL, or 0).
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 spave, by a '/' (the
address and the corresponding mask), or by "->" (the
sources 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)
Hurricane Electric Internet Services
Copyright (C) 1998
Hurricane Electric.
All Rights Reserved.