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.9 2006/07/22 23:52:23 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.Cm ether_demux() , 356but the same packets will have the MAC header stripped off when 357.Nm 358is invoked from 359.Cm 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.Cm ip_input() 366), the 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 rules. 1172.Pp 1173Dynamic rules are created when a packet matches a 1174.Cm keep-state 1175or 1176.Cm limit 1177rule, causing the creation of a 1178.Em dynamic 1179rule which will match all and only packets with 1180a given 1181.Em protocol 1182between a 1183.Em src-ip/src-port dst-ip/dst-port 1184pair of addresses ( 1185.Em src 1186and 1187.Em dst 1188are used here only to denote the initial match addresses, but they 1189are completely equivalent afterwards). 1190Dynamic rules will be checked at the first 1191.Cm check-state, keep-state 1192or 1193.Cm limit 1194occurrence, and the action performed upon a match will be the same 1195as in the parent rule. 1196.Pp 1197Note that no additional attributes other than protocol and IP addresses 1198and ports are checked on dynamic rules. 1199.Pp 1200The typical use of dynamic rules is to keep a closed firewall configuration, 1201but let the first TCP SYN packet from the inside network install a 1202dynamic rule for the flow so that packets belonging to that session 1203will be allowed through the firewall: 1204.Pp 1205.Dl "ipfw add check-state" 1206.Dl "ipfw add allow tcp from my-subnet to any setup keep-state" 1207.Dl "ipfw add deny tcp from any to any" 1208.Pp 1209A similar approach can be used for UDP, where an UDP packet coming 1210from the inside will install a dynamic rule to let the response through 1211the firewall: 1212.Pp 1213.Dl "ipfw add check-state" 1214.Dl "ipfw add allow udp from my-subnet to any keep-state" 1215.Dl "ipfw add deny udp from any to any" 1216.Pp 1217Dynamic rules expire after some time, which depends on the status 1218of the flow and the setting of some 1219.Cm sysctl 1220variables. 1221See Section 1222.Sx SYSCTL VARIABLES 1223for more details. 1224For TCP sessions, dynamic rules can be instructed to periodically 1225send keepalive packets to refresh the state of the rule when it is 1226about to expire. 1227.Pp 1228See Section 1229.Sx EXAMPLES 1230for more examples on how to use dynamic rules. 1231.Sh TRAFFIC SHAPER (DUMMYNET) CONFIGURATION 1232.Nm 1233is also the user interface for the 1234.Xr dummynet 4 1235traffic shaper. 1236.Pp 1237.Nm dummynet 1238operates by first using the firewall to classify packets and divide them into 1239.Em flows , 1240using any match pattern that can be used in 1241.Nm 1242rules. 1243Depending on local policies, a flow can contain packets for a single 1244TCP connection, or from/to a given host, or entire subnet, or a 1245protocol type, etc. 1246.Pp 1247Packets belonging to the same flow are then passed to either of two 1248different objects, which implement the traffic regulation: 1249.Bl -hang -offset XXXX 1250.It Em pipe 1251A pipe emulates a link with given bandwidth, propagation delay, 1252queue size and packet loss rate. 1253Packets are queued in front of the pipe as they come out from the classifier, 1254and then transferred to the pipe according to the pipe's parameters. 1255.Pp 1256.It Em queue 1257A queue 1258is an abstraction used to implement the WF2Q+ 1259(Worst-case Fair Weighted Fair Queueing) policy, which is 1260an efficient variant of the WFQ policy. 1261.br 1262The queue associates a 1263.Em weight 1264and a reference pipe to each flow, and then all backlogged (i.e., 1265with packets queued) flows linked to the same pipe share the pipe's 1266bandwidth proportionally to their weights. 1267Note that weights are not priorities; a flow with a lower weight 1268is still guaranteed to get its fraction of the bandwidth even if a 1269flow with a higher weight is permanently backlogged. 1270.El 1271In practice, 1272.Em pipes 1273can be used to set hard limits to the bandwidth that a flow can use, whereas 1274.Em queues 1275can be used to determine how different flow share the available bandwidth. 1276.Pp 1277The 1278.Em pipe 1279and 1280.Em queue 1281configuration commands are the following: 1282.Bd -ragged -offset indent 1283.Cm pipe Ar number Cm config Ar pipe-configuration 1284.Pp 1285.Cm queue Ar number Cm config Ar queue-configuration 1286.Ed 1287.Pp 1288The following parameters can be configured for a pipe: 1289.Pp 1290.Bl -tag -width indent -compact 1291.It Cm bw Ar bandwidth | device 1292Bandwidth, measured in 1293.Sm off 1294.Op Cm K | M 1295.Brq Cm bit/s | Byte/s . 1296.Sm on 1297.Pp 1298A value of 0 (default) means unlimited bandwidth. 1299The unit must immediately follow the number, as in 1300.Pp 1301.Dl "ipfw pipe 1 config bw 300Kbit/s" 1302.Pp 1303If a device name is specified instead of a numeric value, as in 1304.Pp 1305.Dl "ipfw pipe 1 config bw tun0" 1306.Pp 1307then the transmit clock is supplied by the specified device. 1308At the moment only the 1309.Xr tun 4 1310device supports this 1311functionality, for use in conjunction with 1312.Xr ppp 8 . 1313.Pp 1314.It Cm delay Ar ms-delay 1315Propagation delay, measured in milliseconds. 1316The value is rounded to the next multiple of the clock tick 1317(typically 10ms, but it is a good practice to run kernels 1318with 1319.Cd "options HZ=1000" 1320to reduce 1321the granularity to 1ms or less). 1322Default value is 0, meaning no delay. 1323.El 1324.Pp 1325The following parameters can be configured for a queue: 1326.Pp 1327.Bl -tag -width indent -compact 1328.It Cm pipe Ar pipe_nr 1329Connects a queue to the specified pipe. 1330Multiple queues (with the same or different weights) can be connected to 1331the same pipe, which specifies the aggregate rate for the set of queues. 1332.Pp 1333.It Cm weight Ar weight 1334Specifies the weight to be used for flows matching this queue. 1335The weight must be in the range 1..100, and defaults to 1. 1336.El 1337.Pp 1338Finally, the following parameters can be configured for both 1339pipes and queues: 1340.Pp 1341.Bl -tag -width XXXX -compact 1342.Pp 1343.It Cm buckets Ar hash-table-size 1344Specifies the size of the hash table used for storing the 1345various queues. 1346Default value is 64 controlled by the 1347.Xr sysctl 8 1348variable 1349.Em net.inet.ip.dummynet.hash_size , 1350allowed range is 16 to 65536. 1351.Pp 1352.It Cm mask Ar mask-specifier 1353Packets sent to a given pipe or queue by an 1354.Nm 1355rule can be further classified into multiple flows, each of which is then 1356sent to a different 1357.Em dynamic 1358pipe or queue. 1359A flow identifier is constructed by masking the IP addresses, 1360ports and protocol types as specified with the 1361.Cm mask 1362options in the configuration of the pipe or queue. 1363For each different flow identifier, a new pipe or queue is created 1364with the same parameters as the original object, and matching packets 1365are sent to it. 1366.Pp 1367Thus, when 1368.Em dynamic pipes 1369are used, each flow will get the same bandwidth as defined by the pipe, 1370whereas when 1371.Em dynamic queues 1372are used, each flow will share the parent's pipe bandwidth evenly 1373with other flows generated by the same queue (note that other queues 1374with different weights might be connected to the same pipe). 1375.br 1376Available mask specifiers are a combination of one or more of the following: 1377.Pp 1378.Cm dst-ip Ar mask , 1379.Cm src-ip Ar mask , 1380.Cm dst-port Ar mask , 1381.Cm src-port Ar mask , 1382.Cm proto Ar mask 1383or 1384.Cm all , 1385.Pp 1386where the latter means all bits in all fields are significant. 1387.Pp 1388.It Cm noerror 1389When a packet is dropped by a dummynet queue or pipe, the error 1390is normally reported to the caller routine in the kernel, in the 1391same way as it happens when a device queue fills up. Setting this 1392option reports the packet as successfully delivered, which can be 1393needed for some experimental setups where you want to simulate 1394loss or congestion at a remote router. 1395.Pp 1396.It Cm plr Ar packet-loss-rate 1397Packet loss rate. 1398Argument 1399.Ar packet-loss-rate 1400is a floating-point number between 0 and 1, with 0 meaning no 1401loss, 1 meaning 100% loss. 1402The loss rate is internally represented on 31 bits. 1403.Pp 1404.It Cm queue Brq Ar slots | size Ns Cm Kbytes 1405Queue size, in 1406.Ar slots 1407or 1408.Cm KBytes . 1409Default value is 50 slots, which 1410is the typical queue size for Ethernet devices. 1411Note that for slow speed links you should keep the queue 1412size short or your traffic might be affected by a significant 1413queueing delay. 1414E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit 1415or 20s of queue on a 30Kbit/s pipe. 1416Even worse effect can result if you get packets from an 1417interface with a much larger MTU, e.g. the loopback interface 1418with its 16KB packets. 1419.Pp 1420.It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p 1421Make use of the RED (Random Early Detection) queue management algorithm. 1422.Ar w_q 1423and 1424.Ar max_p 1425are floating 1426point numbers between 0 and 1 (0 not included), while 1427.Ar min_th 1428and 1429.Ar max_th 1430are integer numbers specifying thresholds for queue management 1431(thresholds are computed in bytes if the queue has been defined 1432in bytes, in slots otherwise). 1433The 1434.Xr dummynet 4 1435also supports the gentle RED variant (gred). 1436Three 1437.Xr sysctl 8 1438variables can be used to control the RED behaviour: 1439.Bl -tag -width indent 1440.It Em net.inet.ip.dummynet.red_lookup_depth 1441specifies the accuracy in computing the average queue 1442when the link is idle (defaults to 256, must be greater than zero) 1443.It Em net.inet.ip.dummynet.red_avg_pkt_size 1444specifies the expected average packet size (defaults to 512, must be 1445greater than zero) 1446.It Em net.inet.ip.dummynet.red_max_pkt_size 1447specifies the expected maximum packet size, only used when queue 1448thresholds are in bytes (defaults to 1500, must be greater than zero). 1449.El 1450.El 1451.Sh CHECKLIST 1452Here are some important points to consider when designing your 1453rules: 1454.Bl -bullet 1455.It 1456Remember that you filter both packets going 1457.Cm in 1458and 1459.Cm out . 1460Most connections need packets going in both directions. 1461.It 1462Remember to test very carefully. 1463It is a good idea to be near the console when doing this. 1464If you cannot be near the console, 1465use an auto-recovery script such as the one in 1466.Pa /usr/share/examples/ipfw/change_rules.sh . 1467.It 1468Don't forget the loopback interface. 1469.El 1470.Sh FINE POINTS 1471.Bl -bullet 1472.It 1473There are circumstances where fragmented datagrams are unconditionally 1474dropped. 1475TCP packets are dropped if they do not contain at least 20 bytes of 1476TCP header, UDP packets are dropped if they do not contain a full 8 1477byte UDP header, and ICMP packets are dropped if they do not contain 14784 bytes of ICMP header, enough to specify the ICMP type, code, and 1479checksum. 1480These packets are simply logged as 1481.Dq pullup failed 1482since there may not be enough good data in the packet to produce a 1483meaningful log entry. 1484.It 1485Another type of packet is unconditionally dropped, a TCP packet with a 1486fragment offset of one. 1487This is a valid packet, but it only has one use, to try 1488to circumvent firewalls. 1489When logging is enabled, these packets are 1490reported as being dropped by rule -1. 1491.It 1492If you are logged in over a network, loading the 1493.Xr kld 4 1494version of 1495.Nm 1496is probably not as straightforward as you would think. 1497I recommend the following command line: 1498.Bd -literal -offset indent 1499kldload /modules/ipfw.ko && \e 1500ipfw add 32000 allow ip from any to any 1501.Ed 1502.Pp 1503Along the same lines, doing an 1504.Bd -literal -offset indent 1505ipfw flush 1506.Ed 1507.Pp 1508in similar surroundings is also a bad idea. 1509.It 1510The 1511.Nm 1512filter list may not be modified if the system security level 1513is set to 3 or higher 1514(see 1515.Xr init 8 1516for information on system security levels). 1517.El 1518.Sh PACKET DIVERSION 1519A 1520.Xr divert 4 1521socket bound to the specified port will receive all packets 1522diverted to that port. 1523If no socket is bound to the destination port, or if the kernel 1524wasn't compiled with divert socket support, the packets are 1525dropped. 1526.Sh SYSCTL VARIABLES 1527A set of 1528.Xr sysctl 8 1529variables controls the behaviour of the firewall and 1530associated modules ( 1531.Nm dummynet 1532). 1533These are shown below together with their default value 1534(but always check with the 1535.Xr sysctl 8 1536command what value is actually in use) and meaning: 1537.Bl -tag -width indent 1538.It Em net.inet.ip.dummynet.expire : No 1 1539Lazily delete dynamic pipes/queue once they have no pending traffic. 1540You can disable this by setting the variable to 0, in which case 1541the pipes/queues will only be deleted when the threshold is reached. 1542.It Em net.inet.ip.dummynet.hash_size : No 64 1543Default size of the hash table used for dynamic pipes/queues. 1544This value is used when no 1545.Cm buckets 1546option is specified when configuring a pipe/queue. 1547.It Em net.inet.ip.dummynet.max_chain_len : No 16 1548Target value for the maximum number of pipes/queues in a hash bucket. 1549The product 1550.Cm max_chain_len*hash_size 1551is used to determine the threshold over which empty pipes/queues 1552will be expired even when 1553.Cm net.inet.ip.dummynet.expire=0 . 1554.It Em net.inet.ip.dummynet.red_lookup_depth : No 256 1555.It Em net.inet.ip.dummynet.red_avg_pkt_size : No 512 1556.It Em net.inet.ip.dummynet.red_max_pkt_size : No 1500 1557Parameters used in the computations of the drop probability 1558for the RED algorithm. 1559.It Em net.inet.ip.fw.autoinc_step : No 100 1560Delta between rule numbers when auto-generating them. 1561The value must be in the range 1..1000. 1562.It Em net.inet.ip.fw.curr_dyn_buckets : Em net.inet.ip.fw.dyn_buckets 1563The current number of buckets in the hash table for dynamic rules 1564(readonly). 1565.It Em net.inet.ip.fw.debug : No 1 1566Controls debugging messages produced by 1567.Nm . 1568.It Em net.inet.ip.fw.dyn_buckets : No 256 1569The number of buckets in the hash table for dynamic rules. 1570Must be a power of 2, up to 65536. 1571It only takes effect when all dynamic rules have expired, so you 1572are advised to use a 1573.Cm flush 1574command to make sure that the hash table is resized. 1575.It Em net.inet.ip.fw.dyn_count : No 3 1576Current number of dynamic rules 1577(read-only). 1578.It Em net.inet.ip.fw.dyn_keepalive : No 1 1579Enables generation of keepalive packets for 1580.Cm keep-state 1581rules on TCP sessions. A keepalive is generated to both 1582sides of the connection every 5 seconds for the last 20 1583seconds of the lifetime of the rule. 1584.It Em net.inet.ip.fw.dyn_max : No 8192 1585Maximum number of dynamic rules. 1586When you hit this limit, no more dynamic rules can be 1587installed until old ones expire. 1588.It Em net.inet.ip.fw.dyn_ack_lifetime : No 300 1589.It Em net.inet.ip.fw.dyn_syn_lifetime : No 20 1590.It Em net.inet.ip.fw.dyn_fin_lifetime : No 1 1591.It Em net.inet.ip.fw.dyn_rst_lifetime : No 1 1592.It Em net.inet.ip.fw.dyn_udp_lifetime : No 5 1593.It Em net.inet.ip.fw.dyn_short_lifetime : No 30 1594These variables control the lifetime, in seconds, of dynamic 1595rules. 1596Upon the initial SYN exchange the lifetime is kept short, 1597then increased after both SYN have been seen, then decreased 1598again during the final FIN exchange or when a RST is received. 1599Both 1600.Em dyn_fin_lifetime 1601and 1602.Em dyn_rst_lifetime 1603must be strictly lower than 5 seconds, the period of 1604repetition of keepalives. The firewall enforces that. 1605.It Em net.inet.ip.fw.enable : No 1 1606Enables the firewall. 1607Setting this variable to 0 lets you run your machine without 1608firewall even if compiled in. 1609.It Em net.inet.ip.fw.one_pass : No 1 1610When set, the packet exiting from the 1611.Xr dummynet 4 1612pipe is not passed though the firewall again. 1613Otherwise, after a pipe action, the packet is 1614reinjected into the firewall at the next rule. 1615.Pp 1616Note: layer 2 packets coming out of a pipe 1617are never reinjected in the firewall irrespective of the 1618value of this variable. 1619.It Em net.inet.ip.fw.verbose : No 1 1620Enables verbose messages. 1621.It Em net.inet.ip.fw.verbose_limit : No 0 1622Limits the number of messages produced by a verbose firewall. 1623.It Em net.link.ether.ipfw : No 0 1624Controls whether layer-2 packets are passed to 1625.Nm . 1626Default is no. 1627.El 1628.Sh USING IPFW2 IN FreeBSD-STABLE 1629.Nm ipfw2 1630is standard in 1631.Fx 1632CURRENT, whereas 1633.Fx 1634STABLE still uses 1635.Nm ipfw1 1636unless the kernel is compiled with 1637.Cd options IPFW2 , 1638and 1639.Nm /sbin/ipfw 1640and 1641.Nm /usr/lib/libalias 1642are recompiled with 1643.Cm -DIPFW2 1644and reinstalled (the same effect can be achieved by adding 1645.Cm IPFW2=TRUE 1646to 1647.Nm /etc/make.conf 1648before a buildworld). 1649.Sh IPFW2 ENHANCEMENTS 1650This Section lists the features that have been introduced in 1651.Nm ipfw2 1652which were not present in 1653.Nm ipfw1 . 1654We list them in order of the potential impact that they can 1655have in writing your rulesets. 1656You might want to consider using these features in order to 1657write your rulesets in a more efficient way. 1658.Bl -tag -width indent 1659.It Handling of non-IPv4 packets 1660.Nm ipfw1 1661will silently accept all non-IPv4 packets. 1662.Nm ipfw2 1663will filter all packets (including non-IPv4 ones) according to the ruleset. 1664To achieve the same behaviour as 1665.Nm ipfw1 1666you can use the following as the very first rule in your ruleset: 1667.Pp 1668.Dl "ipfw add 1 allow layer2 not mac-type ip" 1669.Pp 1670The 1671.Cm layer2 1672option might seem redundant, but it is necessary -- packets 1673passed to the firewall from layer3 will not have a MAC header, 1674so the 1675.Cm mac-type ip 1676pattern will always fail on them, and the 1677.Cm not 1678operator will make this rule into a pass-all. 1679.It Address sets 1680.Nm ipfw1 1681does not supports address sets (those in the form 1682.Ar addr/masklen{num,num,...} 1683). 1684.Pp 1685.It Port specifications 1686.Nm ipfw1 1687only allows one port range when specifying TCP and UDP ports, and 1688is limited to 10 entries instead of the 15 allowed by 1689.Nm ipfw2 . 1690Also, in 1691.Nm ipfw1 1692you can only specify ports when the rule is requesting 1693.Cm tcp 1694or 1695.Cm udp 1696packets. With 1697.Nm ipfw2 1698you can put port specifications in rules matching all packets, 1699and the match will be attempted only on those packets carrying 1700protocols which include port identifiers. 1701.Pp 1702Finally, 1703.Nm ipfw1 1704allowed the first port entry to be specified as 1705.Ar port:mask 1706where 1707.Ar mask 1708can be an arbitrary 16-bit mask. 1709This syntax is of questionable usefulness and it is not 1710supported anymore in 1711.Nm ipfw2 . 1712.It Or-blocks 1713.Nm ipfw1 1714does not support Or-blocks. 1715.It keepalives 1716.Nm ipfw1 1717does not generate keepalives for stateful sessions. 1718As a consequence, it might cause idle sessions to drop because 1719the lifetime of the dynamic rules expires. 1720.It Sets of rules 1721.Nm ipfw1 1722does not implement sets of rules. 1723.It MAC header filtering and Layer-2 firewalling. 1724.Nm ipfw1 1725does not implement filtering on MAC header fields, nor is it 1726invoked on packets from 1727.Cm ether_demux() 1728and 1729.Cm ether_output_frame(). 1730The sysctl variable 1731.Em net.link.ether.ipfw 1732has no effect there. 1733.It Options 1734The following options are not supported in 1735.Nm ipfw1 1736.Pp 1737.Cm dst-ip, dst-port, layer2, mac, mac-type, src-ip, src-port. 1738.Pp 1739Additionally, the following options are not supported in 1740.Nm ipfw1 1741(RELENG_4) 1742rules: 1743.Pp 1744.Cm ipid, iplen, ipprecedence, iptos, ipttl, 1745.Cm ipversion, tcpack, tcpseq, tcpwin . 1746.It Dummynet options 1747The following option for 1748.Nm dummynet 1749pipes/queues is not supported: 1750.Cm noerror . 1751.El 1752.Sh EXAMPLES 1753There are far too many possible uses of 1754.Nm 1755so this Section will only give a small set of examples. 1756.Ss BASIC PACKET FILTERING 1757This command adds an entry which denies all tcp packets from 1758.Em cracker.evil.org 1759to the telnet port of 1760.Em wolf.tambov.su 1761from being forwarded by the host: 1762.Pp 1763.Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet" 1764.Pp 1765This one disallows any connection from the entire cracker's 1766network to my host: 1767.Pp 1768.Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org" 1769.Pp 1770A first and efficient way to limit access (not using dynamic rules) 1771is the use of the following rules: 1772.Pp 1773.Dl "ipfw add allow tcp from any to any established" 1774.Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup" 1775.Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup" 1776.Dl "..." 1777.Dl "ipfw add deny tcp from any to any" 1778.Pp 1779The first rule will be a quick match for normal TCP packets, 1780but it will not match the initial SYN packet, which will be 1781matched by the 1782.Cm setup 1783rules only for selected source/destination pairs. 1784All other SYN packets will be rejected by the final 1785.Cm deny 1786rule. 1787.Pp 1788If you administer one or more subnets, you can take advantage of the 1789.Nm ipfw2 1790syntax to specify address sets and or-blocks and write extremely 1791compact rulesets which selectively enable services to blocks 1792of clients, as below: 1793.Pp 1794.Dl "goodguys=\*q{ 10.1.2.0/24{20,35,66,18} or 10.2.3.0/28{6,3,11} }\*q" 1795.Dl "badguys=\*q10.1.2.0/24{8,38,60}\*q" 1796.Dl "" 1797.Dl "ipfw add allow ip from ${goodguys} to any" 1798.Dl "ipfw add deny ip from ${badguys} to any" 1799.Dl "... normal policies ..." 1800.Pp 1801The 1802.Nm ipfw1 1803syntax would require a separate rule for each IP in the above 1804example. 1805.Ss DYNAMIC RULES 1806In order to protect a site from flood attacks involving fake 1807TCP packets, it is safer to use dynamic rules: 1808.Pp 1809.Dl "ipfw add check-state" 1810.Dl "ipfw add deny tcp from any to any established" 1811.Dl "ipfw add allow tcp from my-net to any setup keep-state" 1812.Pp 1813This will let the firewall install dynamic rules only for 1814those connection which start with a regular SYN packet coming 1815from the inside of our network. 1816Dynamic rules are checked when encountering the first 1817.Cm check-state 1818or 1819.Cm keep-state 1820rule. 1821A 1822.Cm check-state 1823rule should usually be placed near the beginning of the 1824ruleset to minimize the amount of work scanning the ruleset. 1825Your mileage may vary. 1826.Pp 1827To limit the number of connections a user can open 1828you can use the following type of rules: 1829.Pp 1830.Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10" 1831.Dl "ipfw add allow tcp from any to me setup limit src-addr 4" 1832.Pp 1833The former (assuming it runs on a gateway) will allow each host 1834on a /24 network to open at most 10 TCP connections. 1835The latter can be placed on a server to make sure that a single 1836client does not use more than 4 simultaneous connections. 1837.Pp 1838.Em BEWARE : 1839stateful rules can be subject to denial-of-service attacks 1840by a SYN-flood which opens a huge number of dynamic rules. 1841The effects of such attacks can be partially limited by 1842acting on a set of 1843.Xr sysctl 8 1844variables which control the operation of the firewall. 1845.Pp 1846Here is a good usage of the 1847.Cm list 1848command to see accounting records and timestamp information: 1849.Pp 1850.Dl ipfw -at list 1851.Pp 1852or in short form without timestamps: 1853.Pp 1854.Dl ipfw -a list 1855.Pp 1856which is equivalent to: 1857.Pp 1858.Dl ipfw show 1859.Pp 1860Next rule diverts all incoming packets from 192.168.2.0/24 1861to divert port 5000: 1862.Pp 1863.Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in 1864.Ss TRAFFIC SHAPING 1865The following rules show some of the applications of 1866.Nm 1867and 1868.Xr dummynet 4 1869for simulations and the like. 1870.Pp 1871This rule drops random incoming packets with a probability 1872of 5%: 1873.Pp 1874.Dl "ipfw add prob 0.05 deny ip from any to any in" 1875.Pp 1876A similar effect can be achieved making use of dummynet pipes: 1877.Pp 1878.Dl "ipfw add pipe 10 ip from any to any" 1879.Dl "ipfw pipe 10 config plr 0.05" 1880.Pp 1881We can use pipes to artificially limit bandwidth, e.g. on a 1882machine acting as a router, if we want to limit traffic from 1883local clients on 192.168.2.0/24 we do: 1884.Pp 1885.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 1886.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes" 1887.Pp 1888note that we use the 1889.Cm out 1890modifier so that the rule is not used twice. 1891Remember in fact that 1892.Nm 1893rules are checked both on incoming and outgoing packets. 1894.Pp 1895Should we want to simulate a bidirectional link with bandwidth 1896limitations, the correct way is the following: 1897.Pp 1898.Dl "ipfw add pipe 1 ip from any to any out" 1899.Dl "ipfw add pipe 2 ip from any to any in" 1900.Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes" 1901.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes" 1902.Pp 1903The above can be very useful, e.g. if you want to see how 1904your fancy Web page will look for a residential user who 1905is connected only through a slow link. 1906You should not use only one pipe for both directions, unless 1907you want to simulate a half-duplex medium (e.g. AppleTalk, 1908Ethernet, IRDA). 1909It is not necessary that both pipes have the same configuration, 1910so we can also simulate asymmetric links. 1911.Pp 1912Should we want to verify network performance with the RED queue 1913management algorithm: 1914.Pp 1915.Dl "ipfw add pipe 1 ip from any to any" 1916.Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1" 1917.Pp 1918Another typical application of the traffic shaper is to 1919introduce some delay in the communication. 1920This can significantly affect applications which do a lot of Remote 1921Procedure Calls, and where the round-trip-time of the 1922connection often becomes a limiting factor much more than 1923bandwidth: 1924.Pp 1925.Dl "ipfw add pipe 1 ip from any to any out" 1926.Dl "ipfw add pipe 2 ip from any to any in" 1927.Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s" 1928.Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s" 1929.Pp 1930Per-flow queueing can be useful for a variety of purposes. 1931A very simple one is counting traffic: 1932.Pp 1933.Dl "ipfw add pipe 1 tcp from any to any" 1934.Dl "ipfw add pipe 1 udp from any to any" 1935.Dl "ipfw add pipe 1 ip from any to any" 1936.Dl "ipfw pipe 1 config mask all" 1937.Pp 1938The above set of rules will create queues (and collect 1939statistics) for all traffic. 1940Because the pipes have no limitations, the only effect is 1941collecting statistics. 1942Note that we need 3 rules, not just the last one, because 1943when 1944.Nm 1945tries to match IP packets it will not consider ports, so we 1946would not see connections on separate ports as different 1947ones. 1948.Pp 1949A more sophisticated example is limiting the outbound traffic 1950on a net with per-host limits, rather than per-network limits: 1951.Pp 1952.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 1953.Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in" 1954.Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 1955.Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 1956.Ss SETS OF RULES 1957To add a set of rules atomically, e.g. set 18: 1958.Pp 1959.Dl "ipfw disable set 18" 1960.Dl "ipfw add NN set 18 ... # repeat as needed" 1961.Dl "ipfw enable set 18" 1962.Pp 1963To delete a set of rules atomically the command is simply: 1964.Pp 1965.Dl "ipfw delete set 18" 1966.Pp 1967To test a ruleset and disable it and regain control if something goes wrong: 1968.Pp 1969.Dl "ipfw disable set 18" 1970.Dl "ipfw add NN set 18 ... # repeat as needed" 1971.Dl "ipfw enable set 18 ; echo done; sleep 30 && ipfw disable set 18" 1972.Pp 1973Here if everything goes well, you press control-C before the "sleep" 1974terminates, and your ruleset will be left active. Otherwise, e.g. if 1975you cannot access your box, the ruleset will be disabled after 1976the sleep terminates thus restoring the previous situation. 1977.Sh SEE ALSO 1978.Xr cpp 1 , 1979.Xr m4 1 , 1980.Xr divert 4 , 1981.Xr dummynet 4 , 1982.Xr ip 4 , 1983.Xr ipfirewall 4 , 1984.Xr protocols 5 , 1985.Xr services 5 , 1986.Xr init 8 , 1987.Xr kldload 8 , 1988.Xr reboot 8 , 1989.Xr sysctl 8 , 1990.Xr syslogd 8 1991.Sh HISTORY 1992The 1993.Nm 1994utility first appeared in 1995.Fx 2.0 . 1996.Xr dummynet 4 1997was introduced in 1998.Fx 2.2.8 . 1999Stateful extensions were introduced in 2000.Fx 4.0 . 2001.Nm ipfw2 2002was introduced in Summer 2002. 2003.Sh AUTHORS 2004.An Ugen J. S. Antsilevich , 2005.An Poul-Henning Kamp , 2006.An Alex Nash , 2007.An Archie Cobbs , 2008.An Luigi Rizzo . 2009.Pp 2010.An -nosplit 2011API based upon code written by 2012.An Daniel Boulet 2013for BSDI. 2014.Pp 2015Work on 2016.Xr dummynet 4 2017traffic shaper supported by Akamba Corp. 2018.Sh BUGS 2019The syntax has grown over the years and sometimes it might be confusing. 2020Unfortunately, backward compatibility prevents cleaning up mistakes 2021made in the definition of the syntax. 2022.Pp 2023.Em !!! WARNING !!! 2024.Pp 2025Misconfiguring the firewall can put your computer in an unusable state, 2026possibly shutting down network services and requiring console access to 2027regain control of it. 2028.Pp 2029Incoming packet fragments diverted by 2030.Cm divert 2031or 2032.Cm tee 2033are reassembled before delivery to the socket. 2034The action used on those packet is the one from the 2035rule which matches the first fragment of the packet. 2036.Pp 2037Packets that match a 2038.Cm tee 2039rule should not be immediately accepted, but should continue 2040going through the rule list. 2041This may be fixed in a later version. 2042.Pp 2043Packets diverted to userland, and then reinserted by a userland process 2044(such as 2045.Xr natd 8 ) 2046will lose various packet attributes, including their source interface. 2047If a packet is reinserted in this manner, later rules may be incorrectly 2048applied, making the order of 2049.Cm divert 2050rules in the rule sequence very important. 2051