1.\" 2.\" $FreeBSD$ 3.\" 4.Dd March 1, 2019 5.Dt IPFW 8 6.Os 7.Sh NAME 8.Nm ipfw 9.Nd User interface for firewall, traffic shaper, packet scheduler, 10in-kernel NAT. 11.Sh SYNOPSIS 12.Ss FIREWALL CONFIGURATION 13.Nm 14.Op Fl cq 15.Cm add 16.Ar rule 17.Nm 18.Op Fl acdefnNStT 19.Op Cm set Ar N 20.Brq Cm list | show 21.Op Ar rule | first-last ... 22.Nm 23.Op Fl f | q 24.Op Cm set Ar N 25.Cm flush 26.Nm 27.Op Fl q 28.Op Cm set Ar N 29.Brq Cm delete | zero | resetlog 30.Op Ar number ... 31.Pp 32.Nm 33.Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ... 34.Nm 35.Cm set move 36.Op Cm rule 37.Ar number Cm to Ar number 38.Nm 39.Cm set swap Ar number number 40.Nm 41.Cm set show 42.Ss SYSCTL SHORTCUTS 43.Nm 44.Cm enable 45.Brq Cm firewall | altq | one_pass | debug | verbose | dyn_keepalive 46.Nm 47.Cm disable 48.Brq Cm firewall | altq | one_pass | debug | verbose | dyn_keepalive 49.Ss LOOKUP TABLES 50.Nm 51.Oo Cm set Ar N Oc Cm table Ar name Cm create Ar create-options 52.Nm 53.Oo Cm set Ar N Oc Cm table 54.Brq Ar name | all 55.Cm destroy 56.Nm 57.Oo Cm set Ar N Oc Cm table Ar name Cm modify Ar modify-options 58.Nm 59.Oo Cm set Ar N Oc Cm table Ar name Cm swap Ar name 60.Nm 61.Oo Cm set Ar N Oc Cm table Ar name Cm add Ar table-key Op Ar value 62.Nm 63.Oo Cm set Ar N Oc Cm table Ar name Cm add Op Ar table-key Ar value ... 64.Nm 65.Oo Cm set Ar N Oc Cm table Ar name Cm atomic add Op Ar table-key Ar value ... 66.Nm 67.Oo Cm set Ar N Oc Cm table Ar name Cm delete Op Ar table-key ... 68.Nm 69.Oo Cm set Ar N Oc Cm table Ar name Cm lookup Ar addr 70.Nm 71.Oo Cm set Ar N Oc Cm table Ar name Cm lock 72.Nm 73.Oo Cm set Ar N Oc Cm table Ar name Cm unlock 74.Nm 75.Oo Cm set Ar N Oc Cm table 76.Brq Ar name | all 77.Cm list 78.Nm 79.Oo Cm set Ar N Oc Cm table 80.Brq Ar name | all 81.Cm info 82.Nm 83.Oo Cm set Ar N Oc Cm table 84.Brq Ar name | all 85.Cm detail 86.Nm 87.Oo Cm set Ar N Oc Cm table 88.Brq Ar name | all 89.Cm flush 90.Ss DUMMYNET CONFIGURATION (TRAFFIC SHAPER AND PACKET SCHEDULER) 91.Nm 92.Brq Cm pipe | queue | sched 93.Ar number 94.Cm config 95.Ar config-options 96.Nm 97.Op Fl s Op Ar field 98.Brq Cm pipe | queue | sched 99.Brq Cm delete | list | show 100.Op Ar number ... 101.Ss IN-KERNEL NAT 102.Nm 103.Op Fl q 104.Cm nat 105.Ar number 106.Cm config 107.Ar config-options 108.Ss STATEFUL IPv6/IPv4 NETWORK ADDRESS AND PROTOCOL TRANSLATION 109.Nm 110.Oo Cm set Ar N Oc Cm nat64lsn Ar name Cm create Ar create-options 111.Nm 112.Oo Cm set Ar N Oc Cm nat64lsn Ar name Cm config Ar config-options 113.Nm 114.Oo Cm set Ar N Oc Cm nat64lsn 115.Brq Ar name | all 116.Brq Cm list | show 117.Op Cm states 118.Nm 119.Oo Cm set Ar N Oc Cm nat64lsn 120.Brq Ar name | all 121.Cm destroy 122.Nm 123.Oo Cm set Ar N Oc Cm nat64lsn Ar name Cm stats Op Cm reset 124.Ss STATELESS IPv6/IPv4 NETWORK ADDRESS AND PROTOCOL TRANSLATION 125.Nm 126.Oo Cm set Ar N Oc Cm nat64stl Ar name Cm create Ar create-options 127.Nm 128.Oo Cm set Ar N Oc Cm nat64stl Ar name Cm config Ar config-options 129.Nm 130.Oo Cm set Ar N Oc Cm nat64stl 131.Brq Ar name | all 132.Brq Cm list | show 133.Nm 134.Oo Cm set Ar N Oc Cm nat64stl 135.Brq Ar name | all 136.Cm destroy 137.Nm 138.Oo Cm set Ar N Oc Cm nat64stl Ar name Cm stats Op Cm reset 139.Ss IPv6-to-IPv6 NETWORK PREFIX TRANSLATION 140.Nm 141.Oo Cm set Ar N Oc Cm nptv6 Ar name Cm create Ar create-options 142.Nm 143.Oo Cm set Ar N Oc Cm nptv6 144.Brq Ar name | all 145.Brq Cm list | show 146.Nm 147.Oo Cm set Ar N Oc Cm nptv6 148.Brq Ar name | all 149.Cm destroy 150.Nm 151.Oo Cm set Ar N Oc Cm nptv6 Ar name Cm stats Op Cm reset 152.Ss INTERNAL DIAGNOSTICS 153.Nm 154.Cm internal iflist 155.Nm 156.Cm internal talist 157.Nm 158.Cm internal vlist 159.Ss LIST OF RULES AND PREPROCESSING 160.Nm 161.Op Fl cfnNqS 162.Oo 163.Fl p Ar preproc 164.Oo 165.Ar preproc-flags 166.Oc 167.Oc 168.Ar pathname 169.Sh DESCRIPTION 170The 171.Nm 172utility is the user interface for controlling the 173.Xr ipfw 4 174firewall, the 175.Xr dummynet 4 176traffic shaper/packet scheduler, and the 177in-kernel NAT services. 178.Pp 179A firewall configuration, or 180.Em ruleset , 181is made of a list of 182.Em rules 183numbered from 1 to 65535. 184Packets are passed to the firewall 185from a number of different places in the protocol stack 186(depending on the source and destination of the packet, 187it is possible for the firewall to be 188invoked multiple times on the same packet). 189The packet passed to the firewall is compared 190against each of the rules in the 191.Em ruleset , 192in rule-number order 193(multiple rules with the same number are permitted, in which case 194they are processed in order of insertion). 195When a match is found, the action corresponding to the 196matching rule is performed. 197.Pp 198Depending on the action and certain system settings, packets 199can be reinjected into the firewall at some rule after the 200matching one for further processing. 201.Pp 202A ruleset always includes a 203.Em default 204rule (numbered 65535) which cannot be modified or deleted, 205and matches all packets. 206The action associated with the 207.Em default 208rule can be either 209.Cm deny 210or 211.Cm allow 212depending on how the kernel is configured. 213.Pp 214If the ruleset includes one or more rules with the 215.Cm keep-state , 216.Cm record-state , 217.Cm limit 218or 219.Cm set-limit 220option, 221the firewall will have a 222.Em stateful 223behaviour, i.e., upon a match it will create 224.Em dynamic rules , 225i.e., rules that match packets with the same 5-tuple 226(protocol, source and destination addresses and ports) 227as the packet which caused their creation. 228Dynamic rules, which have a limited lifetime, are checked 229at the first occurrence of a 230.Cm check-state , 231.Cm keep-state 232or 233.Cm limit 234rule, and are typically used to open the firewall on-demand to 235legitimate traffic only. 236Please note, that 237.Cm keep-state 238amd 239.Cm limit 240imply implicit 241.Cm check-state 242for all packets (not only these matched by the rule) but 243.Cm record-state 244and 245.Cm set-limit 246have no implicit 247.Cm check-state . 248See the 249.Sx STATEFUL FIREWALL 250and 251.Sx EXAMPLES 252Sections below for more information on the stateful behaviour of 253.Nm . 254.Pp 255All rules (including dynamic ones) have a few associated counters: 256a packet count, a byte count, a log count and a timestamp 257indicating the time of the last match. 258Counters can be displayed or reset with 259.Nm 260commands. 261.Pp 262Each rule belongs to one of 32 different 263.Em sets 264, and there are 265.Nm 266commands to atomically manipulate sets, such as enable, 267disable, swap sets, move all rules in a set to another 268one, delete all rules in a set. 269These can be useful to 270install temporary configurations, or to test them. 271See Section 272.Sx SETS OF RULES 273for more information on 274.Em sets . 275.Pp 276Rules can be added with the 277.Cm add 278command; deleted individually or in groups with the 279.Cm delete 280command, and globally (except those in set 31) with the 281.Cm flush 282command; displayed, optionally with the content of the 283counters, using the 284.Cm show 285and 286.Cm list 287commands. 288Finally, counters can be reset with the 289.Cm zero 290and 291.Cm resetlog 292commands. 293.Pp 294.Ss COMMAND OPTIONS 295The following general options are available when invoking 296.Nm : 297.Bl -tag -width indent 298.It Fl a 299Show counter values when listing rules. 300The 301.Cm show 302command implies this option. 303.It Fl b 304Only show the action and the comment, not the body of a rule. 305Implies 306.Fl c . 307.It Fl c 308When entering or showing rules, print them in compact form, 309i.e., omitting the "ip from any to any" string 310when this does not carry any additional information. 311.It Fl d 312When listing, show dynamic rules in addition to static ones. 313.It Fl D 314When listing, show only dynamic states. 315When deleting, delete only dynamic states. 316.It Fl f 317Run without prompting for confirmation for commands that can cause problems if misused, 318i.e., 319.Cm flush . 320If there is no tty associated with the process, this is implied. 321The 322.Cm delete 323command with this flag ignores possible errors, 324i.e., nonexistent rule number. 325And for batched commands execution continues with the next command. 326.It Fl i 327When listing a table (see the 328.Sx LOOKUP TABLES 329section below for more information on lookup tables), format values 330as IP addresses. 331By default, values are shown as integers. 332.It Fl n 333Only check syntax of the command strings, without actually passing 334them to the kernel. 335.It Fl N 336Try to resolve addresses and service names in output. 337.It Fl q 338Be quiet when executing the 339.Cm add , 340.Cm nat , 341.Cm zero , 342.Cm resetlog 343or 344.Cm flush 345commands; 346(implies 347.Fl f ) . 348This is useful when updating rulesets by executing multiple 349.Nm 350commands in a script 351(e.g., 352.Ql sh\ /etc/rc.firewall ) , 353or by processing a file with many 354.Nm 355rules across a remote login session. 356It also stops a table add or delete 357from failing if the entry already exists or is not present. 358.Pp 359The reason why this option may be important is that 360for some of these actions, 361.Nm 362may print a message; if the action results in blocking the 363traffic to the remote client, 364the remote login session will be closed 365and the rest of the ruleset will not be processed. 366Access to the console would then be required to recover. 367.It Fl S 368When listing rules, show the 369.Em set 370each rule belongs to. 371If this flag is not specified, disabled rules will not be 372listed. 373.It Fl s Op Ar field 374When listing pipes, sort according to one of the four 375counters (total or current packets or bytes). 376.It Fl t 377When listing, show last match timestamp converted with ctime(). 378.It Fl T 379When listing, show last match timestamp as seconds from the epoch. 380This form can be more convenient for postprocessing by scripts. 381.El 382.Ss LIST OF RULES AND PREPROCESSING 383To ease configuration, rules can be put into a file which is 384processed using 385.Nm 386as shown in the last synopsis line. 387An absolute 388.Ar pathname 389must be used. 390The file will be read line by line and applied as arguments to the 391.Nm 392utility. 393.Pp 394Optionally, a preprocessor can be specified using 395.Fl p Ar preproc 396where 397.Ar pathname 398is to be piped through. 399Useful preprocessors include 400.Xr cpp 1 401and 402.Xr m4 1 . 403If 404.Ar preproc 405does not start with a slash 406.Pq Ql / 407as its first character, the usual 408.Ev PATH 409name search is performed. 410Care should be taken with this in environments where not all 411file systems are mounted (yet) by the time 412.Nm 413is being run (e.g.\& when they are mounted over NFS). 414Once 415.Fl p 416has been specified, any additional arguments are passed on to the preprocessor 417for interpretation. 418This allows for flexible configuration files (like conditionalizing 419them on the local hostname) and the use of macros to centralize 420frequently required arguments like IP addresses. 421.Ss TRAFFIC SHAPER CONFIGURATION 422The 423.Nm 424.Cm pipe , queue 425and 426.Cm sched 427commands are used to configure the traffic shaper and packet scheduler. 428See the 429.Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION 430Section below for details. 431.Pp 432If the world and the kernel get out of sync the 433.Nm 434ABI may break, preventing you from being able to add any rules. 435This can adversely affect the booting process. 436You can use 437.Nm 438.Cm disable 439.Cm firewall 440to temporarily disable the firewall to regain access to the network, 441allowing you to fix the problem. 442.Sh PACKET FLOW 443A packet is checked against the active ruleset in multiple places 444in the protocol stack, under control of several sysctl variables. 445These places and variables are shown below, and it is important to 446have this picture in mind in order to design a correct ruleset. 447.Bd -literal -offset indent 448 ^ to upper layers V 449 | | 450 +----------->-----------+ 451 ^ V 452 [ip(6)_input] [ip(6)_output] net.inet(6).ip(6).fw.enable=1 453 | | 454 ^ V 455 [ether_demux] [ether_output_frame] net.link.ether.ipfw=1 456 | | 457 +-->--[bdg_forward]-->--+ net.link.bridge.ipfw=1 458 ^ V 459 | to devices | 460.Ed 461.Pp 462The number of 463times the same packet goes through the firewall can 464vary between 0 and 4 depending on packet source and 465destination, and system configuration. 466.Pp 467Note that as packets flow through the stack, headers can be 468stripped or added to it, and so they may or may not be available 469for inspection. 470E.g., incoming packets will include the MAC header when 471.Nm 472is invoked from 473.Cm ether_demux() , 474but the same packets will have the MAC header stripped off when 475.Nm 476is invoked from 477.Cm ip_input() 478or 479.Cm ip6_input() . 480.Pp 481Also note that each packet is always checked against the complete ruleset, 482irrespective of the place where the check occurs, or the source of the packet. 483If a rule contains some match patterns or actions which are not valid 484for the place of invocation (e.g.\& trying to match a MAC header within 485.Cm ip_input 486or 487.Cm ip6_input ), 488the match pattern will not match, but a 489.Cm not 490operator in front of such patterns 491.Em will 492cause the pattern to 493.Em always 494match on those packets. 495It is thus the responsibility of 496the programmer, if necessary, to write a suitable ruleset to 497differentiate among the possible places. 498.Cm skipto 499rules can be useful here, as an example: 500.Bd -literal -offset indent 501# packets from ether_demux or bdg_forward 502ipfw add 10 skipto 1000 all from any to any layer2 in 503# packets from ip_input 504ipfw add 10 skipto 2000 all from any to any not layer2 in 505# packets from ip_output 506ipfw add 10 skipto 3000 all from any to any not layer2 out 507# packets from ether_output_frame 508ipfw add 10 skipto 4000 all from any to any layer2 out 509.Ed 510.Pp 511(yes, at the moment there is no way to differentiate between 512ether_demux and bdg_forward). 513.Pp 514Also note that only actions 515.Cm allow, 516.Cm deny, 517.Cm netgraph, 518.Cm ngtee 519and related to 520.Cm dummynet 521are processed for 522.Cm layer2 523frames and all other actions act as if they were 524.Cm allow 525for such frames. 526Full set of actions is supported for IP packets without 527.Cm layer2 528headers only. 529For example, 530.Cm divert 531action does not divert 532.Cm layer2 533frames. 534.Sh SYNTAX 535In general, each keyword or argument must be provided as 536a separate command line argument, with no leading or trailing 537spaces. 538Keywords are case-sensitive, whereas arguments may 539or may not be case-sensitive depending on their nature 540(e.g.\& uid's are, hostnames are not). 541.Pp 542Some arguments (e.g., port or address lists) are comma-separated 543lists of values. 544In this case, spaces after commas ',' are allowed to make 545the line more readable. 546You can also put the entire 547command (including flags) into a single argument. 548E.g., the following forms are equivalent: 549.Bd -literal -offset indent 550ipfw -q add deny src-ip 10.0.0.0/24,127.0.0.1/8 551ipfw -q add deny src-ip 10.0.0.0/24, 127.0.0.1/8 552ipfw "-q add deny src-ip 10.0.0.0/24, 127.0.0.1/8" 553.Ed 554.Sh RULE FORMAT 555The format of firewall rules is the following: 556.Bd -ragged -offset indent 557.Bk -words 558.Op Ar rule_number 559.Op Cm set Ar set_number 560.Op Cm prob Ar match_probability 561.Ar action 562.Op Cm log Op Cm logamount Ar number 563.Op Cm altq Ar queue 564.Oo 565.Bro Cm tag | untag 566.Brc Ar number 567.Oc 568.Ar body 569.Ek 570.Ed 571.Pp 572where the body of the rule specifies which information is used 573for filtering packets, among the following: 574.Pp 575.Bl -tag -width "Source and dest. addresses and ports" -offset XXX -compact 576.It Layer-2 header fields 577When available 578.It IPv4 and IPv6 Protocol 579SCTP, TCP, UDP, ICMP, etc. 580.It Source and dest. addresses and ports 581.It Direction 582See Section 583.Sx PACKET FLOW 584.It Transmit and receive interface 585By name or address 586.It Misc. IP header fields 587Version, type of service, datagram length, identification, 588fragment flag (non-zero IP offset), 589Time To Live 590.It IP options 591.It IPv6 Extension headers 592Fragmentation, Hop-by-Hop options, 593Routing Headers, Source routing rthdr0, Mobile IPv6 rthdr2, IPSec options. 594.It IPv6 Flow-ID 595.It Misc. TCP header fields 596TCP flags (SYN, FIN, ACK, RST, etc.), 597sequence number, acknowledgment number, 598window 599.It TCP options 600.It ICMP types 601for ICMP packets 602.It ICMP6 types 603for ICMP6 packets 604.It User/group ID 605When the packet can be associated with a local socket. 606.It Divert status 607Whether a packet came from a divert socket (e.g., 608.Xr natd 8 ) . 609.It Fib annotation state 610Whether a packet has been tagged for using a specific FIB (routing table) 611in future forwarding decisions. 612.El 613.Pp 614Note that some of the above information, e.g.\& source MAC or IP addresses and 615TCP/UDP ports, can be easily spoofed, so filtering on those fields 616alone might not guarantee the desired results. 617.Bl -tag -width indent 618.It Ar rule_number 619Each rule is associated with a 620.Ar rule_number 621in the range 1..65535, with the latter reserved for the 622.Em default 623rule. 624Rules are checked sequentially by rule number. 625Multiple rules can have the same number, in which case they are 626checked (and listed) according to the order in which they have 627been added. 628If a rule is entered without specifying a number, the kernel will 629assign one in such a way that the rule becomes the last one 630before the 631.Em default 632rule. 633Automatic rule numbers are assigned by incrementing the last 634non-default rule number by the value of the sysctl variable 635.Ar net.inet.ip.fw.autoinc_step 636which defaults to 100. 637If this is not possible (e.g.\& because we would go beyond the 638maximum allowed rule number), the number of the last 639non-default value is used instead. 640.It Cm set Ar set_number 641Each rule is associated with a 642.Ar set_number 643in the range 0..31. 644Sets can be individually disabled and enabled, so this parameter 645is of fundamental importance for atomic ruleset manipulation. 646It can be also used to simplify deletion of groups of rules. 647If a rule is entered without specifying a set number, 648set 0 will be used. 649.br 650Set 31 is special in that it cannot be disabled, 651and rules in set 31 are not deleted by the 652.Nm ipfw flush 653command (but you can delete them with the 654.Nm ipfw delete set 31 655command). 656Set 31 is also used for the 657.Em default 658rule. 659.It Cm prob Ar match_probability 660A match is only declared with the specified probability 661(floating point number between 0 and 1). 662This can be useful for a number of applications such as 663random packet drop or 664(in conjunction with 665.Nm dummynet ) 666to simulate the effect of multiple paths leading to out-of-order 667packet delivery. 668.Pp 669Note: this condition is checked before any other condition, including 670ones such as 671.Cm keep-state 672or 673.Cm check-state 674which might have 675side effects. 676.It Cm log Op Cm logamount Ar number 677Packets matching a rule with the 678.Cm log 679keyword will be made available for logging in two ways: 680if the sysctl variable 681.Va net.inet.ip.fw.verbose 682is set to 0 (default), one can use 683.Xr bpf 4 684attached to the 685.Li ipfw0 686pseudo interface. 687This pseudo interface can be created manually after a system 688boot by using the following command: 689.Bd -literal -offset indent 690# ifconfig ipfw0 create 691.Ed 692.Pp 693Or, automatically at boot time by adding the following 694line to the 695.Xr rc.conf 5 696file: 697.Bd -literal -offset indent 698firewall_logif="YES" 699.Ed 700.Pp 701There is zero overhead when no 702.Xr bpf 4 703is attached to the pseudo interface. 704.Pp 705If 706.Va net.inet.ip.fw.verbose 707is set to 1, packets will be logged to 708.Xr syslogd 8 709with a 710.Dv LOG_SECURITY 711facility up to a maximum of 712.Cm logamount 713packets. 714If no 715.Cm logamount 716is specified, the limit is taken from the sysctl variable 717.Va net.inet.ip.fw.verbose_limit . 718In both cases, a value of 0 means unlimited logging. 719.Pp 720Once the limit is reached, logging can be re-enabled by 721clearing the logging counter or the packet counter for that entry, see the 722.Cm resetlog 723command. 724.Pp 725Note: logging is done after all other packet matching conditions 726have been successfully verified, and before performing the final 727action (accept, deny, etc.) on the packet. 728.It Cm tag Ar number 729When a packet matches a rule with the 730.Cm tag 731keyword, the numeric tag for the given 732.Ar number 733in the range 1..65534 will be attached to the packet. 734The tag acts as an internal marker (it is not sent out over 735the wire) that can be used to identify these packets later on. 736This can be used, for example, to provide trust between interfaces 737and to start doing policy-based filtering. 738A packet can have multiple tags at the same time. 739Tags are "sticky", meaning once a tag is applied to a packet by a 740matching rule it exists until explicit removal. 741Tags are kept with the packet everywhere within the kernel, but are 742lost when packet leaves the kernel, for example, on transmitting 743packet out to the network or sending packet to a 744.Xr divert 4 745socket. 746.Pp 747To check for previously applied tags, use the 748.Cm tagged 749rule option. 750To delete previously applied tag, use the 751.Cm untag 752keyword. 753.Pp 754Note: since tags are kept with the packet everywhere in kernelspace, 755they can be set and unset anywhere in the kernel network subsystem 756(using the 757.Xr mbuf_tags 9 758facility), not only by means of the 759.Xr ipfw 4 760.Cm tag 761and 762.Cm untag 763keywords. 764For example, there can be a specialized 765.Xr netgraph 4 766node doing traffic analyzing and tagging for later inspecting 767in firewall. 768.It Cm untag Ar number 769When a packet matches a rule with the 770.Cm untag 771keyword, the tag with the number 772.Ar number 773is searched among the tags attached to this packet and, 774if found, removed from it. 775Other tags bound to packet, if present, are left untouched. 776.It Cm altq Ar queue 777When a packet matches a rule with the 778.Cm altq 779keyword, the ALTQ identifier for the given 780.Ar queue 781(see 782.Xr altq 4 ) 783will be attached. 784Note that this ALTQ tag is only meaningful for packets going "out" of IPFW, 785and not being rejected or going to divert sockets. 786Note that if there is insufficient memory at the time the packet is 787processed, it will not be tagged, so it is wise to make your ALTQ 788"default" queue policy account for this. 789If multiple 790.Cm altq 791rules match a single packet, only the first one adds the ALTQ classification 792tag. 793In doing so, traffic may be shaped by using 794.Cm count Cm altq Ar queue 795rules for classification early in the ruleset, then later applying 796the filtering decision. 797For example, 798.Cm check-state 799and 800.Cm keep-state 801rules may come later and provide the actual filtering decisions in 802addition to the fallback ALTQ tag. 803.Pp 804You must run 805.Xr pfctl 8 806to set up the queues before IPFW will be able to look them up by name, 807and if the ALTQ disciplines are rearranged, the rules in containing the 808queue identifiers in the kernel will likely have gone stale and need 809to be reloaded. 810Stale queue identifiers will probably result in misclassification. 811.Pp 812All system ALTQ processing can be turned on or off via 813.Nm 814.Cm enable Ar altq 815and 816.Nm 817.Cm disable Ar altq . 818The usage of 819.Va net.inet.ip.fw.one_pass 820is irrelevant to ALTQ traffic shaping, as the actual rule action is followed 821always after adding an ALTQ tag. 822.El 823.Ss RULE ACTIONS 824A rule can be associated with one of the following actions, which 825will be executed when the packet matches the body of the rule. 826.Bl -tag -width indent 827.It Cm allow | accept | pass | permit 828Allow packets that match rule. 829The search terminates. 830.It Cm check-state Op Ar :flowname | Cm :any 831Checks the packet against the dynamic ruleset. 832If a match is found, execute the action associated with 833the rule which generated this dynamic rule, otherwise 834move to the next rule. 835.br 836.Cm Check-state 837rules do not have a body. 838If no 839.Cm check-state 840rule is found, the dynamic ruleset is checked at the first 841.Cm keep-state 842or 843.Cm limit 844rule. 845The 846.Ar :flowname 847is symbolic name assigned to dynamic rule by 848.Cm keep-state 849opcode. 850The special flowname 851.Cm :any 852can be used to ignore states flowname when matching. 853The 854.Cm :default 855keyword is special name used for compatibility with old rulesets. 856.It Cm count 857Update counters for all packets that match rule. 858The search continues with the next rule. 859.It Cm deny | drop 860Discard packets that match this rule. 861The search terminates. 862.It Cm divert Ar port 863Divert packets that match this rule to the 864.Xr divert 4 865socket bound to port 866.Ar port . 867The search terminates. 868.It Cm fwd | forward Ar ipaddr | tablearg Ns Op , Ns Ar port 869Change the next-hop on matching packets to 870.Ar ipaddr , 871which can be an IP address or a host name. 872The next hop can also be supplied by the last table 873looked up for the packet by using the 874.Cm tablearg 875keyword instead of an explicit address. 876The search terminates if this rule matches. 877.Pp 878If 879.Ar ipaddr 880is a local address, then matching packets will be forwarded to 881.Ar port 882(or the port number in the packet if one is not specified in the rule) 883on the local machine. 884.br 885If 886.Ar ipaddr 887is not a local address, then the port number 888(if specified) is ignored, and the packet will be 889forwarded to the remote address, using the route as found in 890the local routing table for that IP. 891.br 892A 893.Ar fwd 894rule will not match layer-2 packets (those received 895on ether_input, ether_output, or bridged). 896.br 897The 898.Cm fwd 899action does not change the contents of the packet at all. 900In particular, the destination address remains unmodified, so 901packets forwarded to another system will usually be rejected by that system 902unless there is a matching rule on that system to capture them. 903For packets forwarded locally, 904the local address of the socket will be 905set to the original destination address of the packet. 906This makes the 907.Xr netstat 1 908entry look rather weird but is intended for 909use with transparent proxy servers. 910.It Cm nat Ar nat_nr | tablearg 911Pass packet to a 912nat instance 913(for network address translation, address redirect, etc.): 914see the 915.Sx NETWORK ADDRESS TRANSLATION (NAT) 916Section for further information. 917.It Cm nat64lsn Ar name 918Pass packet to a stateful NAT64 instance (for IPv6/IPv4 network address and 919protocol translation): see the 920.Sx IPv6/IPv4 NETWORK ADDRESS AND PROTOCOL TRANSLATION 921Section for further information. 922.It Cm nat64stl Ar name 923Pass packet to a stateless NAT64 instance (for IPv6/IPv4 network address and 924protocol translation): see the 925.Sx IPv6/IPv4 NETWORK ADDRESS AND PROTOCOL TRANSLATION 926Section for further information. 927.It Cm nptv6 Ar name 928Pass packet to a NPTv6 instance (for IPv6-to-IPv6 network prefix translation): 929see the 930.Sx IPv6-to-IPv6 NETWORK PREFIX TRANSLATION (NPTv6) 931Section for further information. 932.It Cm pipe Ar pipe_nr 933Pass packet to a 934.Nm dummynet 935.Dq pipe 936(for bandwidth limitation, delay, etc.). 937See the 938.Sx TRAFFIC SHAPER (DUMMYNET) CONFIGURATION 939Section for further information. 940The search terminates; however, on exit from the pipe and if 941the 942.Xr sysctl 8 943variable 944.Va net.inet.ip.fw.one_pass 945is not set, the packet is passed again to the firewall code 946starting from the next rule. 947.It Cm queue Ar queue_nr 948Pass packet to a 949.Nm dummynet 950.Dq queue 951(for bandwidth limitation using WF2Q+). 952.It Cm reject 953(Deprecated). 954Synonym for 955.Cm unreach host . 956.It Cm reset 957Discard packets that match this rule, and if the 958packet is a TCP packet, try to send a TCP reset (RST) notice. 959The search terminates. 960.It Cm reset6 961Discard packets that match this rule, and if the 962packet is a TCP packet, try to send a TCP reset (RST) notice. 963The search terminates. 964.It Cm skipto Ar number | tablearg 965Skip all subsequent rules numbered less than 966.Ar number . 967The search continues with the first rule numbered 968.Ar number 969or higher. 970It is possible to use the 971.Cm tablearg 972keyword with a skipto for a 973.Em computed 974skipto. Skipto may work either in O(log(N)) or in O(1) depending 975on amount of memory and/or sysctl variables. 976See the 977.Sx SYSCTL VARIABLES 978section for more details. 979.It Cm call Ar number | tablearg 980The current rule number is saved in the internal stack and 981ruleset processing continues with the first rule numbered 982.Ar number 983or higher. 984If later a rule with the 985.Cm return 986action is encountered, the processing returns to the first rule 987with number of this 988.Cm call 989rule plus one or higher 990(the same behaviour as with packets returning from 991.Xr divert 4 992socket after a 993.Cm divert 994action). 995This could be used to make somewhat like an assembly language 996.Dq subroutine 997calls to rules with common checks for different interfaces, etc. 998.Pp 999Rule with any number could be called, not just forward jumps as with 1000.Cm skipto . 1001So, to prevent endless loops in case of mistakes, both 1002.Cm call 1003and 1004.Cm return 1005actions don't do any jumps and simply go to the next rule if memory 1006cannot be allocated or stack overflowed/underflowed. 1007.Pp 1008Internally stack for rule numbers is implemented using 1009.Xr mbuf_tags 9 1010facility and currently has size of 16 entries. 1011As mbuf tags are lost when packet leaves the kernel, 1012.Cm divert 1013should not be used in subroutines to avoid endless loops 1014and other undesired effects. 1015.It Cm return 1016Takes rule number saved to internal stack by the last 1017.Cm call 1018action and returns ruleset processing to the first rule 1019with number greater than number of corresponding 1020.Cm call 1021rule. 1022See description of the 1023.Cm call 1024action for more details. 1025.Pp 1026Note that 1027.Cm return 1028rules usually end a 1029.Dq subroutine 1030and thus are unconditional, but 1031.Nm 1032command-line utility currently requires every action except 1033.Cm check-state 1034to have body. 1035While it is sometimes useful to return only on some packets, 1036usually you want to print just 1037.Dq return 1038for readability. 1039A workaround for this is to use new syntax and 1040.Fl c 1041switch: 1042.Bd -literal -offset indent 1043# Add a rule without actual body 1044ipfw add 2999 return via any 1045 1046# List rules without "from any to any" part 1047ipfw -c list 1048.Ed 1049.Pp 1050This cosmetic annoyance may be fixed in future releases. 1051.It Cm tee Ar port 1052Send a copy of packets matching this rule to the 1053.Xr divert 4 1054socket bound to port 1055.Ar port . 1056The search continues with the next rule. 1057.It Cm unreach Ar code 1058Discard packets that match this rule, and try to send an ICMP 1059unreachable notice with code 1060.Ar code , 1061where 1062.Ar code 1063is a number from 0 to 255, or one of these aliases: 1064.Cm net , host , protocol , port , 1065.Cm needfrag , srcfail , net-unknown , host-unknown , 1066.Cm isolated , net-prohib , host-prohib , tosnet , 1067.Cm toshost , filter-prohib , host-precedence 1068or 1069.Cm precedence-cutoff . 1070The search terminates. 1071.It Cm unreach6 Ar code 1072Discard packets that match this rule, and try to send an ICMPv6 1073unreachable notice with code 1074.Ar code , 1075where 1076.Ar code 1077is a number from 0, 1, 3 or 4, or one of these aliases: 1078.Cm no-route, admin-prohib, address 1079or 1080.Cm port . 1081The search terminates. 1082.It Cm netgraph Ar cookie 1083Divert packet into netgraph with given 1084.Ar cookie . 1085The search terminates. 1086If packet is later returned from netgraph it is either 1087accepted or continues with the next rule, depending on 1088.Va net.inet.ip.fw.one_pass 1089sysctl variable. 1090.It Cm ngtee Ar cookie 1091A copy of packet is diverted into netgraph, original 1092packet continues with the next rule. 1093See 1094.Xr ng_ipfw 4 1095for more information on 1096.Cm netgraph 1097and 1098.Cm ngtee 1099actions. 1100.It Cm setfib Ar fibnum | tablearg 1101The packet is tagged so as to use the FIB (routing table) 1102.Ar fibnum 1103in any subsequent forwarding decisions. 1104In the current implementation, this is limited to the values 0 through 15, see 1105.Xr setfib 2 . 1106Processing continues at the next rule. 1107It is possible to use the 1108.Cm tablearg 1109keyword with setfib. 1110If the tablearg value is not within the compiled range of fibs, 1111the packet's fib is set to 0. 1112.It Cm setdscp Ar DSCP | number | tablearg 1113Set specified DiffServ codepoint for an IPv4/IPv6 packet. 1114Processing continues at the next rule. 1115Supported values are: 1116.Pp 1117.Cm cs0 1118.Pq Dv 000000 , 1119.Cm cs1 1120.Pq Dv 001000 , 1121.Cm cs2 1122.Pq Dv 010000 , 1123.Cm cs3 1124.Pq Dv 011000 , 1125.Cm cs4 1126.Pq Dv 100000 , 1127.Cm cs5 1128.Pq Dv 101000 , 1129.Cm cs6 1130.Pq Dv 110000 , 1131.Cm cs7 1132.Pq Dv 111000 , 1133.Cm af11 1134.Pq Dv 001010 , 1135.Cm af12 1136.Pq Dv 001100 , 1137.Cm af13 1138.Pq Dv 001110 , 1139.Cm af21 1140.Pq Dv 010010 , 1141.Cm af22 1142.Pq Dv 010100 , 1143.Cm af23 1144.Pq Dv 010110 , 1145.Cm af31 1146.Pq Dv 011010 , 1147.Cm af32 1148.Pq Dv 011100 , 1149.Cm af33 1150.Pq Dv 011110 , 1151.Cm af41 1152.Pq Dv 100010 , 1153.Cm af42 1154.Pq Dv 100100 , 1155.Cm af43 1156.Pq Dv 100110 , 1157.Cm ef 1158.Pq Dv 101110 , 1159.Cm be 1160.Pq Dv 000000 . 1161Additionally, DSCP value can be specified by number (0..63). 1162It is also possible to use the 1163.Cm tablearg 1164keyword with setdscp. 1165If the tablearg value is not within the 0..63 range, lower 6 bits of supplied 1166value are used. 1167.It Cm tcp-setmss Ar mss 1168Set the Maximum Segment Size (MSS) in the TCP segment to value 1169.Ar mss . 1170The kernel module 1171.Cm ipfw_pmod 1172should be loaded or kernel should have 1173.Cm options IPFIREWALL_PMOD 1174to be able use this action. 1175This command does not change a packet if original MSS value is lower than 1176specified value. 1177Both TCP over IPv4 and over IPv6 are supported. 1178Regardless of matched a packet or not by the 1179.Cm tcp-setmss 1180rule, the search continues with the next rule. 1181.It Cm reass 1182Queue and reassemble IPv4 fragments. 1183If the packet is not fragmented, counters are updated and 1184processing continues with the next rule. 1185If the packet is the last logical fragment, the packet is reassembled and, if 1186.Va net.inet.ip.fw.one_pass 1187is set to 0, processing continues with the next rule. 1188Otherwise, the packet is allowed to pass and the search terminates. 1189If the packet is a fragment in the middle of a logical group of fragments, 1190it is consumed and 1191processing stops immediately. 1192.Pp 1193Fragment handling can be tuned via 1194.Va net.inet.ip.maxfragpackets 1195and 1196.Va net.inet.ip.maxfragsperpacket 1197which limit, respectively, the maximum number of processable 1198fragments (default: 800) and 1199the maximum number of fragments per packet (default: 16). 1200.Pp 1201NOTA BENE: since fragments do not contain port numbers, 1202they should be avoided with the 1203.Nm reass 1204rule. 1205Alternatively, direction-based (like 1206.Nm in 1207/ 1208.Nm out 1209) and source-based (like 1210.Nm via 1211) match patterns can be used to select fragments. 1212.Pp 1213Usually a simple rule like: 1214.Bd -literal -offset indent 1215# reassemble incoming fragments 1216ipfw add reass all from any to any in 1217.Ed 1218.Pp 1219is all you need at the beginning of your ruleset. 1220.It Cm abort 1221Discard packets that match this rule, and if the packet is an SCTP packet, 1222try to send an SCTP packet containing an ABORT chunk. 1223The search terminates. 1224.It Cm abort6 1225Discard packets that match this rule, and if the packet is an SCTP packet, 1226try to send an SCTP packet containing an ABORT chunk. 1227The search terminates. 1228.El 1229.Ss RULE BODY 1230The body of a rule contains zero or more patterns (such as 1231specific source and destination addresses or ports, 1232protocol options, incoming or outgoing interfaces, etc.) 1233that the packet must match in order to be recognised. 1234In general, the patterns are connected by (implicit) 1235.Cm and 1236operators -- i.e., all must match in order for the 1237rule to match. 1238Individual patterns can be prefixed by the 1239.Cm not 1240operator to reverse the result of the match, as in 1241.Pp 1242.Dl "ipfw add 100 allow ip from not 1.2.3.4 to any" 1243.Pp 1244Additionally, sets of alternative match patterns 1245.Pq Em or-blocks 1246can be constructed by putting the patterns in 1247lists enclosed between parentheses ( ) or braces { }, and 1248using the 1249.Cm or 1250operator as follows: 1251.Pp 1252.Dl "ipfw add 100 allow ip from { x or not y or z } to any" 1253.Pp 1254Only one level of parentheses is allowed. 1255Beware that most shells have special meanings for parentheses 1256or braces, so it is advisable to put a backslash \\ in front of them 1257to prevent such interpretations. 1258.Pp 1259The body of a rule must in general include a source and destination 1260address specifier. 1261The keyword 1262.Ar any 1263can be used in various places to specify that the content of 1264a required field is irrelevant. 1265.Pp 1266The rule body has the following format: 1267.Bd -ragged -offset indent 1268.Op Ar proto Cm from Ar src Cm to Ar dst 1269.Op Ar options 1270.Ed 1271.Pp 1272The first part (proto from src to dst) is for backward 1273compatibility with earlier versions of 1274.Fx . 1275In modern 1276.Fx 1277any match pattern (including MAC headers, IP protocols, 1278addresses and ports) can be specified in the 1279.Ar options 1280section. 1281.Pp 1282Rule fields have the following meaning: 1283.Bl -tag -width indent 1284.It Ar proto : protocol | Cm { Ar protocol Cm or ... } 1285.It Ar protocol : Oo Cm not Oc Ar protocol-name | protocol-number 1286An IP protocol specified by number or name 1287(for a complete list see 1288.Pa /etc/protocols ) , 1289or one of the following keywords: 1290.Bl -tag -width indent 1291.It Cm ip4 | ipv4 1292Matches IPv4 packets. 1293.It Cm ip6 | ipv6 1294Matches IPv6 packets. 1295.It Cm ip | all 1296Matches any packet. 1297.El 1298.Pp 1299The 1300.Cm ipv6 1301in 1302.Cm proto 1303option will be treated as inner protocol. 1304And, the 1305.Cm ipv4 1306is not available in 1307.Cm proto 1308option. 1309.Pp 1310The 1311.Cm { Ar protocol Cm or ... } 1312format (an 1313.Em or-block ) 1314is provided for convenience only but its use is deprecated. 1315.It Ar src No and Ar dst : Bro Cm addr | Cm { Ar addr Cm or ... } Brc Op Oo Cm not Oc Ar ports 1316An address (or a list, see below) 1317optionally followed by 1318.Ar ports 1319specifiers. 1320.Pp 1321The second format 1322.Em ( or-block 1323with multiple addresses) is provided for convenience only and 1324its use is discouraged. 1325.It Ar addr : Oo Cm not Oc Bro 1326.Cm any | me | me6 | 1327.Cm table Ns Pq Ar name Ns Op , Ns Ar value 1328.Ar | addr-list | addr-set 1329.Brc 1330.Bl -tag -width indent 1331.It Cm any 1332Matches any IP address. 1333.It Cm me 1334Matches any IP address configured on an interface in the system. 1335.It Cm me6 1336Matches any IPv6 address configured on an interface in the system. 1337The address list is evaluated at the time the packet is 1338analysed. 1339.It Cm table Ns Pq Ar name Ns Op , Ns Ar value 1340Matches any IPv4 or IPv6 address for which an entry exists in the lookup table 1341.Ar number . 1342If an optional 32-bit unsigned 1343.Ar value 1344is also specified, an entry will match only if it has this value. 1345See the 1346.Sx LOOKUP TABLES 1347section below for more information on lookup tables. 1348.El 1349.It Ar addr-list : ip-addr Ns Op Ns , Ns Ar addr-list 1350.It Ar ip-addr : 1351A host or subnet address specified in one of the following ways: 1352.Bl -tag -width indent 1353.It Ar numeric-ip | hostname 1354Matches a single IPv4 address, specified as dotted-quad or a hostname. 1355Hostnames are resolved at the time the rule is added to the firewall list. 1356.It Ar addr Ns / Ns Ar masklen 1357Matches all addresses with base 1358.Ar addr 1359(specified as an IP address, a network number, or a hostname) 1360and mask width of 1361.Cm masklen 1362bits. 1363As an example, 1.2.3.4/25 or 1.2.3.0/25 will match 1364all IP numbers from 1.2.3.0 to 1.2.3.127 . 1365.It Ar addr Ns : Ns Ar mask 1366Matches all addresses with base 1367.Ar addr 1368(specified as an IP address, a network number, or a hostname) 1369and the mask of 1370.Ar mask , 1371specified as a dotted quad. 1372As an example, 1.2.3.4:255.0.255.0 or 1.0.3.0:255.0.255.0 will match 13731.*.3.*. 1374This form is advised only for non-contiguous 1375masks. 1376It is better to resort to the 1377.Ar addr Ns / Ns Ar masklen 1378format for contiguous masks, which is more compact and less 1379error-prone. 1380.El 1381.It Ar addr-set : addr Ns Oo Ns / Ns Ar masklen Oc Ns Cm { Ns Ar list Ns Cm } 1382.It Ar list : Bro Ar num | num-num Brc Ns Op Ns , Ns Ar list 1383Matches all addresses with base address 1384.Ar addr 1385(specified as an IP address, a network number, or a hostname) 1386and whose last byte is in the list between braces { } . 1387Note that there must be no spaces between braces and 1388numbers (spaces after commas are allowed). 1389Elements of the list can be specified as single entries 1390or ranges. 1391The 1392.Ar masklen 1393field is used to limit the size of the set of addresses, 1394and can have any value between 24 and 32. 1395If not specified, 1396it will be assumed as 24. 1397.br 1398This format is particularly useful to handle sparse address sets 1399within a single rule. 1400Because the matching occurs using a 1401bitmask, it takes constant time and dramatically reduces 1402the complexity of rulesets. 1403.br 1404As an example, an address specified as 1.2.3.4/24{128,35-55,89} 1405or 1.2.3.0/24{128,35-55,89} 1406will match the following IP addresses: 1407.br 14081.2.3.128, 1.2.3.35 to 1.2.3.55, 1.2.3.89 . 1409.It Ar addr6-list : ip6-addr Ns Op Ns , Ns Ar addr6-list 1410.It Ar ip6-addr : 1411A host or subnet specified one of the following ways: 1412.Bl -tag -width indent 1413.It Ar numeric-ip | hostname 1414Matches a single IPv6 address as allowed by 1415.Xr inet_pton 3 1416or a hostname. 1417Hostnames are resolved at the time the rule is added to the firewall 1418list. 1419.It Ar addr Ns / Ns Ar masklen 1420Matches all IPv6 addresses with base 1421.Ar addr 1422(specified as allowed by 1423.Xr inet_pton 1424or a hostname) 1425and mask width of 1426.Cm masklen 1427bits. 1428.It Ar addr Ns / Ns Ar mask 1429Matches all IPv6 addresses with base 1430.Ar addr 1431(specified as allowed by 1432.Xr inet_pton 1433or a hostname) 1434and the mask of 1435.Ar mask , 1436specified as allowed by 1437.Xr inet_pton. 1438As an example, fe::640:0:0/ffff::ffff:ffff:0:0 will match 1439fe:*:*:*:0:640:*:*. 1440This form is advised only for non-contiguous 1441masks. 1442It is better to resort to the 1443.Ar addr Ns / Ns Ar masklen 1444format for contiguous masks, which is more compact and less 1445error-prone. 1446.El 1447.Pp 1448No support for sets of IPv6 addresses is provided because IPv6 addresses 1449are typically random past the initial prefix. 1450.It Ar ports : Bro Ar port | port Ns \&- Ns Ar port Ns Brc Ns Op , Ns Ar ports 1451For protocols which support port numbers (such as SCTP, TCP and UDP), optional 1452.Cm ports 1453may be specified as one or more ports or port ranges, separated 1454by commas but no spaces, and an optional 1455.Cm not 1456operator. 1457The 1458.Ql \&- 1459notation specifies a range of ports (including boundaries). 1460.Pp 1461Service names (from 1462.Pa /etc/services ) 1463may be used instead of numeric port values. 1464The length of the port list is limited to 30 ports or ranges, 1465though one can specify larger ranges by using an 1466.Em or-block 1467in the 1468.Cm options 1469section of the rule. 1470.Pp 1471A backslash 1472.Pq Ql \e 1473can be used to escape the dash 1474.Pq Ql - 1475character in a service name (from a shell, the backslash must be 1476typed twice to avoid the shell itself interpreting it as an escape 1477character). 1478.Pp 1479.Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any" 1480.Pp 1481Fragmented packets which have a non-zero offset (i.e., not the first 1482fragment) will never match a rule which has one or more port 1483specifications. 1484See the 1485.Cm frag 1486option for details on matching fragmented packets. 1487.El 1488.Ss RULE OPTIONS (MATCH PATTERNS) 1489Additional match patterns can be used within 1490rules. 1491Zero or more of these so-called 1492.Em options 1493can be present in a rule, optionally prefixed by the 1494.Cm not 1495operand, and possibly grouped into 1496.Em or-blocks . 1497.Pp 1498The following match patterns can be used (listed in alphabetical order): 1499.Bl -tag -width indent 1500.It Cm // this is a comment. 1501Inserts the specified text as a comment in the rule. 1502Everything following // is considered as a comment and stored in the rule. 1503You can have comment-only rules, which are listed as having a 1504.Cm count 1505action followed by the comment. 1506.It Cm bridged 1507Alias for 1508.Cm layer2 . 1509.It Cm defer-immediate-action | defer-action 1510A rule with this option will not perform normal action 1511upon a match. This option is intended to be used with 1512.Cm record-state 1513or 1514.Cm keep-state 1515as the dynamic rule, created but ignored on match, will work 1516as intended. 1517Rules with both 1518.Cm record-state 1519and 1520.Cm defer-immediate-action 1521create a dynamic rule and continue with the next rule without actually 1522performing the action part of this rule. When the rule is later activated 1523via the state table, the action is performed as usual. 1524.It Cm diverted 1525Matches only packets generated by a divert socket. 1526.It Cm diverted-loopback 1527Matches only packets coming from a divert socket back into the IP stack 1528input for delivery. 1529.It Cm diverted-output 1530Matches only packets going from a divert socket back outward to the IP 1531stack output for delivery. 1532.It Cm dst-ip Ar ip-address 1533Matches IPv4 packets whose destination IP is one of the address(es) 1534specified as argument. 1535.It Bro Cm dst-ip6 | dst-ipv6 Brc Ar ip6-address 1536Matches IPv6 packets whose destination IP is one of the address(es) 1537specified as argument. 1538.It Cm dst-port Ar ports 1539Matches IP packets whose destination port is one of the port(s) 1540specified as argument. 1541.It Cm established 1542Matches TCP packets that have the RST or ACK bits set. 1543.It Cm ext6hdr Ar header 1544Matches IPv6 packets containing the extended header given by 1545.Ar header . 1546Supported headers are: 1547.Pp 1548Fragment, 1549.Pq Cm frag , 1550Hop-to-hop options 1551.Pq Cm hopopt , 1552any type of Routing Header 1553.Pq Cm route , 1554Source routing Routing Header Type 0 1555.Pq Cm rthdr0 , 1556Mobile IPv6 Routing Header Type 2 1557.Pq Cm rthdr2 , 1558Destination options 1559.Pq Cm dstopt , 1560IPSec authentication headers 1561.Pq Cm ah , 1562and IPsec encapsulated security payload headers 1563.Pq Cm esp . 1564.It Cm fib Ar fibnum 1565Matches a packet that has been tagged to use 1566the given FIB (routing table) number. 1567.It Cm flow Ar table Ns Pq Ar name Ns Op , Ns Ar value 1568Search for the flow entry in lookup table 1569.Ar name . 1570If not found, the match fails. 1571Otherwise, the match succeeds and 1572.Cm tablearg 1573is set to the value extracted from the table. 1574.Pp 1575This option can be useful to quickly dispatch traffic based on 1576certain packet fields. 1577See the 1578.Sx LOOKUP TABLES 1579section below for more information on lookup tables. 1580.It Cm flow-id Ar labels 1581Matches IPv6 packets containing any of the flow labels given in 1582.Ar labels . 1583.Ar labels 1584is a comma separated list of numeric flow labels. 1585.It Cm frag 1586Matches packets that are fragments and not the first 1587fragment of an IP datagram. 1588Note that these packets will not have 1589the next protocol header (e.g.\& TCP, UDP) so options that look into 1590these headers cannot match. 1591.It Cm gid Ar group 1592Matches all TCP or UDP packets sent by or received for a 1593.Ar group . 1594A 1595.Ar group 1596may be specified by name or number. 1597.It Cm jail Ar jail 1598Matches all TCP or UDP packets sent by or received for the 1599jail whose ID or name is 1600.Ar jail . 1601.It Cm icmptypes Ar types 1602Matches ICMP packets whose ICMP type is in the list 1603.Ar types . 1604The list may be specified as any combination of 1605individual types (numeric) separated by commas. 1606.Em Ranges are not allowed . 1607The supported ICMP types are: 1608.Pp 1609echo reply 1610.Pq Cm 0 , 1611destination unreachable 1612.Pq Cm 3 , 1613source quench 1614.Pq Cm 4 , 1615redirect 1616.Pq Cm 5 , 1617echo request 1618.Pq Cm 8 , 1619router advertisement 1620.Pq Cm 9 , 1621router solicitation 1622.Pq Cm 10 , 1623time-to-live exceeded 1624.Pq Cm 11 , 1625IP header bad 1626.Pq Cm 12 , 1627timestamp request 1628.Pq Cm 13 , 1629timestamp reply 1630.Pq Cm 14 , 1631information request 1632.Pq Cm 15 , 1633information reply 1634.Pq Cm 16 , 1635address mask request 1636.Pq Cm 17 1637and address mask reply 1638.Pq Cm 18 . 1639.It Cm icmp6types Ar types 1640Matches ICMP6 packets whose ICMP6 type is in the list of 1641.Ar types . 1642The list may be specified as any combination of 1643individual types (numeric) separated by commas. 1644.Em Ranges are not allowed . 1645.It Cm in | out 1646Matches incoming or outgoing packets, respectively. 1647.Cm in 1648and 1649.Cm out 1650are mutually exclusive (in fact, 1651.Cm out 1652is implemented as 1653.Cm not in Ns No ). 1654.It Cm ipid Ar id-list 1655Matches IPv4 packets whose 1656.Cm ip_id 1657field has value included in 1658.Ar id-list , 1659which is either a single value or a list of values or ranges 1660specified in the same way as 1661.Ar ports . 1662.It Cm iplen Ar len-list 1663Matches IP packets whose total length, including header and data, is 1664in the set 1665.Ar len-list , 1666which is either a single value or a list of values or ranges 1667specified in the same way as 1668.Ar ports . 1669.It Cm ipoptions Ar spec 1670Matches packets whose IPv4 header contains the comma separated list of 1671options specified in 1672.Ar spec . 1673The supported IP options are: 1674.Pp 1675.Cm ssrr 1676(strict source route), 1677.Cm lsrr 1678(loose source route), 1679.Cm rr 1680(record packet route) and 1681.Cm ts 1682(timestamp). 1683The absence of a particular option may be denoted 1684with a 1685.Ql \&! . 1686.It Cm ipprecedence Ar precedence 1687Matches IPv4 packets whose precedence field is equal to 1688.Ar precedence . 1689.It Cm ipsec 1690Matches packets that have IPSEC history associated with them 1691(i.e., the packet comes encapsulated in IPSEC, the kernel 1692has IPSEC support, and can correctly decapsulate it). 1693.Pp 1694Note that specifying 1695.Cm ipsec 1696is different from specifying 1697.Cm proto Ar ipsec 1698as the latter will only look at the specific IP protocol field, 1699irrespective of IPSEC kernel support and the validity of the IPSEC data. 1700.Pp 1701Further note that this flag is silently ignored in kernels without 1702IPSEC support. 1703It does not affect rule processing when given and the 1704rules are handled as if with no 1705.Cm ipsec 1706flag. 1707.It Cm iptos Ar spec 1708Matches IPv4 packets whose 1709.Cm tos 1710field contains the comma separated list of 1711service types specified in 1712.Ar spec . 1713The supported IP types of service are: 1714.Pp 1715.Cm lowdelay 1716.Pq Dv IPTOS_LOWDELAY , 1717.Cm throughput 1718.Pq Dv IPTOS_THROUGHPUT , 1719.Cm reliability 1720.Pq Dv IPTOS_RELIABILITY , 1721.Cm mincost 1722.Pq Dv IPTOS_MINCOST , 1723.Cm congestion 1724.Pq Dv IPTOS_ECN_CE . 1725The absence of a particular type may be denoted 1726with a 1727.Ql \&! . 1728.It Cm dscp spec Ns Op , Ns Ar spec 1729Matches IPv4/IPv6 packets whose 1730.Cm DS 1731field value is contained in 1732.Ar spec 1733mask. 1734Multiple values can be specified via 1735the comma separated list. 1736Value can be one of keywords used in 1737.Cm setdscp 1738action or exact number. 1739.It Cm ipttl Ar ttl-list 1740Matches IPv4 packets whose time to live is included in 1741.Ar ttl-list , 1742which is either a single value or a list of values or ranges 1743specified in the same way as 1744.Ar ports . 1745.It Cm ipversion Ar ver 1746Matches IP packets whose IP version field is 1747.Ar ver . 1748.It Cm keep-state Op Ar :flowname 1749Upon a match, the firewall will create a dynamic rule, whose 1750default behaviour is to match bidirectional traffic between 1751source and destination IP/port using the same protocol. 1752The rule has a limited lifetime (controlled by a set of 1753.Xr sysctl 8 1754variables), and the lifetime is refreshed every time a matching 1755packet is found. 1756The 1757.Ar :flowname 1758is used to assign additional to addresses, ports and protocol parameter 1759to dynamic rule. It can be used for more accurate matching by 1760.Cm check-state 1761rule. 1762The 1763.Cm :default 1764keyword is special name used for compatibility with old rulesets. 1765.It Cm layer2 1766Matches only layer2 packets, i.e., those passed to 1767.Nm 1768from ether_demux() and ether_output_frame(). 1769.It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N Op Ar :flowname 1770The firewall will only allow 1771.Ar N 1772connections with the same 1773set of parameters as specified in the rule. 1774One or more 1775of source and destination addresses and ports can be 1776specified. 1777.It Cm lookup Bro Cm dst-ip | dst-port | src-ip | src-port | uid | jail Brc Ar name 1778Search an entry in lookup table 1779.Ar name 1780that matches the field specified as argument. 1781If not found, the match fails. 1782Otherwise, the match succeeds and 1783.Cm tablearg 1784is set to the value extracted from the table. 1785.Pp 1786This option can be useful to quickly dispatch traffic based on 1787certain packet fields. 1788See the 1789.Sx LOOKUP TABLES 1790section below for more information on lookup tables. 1791.It Cm { MAC | mac } Ar dst-mac src-mac 1792Match packets with a given 1793.Ar dst-mac 1794and 1795.Ar src-mac 1796addresses, specified as the 1797.Cm any 1798keyword (matching any MAC address), or six groups of hex digits 1799separated by colons, 1800and optionally followed by a mask indicating the significant bits. 1801The mask may be specified using either of the following methods: 1802.Bl -enum -width indent 1803.It 1804A slash 1805.Pq / 1806followed by the number of significant bits. 1807For example, an address with 33 significant bits could be specified as: 1808.Pp 1809.Dl "MAC 10:20:30:40:50:60/33 any" 1810.It 1811An ampersand 1812.Pq & 1813followed by a bitmask specified as six groups of hex digits separated 1814by colons. 1815For example, an address in which the last 16 bits are significant could 1816be specified as: 1817.Pp 1818.Dl "MAC 10:20:30:40:50:60&00:00:00:00:ff:ff any" 1819.Pp 1820Note that the ampersand character has a special meaning in many shells 1821and should generally be escaped. 1822.El 1823Note that the order of MAC addresses (destination first, 1824source second) is 1825the same as on the wire, but the opposite of the one used for 1826IP addresses. 1827.It Cm mac-type Ar mac-type 1828Matches packets whose Ethernet Type field 1829corresponds to one of those specified as argument. 1830.Ar mac-type 1831is specified in the same way as 1832.Cm port numbers 1833(i.e., one or more comma-separated single values or ranges). 1834You can use symbolic names for known values such as 1835.Em vlan , ipv4, ipv6 . 1836Values can be entered as decimal or hexadecimal (if prefixed by 0x), 1837and they are always printed as hexadecimal (unless the 1838.Cm -N 1839option is used, in which case symbolic resolution will be attempted). 1840.It Cm proto Ar protocol 1841Matches packets with the corresponding IP protocol. 1842.It Cm record-state 1843Upon a match, the firewall will create a dynamic rule as if 1844.Cm keep-state 1845was specified. 1846However, this option doesn't imply an implicit 1847.Cm check-state 1848in contrast to 1849.Cm keep-state . 1850.It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar table Ns Po Ar name Ns Oo , Ns Ar value Oc Pc | Ar ipno | Ar any 1851Matches packets received, transmitted or going through, 1852respectively, the interface specified by exact name 1853.Po Ar ifX Pc , 1854by device name 1855.Po Ar if* Pc , 1856by IP address, or through some interface. 1857Table 1858.Ar name 1859may be used to match interface by its kernel ifindex. 1860See the 1861.Sx LOOKUP TABLES 1862section below for more information on lookup tables. 1863.Pp 1864The 1865.Cm via 1866keyword causes the interface to always be checked. 1867If 1868.Cm recv 1869or 1870.Cm xmit 1871is used instead of 1872.Cm via , 1873then only the receive or transmit interface (respectively) 1874is checked. 1875By specifying both, it is possible to match packets based on 1876both receive and transmit interface, e.g.: 1877.Pp 1878.Dl "ipfw add deny ip from any to any out recv ed0 xmit ed1" 1879.Pp 1880The 1881.Cm recv 1882interface can be tested on either incoming or outgoing packets, 1883while the 1884.Cm xmit 1885interface can only be tested on outgoing packets. 1886So 1887.Cm out 1888is required (and 1889.Cm in 1890is invalid) whenever 1891.Cm xmit 1892is used. 1893.Pp 1894A packet might not have a receive or transmit interface: packets 1895originating from the local host have no receive interface, 1896while packets destined for the local host have no transmit 1897interface. 1898.It Cm set-limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N 1899Works like 1900.Cm limit 1901but does not have an implicit 1902.Cm check-state 1903attached to it. 1904.It Cm setup 1905Matches TCP packets that have the SYN bit set but no ACK bit. 1906This is the short form of 1907.Dq Li tcpflags\ syn,!ack . 1908.It Cm sockarg 1909Matches packets that are associated to a local socket and 1910for which the SO_USER_COOKIE socket option has been set 1911to a non-zero value. 1912As a side effect, the value of the 1913option is made available as 1914.Cm tablearg 1915value, which in turn can be used as 1916.Cm skipto 1917or 1918.Cm pipe 1919number. 1920.It Cm src-ip Ar ip-address 1921Matches IPv4 packets whose source IP is one of the address(es) 1922specified as an argument. 1923.It Cm src-ip6 Ar ip6-address 1924Matches IPv6 packets whose source IP is one of the address(es) 1925specified as an argument. 1926.It Cm src-port Ar ports 1927Matches IP packets whose source port is one of the port(s) 1928specified as argument. 1929.It Cm tagged Ar tag-list 1930Matches packets whose tags are included in 1931.Ar tag-list , 1932which is either a single value or a list of values or ranges 1933specified in the same way as 1934.Ar ports . 1935Tags can be applied to the packet using 1936.Cm tag 1937rule action parameter (see it's description for details on tags). 1938.It Cm tcpack Ar ack 1939TCP packets only. 1940Match if the TCP header acknowledgment number field is set to 1941.Ar ack . 1942.It Cm tcpdatalen Ar tcpdatalen-list 1943Matches TCP packets whose length of TCP data is 1944.Ar tcpdatalen-list , 1945which is either a single value or a list of values or ranges 1946specified in the same way as 1947.Ar ports . 1948.It Cm tcpflags Ar spec 1949TCP packets only. 1950Match if the TCP header contains the comma separated list of 1951flags specified in 1952.Ar spec . 1953The supported TCP flags are: 1954.Pp 1955.Cm fin , 1956.Cm syn , 1957.Cm rst , 1958.Cm psh , 1959.Cm ack 1960and 1961.Cm urg . 1962The absence of a particular flag may be denoted 1963with a 1964.Ql \&! . 1965A rule which contains a 1966.Cm tcpflags 1967specification can never match a fragmented packet which has 1968a non-zero offset. 1969See the 1970.Cm frag 1971option for details on matching fragmented packets. 1972.It Cm tcpseq Ar seq 1973TCP packets only. 1974Match if the TCP header sequence number field is set to 1975.Ar seq . 1976.It Cm tcpwin Ar tcpwin-list 1977Matches TCP packets whose header window field is set to 1978.Ar tcpwin-list , 1979which is either a single value or a list of values or ranges 1980specified in the same way as 1981.Ar ports . 1982.It Cm tcpoptions Ar spec 1983TCP packets only. 1984Match if the TCP header contains the comma separated list of 1985options specified in 1986.Ar spec . 1987The supported TCP options are: 1988.Pp 1989.Cm mss 1990(maximum segment size), 1991.Cm window 1992(tcp window advertisement), 1993.Cm sack 1994(selective ack), 1995.Cm ts 1996(rfc1323 timestamp) and 1997.Cm cc 1998(rfc1644 t/tcp connection count). 1999The absence of a particular option may be denoted 2000with a 2001.Ql \&! . 2002.It Cm uid Ar user 2003Match all TCP or UDP packets sent by or received for a 2004.Ar user . 2005A 2006.Ar user 2007may be matched by name or identification number. 2008.It Cm verrevpath 2009For incoming packets, 2010a routing table lookup is done on the packet's source address. 2011If the interface on which the packet entered the system matches the 2012outgoing interface for the route, 2013the packet matches. 2014If the interfaces do not match up, 2015the packet does not match. 2016All outgoing packets or packets with no incoming interface match. 2017.Pp 2018The name and functionality of the option is intentionally similar to 2019the Cisco IOS command: 2020.Pp 2021.Dl ip verify unicast reverse-path 2022.Pp 2023This option can be used to make anti-spoofing rules to reject all 2024packets with source addresses not from this interface. 2025See also the option 2026.Cm antispoof . 2027.It Cm versrcreach 2028For incoming packets, 2029a routing table lookup is done on the packet's source address. 2030If a route to the source address exists, but not the default route 2031or a blackhole/reject route, the packet matches. 2032Otherwise, the packet does not match. 2033All outgoing packets match. 2034.Pp 2035The name and functionality of the option is intentionally similar to 2036the Cisco IOS command: 2037.Pp 2038.Dl ip verify unicast source reachable-via any 2039.Pp 2040This option can be used to make anti-spoofing rules to reject all 2041packets whose source address is unreachable. 2042.It Cm antispoof 2043For incoming packets, the packet's source address is checked if it 2044belongs to a directly connected network. 2045If the network is directly connected, then the interface the packet 2046came on in is compared to the interface the network is connected to. 2047When incoming interface and directly connected interface are not the 2048same, the packet does not match. 2049Otherwise, the packet does match. 2050All outgoing packets match. 2051.Pp 2052This option can be used to make anti-spoofing rules to reject all 2053packets that pretend to be from a directly connected network but do 2054not come in through that interface. 2055This option is similar to but more restricted than 2056.Cm verrevpath 2057because it engages only on packets with source addresses of directly 2058connected networks instead of all source addresses. 2059.El 2060.Sh LOOKUP TABLES 2061Lookup tables are useful to handle large sparse sets of 2062addresses or other search keys (e.g., ports, jail IDs, interface names). 2063In the rest of this section we will use the term ``key''. 2064Table name needs to match the following spec: 2065.Ar table-name . 2066Tables with the same name can be created in different 2067.Ar sets . 2068However, rule links to the tables in 2069.Ar set 0 2070by default. 2071This behavior can be controlled by 2072.Va net.inet.ip.fw.tables_sets 2073variable. 2074See the 2075.Sx SETS OF RULES 2076section for more information. 2077There may be up to 65535 different lookup tables. 2078.Pp 2079The following table types are supported: 2080.Bl -tag -width indent 2081.It Ar table-type : Ar addr | iface | number | flow 2082.It Ar table-key : Ar addr Ns Oo / Ns Ar masklen Oc | iface-name | number | flow-spec 2083.It Ar flow-spec : Ar flow-field Ns Op , Ns Ar flow-spec 2084.It Ar flow-field : src-ip | proto | src-port | dst-ip | dst-port 2085.It Cm addr 2086Matches IPv4 or IPv6 address. 2087Each entry is represented by an 2088.Ar addr Ns Op / Ns Ar masklen 2089and will match all addresses with base 2090.Ar addr 2091(specified as an IPv4/IPv6 address, or a hostname) and mask width of 2092.Ar masklen 2093bits. 2094If 2095.Ar masklen 2096is not specified, it defaults to 32 for IPv4 and 128 for IPv6. 2097When looking up an IP address in a table, the most specific 2098entry will match. 2099.It Cm iface 2100Matches interface names. 2101Each entry is represented by string treated as interface name. 2102Wildcards are not supported. 2103.It Cm number 2104Matches protocol ports, uids/gids or jail IDs. 2105Each entry is represented by 32-bit unsigned integer. 2106Ranges are not supported. 2107.It Cm flow 2108Matches packet fields specified by 2109.Ar flow 2110type suboptions with table entries. 2111.El 2112.Pp 2113Tables require explicit creation via 2114.Cm create 2115before use. 2116.Pp 2117The following creation options are supported: 2118.Bl -tag -width indent 2119.It Ar create-options : Ar create-option | create-options 2120.It Ar create-option : Cm type Ar table-type | Cm valtype Ar value-mask | Cm algo Ar algo-desc | 2121.Cm limit Ar number | Cm locked 2122.It Cm type 2123Table key type. 2124.It Cm valtype 2125Table value mask. 2126.It Cm algo 2127Table algorithm to use (see below). 2128.It Cm limit 2129Maximum number of items that may be inserted into table. 2130.It Cm locked 2131Restrict any table modifications. 2132.El 2133.Pp 2134Some of these options may be modified later via 2135.Cm modify 2136keyword. 2137The following options can be changed: 2138.Bl -tag -width indent 2139.It Ar modify-options : Ar modify-option | modify-options 2140.It Ar modify-option : Cm limit Ar number 2141.It Cm limit 2142Alter maximum number of items that may be inserted into table. 2143.El 2144.Pp 2145Additionally, table can be locked or unlocked using 2146.Cm lock 2147or 2148.Cm unlock 2149commands. 2150.Pp 2151Tables of the same 2152.Ar type 2153can be swapped with each other using 2154.Cm swap Ar name 2155command. 2156Swap may fail if tables limits are set and data exchange 2157would result in limits hit. 2158Operation is performed atomically. 2159.Pp 2160One or more entries can be added to a table at once using 2161.Cm add 2162command. 2163Addition of all items are performed atomically. 2164By default, error in addition of one entry does not influence 2165addition of other entries. However, non-zero error code is returned 2166in that case. 2167Special 2168.Cm atomic 2169keyword may be specified before 2170.Cm add 2171to indicate all-or-none add request. 2172.Pp 2173One or more entries can be removed from a table at once using 2174.Cm delete 2175command. 2176By default, error in removal of one entry does not influence 2177removing of other entries. However, non-zero error code is returned 2178in that case. 2179.Pp 2180It may be possible to check what entry will be found on particular 2181.Ar table-key 2182using 2183.Cm lookup 2184.Ar table-key 2185command. 2186This functionality is optional and may be unsupported in some algorithms. 2187.Pp 2188The following operations can be performed on 2189.Ar one 2190or 2191.Cm all 2192tables: 2193.Bl -tag -width indent 2194.It Cm list 2195List all entries. 2196.It Cm flush 2197Removes all entries. 2198.It Cm info 2199Shows generic table information. 2200.It Cm detail 2201Shows generic table information and algo-specific data. 2202.El 2203.Pp 2204The following lookup algorithms are supported: 2205.Bl -tag -width indent 2206.It Ar algo-desc : algo-name | "algo-name algo-data" 2207.It Ar algo-name: Ar addr:radix | addr:hash | iface:array | number:array | flow:hash 2208.It Cm addr:radix 2209Separate Radix trees for IPv4 and IPv6, the same way as the routing table (see 2210.Xr route 4 ) . 2211Default choice for 2212.Ar addr 2213type. 2214.It Cm addr:hash 2215Separate auto-growing hashes for IPv4 and IPv6. 2216Accepts entries with the same mask length specified initially via 2217.Cm "addr:hash masks=/v4,/v6" 2218algorithm creation options. 2219Assume /32 and /128 masks by default. 2220Search removes host bits (according to mask) from supplied address and checks 2221resulting key in appropriate hash. 2222Mostly optimized for /64 and byte-ranged IPv6 masks. 2223.It Cm iface:array 2224Array storing sorted indexes for entries which are presented in the system. 2225Optimized for very fast lookup. 2226.It Cm number:array 2227Array storing sorted u32 numbers. 2228.It Cm flow:hash 2229Auto-growing hash storing flow entries. 2230Search calculates hash on required packet fields and searches for matching 2231entries in selected bucket. 2232.El 2233.Pp 2234The 2235.Cm tablearg 2236feature provides the ability to use a value, looked up in the table, as 2237the argument for a rule action, action parameter or rule option. 2238This can significantly reduce number of rules in some configurations. 2239If two tables are used in a rule, the result of the second (destination) 2240is used. 2241.Pp 2242Each record may hold one or more values according to 2243.Ar value-mask . 2244This mask is set on table creation via 2245.Cm valtype 2246option. 2247The following value types are supported: 2248.Bl -tag -width indent 2249.It Ar value-mask : Ar value-type Ns Op , Ns Ar value-mask 2250.It Ar value-type : Ar skipto | pipe | fib | nat | dscp | tag | divert | 2251.Ar netgraph | limit | ipv4 2252.It Cm skipto 2253rule number to jump to. 2254.It Cm pipe 2255Pipe number to use. 2256.It Cm fib 2257fib number to match/set. 2258.It Cm nat 2259nat number to jump to. 2260.It Cm dscp 2261dscp value to match/set. 2262.It Cm tag 2263tag number to match/set. 2264.It Cm divert 2265port number to divert traffic to. 2266.It Cm netgraph 2267hook number to move packet to. 2268.It Cm limit 2269maximum number of connections. 2270.It Cm ipv4 2271IPv4 nexthop to fwd packets to. 2272.It Cm ipv6 2273IPv6 nexthop to fwd packets to. 2274.El 2275.Pp 2276The 2277.Cm tablearg 2278argument can be used with the following actions: 2279.Cm nat, pipe , queue, divert, tee, netgraph, ngtee, fwd, skipto, setfib, 2280action parameters: 2281.Cm tag, untag, 2282rule options: 2283.Cm limit, tagged. 2284.Pp 2285When used with the 2286.Cm skipto 2287action, the user should be aware that the code will walk the ruleset 2288up to a rule equal to, or past, the given number. 2289.Pp 2290See the 2291.Sx EXAMPLES 2292Section for example usage of tables and the tablearg keyword. 2293.Sh SETS OF RULES 2294Each rule or table belongs to one of 32 different 2295.Em sets 2296, numbered 0 to 31. 2297Set 31 is reserved for the default rule. 2298.Pp 2299By default, rules or tables are put in set 0, unless you use the 2300.Cm set N 2301attribute when adding a new rule or table. 2302Sets can be individually and atomically enabled or disabled, 2303so this mechanism permits an easy way to store multiple configurations 2304of the firewall and quickly (and atomically) switch between them. 2305.Pp 2306By default, tables from set 0 are referenced when adding rule with 2307table opcodes regardless of rule set. 2308This behavior can be changed by setting 2309.Va net.inet.ip.fw.tables_sets 2310variable to 1. 2311Rule's set will then be used for table references. 2312.Pp 2313The command to enable/disable sets is 2314.Bd -ragged -offset indent 2315.Nm 2316.Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ... 2317.Ed 2318.Pp 2319where multiple 2320.Cm enable 2321or 2322.Cm disable 2323sections can be specified. 2324Command execution is atomic on all the sets specified in the command. 2325By default, all sets are enabled. 2326.Pp 2327When you disable a set, its rules behave as if they do not exist 2328in the firewall configuration, with only one exception: 2329.Bd -ragged -offset indent 2330dynamic rules created from a rule before it had been disabled 2331will still be active until they expire. 2332In order to delete 2333dynamic rules you have to explicitly delete the parent rule 2334which generated them. 2335.Ed 2336.Pp 2337The set number of rules can be changed with the command 2338.Bd -ragged -offset indent 2339.Nm 2340.Cm set move 2341.Brq Cm rule Ar rule-number | old-set 2342.Cm to Ar new-set 2343.Ed 2344.Pp 2345Also, you can atomically swap two rulesets with the command 2346.Bd -ragged -offset indent 2347.Nm 2348.Cm set swap Ar first-set second-set 2349.Ed 2350.Pp 2351See the 2352.Sx EXAMPLES 2353Section on some possible uses of sets of rules. 2354.Sh STATEFUL FIREWALL 2355Stateful operation is a way for the firewall to dynamically 2356create rules for specific flows when packets that 2357match a given pattern are detected. 2358Support for stateful 2359operation comes through the 2360.Cm check-state , keep-state , record-state , limit 2361and 2362.Cm set-limit 2363options of 2364.Nm rules . 2365.Pp 2366Dynamic rules are created when a packet matches a 2367.Cm keep-state , 2368.Cm record-state , 2369.Cm limit 2370or 2371.Cm set-limit 2372rule, causing the creation of a 2373.Em dynamic 2374rule which will match all and only packets with 2375a given 2376.Em protocol 2377between a 2378.Em src-ip/src-port dst-ip/dst-port 2379pair of addresses 2380.Em ( src 2381and 2382.Em dst 2383are used here only to denote the initial match addresses, but they 2384are completely equivalent afterwards). 2385Rules created by 2386.Cm keep-state 2387option also have a 2388.Ar :flowname 2389taken from it. 2390This name is used in matching together with addresses, ports and protocol. 2391Dynamic rules will be checked at the first 2392.Cm check-state, keep-state 2393or 2394.Cm limit 2395occurrence, and the action performed upon a match will be the same 2396as in the parent rule. 2397.Pp 2398Note that no additional attributes other than protocol and IP addresses 2399and ports and :flowname are checked on dynamic rules. 2400.Pp 2401The typical use of dynamic rules is to keep a closed firewall configuration, 2402but let the first TCP SYN packet from the inside network install a 2403dynamic rule for the flow so that packets belonging to that session 2404will be allowed through the firewall: 2405.Pp 2406.Dl "ipfw add check-state :OUTBOUND" 2407.Dl "ipfw add allow tcp from my-subnet to any setup keep-state :OUTBOUND" 2408.Dl "ipfw add deny tcp from any to any" 2409.Pp 2410A similar approach can be used for UDP, where an UDP packet coming 2411from the inside will install a dynamic rule to let the response through 2412the firewall: 2413.Pp 2414.Dl "ipfw add check-state :OUTBOUND" 2415.Dl "ipfw add allow udp from my-subnet to any keep-state :OUTBOUND" 2416.Dl "ipfw add deny udp from any to any" 2417.Pp 2418Dynamic rules expire after some time, which depends on the status 2419of the flow and the setting of some 2420.Cm sysctl 2421variables. 2422See Section 2423.Sx SYSCTL VARIABLES 2424for more details. 2425For TCP sessions, dynamic rules can be instructed to periodically 2426send keepalive packets to refresh the state of the rule when it is 2427about to expire. 2428.Pp 2429See Section 2430.Sx EXAMPLES 2431for more examples on how to use dynamic rules. 2432.Sh TRAFFIC SHAPER (DUMMYNET) CONFIGURATION 2433.Nm 2434is also the user interface for the 2435.Nm dummynet 2436traffic shaper, packet scheduler and network emulator, a subsystem that 2437can artificially queue, delay or drop packets 2438emulating the behaviour of certain network links 2439or queueing systems. 2440.Pp 2441.Nm dummynet 2442operates by first using the firewall to select packets 2443using any match pattern that can be used in 2444.Nm 2445rules. 2446Matching packets are then passed to either of two 2447different objects, which implement the traffic regulation: 2448.Bl -hang -offset XXXX 2449.It Em pipe 2450A 2451.Em pipe 2452emulates a 2453.Em link 2454with given bandwidth and propagation delay, 2455driven by a FIFO scheduler and a single queue with programmable 2456queue size and packet loss rate. 2457Packets are appended to the queue as they come out from 2458.Nm ipfw , 2459and then transferred in FIFO order to the link at the desired rate. 2460.It Em queue 2461A 2462.Em queue 2463is an abstraction used to implement packet scheduling 2464using one of several packet scheduling algorithms. 2465Packets sent to a 2466.Em queue 2467are first grouped into flows according to a mask on the 5-tuple. 2468Flows are then passed to the scheduler associated to the 2469.Em queue , 2470and each flow uses scheduling parameters (weight and others) 2471as configured in the 2472.Em queue 2473itself. 2474A scheduler in turn is connected to an emulated link, 2475and arbitrates the link's bandwidth among backlogged flows according to 2476weights and to the features of the scheduling algorithm in use. 2477.El 2478.Pp 2479In practice, 2480.Em pipes 2481can be used to set hard limits to the bandwidth that a flow can use, whereas 2482.Em queues 2483can be used to determine how different flows share the available bandwidth. 2484.Pp 2485A graphical representation of the binding of queues, 2486flows, schedulers and links is below. 2487.Bd -literal -offset indent 2488 (flow_mask|sched_mask) sched_mask 2489 +---------+ weight Wx +-------------+ 2490 | |->-[flow]-->--| |-+ 2491 -->--| QUEUE x | ... | | | 2492 | |->-[flow]-->--| SCHEDuler N | | 2493 +---------+ | | | 2494 ... | +--[LINK N]-->-- 2495 +---------+ weight Wy | | +--[LINK N]-->-- 2496 | |->-[flow]-->--| | | 2497 -->--| QUEUE y | ... | | | 2498 | |->-[flow]-->--| | | 2499 +---------+ +-------------+ | 2500 +-------------+ 2501.Ed 2502It is important to understand the role of the SCHED_MASK 2503and FLOW_MASK, which are configured through the commands 2504.Dl "ipfw sched N config mask SCHED_MASK ..." 2505and 2506.Dl "ipfw queue X config mask FLOW_MASK ..." . 2507.Pp 2508The SCHED_MASK is used to assign flows to one or more 2509scheduler instances, one for each 2510value of the packet's 5-tuple after applying SCHED_MASK. 2511As an example, using ``src-ip 0xffffff00'' creates one instance 2512for each /24 destination subnet. 2513.Pp 2514The FLOW_MASK, together with the SCHED_MASK, is used to split 2515packets into flows. 2516As an example, using 2517``src-ip 0x000000ff'' 2518together with the previous SCHED_MASK makes a flow for 2519each individual source address. 2520In turn, flows for each /24 2521subnet will be sent to the same scheduler instance. 2522.Pp 2523The above diagram holds even for the 2524.Em pipe 2525case, with the only restriction that a 2526.Em pipe 2527only supports a SCHED_MASK, and forces the use of a FIFO 2528scheduler (these are for backward compatibility reasons; 2529in fact, internally, a 2530.Nm dummynet's 2531pipe is implemented exactly as above). 2532.Pp 2533There are two modes of 2534.Nm dummynet 2535operation: 2536.Dq normal 2537and 2538.Dq fast . 2539The 2540.Dq normal 2541mode tries to emulate a real link: the 2542.Nm dummynet 2543scheduler ensures that the packet will not leave the pipe faster than it 2544would on the real link with a given bandwidth. 2545The 2546.Dq fast 2547mode allows certain packets to bypass the 2548.Nm dummynet 2549scheduler (if packet flow does not exceed pipe's bandwidth). 2550This is the reason why the 2551.Dq fast 2552mode requires less CPU cycles per packet (on average) and packet latency 2553can be significantly lower in comparison to a real link with the same 2554bandwidth. 2555The default mode is 2556.Dq normal . 2557The 2558.Dq fast 2559mode can be enabled by setting the 2560.Va net.inet.ip.dummynet.io_fast 2561.Xr sysctl 8 2562variable to a non-zero value. 2563.Pp 2564.Ss PIPE, QUEUE AND SCHEDULER CONFIGURATION 2565The 2566.Em pipe , 2567.Em queue 2568and 2569.Em scheduler 2570configuration commands are the following: 2571.Bd -ragged -offset indent 2572.Cm pipe Ar number Cm config Ar pipe-configuration 2573.Pp 2574.Cm queue Ar number Cm config Ar queue-configuration 2575.Pp 2576.Cm sched Ar number Cm config Ar sched-configuration 2577.Ed 2578.Pp 2579The following parameters can be configured for a pipe: 2580.Pp 2581.Bl -tag -width indent -compact 2582.It Cm bw Ar bandwidth | device 2583Bandwidth, measured in 2584.Sm off 2585.Op Cm K | M | G 2586.Brq Cm bit/s | Byte/s . 2587.Sm on 2588.Pp 2589A value of 0 (default) means unlimited bandwidth. 2590The unit must immediately follow the number, as in 2591.Pp 2592.Dl "ipfw pipe 1 config bw 300Kbit/s" 2593.Pp 2594If a device name is specified instead of a numeric value, as in 2595.Pp 2596.Dl "ipfw pipe 1 config bw tun0" 2597.Pp 2598then the transmit clock is supplied by the specified device. 2599At the moment only the 2600.Xr tun 4 2601device supports this 2602functionality, for use in conjunction with 2603.Xr ppp 8 . 2604.Pp 2605.It Cm delay Ar ms-delay 2606Propagation delay, measured in milliseconds. 2607The value is rounded to the next multiple of the clock tick 2608(typically 10ms, but it is a good practice to run kernels 2609with 2610.Dq "options HZ=1000" 2611to reduce 2612the granularity to 1ms or less). 2613The default value is 0, meaning no delay. 2614.Pp 2615.It Cm burst Ar size 2616If the data to be sent exceeds the pipe's bandwidth limit 2617(and the pipe was previously idle), up to 2618.Ar size 2619bytes of data are allowed to bypass the 2620.Nm dummynet 2621scheduler, and will be sent as fast as the physical link allows. 2622Any additional data will be transmitted at the rate specified 2623by the 2624.Nm pipe 2625bandwidth. 2626The burst size depends on how long the pipe has been idle; 2627the effective burst size is calculated as follows: 2628MAX( 2629.Ar size 2630, 2631.Nm bw 2632* pipe_idle_time). 2633.Pp 2634.It Cm profile Ar filename 2635A file specifying the additional overhead incurred in the transmission 2636of a packet on the link. 2637.Pp 2638Some link types introduce extra delays in the transmission 2639of a packet, e.g., because of MAC level framing, contention on 2640the use of the channel, MAC level retransmissions and so on. 2641From our point of view, the channel is effectively unavailable 2642for this extra time, which is constant or variable depending 2643on the link type. 2644Additionally, packets may be dropped after this 2645time (e.g., on a wireless link after too many retransmissions). 2646We can model the additional delay with an empirical curve 2647that represents its distribution. 2648.Bd -literal -offset indent 2649 cumulative probability 2650 1.0 ^ 2651 | 2652 L +-- loss-level x 2653 | ****** 2654 | * 2655 | ***** 2656 | * 2657 | ** 2658 | * 2659 +-------*-------------------> 2660 delay 2661.Ed 2662The empirical curve may have both vertical and horizontal lines. 2663Vertical lines represent constant delay for a range of 2664probabilities. 2665Horizontal lines correspond to a discontinuity in the delay 2666distribution: the pipe will use the largest delay for a 2667given probability. 2668.Pp 2669The file format is the following, with whitespace acting as 2670a separator and '#' indicating the beginning a comment: 2671.Bl -tag -width indent 2672.It Cm name Ar identifier 2673optional name (listed by "ipfw pipe show") 2674to identify the delay distribution; 2675.It Cm bw Ar value 2676the bandwidth used for the pipe. 2677If not specified here, it must be present 2678explicitly as a configuration parameter for the pipe; 2679.It Cm loss-level Ar L 2680the probability above which packets are lost. 2681(0.0 <= L <= 1.0, default 1.0 i.e., no loss); 2682.It Cm samples Ar N 2683the number of samples used in the internal 2684representation of the curve (2..1024; default 100); 2685.It Cm "delay prob" | "prob delay" 2686One of these two lines is mandatory and defines 2687the format of the following lines with data points. 2688.It Ar XXX Ar YYY 26892 or more lines representing points in the curve, 2690with either delay or probability first, according 2691to the chosen format. 2692The unit for delay is milliseconds. 2693Data points do not need to be sorted. 2694Also, the number of actual lines can be different 2695from the value of the "samples" parameter: 2696.Nm 2697utility will sort and interpolate 2698the curve as needed. 2699.El 2700.Pp 2701Example of a profile file: 2702.Bd -literal -offset indent 2703name bla_bla_bla 2704samples 100 2705loss-level 0.86 2706prob delay 27070 200 # minimum overhead is 200ms 27080.5 200 27090.5 300 27100.8 1000 27110.9 1300 27121 1300 2713#configuration file end 2714.Ed 2715.El 2716.Pp 2717The following parameters can be configured for a queue: 2718.Pp 2719.Bl -tag -width indent -compact 2720.It Cm pipe Ar pipe_nr 2721Connects a queue to the specified pipe. 2722Multiple queues (with the same or different weights) can be connected to 2723the same pipe, which specifies the aggregate rate for the set of queues. 2724.Pp 2725.It Cm weight Ar weight 2726Specifies the weight to be used for flows matching this queue. 2727The weight must be in the range 1..100, and defaults to 1. 2728.El 2729.Pp 2730The following case-insensitive parameters can be configured for a 2731scheduler: 2732.Pp 2733.Bl -tag -width indent -compact 2734.It Cm type Ar {fifo | wf2q+ | rr | qfq | fq_codel | fq_pie} 2735specifies the scheduling algorithm to use. 2736.Bl -tag -width indent -compact 2737.It Cm fifo 2738is just a FIFO scheduler (which means that all packets 2739are stored in the same queue as they arrive to the scheduler). 2740FIFO has O(1) per-packet time complexity, with very low 2741constants (estimate 60-80ns on a 2GHz desktop machine) 2742but gives no service guarantees. 2743.It Cm wf2q+ 2744implements the WF2Q+ algorithm, which is a Weighted Fair Queueing 2745algorithm which permits flows to share bandwidth according to 2746their weights. 2747Note that weights are not priorities; even a flow 2748with a minuscule weight will never starve. 2749WF2Q+ has O(log N) per-packet processing cost, where N is the number 2750of flows, and is the default algorithm used by previous versions 2751dummynet's queues. 2752.It Cm rr 2753implements the Deficit Round Robin algorithm, which has O(1) processing 2754costs (roughly, 100-150ns per packet) 2755and permits bandwidth allocation according to weights, but 2756with poor service guarantees. 2757.It Cm qfq 2758implements the QFQ algorithm, which is a very fast variant of 2759WF2Q+, with similar service guarantees and O(1) processing 2760costs (roughly, 200-250ns per packet). 2761.It Cm fq_codel 2762implements the FQ-CoDel (FlowQueue-CoDel) scheduler/AQM algorithm, which 2763uses a modified Deficit Round Robin scheduler to manage two lists of sub-queues 2764(old sub-queues and new sub-queues) for providing brief periods of priority to 2765lightweight or short burst flows. 2766By default, the total number of sub-queues is 1024. 2767FQ-CoDel's internal, dynamically 2768created sub-queues are controlled by separate instances of CoDel AQM. 2769.It Cm fq_pie 2770implements the FQ-PIE (FlowQueue-PIE) scheduler/AQM algorithm, which similar to 2771.Cm fq_codel 2772but uses per sub-queue PIE AQM instance to control the queue delay. 2773.El 2774.Pp 2775.Cm fq_codel 2776inherits AQM parameters and options from 2777.Cm codel 2778(see below), and 2779.Cm fq_pie 2780inherits AQM parameters and options from 2781.Cm pie 2782(see below). 2783Additionally, both of 2784.Cm fq_codel 2785and 2786.Cm fq_pie 2787have shared scheduler parameters which are: 2788.Bl -tag -width indent 2789.It Cm quantum 2790.Ar m 2791specifies the quantum (credit) of the scheduler. 2792.Ar m 2793is the number of bytes a queue can serve before being moved to the tail 2794of old queues list. 2795The default is 1514 bytes, and the maximum acceptable value 2796is 9000 bytes. 2797.It Cm limit 2798.Ar m 2799specifies the hard size limit (in unit of packets) of all queues managed by an 2800instance of the scheduler. 2801The default value of 2802.Ar m 2803is 10240 packets, and the maximum acceptable value is 20480 packets. 2804.It Cm flows 2805.Ar m 2806specifies the total number of flow queues (sub-queues) that fq_* 2807creates and manages. 2808By default, 1024 sub-queues are created when an instance 2809of the fq_{codel/pie} scheduler is created. 2810The maximum acceptable value is 281165536. 2812.El 2813.Pp 2814Note that any token after 2815.Cm fq_codel 2816or 2817.Cm fq_pie 2818is considered a parameter for fq_{codel/pie}. 2819So, ensure all scheduler 2820configuration options not related to fq_{codel/pie} are written before 2821.Cm fq_codel/fq_pie 2822tokens. 2823.El 2824.Pp 2825In addition to the type, all parameters allowed for a pipe can also 2826be specified for a scheduler. 2827.Pp 2828Finally, the following parameters can be configured for both 2829pipes and queues: 2830.Pp 2831.Bl -tag -width XXXX -compact 2832.It Cm buckets Ar hash-table-size 2833Specifies the size of the hash table used for storing the 2834various queues. 2835Default value is 64 controlled by the 2836.Xr sysctl 8 2837variable 2838.Va net.inet.ip.dummynet.hash_size , 2839allowed range is 16 to 65536. 2840.Pp 2841.It Cm mask Ar mask-specifier 2842Packets sent to a given pipe or queue by an 2843.Nm 2844rule can be further classified into multiple flows, each of which is then 2845sent to a different 2846.Em dynamic 2847pipe or queue. 2848A flow identifier is constructed by masking the IP addresses, 2849ports and protocol types as specified with the 2850.Cm mask 2851options in the configuration of the pipe or queue. 2852For each different flow identifier, a new pipe or queue is created 2853with the same parameters as the original object, and matching packets 2854are sent to it. 2855.Pp 2856Thus, when 2857.Em dynamic pipes 2858are used, each flow will get the same bandwidth as defined by the pipe, 2859whereas when 2860.Em dynamic queues 2861are used, each flow will share the parent's pipe bandwidth evenly 2862with other flows generated by the same queue (note that other queues 2863with different weights might be connected to the same pipe). 2864.br 2865Available mask specifiers are a combination of one or more of the following: 2866.Pp 2867.Cm dst-ip Ar mask , 2868.Cm dst-ip6 Ar mask , 2869.Cm src-ip Ar mask , 2870.Cm src-ip6 Ar mask , 2871.Cm dst-port Ar mask , 2872.Cm src-port Ar mask , 2873.Cm flow-id Ar mask , 2874.Cm proto Ar mask 2875or 2876.Cm all , 2877.Pp 2878where the latter means all bits in all fields are significant. 2879.Pp 2880.It Cm noerror 2881When a packet is dropped by a 2882.Nm dummynet 2883queue or pipe, the error 2884is normally reported to the caller routine in the kernel, in the 2885same way as it happens when a device queue fills up. 2886Setting this 2887option reports the packet as successfully delivered, which can be 2888needed for some experimental setups where you want to simulate 2889loss or congestion at a remote router. 2890.Pp 2891.It Cm plr Ar packet-loss-rate 2892Packet loss rate. 2893Argument 2894.Ar packet-loss-rate 2895is a floating-point number between 0 and 1, with 0 meaning no 2896loss, 1 meaning 100% loss. 2897The loss rate is internally represented on 31 bits. 2898.Pp 2899.It Cm queue Brq Ar slots | size Ns Cm Kbytes 2900Queue size, in 2901.Ar slots 2902or 2903.Cm KBytes . 2904Default value is 50 slots, which 2905is the typical queue size for Ethernet devices. 2906Note that for slow speed links you should keep the queue 2907size short or your traffic might be affected by a significant 2908queueing delay. 2909E.g., 50 max-sized Ethernet packets (1500 bytes) mean 600Kbit 2910or 20s of queue on a 30Kbit/s pipe. 2911Even worse effects can result if you get packets from an 2912interface with a much larger MTU, e.g.\& the loopback interface 2913with its 16KB packets. 2914The 2915.Xr sysctl 8 2916variables 2917.Em net.inet.ip.dummynet.pipe_byte_limit 2918and 2919.Em net.inet.ip.dummynet.pipe_slot_limit 2920control the maximum lengths that can be specified. 2921.Pp 2922.It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p 2923[ecn] 2924Make use of the RED (Random Early Detection) queue management algorithm. 2925.Ar w_q 2926and 2927.Ar max_p 2928are floating 2929point numbers between 0 and 1 (inclusive), while 2930.Ar min_th 2931and 2932.Ar max_th 2933are integer numbers specifying thresholds for queue management 2934(thresholds are computed in bytes if the queue has been defined 2935in bytes, in slots otherwise). 2936The two parameters can also be of the same value if needed. The 2937.Nm dummynet 2938also supports the gentle RED variant (gred) and ECN (Explicit Congestion 2939Notification) as optional. Three 2940.Xr sysctl 8 2941variables can be used to control the RED behaviour: 2942.Bl -tag -width indent 2943.It Va net.inet.ip.dummynet.red_lookup_depth 2944specifies the accuracy in computing the average queue 2945when the link is idle (defaults to 256, must be greater than zero) 2946.It Va net.inet.ip.dummynet.red_avg_pkt_size 2947specifies the expected average packet size (defaults to 512, must be 2948greater than zero) 2949.It Va net.inet.ip.dummynet.red_max_pkt_size 2950specifies the expected maximum packet size, only used when queue 2951thresholds are in bytes (defaults to 1500, must be greater than zero). 2952.El 2953.Pp 2954.It Cm codel Oo Cm target Ar time Oc Oo Cm interval Ar time Oc Oo Cm ecn | 2955.Cm noecn Oc 2956Make use of the CoDel (Controlled-Delay) queue management algorithm. 2957.Ar time 2958is interpreted as milliseconds by default but seconds (s), milliseconds (ms) or 2959microseconds (us) can be specified instead. 2960CoDel drops or marks (ECN) packets 2961depending on packet sojourn time in the queue. 2962.Cm target 2963.Ar time 2964(5ms by default) is the minimum acceptable persistent queue delay that CoDel 2965allows. 2966CoDel does not drop packets directly after packets sojourn time becomes 2967higher than 2968.Cm target 2969.Ar time 2970but waits for 2971.Cm interval 2972.Ar time 2973(100ms default) before dropping. 2974.Cm interval 2975.Ar time 2976should be set to maximum RTT for all expected connections. 2977.Cm ecn 2978enables (disabled by default) packet marking (instead of dropping) for 2979ECN-enabled TCP flows when queue delay becomes high. 2980.Pp 2981Note that any token after 2982.Cm codel 2983is considered a parameter for CoDel. 2984So, ensure all pipe/queue 2985configuration options are written before 2986.Cm codel 2987token. 2988.Pp 2989The 2990.Xr sysctl 8 2991variables 2992.Va net.inet.ip.dummynet.codel.target 2993and 2994.Va net.inet.ip.dummynet.codel.interval 2995can be used to set CoDel default parameters. 2996.Pp 2997.It Cm pie Oo Cm target Ar time Oc Oo Cm tupdate Ar time Oc Oo 2998.Cm alpha Ar n Oc Oo Cm beta Ar n Oc Oo Cm max_burst Ar time Oc Oo 2999.Cm max_ecnth Ar n Oc Oo Cm ecn | Cm noecn Oc Oo Cm capdrop | 3000.Cm nocapdrop Oc Oo Cm drand | Cm nodrand Oc Oo Cm onoff 3001.Oc Oo Cm dre | Cm ts Oc 3002Make use of the PIE (Proportional Integral controller Enhanced) queue management 3003algorithm. 3004PIE drops or marks packets depending on a calculated drop probability during 3005en-queue process, with the aim of achieving high throughput while keeping queue 3006delay low. 3007At regular time intervals of 3008.Cm tupdate 3009.Ar time 3010(15ms by default) a background process (re)calculates the probability based on queue delay 3011deviations from 3012.Cm target 3013.Ar time 3014(15ms by default) and queue delay trends. 3015PIE approximates current queue 3016delay by using a departure rate estimation method, or (optionally) by using a 3017packet timestamp method similar to CoDel. 3018.Ar time 3019is interpreted as milliseconds by default but seconds (s), milliseconds (ms) or 3020microseconds (us) can be specified instead. 3021The other PIE parameters and options are as follows: 3022.Bl -tag -width indent 3023.It Cm alpha Ar n 3024.Ar n 3025is a floating point number between 0 and 7 which specifies the weight of queue 3026delay deviations that is used in drop probability calculation. 30270.125 is the default. 3028.It Cm beta Ar n 3029.Ar n 3030is a floating point number between 0 and 7 which specifies is the weight of queue 3031delay trend that is used in drop probability calculation. 30321.25 is the default. 3033.It Cm max_burst Ar time 3034The maximum period of time that PIE does not drop/mark packets. 3035150ms is the 3036default and 10s is the maximum value. 3037.It Cm max_ecnth Ar n 3038Even when ECN is enabled, PIE drops packets instead of marking them when drop 3039probability becomes higher than ECN probability threshold 3040.Cm max_ecnth Ar n 3041, the default is 0.1 (i.e 10%) and 1 is the maximum value. 3042.It Cm ecn | noecn 3043enable or disable ECN marking for ECN-enabled TCP flows. 3044Disabled by default. 3045.It Cm capdrop | nocapdrop 3046enable or disable cap drop adjustment. 3047Cap drop adjustment is enabled by default. 3048.It Cm drand | nodrand 3049enable or disable drop probability de-randomisation. 3050De-randomisation eliminates 3051the problem of dropping packets too close or too far. 3052De-randomisation is enabled by default. 3053.It Cm onoff 3054enable turning PIE on and off depending on queue load. 3055If this option is enabled, 3056PIE turns on when over 1/3 of queue becomes full. 3057This option is disabled by 3058default. 3059.It Cm dre | ts 3060Calculate queue delay using departure rate estimation 3061.Cm dre 3062or timestamps 3063.Cm ts . 3064.Cm dre 3065is used by default. 3066.El 3067.Pp 3068Note that any token after 3069.Cm pie 3070is considered a parameter for PIE. 3071So ensure all pipe/queue 3072the configuration options are written before 3073.Cm pie 3074token. 3075.Xr sysctl 8 3076variables can be used to control the 3077.Cm pie 3078default parameters. 3079See the 3080.Sx SYSCTL VARIABLES 3081section for more details. 3082.El 3083.Pp 3084When used with IPv6 data, 3085.Nm dummynet 3086currently has several limitations. 3087Information necessary to route link-local packets to an 3088interface is not available after processing by 3089.Nm dummynet 3090so those packets are dropped in the output path. 3091Care should be taken to ensure that link-local packets are not passed to 3092.Nm dummynet . 3093.Sh CHECKLIST 3094Here are some important points to consider when designing your 3095rules: 3096.Bl -bullet 3097.It 3098Remember that you filter both packets going 3099.Cm in 3100and 3101.Cm out . 3102Most connections need packets going in both directions. 3103.It 3104Remember to test very carefully. 3105It is a good idea to be near the console when doing this. 3106If you cannot be near the console, 3107use an auto-recovery script such as the one in 3108.Pa /usr/share/examples/ipfw/change_rules.sh . 3109.It 3110Do not forget the loopback interface. 3111.El 3112.Sh FINE POINTS 3113.Bl -bullet 3114.It 3115There are circumstances where fragmented datagrams are unconditionally 3116dropped. 3117TCP packets are dropped if they do not contain at least 20 bytes of 3118TCP header, UDP packets are dropped if they do not contain a full 8 3119byte UDP header, and ICMP packets are dropped if they do not contain 31204 bytes of ICMP header, enough to specify the ICMP type, code, and 3121checksum. 3122These packets are simply logged as 3123.Dq pullup failed 3124since there may not be enough good data in the packet to produce a 3125meaningful log entry. 3126.It 3127Another type of packet is unconditionally dropped, a TCP packet with a 3128fragment offset of one. 3129This is a valid packet, but it only has one use, to try 3130to circumvent firewalls. 3131When logging is enabled, these packets are 3132reported as being dropped by rule -1. 3133.It 3134If you are logged in over a network, loading the 3135.Xr kld 4 3136version of 3137.Nm 3138is probably not as straightforward as you would think. 3139The following command line is recommended: 3140.Bd -literal -offset indent 3141kldload ipfw && \e 3142ipfw add 32000 allow ip from any to any 3143.Ed 3144.Pp 3145Along the same lines, doing an 3146.Bd -literal -offset indent 3147ipfw flush 3148.Ed 3149.Pp 3150in similar surroundings is also a bad idea. 3151.It 3152The 3153.Nm 3154filter list may not be modified if the system security level 3155is set to 3 or higher 3156(see 3157.Xr init 8 3158for information on system security levels). 3159.El 3160.Sh PACKET DIVERSION 3161A 3162.Xr divert 4 3163socket bound to the specified port will receive all packets 3164diverted to that port. 3165If no socket is bound to the destination port, or if the divert module is 3166not loaded, or if the kernel was not compiled with divert socket support, 3167the packets are dropped. 3168.Sh NETWORK ADDRESS TRANSLATION (NAT) 3169.Nm 3170support in-kernel NAT using the kernel version of 3171.Xr libalias 3 . 3172The kernel module 3173.Cm ipfw_nat 3174should be loaded or kernel should have 3175.Cm options IPFIREWALL_NAT 3176to be able use NAT. 3177.Pp 3178The nat configuration command is the following: 3179.Bd -ragged -offset indent 3180.Bk -words 3181.Cm nat 3182.Ar nat_number 3183.Cm config 3184.Ar nat-configuration 3185.Ek 3186.Ed 3187.Pp 3188The following parameters can be configured: 3189.Bl -tag -width indent 3190.It Cm ip Ar ip_address 3191Define an ip address to use for aliasing. 3192.It Cm if Ar nic 3193Use ip address of NIC for aliasing, dynamically changing 3194it if NIC's ip address changes. 3195.It Cm log 3196Enable logging on this nat instance. 3197.It Cm deny_in 3198Deny any incoming connection from outside world. 3199.It Cm same_ports 3200Try to leave the alias port numbers unchanged from 3201the actual local port numbers. 3202.It Cm unreg_only 3203Traffic on the local network not originating from an 3204unregistered address spaces will be ignored. 3205.It Cm reset 3206Reset table of the packet aliasing engine on address change. 3207.It Cm reverse 3208Reverse the way libalias handles aliasing. 3209.It Cm proxy_only 3210Obey transparent proxy rules only, packet aliasing is not performed. 3211.It Cm skip_global 3212Skip instance in case of global state lookup (see below). 3213.El 3214.Pp 3215Some specials value can be supplied instead of 3216.Va nat_number: 3217.Bl -tag -width indent 3218.It Cm global 3219Looks up translation state in all configured nat instances. 3220If an entry is found, packet is aliased according to that entry. 3221If no entry was found in any of the instances, packet is passed unchanged, 3222and no new entry will be created. 3223See section 3224.Sx MULTIPLE INSTANCES 3225in 3226.Xr natd 8 3227for more information. 3228.It Cm tablearg 3229Uses argument supplied in lookup table. 3230See 3231.Sx LOOKUP TABLES 3232section below for more information on lookup tables. 3233.El 3234.Pp 3235To let the packet continue after being (de)aliased, set the sysctl variable 3236.Va net.inet.ip.fw.one_pass 3237to 0. 3238For more information about aliasing modes, refer to 3239.Xr libalias 3 . 3240See Section 3241.Sx EXAMPLES 3242for some examples about nat usage. 3243.Ss REDIRECT AND LSNAT SUPPORT IN IPFW 3244Redirect and LSNAT support follow closely the syntax used in 3245.Xr natd 8 . 3246See Section 3247.Sx EXAMPLES 3248for some examples on how to do redirect and lsnat. 3249.Ss SCTP NAT SUPPORT 3250SCTP nat can be configured in a similar manner to TCP through the 3251.Nm 3252command line tool. 3253The main difference is that 3254.Nm sctp nat 3255does not do port translation. 3256Since the local and global side ports will be the same, 3257there is no need to specify both. 3258Ports are redirected as follows: 3259.Bd -ragged -offset indent 3260.Bk -words 3261.Cm nat 3262.Ar nat_number 3263.Cm config if 3264.Ar nic 3265.Cm redirect_port sctp 3266.Ar ip_address [,addr_list] {[port | port-port] [,ports]} 3267.Ek 3268.Ed 3269.Pp 3270Most 3271.Nm sctp nat 3272configuration can be done in real-time through the 3273.Xr sysctl 8 3274interface. 3275All may be changed dynamically, though the hash_table size will only 3276change for new 3277.Nm nat 3278instances. 3279See 3280.Sx SYSCTL VARIABLES 3281for more info. 3282.Sh IPv6/IPv4 NETWORK ADDRESS AND PROTOCOL TRANSLATION 3283.Nm 3284supports in-kernel IPv6/IPv4 network address and protocol translation. 3285Stateful NAT64 translation allows IPv6-only clients to contact IPv4 servers 3286using unicast TCP, UDP or ICMP protocols. 3287One or more IPv4 addresses assigned to a stateful NAT64 translator are shared 3288among several IPv6-only clients. 3289When stateful NAT64 is used in conjunction with DNS64, no changes are usually 3290required in the IPv6 client or the IPv4 server. 3291The kernel module 3292.Cm ipfw_nat64 3293should be loaded or kernel should have 3294.Cm options IPFIREWALL_NAT64 3295to be able use stateful NAT64 translator. 3296.Pp 3297Stateful NAT64 uses a bunch of memory for several types of objects. 3298When IPv6 client initiates connection, NAT64 translator creates a host entry 3299in the states table. 3300Each host entry has a number of ports group entries allocated on demand. 3301Ports group entries contains connection state entries. 3302There are several options to control limits and lifetime for these objects. 3303.Pp 3304NAT64 translator follows RFC7915 when does ICMPv6/ICMP translation, 3305unsupported message types will be silently dropped. 3306IPv6 needs several ICMPv6 message types to be explicitly allowed for correct 3307operation. 3308Make sure that ND6 neighbor solicitation (ICMPv6 type 135) and neighbor 3309advertisement (ICMPv6 type 136) messages will not be handled by translation 3310rules. 3311.Pp 3312After translation NAT64 translator by default sends packets through 3313corresponding netisr queue. 3314Thus translator host should be configured as IPv4 and IPv6 router. 3315Also this means, that a packet is handled by firewall twice. 3316First time an original packet is handled and consumed by translator, 3317and then it is handled again as translated packet. 3318This behavior can be changed by sysctl variable 3319.Va net.inet.ip.fw.nat64_direct_output . 3320.Pp 3321The stateful NAT64 configuration command is the following: 3322.Bd -ragged -offset indent 3323.Bk -words 3324.Cm nat64lsn 3325.Ar name 3326.Cm create 3327.Ar create-options 3328.Ek 3329.Ed 3330.Pp 3331The following parameters can be configured: 3332.Bl -tag -width indent 3333.It Cm prefix4 Ar ipv4_prefix/plen 3334The IPv4 prefix with mask defines the pool of IPv4 addresses used as 3335source address after translation. 3336Stateful NAT64 module translates IPv6 source address of client to one 3337IPv4 address from this pool. 3338Note that incoming IPv4 packets that don't have corresponding state entry 3339in the states table will be dropped by translator. 3340Make sure that translation rules handle packets, destined to configured prefix. 3341.It Cm prefix6 Ar ipv6_prefix/length 3342The IPv6 prefix defines IPv4-embedded IPv6 addresses used by translator 3343to represent IPv4 addresses. This IPv6 prefix should be configured in DNS64. 3344The translator implementation follows RFC6052, that restricts the length of 3345prefixes to one of following: 32, 40, 48, 56, 64, or 96. 3346The Well-Known IPv6 Prefix 64:ff9b:: must be 96 bits long. 3347.It Cm max_ports Ar number 3348Maximum number of ports reserved for upper level protocols to one IPv6 client. 3349All reserved ports are divided into chunks between supported protocols. 3350The number of connections from one IPv6 client is limited by this option. 3351Note that closed TCP connections still remain in the list of connections until 3352.Cm tcp_close_age 3353interval will not expire. 3354Default value is 3355.Ar 2048 . 3356.It Cm host_del_age Ar seconds 3357The number of seconds until the host entry for a IPv6 client will be deleted 3358and all its resources will be released due to inactivity. 3359Default value is 3360.Ar 3600 . 3361.It Cm pg_del_age Ar seconds 3362The number of seconds until a ports group with unused state entries will 3363be released. 3364Default value is 3365.Ar 900 . 3366.It Cm tcp_syn_age Ar seconds 3367The number of seconds while a state entry for TCP connection with only SYN 3368sent will be kept. 3369If TCP connection establishing will not be finished, 3370state entry will be deleted. 3371Default value is 3372.Ar 10 . 3373.It Cm tcp_est_age Ar seconds 3374The number of seconds while a state entry for established TCP connection 3375will be kept. 3376Default value is 3377.Ar 7200 . 3378.It Cm tcp_close_age Ar seconds 3379The number of seconds while a state entry for closed TCP connection 3380will be kept. 3381Keeping state entries for closed connections is needed, because IPv4 servers 3382typically keep closed connections in a TIME_WAIT state for a several minutes. 3383Since translator's IPv4 addresses are shared among all IPv6 clients, 3384new connections from the same addresses and ports may be rejected by server, 3385because these connections are still in a TIME_WAIT state. 3386Keeping them in translator's state table protects from such rejects. 3387Default value is 3388.Ar 180 . 3389.It Cm udp_age Ar seconds 3390The number of seconds while translator keeps state entry in a waiting for 3391reply to the sent UDP datagram. 3392Default value is 3393.Ar 120 . 3394.It Cm icmp_age Ar seconds 3395The number of seconds while translator keeps state entry in a waiting for 3396reply to the sent ICMP message. 3397Default value is 3398.Ar 60 . 3399.It Cm log 3400Turn on logging of all handled packets via BPF through 3401.Ar ipfwlog0 3402interface. 3403.Ar ipfwlog0 3404is a pseudo interface and can be created after a boot manually with 3405.Cm ifconfig 3406command. 3407Note that it has different purpose than 3408.Ar ipfw0 3409interface. 3410Translators sends to BPF an additional information with each packet. 3411With 3412.Cm tcpdump 3413you are able to see each handled packet before and after translation. 3414.It Cm -log 3415Turn off logging of all handled packets via BPF. 3416.El 3417.Pp 3418To inspect a states table of stateful NAT64 the following command can be used: 3419.Bd -ragged -offset indent 3420.Bk -words 3421.Cm nat64lsn 3422.Ar name 3423.Cm show Cm states 3424.Ek 3425.Ed 3426.Pp 3427.Pp 3428Stateless NAT64 translator doesn't use a states table for translation 3429and converts IPv4 addresses to IPv6 and vice versa solely based on the 3430mappings taken from configured lookup tables. 3431Since a states table doesn't used by stateless translator, 3432it can be configured to pass IPv4 clients to IPv6-only servers. 3433.Pp 3434The stateless NAT64 configuration command is the following: 3435.Bd -ragged -offset indent 3436.Bk -words 3437.Cm nat64stl 3438.Ar name 3439.Cm create 3440.Ar create-options 3441.Ek 3442.Ed 3443.Pp 3444The following parameters can be configured: 3445.Bl -tag -width indent 3446.It Cm prefix6 Ar ipv6_prefix/length 3447The IPv6 prefix defines IPv4-embedded IPv6 addresses used by translator 3448to represent IPv4 addresses. This IPv6 prefix should be configured in DNS64. 3449.It Cm table4 Ar table46 3450The lookup table 3451.Ar table46 3452contains mapping how IPv4 addresses should be translated to IPv6 addresses. 3453.It Cm table6 Ar table64 3454The lookup table 3455.Ar table64 3456contains mapping how IPv6 addresses should be translated to IPv4 addresses. 3457.It Cm log 3458Turn on logging of all handled packets via BPF through 3459.Ar ipfwlog0 3460interface. 3461.It Cm -log 3462Turn off logging of all handled packets via BPF. 3463.El 3464.Pp 3465Note that the behavior of stateless translator with respect to not matched 3466packets differs from stateful translator. 3467If corresponding addresses was not found in the lookup tables, the packet 3468will not be dropped and the search continues. 3469.Sh IPv6-to-IPv6 NETWORK PREFIX TRANSLATION (NPTv6) 3470.Nm 3471supports in-kernel IPv6-to-IPv6 network prefix translation as described 3472in RFC6296. 3473The kernel module 3474.Cm ipfw_nptv6 3475should be loaded or kernel should has 3476.Cm options IPFIREWALL_NPTV6 3477to be able use NPTv6 translator. 3478.Pp 3479The NPTv6 configuration command is the following: 3480.Bd -ragged -offset indent 3481.Bk -words 3482.Cm nptv6 3483.Ar name 3484.Cm create 3485.Ar create-options 3486.Ek 3487.Ed 3488.Pp 3489The following parameters can be configured: 3490.Bl -tag -width indent 3491.It Cm int_prefix Ar ipv6_prefix 3492IPv6 prefix used in internal network. 3493NPTv6 module translates source address when it matches this prefix. 3494.It Cm ext_prefix Ar ipv6_prefix 3495IPv6 prefix used in external network. 3496NPTv6 module translates destination address when it matches this prefix. 3497.It Cm ext_if Ar nic 3498The NPTv6 module will use first global IPv6 address from interface 3499.Ar nic 3500as external prefix. 3501It can be useful when IPv6 prefix of external network is dynamically obtained. 3502.Cm ext_prefix 3503and 3504.Cm ext_if 3505options are mutually exclusive. 3506.It Cm prefixlen Ar length 3507The length of specified IPv6 prefixes. It must be in range from 8 to 64. 3508.El 3509.Pp 3510Note that the prefix translation rules are silently ignored when IPv6 packet 3511forwarding is disabled. 3512To enable the packet forwarding, set the sysctl variable 3513.Va net.inet6.ip6.forwarding 3514to 1. 3515.Pp 3516To let the packet continue after being translated, set the sysctl variable 3517.Va net.inet.ip.fw.one_pass 3518to 0. 3519.Sh LOADER TUNABLES 3520Tunables can be set in 3521.Xr loader 8 3522prompt, 3523.Xr loader.conf 5 3524or 3525.Xr kenv 1 3526before ipfw module gets loaded. 3527.Bl -tag -width indent 3528.It Va net.inet.ip.fw.default_to_accept: No 0 3529Defines ipfw last rule behavior. 3530This value overrides 3531.Cd "options IPFW_DEFAULT_TO_(ACCEPT|DENY)" 3532from kernel configuration file. 3533.It Va net.inet.ip.fw.tables_max: No 128 3534Defines number of tables available in ipfw. 3535Number cannot exceed 65534. 3536.El 3537.Sh SYSCTL VARIABLES 3538A set of 3539.Xr sysctl 8 3540variables controls the behaviour of the firewall and 3541associated modules 3542.Pq Nm dummynet , bridge , sctp nat . 3543These are shown below together with their default value 3544(but always check with the 3545.Xr sysctl 8 3546command what value is actually in use) and meaning: 3547.Bl -tag -width indent 3548.It Va net.inet.ip.alias.sctp.accept_global_ootb_addip: No 0 3549Defines how the 3550.Nm nat 3551responds to receipt of global OOTB ASCONF-AddIP: 3552.Bl -tag -width indent 3553.It Cm 0 3554No response (unless a partially matching association exists - 3555ports and vtags match but global address does not) 3556.It Cm 1 3557.Nm nat 3558will accept and process all OOTB global AddIP messages. 3559.El 3560.Pp 3561Option 1 should never be selected as this forms a security risk. 3562An attacker can 3563establish multiple fake associations by sending AddIP messages. 3564.It Va net.inet.ip.alias.sctp.chunk_proc_limit: No 5 3565Defines the maximum number of chunks in an SCTP packet that will be 3566parsed for a 3567packet that matches an existing association. 3568This value is enforced to be greater or equal than 3569.Cm net.inet.ip.alias.sctp.initialising_chunk_proc_limit . 3570A high value is 3571a DoS risk yet setting too low a value may result in 3572important control chunks in 3573the packet not being located and parsed. 3574.It Va net.inet.ip.alias.sctp.error_on_ootb: No 1 3575Defines when the 3576.Nm nat 3577responds to any Out-of-the-Blue (OOTB) packets with ErrorM packets. 3578An OOTB packet is a packet that arrives with no existing association 3579registered in the 3580.Nm nat 3581and is not an INIT or ASCONF-AddIP packet: 3582.Bl -tag -width indent 3583.It Cm 0 3584ErrorM is never sent in response to OOTB packets. 3585.It Cm 1 3586ErrorM is only sent to OOTB packets received on the local side. 3587.It Cm 2 3588ErrorM is sent to the local side and on the global side ONLY if there is a 3589partial match (ports and vtags match but the source global IP does not). 3590This value is only useful if the 3591.Nm nat 3592is tracking global IP addresses. 3593.It Cm 3 3594ErrorM is sent in response to all OOTB packets on both 3595the local and global side 3596(DoS risk). 3597.El 3598.Pp 3599At the moment the default is 0, since the ErrorM packet is not yet 3600supported by most SCTP stacks. 3601When it is supported, and if not tracking 3602global addresses, we recommend setting this value to 1 to allow 3603multi-homed local hosts to function with the 3604.Nm nat . 3605To track global addresses, we recommend setting this value to 2 to 3606allow global hosts to be informed when they need to (re)send an 3607ASCONF-AddIP. 3608Value 3 should never be chosen (except for debugging) as the 3609.Nm nat 3610will respond to all OOTB global packets (a DoS risk). 3611.It Va net.inet.ip.alias.sctp.hashtable_size: No 2003 3612Size of hash tables used for 3613.Nm nat 3614lookups (100 < prime_number > 1000001). 3615This value sets the 3616.Nm hash table 3617size for any future created 3618.Nm nat 3619instance and therefore must be set prior to creating a 3620.Nm nat 3621instance. 3622The table sizes may be changed to suit specific needs. 3623If there will be few 3624concurrent associations, and memory is scarce, you may make these smaller. 3625If there will be many thousands (or millions) of concurrent associations, you 3626should make these larger. 3627A prime number is best for the table size. 3628The sysctl 3629update function will adjust your input value to the next highest prime number. 3630.It Va net.inet.ip.alias.sctp.holddown_time: No 0 3631Hold association in table for this many seconds after receiving a 3632SHUTDOWN-COMPLETE. 3633This allows endpoints to correct shutdown gracefully if a 3634shutdown_complete is lost and retransmissions are required. 3635.It Va net.inet.ip.alias.sctp.init_timer: No 15 3636Timeout value while waiting for (INIT-ACK|AddIP-ACK). 3637This value cannot be 0. 3638.It Va net.inet.ip.alias.sctp.initialising_chunk_proc_limit: No 2 3639Defines the maximum number of chunks in an SCTP packet that will be parsed when 3640no existing association exists that matches that packet. 3641Ideally this packet 3642will only be an INIT or ASCONF-AddIP packet. 3643A higher value may become a DoS 3644risk as malformed packets can consume processing resources. 3645.It Va net.inet.ip.alias.sctp.param_proc_limit: No 25 3646Defines the maximum number of parameters within a chunk that will be 3647parsed in a 3648packet. 3649As for other similar sysctl variables, larger values pose a DoS risk. 3650.It Va net.inet.ip.alias.sctp.log_level: No 0 3651Level of detail in the system log messages (0 \- minimal, 1 \- event, 36522 \- info, 3 \- detail, 4 \- debug, 5 \- max debug). 3653May be a good 3654option in high loss environments. 3655.It Va net.inet.ip.alias.sctp.shutdown_time: No 15 3656Timeout value while waiting for SHUTDOWN-COMPLETE. 3657This value cannot be 0. 3658.It Va net.inet.ip.alias.sctp.track_global_addresses: No 0 3659Enables/disables global IP address tracking within the 3660.Nm nat 3661and places an 3662upper limit on the number of addresses tracked for each association: 3663.Bl -tag -width indent 3664.It Cm 0 3665Global tracking is disabled 3666.It Cm >1 3667Enables tracking, the maximum number of addresses tracked for each 3668association is limited to this value 3669.El 3670.Pp 3671This variable is fully dynamic, the new value will be adopted for all newly 3672arriving associations, existing associations are treated 3673as they were previously. 3674Global tracking will decrease the number of collisions within the 3675.Nm nat 3676at a cost 3677of increased processing load, memory usage, complexity, and possible 3678.Nm nat 3679state 3680problems in complex networks with multiple 3681.Nm nats . 3682We recommend not tracking 3683global IP addresses, this will still result in a fully functional 3684.Nm nat . 3685.It Va net.inet.ip.alias.sctp.up_timer: No 300 3686Timeout value to keep an association up with no traffic. 3687This value cannot be 0. 3688.It Va net.inet.ip.dummynet.codel.interval : No 100000 3689Default 3690.Cm codel 3691AQM interval in microseconds. 3692The value must be in the range 1..5000000. 3693.It Va net.inet.ip.dummynet.codel.target : No 5000 3694Default 3695.Cm codel 3696AQM target delay time in microseconds (the minimum acceptable persistent queue 3697delay). 3698The value must be in the range 1..5000000. 3699.It Va net.inet.ip.dummynet.expire : No 1 3700Lazily delete dynamic pipes/queue once they have no pending traffic. 3701You can disable this by setting the variable to 0, in which case 3702the pipes/queues will only be deleted when the threshold is reached. 3703.It Va net.inet.ip.dummynet.fqcodel.flows : No 1024 3704Defines the default total number of flow queues (sub-queues) that 3705.Cm fq_codel 3706creates and manages. 3707The value must be in the range 1..65536. 3708.It Va net.inet.ip.dummynet.fqcodel.interval : No 100000 3709Default 3710.Cm fq_codel 3711scheduler/AQM interval in microseconds. 3712The value must be in the range 1..5000000. 3713.It Va net.inet.ip.dummynet.fqcodel.limit : No 10240 3714The default hard size limit (in unit of packet) of all queues managed by an 3715instance of the 3716.Cm fq_codel 3717scheduler. 3718The value must be in the range 1..20480. 3719.It Va net.inet.ip.dummynet.fqcodel.quantum : No 1514 3720The default quantum (credit) of the 3721.Cm fq_codel 3722in unit of byte. 3723The value must be in the range 1..9000. 3724.It Va net.inet.ip.dummynet.fqcodel.target : No 5000 3725Default 3726.Cm fq_codel 3727scheduler/AQM target delay time in microseconds (the minimum acceptable 3728persistent queue delay). 3729The value must be in the range 1..5000000. 3730.It Va net.inet.ip.dummynet.fqpie.alpha : No 125 3731The default 3732.Ar alpha 3733parameter (scaled by 1000) for 3734.Cm fq_pie 3735scheduler/AQM. 3736The value must be in the range 1..7000. 3737.It Va net.inet.ip.dummynet.fqpie.beta : No 1250 3738The default 3739.Ar beta 3740parameter (scaled by 1000) for 3741.Cm fq_pie 3742scheduler/AQM. 3743The value must be in the range 1..7000. 3744.It Va net.inet.ip.dummynet.fqpie.flows : No 1024 3745Defines the default total number of flow queues (sub-queues) that 3746.Cm fq_pie 3747creates and manages. 3748The value must be in the range 1..65536. 3749.It Va net.inet.ip.dummynet.fqpie.limit : No 10240 3750The default hard size limit (in unit of packet) of all queues managed by an 3751instance of the 3752.Cm fq_pie 3753scheduler. 3754The value must be in the range 1..20480. 3755.It Va net.inet.ip.dummynet.fqpie.max_burst : No 150000 3756The default maximum period of microseconds that 3757.Cm fq_pie 3758scheduler/AQM does not drop/mark packets. 3759The value must be in the range 1..10000000. 3760.It Va net.inet.ip.dummynet.fqpie.max_ecnth : No 99 3761The default maximum ECN probability threshold (scaled by 1000) for 3762.Cm fq_pie 3763scheduler/AQM. 3764The value must be in the range 1..7000. 3765.It Va net.inet.ip.dummynet.fqpie.quantum : No 1514 3766The default quantum (credit) of the 3767.Cm fq_pie 3768in unit of byte. 3769The value must be in the range 1..9000. 3770.It Va net.inet.ip.dummynet.fqpie.target : No 15000 3771The default 3772.Cm target 3773delay of the 3774.Cm fq_pie 3775in unit of microsecond. 3776The value must be in the range 1..5000000. 3777.It Va net.inet.ip.dummynet.fqpie.tupdate : No 15000 3778The default 3779.Cm tupdate 3780of the 3781.Cm fq_pie 3782in unit of microsecond. 3783The value must be in the range 1..5000000. 3784.It Va net.inet.ip.dummynet.hash_size : No 64 3785Default size of the hash table used for dynamic pipes/queues. 3786This value is used when no 3787.Cm buckets 3788option is specified when configuring a pipe/queue. 3789.It Va net.inet.ip.dummynet.io_fast : No 0 3790If set to a non-zero value, 3791the 3792.Dq fast 3793mode of 3794.Nm dummynet 3795operation (see above) is enabled. 3796.It Va net.inet.ip.dummynet.io_pkt 3797Number of packets passed to 3798.Nm dummynet . 3799.It Va net.inet.ip.dummynet.io_pkt_drop 3800Number of packets dropped by 3801.Nm dummynet . 3802.It Va net.inet.ip.dummynet.io_pkt_fast 3803Number of packets bypassed by the 3804.Nm dummynet 3805scheduler. 3806.It Va net.inet.ip.dummynet.max_chain_len : No 16 3807Target value for the maximum number of pipes/queues in a hash bucket. 3808The product 3809.Cm max_chain_len*hash_size 3810is used to determine the threshold over which empty pipes/queues 3811will be expired even when 3812.Cm net.inet.ip.dummynet.expire=0 . 3813.It Va net.inet.ip.dummynet.red_lookup_depth : No 256 3814.It Va net.inet.ip.dummynet.red_avg_pkt_size : No 512 3815.It Va net.inet.ip.dummynet.red_max_pkt_size : No 1500 3816Parameters used in the computations of the drop probability 3817for the RED algorithm. 3818.It Va net.inet.ip.dummynet.pie.alpha : No 125 3819The default 3820.Ar alpha 3821parameter (scaled by 1000) for 3822.Cm pie 3823AQM. 3824The value must be in the range 1..7000. 3825.It Va net.inet.ip.dummynet.pie.beta : No 1250 3826The default 3827.Ar beta 3828parameter (scaled by 1000) for 3829.Cm pie 3830AQM. 3831The value must be in the range 1..7000. 3832.It Va net.inet.ip.dummynet.pie.max_burst : No 150000 3833The default maximum period of microseconds that 3834.Cm pie 3835AQM does not drop/mark packets. 3836The value must be in the range 1..10000000. 3837.It Va net.inet.ip.dummynet.pie.max_ecnth : No 99 3838The default maximum ECN probability threshold (scaled by 1000) for 3839.Cm pie 3840AQM. 3841The value must be in the range 1..7000. 3842.It Va net.inet.ip.dummynet.pie.target : No 15000 3843The default 3844.Cm target 3845delay of 3846.Cm pie 3847AQM in unit of microsecond. 3848The value must be in the range 1..5000000. 3849.It Va net.inet.ip.dummynet.pie.tupdate : No 15000 3850The default 3851.Cm tupdate 3852of 3853.Cm pie 3854AQM in unit of microsecond. 3855The value must be in the range 1..5000000. 3856.It Va net.inet.ip.dummynet.pipe_byte_limit : No 1048576 3857.It Va net.inet.ip.dummynet.pipe_slot_limit : No 100 3858The maximum queue size that can be specified in bytes or packets. 3859These limits prevent accidental exhaustion of resources such as mbufs. 3860If you raise these limits, 3861you should make sure the system is configured so that sufficient resources 3862are available. 3863.It Va net.inet.ip.fw.autoinc_step : No 100 3864Delta between rule numbers when auto-generating them. 3865The value must be in the range 1..1000. 3866.It Va net.inet.ip.fw.curr_dyn_buckets : Va net.inet.ip.fw.dyn_buckets 3867The current number of buckets in the hash table for dynamic rules 3868(readonly). 3869.It Va net.inet.ip.fw.debug : No 1 3870Controls debugging messages produced by 3871.Nm . 3872.It Va net.inet.ip.fw.default_rule : No 65535 3873The default rule number (read-only). 3874By the design of 3875.Nm , the default rule is the last one, so its number 3876can also serve as the highest number allowed for a rule. 3877.It Va net.inet.ip.fw.dyn_buckets : No 256 3878The number of buckets in the hash table for dynamic rules. 3879Must be a power of 2, up to 65536. 3880It only takes effect when all dynamic rules have expired, so you 3881are advised to use a 3882.Cm flush 3883command to make sure that the hash table is resized. 3884.It Va net.inet.ip.fw.dyn_count : No 3 3885Current number of dynamic rules 3886(read-only). 3887.It Va net.inet.ip.fw.dyn_keepalive : No 1 3888Enables generation of keepalive packets for 3889.Cm keep-state 3890rules on TCP sessions. 3891A keepalive is generated to both 3892sides of the connection every 5 seconds for the last 20 3893seconds of the lifetime of the rule. 3894.It Va net.inet.ip.fw.dyn_max : No 8192 3895Maximum number of dynamic rules. 3896When you hit this limit, no more dynamic rules can be 3897installed until old ones expire. 3898.It Va net.inet.ip.fw.dyn_ack_lifetime : No 300 3899.It Va net.inet.ip.fw.dyn_syn_lifetime : No 20 3900.It Va net.inet.ip.fw.dyn_fin_lifetime : No 1 3901.It Va net.inet.ip.fw.dyn_rst_lifetime : No 1 3902.It Va net.inet.ip.fw.dyn_udp_lifetime : No 5 3903.It Va net.inet.ip.fw.dyn_short_lifetime : No 30 3904These variables control the lifetime, in seconds, of dynamic 3905rules. 3906Upon the initial SYN exchange the lifetime is kept short, 3907then increased after both SYN have been seen, then decreased 3908again during the final FIN exchange or when a RST is received. 3909Both 3910.Em dyn_fin_lifetime 3911and 3912.Em dyn_rst_lifetime 3913must be strictly lower than 5 seconds, the period of 3914repetition of keepalives. 3915The firewall enforces that. 3916.It Va net.inet.ip.fw.dyn_keep_states: No 0 3917Keep dynamic states on rule/set deletion. 3918States are relinked to default rule (65535). 3919This can be handly for ruleset reload. 3920Turned off by default. 3921.It Va net.inet.ip.fw.enable : No 1 3922Enables the firewall. 3923Setting this variable to 0 lets you run your machine without 3924firewall even if compiled in. 3925.It Va net.inet6.ip6.fw.enable : No 1 3926provides the same functionality as above for the IPv6 case. 3927.It Va net.inet.ip.fw.one_pass : No 1 3928When set, the packet exiting from the 3929.Nm dummynet 3930pipe or from 3931.Xr ng_ipfw 4 3932node is not passed though the firewall again. 3933Otherwise, after an action, the packet is 3934reinjected into the firewall at the next rule. 3935.It Va net.inet.ip.fw.tables_max : No 128 3936Maximum number of tables. 3937.It Va net.inet.ip.fw.verbose : No 1 3938Enables verbose messages. 3939.It Va net.inet.ip.fw.verbose_limit : No 0 3940Limits the number of messages produced by a verbose firewall. 3941.It Va net.inet6.ip6.fw.deny_unknown_exthdrs : No 1 3942If enabled packets with unknown IPv6 Extension Headers will be denied. 3943.It Va net.link.ether.ipfw : No 0 3944Controls whether layer-2 packets are passed to 3945.Nm . 3946Default is no. 3947.It Va net.link.bridge.ipfw : No 0 3948Controls whether bridged packets are passed to 3949.Nm . 3950Default is no. 3951.It Va net.inet.ip.fw.nat64_allow_private : No 0 3952Defines how 3953.Nm nat64 3954handles private IPv4 addresses: 3955.Bl -tag -width indent 3956.It Cm 0 3957Packets with private IPv4 will not be handled by translator 3958.It Cm 1 3959Translator will accept and process packets with private IPv4 addresses. 3960.El 3961.It Va net.inet.ip.fw.nat64_debug : No 0 3962Controls debugging messages produced by 3963.Nm ipfw_nat64 3964module. 3965.It Va net.inet.ip.fw.nat64_direct_output : No 0 3966Controls the output method used by 3967.Nm ipfw_nat64 3968module: 3969.Bl -tag -width indent 3970.It Cm 0 3971A packet is handled by 3972.Nm ipfw 3973twice. 3974First time an original packet is handled by 3975.Nm ipfw 3976and consumed by 3977.Nm ipfw_nat64 3978translator. 3979Then translated packet is queued via netisr to input processing again. 3980.It Cm 1 3981A packet is handled by 3982.Nm ipfw 3983only once, and after translation it will be pushed directly to outgoing 3984interface. 3985.El 3986.El 3987.Sh INTERNAL DIAGNOSTICS 3988There are some commands that may be useful to understand current state 3989of certain subsystems inside kernel module. 3990These commands provide debugging output which may change without notice. 3991.Pp 3992Currently the following commands are available as 3993.Cm internal 3994sub-options: 3995.Bl -tag -width indent 3996.It Cm iflist 3997Lists all interface which are currently tracked by 3998.Nm 3999with their in-kernel status. 4000.It Cm talist 4001List all table lookup algorithms currently available. 4002.El 4003.Sh EXAMPLES 4004There are far too many possible uses of 4005.Nm 4006so this Section will only give a small set of examples. 4007.Pp 4008.Ss BASIC PACKET FILTERING 4009This command adds an entry which denies all tcp packets from 4010.Em cracker.evil.org 4011to the telnet port of 4012.Em wolf.tambov.su 4013from being forwarded by the host: 4014.Pp 4015.Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet" 4016.Pp 4017This one disallows any connection from the entire cracker's 4018network to my host: 4019.Pp 4020.Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org" 4021.Pp 4022A first and efficient way to limit access (not using dynamic rules) 4023is the use of the following rules: 4024.Pp 4025.Dl "ipfw add allow tcp from any to any established" 4026.Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup" 4027.Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup" 4028.Dl "..." 4029.Dl "ipfw add deny tcp from any to any" 4030.Pp 4031The first rule will be a quick match for normal TCP packets, 4032but it will not match the initial SYN packet, which will be 4033matched by the 4034.Cm setup 4035rules only for selected source/destination pairs. 4036All other SYN packets will be rejected by the final 4037.Cm deny 4038rule. 4039.Pp 4040If you administer one or more subnets, you can take advantage 4041of the address sets and or-blocks and write extremely 4042compact rulesets which selectively enable services to blocks 4043of clients, as below: 4044.Pp 4045.Dl "goodguys=\*q{ 10.1.2.0/24{20,35,66,18} or 10.2.3.0/28{6,3,11} }\*q" 4046.Dl "badguys=\*q10.1.2.0/24{8,38,60}\*q" 4047.Dl "" 4048.Dl "ipfw add allow ip from ${goodguys} to any" 4049.Dl "ipfw add deny ip from ${badguys} to any" 4050.Dl "... normal policies ..." 4051.Pp 4052The 4053.Cm verrevpath 4054option could be used to do automated anti-spoofing by adding the 4055following to the top of a ruleset: 4056.Pp 4057.Dl "ipfw add deny ip from any to any not verrevpath in" 4058.Pp 4059This rule drops all incoming packets that appear to be coming to the 4060system on the wrong interface. 4061For example, a packet with a source 4062address belonging to a host on a protected internal network would be 4063dropped if it tried to enter the system from an external interface. 4064.Pp 4065The 4066.Cm antispoof 4067option could be used to do similar but more restricted anti-spoofing 4068by adding the following to the top of a ruleset: 4069.Pp 4070.Dl "ipfw add deny ip from any to any not antispoof in" 4071.Pp 4072This rule drops all incoming packets that appear to be coming from another 4073directly connected system but on the wrong interface. 4074For example, a packet with a source address of 4075.Li 192.168.0.0/24 , 4076configured on 4077.Li fxp0 , 4078but coming in on 4079.Li fxp1 4080would be dropped. 4081.Pp 4082The 4083.Cm setdscp 4084option could be used to (re)mark user traffic, 4085by adding the following to the appropriate place in ruleset: 4086.Pp 4087.Dl "ipfw add setdscp be ip from any to any dscp af11,af21" 4088.Ss SELECTIVE MIRRORING 4089If your network has network traffic analyzer 4090connected to your host directly via dedicated interface 4091or remotely via RSPAN vlan, you can selectively mirror 4092some Ethernet layer2 frames to the analyzer. 4093.Pp 4094First, make sure your firewall is already configured and runs. 4095Then, enable layer2 processing if not already enabled: 4096.Pp 4097.Dl "sysctl net.link.ether.ipfw=1" 4098.Pp 4099Next, load needed additional kernel modules: 4100.Pp 4101.Dl "kldload ng_ether ng_ipfw" 4102.Pp 4103Optionally, make system load these modules automatically 4104at startup: 4105.Pp 4106.Dl sysrc kld_list+="ng_ether ng_ipfw" 4107.Pp 4108Next, configure 4109.Xr ng_ipfw 4 4110kernel module to transmit mirrored copies of layer2 frames 4111out via vlan900 interface: 4112.Pp 4113.Dl "ngctl connect ipfw: vlan900: 1 lower" 4114.Pp 4115Think of "1" here as of "mirroring instance index" and vlan900 is its 4116destination. 4117You can have arbitrary number of instances. 4118Refer to 4119.Xr ng_ipfw 4 4120for details. 4121.Pp 4122At last, actually start mirroring of selected frames using "instance 1". 4123For frames incoming from em0 interface: 4124.Pp 4125.Dl "ipfw add ngtee 1 ip from any to 192.168.0.1 layer2 in recv em0" 4126.Pp 4127For frames outgoing to em0 interface: 4128.Pp 4129.Dl "ipfw add ngtee 1 ip from any to 192.168.0.1 layer2 out xmit em0" 4130.Pp 4131For both incoming and outgoing frames while flowing through em0: 4132.Pp 4133.Dl "ipfw add ngtee 1 ip from any to 192.168.0.1 layer2 via em0" 4134.Pp 4135Make sure you do not perform mirroring for already duplicated frames 4136or kernel may hang as there is no safety net. 4137.Ss DYNAMIC RULES 4138In order to protect a site from flood attacks involving fake 4139TCP packets, it is safer to use dynamic rules: 4140.Pp 4141.Dl "ipfw add check-state" 4142.Dl "ipfw add deny tcp from any to any established" 4143.Dl "ipfw add allow tcp from my-net to any setup keep-state" 4144.Pp 4145This will let the firewall install dynamic rules only for 4146those connection which start with a regular SYN packet coming 4147from the inside of our network. 4148Dynamic rules are checked when encountering the first 4149occurrence of a 4150.Cm check-state , 4151.Cm keep-state 4152or 4153.Cm limit 4154rule. 4155A 4156.Cm check-state 4157rule should usually be placed near the beginning of the 4158ruleset to minimize the amount of work scanning the ruleset. 4159Your mileage may vary. 4160.Pp 4161For more complex scenarios with dynamic rules 4162.Cm record-state 4163and 4164.Cm defer-action 4165can be used to precisely control creation and checking of dynamic rules. 4166Example of usage of these options are provided in 4167.Sx NETWORK ADDRESS TRANSLATION (NAT) 4168Section. 4169.Pp 4170To limit the number of connections a user can open 4171you can use the following type of rules: 4172.Pp 4173.Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10" 4174.Dl "ipfw add allow tcp from any to me setup limit src-addr 4" 4175.Pp 4176The former (assuming it runs on a gateway) will allow each host 4177on a /24 network to open at most 10 TCP connections. 4178The latter can be placed on a server to make sure that a single 4179client does not use more than 4 simultaneous connections. 4180.Pp 4181.Em BEWARE : 4182stateful rules can be subject to denial-of-service attacks 4183by a SYN-flood which opens a huge number of dynamic rules. 4184The effects of such attacks can be partially limited by 4185acting on a set of 4186.Xr sysctl 8 4187variables which control the operation of the firewall. 4188.Pp 4189Here is a good usage of the 4190.Cm list 4191command to see accounting records and timestamp information: 4192.Pp 4193.Dl ipfw -at list 4194.Pp 4195or in short form without timestamps: 4196.Pp 4197.Dl ipfw -a list 4198.Pp 4199which is equivalent to: 4200.Pp 4201.Dl ipfw show 4202.Pp 4203Next rule diverts all incoming packets from 192.168.2.0/24 4204to divert port 5000: 4205.Pp 4206.Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in 4207.Ss TRAFFIC SHAPING 4208The following rules show some of the applications of 4209.Nm 4210and 4211.Nm dummynet 4212for simulations and the like. 4213.Pp 4214This rule drops random incoming packets with a probability 4215of 5%: 4216.Pp 4217.Dl "ipfw add prob 0.05 deny ip from any to any in" 4218.Pp 4219A similar effect can be achieved making use of 4220.Nm dummynet 4221pipes: 4222.Pp 4223.Dl "ipfw add pipe 10 ip from any to any" 4224.Dl "ipfw pipe 10 config plr 0.05" 4225.Pp 4226We can use pipes to artificially limit bandwidth, e.g.\& on a 4227machine acting as a router, if we want to limit traffic from 4228local clients on 192.168.2.0/24 we do: 4229.Pp 4230.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 4231.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes" 4232.Pp 4233note that we use the 4234.Cm out 4235modifier so that the rule is not used twice. 4236Remember in fact that 4237.Nm 4238rules are checked both on incoming and outgoing packets. 4239.Pp 4240Should we want to simulate a bidirectional link with bandwidth 4241limitations, the correct way is the following: 4242.Pp 4243.Dl "ipfw add pipe 1 ip from any to any out" 4244.Dl "ipfw add pipe 2 ip from any to any in" 4245.Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes" 4246.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes" 4247.Pp 4248The above can be very useful, e.g.\& if you want to see how 4249your fancy Web page will look for a residential user who 4250is connected only through a slow link. 4251You should not use only one pipe for both directions, unless 4252you want to simulate a half-duplex medium (e.g.\& AppleTalk, 4253Ethernet, IRDA). 4254It is not necessary that both pipes have the same configuration, 4255so we can also simulate asymmetric links. 4256.Pp 4257Should we want to verify network performance with the RED queue 4258management algorithm: 4259.Pp 4260.Dl "ipfw add pipe 1 ip from any to any" 4261.Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1" 4262.Pp 4263Another typical application of the traffic shaper is to 4264introduce some delay in the communication. 4265This can significantly affect applications which do a lot of Remote 4266Procedure Calls, and where the round-trip-time of the 4267connection often becomes a limiting factor much more than 4268bandwidth: 4269.Pp 4270.Dl "ipfw add pipe 1 ip from any to any out" 4271.Dl "ipfw add pipe 2 ip from any to any in" 4272.Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s" 4273.Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s" 4274.Pp 4275Per-flow queueing can be useful for a variety of purposes. 4276A very simple one is counting traffic: 4277.Pp 4278.Dl "ipfw add pipe 1 tcp from any to any" 4279.Dl "ipfw add pipe 1 udp from any to any" 4280.Dl "ipfw add pipe 1 ip from any to any" 4281.Dl "ipfw pipe 1 config mask all" 4282.Pp 4283The above set of rules will create queues (and collect 4284statistics) for all traffic. 4285Because the pipes have no limitations, the only effect is 4286collecting statistics. 4287Note that we need 3 rules, not just the last one, because 4288when 4289.Nm 4290tries to match IP packets it will not consider ports, so we 4291would not see connections on separate ports as different 4292ones. 4293.Pp 4294A more sophisticated example is limiting the outbound traffic 4295on a net with per-host limits, rather than per-network limits: 4296.Pp 4297.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 4298.Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in" 4299.Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 4300.Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 4301.Ss LOOKUP TABLES 4302In the following example, we need to create several traffic bandwidth 4303classes and we need different hosts/networks to fall into different classes. 4304We create one pipe for each class and configure them accordingly. 4305Then we create a single table and fill it with IP subnets and addresses. 4306For each subnet/host we set the argument equal to the number of the pipe 4307that it should use. 4308Then we classify traffic using a single rule: 4309.Pp 4310.Dl "ipfw pipe 1 config bw 1000Kbyte/s" 4311.Dl "ipfw pipe 4 config bw 4000Kbyte/s" 4312.Dl "..." 4313.Dl "ipfw table T1 create type addr" 4314.Dl "ipfw table T1 add 192.168.2.0/24 1" 4315.Dl "ipfw table T1 add 192.168.0.0/27 4" 4316.Dl "ipfw table T1 add 192.168.0.2 1" 4317.Dl "..." 4318.Dl "ipfw add pipe tablearg ip from 'table(T1)' to any" 4319.Pp 4320Using the 4321.Cm fwd 4322action, the table entries may include hostnames and IP addresses. 4323.Pp 4324.Dl "ipfw table T2 create type addr ftype ip" 4325.Dl "ipfw table T2 add 192.168.2.0/24 10.23.2.1" 4326.Dl "ipfw table T21 add 192.168.0.0/27 router1.dmz" 4327.Dl "..." 4328.Dl "ipfw add 100 fwd tablearg ip from any to table(1)" 4329.Pp 4330In the following example per-interface firewall is created: 4331.Pp 4332.Dl "ipfw table IN create type iface valtype skipto,fib" 4333.Dl "ipfw table IN add vlan20 12000,12" 4334.Dl "ipfw table IN add vlan30 13000,13" 4335.Dl "ipfw table OUT create type iface valtype skipto" 4336.Dl "ipfw table OUT add vlan20 22000" 4337.Dl "ipfw table OUT add vlan30 23000" 4338.Dl ".." 4339.Dl "ipfw add 100 setfib tablearg ip from any to any recv 'table(IN)' in" 4340.Dl "ipfw add 200 skipto tablearg ip from any to any recv 'table(IN)' in" 4341.Dl "ipfw add 300 skipto tablearg ip from any to any xmit 'table(OUT)' out" 4342.Pp 4343The following example illustrate usage of flow tables: 4344.Pp 4345.Dl "ipfw table fl create type flow:src-ip,proto,dst-ip,dst-port" 4346.Dl "ipfw table fl add 2a02:6b8:77::88,tcp,2a02:6b8:77::99,80 11" 4347.Dl "ipfw table fl add 10.0.0.1,udp,10.0.0.2,53 12" 4348.Dl ".." 4349.Dl "ipfw add 100 allow ip from any to any flow 'table(fl,11)' recv ix0" 4350.Ss SETS OF RULES 4351To add a set of rules atomically, e.g.\& set 18: 4352.Pp 4353.Dl "ipfw set disable 18" 4354.Dl "ipfw add NN set 18 ... # repeat as needed" 4355.Dl "ipfw set enable 18" 4356.Pp 4357To delete a set of rules atomically the command is simply: 4358.Pp 4359.Dl "ipfw delete set 18" 4360.Pp 4361To test a ruleset and disable it and regain control if something goes wrong: 4362.Pp 4363.Dl "ipfw set disable 18" 4364.Dl "ipfw add NN set 18 ... # repeat as needed" 4365.Dl "ipfw set enable 18; echo done; sleep 30 && ipfw set disable 18" 4366.Pp 4367Here if everything goes well, you press control-C before the "sleep" 4368terminates, and your ruleset will be left active. 4369Otherwise, e.g.\& if 4370you cannot access your box, the ruleset will be disabled after 4371the sleep terminates thus restoring the previous situation. 4372.Pp 4373To show rules of the specific set: 4374.Pp 4375.Dl "ipfw set 18 show" 4376.Pp 4377To show rules of the disabled set: 4378.Pp 4379.Dl "ipfw -S set 18 show" 4380.Pp 4381To clear a specific rule counters of the specific set: 4382.Pp 4383.Dl "ipfw set 18 zero NN" 4384.Pp 4385To delete a specific rule of the specific set: 4386.Pp 4387.Dl "ipfw set 18 delete NN" 4388.Ss NAT, REDIRECT AND LSNAT 4389First redirect all the traffic to nat instance 123: 4390.Pp 4391.Dl "ipfw add nat 123 all from any to any" 4392.Pp 4393Then to configure nat instance 123 to alias all the outgoing traffic with ip 4394192.168.0.123, blocking all incoming connections, trying to keep 4395same ports on both sides, clearing aliasing table on address change 4396and keeping a log of traffic/link statistics: 4397.Pp 4398.Dl "ipfw nat 123 config ip 192.168.0.123 log deny_in reset same_ports" 4399.Pp 4400Or to change address of instance 123, aliasing table will be cleared (see 4401reset option): 4402.Pp 4403.Dl "ipfw nat 123 config ip 10.0.0.1" 4404.Pp 4405To see configuration of nat instance 123: 4406.Pp 4407.Dl "ipfw nat 123 show config" 4408.Pp 4409To show logs of all the instances in range 111-999: 4410.Pp 4411.Dl "ipfw nat 111-999 show" 4412.Pp 4413To see configurations of all instances: 4414.Pp 4415.Dl "ipfw nat show config" 4416.Pp 4417Or a redirect rule with mixed modes could looks like: 4418.Pp 4419.Dl "ipfw nat 123 config redirect_addr 10.0.0.1 10.0.0.66" 4420.Dl " redirect_port tcp 192.168.0.1:80 500" 4421.Dl " redirect_proto udp 192.168.1.43 192.168.1.1" 4422.Dl " redirect_addr 192.168.0.10,192.168.0.11" 4423.Dl " 10.0.0.100 # LSNAT" 4424.Dl " redirect_port tcp 192.168.0.1:80,192.168.0.10:22" 4425.Dl " 500 # LSNAT" 4426.Pp 4427or it could be split in: 4428.Pp 4429.Dl "ipfw nat 1 config redirect_addr 10.0.0.1 10.0.0.66" 4430.Dl "ipfw nat 2 config redirect_port tcp 192.168.0.1:80 500" 4431.Dl "ipfw nat 3 config redirect_proto udp 192.168.1.43 192.168.1.1" 4432.Dl "ipfw nat 4 config redirect_addr 192.168.0.10,192.168.0.11,192.168.0.12" 4433.Dl " 10.0.0.100" 4434.Dl "ipfw nat 5 config redirect_port tcp" 4435.Dl " 192.168.0.1:80,192.168.0.10:22,192.168.0.20:25 500" 4436.Pp 4437Sometimes you may want to mix NAT and dynamic rules. It could be achieved with 4438.Cm record-state 4439and 4440.Cm defer-action 4441options. Problem is, you need to create dynamic rule before NAT and check it 4442after NAT actions (or vice versa) to have consistent addresses and ports. 4443Rule with 4444.Cm keep-state 4445option will trigger activation of existing dynamic state, and action of such 4446rule will be performed as soon as rule is matched. In case of NAT and 4447.Cm allow 4448rule packet need to be passed to NAT, not allowed as soon is possible. 4449.Pp 4450There is example of set of rules to achieve this. Bear in mind that this 4451is exmaple only and it is not very useful by itself. 4452.Pp 4453On way out, after all checks place this rules: 4454.Pp 4455.Dl "ipfw add allow record-state skip-action" 4456.Dl "ipfw add nat 1" 4457.Pp 4458And on way in there should be something like this: 4459.Pp 4460.Dl "ipfw add nat 1" 4461.Dl "ipfw add check-state" 4462.Pp 4463Please note, that first rule on way out doesn't allow packet and doesn't 4464execute existing dynamic rules. All it does, create new dynamic rule with 4465.Cm allow 4466action, if it is not created yet. Later, this dynamic rule is used on way 4467in by 4468.Cm check-state 4469rule. 4470.Ss CONFIGURING CODEL, PIE, FQ-CODEL and FQ-PIE AQM 4471.Cm codel 4472and 4473.Cm pie 4474AQM can be configured for 4475.Nm dummynet 4476.Cm pipe 4477or 4478.Cm queue. 4479.Pp 4480To configure a 4481.Cm pipe 4482with 4483.Cm codel 4484AQM using default configuration for traffic from 192.168.0.0/24 and 1Mbits/s 4485rate limit, we do: 4486.Pp 4487.Dl "ipfw pipe 1 config bw 1mbits/s codel" 4488.Dl "ipfw add 100 pipe 1 ip from 192.168.0.0/24 to any" 4489.Pp 4490To configure a 4491.Cm queue 4492with 4493.Cm codel 4494AQM using different configurations parameters for traffic from 4495192.168.0.0/24 and 1Mbits/s rate limit, we do: 4496.Pp 4497.Dl "ipfw pipe 1 config bw 1mbits/s" 4498.Dl "ipfw queue 1 config pipe 1 codel target 8ms interval 160ms ecn" 4499.Dl "ipfw add 100 queue 1 ip from 192.168.0.0/24 to any" 4500.Pp 4501To configure a 4502.Cm pipe 4503with 4504.Cm pie 4505AQM using default configuration for traffic from 192.168.0.0/24 and 1Mbits/s 4506rate limit, we do: 4507.Pp 4508.Dl "ipfw pipe 1 config bw 1mbits/s pie" 4509.Dl "ipfw add 100 pipe 1 ip from 192.168.0.0/24 to any" 4510.Pp 4511To configure a 4512.Cm queue 4513with 4514.Cm pie 4515AQM using different configuration parameters for traffic from 4516192.168.0.0/24 and 1Mbits/s rate limit, we do: 4517.Pp 4518.Dl "ipfw pipe 1 config bw 1mbits/s" 4519.Dl "ipfw queue 1 config pipe 1 pie target 20ms tupdate 30ms ecn" 4520.Dl "ipfw add 100 queue 1 ip from 192.168.0.0/24 to any" 4521.Pp 4522.Cm fq_codel 4523and 4524.Cm fq_pie 4525AQM can be configured for 4526.Nm dummynet 4527schedulers. 4528.Pp 4529To configure 4530.Cm fq_codel 4531scheduler using different configurations parameters for traffic from 4532192.168.0.0/24 and 1Mbits/s rate limit, we do: 4533.Pp 4534.Dl "ipfw pipe 1 config bw 1mbits/s" 4535.Dl "ipfw sched 1 config pipe 1 type fq_codel" 4536.Dl "ipfw queue 1 config sched 1" 4537.Dl "ipfw add 100 queue 1 ip from 192.168.0.0/24 to any" 4538.Pp 4539To change 4540.Cm fq_codel 4541default configuration for a 4542.Cm sched 4543such as disable ECN and change the 4544.Ar target 4545to 10ms, we do: 4546.Pp 4547.Dl "ipfw sched 1 config pipe 1 type fq_codel target 10ms noecn" 4548.Pp 4549Similar to 4550.Cm fq_codel, 4551to configure 4552.Cm fq_pie 4553scheduler using different configurations parameters for traffic from 4554192.168.0.0/24 and 1Mbits/s rate limit, we do: 4555.Pp 4556.Dl "ipfw pipe 1 config bw 1mbits/s" 4557.Dl "ipfw sched 1 config pipe 1 type fq_pie" 4558.Dl "ipfw queue 1 config sched 1" 4559.Dl "ipfw add 100 queue 1 ip from 192.168.0.0/24 to any" 4560.Pp 4561The configurations of 4562.Cm fq_pie 4563.Cm sched 4564can be changed in a similar way as for 4565.Cm fq_codel 4566.Sh SEE ALSO 4567.Xr cpp 1 , 4568.Xr m4 1 , 4569.Xr altq 4 , 4570.Xr divert 4 , 4571.Xr dummynet 4 , 4572.Xr if_bridge 4 , 4573.Xr ip 4 , 4574.Xr ipfirewall 4 , 4575.Xr ng_ether 4 , 4576.Xr ng_ipfw 4 , 4577.Xr protocols 5 , 4578.Xr services 5 , 4579.Xr init 8 , 4580.Xr kldload 8 , 4581.Xr reboot 8 , 4582.Xr sysctl 8 , 4583.Xr sysrc 8 , 4584.Xr syslogd 8 4585.Sh HISTORY 4586The 4587.Nm 4588utility first appeared in 4589.Fx 2.0 . 4590.Nm dummynet 4591was introduced in 4592.Fx 2.2.8 . 4593Stateful extensions were introduced in 4594.Fx 4.0 . 4595.Nm ipfw2 4596was introduced in Summer 2002. 4597.Sh AUTHORS 4598.An Ugen J. S. Antsilevich , 4599.An Poul-Henning Kamp , 4600.An Alex Nash , 4601.An Archie Cobbs , 4602.An Luigi Rizzo , 4603.An Rasool Al-Saadi . 4604.Pp 4605.An -nosplit 4606API based upon code written by 4607.An Daniel Boulet 4608for BSDI. 4609.Pp 4610Dummynet has been introduced by Luigi Rizzo in 1997-1998. 4611.Pp 4612Some early work (1999-2000) on the 4613.Nm dummynet 4614traffic shaper supported by Akamba Corp. 4615.Pp 4616The ipfw core (ipfw2) has been completely redesigned and 4617reimplemented by Luigi Rizzo in summer 2002. 4618Further 4619actions and 4620options have been added by various developers over the years. 4621.Pp 4622.An -nosplit 4623In-kernel NAT support written by 4624.An Paolo Pisati Aq Mt piso@FreeBSD.org 4625as part of a Summer of Code 2005 project. 4626.Pp 4627SCTP 4628.Nm nat 4629support has been developed by 4630.An The Centre for Advanced Internet Architectures (CAIA) Aq http://www.caia.swin.edu.au . 4631The primary developers and maintainers are David Hayes and Jason But. 4632For further information visit: 4633.Aq http://www.caia.swin.edu.au/urp/SONATA 4634.Pp 4635Delay profiles have been developed by Alessandro Cerri and 4636Luigi Rizzo, supported by the 4637European Commission within Projects Onelab and Onelab2. 4638.Pp 4639CoDel, PIE, FQ-CoDel and FQ-PIE AQM for Dummynet have been implemented by 4640.An The Centre for Advanced Internet Architectures (CAIA) 4641in 2016, supported by The Comcast Innovation Fund. 4642The primary developer is 4643Rasool Al-Saadi. 4644.Sh BUGS 4645The syntax has grown over the years and sometimes it might be confusing. 4646Unfortunately, backward compatibility prevents cleaning up mistakes 4647made in the definition of the syntax. 4648.Pp 4649.Em !!! WARNING !!! 4650.Pp 4651Misconfiguring the firewall can put your computer in an unusable state, 4652possibly shutting down network services and requiring console access to 4653regain control of it. 4654.Pp 4655Incoming packet fragments diverted by 4656.Cm divert 4657are reassembled before delivery to the socket. 4658The action used on those packet is the one from the 4659rule which matches the first fragment of the packet. 4660.Pp 4661Packets diverted to userland, and then reinserted by a userland process 4662may lose various packet attributes. 4663The packet source interface name 4664will be preserved if it is shorter than 8 bytes and the userland process 4665saves and reuses the sockaddr_in 4666(as does 4667.Xr natd 8 ) ; 4668otherwise, it may be lost. 4669If a packet is reinserted in this manner, later rules may be incorrectly 4670applied, making the order of 4671.Cm divert 4672rules in the rule sequence very important. 4673.Pp 4674Dummynet drops all packets with IPv6 link-local addresses. 4675.Pp 4676Rules using 4677.Cm uid 4678or 4679.Cm gid 4680may not behave as expected. 4681In particular, incoming SYN packets may 4682have no uid or gid associated with them since they do not yet belong 4683to a TCP connection, and the uid/gid associated with a packet may not 4684be as expected if the associated process calls 4685.Xr setuid 2 4686or similar system calls. 4687.Pp 4688Rule syntax is subject to the command line environment and some patterns 4689may need to be escaped with the backslash character 4690or quoted appropriately. 4691.Pp 4692Due to the architecture of 4693.Xr libalias 3 , 4694ipfw nat is not compatible with the TCP segmentation offloading (TSO). 4695Thus, to reliably nat your network traffic, please disable TSO 4696on your NICs using 4697.Xr ifconfig 8 . 4698.Pp 4699ICMP error messages are not implicitly matched by dynamic rules 4700for the respective conversations. 4701To avoid failures of network error detection and path MTU discovery, 4702ICMP error messages may need to be allowed explicitly through static 4703rules. 4704.Pp 4705Rules using 4706.Cm call 4707and 4708.Cm return 4709actions may lead to confusing behaviour if ruleset has mistakes, 4710and/or interaction with other subsystems (netgraph, dummynet, etc.) is used. 4711One possible case for this is packet leaving 4712.Nm 4713in subroutine on the input pass, while later on output encountering unpaired 4714.Cm return 4715first. 4716As the call stack is kept intact after input pass, packet will suddenly 4717return to the rule number used on input pass, not on output one. 4718Order of processing should be checked carefully to avoid such mistakes. 4719