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