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