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