xref: /freebsd/share/man/man4/ipfirewall.4 (revision 05c7a37afb48ddd5ee1bd921a5d46fe59cc70b15)
1.Dd November 16, 1994
2.Dt IPFW(4)/IPACCT 4
3.Os
4.Sh NAME
5
6 ipfirewall,ipfw     - IP packets filter.
7 ipaccounting,ipacct - IP packets/traffic accounting.
8
9.Sh SYNOPSIS
10#include <netinet/ip_fw.h>
11
12setsockopt(raw_socket,IPPROTO_IP,<ipfw/ipacct  option>,
13                        <struct ip|struct ipfw>,<size>)
14
15Ipfw options:
16  IP_FW_ADD_BLK   - add entry to blocking chain.
17  IP_FW_ADD_FWD   - add entry to forwarding chain.
18  IP_FW_CHK_BLK   - check ip packet against blocking chain.
19  IP_FW_CHK_FWD   - check ip packet against forwarding chain.
20  IP_FW_DEL_BLK   - delete entry from blocking chain.
21  IP_FW_DEL_FWD   - delete entry from forwarding chain.
22  IP_FW_FLUSH     - flush all blocking & forwarding chain entries.
23  IP_FW_POLICY    - define default ipfw policy.
24
25Ipacct options:
26  IP_ACCT_ADD     - add entry to accounting chain.
27  IP_ACCT_DEL     - delete entry from accounting chain.
28  IP_ACCT_FLUSH   - flush all accounting chain entries.
29  IP_ACCT_ZERO    - zero all accounting chain entries.
30
31Ipfw/ipacct entry structure:
32  #define IP_FW_MAX_PORTS 10
33
34struct ip_fw {
35  struct ip_fw *next;
36  struct in_addr src, dst;
37  struct in_addr src_mask, dst_mask;
38  u_short flags;
39  u_short n_src_p, n_dst_p;
40  u_short ports[IP_FW_MAX_PORTS];
41  u_long p_cnt,b_cnt;
42}
43
44Flags values for "flags" field:
45  IP_FW_F_ALL  	- The entry should match all IP packets.
46  IP_FW_F_TCP     - The entry should match TCP packets.
47  IP_FW_F_UDP     - The entry should match UDP packets.
48  IP_FW_F_ICMP    - The entry should match ICMP packets.
49  IP_FW_F_KIND    - Mask value to separate protocol kind.
50  IP_FW_F_ACCEPT  - This entry is accepting ( see below )
51  IP_FW_F_SRNG    - Source ports are range ( see below )
52  IP_FW_F_DRNG    - Destination ports are range ( see below )
53  IP_FW_F_PRN     - Print this entry ( see below )
54  IP_FW_F_BIDIR   - This acct entry is bidirectional ( see below )
55  IP_FW_F_MASK    - Mask to match all valid flag bits.
56
57Kernel symbols to kvm_nlist():
58  struct ip_fw *ip_fw_blk_chain - chain of forwarding entries.
59  struct ip_fw *ip_fw_fwd_chain - chain of blocking entries.
60  int           ip_fw_policy    - default policy.
61  struct ip_fw *ip_acct_chain   - chain of accounting entries.
62
63Options in the kernel configuration file:
64  IPFIREWALL	   - enable ipfirewall.
65  IPFIREWALL_VERBOSE - enable firewall output ( see below )
66  DEBUG_IPFIREWALL   - enable extensive debugging output.
67  IPACCT		   - enable ipaccounting.
68
69.Sh DESCRIPTION
70Ipfirewall (later ipfw) is a system facility,which allows filtering
71of incoming and/or forwarding packets on the protocol+source/destination
72address/ports base.
73Ipaccounting (later ipacct) is a system facility,which allows counting
74of incoming,outgoing and forwarding traffic by packet/byte count.
75
76Basic idea is that every packet checked against number of entries
77in several chains.There are 3 chains:
78  Blocking - this chain defines whenever packet should be accepted
79             ever for local delivery or for forwarding.
80  Forwarding - this chain defines whenever packet should be accepted
81               for forwarding only.
82  Accounting - this chain defines types of packets , which should be
83               counted.
84
85Entries added to chains by means of setsockopt() call on RAW IP socket.
86Options to add/remove specific entries or to flush all entries described
87above. Value passed to setsockopt() is a value of struct ip_fw for
88entry. If entry added , it checked by such rules that when we start
89searching chain for matching entry the first matching is the best match,
90[ or at least one of them :^) ].
91 That means:
92  * First in chain entries with specific protocol and small ranges
93    of src/dst addresses and ports.
94  * Later go entries with wider ranges of ports and addresses.
95  * Later entries matching every port for some address range.
96  * Later universal entries matching any protocol.
97
98While deleting entry , every entry which equal to that passed to
99setsockopt() will be removed.
100Flush removes all entries.
101
102Every entry have several fields,by which packets matched:
103   struct ip_fw *next - next entry in chain.(Set internally)
104
105   struct in_addr src - source address to be matched.
106   struct in_addr src_mask  - source address mask.
107           To match whole networks/subnets or address groups
108           mask bits should be zeroed here and also
109           in src_mask field. Valuable bits should be set
110           in src_mask field.
111   struct in_addr dst - destination address to be matched.
112   struct in_addr dst_mask - destination address mask.
113
114   u_short flags  - flags field.See exact description of flags meaning
115                    in description later.
116
117   u_short n_src_p - number of source ports in "ports" array.
118   u_short n_dst_p - number of destination ports in "ports" array.
119   u_short ports[] - ports array.Overall length currently defined
120                     to reasonable maximum - 10,and could be changed.
121                     The packet's src port can ever match one of
122                     ports[0] ... ports[--n_src_p] numbers,or if
123                     flag IP_FW_F_SRNG set take port[0] as bottom
124                     range value and ports[1] as top one.n_src_p should
125                     be set to 2 then.If n_src_p equal to 0 , every port
126                     match. The same rules apply to packet's dst port,
127                     except that it matched against ports[n_src_p] ...
128                     ... ports[n_src_p+n_dst_p--],or if IP_FW_F_DRNG set,
129                     range is ports[n_src_p] to ports[n_srcp++].
130
131   u_long p_cnt - packets count for ipacct entries.
132   u_long b_cnt - bytes count for ipacct entries.
133
134Packet matching proceeds in following way:
135
136a) If packet entry protocol set to ALL, see c).
137
138b) If entry protocol set to TCP/UDP/ICMP and packet protocol
139   different - no match,if packet protocol and entry protocol
140   same - continue.
141
142c) If source address pattern does not equal to packets sources address
143   masked with src_mask , or destination pattern not equal to packets
144   destination address masked with dst_mask - no match.
145   If they does and protocol set to ALL/ICMP - got match.
146   If they does and protocol set to TCP/UDP - continue.
147
148d) If src port doesn't match or dst port doesn't match - all
149   packet don't match. If they does - got match.
150
151In ipfw packet matched consequently against every chain entry.
152Search continues untill first matching entry found.If IP_FW_F_ACCEPT
153flag set - packet accepted.If it is not set - packet denied.
154If no matching entry found , all unmatched packets ever accepted or
155denied depending on global policy value. It can be set with
156IP_FW_POLICY raw socket option. Deny value is 0, other values
157(default 1) is accept.
158
159Entries can be added with IP_FW_F_PRN flag set.If kernel compiled
160with IPFIREWALL_VERBOSE option,packets matching this entries will
161be printed by kernel printf's.
162
163If some chain is empty,every packet accepted by this chain no
164matter what default policy is.
165
166To check whenever or not packet denied by some chain , checking
167options to setsockopt() can be issued. Then the argument is
168a buffer representing ip packet,thus it has to be
169struct ip + struct tcphdr .
170Then setsockopt() return value 0 on accept or another on deny.
171
172Ipaccounting entries added the same way as ipfw ones.Packet checked
173against all entries in chain and values of p_cnt and b_cnt in matching
174entries rised.p_cnt rises by 1 and b_cnt by ip_len value of ip packet.
175Thus all traffic size counted including IP headers.
176
177If IP_FW_F_BIDIR flag is set in accounting entry,packets counted are
178those which match entry in standard way along with packets which match
179entry while their source and destination addr/port pairs swapped.
180
181Zero option allows all accounting to be cleared.
182
183.Sh DIAGNOSTICS
184
185[EINVAL]  The IP option field was improperly formed; an option
186          field was shorter than the minimum value or longer than
187          the option buffer provided.An structural error in
188          ip_fw structure occured (n_src_p+n_dst_p too big,
189          ports set for ALL/ICMP protocols etc.)
190
191.Sh SEE ALSO
192
193ip(4), setsockopt(2), kvm_nlist(3), kvm_read(3)
194
195.Sh BUGS
196 Ipfw/ipacct facilities are new and , although serious bugs has
197been tracked,some less important ones expected.
198 This man page is mostly out of date and should be rewritten.
199
200.Sh HISTORY
201 Ipfw facility has been initially written as package to BSDI
202by Daniel Boulet <danny@BouletFermat.ab.ca>.
203 It has been heavily modified and ported to FreeBSD 2.0
204by Ugen J.S.Antsilevich <ugen@NetVision.net.il>
205 Ipacct facility written for FreeBSD 2.0
206by Ugen J.S.Antsilevich <ugen@NetVision.net.il>
207