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