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