1.\" 2.\" $FreeBSD: src/sbin/ipfw/ipfw.8,v 1.63.2.33 2003/02/04 01:36:02 brueffer Exp $ 3.\" $DragonFly: src/sbin/ipfw/ipfw.8,v 1.20 2008/11/23 21:55:52 swildner Exp $ 4.\" 5.Dd October 3, 2008 6.Dt IPFW 8 7.Os 8.Sh NAME 9.Nm ipfw 10.Nd IP firewall and traffic shaper control program 11.Sh SYNOPSIS 12.Nm 13.Op Fl cq 14.Cm add 15.Ar rule 16.Nm 17.Op Fl acdeftNS 18.Brq Cm list | show 19.Op Ar number ... 20.Nm 21.Op Fl f | q 22.Cm flush 23.Nm 24.Op Fl q 25.Brq Cm delete | zero | resetlog 26.Op Cm set 27.Op Ar number ... 28.Nm 29.Cm enable 30.Brq Cm firewall | one_pass | debug | verbose | dyn_keepalive 31.Nm 32.Cm disable 33.Brq Cm firewall | one_pass | debug | verbose | dyn_keepalive 34.Pp 35.Nm 36.Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ... 37.Nm 38.Cm set move 39.Op Cm rule 40.Ar number Cm to Ar number 41.Nm 42.Cm set swap Ar number number 43.Nm 44.Cm set show 45.Pp 46.Nm 47.Brq Cm pipe | queue 48.Ar number 49.Cm config 50.Ar config-options 51.Nm 52.Op Fl s Op Ar field 53.Brq Cm pipe | queue 54.Brq Cm delete | list | show 55.Op Ar number ... 56.Pp 57.Nm 58.Op Fl q 59.Oo 60.Fl p Ar preproc 61.Oo Fl D 62.Ar macro Ns Op = Ns Ar value 63.Oc 64.Op Fl U Ar macro 65.Oc 66.Ar pathname 67.Sh DESCRIPTION 68The 69.Nm 70utility is the user interface for controlling the 71.Xr ipfw 4 72firewall and the 73.Xr dummynet 4 74traffic shaper in 75.Dx . 76.Bd -ragged -offset XXXX 77.Em NOTE: 78this manual page documents the newer version of 79.Nm 80introduced in 81.Fx 82CURRENT in July 2002, also known as 83.Nm ipfw2 . 84.Nm ipfw2 85is a superset of the old firewall, 86.Nm ipfw1 . 87The differences between the two are listed in Section 88.Sx IPFW2 ENHANCEMENTS , 89which you are encouraged to read to revise older rulesets and possibly 90write them more efficiently. 91.Ed 92.Pp 93An 94.Nm 95configuration, or 96.Em ruleset , 97is made of a list of 98.Em rules 99numbered from 1 to 65535. 100Packets are passed to 101.Nm 102from a number of different places in the protocol stack 103(depending on the source and destination of the packet, 104it is possible that 105.Nm 106is invoked multiple times on the same packet). 107The packet passed to the firewall is compared 108against each of the rules in the firewall 109.Em ruleset . 110When a match is found, the action corresponding to the 111matching rule is performed. 112.Pp 113Depending on the action and certain system settings, packets 114can be reinjected into the firewall at some rule after the 115matching one for further processing. 116.Pp 117An 118.Nm 119ruleset always includes a 120.Em default 121rule (numbered 65535) which cannot be modified, 122and matches all packets. 123The action associated with the 124.Em default 125rule can be either 126.Cm deny 127or 128.Cm allow 129depending on how the kernel is configured. 130.Pp 131If the ruleset includes one or more rules with the 132.Cm keep-state 133or 134.Cm limit 135option, then 136.Nm 137assumes a 138.Em stateful 139behaviour, i.e. upon a match it will create dynamic rules matching 140the exact parameters (addresses and ports) of the matching packet. 141.Pp 142These dynamic rules, which have a limited lifetime, are checked 143at the first occurrence of a 144.Cm check-state , 145.Cm keep-state 146or 147.Cm limit 148rule, and are typically used to open the firewall on-demand to 149legitimate traffic only. 150See the 151.Sx STATEFUL FIREWALL 152and 153.Sx EXAMPLES 154Sections below for more information on the stateful behaviour of 155.Nm . 156.Pp 157All rules (including dynamic ones) have a few associated counters: 158a packet count, a byte count, a log count and a timestamp 159indicating the time of the last match. 160Counters can be displayed or reset with 161.Nm 162commands. 163.Pp 164Rules can be added with the 165.Cm add 166command; deleted individually or in groups with the 167.Cm delete 168command, and globally with the 169.Cm flush 170command; displayed, optionally with the content of the 171counters, using the 172.Cm show 173and 174.Cm list 175commands. 176Finally, counters can be reset with the 177.Cm zero 178and 179.Cm resetlog 180commands. 181.Pp 182Also, each rule belongs to one of 32 different 183.Em sets 184, and there are 185.Nm 186commands to atomically manipulate sets, such as enable, 187disable, swap sets, move all rules in a set to another 188one, delete all rules in a set. These can be useful to 189install temporary configurations, or to test them. 190See Section 191.Sx SETS OF RULES 192for more information on 193.Em sets . 194.Pp 195The following options are available: 196.Bl -tag -width indent 197.It Fl a 198While listing, show counter values. 199The 200.Cm show 201command just implies this option. 202.It Fl c 203When entering or showing rules, print them in compact form, 204i.e. without the optional "ip from any to any" string 205when this does not carry any additional information. 206.It Fl d 207While listing, show dynamic rules in addition to static ones. 208.It Fl e 209While listing, if the 210.Fl d 211option was specified, also show expired dynamic rules. 212.It Fl f 213Don't ask for confirmation for commands that can cause problems 214if misused, 215.No i.e. Cm flush . 216If there is no tty associated with the process, this is implied. 217.It Fl N 218Try to resolve addresses and service names in output. 219.It Fl q 220While 221.Cm add Ns ing , 222.Cm zero Ns ing , 223.Cm resetlog Ns ging 224or 225.Cm flush Ns ing , 226be quiet about actions 227(implies 228.Fl f ) . 229This is useful for adjusting rules by executing multiple 230.Nm 231commands in a script 232(e.g., 233.Ql sh\ /etc/rc.firewall ) , 234or by processing a file of many 235.Nm 236rules across a remote login session. 237If a 238.Cm flush 239is performed in normal (verbose) mode (with the default kernel 240configuration), it prints a message. 241Because all rules are flushed, the message might not be delivered 242to the login session, causing the remote login session to be closed 243and the remainder of the ruleset to not be processed. 244Access to the console would then be required to recover. 245.It Fl S 246While listing rules, show the 247.Em set 248each rule belongs to. 249If this flag is not specified, disabled rules will not be 250listed. 251.It Fl s Op Ar field 252While listing pipes, sort according to one of the four 253counters (total or current packets or bytes). 254.It Fl t 255While listing, show last match timestamp. 256.El 257.Pp 258To ease configuration, rules can be put into a file which is 259processed using 260.Nm 261as shown in the last synopsis line. 262An absolute 263.Ar pathname 264must be used. 265The file will be read line by line and applied as arguments to the 266.Nm 267utility. 268.Pp 269Optionally, a preprocessor can be specified using 270.Fl p Ar preproc 271where 272.Ar pathname 273is to be piped through. 274Useful preprocessors include 275.Xr cpp 1 276and 277.Xr m4 1 . 278If 279.Ar preproc 280doesn't start with a slash 281.Pq Ql / 282as its first character, the usual 283.Ev PATH 284name search is performed. 285Care should be taken with this in environments where not all 286file systems are mounted (yet) by the time 287.Nm 288is being run (e.g. when they are mounted over NFS). 289Once 290.Fl p 291has been specified, optional 292.Fl D 293and 294.Fl U 295specifications can follow and will be passed on to the preprocessor. 296This allows for flexible configuration files (like conditionalizing 297them on the local hostname) and the use of macros to centralize 298frequently required arguments like IP addresses. 299.Pp 300The 301.Nm 302.Cm pipe 303and 304.Cm queue 305commands are used to configure the traffic shaper, as shown in the 306.Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION 307Section below. 308.Pp 309If the world and the kernel get out of sync the 310.Nm 311ABI may break, preventing you from being able to add any rules. This can 312adversely affect the booting process. You can use 313.Nm 314.Cm disable 315.Cm firewall 316to temporarily disable the firewall to regain access to the network, 317allowing you to fix the problem. 318.Sh PACKET FLOW 319A packet is checked against the active ruleset in multiple places 320in the protocol stack, under control of several sysctl variables. 321These places and variables are shown below, and it is important to 322have this picture in mind in order to design a correct ruleset. 323.Bd -literal -offset indent 324 ^ to upper layers V 325 | | 326 +------------>------------+ 327 ^ V 328 [ip_input] [ip_output] net.inet.ip.fw.enable=1 329 | | 330 ^ V 331[ether_demux_oncpu] [ether_output_frame] net.link.ether.ipfw=1 332 ^ V 333 | to devices | 334.Ed 335.Pp 336As can be noted from the above picture, the number of 337times the same packet goes through the firewall can 338vary between 0 and 4 depending on packet source and 339destination, and system configuration. 340.Pp 341Note that as packets flow through the stack, headers can be 342stripped or added to it, and so they may or may not be available 343for inspection. 344E.g., incoming packets will include the MAC header when 345.Nm 346is invoked from 347.Fn ether_demux_oncpu , 348but the same packets will have the MAC header stripped off when 349.Nm 350is invoked from 351.Fn ip_input . 352.Pp 353Also note that each packet is always checked against the complete ruleset, 354irrespective of the place where the check occurs, or the source of the packet. 355If a rule contains some match patterns or actions which are not valid 356for the place of invocation (e.g. trying to match a MAC header within 357.Fn ip_input ) , 358the match pattern will not match, but a 359.Cm not 360operator in front of such patterns 361.Em will 362cause the pattern to 363.Em always 364match on those packets. 365It is thus the responsibility of 366the programmer, if necessary, to write a suitable ruleset to 367differentiate among the possible places. 368.Cm skipto 369rules can be useful here, as an example: 370.Bd -literal -offset indent 371# packets from ether_demux_oncpu 372ipfw add 10 skipto 1000 all from any to any layer2 in 373# packets from ip_input 374ipfw add 10 skipto 2000 all from any to any not layer2 in 375# packets from ip_output 376ipfw add 10 skipto 3000 all from any to any not layer2 out 377# packets from ether_output_frame 378ipfw add 10 skipto 4000 all from any to any layer2 out 379.Ed 380.Sh RULE FORMAT 381The format of 382.Nm 383rules is the following: 384.Bd -ragged -offset indent 385.Op Ar rule_number 386.Op Cm set Ar set_number 387.Op Cm prob Ar match_probability 388.br 389.Ar " " action 390.Op Cm log Op Cm logamount Ar number 391.Ar body 392.Ed 393.Pp 394where the body of the rule specifies which information is used 395for filtering packets, among the following: 396.Pp 397.Bl -tag -width "Source and dest. addresses and ports" -offset XXX -compact 398.It Layer-2 header fields 399When available 400.It IPv4 Protocol 401TCP, UDP, ICMP, etc. 402.It Source and dest. addresses and ports 403.It Direction 404See Section 405.Sx PACKET FLOW 406.It Transmit and receive interface 407By name or address 408.It Misc. IP header fields 409Version, type of service, datagram length, identification, 410fragment flag (non-zero IP offset), 411Time To Live 412.It IP options 413.It Misc. TCP header fields 414TCP flags (SYN, FIN, ACK, RST, etc.), 415sequence number, acknowledgment number, 416window 417.It TCP options 418.It ICMP types 419for ICMP packets 420.It User/group ID 421When the packet can be associated with a local socket. 422.El 423.Pp 424Note that some of the above information, e.g. source MAC or IP addresses and 425TCP/UDP ports, could easily be spoofed, so filtering on those fields 426alone might not guarantee the desired results. 427.Bl -tag -width indent 428.It Ar rule_number 429Each rule is associated with a 430.Ar rule_number 431in the range 1..65535, with the latter reserved for the 432.Em default 433rule. 434Rules are checked sequentially by rule number. 435Multiple rules can have the same number, in which case they are 436checked (and listed) according to the order in which they have 437been added. 438If a rule is entered without specifying a number, the kernel will 439assign one in such a way that the rule becomes the last one 440before the 441.Em default 442rule. 443Automatic rule numbers are assigned by incrementing the last 444non-default rule number by the value of the sysctl variable 445.Ar net.inet.ip.fw.autoinc_step 446which defaults to 100. 447If this is not possible (e.g. because we would go beyond the 448maximum allowed rule number), the number of the last 449non-default value is used instead. 450.It Cm set Ar set_number 451Each rule is associated with a 452.Ar set_number 453in the range 0..31, with the latter reserved for the 454.Em default 455rule. 456Sets can be individually disabled and enabled, so this parameter 457is of fundamental importance for atomic ruleset manipulation. 458It can be also used to simplify deletion of groups of rules. 459If a rule is entered without specifying a set number, 460set 0 will be used. 461.It Cm prob Ar match_probability 462A match is only declared with the specified probability 463(floating point number between 0 and 1). 464This can be useful for a number of applications such as 465random packet drop or 466(in conjunction with 467.Xr dummynet 4 ) 468to simulate the effect of multiple paths leading to out-of-order 469packet delivery. 470.It Cm log Op Cm logamount Ar number 471When a packet matches a rule with the 472.Cm log 473keyword, a message will be 474logged to 475.Xr syslogd 8 476with a 477.Dv LOG_SECURITY 478facility. 479The logging only occurs if the sysctl variable 480.Em net.inet.ip.fw.verbose 481is set to 1 482(which is the default when the kernel is compiled with 483.Dv IPFIREWALL_VERBOSE ) 484and the number of packets logged so far for that 485particular rule does not exceed the 486.Cm logamount 487parameter. 488If no 489.Cm logamount 490is specified, the limit is taken from the sysctl variable 491.Em net.inet.ip.fw.verbose_limit . 492In both cases, a value of 0 removes the logging limit. 493.Pp 494Once the limit is reached, logging can be re-enabled by 495clearing the logging counter or the packet counter for that entry, see the 496.Cm resetlog 497command. 498.El 499.Ss RULE ACTIONS 500A rule can be associated with one of the following actions, which 501will be executed when the packet matches the body of the rule. 502.Bl -tag -width indent 503.It Cm allow | accept | pass | permit 504Allow packets that match rule. 505The search terminates. 506.It Cm check-state 507Checks the packet against the dynamic ruleset. 508If a match is found, execute the action associated with 509the rule which generated this dynamic rule, otherwise 510move to the next rule. 511.br 512.Cm Check-state 513rules do not have a body. 514If no 515.Cm check-state 516rule is found, the dynamic ruleset is checked at the first 517.Cm keep-state 518or 519.Cm limit 520rule. 521.It Cm count 522Update counters for all packets that match rule. 523The search continues with the next rule. 524.It Cm deny | drop 525Discard packets that match this rule. 526The search terminates. 527.It Cm divert Ar port 528Divert packets that match this rule to the 529.Xr divert 4 530socket bound to port 531.Ar port . 532The search terminates. 533.It Cm fwd | forward Ar ipaddr Ns Op , Ns Ar port 534Change the next-hop on matching packets to 535.Ar ipaddr , 536which can be an IP address in dotted quad format or a host name. 537The search terminates if this rule matches. 538.Pp 539If 540.Ar ipaddr 541is a local address, then matching packets will be forwarded to 542.Ar port 543(or the port number in the packet if one is not specified in the rule) 544on the local machine. 545.br 546If 547.Ar ipaddr 548is not a local address, then the port number 549(if specified) is ignored, and the packet will be 550forwarded to the remote address, using the route as found in 551the local routing table for that IP. 552.br 553A 554.Ar fwd 555rule will not match layer-2 packets (those received 556on 557.Fn ether_input 558or 559.Fn ether_output ) . 560.br 561The 562.Cm fwd 563action does not change the contents of the packet at all. 564In particular, the destination address remains unmodified, so 565packets forwarded to another system will usually be rejected by that system 566unless there is a matching rule on that system to capture them. 567For packets forwarded locally, 568the local address of the socket will be 569set to the original destination address of the packet. 570This makes the 571.Xr netstat 1 572entry look rather weird but is intended for 573use with transparent proxy servers. 574.It Cm pipe Ar pipe_nr 575Pass packet to a 576.Xr dummynet 4 577.Dq pipe 578(for bandwidth limitation, delay, etc.). 579See the 580.Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION 581Section for further information. 582The search terminates; however, on exit from the pipe and if 583the 584.Xr sysctl 8 585variable 586.Em net.inet.ip.fw.one_pass 587is not set, the packet is passed again to the firewall code 588starting from the next rule. 589.It Cm queue Ar queue_nr 590Pass packet to a 591.Xr dummynet 4 592.Dq queue 593(for bandwidth limitation using WF2Q+). 594.It Cm reject 595(Deprecated). 596Synonym for 597.Cm unreach host . 598.It Cm reset 599Discard packets that match this rule, and if the 600packet is a TCP packet, try to send a TCP reset (RST) notice. 601The search terminates. 602.It Cm skipto Ar number 603Skip all subsequent rules numbered less than 604.Ar number . 605The search continues with the first rule numbered 606.Ar number 607or higher. 608.It Cm tee Ar port 609Send a copy of packets matching this rule to the 610.Xr divert 4 611socket bound to port 612.Ar port . 613The search terminates and the original packet is accepted 614(but see Section 615.Sx BUGS 616below). 617.It Cm unreach Ar code 618Discard packets that match this rule, and try to send an ICMP 619unreachable notice with code 620.Ar code , 621where 622.Ar code 623is a number from 0 to 255, or one of these aliases: 624.Cm net , host , protocol , port , 625.Cm needfrag , srcfail , net-unknown , host-unknown , 626.Cm isolated , net-prohib , host-prohib , tosnet , 627.Cm toshost , filter-prohib , host-precedence 628or 629.Cm precedence-cutoff . 630The search terminates. 631.El 632.Ss RULE BODY 633The body of a rule contains zero or more patterns (such as 634specific source and destination addresses or ports, 635protocol options, incoming or outgoing interfaces, etc.) 636that the packet must match in order to be recognised. 637In general, the patterns are connected by (implicit) 638.Cm and 639operators -- i.e. all must match in order for the 640rule to match. 641Individual patterns can be prefixed by the 642.Cm not 643operator to reverse the result of the match, as in 644.Pp 645.Dl "ipfw add 100 allow ip from not 1.2.3.4 to any" 646.Pp 647Additionally, sets of alternative match patterns 648.Em ( or-blocks ) 649can be constructed by putting the patterns in 650lists enclosed between parentheses ( ) or braces { }, and 651using the 652.Cm or 653operator as follows: 654.Pp 655.Dl "ipfw add 100 allow ip from { x or not y or z } to any" 656.Pp 657Only one level of parentheses is allowed. 658Beware that most shells have special meanings for parentheses 659or braces, so it is advisable to put a backslash \\ in front of them 660to prevent such interpretations. 661.Pp 662The body of a rule must in general include a source and destination 663address specifier. 664The keyword 665.Ar any 666can be used in various places to specify that the content of 667a required field is irrelevant. 668.Pp 669The rule body has the following format: 670.Bd -ragged -offset indent 671.Op Ar proto Cm from Ar src Cm to Ar dst 672.Op Ar options 673.Ed 674.Pp 675The first part (protocol from src to dst) is for backward 676compatibility with 677.Nm ipfw1 . 678In 679.Nm ipfw2 680any match pattern (including MAC headers, IPv4 protocols, 681addresses and ports) can be specified in the 682.Ar options 683section. 684.Pp 685Rule fields have the following meaning: 686.Bl -tag -width indent 687.It Ar proto : protocol | Cm { Ar protocol Cm or ... } 688An IPv4 protocol (or an 689.Em or-block 690with multiple protocols) specified by number or name 691(for a complete list see 692.Pa /etc/protocols ) . 693The 694.Cm ip 695or 696.Cm all 697keywords mean any protocol will match. 698.It Ar src No and Ar dst : ip-address | Cm { Ar ip-address Cm or ... } Op Ar ports 699A single 700.Ar ip-address 701, or an 702.Em or-block 703containing one or more of them, 704optionally followed by 705.Ar ports 706specifiers. 707.It Ar ip-address : 708An address (or set of addresses) specified in one of the following 709ways, optionally preceded by a 710.Cm not 711operator: 712.Bl -tag -width indent 713.It Cm any 714matches any IP address. 715.It Cm me 716matches any IP address configured on an interface in the system. 717The address list is evaluated at the time the packet is 718analysed. 719.It Ar numeric-ip | hostname 720Matches a single IPv4 address, specified as dotted-quad or a hostname. 721Hostnames are resolved at the time the rule is added to the firewall list. 722.It Ar addr Ns / Ns Ar masklen 723Matches all addresses with base 724.Ar addr 725(specified as a dotted quad or a hostname) 726and mask width of 727.Cm masklen 728bits. 729As an example, 1.2.3.4/25 will match 730all IP numbers from 1.2.3.0 to 1.2.3.127 . 731.It Ar addr Ns / Ns Ar masklen Ns Cm { Ns Ar num,num,... Ns Cm } 732Matches all addresses with base address 733.Ar addr 734(specified as a dotted quad or a hostname) 735and whose last byte is in the list between braces { } . 736Note that there must be no spaces between braces, commas and 737numbers. 738The 739.Ar masklen 740field is used to limit the size of the set of addresses, 741and can have any value between 24 and 32. 742.br 743As an example, an address specified as 1.2.3.4/24{128,35,55,89} 744will match the following IP addresses: 745.br 7461.2.3.128 1.2.3.35 1.2.3.55 1.2.3.89 . 747.br 748This format is particularly useful to handle sparse address sets 749within a single rule. Because the matching occurs using a 750bitmask, it takes constant time and dramatically reduces 751the complexity of rulesets. 752.It Ar addr Ns : Ns Ar mask 753Matches all addresses with base 754.Ar addr 755(specified as a dotted quad or a hostname) 756and the mask of 757.Ar mask , 758specified as a dotted quad. 759As an example, 1.2.3.4/255.0.255.0 will match 7601.*.3.*. 761We suggest to use this form only for non-contiguous 762masks, and resort to the 763.Ar addr Ns / Ns Ar masklen 764format for contiguous masks, which is more compact and less 765error-prone. 766.El 767.It Ar ports : Oo Cm not Oc Bro Ar port | port Ns \&- Ns Ar port Ns Brc Op , Ns Ar ... 768For protocols which support port numbers (such as TCP and UDP), optional 769.Cm ports 770may be specified as one or more ports or port ranges, separated 771by commas but no spaces, and an optional 772.Cm not 773operator. 774The 775.Ql \&- 776notation specifies a range of ports (including boundaries). 777.Pp 778Service names (from 779.Pa /etc/services ) 780may be used instead of numeric port values. 781The length of the port list is limited to 30 ports or ranges, 782though one can specify larger ranges by using an 783.Em or-block 784in the 785.Cm options 786section of the rule. 787.Pp 788A backslash 789.Pq Ql \e 790can be used to escape the dash 791.Pq Ql - 792character in a service name (from a shell, the backslash must be 793typed twice to avoid the shell itself interpreting it as an escape 794character). 795.Pp 796.Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any" 797.Pp 798Fragmented packets which have a non-zero offset (i.e. not the first 799fragment) will never match a rule which has one or more port 800specifications. 801See the 802.Cm frag 803option for details on matching fragmented packets. 804.El 805.Ss RULE OPTIONS (MATCH PATTERNS) 806Additional match patterns can be used within 807rules. Zero or more of these so-called 808.Em options 809can be present in a rule, optionally prefixed by the 810.Cm not 811operand, and possibly grouped into 812.Em or-blocks . 813.Pp 814The following match patterns can be used (listed in alphabetical order): 815.Bl -tag -width indent 816.It Cm dst-ip Ar ip address 817Matches IP packets whose destination IP is one of the address(es) 818specified as argument. 819.It Cm dst-port Ar source ports 820Matches IP packets whose destination port is one of the port(s) 821specified as argument. 822.It Cm established 823Matches TCP packets that have the RST or ACK bits set. 824.It Cm frag 825Matches packets that are fragments and not the first 826fragment of an IP datagram. Note that these packets will not have 827the next protocol header (e.g. TCP, UDP) so options that look into 828these headers cannot match. 829.It Cm gid Ar group 830Matches all TCP or UDP packets sent by or received for a 831.Ar group . 832A 833.Ar group 834may be specified by name or number. 835.It Cm icmptypes Ar types 836Matches ICMP packets whose ICMP type is in the list 837.Ar types . 838The list may be specified as any combination of ranges or 839individual types separated by commas. 840The supported ICMP types are: 841.Pp 842echo reply 843.Pq Cm 0 , 844destination unreachable 845.Pq Cm 3 , 846source quench 847.Pq Cm 4 , 848redirect 849.Pq Cm 5 , 850echo request 851.Pq Cm 8 , 852router advertisement 853.Pq Cm 9 , 854router solicitation 855.Pq Cm 10 , 856time-to-live exceeded 857.Pq Cm 11 , 858IP header bad 859.Pq Cm 12 , 860timestamp request 861.Pq Cm 13 , 862timestamp reply 863.Pq Cm 14 , 864information request 865.Pq Cm 15 , 866information reply 867.Pq Cm 16 , 868address mask request 869.Pq Cm 17 870and address mask reply 871.Pq Cm 18 . 872.It Cm in | out 873Matches incoming or outgoing packets, respectively. 874.Cm in 875and 876.Cm out 877are mutually exclusive (in fact, 878.Cm out 879is implemented as 880.Cm not in Ns No ). 881.It Cm ipid Ar id 882Matches IP packets whose 883.Cm ip_id 884field has value 885.Ar id . 886.It Cm iplen Ar len 887Matches IP packets whose total length, including header and data, is 888.Ar len 889bytes. 890.It Cm ipoptions Ar spec 891Matches packets whose IP header contains the comma separated list of 892options specified in 893.Ar spec . 894The supported IP options are: 895.Pp 896.Cm ssrr 897(strict source route), 898.Cm lsrr 899(loose source route), 900.Cm rr 901(record packet route) and 902.Cm ts 903(timestamp). 904The absence of a particular option may be denoted 905with a 906.Ql \&! . 907.It Cm ipprecedence Ar precedence 908Matches IP packets whose precedence field is equal to 909.Ar precedence . 910.It Cm iptos Ar spec 911Matches IP packets whose 912.Cm tos 913field contains the comma separated list of 914service types specified in 915.Ar spec . 916The supported IP types of service are: 917.Pp 918.Cm lowdelay 919.Pq Dv IPTOS_LOWDELAY , 920.Cm throughput 921.Pq Dv IPTOS_THROUGHPUT , 922.Cm reliability 923.Pq Dv IPTOS_RELIABILITY , 924.Cm mincost 925.Pq Dv IPTOS_MINCOST , 926.Cm congestion 927.Pq Dv IPTOS_CE . 928The absence of a particular type may be denoted 929with a 930.Ql \&! . 931.It Cm ipttl Ar ttl 932Matches IP packets whose time to live is 933.Ar ttl . 934.It Cm ipversion Ar ver 935Matches IP packets whose IP version field is 936.Ar ver . 937.It Cm keep-state 938Upon a match, the firewall will create a dynamic rule, whose 939default behaviour is to match bidirectional traffic between 940source and destination IP/port using the same protocol. 941The rule has a limited lifetime (controlled by a set of 942.Xr sysctl 8 943variables), and the lifetime is refreshed every time a matching 944packet is found. 945.It Cm layer2 946Matches only layer2 packets, i.e. those passed to 947.Nm 948from 949.Fn ether_demux_oncpu 950and 951.Fn ether_output_frame . 952.It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N 953The firewall will only allow 954.Ar N 955connections with the same 956set of parameters as specified in the rule. 957One or more 958of source and destination addresses and ports can be 959specified. 960.It Cm { MAC | mac } Ar dst-mac src-mac 961Match packets with a given 962.Ar dst-mac 963and 964.Ar src-mac 965addresses, specified as the 966.Cm any 967keyword (matching any MAC address), or six groups of hex digits 968separated by colons, 969and optionally followed by a mask indicating how many bits are 970significant, as in 971.Pp 972.Dl "MAC 10:20:30:40:50:60/33 any" 973.Pp 974Note that the order of MAC addresses (destination first, 975source second) is 976the same as on the wire, but the opposite of the one used for 977IP addresses. 978.It Cm mac-type Ar mac-type 979Matches packets whose Ethernet Type field 980corresponds to one of those specified as argument. 981.Ar mac-type 982is specified in the same way as 983.Cm port numbers 984(i.e. one or more comma-separated single values or ranges). 985You can use symbolic names for known values such as 986.Em vlan , ipv4, ipv6 . 987Values can be entered as decimal or hexadecimal (if prefixed by 0x), 988and they are always printed as hexadecimal (unless the 989.Cm -N 990option is used, in which case symbolic resolution will be attempted). 991.It Cm proto Ar protocol 992Matches packets with the corresponding IPv4 protocol. 993.It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar ipno | Ar any 994Matches packets received, transmitted or going through, 995respectively, the interface specified by exact name 996.Pq Ar ifX , 997by device name 998.Pq Ar if Ns Cm * , 999by IP address, or through some interface. 1000.Pp 1001The 1002.Cm via 1003keyword causes the interface to always be checked. 1004If 1005.Cm recv 1006or 1007.Cm xmit 1008is used instead of 1009.Cm via , 1010then only the receive or transmit interface (respectively) 1011is checked. 1012By specifying both, it is possible to match packets based on 1013both receive and transmit interface, e.g.: 1014.Pp 1015.Dl "ipfw add deny ip from any to any out recv ed0 xmit ed1" 1016.Pp 1017The 1018.Cm recv 1019interface can be tested on either incoming or outgoing packets, 1020while the 1021.Cm xmit 1022interface can only be tested on outgoing packets. 1023So 1024.Cm out 1025is required (and 1026.Cm in 1027is invalid) whenever 1028.Cm xmit 1029is used. 1030.Pp 1031A packet may not have a receive or transmit interface: packets 1032originating from the local host have no receive interface, 1033while packets destined for the local host have no transmit 1034interface. 1035.It Cm setup 1036Matches TCP packets that have the SYN bit set but no ACK bit. 1037This is the short form of 1038.Dq Li tcpflags\ syn,!ack . 1039.It Cm src-ip Ar ip-address 1040Matches IP packets whose source IP is one of the address(es) 1041specified as argument. 1042.It Cm src-port Ar ports 1043Matches IP packets whose source port is one of the port(s) 1044specified as argument. 1045.It Cm tcpack Ar ack 1046TCP packets only. 1047Match if the TCP header acknowledgment number field is set to 1048.Ar ack . 1049.It Cm tcpflags Ar spec 1050TCP packets only. 1051Match if the TCP header contains the comma separated list of 1052flags specified in 1053.Ar spec . 1054The supported TCP flags are: 1055.Pp 1056.Cm fin , 1057.Cm syn , 1058.Cm rst , 1059.Cm psh , 1060.Cm ack 1061and 1062.Cm urg . 1063The absence of a particular flag may be denoted 1064with a 1065.Ql \&! . 1066A rule which contains a 1067.Cm tcpflags 1068specification can never match a fragmented packet which has 1069a non-zero offset. 1070See the 1071.Cm frag 1072option for details on matching fragmented packets. 1073.It Cm tcpseq Ar seq 1074TCP packets only. 1075Match if the TCP header sequence number field is set to 1076.Ar seq . 1077.It Cm tcpwin Ar win 1078TCP packets only. 1079Match if the TCP header window field is set to 1080.Ar win . 1081.It Cm tcpoptions Ar spec 1082TCP packets only. 1083Match if the TCP header contains the comma separated list of 1084options specified in 1085.Ar spec . 1086The supported TCP options are: 1087.Pp 1088.Cm mss 1089(maximum segment size), 1090.Cm window 1091(tcp window advertisement), 1092.Cm sack 1093(selective ack), 1094.Cm ts 1095(rfc1323 timestamp) and 1096.Cm cc 1097(rfc1644 t/tcp connection count). 1098The absence of a particular option may be denoted 1099with a 1100.Ql \&! . 1101.It Cm uid Ar user 1102Match all TCP or UDP packets sent by or received for a 1103.Ar user . 1104A 1105.Ar user 1106may be matched by name or identification number. 1107.El 1108.Sh SETS OF RULES 1109Each rule belongs to one of 32 different 1110.Em sets 1111, numbered 0 to 31. 1112Set 31 is reserved for the default rule. 1113.Pp 1114By default, rules are put in set 0, unless you use the 1115.Cm set N 1116attribute when entering a new rule. 1117Sets can be individually and atomically enabled or disabled, 1118so this mechanism permits an easy way to store multiple configurations 1119of the firewall and quickly (and atomically) switch between them. 1120The command to enable/disable sets is 1121.Bd -ragged -offset indent 1122.Nm 1123.Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ... 1124.Ed 1125.Pp 1126where multiple 1127.Cm enable 1128or 1129.Cm disable 1130sections can be specified. 1131Command execution is atomic on all the sets specified in the command. 1132By default, all sets are enabled. 1133.Pp 1134When you disable a set, its rules behave as if they do not exist 1135in the firewall configuration, with only one exception: 1136.Bd -ragged -offset indent 1137dynamic rules created from a rule before it had been disabled 1138will still be active until they expire. In order to delete 1139dynamic rules you have to explicitly delete the parent rule 1140which generated them. 1141.Ed 1142.Pp 1143The set number of rules can be changed with the command 1144.Bd -ragged -offset indent 1145.Nm 1146.Cm set move 1147.Brq Cm rule Ar rule-number | old-set 1148.Cm to Ar new-set 1149.Ed 1150.Pp 1151Also, you can atomically swap two rulesets with the command 1152.Bd -ragged -offset indent 1153.Nm 1154.Cm set swap Ar first-set second-set 1155.Ed 1156.Pp 1157See the 1158.Sx EXAMPLES 1159Section on some possible uses of sets of rules. 1160.Sh STATEFUL FIREWALL 1161Stateful operation is a way for the firewall to dynamically 1162create rules for specific flows when packets that 1163match a given pattern are detected. Support for stateful 1164operation comes through the 1165.Cm check-state , keep-state 1166and 1167.Cm limit 1168options of 1169.Nm 1170rules. 1171.Pp 1172Dynamic rules are created when a packet matches a 1173.Cm keep-state 1174or 1175.Cm limit 1176rule, causing the creation of a 1177.Em dynamic 1178rule which will match all and only packets with 1179a given 1180.Em protocol 1181between a 1182.Em src-ip/src-port dst-ip/dst-port 1183pair of addresses ( 1184.Em src 1185and 1186.Em dst 1187are used here only to denote the initial match addresses, but they 1188are completely equivalent afterwards). 1189Dynamic rules will be checked at the first 1190.Cm check-state, keep-state 1191or 1192.Cm limit 1193occurrence, and the action performed upon a match will be the same 1194as in the parent rule. 1195.Pp 1196Note that no additional attributes other than protocol and IP addresses 1197and ports are checked on dynamic rules. 1198.Pp 1199The typical use of dynamic rules is to keep a closed firewall configuration, 1200but let the first TCP SYN packet from the inside network install a 1201dynamic rule for the flow so that packets belonging to that session 1202will be allowed through the firewall: 1203.Pp 1204.Dl "ipfw add check-state" 1205.Dl "ipfw add allow tcp from my-subnet to any setup keep-state" 1206.Dl "ipfw add deny tcp from any to any" 1207.Pp 1208A similar approach can be used for UDP, where an UDP packet coming 1209from the inside will install a dynamic rule to let the response through 1210the firewall: 1211.Pp 1212.Dl "ipfw add check-state" 1213.Dl "ipfw add allow udp from my-subnet to any keep-state" 1214.Dl "ipfw add deny udp from any to any" 1215.Pp 1216Dynamic rules expire after some time, which depends on the status 1217of the flow and the setting of some 1218.Cm sysctl 1219variables. 1220See Section 1221.Sx SYSCTL VARIABLES 1222for more details. 1223For TCP sessions, dynamic rules can be instructed to periodically 1224send keepalive packets to refresh the state of the rule when it is 1225about to expire. 1226.Pp 1227See Section 1228.Sx EXAMPLES 1229for more examples on how to use dynamic rules. 1230.Sh TRAFFIC SHAPER (DUMMYNET) CONFIGURATION 1231.Nm 1232is also the user interface for the 1233.Xr dummynet 4 1234traffic shaper. 1235.Pp 1236.Nm dummynet 1237operates by first using the firewall to classify packets and divide them into 1238.Em flows , 1239using any match pattern that can be used in 1240.Nm 1241rules. 1242Depending on local policies, a flow can contain packets for a single 1243TCP connection, or from/to a given host, or entire subnet, or a 1244protocol type, etc. 1245.Pp 1246Packets belonging to the same flow are then passed to either of two 1247different objects, which implement the traffic regulation: 1248.Bl -hang -offset XXXX 1249.It Em pipe 1250A pipe emulates a link with given bandwidth, propagation delay, 1251queue size and packet loss rate. 1252Packets are queued in front of the pipe as they come out from the classifier, 1253and then transferred to the pipe according to the pipe's parameters. 1254.It Em queue 1255A queue 1256is an abstraction used to implement the WF2Q+ 1257(Worst-case Fair Weighted Fair Queueing) policy, which is 1258an efficient variant of the WFQ policy. 1259.br 1260The queue associates a 1261.Em weight 1262and a reference pipe to each flow, and then all backlogged (i.e., 1263with packets queued) flows linked to the same pipe share the pipe's 1264bandwidth proportionally to their weights. 1265Note that weights are not priorities; a flow with a lower weight 1266is still guaranteed to get its fraction of the bandwidth even if a 1267flow with a higher weight is permanently backlogged. 1268.El 1269In practice, 1270.Em pipes 1271can be used to set hard limits to the bandwidth that a flow can use, whereas 1272.Em queues 1273can be used to determine how different flow share the available bandwidth. 1274.Pp 1275The 1276.Em pipe 1277and 1278.Em queue 1279configuration commands are the following: 1280.Bd -ragged -offset indent 1281.Cm pipe Ar number Cm config Ar pipe-configuration 1282.Pp 1283.Cm queue Ar number Cm config Ar queue-configuration 1284.Ed 1285.Pp 1286The following parameters can be configured for a pipe: 1287.Pp 1288.Bl -tag -width indent -compact 1289.It Cm bw Ar bandwidth 1290Bandwidth, measured in 1291.Sm off 1292.Op Cm K | M 1293.Brq Cm bit/s | Byte/s . 1294.Sm on 1295.Pp 1296A value of 0 (default) means unlimited bandwidth. 1297The unit must immediately follow the number, as in 1298.Pp 1299.Dl "ipfw pipe 1 config bw 300Kbit/s" 1300.Pp 1301.It Cm delay Ar ms-delay 1302Propagation delay, measured in milliseconds. 1303The value is rounded to the next multiple of the clock tick 1304(typically 10ms, but it is a good practice to run kernels 1305with 1306.Cd "options HZ=1000" 1307to reduce 1308the granularity to 1ms or less). 1309Default value is 0, meaning no delay. 1310.El 1311.Pp 1312The following parameters can be configured for a queue: 1313.Pp 1314.Bl -tag -width indent -compact 1315.It Cm pipe Ar pipe_nr 1316Connects a queue to the specified pipe. 1317Multiple queues (with the same or different weights) can be connected to 1318the same pipe, which specifies the aggregate rate for the set of queues. 1319.Pp 1320.It Cm weight Ar weight 1321Specifies the weight to be used for flows matching this queue. 1322The weight must be in the range 1..100, and defaults to 1. 1323.El 1324.Pp 1325Finally, the following parameters can be configured for both 1326pipes and queues: 1327.Pp 1328.Bl -tag -width XXXX -compact 1329.It Cm buckets Ar hash-table-size 1330Specifies the size of the hash table used for storing the 1331various queues. 1332Default value is 64 controlled by the 1333.Xr sysctl 8 1334variable 1335.Em net.inet.ip.dummynet.hash_size , 1336allowed range is 16 to 65536. 1337.Pp 1338.It Cm mask Ar mask-specifier 1339Packets sent to a given pipe or queue by an 1340.Nm 1341rule can be further classified into multiple flows, each of which is then 1342sent to a different 1343.Em dynamic 1344pipe or queue. 1345A flow identifier is constructed by masking the IP addresses, 1346ports and protocol types as specified with the 1347.Cm mask 1348options in the configuration of the pipe or queue. 1349For each different flow identifier, a new pipe or queue is created 1350with the same parameters as the original object, and matching packets 1351are sent to it. 1352.Pp 1353Thus, when 1354.Em dynamic pipes 1355are used, each flow will get the same bandwidth as defined by the pipe, 1356whereas when 1357.Em dynamic queues 1358are used, each flow will share the parent's pipe bandwidth evenly 1359with other flows generated by the same queue (note that other queues 1360with different weights might be connected to the same pipe). 1361.br 1362Available mask specifiers are a combination of one or more of the following: 1363.Pp 1364.Cm dst-ip Ar mask , 1365.Cm src-ip Ar mask , 1366.Cm dst-port Ar mask , 1367.Cm src-port Ar mask , 1368.Cm proto Ar mask 1369or 1370.Cm all , 1371.Pp 1372where the latter means all bits in all fields are significant. 1373.Pp 1374.It Cm noerror 1375When a packet is dropped by a dummynet queue or pipe, the error 1376is normally reported to the caller routine in the kernel, in the 1377same way as it happens when a device queue fills up. Setting this 1378option reports the packet as successfully delivered, which can be 1379needed for some experimental setups where you want to simulate 1380loss or congestion at a remote router. 1381.Pp 1382.Em NOTE: 1383This option is always on, 1384since 1385.Dx 1.11 . 1386.Pp 1387.It Cm plr Ar packet-loss-rate 1388Packet loss rate. 1389Argument 1390.Ar packet-loss-rate 1391is a floating-point number between 0 and 1, with 0 meaning no 1392loss, 1 meaning 100% loss. 1393The loss rate is internally represented on 31 bits. 1394.Pp 1395.It Cm queue Brq Ar slots | size Ns Cm Kbytes 1396Queue size, in 1397.Ar slots 1398or 1399.Cm KBytes . 1400Default value is 50 slots, which 1401is the typical queue size for Ethernet devices. 1402Note that for slow speed links you should keep the queue 1403size short or your traffic might be affected by a significant 1404queueing delay. 1405E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit 1406or 20s of queue on a 30Kbit/s pipe. 1407Even worse effect can result if you get packets from an 1408interface with a much larger MTU, e.g. the loopback interface 1409with its 16KB packets. 1410.Pp 1411.It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p 1412Make use of the RED (Random Early Detection) queue management algorithm. 1413.Ar w_q 1414and 1415.Ar max_p 1416are floating 1417point numbers between 0 and 1 (0 not included), while 1418.Ar min_th 1419and 1420.Ar max_th 1421are integer numbers specifying thresholds for queue management 1422(thresholds are computed in bytes if the queue has been defined 1423in bytes, in slots otherwise). 1424The 1425.Xr dummynet 4 1426also supports the gentle RED variant (gred). 1427Three 1428.Xr sysctl 8 1429variables can be used to control the RED behaviour: 1430.Bl -tag -width indent 1431.It Em net.inet.ip.dummynet.red_lookup_depth 1432specifies the accuracy in computing the average queue 1433when the link is idle (defaults to 256, must be greater than zero) 1434.It Em net.inet.ip.dummynet.red_avg_pkt_size 1435specifies the expected average packet size (defaults to 512, must be 1436greater than zero) 1437.It Em net.inet.ip.dummynet.red_max_pkt_size 1438specifies the expected maximum packet size, only used when queue 1439thresholds are in bytes (defaults to 1500, must be greater than zero). 1440.El 1441.El 1442.Sh CHECKLIST 1443Here are some important points to consider when designing your 1444rules: 1445.Bl -bullet 1446.It 1447Remember that you filter both packets going 1448.Cm in 1449and 1450.Cm out . 1451Most connections need packets going in both directions. 1452.It 1453Remember to test very carefully. 1454It is a good idea to be near the console when doing this. 1455If you cannot be near the console, 1456use an auto-recovery script such as the one in 1457.Pa /usr/share/examples/ipfw/change_rules.sh . 1458.It 1459Don't forget the loopback interface. 1460.El 1461.Sh FINE POINTS 1462.Bl -bullet 1463.It 1464There are circumstances where fragmented datagrams are unconditionally 1465dropped. 1466TCP packets are dropped if they do not contain at least 20 bytes of 1467TCP header, UDP packets are dropped if they do not contain a full 8 1468byte UDP header, and ICMP packets are dropped if they do not contain 14694 bytes of ICMP header, enough to specify the ICMP type, code, and 1470checksum. 1471These packets are simply logged as 1472.Dq pullup failed 1473since there may not be enough good data in the packet to produce a 1474meaningful log entry. 1475.It 1476Another type of packet is unconditionally dropped, a TCP packet with a 1477fragment offset of one. 1478This is a valid packet, but it only has one use, to try 1479to circumvent firewalls. 1480When logging is enabled, these packets are 1481reported as being dropped by rule -1. 1482.It 1483If you are logged in over a network, loading the 1484.Xr kld 4 1485version of 1486.Nm 1487is probably not as straightforward as you would think. 1488I recommend the following command line: 1489.Bd -literal -offset indent 1490kldload /boot/modules/ipfw.ko && \e 1491ipfw add 32000 allow ip from any to any 1492.Ed 1493.Pp 1494Along the same lines, doing an 1495.Bd -literal -offset indent 1496ipfw flush 1497.Ed 1498.Pp 1499in similar surroundings is also a bad idea. 1500.It 1501The 1502.Nm 1503filter list may not be modified if the system security level 1504is set to 3 or higher 1505(see 1506.Xr init 8 1507for information on system security levels). 1508.El 1509.Sh PACKET DIVERSION 1510A 1511.Xr divert 4 1512socket bound to the specified port will receive all packets 1513diverted to that port. 1514If no socket is bound to the destination port, or if the kernel 1515wasn't compiled with divert socket support, the packets are 1516dropped. 1517.Sh SYSCTL VARIABLES 1518A set of 1519.Xr sysctl 8 1520variables controls the behaviour of the firewall and 1521associated modules 1522.Nm ( dummynet ) . 1523These are shown below together with their default value 1524(but always check with the 1525.Xr sysctl 8 1526command what value is actually in use) and meaning: 1527.Bl -tag -width indent 1528.It Em net.inet.ip.dummynet.expire : No 1 1529Lazily delete dynamic pipes/queue once they have no pending traffic. 1530You can disable this by setting the variable to 0, in which case 1531the pipes/queues will only be deleted when the threshold is reached. 1532.It Em net.inet.ip.dummynet.hash_size : No 64 1533Default size of the hash table used for dynamic pipes/queues. 1534This value is used when no 1535.Cm buckets 1536option is specified when configuring a pipe/queue. 1537.It Em net.inet.ip.dummynet.max_chain_len : No 16 1538Target value for the maximum number of pipes/queues in a hash bucket. 1539The product 1540.Cm max_chain_len*hash_size 1541is used to determine the threshold over which empty pipes/queues 1542will be expired even when 1543.Cm net.inet.ip.dummynet.expire=0 . 1544.It Em net.inet.ip.dummynet.red_lookup_depth : No 256 1545.It Em net.inet.ip.dummynet.red_avg_pkt_size : No 512 1546.It Em net.inet.ip.dummynet.red_max_pkt_size : No 1500 1547Parameters used in the computations of the drop probability 1548for the RED algorithm. 1549.It Em net.inet.ip.fw.autoinc_step : No 100 1550Delta between rule numbers when auto-generating them. 1551The value must be in the range 1..1000. 1552.It Em net.inet.ip.fw.curr_dyn_buckets : Em net.inet.ip.fw.dyn_buckets 1553The current number of buckets in the hash table for dynamic rules 1554(readonly). 1555.It Em net.inet.ip.fw.debug : No 1 1556Controls debugging messages produced by 1557.Nm . 1558.It Em net.inet.ip.fw.dyn_buckets : No 256 1559The number of buckets in the hash table for dynamic rules. 1560Must be a power of 2, up to 65536. 1561It only takes effect when all dynamic rules have expired, so you 1562are advised to use a 1563.Cm flush 1564command to make sure that the hash table is resized. 1565.It Em net.inet.ip.fw.dyn_count : No 3 1566Current number of dynamic rules 1567(read-only). 1568.It Em net.inet.ip.fw.dyn_keepalive : No 1 1569Enables generation of keepalive packets for 1570.Cm keep-state 1571rules on TCP sessions. A keepalive is generated to both 1572sides of the connection every 5 seconds for the last 20 1573seconds of the lifetime of the rule. 1574.It Em net.inet.ip.fw.dyn_max : No 8192 1575Maximum number of dynamic rules. 1576When you hit this limit, no more dynamic rules can be 1577installed until old ones expire. 1578.It Em net.inet.ip.fw.dyn_ack_lifetime : No 300 1579.It Em net.inet.ip.fw.dyn_syn_lifetime : No 20 1580.It Em net.inet.ip.fw.dyn_fin_lifetime : No 1 1581.It Em net.inet.ip.fw.dyn_rst_lifetime : No 1 1582.It Em net.inet.ip.fw.dyn_udp_lifetime : No 5 1583.It Em net.inet.ip.fw.dyn_short_lifetime : No 30 1584These variables control the lifetime, in seconds, of dynamic 1585rules. 1586Upon the initial SYN exchange the lifetime is kept short, 1587then increased after both SYN have been seen, then decreased 1588again during the final FIN exchange or when a RST is received. 1589Both 1590.Em dyn_fin_lifetime 1591and 1592.Em dyn_rst_lifetime 1593must be strictly lower than 5 seconds, the period of 1594repetition of keepalives. The firewall enforces that. 1595.It Em net.inet.ip.fw.enable : No 1 1596Enables the firewall. 1597Setting this variable to 0 lets you run your machine without 1598firewall even if compiled in. 1599.It Em net.inet.ip.fw.one_pass : No 1 1600When set, the packet exiting from the 1601.Xr dummynet 4 1602pipe is not passed though the firewall again. 1603Otherwise, after a pipe action, the packet is 1604reinjected into the firewall at the next rule. 1605.Pp 1606Note: layer 2 packets coming out of a pipe 1607are never reinjected in the firewall irrespective of the 1608value of this variable. 1609.It Em net.inet.ip.fw.verbose : No 1 1610Enables verbose messages. 1611.It Em net.inet.ip.fw.verbose_limit : No 0 1612Limits the number of messages produced by a verbose firewall. 1613.It Em net.link.ether.ipfw : No 0 1614Controls whether layer-2 packets are passed to 1615.Nm . 1616Default is no. 1617.El 1618.Sh IPFW2 ENHANCEMENTS 1619This Section lists the features that have been introduced in 1620.Nm ipfw2 1621which were not present in 1622.Nm ipfw1 . 1623We list them in order of the potential impact that they can 1624have in writing your rulesets. 1625You might want to consider using these features in order to 1626write your rulesets in a more efficient way. 1627.Bl -tag -width indent 1628.It Handling of non-IPv4 packets 1629.Nm ipfw1 1630will silently accept all non-IPv4 packets. 1631.Nm ipfw2 1632will filter all packets (including non-IPv4 ones) according to the ruleset. 1633To achieve the same behaviour as 1634.Nm ipfw1 1635you can use the following as the very first rule in your ruleset: 1636.Pp 1637.Dl "ipfw add 1 allow layer2 not mac-type ip" 1638.Pp 1639The 1640.Cm layer2 1641option might seem redundant, but it is necessary -- packets 1642passed to the firewall from layer3 will not have a MAC header, 1643so the 1644.Cm mac-type ip 1645pattern will always fail on them, and the 1646.Cm not 1647operator will make this rule into a pass-all. 1648.It Address sets 1649.Nm ipfw1 1650does not supports address sets (those in the form 1651.Ar addr/masklen{num,num,...} ) . 1652.It Port specifications 1653.Nm ipfw1 1654only allows one port range when specifying TCP and UDP ports, and 1655is limited to 10 entries instead of the 15 allowed by 1656.Nm ipfw2 . 1657Also, in 1658.Nm ipfw1 1659you can only specify ports when the rule is requesting 1660.Cm tcp 1661or 1662.Cm udp 1663packets. With 1664.Nm ipfw2 1665you can put port specifications in rules matching all packets, 1666and the match will be attempted only on those packets carrying 1667protocols which include port identifiers. 1668.Pp 1669Finally, 1670.Nm ipfw1 1671allowed the first port entry to be specified as 1672.Ar port:mask 1673where 1674.Ar mask 1675can be an arbitrary 16-bit mask. 1676This syntax is of questionable usefulness and it is not 1677supported anymore in 1678.Nm ipfw2 . 1679.It Or-blocks 1680.Nm ipfw1 1681does not support Or-blocks. 1682.It keepalives 1683.Nm ipfw1 1684does not generate keepalives for stateful sessions. 1685As a consequence, it might cause idle sessions to drop because 1686the lifetime of the dynamic rules expires. 1687.It Sets of rules 1688.Nm ipfw1 1689does not implement sets of rules. 1690.It MAC header filtering and Layer-2 firewalling. 1691.Nm ipfw1 1692does not implement filtering on MAC header fields, nor is it 1693invoked on packets from 1694.Fn ether_demux_oncpu 1695and 1696.Fn ether_output_frame . 1697The sysctl variable 1698.Em net.link.ether.ipfw 1699has no effect there. 1700.It Options 1701The following options are not supported in 1702.Nm ipfw1 1703.Pp 1704.Cm dst-ip, dst-port, layer2, mac, mac-type, src-ip, src-port. 1705.Pp 1706Additionally, the following options are not supported in 1707.Nm ipfw1 1708(RELENG_4) 1709rules: 1710.Pp 1711.Cm ipid, iplen, ipprecedence, iptos, ipttl, 1712.Cm ipversion, tcpack, tcpseq, tcpwin . 1713.It Dummynet options 1714The following option for 1715.Nm dummynet 1716pipes/queues is not supported: 1717.Cm noerror . 1718.El 1719.Sh EXAMPLES 1720There are far too many possible uses of 1721.Nm 1722so this Section will only give a small set of examples. 1723.Ss BASIC PACKET FILTERING 1724This command adds an entry which denies all tcp packets from 1725.Em cracker.evil.org 1726to the telnet port of 1727.Em wolf.tambov.su 1728from being forwarded by the host: 1729.Pp 1730.Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet" 1731.Pp 1732This one disallows any connection from the entire cracker's 1733network to my host: 1734.Pp 1735.Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org" 1736.Pp 1737A first and efficient way to limit access (not using dynamic rules) 1738is the use of the following rules: 1739.Pp 1740.Dl "ipfw add allow tcp from any to any established" 1741.Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup" 1742.Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup" 1743.Dl "..." 1744.Dl "ipfw add deny tcp from any to any" 1745.Pp 1746The first rule will be a quick match for normal TCP packets, 1747but it will not match the initial SYN packet, which will be 1748matched by the 1749.Cm setup 1750rules only for selected source/destination pairs. 1751All other SYN packets will be rejected by the final 1752.Cm deny 1753rule. 1754.Pp 1755If you administer one or more subnets, you can take advantage of the 1756.Nm ipfw2 1757syntax to specify address sets and or-blocks and write extremely 1758compact rulesets which selectively enable services to blocks 1759of clients, as below: 1760.Pp 1761.Dl "goodguys=\*q{ 10.1.2.0/24{20,35,66,18} or 10.2.3.0/28{6,3,11} }\*q" 1762.Dl "badguys=\*q10.1.2.0/24{8,38,60}\*q" 1763.Dl "" 1764.Dl "ipfw add allow ip from ${goodguys} to any" 1765.Dl "ipfw add deny ip from ${badguys} to any" 1766.Dl "... normal policies ..." 1767.Pp 1768The 1769.Nm ipfw1 1770syntax would require a separate rule for each IP in the above 1771example. 1772.Ss DYNAMIC RULES 1773In order to protect a site from flood attacks involving fake 1774TCP packets, it is safer to use dynamic rules: 1775.Pp 1776.Dl "ipfw add check-state" 1777.Dl "ipfw add deny tcp from any to any established" 1778.Dl "ipfw add allow tcp from my-net to any setup keep-state" 1779.Pp 1780This will let the firewall install dynamic rules only for 1781those connection which start with a regular SYN packet coming 1782from the inside of our network. 1783Dynamic rules are checked when encountering the first 1784.Cm check-state 1785or 1786.Cm keep-state 1787rule. 1788A 1789.Cm check-state 1790rule should usually be placed near the beginning of the 1791ruleset to minimize the amount of work scanning the ruleset. 1792Your mileage may vary. 1793.Pp 1794To limit the number of connections a user can open 1795you can use the following type of rules: 1796.Pp 1797.Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10" 1798.Dl "ipfw add allow tcp from any to me setup limit src-addr 4" 1799.Pp 1800The former (assuming it runs on a gateway) will allow each host 1801on a /24 network to open at most 10 TCP connections. 1802The latter can be placed on a server to make sure that a single 1803client does not use more than 4 simultaneous connections. 1804.Pp 1805.Em BEWARE : 1806stateful rules can be subject to denial-of-service attacks 1807by a SYN-flood which opens a huge number of dynamic rules. 1808The effects of such attacks can be partially limited by 1809acting on a set of 1810.Xr sysctl 8 1811variables which control the operation of the firewall. 1812.Pp 1813Here is a good usage of the 1814.Cm list 1815command to see accounting records and timestamp information: 1816.Pp 1817.Dl ipfw -at list 1818.Pp 1819or in short form without timestamps: 1820.Pp 1821.Dl ipfw -a list 1822.Pp 1823which is equivalent to: 1824.Pp 1825.Dl ipfw show 1826.Pp 1827Next rule diverts all incoming packets from 192.168.2.0/24 1828to divert port 5000: 1829.Pp 1830.Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in 1831.Ss TRAFFIC SHAPING 1832The following rules show some of the applications of 1833.Nm 1834and 1835.Xr dummynet 4 1836for simulations and the like. 1837.Pp 1838This rule drops random incoming packets with a probability 1839of 5%: 1840.Pp 1841.Dl "ipfw add prob 0.05 deny ip from any to any in" 1842.Pp 1843A similar effect can be achieved making use of dummynet pipes: 1844.Pp 1845.Dl "ipfw add pipe 10 ip from any to any" 1846.Dl "ipfw pipe 10 config plr 0.05" 1847.Pp 1848We can use pipes to artificially limit bandwidth, e.g. on a 1849machine acting as a router, if we want to limit traffic from 1850local clients on 192.168.2.0/24 we do: 1851.Pp 1852.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 1853.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes" 1854.Pp 1855note that we use the 1856.Cm out 1857modifier so that the rule is not used twice. 1858Remember in fact that 1859.Nm 1860rules are checked both on incoming and outgoing packets. 1861.Pp 1862Should we want to simulate a bidirectional link with bandwidth 1863limitations, the correct way is the following: 1864.Pp 1865.Dl "ipfw add pipe 1 ip from any to any out" 1866.Dl "ipfw add pipe 2 ip from any to any in" 1867.Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes" 1868.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes" 1869.Pp 1870The above can be very useful, e.g. if you want to see how 1871your fancy Web page will look for a residential user who 1872is connected only through a slow link. 1873You should not use only one pipe for both directions, unless 1874you want to simulate a half-duplex medium (e.g. AppleTalk, 1875Ethernet, IRDA). 1876It is not necessary that both pipes have the same configuration, 1877so we can also simulate asymmetric links. 1878.Pp 1879Should we want to verify network performance with the RED queue 1880management algorithm: 1881.Pp 1882.Dl "ipfw add pipe 1 ip from any to any" 1883.Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1" 1884.Pp 1885Another typical application of the traffic shaper is to 1886introduce some delay in the communication. 1887This can significantly affect applications which do a lot of Remote 1888Procedure Calls, and where the round-trip-time of the 1889connection often becomes a limiting factor much more than 1890bandwidth: 1891.Pp 1892.Dl "ipfw add pipe 1 ip from any to any out" 1893.Dl "ipfw add pipe 2 ip from any to any in" 1894.Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s" 1895.Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s" 1896.Pp 1897Per-flow queueing can be useful for a variety of purposes. 1898A very simple one is counting traffic: 1899.Pp 1900.Dl "ipfw add pipe 1 tcp from any to any" 1901.Dl "ipfw add pipe 1 udp from any to any" 1902.Dl "ipfw add pipe 1 ip from any to any" 1903.Dl "ipfw pipe 1 config mask all" 1904.Pp 1905The above set of rules will create queues (and collect 1906statistics) for all traffic. 1907Because the pipes have no limitations, the only effect is 1908collecting statistics. 1909Note that we need 3 rules, not just the last one, because 1910when 1911.Nm 1912tries to match IP packets it will not consider ports, so we 1913would not see connections on separate ports as different 1914ones. 1915.Pp 1916A more sophisticated example is limiting the outbound traffic 1917on a net with per-host limits, rather than per-network limits: 1918.Pp 1919.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 1920.Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in" 1921.Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 1922.Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 1923.Ss SETS OF RULES 1924To add a set of rules atomically, e.g. set 18: 1925.Pp 1926.Dl "ipfw disable set 18" 1927.Dl "ipfw add NN set 18 ... # repeat as needed" 1928.Dl "ipfw enable set 18" 1929.Pp 1930To delete a set of rules atomically the command is simply: 1931.Pp 1932.Dl "ipfw delete set 18" 1933.Pp 1934To test a ruleset and disable it and regain control if something goes wrong: 1935.Pp 1936.Dl "ipfw disable set 18" 1937.Dl "ipfw add NN set 18 ... # repeat as needed" 1938.Dl "ipfw enable set 18 ; echo done; sleep 30 && ipfw disable set 18" 1939.Pp 1940Here if everything goes well, you press control-C before the "sleep" 1941terminates, and your ruleset will be left active. Otherwise, e.g. if 1942you cannot access your box, the ruleset will be disabled after 1943the sleep terminates thus restoring the previous situation. 1944.Sh SEE ALSO 1945.Xr cpp 1 , 1946.Xr m4 1 , 1947.Xr divert 4 , 1948.Xr dummynet 4 , 1949.Xr ip 4 , 1950.Xr ipfirewall 4 , 1951.Xr protocols 5 , 1952.Xr services 5 , 1953.Xr init 8 , 1954.Xr kldload 8 , 1955.Xr reboot 8 , 1956.Xr sysctl 8 , 1957.Xr syslogd 8 1958.Sh HISTORY 1959The 1960.Nm 1961utility first appeared in 1962.Fx 2.0 . 1963.Xr dummynet 4 1964was introduced in 1965.Fx 2.2.8 . 1966Stateful extensions were introduced in 1967.Fx 4.0 . 1968.Nm ipfw2 1969was introduced in Summer 2002. 1970.Sh AUTHORS 1971.An Ugen J. S. Antsilevich , 1972.An Poul-Henning Kamp , 1973.An Alex Nash , 1974.An Archie Cobbs , 1975.An Luigi Rizzo . 1976.Pp 1977.An -nosplit 1978API based upon code written by 1979.An Daniel Boulet 1980for BSDI. 1981.Pp 1982Work on 1983.Xr dummynet 4 1984traffic shaper supported by Akamba Corp. 1985.Sh BUGS 1986The syntax has grown over the years and sometimes it might be confusing. 1987Unfortunately, backward compatibility prevents cleaning up mistakes 1988made in the definition of the syntax. 1989.Pp 1990.Em !!! WARNING !!! 1991.Pp 1992Misconfiguring the firewall can put your computer in an unusable state, 1993possibly shutting down network services and requiring console access to 1994regain control of it. 1995.Pp 1996Incoming packet fragments diverted by 1997.Cm divert 1998or 1999.Cm tee 2000are reassembled before delivery to the socket. 2001The action used on those packet is the one from the 2002rule which matches the first fragment of the packet. 2003.Pp 2004Packets that match a 2005.Cm tee 2006rule should not be immediately accepted, but should continue 2007going through the rule list. 2008This may be fixed in a later version. 2009.Pp 2010Packets diverted to userland, and then reinserted by a userland process 2011(such as 2012.Xr natd 8 ) 2013will lose various packet attributes, including their source interface. 2014If a packet is reinserted in this manner, later rules may be incorrectly 2015applied, making the order of 2016.Cm divert 2017rules in the rule sequence very important. 2018