IPFIREWALL(4) BSD Kernel Interfaces Manual IPFIREWALL(4)
NAME
iippffiirreewwaallll - IP packet filter and traffic accounting
SYNOPSIS
##iinncclluuddee <>
##iinncclluuddee <>
##iinncclluuddee <>
##iinncclluuddee <>
int
sseettssoocckkoopptt(rawsocket, IPPROTOIP, ipfw option, struct ipfw, size);
DESCRIPTION
IPFirewall (sometimes referred to as "ipfw") is a system facility which
allows filtering, redirecting, and other operations on IP packets travel-
ling through network interfaces. Packets are matched by applying an
ordered list of pattern rules against each packet until a match is found,
at which point the corresponding action is taken. Rules are numbered
from 1 to 65534; multiple rules may share the same number.
There is one rule that always exists, rule number 65535. This rule nor-
mally causes all packets to be dropped. Hence, any packet which does not
match a lower numbered rule will be dropped. However, the kernel compile
time option IPFIREWALLDEFAULTTOACCEPT allows the administrator to
change this fixed rule to permit everything.
The buffer passed down via the socket-option call should contain a
"struct ipfw" that is initialized with the required parameters for the
firewall command being invoked. This structure is consistently required
for every firewall command, even though in some cases the majority of its
fields will go unused. The reason for this is the API versioning that
the firewall supports for the sake of backward compatibility. The
version field of this structure should always be set to
IPFWCURRENTAPIVERSION or an EINVAL error will be returned.
CCoommmmaannddss
The following socket options are used to manage the rule list:
IPFWADD inserts the rule into the rule list
IPFWDEL deletes all rules having the matching rule number
IPFWGET returns the (first) rule having the matching rule number
IPFWZERO zeros the statistics associated with all rules having the
matching rule number. If the rule number is zero, all rules
are zeroed.
IPFWFLUSH removes all rules (except 65535).
When the kernel security level is greater than 2, only IPFWGET is
allowed.
RRuullee SSttrruuccttuurree
Rules are described by the following structure:
/* One ipfw rule */
struct ipfw {
uint32t version; /* Version of this structure. Should always be */
/* set to IPFWCURRENTAPIVERSION by clients. */
void *context; /* Context that is usable by user processes to */
/* identify this rule. */
uint64t fwpcnt,fwbcnt; /* Packet and byte counters */
struct inaddr fwsrc, fwdst; /* Source and destination IP addr */
struct inaddr fwsmsk, fwdmsk; /* Mask for src and dest IP addr */
ushort fwnumber; /* Rule number */
uint fwflg; /* Flags word */
#define IPFWMAXPORTS 10 /* A reasonable maximum */
union {
ushort fwpts[IPFWMAXPORTS]; /* Array of port numbers to match */
#define IPFWICMPTYPESMAX 128
#define IPFWICMPTYPESDIM (IPFWICMPTYPESMAX / (sizeof(unsigned) * 8))
unsigned fwicmptypes[IPFWICMPTYPESDIM]; /* ICMP types bitmap */
} fwuar;
uint fwipflg; /* IP flags word */
uchar fwipopt,fwipnopt; /* IP options set/unset */
uchar fwtcpopt,fwtcpnopt; /* TCP options set/unset */
uchar fwtcpf,fwtcpnf; /* TCP flags set/unset */
long timestamp; /* timestamp (tvsec) of last match */
union ipfwif fwinif, fwoutif; /* Incoming and outgoing interfaces */
union {
ushort fudivertport; /* Divert/tee port (options IPDIVERT) */
ushort fupipenr; /* queue number (option DUMMYNET) */
ushort fuskiptorule; /* SKIPTO command rule number */
ushort furejectcode; /* REJECT response code */
struct sockaddrin fufwdip;
} fwun;
uchar fwprot; /* IP protocol */
/*
* N'of src ports and # of dst ports in ports array (dst ports
* follow src ports; max of 10 ports in all; count of 0 means
* match all ports)
*/
uchar fwnports;
void *pipeptr; /* flowset ptr for dummynet pipe */
void *nextruleptr ; /* next rule in case of match */
uidt fwuid; /* uid to match */
int fwlogamount; /* amount to log */
uint64t fwloghighest; /* highest number packet to log */
};
The ipfw.h header also contains macros for setting the fwports field and various
flags and constants for setting other fields.
RRuullee AAccttiioonnss
Each rule has an action described by the IPFWFCOMMAND bits in the
flags word:
IPFWFDENY drop packet
IPFWFREJECT drop packet; send rejection via ICMP or TCP
IPFWFACCEPT accept packet
IPFWFCOUNT increment counters; continue matching
IPFWFDIVERT divert packet to a divert(4) socket
IPFWFTEE copy packet to a divert(4) socket; continue
IPFWFSKIPTO skip to rule number fuskiptorule
In the case of IPFWFREJECT, if the furejectcode is a number from 0
to 255, then an ICMP unreachable packet is sent back to the original
packet's source IP address, with the corresponding code. Otherwise, the
value must be 256 and the protocol IPPROTOTCP, in which case a TCP reset
packet is sent instead.
With IPFWFSKIPTO, all succeeding rules having rule number less than
fuskiptorule are skipped.
Kernel Options Options in the kernel configuration file:
ooppttiioonnss IIPPFFIIRREEWWAALLLL enable iippffiirreewwaallll
ooppttiioonnss IIPPFFIIRREEWWAALLLLVVEERRBBOOSSEE enable firewall logging
ooppttiioonnss IIPPFFIIRREEWWAALLLLVVEERRBBOOSSEELLIIMMIITT limit firewall logging
ooppttiioonnss IIPPDDIIVVEERRTT enable divert(4) sockets
When packets match a rule with the IPFWFPRN bit set, and if
IPFIREWALLVERBOSE has been enabled,a message is written to /dev/klog
with the LOGSECURITY facility (see syslog(3)) for further logging by
syslogd(8); IPFIREWALLVERBOSELIMIT limits the maximum number of times
each rule can cause a log message. These variables are also available via
the sysctl(3) interface.
RETURN VALUES
The sseettssoocckkoopptt() function returns 0 on success. Otherwise, -1 is
returned and the global variable errno is set to indicate the error.
EERRRROORRSS
The sseettssoocckkoopptt() function will fail if:
[EINVAL] The IP option field was improperly formed; an option
field was shorter than the minimum value or longer
than the option buffer provided.
[EINVAL] A structural error in ipfw structure occurred
(nsrcp+ndstp too big, ports set for ALL/ICMP pro-
tocols etc.).
[EINVAL] The version field of the ipfw structure was set to a
value not supported by the currently-installed
IPFirewall, or no ipfw structure was passed to it at
all.
[EINVAL] An invalid rule number was used.
SEE ALSO
setsockopt(2), divert(4), ip(4), ipfw(8), sysctl(8), syslogd(8)
BUGS
The ``tee'' rule is not yet implemented (currently it has no effect).
This man page still needs work.
HISTORY The ipfw facility was initially written as package to BSDI by Daniel
Boulet . It has been heavily modified and
ported to FreeBSD by Ugen J.S. Antsilevich .
Several enhancements added by Archie Cobbs .
Darwin June 22, 1997 Darwin