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