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