1.\" 2.\" $FreeBSD$ 3.\" 4.Dd June 22, 1997 5.Dt IPFIREWALL 4 6.Os 7.Sh NAME 8.Nm ipfirewall 9.Nd IP packet filter and traffic accounting 10.Sh SYNOPSIS 11.Fd #include <sys/types.h> 12.Fd #include <sys/queue.h> 13.Fd #include <netinet/in.h> 14.Fd #include <netinet/ip_fw.h> 15.Ft int 16.Fn setsockopt raw_socket IPPROTO_IP "ipfw option" "struct ipfw" size 17.Sh DESCRIPTION 18Ipfirewall (alias ipfw) is a system facility which allows filtering, 19redirecting, and other operations on IP packets travelling through 20system interfaces. 21Packets are matched by applying an ordered list 22of pattern rules against each packet until a match is found, at 23which point the corresponding action is taken. 24Rules are numbered 25from 1 to 65534; multiple rules may share the same number. 26.Pp 27There is one rule that always exists, rule number 65535. 28This rule 29normally causes all packets to be dropped. 30Hence, any packet which does not 31match a lower numbered rule will be dropped. However, a kernel compile 32time option 33.Dq IPFIREWALL_DEFAULT_TO_ACCEPT 34allows the administrator to change this fixed rule to permit everything. 35.Pp 36The value passed to 37.Fn setsockopt 38is a struct ip_fw describing the rule (see below). 39In some cases 40(such as 41.Dv IP_FW_DEL ) , 42only the rule number is significant. 43.Ss Commands 44The following socket options are used to manage the rule list: 45.Bl -tag -width "IP_FW_FLUSH" 46.It Dv IP_FW_ADD 47inserts the rule into the rule list 48.It Dv IP_FW_DEL 49deletes all rules having the matching rule number 50.It Dv IP_FW_GET 51returns the (first) rule having the matching rule number 52.It Dv IP_FW_ZERO 53zeros the statistics associated with all rules having the 54matching rule number. 55If the rule number is zero, all rules are zeroed. 56.It Dv IP_FW_FLUSH 57removes all rules (except 65535). 58.El 59.Pp 60When the kernel security level is greater than 2, only 61.Dv IP_FW_GET 62is allowed. 63.Ss Rule Structure 64Rules are described by the structures in ip_fw.h. 65.Ss Rule Actions 66Each rule has an action described by the IP_FW_F_COMMAND bits in the 67flags word: 68.Bl -tag -width "IP_FW_F_DIVERT" 69.It Dv IP_FW_F_DENY 70Drop packet and stop processing. 71.It Dv IP_FW_F_REJECT 72drop packet; send rejection via ICMP or TCP and stop processing. 73.It Dv IP_FW_F_ACCEPT 74accept packet and stop processing. 75.It Dv IP_FW_F_COUNT 76increment counters; continue matching 77.It Dv IP_FW_F_DIVERT 78divert packet to a 79.Xr divert 4 80socket and stop processing. 81.It Dv IP_FW_F_TEE 82Send a copy of this packet to a 83.Xr divert 4 84socket and continue processing the original packet at the next rule. 85.It Dv IP_FW_F_SKIPTO 86skip to rule number 87.Va fu_skipto_rule 88At this time the target rule number must be greater than the active rule number. 89.It Dv IP_FW_F_PIPE 90The packet is marked for the use of 91.Xr dummynet 4 , 92and processing stopped. 93.It Dv IP_FW_F_QUEUE 94The packet is marked for the use of 95.Xr dummynet 4 , 96and processing stopped. 97.It Dv IP_FW_F_FWD 98The packet is accepted but the destination is hijacked. (see 99.Xr ipfw 8 ) 100.El 101.Pp 102In the case of 103.Dv IP_FW_F_REJECT , 104if the 105.Va fu_reject_code 106is a number 107from 0 to 255, then an ICMP unreachable packet is sent back to the 108original packet's source IP address, with the corresponding code. 109Otherwise, the value must be 256 and the protocol 110.Dv IPPROTO_TCP , 111in which case a TCP reset packet is sent instead. 112.Pp 113With 114.Dv IP_FW_F_SKIPTO , 115all succeeding rules having rule number less 116than 117.Va fu_skipto_rule 118are skipped. 119.Ss Kernel Options 120Options in the kernel configuration file: 121.Bl -tag -width "optionsXIPFIREWALL_VERBOSE_LIMIT" 122.It Cd options IPFIREWALL 123enable 124.Nm 125.It Cd options IPFIREWALL_VERBOSE 126enable firewall output 127.It Cd options IPFIREWALL_VERBOSE_LIMIT 128limit firewall output 129.It Cd options IPDIVERT 130enable 131.Xr divert 4 132sockets 133.El 134.Pp 135When packets match a rule with the 136.Dv IP_FW_F_PRN 137bit set, a message 138is logged to the console if 139.Dv IPFIREWALL_VERBOSE 140has been enabled; 141Dq IPFIREWALL_VERBOSE_LIMIT 142limits the maximum number of times each 143rule can cause a log message. 144These variables are also 145available via the 146.Xr sysctl 3 147interface. 148.Sh RETURN VALUES 149The 150.Fn setsockopt 151function returns 0 on success. 152Otherwise, -1 is returned and the global variable 153.Va errno 154is set to indicate the error. 155.Sh ERRORS 156The 157.Fn setsockopt 158function will fail if: 159.Bl -tag -width Er 160.It Bq Er EINVAL 161The IP option field was improperly formed; 162an option field was shorter than the minimum value 163or longer than the option buffer provided. 164.It Bq Er EINVAL 165A structural error in ip_fw structure occurred 166(n_src_p+n_dst_p too big, ports set for ALL/ICMP protocols etc.). 167.It Bq Er EINVAL 168An invalid rule number was used. 169.El 170.Sh SEE ALSO 171.Xr setsockopt 2 , 172.Xr divert 4 , 173.Xr ip 4 , 174.Xr ipfw 8 , 175.Xr sysctl 8 176.Sh BUGS 177.Pp 178This man page still needs work. 179.Sh HISTORY 180The ipfw facility was initially written as package to BSDI 181by 182.An Daniel Boulet 183.Aq danny@BouletFermat.ab.ca . 184It has been heavily modified and ported to 185.Fx 186by 187.Ar Ugen J.S.Antsilevich 188.Aq ugen@NetVision.net.il . 189.Pp 190Several enhancements added by 191.An Archie Cobbs 192.Aq archie@FreeBSD.org . 193