1.\" 2.\" $FreeBSD: src/sbin/ipfw/ipfw.8,v 1.63.2.33 2003/02/04 01:36:02 brueffer Exp $ 3.\" 4.Dd October 15, 2017 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 : 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 icmptypes Ar types 925Matches ICMP packets whose ICMP type is in the list 926.Ar types . 927The list may be specified as any combination of ranges or 928individual types separated by commas. 929The supported ICMP types are: 930.Pp 931echo reply 932.Pq Cm 0 , 933destination unreachable 934.Pq Cm 3 , 935source quench 936.Pq Cm 4 , 937redirect 938.Pq Cm 5 , 939echo request 940.Pq Cm 8 , 941router advertisement 942.Pq Cm 9 , 943router solicitation 944.Pq Cm 10 , 945time-to-live exceeded 946.Pq Cm 11 , 947IP header bad 948.Pq Cm 12 , 949timestamp request 950.Pq Cm 13 , 951timestamp reply 952.Pq Cm 14 , 953information request 954.Pq Cm 15 , 955information reply 956.Pq Cm 16 , 957address mask request 958.Pq Cm 17 959and address mask reply 960.Pq Cm 18 . 961.It Cm in | out 962Matches incoming or outgoing packets, respectively. 963.Cm in 964and 965.Cm out 966are mutually exclusive (in fact, 967.Cm out 968is implemented as 969.Cm not in Ns No ). 970.It Cm ipfrag 971Matches IP fragment, 972even if it's the first fragment. 973See also 974.Cm frag 975option and 976.Cm defrag 977action. 978.It Cm ipid Ar id 979Matches IP packets whose 980.Cm ip_id 981field has value 982.Ar id . 983.It Cm iplen Ar len 984Matches IP packets whose total length, including header and data, is 985.Ar len 986bytes. 987.It Cm ipoptions Ar spec 988Matches packets whose IP header contains the comma separated list of 989options specified in 990.Ar spec . 991The supported IP options are: 992.Pp 993.Cm ssrr 994(strict source route), 995.Cm lsrr 996(loose source route), 997.Cm rr 998(record packet route) and 999.Cm ts 1000(timestamp). 1001The absence of a particular option may be denoted 1002with a 1003.Ql \&! . 1004.It Cm ipprecedence Ar precedence 1005Matches IP packets whose precedence field is equal to 1006.Ar precedence . 1007.It Cm iptos Ar spec 1008Matches IP packets whose 1009.Cm tos 1010field contains the comma separated list of 1011service types specified in 1012.Ar spec . 1013The supported IP types of service are: 1014.Pp 1015.Cm lowdelay 1016.Pq Dv IPTOS_LOWDELAY , 1017.Cm throughput 1018.Pq Dv IPTOS_THROUGHPUT , 1019.Cm reliability 1020.Pq Dv IPTOS_RELIABILITY , 1021.Cm mincost 1022.Pq Dv IPTOS_MINCOST , 1023.Cm congestion 1024.Pq Dv IPTOS_CE . 1025The absence of a particular type may be denoted 1026with a 1027.Ql \&! . 1028.It Cm ipttl Ar ttl 1029Matches IP packets whose time to live is 1030.Ar ttl . 1031.It Cm ipversion Ar ver 1032Matches IP packets whose IP version field is 1033.Ar ver . 1034.It Cm keep-state 1035Upon a match, the firewall will create a state, whose 1036default behaviour is to match bidirectional traffic between 1037source and destination IP/port using the same protocol. 1038The rule has a limited lifetime (controlled by a set of 1039.Xr sysctl 8 1040variables), and the lifetime is refreshed every time a matching 1041packet is found. 1042.It Cm layer2 1043Matches only layer2 packets, i.e. those passed to 1044.Nm 1045from 1046.Fn ether_demux_oncpu 1047and 1048.Fn ether_output_frame . 1049.It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N 1050The firewall will only allow 1051.Ar N 1052connections with the same 1053set of parameters as specified in the rule. 1054One or more 1055of source and destination addresses and ports can be 1056specified. 1057.It Cm { MAC | mac } Ar dst-mac src-mac 1058Match packets with a given 1059.Ar dst-mac 1060and 1061.Ar src-mac 1062addresses, specified as the 1063.Cm any 1064keyword (matching any MAC address), or six groups of hex digits 1065separated by colons, 1066and optionally followed by a mask indicating how many bits are 1067significant, as in 1068.Pp 1069.Dl "MAC 10:20:30:40:50:60/33 any" 1070.Pp 1071Note that the order of MAC addresses (destination first, 1072source second) is 1073the same as on the wire, but the opposite of the one used for 1074IP addresses. 1075.It Cm mac-type Ar mac-type 1076Matches packets whose Ethernet Type field 1077corresponds to one of those specified as argument. 1078.Ar mac-type 1079is specified in the same way as 1080.Cm port numbers 1081(i.e. one or more comma-separated single values or ranges). 1082You can use symbolic names for known values such as 1083.Em vlan , ipv4, ipv6 . 1084Values can be entered as decimal or hexadecimal (if prefixed by 0x), 1085and they are always printed as hexadecimal (unless the 1086.Cm -N 1087option is used, in which case symbolic resolution will be attempted). 1088.It Cm proto Ar protocol 1089Matches packets with the corresponding IPv4 protocol. 1090.It Cm rdr | redirect Ar ipaddr Ns Op , Ns Ar port 1091Upon a match, 1092the TCP or UDP packet will be redirected to 1093.Ar port 1094on 1095.Ar ipaddr , 1096after changing the packet's destination IP address to 1097.Ar ipaddr , 1098and destination port to 1099.Ar port . 1100If 1101.Ar port 1102is omitted, 1103packet's destination port will not be changed. 1104This rule only applies to 1105.Cm in 1106TCP or UDP packets. 1107This rule requires 1108.Cm recv 1109and 1110.Cm dst-port , 1111or 1112.Ar ports 1113specified after 1114.Ar dst 1115in rule body. 1116This rule will create a state. 1117See 1118.Cm keep-state . 1119.It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar ipno | Ar any 1120Matches packets received, transmitted or going through, 1121respectively, the interface specified by exact name 1122.Pq Ar ifX , 1123by device name 1124.Pq Ar if Ns Cm * , 1125by IP address, or through some interface. 1126.Pp 1127The 1128.Cm via 1129keyword causes the interface to always be checked. 1130If 1131.Cm recv 1132or 1133.Cm xmit 1134is used instead of 1135.Cm via , 1136then only the receive or transmit interface (respectively) 1137is checked. 1138By specifying both, it is possible to match packets based on 1139both receive and transmit interface, e.g.: 1140.Pp 1141.Dl "ipfw add deny ip from any to any out recv ed0 xmit ed1" 1142.Pp 1143The 1144.Cm recv 1145interface can be tested on either incoming or outgoing packets, 1146while the 1147.Cm xmit 1148interface can only be tested on outgoing packets. 1149So 1150.Cm out 1151is required (and 1152.Cm in 1153is invalid) whenever 1154.Cm xmit 1155is used. 1156.Pp 1157A packet may not have a receive or transmit interface: packets 1158originating from the local host have no receive interface, 1159while packets destined for the local host have no transmit 1160interface. 1161.It Cm setup 1162Matches TCP packets that have the SYN bit set but no ACK bit. 1163This is the short form of 1164.Dq Li tcpflags\ syn,!ack . 1165.It Cm src-ip Ar ip-address 1166Matches IP packets whose source IP is one of the address(es) 1167specified as argument. 1168.It Cm src-port Ar ports 1169Matches IP packets whose source port is one of the port(s) 1170specified as argument. 1171.It Cm tcpack Ar ack 1172TCP packets only. 1173Match if the TCP header acknowledgment number field is set to 1174.Ar ack . 1175.It Cm tcpflags Ar spec 1176TCP packets only. 1177Match if the TCP header contains the comma separated list of 1178flags specified in 1179.Ar spec . 1180The supported TCP flags are: 1181.Pp 1182.Cm fin , 1183.Cm syn , 1184.Cm rst , 1185.Cm psh , 1186.Cm ack 1187and 1188.Cm urg . 1189The absence of a particular flag may be denoted 1190with a 1191.Ql \&! . 1192A rule which contains a 1193.Cm tcpflags 1194specification can never match a fragmented packet which has 1195a non-zero offset. 1196See the 1197.Cm frag 1198and 1199.Cm ipfrag 1200options for details on matching fragmented packets. 1201And see the 1202.Cm defrag 1203action for reassembling IP fragments. 1204.It Cm tcpseq Ar seq 1205TCP packets only. 1206Match if the TCP header sequence number field is set to 1207.Ar seq . 1208.It Cm tcpwin Ar win 1209TCP packets only. 1210Match if the TCP header window field is set to 1211.Ar win . 1212.It Cm tcpoptions Ar spec 1213TCP packets only. 1214Match if the TCP header contains the comma separated list of 1215options specified in 1216.Ar spec . 1217The supported TCP options are: 1218.Pp 1219.Cm mss 1220(maximum segment size), 1221.Cm window 1222(tcp window advertisement), 1223.Cm sack 1224(selective ack), 1225.Cm ts 1226(rfc1323 timestamp) and 1227.Cm cc 1228(rfc1644 t/tcp connection count). 1229The absence of a particular option may be denoted 1230with a 1231.Ql \&! . 1232.It Cm uid Ar user 1233Match all TCP or UDP packets sent by or received for a 1234.Ar user . 1235A 1236.Ar user 1237may be matched by name or identification number. 1238.El 1239.Sh SETS OF RULES 1240Each rule belongs to one of 32 different 1241.Em sets 1242, numbered 0 to 31. 1243Set 31 is reserved for the default rule. 1244.Pp 1245By default, rules are put in set 0, unless you use the 1246.Cm set N 1247attribute when entering a new rule. 1248Sets can be individually and atomically enabled or disabled, 1249so this mechanism permits an easy way to store multiple configurations 1250of the firewall and quickly (and atomically) switch between them. 1251The command to enable/disable sets is 1252.Bd -ragged -offset indent 1253.Nm 1254.Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ... 1255.Ed 1256.Pp 1257where multiple 1258.Cm enable 1259or 1260.Cm disable 1261sections can be specified. 1262Command execution is atomic on all the sets specified in the command. 1263By default, all sets are enabled. 1264.Pp 1265When you disable a set, its rules behave as if they do not exist 1266in the firewall configuration, with only one exception: 1267.Bd -ragged -offset indent 1268states and tracks created from a rule before it had been disabled 1269will still be active until they expire. In order to delete 1270states and tracks you have to explicitly delete the parent rule 1271which generated them. 1272.Ed 1273.Pp 1274The set number of rules can be changed with the command 1275.Bd -ragged -offset indent 1276.Nm 1277.Cm set move 1278.Brq Cm rule Ar rule-number | old-set 1279.Cm to Ar new-set 1280.Ed 1281.Pp 1282Also, you can atomically swap two rulesets with the command 1283.Bd -ragged -offset indent 1284.Nm 1285.Cm set swap Ar first-set second-set 1286.Ed 1287.Pp 1288See the 1289.Sx EXAMPLES 1290Section on some possible uses of sets of rules. 1291.Sh STATEFUL FIREWALL 1292Stateful operation is a way for the firewall to dynamically 1293create states and tracks for specific flows when packets that 1294match a given pattern are detected. Support for stateful 1295operation comes through the 1296.Cm check-state , 1297.Cm keep-state , 1298.Cm redirect 1299and 1300.Cm limit 1301options of 1302.Nm 1303rules. 1304.Pp 1305States are created when a packet matches a 1306.Cm keep-state , 1307.Cm redirect 1308or 1309.Cm limit 1310rule, causing the creation of a 1311.Em state 1312which will match all and only packets with 1313a given 1314.Em protocol 1315between a 1316.Em src-ip/src-port dst-ip/dst-port 1317pair of addresses ( 1318.Em src 1319and 1320.Em dst 1321are used here only to denote the initial match addresses, but they 1322are completely equivalent afterwards). 1323Additionally, 1324tracks are created when a packet matches a 1325.Cm limit 1326rule. 1327States will be checked at the first 1328.Cm check-state , 1329.Cm keep-state , 1330.Cm redirect , 1331or 1332.Cm limit 1333occurrence, and the action performed upon a match will be the same 1334as in the parent rule. 1335.Pp 1336Note that no additional attributes other than protocol and IP addresses 1337and ports are checked on states. 1338.Pp 1339The typical use of states is to keep a closed firewall configuration, 1340but let the first TCP SYN packet from the inside network install a 1341state for the flow so that packets belonging to that session 1342will be allowed through the firewall: 1343.Pp 1344.Dl "ipfw add check-state" 1345.Dl "ipfw add allow tcp from my-subnet to any setup keep-state" 1346.Dl "ipfw add deny tcp from any to any" 1347.Pp 1348A similar approach can be used for UDP, where an UDP packet coming 1349from the inside will install a state to let the response through 1350the firewall: 1351.Pp 1352.Dl "ipfw add check-state" 1353.Dl "ipfw add allow udp from my-subnet to any keep-state" 1354.Dl "ipfw add deny udp from any to any" 1355.Pp 1356States and tracks expire after some time, which depends on the status 1357of the flow and the setting of some 1358.Cm sysctl 1359variables. 1360See Section 1361.Sx SYSCTL VARIABLES 1362for more details. 1363For TCP sessions, states can be instructed to periodically 1364send keepalive packets to refresh the state of the rule when it is 1365about to expire. 1366.Pp 1367See Section 1368.Sx EXAMPLES 1369for more examples on how to use states. 1370.Sh TRAFFIC SHAPER (DUMMYNET) CONFIGURATION 1371.Nm 1372is also the user interface for the 1373.Xr dummynet 4 1374traffic shaper. 1375.Pp 1376.Nm dummynet 1377operates by first using the firewall to classify packets and divide them into 1378.Em flows , 1379using any match pattern that can be used in 1380.Nm 1381rules. 1382Depending on local policies, a flow can contain packets for a single 1383TCP connection, or from/to a given host, or entire subnet, or a 1384protocol type, etc. 1385.Pp 1386Packets belonging to the same flow are then passed to either of two 1387different objects, which implement the traffic regulation: 1388.Bl -hang -offset XXXX 1389.It Em pipe 1390A pipe emulates a link with given bandwidth, propagation delay, 1391queue size and packet loss rate. 1392Packets are queued in front of the pipe as they come out from the classifier, 1393and then transferred to the pipe according to the pipe's parameters. 1394.It Em queue 1395A queue 1396is an abstraction used to implement the WF2Q+ 1397(Worst-case Fair Weighted Fair Queueing) policy, which is 1398an efficient variant of the WFQ policy. 1399.br 1400The queue associates a 1401.Em weight 1402and a reference pipe to each flow, and then all backlogged (i.e., 1403with packets queued) flows linked to the same pipe share the pipe's 1404bandwidth proportionally to their weights. 1405Note that weights are not priorities; a flow with a lower weight 1406is still guaranteed to get its fraction of the bandwidth even if a 1407flow with a higher weight is permanently backlogged. 1408.El 1409In practice, 1410.Em pipes 1411can be used to set hard limits to the bandwidth that a flow can use, whereas 1412.Em queues 1413can be used to determine how different flow share the available bandwidth. 1414.Pp 1415The 1416.Em pipe 1417and 1418.Em queue 1419configuration commands are the following: 1420.Bd -ragged -offset indent 1421.Cm pipe Ar number Cm config Ar pipe-configuration 1422.Pp 1423.Cm queue Ar number Cm config Ar queue-configuration 1424.Ed 1425.Pp 1426The following parameters can be configured for a pipe: 1427.Pp 1428.Bl -tag -width indent -compact 1429.It Cm bw Ar bandwidth 1430Bandwidth, measured in 1431.Sm off 1432.Op Cm K | M 1433.Brq Cm bit/s | Byte/s . 1434.Sm on 1435.Pp 1436A value of 0 (default) means unlimited bandwidth. 1437The unit must immediately follow the number, as in 1438.Pp 1439.Dl "ipfw pipe 1 config bw 300Kbit/s" 1440.Pp 1441.It Cm delay Ar ms-delay 1442Propagation delay, measured in milliseconds. 1443The value is rounded to the next multiple of the clock tick 1444(typically 10ms, but it is a good practice to run kernels 1445with 1446.Cd "options HZ=1000" 1447to reduce 1448the granularity to 1ms or less). 1449Default value is 0, meaning no delay. 1450.El 1451.Pp 1452The following parameters can be configured for a queue: 1453.Pp 1454.Bl -tag -width indent -compact 1455.It Cm pipe Ar pipe_nr 1456Connects a queue to the specified pipe. 1457Multiple queues (with the same or different weights) can be connected to 1458the same pipe, which specifies the aggregate rate for the set of queues. 1459.Pp 1460.It Cm weight Ar weight 1461Specifies the weight to be used for flows matching this queue. 1462The weight must be in the range 1..100, and defaults to 1. 1463.El 1464.Pp 1465Finally, the following parameters can be configured for both 1466pipes and queues: 1467.Pp 1468.Bl -tag -width XXXX -compact 1469.It Cm buckets Ar hash-table-size 1470Specifies the size of the hash table used for storing the 1471various queues. 1472Default value is 64 controlled by the 1473.Xr sysctl 8 1474variable 1475.Em net.inet.ip.dummynet.hash_size , 1476allowed range is 16 to 65536. 1477.Pp 1478.It Cm mask Ar mask-specifier 1479Packets sent to a given pipe or queue by an 1480.Nm 1481rule can be further classified into multiple flows, each of which is then 1482sent to a different 1483.Em dynamic 1484pipe or queue. 1485A flow identifier is constructed by masking the IP addresses, 1486ports and protocol types as specified with the 1487.Cm mask 1488options in the configuration of the pipe or queue. 1489For each different flow identifier, a new pipe or queue is created 1490with the same parameters as the original object, and matching packets 1491are sent to it. 1492.Pp 1493Thus, when 1494.Em dynamic pipes 1495are used, each flow will get the same bandwidth as defined by the pipe, 1496whereas when 1497.Em dynamic queues 1498are used, each flow will share the parent's pipe bandwidth evenly 1499with other flows generated by the same queue (note that other queues 1500with different weights might be connected to the same pipe). 1501.br 1502Available mask specifiers are a combination of one or more of the following: 1503.Pp 1504.Cm dst-ip Ar mask , 1505.Cm src-ip Ar mask , 1506.Cm dst-port Ar mask , 1507.Cm src-port Ar mask , 1508.Cm proto Ar mask 1509or 1510.Cm all , 1511.Pp 1512where the latter means all bits in all fields are significant. 1513.Pp 1514.It Cm noerror 1515When a packet is dropped by a dummynet queue or pipe, the error 1516is normally reported to the caller routine in the kernel, in the 1517same way as it happens when a device queue fills up. Setting this 1518option reports the packet as successfully delivered, which can be 1519needed for some experimental setups where you want to simulate 1520loss or congestion at a remote router. 1521.Pp 1522.Em NOTE: 1523This option is always on, 1524since 1525.Dx 1.11 . 1526.Pp 1527.It Cm plr Ar packet-loss-rate 1528Packet loss rate. 1529Argument 1530.Ar packet-loss-rate 1531is a floating-point number between 0 and 1, with 0 meaning no 1532loss, 1 meaning 100% loss. 1533The loss rate is internally represented on 31 bits. 1534.Pp 1535.It Cm queue Brq Ar slots | size Ns Cm Kbytes 1536Queue size, in 1537.Ar slots 1538or 1539.Cm KBytes . 1540Default value is 50 slots, which 1541is the typical queue size for Ethernet devices. 1542Note that for slow speed links you should keep the queue 1543size short or your traffic might be affected by a significant 1544queueing delay. 1545E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit 1546or 20s of queue on a 30Kbit/s pipe. 1547Even worse effect can result if you get packets from an 1548interface with a much larger MTU, e.g. the loopback interface 1549with its 16KB packets. 1550.Pp 1551.It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p 1552Make use of the RED (Random Early Detection) queue management algorithm. 1553.Ar w_q 1554and 1555.Ar max_p 1556are floating 1557point numbers between 0 and 1 (0 not included), while 1558.Ar min_th 1559and 1560.Ar max_th 1561are integer numbers specifying thresholds for queue management 1562(thresholds are computed in bytes if the queue has been defined 1563in bytes, in slots otherwise). 1564The 1565.Xr dummynet 4 1566also supports the gentle RED variant (gred). 1567Three 1568.Xr sysctl 8 1569variables can be used to control the RED behaviour: 1570.Bl -tag -width indent 1571.It Em net.inet.ip.dummynet.red_lookup_depth 1572specifies the accuracy in computing the average queue 1573when the link is idle (defaults to 256, must be greater than zero) 1574.It Em net.inet.ip.dummynet.red_avg_pkt_size 1575specifies the expected average packet size (defaults to 512, must be 1576greater than zero) 1577.It Em net.inet.ip.dummynet.red_max_pkt_size 1578specifies the expected maximum packet size, only used when queue 1579thresholds are in bytes (defaults to 1500, must be greater than zero). 1580.El 1581.El 1582.Sh TABLE 1583Table provides a convenient way to support a large amount of 1584discrete host or network addresses for the 1585.Cm from , 1586.Cm to , 1587.Cm src-ip , 1588and 1589.Cm dst-ip . 1590Non-existing tables never match. 1591For network addresses, 1592only CIDR form is supported. 1593.Pp 1594Tables are identified by 1595.Ar number , 1596which ranges from 0 to 1597.Cm net.inet.ip.fw.table_max 1598- 1. 1599Default number of available tables is 64, 1600i.e. valid table ids are from 0 to 63. 1601Number of available tables can be changed by setting tunable 1602.Cm net.inet.ip.fw.table_max . 1603Max configurable number of available tables is 65535. 1604.Pp 1605Tables must be created explicitly 1606before host or network addresses could be added to them: 1607.Bd -ragged -offset indent 1608.Cm table Ar number Cm create 1609.Ed 1610.Pp 1611Host or network addresses can be added to an existing 1612table by using: 1613.Bd -ragged -offset indent 1614.Cm table Ar number Cm add Ar address 1615.Op Ar address ... 1616.Ed 1617.Pp 1618Host or network addresses can be removed from an existing 1619table by using: 1620.Bd -ragged -offset indent 1621.Cm table Ar number Cm delete Ar address 1622.Op Ar address ... 1623.Ed 1624.Pp 1625Addresses in a table can be flushed by: 1626.Bd -ragged -offset indent 1627.Cm table Ar number Cm flush 1628.Ed 1629.Pp 1630Or you can optionally flush all existing tables: 1631.Bd -ragged -offset indent 1632.Cm table flush 1633.Ed 1634.Pp 1635Each address in a table has two counters. 1636One records the number of usage, 1637the other saves the time of the last match. 1638These counters can be resetted for a specific table: 1639.Bd -ragged -offset indent 1640.Cm table Ar number Cm zero 1641.Ed 1642.Pp 1643Or you can reset counters of addresses in all existing tables by: 1644.Bd -ragged -offset indent 1645.Cm table zero 1646.Ed 1647.Pp 1648Host and network addresses in the tables are not expired by the 1649.Nm , 1650manual intervention is required to expire addresses unused in a table 1651within the last 1652.Ar seconds : 1653.Bd -ragged -offset indent 1654.Cm table Ar number Cm expire Ar seconds 1655.Ed 1656.Pp 1657Optionally, 1658you can expire all addresses that were unused within the last 1659.Ar seconds 1660by: 1661.Bd -ragged -offset indent 1662.Cm table expire Ar seconds 1663.Ed 1664.Pp 1665An existing table can be destroyed by: 1666.Bd -ragged -offset indent 1667.Cm table Ar number Cm destroy 1668.Ed 1669.Pp 1670All existing tables can be listed by: 1671.Bd -ragged -offset indent 1672.Cm table list 1673.Ed 1674.Pp 1675All addresses in an existing table can be dumped by: 1676.Bd -ragged -offset indent 1677.Cm table Ar number 1678.Brq Cm print | show 1679.Ed 1680.Sh CHECKLIST 1681Here are some important points to consider when designing your 1682rules: 1683.Bl -bullet 1684.It 1685Remember that you filter both packets going 1686.Cm in 1687and 1688.Cm out . 1689Most connections need packets going in both directions. 1690.It 1691Remember to test very carefully. 1692It is a good idea to be near the console when doing this. 1693If you cannot be near the console, 1694use an auto-recovery script such as the one in 1695.Pa /usr/share/examples/ipfw/change_rules.sh . 1696.It 1697Don't forget the loopback interface. 1698.El 1699.Sh FINE POINTS 1700.Bl -bullet 1701.It 1702There are circumstances where fragmented datagrams are unconditionally 1703dropped. 1704TCP packets are dropped if they do not contain at least 20 bytes of 1705TCP header, UDP packets are dropped if they do not contain a full 8 1706byte UDP header, and ICMP packets are dropped if they do not contain 17074 bytes of ICMP header, enough to specify the ICMP type, code, and 1708checksum. 1709These packets are simply logged as 1710.Dq pullup failed 1711since there may not be enough good data in the packet to produce a 1712meaningful log entry. 1713.It 1714Another type of packet is unconditionally dropped, a TCP packet with a 1715fragment offset of one. 1716This is a valid packet, but it only has one use, to try 1717to circumvent firewalls. 1718When logging is enabled, these packets are 1719reported as being dropped by rule -1. 1720.It 1721If you are logged in over a network, loading the 1722.Xr kld 4 1723version of 1724.Nm 1725is probably not as straightforward as you would think. 1726I recommend the following command line: 1727.Bd -literal -offset indent 1728kldload /boot/modules/ipfw.ko && \e 1729ipfw add 32000 allow ip from any to any 1730.Ed 1731.Pp 1732Along the same lines, doing an 1733.Bd -literal -offset indent 1734ipfw flush 1735.Ed 1736.Pp 1737in similar surroundings is also a bad idea. 1738.It 1739The 1740.Nm 1741filter list may not be modified if the system security level 1742is set to 3 or higher 1743(see 1744.Xr init 8 1745for information on system security levels). 1746.El 1747.Sh PACKET DIVERSION 1748A 1749.Xr divert 4 1750socket bound to the specified port will receive all packets 1751diverted to that port. 1752If no socket is bound to the destination port, or if the kernel 1753wasn't compiled with divert socket support, the packets are 1754dropped. 1755.Sh SYSCTL VARIABLES 1756A set of 1757.Xr sysctl 8 1758variables controls the behaviour of the firewall and 1759associated modules 1760.Nm ( dummynet ) . 1761These are shown below together with their default value 1762(but always check with the 1763.Xr sysctl 8 1764command what value is actually in use) and meaning: 1765.Bl -tag -width indent 1766.It Em net.filters_default_to_accept : No 0 1767If set prior to loading the 1768.Nm 1769kernel module, the filter will default to allowing all packets through. 1770If not set the filter will likely default to not allowing any packets through. 1771.It Em net.inet.ip.dummynet.expire : No 1 1772Lazily delete dynamic pipes/queue once they have no pending traffic. 1773You can disable this by setting the variable to 0, in which case 1774the pipes/queues will only be deleted when the threshold is reached. 1775.It Em net.inet.ip.dummynet.hash_size : No 64 1776Default size of the hash table used for dynamic pipes/queues. 1777This value is used when no 1778.Cm buckets 1779option is specified when configuring a pipe/queue. 1780.It Em net.inet.ip.dummynet.max_chain_len : No 16 1781Target value for the maximum number of pipes/queues in a hash bucket. 1782The product 1783.Cm max_chain_len*hash_size 1784is used to determine the threshold over which empty pipes/queues 1785will be expired even when 1786.Cm net.inet.ip.dummynet.expire=0 . 1787.It Em net.inet.ip.dummynet.red_lookup_depth : No 256 1788.It Em net.inet.ip.dummynet.red_avg_pkt_size : No 512 1789.It Em net.inet.ip.dummynet.red_max_pkt_size : No 1500 1790Parameters used in the computations of the drop probability 1791for the RED algorithm. 1792.It Em net.inet.ip.fw.autoinc_step : No 100 1793Delta between rule numbers when auto-generating them. 1794The value must be in the range 1..1000. 1795.It Em net.inet.ip.fw.debug : No 1 1796Controls debugging messages produced by 1797.Nm . 1798.It Em net.inet.ip.fw.table_max : No 64 1799Number of available tables. 1800This value can only be changed by setting tunable 1801.Cm net.inet.ip.fw.table_max . 1802.It Em net.inet.ip.fw.state_cnt : No 3 1803Current number of states 1804(read-only). 1805.It Em net.inet.ip.fw.state_max : No 4096 1806Maximum number of states. 1807When you hit this limit, 1808no more states can be installed until old ones expire. 1809.It Em net.inet.ip.fw.track_cnt : No 3 1810Current number of tracks 1811(read-only), 1812which is created by 1813.Cm limit 1814option. 1815.It Em net.inet.ip.fw.track_max : No 4096 1816Maximum number of tracks. 1817When you hit this limit, 1818no more tracks can be installed until old ones expire. 1819.It Em net.inet.ip.fw.dyn_keepalive : No 1 1820Enables generation of keepalive packets for 1821.Cm keep-state , 1822.Cm redirect , 1823or 1824.Cm limit 1825rules on TCP sessions. A keepalive is generated to both 1826sides of the connection every 5 seconds for the last 20 1827seconds of the lifetime of the rule. 1828.It Em net.inet.ip.fw.dyn_ack_lifetime : No 300 1829.It Em net.inet.ip.fw.dyn_syn_lifetime : No 20 1830.It Em net.inet.ip.fw.dyn_finwait_lifetime : No 20 1831.It Em net.inet.ip.fw.dyn_fin_lifetime : No 2 1832.It Em net.inet.ip.fw.dyn_rst_lifetime : No 2 1833.It Em net.inet.ip.fw.dyn_udp_lifetime : No 10 1834.It Em net.inet.ip.fw.dyn_short_lifetime : No 5 1835These variables control the lifetime, in seconds, of states and tracks. 1836Upon the initial SYN exchange the lifetime is kept short, 1837then increased after both SYN have been seen, then decreased 1838again during the final FIN exchange or when a RST is received. 1839.It Em net.inet.ip.fw.enable : No 1 1840Enables the firewall. 1841Setting this variable to 0 lets you run your machine without 1842firewall even if compiled in. 1843.It Em net.inet.ip.fw.one_pass : No 1 1844When set, the packet exiting from the 1845.Xr dummynet 4 1846pipe is not passed though the firewall again. 1847Otherwise, after a pipe action, the packet is 1848reinjected into the firewall at the next rule. 1849.Pp 1850Note: layer 2 packets coming out of a pipe 1851are never reinjected in the firewall irrespective of the 1852value of this variable. 1853.It Em net.inet.ip.fw.verbose : No 1 1854Enables verbose messages. 1855.It Em net.inet.ip.fw.verbose_limit : No 0 1856Limits the number of messages produced by a verbose firewall. 1857.It Em net.link.ether.ipfw : No 0 1858Controls whether layer-2 packets are passed to 1859.Nm . 1860Default is no. 1861.El 1862.Sh IPFW2 ENHANCEMENTS 1863This Section lists the features that have been introduced in 1864.Nm ipfw2 1865which were not present in 1866.Nm ipfw1 . 1867We list them in order of the potential impact that they can 1868have in writing your rulesets. 1869You might want to consider using these features in order to 1870write your rulesets in a more efficient way. 1871.Bl -tag -width indent 1872.It Handling of non-IPv4 packets 1873.Nm ipfw1 1874will silently accept all non-IPv4 packets. 1875.Nm ipfw2 1876will filter all packets (including non-IPv4 ones) according to the ruleset. 1877To achieve the same behaviour as 1878.Nm ipfw1 1879you can use the following as the very first rule in your ruleset: 1880.Pp 1881.Dl "ipfw add 1 allow layer2 not mac-type ip" 1882.Pp 1883The 1884.Cm layer2 1885option might seem redundant, but it is necessary -- packets 1886passed to the firewall from layer3 will not have a MAC header, 1887so the 1888.Cm mac-type ip 1889pattern will always fail on them, and the 1890.Cm not 1891operator will make this rule into a pass-all. 1892.It Address sets 1893.Nm ipfw1 1894does not support address sets (those in the form 1895.Ar addr/masklen{num,num,...} ) . 1896.It Table 1897.Nm ipfw1 1898does not support 1899.Cm table . 1900.It Port specifications 1901.Nm ipfw1 1902only allows one port range when specifying TCP and UDP ports, and 1903is limited to 10 entries instead of the 15 allowed by 1904.Nm ipfw2 . 1905Also, in 1906.Nm ipfw1 1907you can only specify ports when the rule is requesting 1908.Cm tcp 1909or 1910.Cm udp 1911packets. With 1912.Nm ipfw2 1913you can put port specifications in rules matching all packets, 1914and the match will be attempted only on those packets carrying 1915protocols which include port identifiers. 1916.Pp 1917Finally, 1918.Nm ipfw1 1919allowed the first port entry to be specified as 1920.Ar port:mask 1921where 1922.Ar mask 1923can be an arbitrary 16-bit mask. 1924This syntax is of questionable usefulness and it is not 1925supported anymore in 1926.Nm ipfw2 . 1927.It Or-blocks 1928.Nm ipfw1 1929does not support Or-blocks. 1930.It keepalives 1931.Nm ipfw1 1932does not generate keepalives for stateful sessions. 1933As a consequence, it might cause idle sessions to drop because 1934the lifetime of the states expires. 1935.It Sets of rules 1936.Nm ipfw1 1937does not implement sets of rules. 1938.It MAC header filtering and Layer-2 firewalling. 1939.Nm ipfw1 1940does not implement filtering on MAC header fields, nor is it 1941invoked on packets from 1942.Fn ether_demux_oncpu 1943and 1944.Fn ether_output_frame . 1945The sysctl variable 1946.Em net.link.ether.ipfw 1947has no effect there. 1948.It Options 1949The following options are not supported in 1950.Nm ipfw1 1951.Pp 1952.Cm dst-ip, dst-port, layer2, mac, mac-type, src-ip, src-port. 1953.Pp 1954Additionally, the following options are not supported in 1955.Nm ipfw1 1956(RELENG_4) 1957rules: 1958.Pp 1959.Cm ipid, iplen, ipprecedence, iptos, ipttl, 1960.Cm ipversion, tcpack, tcpseq, tcpwin . 1961.It Dummynet options 1962The following option for 1963.Nm dummynet 1964pipes/queues is not supported: 1965.Cm noerror . 1966.El 1967.Sh EXAMPLES 1968There are far too many possible uses of 1969.Nm 1970so this Section will only give a small set of examples. 1971.Ss BASIC PACKET FILTERING 1972This command adds an entry which denies all tcp packets from 1973.Em cracker.evil.org 1974to the telnet port of 1975.Em wolf.tambov.su 1976from being forwarded by the host: 1977.Pp 1978.Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet" 1979.Pp 1980This one disallows any connection from the entire cracker's 1981network to my host: 1982.Pp 1983.Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org" 1984.Pp 1985A first and efficient way to limit access (not using states) 1986is the use of the following rules: 1987.Pp 1988.Dl "ipfw add allow tcp from any to any established" 1989.Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup" 1990.Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup" 1991.Dl "..." 1992.Dl "ipfw add deny tcp from any to any" 1993.Pp 1994The first rule will be a quick match for normal TCP packets, 1995but it will not match the initial SYN packet, which will be 1996matched by the 1997.Cm setup 1998rules only for selected source/destination pairs. 1999All other SYN packets will be rejected by the final 2000.Cm deny 2001rule. 2002.Pp 2003If you administer one or more subnets, you can take advantage of the 2004.Nm ipfw2 2005syntax to specify address sets and or-blocks and write extremely 2006compact rulesets which selectively enable services to blocks 2007of clients, as below: 2008.Pp 2009.Dl "goodguys=\*q{ 10.1.2.0/24{20,35,66,18} or 10.2.3.0/28{6,3,11} }\*q" 2010.Dl "badguys=\*q10.1.2.0/24{8,38,60}\*q" 2011.Dl "" 2012.Dl "ipfw add allow ip from ${goodguys} to any" 2013.Dl "ipfw add deny ip from ${badguys} to any" 2014.Dl "... normal policies ..." 2015.Pp 2016The 2017.Nm ipfw1 2018syntax would require a separate rule for each IP in the above 2019example. 2020.Pp 2021If you have large number of discrete addresses to block, 2022and the number of addresses to block keep increasing, 2023.Cm table 2024can be used as below: 2025.Pp 2026.Dl "... Initialize the blocked address list using table 0 ..." 2027.Dl "ipfw table 0 create" 2028.Dl "ipfw table 0 add 10.0.0.1 10.1.0.1 172.0.0.1" 2029.Dl "... Block the addresses in table 0 ..." 2030.Dl "ipfw add deny ip from <0> to any" 2031.Dl "... Add more addresses to table 0 any time later..." 2032.Dl "ipfw table 0 add 172.1.0.1" 2033.Dl "... Expire the addresses unused within the last 24 hours ..." 2034.Dl "ipfw table 0 expire 86400" 2035.Ss STATES 2036In order to protect a site from flood attacks involving fake 2037TCP packets, it is safer to use states: 2038.Pp 2039.Dl "ipfw add check-state" 2040.Dl "ipfw add deny tcp from any to any established" 2041.Dl "ipfw add allow tcp from my-net to any setup keep-state" 2042.Pp 2043This will let the firewall install states only for 2044those connection which start with a regular SYN packet coming 2045from the inside of our network. 2046States are checked when encountering the first 2047.Cm check-state 2048or 2049.Cm keep-state 2050rule. 2051A 2052.Cm check-state 2053rule should usually be placed near the beginning of the 2054ruleset to minimize the amount of work scanning the ruleset. 2055Your mileage may vary. 2056.Pp 2057To limit the number of connections a user can open 2058you can use the following type of rules: 2059.Pp 2060.Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10" 2061.Dl "ipfw add allow tcp from any to me setup limit src-addr 4" 2062.Pp 2063The former (assuming it runs on a gateway) will allow each host 2064on a /24 network to open at most 10 TCP connections. 2065The latter can be placed on a server to make sure that a single 2066client does not use more than 4 simultaneous connections. 2067.Pp 2068.Em BEWARE : 2069stateful rules can be subject to denial-of-service attacks 2070by a SYN-flood which opens a huge number of states. 2071The effects of such attacks can be partially limited by 2072acting on a set of 2073.Xr sysctl 8 2074variables which control the operation of the firewall. 2075.Pp 2076Here is a good usage of the 2077.Cm list 2078command to see accounting records and timestamp information: 2079.Pp 2080.Dl ipfw -at list 2081.Pp 2082or in short form without timestamps: 2083.Pp 2084.Dl ipfw -a list 2085.Pp 2086which is equivalent to: 2087.Pp 2088.Dl ipfw show 2089.Pp 2090Next rule diverts all incoming packets from 192.168.2.0/24 2091to divert port 5000: 2092.Pp 2093.Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in 2094.Ss TRAFFIC SHAPING 2095The following rules show some of the applications of 2096.Nm 2097and 2098.Xr dummynet 4 2099for simulations and the like. 2100.Pp 2101This rule drops random incoming packets with a probability 2102of 5%: 2103.Pp 2104.Dl "ipfw add prob 0.05 deny ip from any to any in" 2105.Pp 2106A similar effect can be achieved making use of dummynet pipes: 2107.Pp 2108.Dl "ipfw add pipe 10 ip from any to any" 2109.Dl "ipfw pipe 10 config plr 0.05" 2110.Pp 2111We can use pipes to artificially limit bandwidth, e.g. on a 2112machine acting as a router, if we want to limit traffic from 2113local clients on 192.168.2.0/24 we do: 2114.Pp 2115.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 2116.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes" 2117.Pp 2118note that we use the 2119.Cm out 2120modifier so that the rule is not used twice. 2121Remember in fact that 2122.Nm 2123rules are checked both on incoming and outgoing packets. 2124.Pp 2125Should we want to simulate a bidirectional link with bandwidth 2126limitations, the correct way is the following: 2127.Pp 2128.Dl "ipfw add pipe 1 ip from any to any out" 2129.Dl "ipfw add pipe 2 ip from any to any in" 2130.Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes" 2131.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes" 2132.Pp 2133The above can be very useful, e.g. if you want to see how 2134your fancy Web page will look for a residential user who 2135is connected only through a slow link. 2136You should not use only one pipe for both directions, unless 2137you want to simulate a half-duplex medium (e.g. AppleTalk, 2138Ethernet, IRDA). 2139It is not necessary that both pipes have the same configuration, 2140so we can also simulate asymmetric links. 2141.Pp 2142Should we want to verify network performance with the RED queue 2143management algorithm: 2144.Pp 2145.Dl "ipfw add pipe 1 ip from any to any" 2146.Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1" 2147.Pp 2148Another typical application of the traffic shaper is to 2149introduce some delay in the communication. 2150This can significantly affect applications which do a lot of Remote 2151Procedure Calls, and where the round-trip-time of the 2152connection often becomes a limiting factor much more than 2153bandwidth: 2154.Pp 2155.Dl "ipfw add pipe 1 ip from any to any out" 2156.Dl "ipfw add pipe 2 ip from any to any in" 2157.Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s" 2158.Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s" 2159.Pp 2160Per-flow queueing can be useful for a variety of purposes. 2161A very simple one is counting traffic: 2162.Pp 2163.Dl "ipfw add pipe 1 tcp from any to any" 2164.Dl "ipfw add pipe 1 udp from any to any" 2165.Dl "ipfw add pipe 1 ip from any to any" 2166.Dl "ipfw pipe 1 config mask all" 2167.Pp 2168The above set of rules will create queues (and collect 2169statistics) for all traffic. 2170Because the pipes have no limitations, the only effect is 2171collecting statistics. 2172Note that we need 3 rules, not just the last one, because 2173when 2174.Nm 2175tries to match IP packets it will not consider ports, so we 2176would not see connections on separate ports as different 2177ones. 2178.Pp 2179A more sophisticated example is limiting the outbound traffic 2180on a net with per-host limits, rather than per-network limits: 2181.Pp 2182.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 2183.Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in" 2184.Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 2185.Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 2186.Ss SETS OF RULES 2187To add a set of rules atomically, e.g. set 18: 2188.Pp 2189.Dl "ipfw disable set 18" 2190.Dl "ipfw add NN set 18 ... # repeat as needed" 2191.Dl "ipfw enable set 18" 2192.Pp 2193To delete a set of rules atomically the command is simply: 2194.Pp 2195.Dl "ipfw delete set 18" 2196.Pp 2197To test a ruleset and disable it and regain control if something goes wrong: 2198.Pp 2199.Dl "ipfw disable set 18" 2200.Dl "ipfw add NN set 18 ... # repeat as needed" 2201.Dl "ipfw enable set 18 ; echo done; sleep 30 && ipfw disable set 18" 2202.Pp 2203Here if everything goes well, you press control-C before the "sleep" 2204terminates, and your ruleset will be left active. Otherwise, e.g. if 2205you cannot access your box, the ruleset will be disabled after 2206the sleep terminates thus restoring the previous situation. 2207.Sh SEE ALSO 2208.Xr cpp 1 , 2209.Xr m4 1 , 2210.Xr divert 4 , 2211.Xr dummynet 4 , 2212.Xr ip 4 , 2213.Xr ipfirewall 4 , 2214.Xr protocols 5 , 2215.Xr services 5 , 2216.Xr init 8 , 2217.Xr kldload 8 , 2218.Xr reboot 8 , 2219.Xr sysctl 8 , 2220.Xr syslogd 8 2221.Sh HISTORY 2222The 2223.Nm 2224utility first appeared in 2225.Fx 2.0 . 2226.Xr dummynet 4 2227was introduced in 2228.Fx 2.2.8 . 2229Stateful extensions were introduced in 2230.Fx 4.0 , 2231and were rewritten in 2232.Dx 4.9 . 2233Table was introduced in 2234.Dx 4.9 . 2235.Nm ipfw2 2236was introduced in Summer 2002. 2237.Sh AUTHORS 2238.An Ugen J. S. Antsilevich , 2239.An Poul-Henning Kamp , 2240.An Alex Nash , 2241.An Archie Cobbs , 2242.An Luigi Rizzo . 2243.Pp 2244.An -nosplit 2245API based upon code written by 2246.An Daniel Boulet 2247for BSDI. 2248.Pp 2249Work on 2250.Xr dummynet 4 2251traffic shaper supported by Akamba Corp. 2252.Sh BUGS 2253The syntax has grown over the years and sometimes it might be confusing. 2254Unfortunately, backward compatibility prevents cleaning up mistakes 2255made in the definition of the syntax. 2256.Pp 2257.Em !!! WARNING !!! 2258.Pp 2259Misconfiguring the firewall can put your computer in an unusable state, 2260possibly shutting down network services and requiring console access to 2261regain control of it. 2262.Pp 2263Incoming packet fragments diverted by 2264.Cm divert 2265or 2266.Cm tee 2267are reassembled before delivery to the socket. 2268The action used on those packet is the one from the 2269rule which matches the first fragment of the packet. 2270.Pp 2271Packets that match a 2272.Cm tee 2273rule should not be immediately accepted, but should continue 2274going through the rule list. 2275This may be fixed in a later version. 2276.Pp 2277Packets diverted to userland, and then reinserted by a userland process 2278(such as 2279.Xr natd 8 ) 2280will lose various packet attributes, including their source interface. 2281If a packet is reinserted in this manner, later rules may be incorrectly 2282applied, making the order of 2283.Cm divert 2284rules in the rule sequence very important. 2285