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