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