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