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