1.Dd June 22, 1997
2.Dt IPFIREWALL 4
3.Os Darwin
4.Sh NAME
5.Nm ipfirewall
6.Nd IP packet filter and traffic accounting
7.Sh SYNOPSIS
8.Fd #include <sys/types.h>
9.Fd #include <sys/queue.h>
10.Fd #include <netinet/in.h>
11.Fd #include <netinet/ip_fw.h>
12.Ft int
13.Fn setsockopt raw_socket IPPROTO_IP "ipfw option" "struct ipfw" size
14.\"--------------------------------------------------------------------------------------------
15.Sh DESCRIPTION
16.\"--------------------------------------------------------------------------------------------
17IPFirewall (sometimes referred to as "ipfw") is a system facility which allows filtering,
18redirecting, and other operations on IP packets travelling through network interfaces.  Packets
19are matched by applying an ordered list of pattern rules against each packet until a match is
20found, at which point the corresponding action is taken.  Rules are numbered from 1 to 65534;
21multiple rules may share the same number.
22.Pp
23There is one rule that always exists, rule number 65535.  This rule normally causes all packets
24to be dropped.  Hence, any packet which does not match a lower numbered rule will be dropped.
25However, the kernel compile time option
26.Dv IPFIREWALL_DEFAULT_TO_ACCEPT
27allows the administrator to change this fixed rule to permit everything.
28.Pp
29The buffer passed down via the socket-option call should contain a "struct ip_fw" that is
30initialized with the required parameters for the firewall command being invoked.  This
31structure is consistently required for every firewall command, even though in some cases
32the majority of its fields will go unused.  The reason for this is the API versioning that
33the firewall supports for the sake of backward compatibility.  The
34.Dv version
35field of this
36structure should always be set to
37.Dv IP_FW_CURRENT_API_VERSION
38or an EINVAL error will be returned.
39.Ss Commands
40The following socket options are used to manage the rule list:
41.Bl -tag -width "IP_FW_FLUSH"
42.It Dv IP_FW_ADD
43inserts the rule into the rule list
44.It Dv IP_FW_DEL
45deletes all rules having the matching rule number
46.It Dv IP_FW_GET
47returns the (first) rule having the matching rule number
48.It Dv IP_FW_ZERO
49zeros the statistics associated with all rules having the
50matching rule number.
51If the rule number is zero, all rules are zeroed.
52.It Dv IP_FW_FLUSH
53removes all rules (except 65535).
54.El
55.Pp
56When the kernel security level is greater than 2, only
57.Dv IP_FW_GET
58is allowed.
59.\"--------------------------------------------------------------------------------------------
60.Ss Rule Structure
61.\"--------------------------------------------------------------------------------------------
62Rules are described by the following structure:
63.Bd -literal
64/* One ipfw rule */
65struct ip_fw {
66    u_int32_t version;              /* Version of this structure.  Should always be */
67                                    /* set to IP_FW_CURRENT_API_VERSION by clients. */
68    void *context;                  /* Context that is usable by user processes to */
69                                    /* identify this rule. */
70    u_int64_t fw_pcnt,fw_bcnt;          /* Packet and byte counters */
71    struct in_addr fw_src, fw_dst;      /* Source and destination IP addr */
72    struct in_addr fw_smsk, fw_dmsk;    /* Mask for src and dest IP addr */
73    u_short fw_number;                  /* Rule number */
74    u_int fw_flg;                       /* Flags word */
75#define IP_FW_MAX_PORTS 10              /* A reasonable maximum */
76        union {
77        u_short fw_pts[IP_FW_MAX_PORTS];        /* Array of port numbers to match */
78#define IP_FW_ICMPTYPES_MAX     128
79#define IP_FW_ICMPTYPES_DIM     (IP_FW_ICMPTYPES_MAX / (sizeof(unsigned) * 8))
80        unsigned fw_icmptypes[IP_FW_ICMPTYPES_DIM]; /* ICMP types bitmap */
81        } fw_uar;
82    u_int fw_ipflg;                     /* IP flags word */
83    u_char fw_ipopt,fw_ipnopt;          /* IP options set/unset */
84    u_char fw_tcpopt,fw_tcpnopt;        /* TCP options set/unset */
85    u_char fw_tcpf,fw_tcpnf;            /* TCP flags set/unset */
86    long timestamp;                     /* timestamp (tv_sec) of last match */
87    union ip_fw_if fw_in_if, fw_out_if; /* Incoming and outgoing interfaces */
88    union {
89        u_short fu_divert_port;         /* Divert/tee port (options IPDIVERT) */
90        u_short fu_pipe_nr;             /* queue number (option DUMMYNET) */
91        u_short fu_skipto_rule;         /* SKIPTO command rule number */
92        u_short fu_reject_code;         /* REJECT response code */
93        struct sockaddr_in fu_fwd_ip;
94    } fw_un;
95    u_char fw_prot;                     /* IP protocol */
96        /*
97         * N'of src ports and # of dst ports in ports array (dst ports
98         * follow src ports; max of 10 ports in all; count of 0 means
99         * match all ports)
100         */
101    u_char fw_nports;
102    void *pipe_ptr;                    /* flow_set ptr for dummynet pipe */
103    void *next_rule_ptr ;              /* next rule in case of match */
104    uid_t fw_uid;                       /* uid to match */
105    int fw_logamount;                   /* amount to log */
106    u_int64_t fw_loghighest;            /* highest number packet to log */
107};
108
109The ip_fw.h header also contains macros for setting the fw_ports field and various
110flags and constants for setting other fields.
111.Ed
112.\"--------------------------------------------------------------------------------------------
113.Ss Rule Actions
114.\"--------------------------------------------------------------------------------------------
115Each rule has an action described by the IP_FW_F_COMMAND bits in the flags word:
116.Bl -tag -width "IP_FW_F_DIVERT"
117.It Dv IP_FW_F_DENY
118drop packet
119.It Dv IP_FW_F_REJECT
120drop packet; send rejection via ICMP or TCP
121.It Dv IP_FW_F_ACCEPT
122accept packet
123.It Dv IP_FW_F_COUNT
124increment counters; continue matching
125.It Dv IP_FW_F_DIVERT
126divert packet to a
127.Xr divert 4
128socket
129.It Dv IP_FW_F_TEE
130copy packet to a
131.Xr divert 4
132socket; continue
133.It Dv IP_FW_F_SKIPTO
134skip to rule number
135.Va fu_skipto_rule
136.El
137.Pp
138In the case of
139.Dv IP_FW_F_REJECT ,
140if the
141.Va fu_reject_code
142is a number from 0 to 255, then an ICMP unreachable packet is sent back to the
143original packet's source IP address, with the corresponding code.  Otherwise, the
144value must be 256 and the protocol
145.Dv IPPROTO_TCP ,
146in which case a TCP reset packet is sent instead.
147.Pp
148With
149.Dv IP_FW_F_SKIPTO ,
150all succeeding rules having rule number less than
151.Va fu_skipto_rule
152are skipped.
153.Ss Kernel Options
154Options in the kernel configuration file:
155.Bl -tag -width "options IPFIREWALL_VERBOSE_LIMIT"
156.It Cd options IPFIREWALL
157enable
158.Nm
159.It Cd options IPFIREWALL_VERBOSE
160enable firewall logging
161.It Cd options IPFIREWALL_VERBOSE_LIMIT
162limit firewall logging
163.It Cd options IPDIVERT
164enable
165.Xr divert 4
166sockets
167.El
168.Pp
169When packets match a rule with the
170.Dv IP_FW_F_PRN
171bit set, and if
172.Dv IPFIREWALL_VERBOSE
173has been enabled,a message is written to
174.Pa /dev/klog
175with the
176.Dv LOG_SECURITY
177facility
178(see
179.Xr syslog 3 )
180for further logging by
181.Xr syslogd 8 ;
182.Dv IPFIREWALL_VERBOSE_LIMIT
183limits the maximum number of times each rule can cause a log message. These variables are also
184available via the
185.Xr sysctl 3
186interface.
187.\"--------------------------------------------------------------------------------------------
188.Sh RETURN VALUES
189.\"--------------------------------------------------------------------------------------------
190The
191.Fn setsockopt
192function returns 0 on success.  Otherwise, -1 is returned and the global variable
193.Va errno
194is set to indicate the error.
195.\"--------------------------------------------------------------------------------------------
196.Sh ERRORS
197.\"--------------------------------------------------------------------------------------------
198The
199.Fn setsockopt
200function will fail if:
201.Bl -tag -width Er
202.It Bq Er EINVAL
203The IP option field was improperly formed;
204an option field was shorter than the minimum value
205or longer than the option buffer provided.
206.It Bq Er EINVAL
207A structural error in ip_fw structure occurred
208(n_src_p+n_dst_p too big, ports set for ALL/ICMP protocols etc.).
209.It Bq Er EINVAL
210The version field of the ip_fw structure was set to a value not supported by the
211currently-installed
212.Dv IPFirewall,
213or no ip_fw structure was passed to it at all.
214.It Bq Er EINVAL
215An invalid rule number was used.
216.El
217.\"--------------------------------------------------------------------------------------------
218.Sh SEE ALSO
219.\"--------------------------------------------------------------------------------------------
220.Xr setsockopt 2 ,
221.Xr divert 4 ,
222.Xr ip 4 ,
223.Xr ipfw 8 ,
224.Xr sysctl 8 ,
225.Xr syslogd 8
226.\"--------------------------------------------------------------------------------------------
227.Sh BUGS
228.\"--------------------------------------------------------------------------------------------
229The ``tee'' rule is not yet implemented (currently it has no effect).
230.Pp
231This man page still needs work.
232.\"--------------------------------------------------------------------------------------------
233.Sh HISTORY
234.\"--------------------------------------------------------------------------------------------
235The ipfw facility was initially written as package to BSDI by
236.An Daniel Boulet
237.Aq danny@BouletFermat.ab.ca .
238It has been heavily modified and ported to
239.Fx
240by
241.An Ugen J.S. Antsilevich
242.Aq ugen@NetVision.net.il .
243.Pp
244Several enhancements added by
245.An Archie Cobbs
246.Aq archie@FreeBSD.org .
247