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