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