1.\" 2.\" $Id: ipfw.8,v 1.53 1999/06/15 12:56:38 ru Exp $ 3.\" 4.Dd July 20, 1996 5.Dt IPFW 8 6.Os FreeBSD 7.Sh NAME 8.Nm ipfw 9.Nd controlling utility for IP firewall 10.Sh SYNOPSIS 11.Nm ipfw 12.Op Fl q 13.Oo 14.Fl p Ar preproc 15.Op Fl D Ar macro Ns Op Ns =value 16.Op Fl U Ar macro 17.Oc 18.Ar file 19.Nm ipfw 20.Oo 21.Fl f 22| 23.Fl q 24.Oc 25flush 26.Nm ipfw 27.Oo 28.Fl q 29.Oc 30zero 31.Op Ar number ... 32.Nm ipfw 33delete 34.Ar number ... 35.Nm ipfw 36.Op Fl aftN 37list 38.Op Ar number ... 39.Nm ipfw 40.Oo 41.Fl ftN 42.Oc 43show 44.Op Ar number ... 45.Nm ipfw 46.Oo 47.Fl q 48.Oc 49add 50.Op Ar number 51.Ar action 52.Op log 53.Ar proto 54from 55.Ar src 56to 57.Ar dst 58.Op via Ar name | ipno 59.Op Ar options 60.Sh DESCRIPTION 61If used as shown in the first synopsis line, the 62.Ar file 63will be read line by line and applied as arguments to the 64.Nm 65command. 66.Pp 67Optionally, a preprocessor can be specified using 68.Fl p Ar preproc 69where 70.Ar file 71is to be piped through. Useful preprocessors include 72.Xr cpp 1 73and 74.Xr m4 1 . 75If 76.Ar preproc 77doesn't start with a slash as its first character, the usual 78.Ev PATH 79name search is performed. Care should be taken with this in environments 80where not all filesystems are mounted (yet) by the time 81.Nm 82is being run (e. g. since they are mounted over NFS). Once 83.Fl p 84has been specified, optional 85.Fl D 86and 87.Fl U 88specifications can follow and will be passed on to the preprocessor. 89This allows for flexible configuration files (like conditionalizing 90them on the local hostname) and the use of macros to centralize 91frequently required arguments like IP addresses. 92.Pp 93Each packet that has been received or is about to be sent goes through 94the 95.Nm 96rules. In the case of a host acting as a gateway, packets that are 97forwarded by the host are processed by 98.Nm 99twice 100.Po 101once when entering, and once when leaving 102.Pc . 103Each packet can be filtered based on the following information that is 104associated with it: 105.Pp 106.Bl -tag -offset indent -compact -width xxxx 107.It Receive Interface Pq Ar recv 108Interface over which the packet was received 109.It Transmit Interface Pq Ar xmit 110Interface over which the packet would be transmitted 111.It Incoming Pq Ar in 112Packet was just received 113.It Outgoing Pq Ar out 114Packet would be transmitted 115.It Source IP Address 116Sender's IP Address 117.It Destination IP Address 118Target's IP Address 119.It Protocol 120IP protocol, including but not limited to IP 121.Pq Ar ip , 122UDP 123.Pq Ar udp , 124TCP 125.Pq Ar tcp , 126or 127ICMP 128.Pq Ar icmp 129.It Source Port 130Sender's UDP or TCP port 131.It Destination Port 132Target's UDP or TCP port 133.It Connection Setup Flag Pq Ar setup 134This packet is a request to setup a TCP connection 135.It Connection Established Flag Pq Ar established 136This packet is part of an established TCP connection 137.It All TCP Flags Pq Ar tcpflags 138One or more of the TCP flags: close connection 139.Pq Ar fin , 140open connection 141.Pq Ar syn , 142reset connection 143.Pq Ar rst , 144push 145.Pq Ar psh , 146acknowledgment 147.Pq Ar ack , 148and 149urgent 150.Pq Ar urg 151.It Fragment Flag Pq Ar frag 152This packet is a fragment of an IP packet 153.It IP Options Pq Ar ipoptions 154One or more of the IP options: strict source route 155.Pq Ar ssrr , 156loose source route 157.Pq Ar lsrr , 158record route 159.Pq Ar rr , 160and timestamp 161.Pq Ar ts 162.It ICMP Types Pq Ar icmptypes 163One or more of the ICMP types: echo reply 164.Pq Ar 0 , 165destination unreachable 166.Pq Ar 3 , 167source quench 168.Pq Ar 4 , 169redirect 170.Pq Ar 5 , 171echo request 172.Pq Ar 8 , 173router advertisement 174.Pq Ar 9 , 175router solicitation 176.Pq Ar 10 , 177time-to-live exceeded 178.Pq Ar 11 , 179IP header bad 180.Pq Ar 12 , 181timestamp request 182.Pq Ar 13 , 183timestamp reply 184.Pq Ar 14 , 185information request 186.Pq Ar 15 , 187information reply 188.Pq Ar 16 , 189address mask request 190.Pq Ar 17 , 191and address mask reply 192.Pq Ar 18 193.El 194.Pp 195Note that may be dangerous to filter on the source IP address or 196source TCP/UDP port because either or both could easily be spoofed. 197.Pp 198The 199.Nm 200code works by going through the rule-list for each packet 201until a match is found. 202All rules have two associated counters, a packet count and 203a byte count. 204These counters are updated when a packet matches the rule. 205.Pp 206The rules are ordered by a 207.Dq line-number 208from 1 to 65534 that is used 209to order and delete rules. Rules are tried in increasing order, and the 210first rule that matches a packet applies. 211Multiple rules may share the same number and apply in 212the order in which they were added. 213.Pp 214If a rule is added without a number, it is numbered 100 higher than the highest 215defined rule number, unless the highest defined rule number is 65435 or 216greater, in which case new rules are given that same number. 217.Pp 218The delete operation deletes the first rule with number 219.Ar number , 220if any. 221.Pp 222The list command prints out the current rule set. 223.Pp 224The show command is equivalent to 225.Sq ipfw -a list . 226.Pp 227The zero operation zeroes the counters associated with rule number 228.Ar number . 229.Pp 230The flush operation removes all rules. 231.Pp 232Any command beginning with a 233.Sq # , 234or being all blank, is ignored. 235.Pp 236One rule is always present: 237.Bd -literal -offset center 23865535 deny all from any to any 239.Ed 240.Pp 241This rule is the default policy, i.e., don't allow anything at all. 242Your job in setting up rules is to modify this policy to match your 243needs. 244.Pp 245However, if the kernel option 246.Dq IPFIREWALL_DEFAULT_TO_ACCEPT 247is active, the rule is instead: 248.Bd -literal -offset center 24965535 allow all from any to any 250.Ed 251.Pp 252This variation lets everything pass through. This option should only be 253activated in particular circumstances, such as if you use the firewall 254system as an on-demand denial-of-service filter that is normally wide open. 255.Pp 256The following options are available: 257.Bl -tag -width indent 258.It Fl a 259While listing, show counter values. See also 260.Dq show 261command. 262.It Fl f 263Don't ask for confirmation for commands that can cause problems if misused 264(i.e. flush). 265.Ar Note , 266if there is no tty associated with the process, this is implied. 267.It Fl q 268While adding, zeroing or flushing, be quiet about actions (implies 269.Fl f Ns ). 270This is useful for adjusting rules by executing multiple 271.Nm 272commands in a script 273.Po 274e.g., 275.Sq sh /etc/rc.firewall 276.Pc , 277or by processing a file of many 278.Nm 279rules, 280across a remote login session. If a flush is performed in normal 281(verbose) mode (with the default kernel configuration), it prints a message. 282Because all rules are flushed, the 283message cannot be delivered to the login session. This causes the 284remote login session to be closed and the remainder of the ruleset is 285not processed. Access to the console is required to recover. 286.It Fl t 287While listing, show last match timestamp. 288.It Fl N 289Try to resolve addresses and service names in output. 290.El 291.Pp 292.Ar action : 293.Bl -hang -offset flag -width 1234567890123456 294.It Ar allow 295Allow packets that match rule. 296The search terminates. Aliases are 297.Ar pass , 298.Ar permit , 299and 300.Ar accept . 301.It Ar deny 302Discard packets that match this rule. 303The search terminates. 304.Ar Drop 305is an alias for 306.Ar deny . 307.It Ar reject 308(Deprecated.) Discard packets that match this rule, and try to send an ICMP 309host unreachable notice. 310The search terminates. 311.It Ar unreach code 312Discard packets that match this rule, and try to send an ICMP 313unreachable notice with code 314.Ar code , 315where 316.Ar code 317is a number from zero to 255, or one of these aliases: 318.Ar net , 319.Ar host , 320.Ar protocol , 321.Ar port , 322.Ar needfrag , 323.Ar srcfail , 324.Ar net-unknown , 325.Ar host-unknown , 326.Ar isolated , 327.Ar net-prohib , 328.Ar host-prohib , 329.Ar tosnet , 330.Ar toshost , 331.Ar filter-prohib , 332.Ar host-precedence , 333or 334.Ar precedence-cutoff . 335The search terminates. 336.It Ar reset 337TCP packets only. Discard packets that match this rule, 338and try to send a TCP reset 339.Pq RST 340notice. 341The search terminates. 342.It Ar count 343Update counters for all packets that match rule. 344The search continues with the next rule. 345.It Ar divert port 346Divert packets that match this rule to the 347.Xr divert 4 348socket bound to port 349.Ar port . 350The search terminates. 351.It Ar tee port 352Send a copy of packets matching this rule to the 353.Xr divert 4 354socket bound to port 355.Ar port . 356The search continues with the next rule. This feature is not yet implemented. 357.It Ar fwd ipaddr Op ,port 358Change the next-hop on matching packets to 359.Ar ipaddr , 360which can be an IP address in dotted quad or a host name. 361If 362.Ar ipaddr 363is not a directly-reachable address, the route 364as found in the local routing table for that IP is used 365instead. 366If 367.Ar ipaddr 368is a local address, then on a packet entering the system from a remote 369host it will be diverted to 370.Ar port 371on the local machine, keeping the local address of the socket set 372to the original IP address the packet was destined for. This is intended 373for use with transparent proxy servers. If the IP is not 374a local address then the port number (if specified) is ignored and 375the rule only applies to packets leaving the system. This will 376also map addresses to local ports when packets are generated locally. 377The search terminates if this rule matches. If the port number is not 378given then the port number in the packet is used, so that a packet for 379an external machine port Y would be forwarded to local port Y. The kernel 380must have been compiled with options IPFIREWALL_FORWARD. 381.It Ar skipto number 382Skip all subsequent rules numbered less than 383.Ar number . 384The search continues with the first rule numbered 385.Ar number 386or higher. 387.It Ar uid user 388Match all TCP or UDP packets sent by or received for a 389.Ar user . 390A 391.Ar user 392may be matched by name or identification number. 393.It Ar gid group 394Match all TCP or UDP packets sent by or received for a 395.Ar group . 396A 397.Ar group 398may be matched by name or identification number. 399.El 400.Pp 401If a packet matches more than one 402.Ar divert 403and/or 404.Ar tee 405rule, all but the last are ignored. 406.Pp 407If the kernel was compiled with 408.Dv IPFIREWALL_VERBOSE , 409then when a packet matches a rule with the 410.Ar log 411keyword a message will be printed on the console. 412If the kernel was compiled with the 413.Dv IPFIREWALL_VERBOSE_LIMIT 414option, then logging will cease after the number of packets 415specified by the option are received for that particular 416chain entry. Logging may then be re-enabled by clearing 417the packet counter for that entry. 418.Pp 419Console logging and the log limit are adjustable dynamically 420through the 421.Xr sysctl 8 422interface. 423.Pp 424.Ar proto : 425.Bl -hang -offset flag -width 1234567890123456 426.It Ar ip 427All packets match. The alias 428.Ar all 429has the same effect. 430.It Ar tcp 431Only TCP packets match. 432.It Ar udp 433Only UDP packets match. 434.It Ar icmp 435Only ICMP packets match. 436.It Ar <number|name> 437Only packets for the specified protocol matches (see 438.Pa /etc/protocols 439for a complete list). 440.El 441.Pp 442.Ar src 443and 444.Ar dst : 445.Bl -hang -offset flag 446.It Ar <address/mask> 447.Op Ar ports 448.El 449.Pp 450The 451.Em <address/mask> 452may be specified as: 453.Bl -hang -offset flag -width 1234567890123456 454.It Ar ipno 455An ipnumber of the form 1.2.3.4. 456Only this exact ip number match the rule. 457.It Ar ipno/bits 458An ipnumber with a mask width of the form 1.2.3.4/24. 459In this case all ip numbers from 1.2.3.0 to 1.2.3.255 will match. 460.It Ar ipno:mask 461An ipnumber with a mask width of the form 1.2.3.4:255.255.240.0. 462In this case all ip numbers from 1.2.0.0 to 1.2.15.255 will match. 463.El 464.Pp 465The sense of the match can be inverted by preceding an address with the 466.Dq not 467modifier, causing all other addresses to be matched instead. This 468does not affect the selection of port numbers. 469.Pp 470With the TCP and UDP protocols, optional 471.Em ports 472may be specified as: 473.Pp 474.Bl -hang -offset flag 475.It Ns {port|port-port} Ns Op ,port Ns Op ,... 476.El 477.Pp 478Service names (from 479.Pa /etc/services ) 480may be used instead of numeric port values. 481A range may only be specified as the first value, 482and the length of the port list is limited to 483.Dv IP_FW_MAX_PORTS 484(as defined in 485.Pa /usr/src/sys/netinet/ip_fw.h ) 486ports. 487A 488.Ql \e 489can be used to escape the 490.Ql - 491character in a service name: 492.Pp 493.Dl ipfw add count tcp from any ftp\e\e-data-ftp to any 494.Pp 495Fragmented packets which have a non-zero offset (i.e. not the first 496fragment) will never match a rule which has one or more port 497specifications. See the 498.Ar frag 499option for details on matching fragmented packets. 500.Pp 501Rules can apply to packets when they are incoming, or outgoing, or both. 502The 503.Ar in 504keyword indicates the rule should only match incoming packets. 505The 506.Ar out 507keyword indicates the rule should only match outgoing packets. 508.Pp 509To match packets going through a certain interface, specify 510the interface using 511.Ar via : 512.Bl -hang -offset flag -width 1234567890123456 513.It Ar via ifX 514Packet must be going through interface 515.Ar ifX. 516.It Ar via if* 517Packet must be going through interface 518.Ar ifX , 519where X is any unit number. 520.It Ar via any 521Packet must be going through 522.Em some 523interface. 524.It Ar via ipno 525Packet must be going through the interface having IP address 526.Ar ipno . 527.El 528.Pp 529The 530.Ar via 531keyword causes the interface to always be checked. 532If 533.Ar recv 534or 535.Ar xmit 536is used instead of 537.Ar via , 538then the only receive or transmit interface (respectively) is checked. 539By specifying both, it is possible to match packets based on both receive 540and transmit interface, e.g.: 541.Pp 542.Dl "ipfw add 100 deny ip from any to any out recv ed0 xmit ed1" 543.Pp 544The 545.Ar recv 546interface can be tested on either incoming or outgoing packets, while the 547.Ar xmit 548interface can only be tested on outgoing packets. So 549.Ar out 550is required (and 551.Ar in 552invalid) whenever 553.Ar xmit 554is used. Specifying 555.Ar via 556together with 557.Ar xmit 558or 559.Ar recv 560is invalid. 561.Pp 562A packet may not have a receive or transmit interface: packets originating 563from the local host have no receive interface. while packets destined for 564the local host have no transmit interface. 565.Pp 566Additional 567.Ar options : 568.Bl -hang -offset flag -width 1234567890123456 569.It frag 570Match if the packet is a fragment and this is not the first fragment 571of the datagram. 572.Ar frag 573may not be used in conjunction with either 574.Ar tcpflags 575or TCP/UDP port specifications. 576.It in 577Match if this packet was on the way in. 578.It out 579Match if this packet was on the way out. 580.It ipoptions Ar spec 581Match if the IP header contains the comma separated list of 582options specified in 583.Ar spec . 584The supported IP options are: 585.Ar ssrr 586(strict source route), 587.Ar lsrr 588(loose source route), 589.Ar rr 590(record packet route), and 591.Ar ts 592(timestamp). 593The absence of a particular option may be denoted 594with a 595.Dq ! . 596.It established 597Match packets that have the RST or ACK bits set. 598TCP packets only. 599.It setup 600Match packets that have the SYN bit set but no ACK bit. 601TCP packets only. 602.It tcpflags Ar spec 603Match if the TCP header contains the comma separated list of 604flags specified in 605.Ar spec . 606The supported TCP flags are: 607.Ar fin , 608.Ar syn , 609.Ar rst , 610.Ar psh , 611.Ar ack , 612and 613.Ar urg . 614The absence of a particular flag may be denoted 615with a 616.Dq ! . 617A rule which contains a 618.Ar tcpflags 619specification can never match a fragmented packet which has 620a non-zero offset. See the 621.Ar frag 622option for details on matching fragmented packets. 623.It icmptypes Ar types 624Match if the ICMP type is in the list 625.Ar types . 626The list may be specified as any combination of ranges 627or individual types separated by commas. 628.El 629.Sh CHECKLIST 630Here are some important points to consider when designing your 631rules: 632.Bl -bullet -hang -offset flag 633.It 634Remember that you filter both packets going in and out. 635Most connections need packets going in both directions. 636.It 637Remember to test very carefully. 638It is a good idea to be near the console when doing this. 639.It 640Don't forget the loopback interface. 641.El 642.Sh FINE POINTS 643There is one kind of packet that the firewall will always discard, 644that is an IP fragment with a fragment offset of one. 645This is a valid packet, but it only has one use, to try to circumvent 646firewalls. 647.Pp 648If you are logged in over a network, loading the KLD version of 649.Nm 650is probably not as straightforward as you would think. 651I recommend this command line: 652.Bd -literal -offset center 653kldload /modules/ipfw.ko && \e 654ipfw add 32000 allow all from any to any 655.Ed 656.Pp 657Along the same lines, doing an 658.Bd -literal -offset center 659ipfw flush 660.Ed 661.Pp 662in similar surroundings is also a bad idea. 663.Pp 664The IP filter list may not be modified if the system security level 665is set to 3 or higher 666.Po 667see 668.Xr init 8 669for information on system security levels 670.Pc . 671.Sh PACKET DIVERSION 672A divert socket bound to the specified port will receive all packets diverted 673to that port; see 674.Xr divert 4 . 675If no socket is bound to the destination port, or if the kernel 676wasn't compiled with divert socket support, diverted packets are dropped. 677.Sh EXAMPLES 678This command adds an entry which denies all tcp packets from 679.Em cracker.evil.org 680to the telnet port of 681.Em wolf.tambov.su 682from being forwarded by the host: 683.Pp 684.Dl ipfw add deny tcp from cracker.evil.org to wolf.tambov.su 23 685.Pp 686This one disallows any connection from the entire crackers network to 687my host: 688.Pp 689.Dl ipfw add deny all from 123.45.67.0/24 to my.host.org 690.Pp 691Here is a good usage of the 692.Ar list 693command to see accounting records 694and timestamp information: 695.Pp 696.Dl ipfw -at l 697.Pp 698or in short form without timestamps: 699.Pp 700.Dl ipfw -a l 701.Pp 702This rule diverts all incoming packets from 192.168.2.0/24 to divert port 5000: 703.Pp 704.Dl ipfw divert 5000 all from 192.168.2.0/24 to any in 705.Sh SEE ALSO 706.Xr cpp 1 , 707.Xr m4 1 , 708.Xr divert 4 , 709.Xr ip 4 , 710.Xr ipfirewall 4 , 711.Xr protocols 5 , 712.Xr services 5 , 713.Xr init 8 , 714.Xr kldload 8 , 715.Xr reboot 8 , 716.Xr sysctl 8 , 717.Xr syslogd 8 . 718.Sh BUGS 719.Pp 720.Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!! 721.Pp 722This program can put your computer in rather unusable state. When 723using it for the first time, work on the console of the computer, and 724do 725.Em NOT 726do anything you don't understand. 727.Pp 728When manipulating/adding chain entries, service and protocol names are 729not accepted. 730.Pp 731Incoming packet fragments diverted by 732.Ar divert 733are reassembled before delivery to the socket, whereas fragments diverted via 734.Ar tee 735are not. 736.Pp 737Port aliases containing dashes cannot be first in a list. 738.Pp 739The 740.Dq tee 741action is unimplemented. 742.Sh AUTHORS 743.An Ugen J. S. Antsilevich , 744.An Poul-Henning Kamp , 745.An Alex Nash , 746.An Archie Cobbs . 747API based upon code written by 748.An Daniel Boulet 749for BSDI. 750.Sh HISTORY 751.Nm Ipfw 752first appeared in 753.Fx 2.0 . 754