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