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.Dv 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 "options IPFIREWALL_VERBOSE_LIMIT" 122.It Cd options IPFIREWALL 123enable 124.Nm 125.It Cd options IPFIREWALL_VERBOSE 126enable firewall logging 127.It Cd options IPFIREWALL_VERBOSE_LIMIT 128limit firewall logging 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, and if 138.Dv IPFIREWALL_VERBOSE 139has been enabled, 140a message is written to 141.Pa /dev/klog 142with the 143.Dv LOG_SECURITY 144facility 145(see 146.Xr syslog 3 ) 147for further logging by 148.Xr syslogd 8 ; 149.Dv IPFIREWALL_VERBOSE_LIMIT 150limits the maximum number of times each 151rule can cause a log message. 152These variables are also 153available via the 154.Xr sysctl 3 155interface. 156.Sh RETURN VALUES 157The 158.Fn setsockopt 159function returns 0 on success. 160Otherwise, -1 is returned and the global variable 161.Va errno 162is set to indicate the error. 163.Sh ERRORS 164The 165.Fn setsockopt 166function will fail if: 167.Bl -tag -width Er 168.It Bq Er EINVAL 169The IP option field was improperly formed; 170an option field was shorter than the minimum value 171or longer than the option buffer provided. 172.It Bq Er EINVAL 173A structural error in ip_fw structure occurred 174(n_src_p+n_dst_p too big, ports set for ALL/ICMP protocols etc.). 175.It Bq Er EINVAL 176An invalid rule number was used. 177.El 178.Sh SEE ALSO 179.Xr setsockopt 2 , 180.Xr divert 4 , 181.Xr ip 4 , 182.Xr ipfw 8 , 183.Xr sysctl 8 , 184.Xr syslogd 8 185.Sh BUGS 186This man page still needs work. 187.Sh HISTORY 188The ipfw facility was initially written as package to BSDI 189by 190.An Daniel Boulet 191.Aq danny@BouletFermat.ab.ca . 192It has been heavily modified and ported to 193.Fx 194by 195.An Ugen J.S. Antsilevich 196.Aq ugen@NetVision.net.il . 197.Pp 198Several enhancements added by 199.An Archie Cobbs 200.Aq archie@FreeBSD.org . 201