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.Ns No ( Ar ifX Ns No ), 997by device name 998.Ns No ( Ar if Ns Ar * Ns No ), 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.Pp 1255.It Em queue 1256A queue 1257is an abstraction used to implement the WF2Q+ 1258(Worst-case Fair Weighted Fair Queueing) policy, which is 1259an efficient variant of the WFQ policy. 1260.br 1261The queue associates a 1262.Em weight 1263and a reference pipe to each flow, and then all backlogged (i.e., 1264with packets queued) flows linked to the same pipe share the pipe's 1265bandwidth proportionally to their weights. 1266Note that weights are not priorities; a flow with a lower weight 1267is still guaranteed to get its fraction of the bandwidth even if a 1268flow with a higher weight is permanently backlogged. 1269.El 1270In practice, 1271.Em pipes 1272can be used to set hard limits to the bandwidth that a flow can use, whereas 1273.Em queues 1274can be used to determine how different flow share the available bandwidth. 1275.Pp 1276The 1277.Em pipe 1278and 1279.Em queue 1280configuration commands are the following: 1281.Bd -ragged -offset indent 1282.Cm pipe Ar number Cm config Ar pipe-configuration 1283.Pp 1284.Cm queue Ar number Cm config Ar queue-configuration 1285.Ed 1286.Pp 1287The following parameters can be configured for a pipe: 1288.Pp 1289.Bl -tag -width indent -compact 1290.It Cm bw Ar bandwidth 1291Bandwidth, measured in 1292.Sm off 1293.Op Cm K | M 1294.Brq Cm bit/s | Byte/s . 1295.Sm on 1296.Pp 1297A value of 0 (default) means unlimited bandwidth. 1298The unit must immediately follow the number, as in 1299.Pp 1300.Dl "ipfw pipe 1 config bw 300Kbit/s" 1301.Pp 1302.It Cm delay Ar ms-delay 1303Propagation delay, measured in milliseconds. 1304The value is rounded to the next multiple of the clock tick 1305(typically 10ms, but it is a good practice to run kernels 1306with 1307.Cd "options HZ=1000" 1308to reduce 1309the granularity to 1ms or less). 1310Default value is 0, meaning no delay. 1311.El 1312.Pp 1313The following parameters can be configured for a queue: 1314.Pp 1315.Bl -tag -width indent -compact 1316.It Cm pipe Ar pipe_nr 1317Connects a queue to the specified pipe. 1318Multiple queues (with the same or different weights) can be connected to 1319the same pipe, which specifies the aggregate rate for the set of queues. 1320.Pp 1321.It Cm weight Ar weight 1322Specifies the weight to be used for flows matching this queue. 1323The weight must be in the range 1..100, and defaults to 1. 1324.El 1325.Pp 1326Finally, the following parameters can be configured for both 1327pipes and queues: 1328.Pp 1329.Bl -tag -width XXXX -compact 1330.It Cm buckets Ar hash-table-size 1331Specifies the size of the hash table used for storing the 1332various queues. 1333Default value is 64 controlled by the 1334.Xr sysctl 8 1335variable 1336.Em net.inet.ip.dummynet.hash_size , 1337allowed range is 16 to 65536. 1338.Pp 1339.It Cm mask Ar mask-specifier 1340Packets sent to a given pipe or queue by an 1341.Nm 1342rule can be further classified into multiple flows, each of which is then 1343sent to a different 1344.Em dynamic 1345pipe or queue. 1346A flow identifier is constructed by masking the IP addresses, 1347ports and protocol types as specified with the 1348.Cm mask 1349options in the configuration of the pipe or queue. 1350For each different flow identifier, a new pipe or queue is created 1351with the same parameters as the original object, and matching packets 1352are sent to it. 1353.Pp 1354Thus, when 1355.Em dynamic pipes 1356are used, each flow will get the same bandwidth as defined by the pipe, 1357whereas when 1358.Em dynamic queues 1359are used, each flow will share the parent's pipe bandwidth evenly 1360with other flows generated by the same queue (note that other queues 1361with different weights might be connected to the same pipe). 1362.br 1363Available mask specifiers are a combination of one or more of the following: 1364.Pp 1365.Cm dst-ip Ar mask , 1366.Cm src-ip Ar mask , 1367.Cm dst-port Ar mask , 1368.Cm src-port Ar mask , 1369.Cm proto Ar mask 1370or 1371.Cm all , 1372.Pp 1373where the latter means all bits in all fields are significant. 1374.Pp 1375.It Cm noerror 1376When a packet is dropped by a dummynet queue or pipe, the error 1377is normally reported to the caller routine in the kernel, in the 1378same way as it happens when a device queue fills up. Setting this 1379option reports the packet as successfully delivered, which can be 1380needed for some experimental setups where you want to simulate 1381loss or congestion at a remote router. 1382.Pp 1383.Em NOTE: 1384This option is always on, 1385since 1386.Dx 1.11 . 1387.Pp 1388.It Cm plr Ar packet-loss-rate 1389Packet loss rate. 1390Argument 1391.Ar packet-loss-rate 1392is a floating-point number between 0 and 1, with 0 meaning no 1393loss, 1 meaning 100% loss. 1394The loss rate is internally represented on 31 bits. 1395.Pp 1396.It Cm queue Brq Ar slots | size Ns Cm Kbytes 1397Queue size, in 1398.Ar slots 1399or 1400.Cm KBytes . 1401Default value is 50 slots, which 1402is the typical queue size for Ethernet devices. 1403Note that for slow speed links you should keep the queue 1404size short or your traffic might be affected by a significant 1405queueing delay. 1406E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit 1407or 20s of queue on a 30Kbit/s pipe. 1408Even worse effect can result if you get packets from an 1409interface with a much larger MTU, e.g. the loopback interface 1410with its 16KB packets. 1411.Pp 1412.It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p 1413Make use of the RED (Random Early Detection) queue management algorithm. 1414.Ar w_q 1415and 1416.Ar max_p 1417are floating 1418point numbers between 0 and 1 (0 not included), while 1419.Ar min_th 1420and 1421.Ar max_th 1422are integer numbers specifying thresholds for queue management 1423(thresholds are computed in bytes if the queue has been defined 1424in bytes, in slots otherwise). 1425The 1426.Xr dummynet 4 1427also supports the gentle RED variant (gred). 1428Three 1429.Xr sysctl 8 1430variables can be used to control the RED behaviour: 1431.Bl -tag -width indent 1432.It Em net.inet.ip.dummynet.red_lookup_depth 1433specifies the accuracy in computing the average queue 1434when the link is idle (defaults to 256, must be greater than zero) 1435.It Em net.inet.ip.dummynet.red_avg_pkt_size 1436specifies the expected average packet size (defaults to 512, must be 1437greater than zero) 1438.It Em net.inet.ip.dummynet.red_max_pkt_size 1439specifies the expected maximum packet size, only used when queue 1440thresholds are in bytes (defaults to 1500, must be greater than zero). 1441.El 1442.El 1443.Sh CHECKLIST 1444Here are some important points to consider when designing your 1445rules: 1446.Bl -bullet 1447.It 1448Remember that you filter both packets going 1449.Cm in 1450and 1451.Cm out . 1452Most connections need packets going in both directions. 1453.It 1454Remember to test very carefully. 1455It is a good idea to be near the console when doing this. 1456If you cannot be near the console, 1457use an auto-recovery script such as the one in 1458.Pa /usr/share/examples/ipfw/change_rules.sh . 1459.It 1460Don't forget the loopback interface. 1461.El 1462.Sh FINE POINTS 1463.Bl -bullet 1464.It 1465There are circumstances where fragmented datagrams are unconditionally 1466dropped. 1467TCP packets are dropped if they do not contain at least 20 bytes of 1468TCP header, UDP packets are dropped if they do not contain a full 8 1469byte UDP header, and ICMP packets are dropped if they do not contain 14704 bytes of ICMP header, enough to specify the ICMP type, code, and 1471checksum. 1472These packets are simply logged as 1473.Dq pullup failed 1474since there may not be enough good data in the packet to produce a 1475meaningful log entry. 1476.It 1477Another type of packet is unconditionally dropped, a TCP packet with a 1478fragment offset of one. 1479This is a valid packet, but it only has one use, to try 1480to circumvent firewalls. 1481When logging is enabled, these packets are 1482reported as being dropped by rule -1. 1483.It 1484If you are logged in over a network, loading the 1485.Xr kld 4 1486version of 1487.Nm 1488is probably not as straightforward as you would think. 1489I recommend the following command line: 1490.Bd -literal -offset indent 1491kldload /boot/modules/ipfw.ko && \e 1492ipfw add 32000 allow ip from any to any 1493.Ed 1494.Pp 1495Along the same lines, doing an 1496.Bd -literal -offset indent 1497ipfw flush 1498.Ed 1499.Pp 1500in similar surroundings is also a bad idea. 1501.It 1502The 1503.Nm 1504filter list may not be modified if the system security level 1505is set to 3 or higher 1506(see 1507.Xr init 8 1508for information on system security levels). 1509.El 1510.Sh PACKET DIVERSION 1511A 1512.Xr divert 4 1513socket bound to the specified port will receive all packets 1514diverted to that port. 1515If no socket is bound to the destination port, or if the kernel 1516wasn't compiled with divert socket support, the packets are 1517dropped. 1518.Sh SYSCTL VARIABLES 1519A set of 1520.Xr sysctl 8 1521variables controls the behaviour of the firewall and 1522associated modules 1523.Nm ( dummynet ) . 1524These are shown below together with their default value 1525(but always check with the 1526.Xr sysctl 8 1527command what value is actually in use) and meaning: 1528.Bl -tag -width indent 1529.It Em net.inet.ip.dummynet.expire : No 1 1530Lazily delete dynamic pipes/queue once they have no pending traffic. 1531You can disable this by setting the variable to 0, in which case 1532the pipes/queues will only be deleted when the threshold is reached. 1533.It Em net.inet.ip.dummynet.hash_size : No 64 1534Default size of the hash table used for dynamic pipes/queues. 1535This value is used when no 1536.Cm buckets 1537option is specified when configuring a pipe/queue. 1538.It Em net.inet.ip.dummynet.max_chain_len : No 16 1539Target value for the maximum number of pipes/queues in a hash bucket. 1540The product 1541.Cm max_chain_len*hash_size 1542is used to determine the threshold over which empty pipes/queues 1543will be expired even when 1544.Cm net.inet.ip.dummynet.expire=0 . 1545.It Em net.inet.ip.dummynet.red_lookup_depth : No 256 1546.It Em net.inet.ip.dummynet.red_avg_pkt_size : No 512 1547.It Em net.inet.ip.dummynet.red_max_pkt_size : No 1500 1548Parameters used in the computations of the drop probability 1549for the RED algorithm. 1550.It Em net.inet.ip.fw.autoinc_step : No 100 1551Delta between rule numbers when auto-generating them. 1552The value must be in the range 1..1000. 1553.It Em net.inet.ip.fw.curr_dyn_buckets : Em net.inet.ip.fw.dyn_buckets 1554The current number of buckets in the hash table for dynamic rules 1555(readonly). 1556.It Em net.inet.ip.fw.debug : No 1 1557Controls debugging messages produced by 1558.Nm . 1559.It Em net.inet.ip.fw.dyn_buckets : No 256 1560The number of buckets in the hash table for dynamic rules. 1561Must be a power of 2, up to 65536. 1562It only takes effect when all dynamic rules have expired, so you 1563are advised to use a 1564.Cm flush 1565command to make sure that the hash table is resized. 1566.It Em net.inet.ip.fw.dyn_count : No 3 1567Current number of dynamic rules 1568(read-only). 1569.It Em net.inet.ip.fw.dyn_keepalive : No 1 1570Enables generation of keepalive packets for 1571.Cm keep-state 1572rules on TCP sessions. A keepalive is generated to both 1573sides of the connection every 5 seconds for the last 20 1574seconds of the lifetime of the rule. 1575.It Em net.inet.ip.fw.dyn_max : No 8192 1576Maximum number of dynamic rules. 1577When you hit this limit, no more dynamic rules can be 1578installed until old ones expire. 1579.It Em net.inet.ip.fw.dyn_ack_lifetime : No 300 1580.It Em net.inet.ip.fw.dyn_syn_lifetime : No 20 1581.It Em net.inet.ip.fw.dyn_fin_lifetime : No 1 1582.It Em net.inet.ip.fw.dyn_rst_lifetime : No 1 1583.It Em net.inet.ip.fw.dyn_udp_lifetime : No 5 1584.It Em net.inet.ip.fw.dyn_short_lifetime : No 30 1585These variables control the lifetime, in seconds, of dynamic 1586rules. 1587Upon the initial SYN exchange the lifetime is kept short, 1588then increased after both SYN have been seen, then decreased 1589again during the final FIN exchange or when a RST is received. 1590Both 1591.Em dyn_fin_lifetime 1592and 1593.Em dyn_rst_lifetime 1594must be strictly lower than 5 seconds, the period of 1595repetition of keepalives. The firewall enforces that. 1596.It Em net.inet.ip.fw.enable : No 1 1597Enables the firewall. 1598Setting this variable to 0 lets you run your machine without 1599firewall even if compiled in. 1600.It Em net.inet.ip.fw.one_pass : No 1 1601When set, the packet exiting from the 1602.Xr dummynet 4 1603pipe is not passed though the firewall again. 1604Otherwise, after a pipe action, the packet is 1605reinjected into the firewall at the next rule. 1606.Pp 1607Note: layer 2 packets coming out of a pipe 1608are never reinjected in the firewall irrespective of the 1609value of this variable. 1610.It Em net.inet.ip.fw.verbose : No 1 1611Enables verbose messages. 1612.It Em net.inet.ip.fw.verbose_limit : No 0 1613Limits the number of messages produced by a verbose firewall. 1614.It Em net.link.ether.ipfw : No 0 1615Controls whether layer-2 packets are passed to 1616.Nm . 1617Default is no. 1618.El 1619.Sh IPFW2 ENHANCEMENTS 1620This Section lists the features that have been introduced in 1621.Nm ipfw2 1622which were not present in 1623.Nm ipfw1 . 1624We list them in order of the potential impact that they can 1625have in writing your rulesets. 1626You might want to consider using these features in order to 1627write your rulesets in a more efficient way. 1628.Bl -tag -width indent 1629.It Handling of non-IPv4 packets 1630.Nm ipfw1 1631will silently accept all non-IPv4 packets. 1632.Nm ipfw2 1633will filter all packets (including non-IPv4 ones) according to the ruleset. 1634To achieve the same behaviour as 1635.Nm ipfw1 1636you can use the following as the very first rule in your ruleset: 1637.Pp 1638.Dl "ipfw add 1 allow layer2 not mac-type ip" 1639.Pp 1640The 1641.Cm layer2 1642option might seem redundant, but it is necessary -- packets 1643passed to the firewall from layer3 will not have a MAC header, 1644so the 1645.Cm mac-type ip 1646pattern will always fail on them, and the 1647.Cm not 1648operator will make this rule into a pass-all. 1649.It Address sets 1650.Nm ipfw1 1651does not supports address sets (those in the form 1652.Ar addr/masklen{num,num,...} ) . 1653.Pp 1654.It Port specifications 1655.Nm ipfw1 1656only allows one port range when specifying TCP and UDP ports, and 1657is limited to 10 entries instead of the 15 allowed by 1658.Nm ipfw2 . 1659Also, in 1660.Nm ipfw1 1661you can only specify ports when the rule is requesting 1662.Cm tcp 1663or 1664.Cm udp 1665packets. With 1666.Nm ipfw2 1667you can put port specifications in rules matching all packets, 1668and the match will be attempted only on those packets carrying 1669protocols which include port identifiers. 1670.Pp 1671Finally, 1672.Nm ipfw1 1673allowed the first port entry to be specified as 1674.Ar port:mask 1675where 1676.Ar mask 1677can be an arbitrary 16-bit mask. 1678This syntax is of questionable usefulness and it is not 1679supported anymore in 1680.Nm ipfw2 . 1681.It Or-blocks 1682.Nm ipfw1 1683does not support Or-blocks. 1684.It keepalives 1685.Nm ipfw1 1686does not generate keepalives for stateful sessions. 1687As a consequence, it might cause idle sessions to drop because 1688the lifetime of the dynamic rules expires. 1689.It Sets of rules 1690.Nm ipfw1 1691does not implement sets of rules. 1692.It MAC header filtering and Layer-2 firewalling. 1693.Nm ipfw1 1694does not implement filtering on MAC header fields, nor is it 1695invoked on packets from 1696.Fn ether_demux_oncpu 1697and 1698.Fn ether_output_frame . 1699The sysctl variable 1700.Em net.link.ether.ipfw 1701has no effect there. 1702.It Options 1703The following options are not supported in 1704.Nm ipfw1 1705.Pp 1706.Cm dst-ip, dst-port, layer2, mac, mac-type, src-ip, src-port. 1707.Pp 1708Additionally, the following options are not supported in 1709.Nm ipfw1 1710(RELENG_4) 1711rules: 1712.Pp 1713.Cm ipid, iplen, ipprecedence, iptos, ipttl, 1714.Cm ipversion, tcpack, tcpseq, tcpwin . 1715.It Dummynet options 1716The following option for 1717.Nm dummynet 1718pipes/queues is not supported: 1719.Cm noerror . 1720.El 1721.Sh EXAMPLES 1722There are far too many possible uses of 1723.Nm 1724so this Section will only give a small set of examples. 1725.Ss BASIC PACKET FILTERING 1726This command adds an entry which denies all tcp packets from 1727.Em cracker.evil.org 1728to the telnet port of 1729.Em wolf.tambov.su 1730from being forwarded by the host: 1731.Pp 1732.Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet" 1733.Pp 1734This one disallows any connection from the entire cracker's 1735network to my host: 1736.Pp 1737.Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org" 1738.Pp 1739A first and efficient way to limit access (not using dynamic rules) 1740is the use of the following rules: 1741.Pp 1742.Dl "ipfw add allow tcp from any to any established" 1743.Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup" 1744.Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup" 1745.Dl "..." 1746.Dl "ipfw add deny tcp from any to any" 1747.Pp 1748The first rule will be a quick match for normal TCP packets, 1749but it will not match the initial SYN packet, which will be 1750matched by the 1751.Cm setup 1752rules only for selected source/destination pairs. 1753All other SYN packets will be rejected by the final 1754.Cm deny 1755rule. 1756.Pp 1757If you administer one or more subnets, you can take advantage of the 1758.Nm ipfw2 1759syntax to specify address sets and or-blocks and write extremely 1760compact rulesets which selectively enable services to blocks 1761of clients, as below: 1762.Pp 1763.Dl "goodguys=\*q{ 10.1.2.0/24{20,35,66,18} or 10.2.3.0/28{6,3,11} }\*q" 1764.Dl "badguys=\*q10.1.2.0/24{8,38,60}\*q" 1765.Dl "" 1766.Dl "ipfw add allow ip from ${goodguys} to any" 1767.Dl "ipfw add deny ip from ${badguys} to any" 1768.Dl "... normal policies ..." 1769.Pp 1770The 1771.Nm ipfw1 1772syntax would require a separate rule for each IP in the above 1773example. 1774.Ss DYNAMIC RULES 1775In order to protect a site from flood attacks involving fake 1776TCP packets, it is safer to use dynamic rules: 1777.Pp 1778.Dl "ipfw add check-state" 1779.Dl "ipfw add deny tcp from any to any established" 1780.Dl "ipfw add allow tcp from my-net to any setup keep-state" 1781.Pp 1782This will let the firewall install dynamic rules only for 1783those connection which start with a regular SYN packet coming 1784from the inside of our network. 1785Dynamic rules are checked when encountering the first 1786.Cm check-state 1787or 1788.Cm keep-state 1789rule. 1790A 1791.Cm check-state 1792rule should usually be placed near the beginning of the 1793ruleset to minimize the amount of work scanning the ruleset. 1794Your mileage may vary. 1795.Pp 1796To limit the number of connections a user can open 1797you can use the following type of rules: 1798.Pp 1799.Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10" 1800.Dl "ipfw add allow tcp from any to me setup limit src-addr 4" 1801.Pp 1802The former (assuming it runs on a gateway) will allow each host 1803on a /24 network to open at most 10 TCP connections. 1804The latter can be placed on a server to make sure that a single 1805client does not use more than 4 simultaneous connections. 1806.Pp 1807.Em BEWARE : 1808stateful rules can be subject to denial-of-service attacks 1809by a SYN-flood which opens a huge number of dynamic rules. 1810The effects of such attacks can be partially limited by 1811acting on a set of 1812.Xr sysctl 8 1813variables which control the operation of the firewall. 1814.Pp 1815Here is a good usage of the 1816.Cm list 1817command to see accounting records and timestamp information: 1818.Pp 1819.Dl ipfw -at list 1820.Pp 1821or in short form without timestamps: 1822.Pp 1823.Dl ipfw -a list 1824.Pp 1825which is equivalent to: 1826.Pp 1827.Dl ipfw show 1828.Pp 1829Next rule diverts all incoming packets from 192.168.2.0/24 1830to divert port 5000: 1831.Pp 1832.Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in 1833.Ss TRAFFIC SHAPING 1834The following rules show some of the applications of 1835.Nm 1836and 1837.Xr dummynet 4 1838for simulations and the like. 1839.Pp 1840This rule drops random incoming packets with a probability 1841of 5%: 1842.Pp 1843.Dl "ipfw add prob 0.05 deny ip from any to any in" 1844.Pp 1845A similar effect can be achieved making use of dummynet pipes: 1846.Pp 1847.Dl "ipfw add pipe 10 ip from any to any" 1848.Dl "ipfw pipe 10 config plr 0.05" 1849.Pp 1850We can use pipes to artificially limit bandwidth, e.g. on a 1851machine acting as a router, if we want to limit traffic from 1852local clients on 192.168.2.0/24 we do: 1853.Pp 1854.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 1855.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes" 1856.Pp 1857note that we use the 1858.Cm out 1859modifier so that the rule is not used twice. 1860Remember in fact that 1861.Nm 1862rules are checked both on incoming and outgoing packets. 1863.Pp 1864Should we want to simulate a bidirectional link with bandwidth 1865limitations, the correct way is the following: 1866.Pp 1867.Dl "ipfw add pipe 1 ip from any to any out" 1868.Dl "ipfw add pipe 2 ip from any to any in" 1869.Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes" 1870.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes" 1871.Pp 1872The above can be very useful, e.g. if you want to see how 1873your fancy Web page will look for a residential user who 1874is connected only through a slow link. 1875You should not use only one pipe for both directions, unless 1876you want to simulate a half-duplex medium (e.g. AppleTalk, 1877Ethernet, IRDA). 1878It is not necessary that both pipes have the same configuration, 1879so we can also simulate asymmetric links. 1880.Pp 1881Should we want to verify network performance with the RED queue 1882management algorithm: 1883.Pp 1884.Dl "ipfw add pipe 1 ip from any to any" 1885.Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1" 1886.Pp 1887Another typical application of the traffic shaper is to 1888introduce some delay in the communication. 1889This can significantly affect applications which do a lot of Remote 1890Procedure Calls, and where the round-trip-time of the 1891connection often becomes a limiting factor much more than 1892bandwidth: 1893.Pp 1894.Dl "ipfw add pipe 1 ip from any to any out" 1895.Dl "ipfw add pipe 2 ip from any to any in" 1896.Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s" 1897.Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s" 1898.Pp 1899Per-flow queueing can be useful for a variety of purposes. 1900A very simple one is counting traffic: 1901.Pp 1902.Dl "ipfw add pipe 1 tcp from any to any" 1903.Dl "ipfw add pipe 1 udp from any to any" 1904.Dl "ipfw add pipe 1 ip from any to any" 1905.Dl "ipfw pipe 1 config mask all" 1906.Pp 1907The above set of rules will create queues (and collect 1908statistics) for all traffic. 1909Because the pipes have no limitations, the only effect is 1910collecting statistics. 1911Note that we need 3 rules, not just the last one, because 1912when 1913.Nm 1914tries to match IP packets it will not consider ports, so we 1915would not see connections on separate ports as different 1916ones. 1917.Pp 1918A more sophisticated example is limiting the outbound traffic 1919on a net with per-host limits, rather than per-network limits: 1920.Pp 1921.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 1922.Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in" 1923.Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 1924.Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 1925.Ss SETS OF RULES 1926To add a set of rules atomically, e.g. set 18: 1927.Pp 1928.Dl "ipfw disable set 18" 1929.Dl "ipfw add NN set 18 ... # repeat as needed" 1930.Dl "ipfw enable set 18" 1931.Pp 1932To delete a set of rules atomically the command is simply: 1933.Pp 1934.Dl "ipfw delete set 18" 1935.Pp 1936To test a ruleset and disable it and regain control if something goes wrong: 1937.Pp 1938.Dl "ipfw disable set 18" 1939.Dl "ipfw add NN set 18 ... # repeat as needed" 1940.Dl "ipfw enable set 18 ; echo done; sleep 30 && ipfw disable set 18" 1941.Pp 1942Here if everything goes well, you press control-C before the "sleep" 1943terminates, and your ruleset will be left active. Otherwise, e.g. if 1944you cannot access your box, the ruleset will be disabled after 1945the sleep terminates thus restoring the previous situation. 1946.Sh SEE ALSO 1947.Xr cpp 1 , 1948.Xr m4 1 , 1949.Xr divert 4 , 1950.Xr dummynet 4 , 1951.Xr ip 4 , 1952.Xr ipfirewall 4 , 1953.Xr protocols 5 , 1954.Xr services 5 , 1955.Xr init 8 , 1956.Xr kldload 8 , 1957.Xr reboot 8 , 1958.Xr sysctl 8 , 1959.Xr syslogd 8 1960.Sh HISTORY 1961The 1962.Nm 1963utility first appeared in 1964.Fx 2.0 . 1965.Xr dummynet 4 1966was introduced in 1967.Fx 2.2.8 . 1968Stateful extensions were introduced in 1969.Fx 4.0 . 1970.Nm ipfw2 1971was introduced in Summer 2002. 1972.Sh AUTHORS 1973.An Ugen J. S. Antsilevich , 1974.An Poul-Henning Kamp , 1975.An Alex Nash , 1976.An Archie Cobbs , 1977.An Luigi Rizzo . 1978.Pp 1979.An -nosplit 1980API based upon code written by 1981.An Daniel Boulet 1982for BSDI. 1983.Pp 1984Work on 1985.Xr dummynet 4 1986traffic shaper supported by Akamba Corp. 1987.Sh BUGS 1988The syntax has grown over the years and sometimes it might be confusing. 1989Unfortunately, backward compatibility prevents cleaning up mistakes 1990made in the definition of the syntax. 1991.Pp 1992.Em !!! WARNING !!! 1993.Pp 1994Misconfiguring the firewall can put your computer in an unusable state, 1995possibly shutting down network services and requiring console access to 1996regain control of it. 1997.Pp 1998Incoming packet fragments diverted by 1999.Cm divert 2000or 2001.Cm tee 2002are reassembled before delivery to the socket. 2003The action used on those packet is the one from the 2004rule which matches the first fragment of the packet. 2005.Pp 2006Packets that match a 2007.Cm tee 2008rule should not be immediately accepted, but should continue 2009going through the rule list. 2010This may be fixed in a later version. 2011.Pp 2012Packets diverted to userland, and then reinserted by a userland process 2013(such as 2014.Xr natd 8 ) 2015will lose various packet attributes, including their source interface. 2016If a packet is reinserted in this manner, later rules may be incorrectly 2017applied, making the order of 2018.Cm divert 2019rules in the rule sequence very important. 2020