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