ipfw.8 revision 28506
1.Dd July 20, 1996 2.Dt IPFW 8 SMM 3.Os FreeBSD 4.Sh NAME 5.Nm ipfw 6.Nd controlling utility for IP firewall 7.Sh SYNOPSIS 8.Nm 9.Ar file 10.Nm ipfw 11.Oo 12.Fl f 13| 14.Fl q 15.Oc 16flush 17.Nm ipfw 18.Oo 19.Fl q 20.Oc 21zero 22.Op Ar number ... 23.Nm ipfw 24delete 25.Ar number ... 26.Nm ipfw 27.Op Fl aftN 28list 29.Nm ipfw 30.Oo 31.Fl ftN 32.Oc 33show 34.Nm ipfw 35.Oo 36.Fl q 37.Oc 38add 39.Op Ar number 40.Ar action 41.Op log 42.Ar proto 43from 44.Ar src 45to 46.Ar dst 47.Op via Ar name | ipno 48.Op Ar options 49.Sh DESCRIPTION 50If used as shown in the first synopsis line, the 51.Ar file 52will be read line by line and applied as arguments to the 53.Nm 54command. 55.Pp 56The 57.Nm 58code works by going through the rule-list for each packet, 59until a match is found. 60All rules have two associated counters, a packet count and 61a byte count. 62These counters are updated when a packet matches the rule. 63.Pp 64The rules are ordered by a ``line-number'' from 1 to 65534 that is used 65to order and delete rules. Rules are tried in increasing order, and the 66first rule that matches a packet applies. 67Multiple rules may share the same number and apply in 68the order in which they were added. 69.Pp 70If a rule is added without a number, it is numbered 100 higher 71than the previous rule. If the highest defined rule number is 72greater than 65434, new rules are appended to the last rule. 73.Pp 74The delete operation deletes the first rule with number 75.Ar number , 76if any. 77.Pp 78The list command prints out the current rule set. 79.Pp 80The show command is equivalent to `ipfw -a list'. 81.Pp 82The zero operation zeroes the counters associated with rule number 83.Ar number . 84.Pp 85The flush operation removes all rules. 86.Pp 87One rule is always present: 88.Bd -literal -offset center 8965535 deny all from any to any 90.Ed 91.Pp 92This rule is the default policy, i.e., don't allow anything at all. 93Your job in setting up rules is to modify this policy to match your 94needs. 95.Pp 96The following options are available: 97.Bl -tag -width flag 98.It Fl a 99While listing, show counter values. See also ``show'' command. 100.It Fl f 101Don't ask for confirmation for commands that can cause problems if misused 102(ie; flush). 103.Ar Note , 104if there is no tty associated with the process, this is implied. 105.It Fl q 106While adding or flushing, be quiet about actions (implies '-f'). This is 107useful for adjusting rules by executing multiple ipfw commands in a script 108(e.g. sh /etc/rc.firewall), or by processing a file of many ipfw rules, 109across a remote login session. If a flush is performed in normal 110(verbose) mode, it prints a message. Because all rules are flushed, the 111message cannot be delivered to the login session, the login session is 112closed and the remainder of the ruleset is not processed. Access to the 113console is required to recover. 114.It Fl t 115While listing, show last match timestamp. 116.It Fl N 117Try to resolve addresses and service names in output. 118.El 119.Pp 120.Ar action : 121.Bl -hang -offset flag -width 1234567890123456 122.It Ar allow 123Allow packets that match rule. 124The search terminates. Aliases are 125.Ar pass , 126.Ar permit , 127and 128.Ar accept . 129.It Ar deny 130Discard packets that match this rule. 131The search terminates. 132.Ar Drop 133is an alias for 134.Ar deny . 135.It Ar reject 136(Deprecated.) Discard packets that match this rule, and try to send an ICMP 137host unreachable notice. 138The search terminates. 139.It Ar unreach code 140Discard packets that match this rule, and try to send an ICMP 141unreachable notice with code 142.Ar code , 143where 144.Ar code 145is a number from zero to 255, or one of these aliases: 146.Ar net , 147.Ar host , 148.Ar protocol , 149.Ar port , 150.Ar needfrag , 151.Ar srcfail , 152.Ar net-unknown , 153.Ar host-unknown , 154.Ar isolated , 155.Ar net-prohib , 156.Ar host-prohib , 157.Ar tosnet , 158.Ar toshost , 159.Ar filter-prohib , 160.Ar host-precedence , 161or 162.Ar precedence-cutoff . 163The search terminates. 164.It Ar reset 165TCP packets only. Discard packets that match this rule, 166and try to send a TCP reset (RST) notice. 167The search terminates. 168.It Ar count 169Update counters for all packets that match rule. 170The search continues with the next rule. 171.It Ar divert port 172Divert packets that match this rule to the 173.Xr divert 4 174socket bound to port 175.Ar port . 176The search terminates. 177.It Ar tee port 178Send a copy of packets matching this rule to the 179.Xr divert 4 180socket bound to port 181.Ar port . 182The search continues with the next rule. 183.It Ar skipto number 184Skip all subsequent rules numbered less than 185.Ar number . 186The search continues with the first rule numbered 187.Ar number 188or higher. 189.El 190.Pp 191If a packet matches more than one 192.Ar divert 193and/or 194.Ar tee 195rule, all but the last are ignored. 196.Pp 197If the kernel was compiled with 198.Dv IPFIREWALL_VERBOSE , 199then when a packet matches a rule with the ``log'' 200keyword a message will be printed on the console. 201If the kernel was compiled with the 202.Dv IPFIREWALL_VERBOSE_LIMIT 203option, then logging will cease after the number of packets 204specified by the option are received for that particular 205chain entry. Logging may then be re-enabled by clearing 206the packet counter for that entry. 207.Pp 208Console logging and the log limit are adjustable dynamically 209through the 210.Xr sysctl 8 211interface. 212.Pp 213.Ar proto : 214.Bl -hang -offset flag -width 1234567890123456 215.It Ar ip 216All packets match. The alias 217.Ar all 218has the same effect. 219.It Ar tcp 220Only TCP packets match. 221.It Ar udp 222Only UDP packets match. 223.It Ar icmp 224Only ICMP packets match. 225.It Ar <number|name> 226Only packets for the specified protocol matches (see 227.Pa /etc/protocols 228for a complete list). 229.El 230.Pp 231.Ar src 232and 233.Ar dst : 234.Bl -hang -offset flag 235.It Ar <address/mask> 236.Op Ar ports 237.El 238.Pp 239The 240.Em <address/mask> 241may be specified as: 242.Bl -hang -offset flag -width 1234567890123456 243.It Ar ipno 244An ipnumber of the form 1.2.3.4. 245Only this exact ip number match the rule. 246.It Ar ipno/bits 247An ipnumber with a mask width of the form 1.2.3.4/24. 248In this case all ip numbers from 1.2.3.0 to 1.2.3.255 will match. 249.It Ar ipno:mask 250An ipnumber with a mask width of the form 1.2.3.4:255.255.240.0. 251In this case all ip numbers from 1.2.0.0 to 1.2.15.255 will match. 252.El 253.Pp 254The sense of the match can be inverted by preceding an address with the 255``not'' modifier, causing all other addresses to be matched instead. This 256does not affect the selection of port numbers. 257.Pp 258With the TCP and UDP protocols, optional 259.Em ports 260may be specified as: 261.Pp 262.Bl -hang -offset flag 263.It Ns {port|port-port} Ns Op ,port Ns Op ,... 264.El 265.Pp 266Service names (from 267.Pa /etc/services ) 268may be used instead of numeric port values. 269A range may only be specified as the first value, 270and the length of the port list is limited to 271.Dv IP_FW_MAX_PORTS 272(as defined in 273.Pa /usr/src/sys/netinet/ip_fw.h ) 274ports. 275.Pp 276Rules can apply to packets when they are incoming, or outgoing, or both. 277The 278.Ar in 279keyword indicates the rule should only match incoming packets. 280The 281.Ar out 282keyword indicates the rule should only match outgoing packets. 283.Pp 284To match packets going through a certain interface, specify 285the interface using 286.Ar via : 287.Bl -hang -offset flag -width 1234567890123456 288.It Ar via ifX 289Packet must be going through interface 290.Ar ifX. 291.It Ar via if* 292Packet must be going through interface 293.Ar ifX , 294where X is any unit number. 295.It Ar via any 296Packet must be going through 297.Em some 298interface. 299.It Ar via ipno 300Packet must be going through the interface having IP address 301.Ar ipno . 302.El 303.Pp 304The 305.Ar via 306keyword causes the interface to always be checked. 307If 308.Ar recv 309or 310.Ar xmit 311is used instead of 312.Ar via , 313then the only receive or transmit interface (respectively) is checked. 314By specifying both, it is possible to match packets based on both receive 315and transmit interface, e.g.: 316.Pp 317.Dl "ipfw add 100 deny ip from any to any out recv ed0 xmit ed1" 318.Pp 319The 320.Ar recv 321interface can be tested on either incoming or outgoing packets, while the 322.Ar xmit 323interface can only be tested on outgoing packets. So 324.Ar out 325is required (and 326.Ar in 327invalid) whenver 328.Ar xmit 329is used. Specifying 330.Ar via 331together with 332.Ar xmit 333or 334.Ar recv 335is invalid. 336.Pp 337A packet may not have a receive or transmit interface: packets originating 338from the local host have no receive interface. while packets destined for 339the local host have no transmit interface. 340.Pp 341Additional 342.Ar options : 343.Bl -hang -offset flag -width 1234567890123456 344.It frag 345Matches if the packet is a fragment and this is not the first fragment 346of the datagram. 347.It in 348Matches if this packet was on the way in. 349.It out 350Matches if this packet was on the way out. 351.It ipoptions Ar spec 352Matches if the IP header contains the comma separated list of 353options specified in 354.Ar spec . 355The supported IP options are: 356.Ar ssrr 357(strict source route), 358.Ar lsrr 359(loose source route), 360.Ar rr 361(record packet route), and 362.Ar ts 363(timestamp). 364The absence of a particular option may be denoted 365with a ``!''. 366.It established 367Matches packets that have the RST or ACK bits set. 368TCP packets only. 369.It setup 370Matches packets that have the SYN bit set but no ACK bit. 371TCP packets only. 372.It tcpflags Ar spec 373Matches if the TCP header contains the comma separated list of 374flags specified in 375.Ar spec . 376The supported TCP flags are: 377.Ar fin , 378.Ar syn , 379.Ar rst , 380.Ar psh , 381.Ar ack , 382and 383.Ar urg . 384The absence of a particular flag may be denoted 385with a ``!''. 386.It icmptypes Ar types 387Matches if the ICMP type is in the list 388.Ar types . 389The list may be specified as any combination of ranges 390or individual types separated by commas. 391.El 392.Sh CHECKLIST 393Here are some important points to consider when designing your 394rules: 395.Bl -bullet -hang -offset flag 396.It 397Remember that you filter both packets going in and out. 398Most connections need packets going in both directions. 399.It 400Remember to test very carefully. 401It is a good idea to be near the console when doing this. 402.It 403Don't forget the loopback interface. 404.El 405.Sh FINE POINTS 406There is one kind of packet that the firewall will always discard, 407that is an IP fragment with a fragment offset of one. 408This is a valid packet, but it only has one use, to try to circumvent 409firewalls. 410.Pp 411If you are logged in over a network, loading the LKM version of 412.Nm 413is probably not as straightforward as you would think. 414I recommend this command line: 415.Bd -literal -offset center 416modload /lkm/ipfw_mod.o && \e 417ipfw add 32000 allow all from any to any 418.Ed 419.Pp 420Along the same lines, doing an 421.Bd -literal -offset center 422ipfw flush 423.Ed 424.Pp 425in similar surroundings is also a bad idea. 426.Sh PACKET DIVERSION 427A divert socket bound to the specified port will receive all packets diverted 428to that port; see 429.Xr divert 4 . 430If no socket is bound to the destination port, or if the kernel 431wasn't compiled with divert socket support, diverted packets are dropped. 432.Sh EXAMPLES 433This command adds an entry which denies all tcp packets from 434.Em hacker.evil.org 435to the telnet port of 436.Em wolf.tambov.su 437from being forwarded by the host: 438.Pp 439.Dl ipfw add deny tcp from hacker.evil.org to wolf.tambov.su 23 440.Pp 441This one disallows any connection from the entire hackers network to 442my host: 443.Pp 444.Dl ipfw addf deny all from 123.45.67.0/24 to my.host.org 445.Pp 446Here is a good usage of the list command to see accounting records 447and timestamp information: 448.Pp 449.Dl ipfw -at l 450.Pp 451or in short form without timestamps: 452.Pp 453.Dl ipfw -a l 454.Pp 455This rule diverts all incoming packets from 192.168.2.0/24 to divert port 5000: 456.Pp 457.Dl ipfw divert 5000 all from 192.168.2.0/24 to any in 458.Sh SEE ALSO 459.Xr ip 4 , 460.Xr ipfirewall 4 , 461.Xr divert 4 , 462.Xr protocols 5 , 463.Xr services 5 , 464.Xr reboot 8 , 465.Xr syslogd 8 , 466.Xr sysctl 8 467.Sh BUGS 468.Pp 469.Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!! 470.Pp 471This program can put your computer in rather unusable state. When 472using it for the first time, work on the console of the computer, and 473do 474.Em NOT 475do anything you don't understand. 476.Pp 477When manipulating/adding chain entries, service and protocol names are 478not accepted. 479.Pp 480Incoming packet fragments diverted by 481.Ar divert 482are reassembled before delivery to the socket, whereas fragments diverted via 483.Ar tee 484are not. 485.Pp 486Port aliases containing dashes cannot be first in a list. 487.Sh AUTHORS 488Ugen J. S. Antsilevich, 489Poul-Henning Kamp, 490Alex Nash, 491Archie Cobbs. 492API based upon code written by Daniel Boulet for BSDI. 493.Sh HISTORY 494.Nm 495first appeared in 496.Fx 2.0 . 497