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