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