1.\" 2.\" $FreeBSD$ 3.\" 4.Dd March 20, 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 is either accepted or continues with the next rule, depending on 863.Va net.inet.ip.fw.one_pass 864sysctl variable. 865See 866.Xr ng_ipfw 4 867for more information on 868.Cm netgraph 869and 870.Cm ngtee 871actions. 872.It Cm setfib Ar fibnum 873The packet is tagged so as to use the FIB (routing table) 874.Ar fibnum 875in any subsequent forwarding decisions. 876Initially this is limited to the values 0 through 15, see 877.Xr setfib 1 . 878Processing continues at the next rule. 879.It Cm reass 880Queue and reassemble ip fragments. 881If the packet is not fragmented, counters are updated and processing continues with the next rule. 882If the packet is the last logical fragment, the packet is reassembled and, if 883.Va net.inet.ip.fw.one_pass 884is set to 0, processing continues with the next rule, else packet is allowed to pass and search terminates. 885If the packet is a fragment in the middle, it is consumed and processing stops immediately. 886.Pp 887Fragments handling can be tuned via 888.Va net.inet.ip.maxfragpackets 889and 890.Va net.inet.ip.maxfragsperpacket 891which limit, respectively, the maximum number of processable fragments (default: 800) and 892the maximum number of fragments per packet (default: 16). 893.Pp 894NOTA BENE: since fragments do not contain port numbers, they should be avoided with the 895.Nm reass 896rule. 897Alternatively, direction-based (like 898.Nm in 899/ 900.Nm out 901) and source-based (like 902.Nm via 903) match patterns can be used to select fragments. 904.Pp 905Usually a simple rule like: 906.Bd -literal -offset indent 907# reassemble incoming fragments 908ipfw add reass all from any to any in 909.Ed 910.Pp 911is all you need at the beginning of your ruleset. 912.El 913.Ss RULE BODY 914The body of a rule contains zero or more patterns (such as 915specific source and destination addresses or ports, 916protocol options, incoming or outgoing interfaces, etc.) 917that the packet must match in order to be recognised. 918In general, the patterns are connected by (implicit) 919.Cm and 920operators -- i.e., all must match in order for the 921rule to match. 922Individual patterns can be prefixed by the 923.Cm not 924operator to reverse the result of the match, as in 925.Pp 926.Dl "ipfw add 100 allow ip from not 1.2.3.4 to any" 927.Pp 928Additionally, sets of alternative match patterns 929.Pq Em or-blocks 930can be constructed by putting the patterns in 931lists enclosed between parentheses ( ) or braces { }, and 932using the 933.Cm or 934operator as follows: 935.Pp 936.Dl "ipfw add 100 allow ip from { x or not y or z } to any" 937.Pp 938Only one level of parentheses is allowed. 939Beware that most shells have special meanings for parentheses 940or braces, so it is advisable to put a backslash \\ in front of them 941to prevent such interpretations. 942.Pp 943The body of a rule must in general include a source and destination 944address specifier. 945The keyword 946.Ar any 947can be used in various places to specify that the content of 948a required field is irrelevant. 949.Pp 950The rule body has the following format: 951.Bd -ragged -offset indent 952.Op Ar proto Cm from Ar src Cm to Ar dst 953.Op Ar options 954.Ed 955.Pp 956The first part (proto from src to dst) is for backward 957compatibility with earlier versions of 958.Fx . 959In modern 960.Fx 961any match pattern (including MAC headers, IP protocols, 962addresses and ports) can be specified in the 963.Ar options 964section. 965.Pp 966Rule fields have the following meaning: 967.Bl -tag -width indent 968.It Ar proto : protocol | Cm { Ar protocol Cm or ... } 969.It Ar protocol : Oo Cm not Oc Ar protocol-name | protocol-number 970An IP protocol specified by number or name 971(for a complete list see 972.Pa /etc/protocols ) , 973or one of the following keywords: 974.Bl -tag -width indent 975.It Cm ip4 | ipv4 976Matches IPv4 packets. 977.It Cm ip6 | ipv6 978Matches IPv6 packets. 979.It Cm ip | all 980Matches any packet. 981.El 982.Pp 983The 984.Cm ipv6 985in 986.Cm proto 987option will be treated as inner protocol. 988And, the 989.Cm ipv4 990is not available in 991.Cm proto 992option. 993.Pp 994The 995.Cm { Ar protocol Cm or ... } 996format (an 997.Em or-block ) 998is provided for convenience only but its use is deprecated. 999.It Ar src No and Ar dst : Bro Cm addr | Cm { Ar addr Cm or ... } Brc Op Oo Cm not Oc Ar ports 1000An address (or a list, see below) 1001optionally followed by 1002.Ar ports 1003specifiers. 1004.Pp 1005The second format 1006.Em ( or-block 1007with multiple addresses) is provided for convenience only and 1008its use is discouraged. 1009.It Ar addr : Oo Cm not Oc Bro 1010.Bl -tag -width indent 1011.Cm any | me | me6 | 1012.Cm table Ns Pq Ar number Ns Op , Ns Ar value 1013.Ar | addr-list | addr-set 1014.Brc 1015.It Cm any 1016matches any IP address. 1017.It Cm me 1018matches any IP address configured on an interface in the system. 1019.It Cm me6 1020matches any IPv6 address configured on an interface in the system. 1021The address list is evaluated at the time the packet is 1022analysed. 1023.It Cm table Ns Pq Ar number Ns Op , Ns Ar value 1024Matches any IPv4 address for which an entry exists in the lookup table 1025.Ar number . 1026If an optional 32-bit unsigned 1027.Ar value 1028is also specified, an entry will match only if it has this value. 1029See the 1030.Sx LOOKUP TABLES 1031section below for more information on lookup tables. 1032.El 1033.It Ar addr-list : ip-addr Ns Op Ns , Ns Ar addr-list 1034.It Ar ip-addr : 1035A host or subnet address specified in one of the following ways: 1036.Bl -tag -width indent 1037.It Ar numeric-ip | hostname 1038Matches a single IPv4 address, specified as dotted-quad or a hostname. 1039Hostnames are resolved at the time the rule is added to the firewall list. 1040.It Ar addr Ns / Ns Ar masklen 1041Matches all addresses with base 1042.Ar addr 1043(specified as an IP address, a network number, or a hostname) 1044and mask width of 1045.Cm masklen 1046bits. 1047As an example, 1.2.3.4/25 or 1.2.3.0/25 will match 1048all IP numbers from 1.2.3.0 to 1.2.3.127 . 1049.It Ar addr Ns : Ns Ar mask 1050Matches all addresses with base 1051.Ar addr 1052(specified as an IP address, a network number, or a hostname) 1053and the mask of 1054.Ar mask , 1055specified as a dotted quad. 1056As an example, 1.2.3.4:255.0.255.0 or 1.0.3.0:255.0.255.0 will match 10571.*.3.*. 1058This form is advised only for non-contiguous 1059masks. 1060It is better to resort to the 1061.Ar addr Ns / Ns Ar masklen 1062format for contiguous masks, which is more compact and less 1063error-prone. 1064.El 1065.It Ar addr-set : addr Ns Oo Ns / Ns Ar masklen Oc Ns Cm { Ns Ar list Ns Cm } 1066.It Ar list : Bro Ar num | num-num Brc Ns Op Ns , Ns Ar list 1067Matches all addresses with base address 1068.Ar addr 1069(specified as an IP address, a network number, or a hostname) 1070and whose last byte is in the list between braces { } . 1071Note that there must be no spaces between braces and 1072numbers (spaces after commas are allowed). 1073Elements of the list can be specified as single entries 1074or ranges. 1075The 1076.Ar masklen 1077field is used to limit the size of the set of addresses, 1078and can have any value between 24 and 32. 1079If not specified, 1080it will be assumed as 24. 1081.br 1082This format is particularly useful to handle sparse address sets 1083within a single rule. 1084Because the matching occurs using a 1085bitmask, it takes constant time and dramatically reduces 1086the complexity of rulesets. 1087.br 1088As an example, an address specified as 1.2.3.4/24{128,35-55,89} 1089or 1.2.3.0/24{128,35-55,89} 1090will match the following IP addresses: 1091.br 10921.2.3.128, 1.2.3.35 to 1.2.3.55, 1.2.3.89 . 1093.It Ar addr6-list : ip6-addr Ns Op Ns , Ns Ar addr6-list 1094.It Ar ip6-addr : 1095A host or subnet specified one of the following ways: 1096.Pp 1097.Bl -tag -width indent 1098.It Ar numeric-ip | hostname 1099Matches a single IPv6 address as allowed by 1100.Xr inet_pton 3 1101or a hostname. 1102Hostnames are resolved at the time the rule is added to the firewall 1103list. 1104.It Ar addr Ns / Ns Ar masklen 1105Matches all IPv6 addresses with base 1106.Ar addr 1107(specified as allowed by 1108.Xr inet_pton 1109or a hostname) 1110and mask width of 1111.Cm masklen 1112bits. 1113.El 1114.Pp 1115No support for sets of IPv6 addresses is provided because IPv6 addresses 1116are typically random past the initial prefix. 1117.It Ar ports : Bro Ar port | port Ns \&- Ns Ar port Ns Brc Ns Op , Ns Ar ports 1118For protocols which support port numbers (such as TCP and UDP), optional 1119.Cm ports 1120may be specified as one or more ports or port ranges, separated 1121by commas but no spaces, and an optional 1122.Cm not 1123operator. 1124The 1125.Ql \&- 1126notation specifies a range of ports (including boundaries). 1127.Pp 1128Service names (from 1129.Pa /etc/services ) 1130may be used instead of numeric port values. 1131The length of the port list is limited to 30 ports or ranges, 1132though one can specify larger ranges by using an 1133.Em or-block 1134in the 1135.Cm options 1136section of the rule. 1137.Pp 1138A backslash 1139.Pq Ql \e 1140can be used to escape the dash 1141.Pq Ql - 1142character in a service name (from a shell, the backslash must be 1143typed twice to avoid the shell itself interpreting it as an escape 1144character). 1145.Pp 1146.Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any" 1147.Pp 1148Fragmented packets which have a non-zero offset (i.e., not the first 1149fragment) will never match a rule which has one or more port 1150specifications. 1151See the 1152.Cm frag 1153option for details on matching fragmented packets. 1154.El 1155.Ss RULE OPTIONS (MATCH PATTERNS) 1156Additional match patterns can be used within 1157rules. 1158Zero or more of these so-called 1159.Em options 1160can be present in a rule, optionally prefixed by the 1161.Cm not 1162operand, and possibly grouped into 1163.Em or-blocks . 1164.Pp 1165The following match patterns can be used (listed in alphabetical order): 1166.Bl -tag -width indent 1167.It Cm // this is a comment. 1168Inserts the specified text as a comment in the rule. 1169Everything following // is considered as a comment and stored in the rule. 1170You can have comment-only rules, which are listed as having a 1171.Cm count 1172action followed by the comment. 1173.It Cm bridged 1174Alias for 1175.Cm layer2 . 1176.It Cm diverted 1177Matches only packets generated by a divert socket. 1178.It Cm diverted-loopback 1179Matches only packets coming from a divert socket back into the IP stack 1180input for delivery. 1181.It Cm diverted-output 1182Matches only packets going from a divert socket back outward to the IP 1183stack output for delivery. 1184.It Cm dst-ip Ar ip-address 1185Matches IPv4 packets whose destination IP is one of the address(es) 1186specified as argument. 1187.It Bro Cm dst-ip6 | dst-ipv6 Brc Ar ip6-address 1188Matches IPv6 packets whose destination IP is one of the address(es) 1189specified as argument. 1190.It Cm dst-port Ar ports 1191Matches IP packets whose destination port is one of the port(s) 1192specified as argument. 1193.It Cm established 1194Matches TCP packets that have the RST or ACK bits set. 1195.It Cm ext6hdr Ar header 1196Matches IPv6 packets containing the extended header given by 1197.Ar header . 1198Supported headers are: 1199.Pp 1200Fragment, 1201.Pq Cm frag , 1202Hop-to-hop options 1203.Pq Cm hopopt , 1204any type of Routing Header 1205.Pq Cm route , 1206Source routing Routing Header Type 0 1207.Pq Cm rthdr0 , 1208Mobile IPv6 Routing Header Type 2 1209.Pq Cm rthdr2 , 1210Destination options 1211.Pq Cm dstopt , 1212IPSec authentication headers 1213.Pq Cm ah , 1214and IPsec encapsulated security payload headers 1215.Pq Cm esp . 1216.It Cm fib Ar fibnum 1217Matches a packet that has been tagged to use 1218the given FIB (routing table) number. 1219.It Cm flow-id Ar labels 1220Matches IPv6 packets containing any of the flow labels given in 1221.Ar labels . 1222.Ar labels 1223is a comma separated list of numeric flow labels. 1224.It Cm frag 1225Matches packets that are fragments and not the first 1226fragment of an IP datagram. 1227Note that these packets will not have 1228the next protocol header (e.g.\& TCP, UDP) so options that look into 1229these headers cannot match. 1230.It Cm gid Ar group 1231Matches all TCP or UDP packets sent by or received for a 1232.Ar group . 1233A 1234.Ar group 1235may be specified by name or number. 1236.It Cm jail Ar prisonID 1237Matches all TCP or UDP packets sent by or received for the 1238jail whos prison ID is 1239.Ar prisonID . 1240.It Cm icmptypes Ar types 1241Matches ICMP packets whose ICMP type is in the list 1242.Ar types . 1243The list may be specified as any combination of 1244individual types (numeric) separated by commas. 1245.Em Ranges are not allowed . 1246The supported ICMP types are: 1247.Pp 1248echo reply 1249.Pq Cm 0 , 1250destination unreachable 1251.Pq Cm 3 , 1252source quench 1253.Pq Cm 4 , 1254redirect 1255.Pq Cm 5 , 1256echo request 1257.Pq Cm 8 , 1258router advertisement 1259.Pq Cm 9 , 1260router solicitation 1261.Pq Cm 10 , 1262time-to-live exceeded 1263.Pq Cm 11 , 1264IP header bad 1265.Pq Cm 12 , 1266timestamp request 1267.Pq Cm 13 , 1268timestamp reply 1269.Pq Cm 14 , 1270information request 1271.Pq Cm 15 , 1272information reply 1273.Pq Cm 16 , 1274address mask request 1275.Pq Cm 17 1276and address mask reply 1277.Pq Cm 18 . 1278.It Cm icmp6types Ar types 1279Matches ICMP6 packets whose ICMP6 type is in the list of 1280.Ar types . 1281The list may be specified as any combination of 1282individual types (numeric) separated by commas. 1283.Em Ranges are not allowed . 1284.It Cm in | out 1285Matches incoming or outgoing packets, respectively. 1286.Cm in 1287and 1288.Cm out 1289are mutually exclusive (in fact, 1290.Cm out 1291is implemented as 1292.Cm not in Ns No ). 1293.It Cm ipid Ar id-list 1294Matches IPv4 packets whose 1295.Cm ip_id 1296field has value included in 1297.Ar id-list , 1298which is either a single value or a list of values or ranges 1299specified in the same way as 1300.Ar ports . 1301.It Cm iplen Ar len-list 1302Matches IP packets whose total length, including header and data, is 1303in the set 1304.Ar len-list , 1305which is either a single value or a list of values or ranges 1306specified in the same way as 1307.Ar ports . 1308.It Cm ipoptions Ar spec 1309Matches packets whose IPv4 header contains the comma separated list of 1310options specified in 1311.Ar spec . 1312The supported IP options are: 1313.Pp 1314.Cm ssrr 1315(strict source route), 1316.Cm lsrr 1317(loose source route), 1318.Cm rr 1319(record packet route) and 1320.Cm ts 1321(timestamp). 1322The absence of a particular option may be denoted 1323with a 1324.Ql \&! . 1325.It Cm ipprecedence Ar precedence 1326Matches IPv4 packets whose precedence field is equal to 1327.Ar precedence . 1328.It Cm ipsec 1329Matches packets that have IPSEC history associated with them 1330(i.e., the packet comes encapsulated in IPSEC, the kernel 1331has IPSEC support and IPSEC_FILTERTUNNEL option, and can correctly 1332decapsulate it). 1333.Pp 1334Note that specifying 1335.Cm ipsec 1336is different from specifying 1337.Cm proto Ar ipsec 1338as the latter will only look at the specific IP protocol field, 1339irrespective of IPSEC kernel support and the validity of the IPSEC data. 1340.Pp 1341Further note that this flag is silently ignored in kernels without 1342IPSEC support. 1343It does not affect rule processing when given and the 1344rules are handled as if with no 1345.Cm ipsec 1346flag. 1347.It Cm iptos Ar spec 1348Matches IPv4 packets whose 1349.Cm tos 1350field contains the comma separated list of 1351service types specified in 1352.Ar spec . 1353The supported IP types of service are: 1354.Pp 1355.Cm lowdelay 1356.Pq Dv IPTOS_LOWDELAY , 1357.Cm throughput 1358.Pq Dv IPTOS_THROUGHPUT , 1359.Cm reliability 1360.Pq Dv IPTOS_RELIABILITY , 1361.Cm mincost 1362.Pq Dv IPTOS_MINCOST , 1363.Cm congestion 1364.Pq Dv IPTOS_ECN_CE . 1365The absence of a particular type may be denoted 1366with a 1367.Ql \&! . 1368.It Cm ipttl Ar ttl-list 1369Matches IPv4 packets whose time to live is included in 1370.Ar ttl-list , 1371which is either a single value or a list of values or ranges 1372specified in the same way as 1373.Ar ports . 1374.It Cm ipversion Ar ver 1375Matches IP packets whose IP version field is 1376.Ar ver . 1377.It Cm keep-state 1378Upon a match, the firewall will create a dynamic rule, whose 1379default behaviour is to match bidirectional traffic between 1380source and destination IP/port using the same protocol. 1381The rule has a limited lifetime (controlled by a set of 1382.Xr sysctl 8 1383variables), and the lifetime is refreshed every time a matching 1384packet is found. 1385.It Cm layer2 1386Matches only layer2 packets, i.e., those passed to 1387.Nm 1388from ether_demux() and ether_output_frame(). 1389.It Cm limit Bro Cm src-addr | src-port | dst-addr | dst-port Brc Ar N 1390The firewall will only allow 1391.Ar N 1392connections with the same 1393set of parameters as specified in the rule. 1394One or more 1395of source and destination addresses and ports can be 1396specified. 1397Currently, 1398only IPv4 flows are supported. 1399.It Cm lookup Bro Cm dst-ip | dst-port | src-ip | src-port | uid | jail Brc Ar N 1400Search an entry in lookup table 1401.Ar N 1402that matches the field specified as argument. 1403If not found, the match fails. 1404Otherwise, the match succeeds and 1405.Cm tablearg 1406is set to the value extracted from the table. 1407.Pp 1408This option can be useful to quickly dispatch traffic based on 1409certain packet fields. 1410See the 1411.Sx LOOKUP TABLES 1412section below for more information on lookup tables. 1413.It Cm { MAC | mac } Ar dst-mac src-mac 1414Match packets with a given 1415.Ar dst-mac 1416and 1417.Ar src-mac 1418addresses, specified as the 1419.Cm any 1420keyword (matching any MAC address), or six groups of hex digits 1421separated by colons, 1422and optionally followed by a mask indicating the significant bits. 1423The mask may be specified using either of the following methods: 1424.Bl -enum -width indent 1425.It 1426A slash 1427.Pq / 1428followed by the number of significant bits. 1429For example, an address with 33 significant bits could be specified as: 1430.Pp 1431.Dl "MAC 10:20:30:40:50:60/33 any" 1432.Pp 1433.It 1434An ampersand 1435.Pq & 1436followed by a bitmask specified as six groups of hex digits separated 1437by colons. 1438For example, an address in which the last 16 bits are significant could 1439be specified as: 1440.Pp 1441.Dl "MAC 10:20:30:40:50:60&00:00:00:00:ff:ff any" 1442.Pp 1443Note that the ampersand character has a special meaning in many shells 1444and should generally be escaped. 1445.Pp 1446.El 1447Note that the order of MAC addresses (destination first, 1448source second) is 1449the same as on the wire, but the opposite of the one used for 1450IP addresses. 1451.It Cm mac-type Ar mac-type 1452Matches packets whose Ethernet Type field 1453corresponds to one of those specified as argument. 1454.Ar mac-type 1455is specified in the same way as 1456.Cm port numbers 1457(i.e., one or more comma-separated single values or ranges). 1458You can use symbolic names for known values such as 1459.Em vlan , ipv4, ipv6 . 1460Values can be entered as decimal or hexadecimal (if prefixed by 0x), 1461and they are always printed as hexadecimal (unless the 1462.Cm -N 1463option is used, in which case symbolic resolution will be attempted). 1464.It Cm proto Ar protocol 1465Matches packets with the corresponding IP protocol. 1466.It Cm recv | xmit | via Brq Ar ifX | Ar if Ns Cm * | Ar ipno | Ar any 1467Matches packets received, transmitted or going through, 1468respectively, the interface specified by exact name 1469.Ns No ( Ar ifX Ns No ), 1470by device name 1471.Ns No ( Ar if Ns Ar * Ns No ), 1472by IP address, or through some interface. 1473.Pp 1474The 1475.Cm via 1476keyword causes the interface to always be checked. 1477If 1478.Cm recv 1479or 1480.Cm xmit 1481is used instead of 1482.Cm via , 1483then only the receive or transmit interface (respectively) 1484is checked. 1485By specifying both, it is possible to match packets based on 1486both receive and transmit interface, e.g.: 1487.Pp 1488.Dl "ipfw add deny ip from any to any out recv ed0 xmit ed1" 1489.Pp 1490The 1491.Cm recv 1492interface can be tested on either incoming or outgoing packets, 1493while the 1494.Cm xmit 1495interface can only be tested on outgoing packets. 1496So 1497.Cm out 1498is required (and 1499.Cm in 1500is invalid) whenever 1501.Cm xmit 1502is used. 1503.Pp 1504A packet might not have a receive or transmit interface: packets 1505originating from the local host have no receive interface, 1506while packets destined for the local host have no transmit 1507interface. 1508.It Cm setup 1509Matches TCP packets that have the SYN bit set but no ACK bit. 1510This is the short form of 1511.Dq Li tcpflags\ syn,!ack . 1512.It Cm src-ip Ar ip-address 1513Matches IPv4 packets whose source IP is one of the address(es) 1514specified as an argument. 1515.It Cm src-ip6 Ar ip6-address 1516Matches IPv6 packets whose source IP is one of the address(es) 1517specified as an argument. 1518.It Cm src-port Ar ports 1519Matches IP packets whose source port is one of the port(s) 1520specified as argument. 1521.It Cm tagged Ar tag-list 1522Matches packets whose tags are included in 1523.Ar tag-list , 1524which is either a single value or a list of values or ranges 1525specified in the same way as 1526.Ar ports . 1527Tags can be applied to the packet using 1528.Cm tag 1529rule action parameter (see it's description for details on tags). 1530.It Cm tcpack Ar ack 1531TCP packets only. 1532Match if the TCP header acknowledgment number field is set to 1533.Ar ack . 1534.It Cm tcpdatalen Ar tcpdatalen-list 1535Matches TCP packets whose length of TCP data is 1536.Ar tcpdatalen-list , 1537which is either a single value or a list of values or ranges 1538specified in the same way as 1539.Ar ports . 1540.It Cm tcpflags Ar spec 1541TCP packets only. 1542Match if the TCP header contains the comma separated list of 1543flags specified in 1544.Ar spec . 1545The supported TCP flags are: 1546.Pp 1547.Cm fin , 1548.Cm syn , 1549.Cm rst , 1550.Cm psh , 1551.Cm ack 1552and 1553.Cm urg . 1554The absence of a particular flag may be denoted 1555with a 1556.Ql \&! . 1557A rule which contains a 1558.Cm tcpflags 1559specification can never match a fragmented packet which has 1560a non-zero offset. 1561See the 1562.Cm frag 1563option for details on matching fragmented packets. 1564.It Cm tcpseq Ar seq 1565TCP packets only. 1566Match if the TCP header sequence number field is set to 1567.Ar seq . 1568.It Cm tcpwin Ar win 1569TCP packets only. 1570Match if the TCP header window field is set to 1571.Ar win . 1572.It Cm tcpoptions Ar spec 1573TCP packets only. 1574Match if the TCP header contains the comma separated list of 1575options specified in 1576.Ar spec . 1577The supported TCP options are: 1578.Pp 1579.Cm mss 1580(maximum segment size), 1581.Cm window 1582(tcp window advertisement), 1583.Cm sack 1584(selective ack), 1585.Cm ts 1586(rfc1323 timestamp) and 1587.Cm cc 1588(rfc1644 t/tcp connection count). 1589The absence of a particular option may be denoted 1590with a 1591.Ql \&! . 1592.It Cm uid Ar user 1593Match all TCP or UDP packets sent by or received for a 1594.Ar user . 1595A 1596.Ar user 1597may be matched by name or identification number. 1598.It Cm verrevpath 1599For incoming packets, 1600a routing table lookup is done on the packet's source address. 1601If the interface on which the packet entered the system matches the 1602outgoing interface for the route, 1603the packet matches. 1604If the interfaces do not match up, 1605the packet does not match. 1606All outgoing packets or packets with no incoming interface match. 1607.Pp 1608The name and functionality of the option is intentionally similar to 1609the Cisco IOS command: 1610.Pp 1611.Dl ip verify unicast reverse-path 1612.Pp 1613This option can be used to make anti-spoofing rules to reject all 1614packets with source addresses not from this interface. 1615See also the option 1616.Cm antispoof . 1617.It Cm versrcreach 1618For incoming packets, 1619a routing table lookup is done on the packet's source address. 1620If a route to the source address exists, but not the default route 1621or a blackhole/reject route, the packet matches. 1622Otherwise, the packet does not match. 1623All outgoing packets match. 1624.Pp 1625The name and functionality of the option is intentionally similar to 1626the Cisco IOS command: 1627.Pp 1628.Dl ip verify unicast source reachable-via any 1629.Pp 1630This option can be used to make anti-spoofing rules to reject all 1631packets whose source address is unreachable. 1632.It Cm antispoof 1633For incoming packets, the packet's source address is checked if it 1634belongs to a directly connected network. 1635If the network is directly connected, then the interface the packet 1636came on in is compared to the interface the network is connected to. 1637When incoming interface and directly connected interface are not the 1638same, the packet does not match. 1639Otherwise, the packet does match. 1640All outgoing packets match. 1641.Pp 1642This option can be used to make anti-spoofing rules to reject all 1643packets that pretend to be from a directly connected network but do 1644not come in through that interface. 1645This option is similar to but more restricted than 1646.Cm verrevpath 1647because it engages only on packets with source addresses of directly 1648connected networks instead of all source addresses. 1649.El 1650.Sh LOOKUP TABLES 1651Lookup tables are useful to handle large sparse sets of 1652addresses or other search keys (e.g. ports, jail IDs). 1653In the rest of this section we will use the term ``address'' 1654to mean any unsigned value of up to 32-bit. 1655There may be up to 128 different lookup tables, numbered 0 to 127. 1656.Pp 1657Each entry is represented by an 1658.Ar addr Ns Op / Ns Ar masklen 1659and will match all addresses with base 1660.Ar addr 1661(specified as an IP address, a hostname or an unsigned integer) 1662and mask width of 1663.Ar masklen 1664bits. 1665If 1666.Ar masklen 1667is not specified, it defaults to 32. 1668When looking up an IP address in a table, the most specific 1669entry will match. 1670Associated with each entry is a 32-bit unsigned 1671.Ar value , 1672which can optionally be checked by a rule matching code. 1673When adding an entry, if 1674.Ar value 1675is not specified, it defaults to 0. 1676.Pp 1677An entry can be added to a table 1678.Pq Cm add , 1679or removed from a table 1680.Pq Cm delete . 1681A table can be examined 1682.Pq Cm list 1683or flushed 1684.Pq Cm flush . 1685.Pp 1686Internally, each table is stored in a Radix tree, the same way as 1687the routing table (see 1688.Xr route 4 ) . 1689.Pp 1690Lookup tables currently support only ports, jail IDs and IPv4 addresses. 1691.Pp 1692The 1693.Cm tablearg 1694feature provides the ability to use a value, looked up in the table, as 1695the argument for a rule action, action parameter or rule option. 1696This can significantly reduce number of rules in some configurations. 1697If two tables are used in a rule, the result of the second (destination) 1698is used. 1699The 1700.Cm tablearg 1701argument can be used with the following actions: 1702.Cm nat, pipe , queue, divert, tee, netgraph, ngtee, fwd, skipto 1703action parameters: 1704.Cm tag, untag, 1705rule options: 1706.Cm limit, tagged. 1707.Pp 1708When used with 1709.Cm fwd 1710it is possible to supply table entries with values 1711that are in the form of IP addresses or hostnames. 1712See the 1713.Sx EXAMPLES 1714Section for example usage of tables and the tablearg keyword. 1715.Pp 1716When used with the 1717.Cm skipto 1718action, the user should be aware that the code will walk the ruleset 1719up to a rule equal to, or past, the given number, and should therefore try keep the 1720ruleset compact between the skipto and the target rules. 1721.Sh SETS OF RULES 1722Each rule belongs to one of 32 different 1723.Em sets 1724, numbered 0 to 31. 1725Set 31 is reserved for the default rule. 1726.Pp 1727By default, rules are put in set 0, unless you use the 1728.Cm set N 1729attribute when entering a new rule. 1730Sets can be individually and atomically enabled or disabled, 1731so this mechanism permits an easy way to store multiple configurations 1732of the firewall and quickly (and atomically) switch between them. 1733The command to enable/disable sets is 1734.Bd -ragged -offset indent 1735.Nm 1736.Cm set Oo Cm disable Ar number ... Oc Op Cm enable Ar number ... 1737.Ed 1738.Pp 1739where multiple 1740.Cm enable 1741or 1742.Cm disable 1743sections can be specified. 1744Command execution is atomic on all the sets specified in the command. 1745By default, all sets are enabled. 1746.Pp 1747When you disable a set, its rules behave as if they do not exist 1748in the firewall configuration, with only one exception: 1749.Bd -ragged -offset indent 1750dynamic rules created from a rule before it had been disabled 1751will still be active until they expire. 1752In order to delete 1753dynamic rules you have to explicitly delete the parent rule 1754which generated them. 1755.Ed 1756.Pp 1757The set number of rules can be changed with the command 1758.Bd -ragged -offset indent 1759.Nm 1760.Cm set move 1761.Brq Cm rule Ar rule-number | old-set 1762.Cm to Ar new-set 1763.Ed 1764.Pp 1765Also, you can atomically swap two rulesets with the command 1766.Bd -ragged -offset indent 1767.Nm 1768.Cm set swap Ar first-set second-set 1769.Ed 1770.Pp 1771See the 1772.Sx EXAMPLES 1773Section on some possible uses of sets of rules. 1774.Sh STATEFUL FIREWALL 1775Stateful operation is a way for the firewall to dynamically 1776create rules for specific flows when packets that 1777match a given pattern are detected. 1778Support for stateful 1779operation comes through the 1780.Cm check-state , keep-state 1781and 1782.Cm limit 1783options of 1784.Nm rules . 1785.Pp 1786Dynamic rules are created when a packet matches a 1787.Cm keep-state 1788or 1789.Cm limit 1790rule, causing the creation of a 1791.Em dynamic 1792rule which will match all and only packets with 1793a given 1794.Em protocol 1795between a 1796.Em src-ip/src-port dst-ip/dst-port 1797pair of addresses 1798.Em ( src 1799and 1800.Em dst 1801are used here only to denote the initial match addresses, but they 1802are completely equivalent afterwards). 1803Dynamic rules will be checked at the first 1804.Cm check-state, keep-state 1805or 1806.Cm limit 1807occurrence, and the action performed upon a match will be the same 1808as in the parent rule. 1809.Pp 1810Note that no additional attributes other than protocol and IP addresses 1811and ports are checked on dynamic rules. 1812.Pp 1813The typical use of dynamic rules is to keep a closed firewall configuration, 1814but let the first TCP SYN packet from the inside network install a 1815dynamic rule for the flow so that packets belonging to that session 1816will be allowed through the firewall: 1817.Pp 1818.Dl "ipfw add check-state" 1819.Dl "ipfw add allow tcp from my-subnet to any setup keep-state" 1820.Dl "ipfw add deny tcp from any to any" 1821.Pp 1822A similar approach can be used for UDP, where an UDP packet coming 1823from the inside will install a dynamic rule to let the response through 1824the firewall: 1825.Pp 1826.Dl "ipfw add check-state" 1827.Dl "ipfw add allow udp from my-subnet to any keep-state" 1828.Dl "ipfw add deny udp from any to any" 1829.Pp 1830Dynamic rules expire after some time, which depends on the status 1831of the flow and the setting of some 1832.Cm sysctl 1833variables. 1834See Section 1835.Sx SYSCTL VARIABLES 1836for more details. 1837For TCP sessions, dynamic rules can be instructed to periodically 1838send keepalive packets to refresh the state of the rule when it is 1839about to expire. 1840.Pp 1841See Section 1842.Sx EXAMPLES 1843for more examples on how to use dynamic rules. 1844.Sh TRAFFIC SHAPER (DUMMYNET) CONFIGURATION 1845.Nm 1846is also the user interface for the 1847.Nm dummynet 1848traffic shaper, packet scheduler and network emulator, a subsystem that 1849can artificially queue, delay or drop packets 1850emulating the behaviour of certain network links 1851or queueing systems. 1852.Pp 1853.Nm dummynet 1854operates by first using the firewall to select packets 1855using any match pattern that can be used in 1856.Nm 1857rules. 1858Matching packets are then passed to either of two 1859different objects, which implement the traffic regulation: 1860.Bl -hang -offset XXXX 1861.It Em pipe 1862A 1863.Em pipe 1864emulates a 1865.Em link 1866with given bandwidth and propagation delay, 1867driven by a FIFO scheduler and a single queue with programmable 1868queue size and packet loss rate. 1869Packets are appended to the queue as they come out from 1870.Nm ipfw , 1871and then transferred in FIFO order to the link at the desired rate. 1872.It Em queue 1873A 1874.Em queue 1875is an abstraction used to implement packet scheduling 1876using one of several packet scheduling algorithms. 1877Packets sent to a 1878.Em queue 1879are first grouped into flows according to a mask on the 5-tuple. 1880Flows are then passed to the scheduler associated to the 1881.Em queue , 1882and each flow uses scheduling parameters (weight and others) 1883as configured in the 1884.Em queue 1885itself. 1886A scheduler in turn is connected to an emulated link, 1887and arbitrates the link's bandwidth among backlogged flows according to 1888weights and to the features of the scheduling algorithm in use. 1889.El 1890.Pp 1891In practice, 1892.Em pipes 1893can be used to set hard limits to the bandwidth that a flow can use, whereas 1894.Em queues 1895can be used to determine how different flows share the available bandwidth. 1896.Pp 1897A graphical representation of the binding of queues, 1898flows, schedulers and links is below. 1899.Bd -literal -offset indent 1900 (flow_mask|sched_mask) sched_mask 1901 +---------+ weight Wx +-------------+ 1902 | |->-[flow]-->--| |-+ 1903 -->--| QUEUE x | ... | | | 1904 | |->-[flow]-->--| SCHEDuler N | | 1905 +---------+ | | | 1906 ... | +--[LINK N]-->-- 1907 +---------+ weight Wy | | +--[LINK N]-->-- 1908 | |->-[flow]-->--| | | 1909 -->--| QUEUE y | ... | | | 1910 | |->-[flow]-->--| | | 1911 +---------+ +-------------+ | 1912 +-------------+ 1913.Ed 1914It is important to understand the role of the SCHED_MASK 1915and FLOW_MASK, which are configured through the commands 1916.Dl "ipfw sched N config mask SCHED_MASK ..." 1917and 1918.Dl "ipfw queue X config mask FLOW_MASK ..." . 1919.Pp 1920The SCHED_MASK is used to assign flows to one or more 1921scheduler instances, one for each 1922value of the packet's 5-fuple after applying SCHED_MASK. 1923As an example, using ``src-ip 0xffffff00'' creates one instance 1924for each /24 destination subnet. 1925.Pp 1926The FLOW_MASK, together with the SCHED_MASK, is used to split 1927packets into flows. As an example, using 1928``src-ip 0x000000ff'' 1929together with the previous SCHED_MASK makes a flow for 1930each individual source address. In turn, flows for each /24 1931subnet will be sent to the same scheduler instance. 1932.Pp 1933The above diagram holds even for the 1934.Em pipe 1935case, with the only restriction that a 1936.Em pipe 1937only supports a SCHED_MASK, and forces the use of a FIFO 1938scheduler (these are for backward compatibility reasons; 1939in fact, internally, a 1940.Nm dummynet's 1941pipe is implemented exactly as above). 1942.Pp 1943There are two modes of 1944.Nm dummynet 1945operation: 1946.Dq normal 1947and 1948.Dq fast . 1949The 1950.Dq normal 1951mode tries to emulate a real link: the 1952.Nm dummynet 1953scheduler ensures that the packet will not leave the pipe faster than it 1954would on the real link with a given bandwidth. 1955The 1956.Dq fast 1957mode allows certain packets to bypass the 1958.Nm dummynet 1959scheduler (if packet flow does not exceed pipe's bandwidth). 1960This is the reason why the 1961.Dq fast 1962mode requires less CPU cycles per packet (on average) and packet latency 1963can be significantly lower in comparison to a real link with the same 1964bandwidth. 1965The default mode is 1966.Dq normal . 1967The 1968.Dq fast 1969mode can be enabled by setting the 1970.Va net.inet.ip.dummynet.io_fast 1971.Xr sysctl 8 1972variable to a non-zero value. 1973.Pp 1974.Ss PIPE, QUEUE AND SCHEDULER CONFIGURATION 1975The 1976.Em pipe , 1977.Em queue 1978and 1979.Em scheduler 1980configuration commands are the following: 1981.Bd -ragged -offset indent 1982.Cm pipe Ar number Cm config Ar pipe-configuration 1983.Pp 1984.Cm queue Ar number Cm config Ar queue-configuration 1985.Pp 1986.Cm sched Ar number Cm config Ar sched-configuration 1987.Ed 1988.Pp 1989The following parameters can be configured for a pipe: 1990.Pp 1991.Bl -tag -width indent -compact 1992.It Cm bw Ar bandwidth | device 1993Bandwidth, measured in 1994.Sm off 1995.Op Cm K | M 1996.Brq Cm bit/s | Byte/s . 1997.Sm on 1998.Pp 1999A value of 0 (default) means unlimited bandwidth. 2000The unit must immediately follow the number, as in 2001.Pp 2002.Dl "ipfw pipe 1 config bw 300Kbit/s" 2003.Pp 2004If a device name is specified instead of a numeric value, as in 2005.Pp 2006.Dl "ipfw pipe 1 config bw tun0" 2007.Pp 2008then the transmit clock is supplied by the specified device. 2009At the moment only the 2010.Xr tun 4 2011device supports this 2012functionality, for use in conjunction with 2013.Xr ppp 8 . 2014.Pp 2015.It Cm delay Ar ms-delay 2016Propagation delay, measured in milliseconds. 2017The value is rounded to the next multiple of the clock tick 2018(typically 10ms, but it is a good practice to run kernels 2019with 2020.Dq "options HZ=1000" 2021to reduce 2022the granularity to 1ms or less). 2023The default value is 0, meaning no delay. 2024.Pp 2025.It Cm burst Ar size 2026If the data to be sent exceeds the pipe's bandwidth limit 2027(and the pipe was previously idle), up to 2028.Ar size 2029bytes of data are allowed to bypass the 2030.Nm dummynet 2031scheduler, and will be sent as fast as the physical link allows. 2032Any additional data will be transmitted at the rate specified 2033by the 2034.Nm pipe 2035bandwidth. 2036The burst size depends on how long the pipe has been idle; 2037the effective burst size is calculated as follows: 2038MAX( 2039.Ar size 2040, 2041.Nm bw 2042* pipe_idle_time). 2043.Pp 2044.It Cm profile Ar filename 2045A file specifying the additional overhead incurred in the transmission 2046of a packet on the link. 2047.Pp 2048Some link types introduce extra delays in the transmission 2049of a packet, e.g. because of MAC level framing, contention on 2050the use of the channel, MAC level retransmissions and so on. 2051From our point of view, the channel is effectively unavailable 2052for this extra time, which is constant or variable depending 2053on the link type. Additionally, packets may be dropped after this 2054time (e.g. on a wireless link after too many retransmissions). 2055We can model the additional delay with an empirical curve 2056that represents its distribution. 2057.Bd -literal -offset indent 2058 cumulative probability 2059 1.0 ^ 2060 | 2061 L +-- loss-level x 2062 | ****** 2063 | * 2064 | ***** 2065 | * 2066 | ** 2067 | * 2068 +-------*-------------------> 2069 delay 2070.Ed 2071The empirical curve may have both vertical and horizontal lines. 2072Vertical lines represent constant delay for a range of 2073probabilities. 2074Horizontal lines correspond to a discontinuity in the delay 2075distribution: the pipe will use the largest delay for a 2076given probability. 2077.Pp 2078The file format is the following, with whitespace acting as 2079a separator and '#' indicating the beginning a comment: 2080.Bl -tag -width indent 2081.It Cm name Ar identifier 2082optional name (listed by "ipfw pipe show") 2083to identify the delay distribution; 2084.It Cm bw Ar value 2085the bandwidth used for the pipe. 2086If not specified here, it must be present 2087explicitly as a configuration parameter for the pipe; 2088.It Cm loss-level Ar L 2089the probability above which packets are lost. 2090(0.0 <= L <= 1.0, default 1.0 i.e. no loss); 2091.It Cm samples Ar N 2092the number of samples used in the internal 2093representation of the curve (2..1024; default 100); 2094.It Cm "delay prob" | "prob delay" 2095One of these two lines is mandatory and defines 2096the format of the following lines with data points. 2097.It Ar XXX Ar YYY 20982 or more lines representing points in the curve, 2099with either delay or probability first, according 2100to the chosen format. 2101The unit for delay is milliseconds. 2102Data points do not need to be sorted. 2103Also, tne number of actual lines can be different 2104from the value of the "samples" parameter: 2105.Nm 2106utility will sort and interpolate 2107the curve as needed. 2108.El 2109.Pp 2110Example of a profile file: 2111.Bd -literal -offset indent 2112name bla_bla_bla 2113samples 100 2114loss-level 0.86 2115prob delay 21160 200 # minimum overhead is 200ms 21170.5 200 21180.5 300 21190.8 1000 21200.9 1300 21211 1300 2122#configuration file end 2123.Ed 2124.El 2125.Pp 2126The following parameters can be configured for a queue: 2127.Pp 2128.Bl -tag -width indent -compact 2129.It Cm pipe Ar pipe_nr 2130Connects a queue to the specified pipe. 2131Multiple queues (with the same or different weights) can be connected to 2132the same pipe, which specifies the aggregate rate for the set of queues. 2133.Pp 2134.It Cm weight Ar weight 2135Specifies the weight to be used for flows matching this queue. 2136The weight must be in the range 1..100, and defaults to 1. 2137.El 2138.Pp 2139The following parameters can be configured for a scheduler: 2140.Pp 2141.Bl -tag -width indent -compact 2142.It Cm type Ar {fifo | wf2qp | rr | qfq} 2143specifies the scheduling algorithm to use. 2144.Bl -tag -width indent -compact 2145.It cm fifo 2146is just a FIFO scheduler (which means that all packets 2147are stored in the same queue as they arrive to the scheduler). 2148FIFO has O(1) per-packet time complexity, with very low 2149constants (estimate 60-80ns on a 2Ghz desktop machine) 2150but gives no service guarantees. 2151.It Cm wf2qp 2152implements the WF2Q+ algorithm, which is a Weighted Fair Queueing 2153algorithm which permits flows to share bandwidth according to 2154their weights. Note that weights are not priorities; even a flow 2155with a minuscule weight will never starve. 2156WF2Q+ has O(log N) per-packet processing cost, where N is the number 2157of flows, and is the default algorithm used by previous versions 2158dummynet's queues. 2159.It Cm rr 2160implements the Deficit Round Robin algorithm, which has O(1) processing 2161costs (roughly, 100-150ns per packet) 2162and permits bandwidth allocation according to weights, but 2163with poor service guarantees. 2164.It Cm qfq 2165implements the QFQ algorithm, which is a very fast variant of 2166WF2Q+, with similar service guarantees and O(1) processing 2167costs (roughly, 200-250ns per packet). 2168.El 2169.El 2170.Pp 2171In addition to the type, all parameters allowed for a pipe can also 2172be specified for a scheduler. 2173.Pp 2174Finally, the following parameters can be configured for both 2175pipes and queues: 2176.Pp 2177.Bl -tag -width XXXX -compact 2178.Pp 2179.It Cm buckets Ar hash-table-size 2180Specifies the size of the hash table used for storing the 2181various queues. 2182Default value is 64 controlled by the 2183.Xr sysctl 8 2184variable 2185.Va net.inet.ip.dummynet.hash_size , 2186allowed range is 16 to 65536. 2187.Pp 2188.It Cm mask Ar mask-specifier 2189Packets sent to a given pipe or queue by an 2190.Nm 2191rule can be further classified into multiple flows, each of which is then 2192sent to a different 2193.Em dynamic 2194pipe or queue. 2195A flow identifier is constructed by masking the IP addresses, 2196ports and protocol types as specified with the 2197.Cm mask 2198options in the configuration of the pipe or queue. 2199For each different flow identifier, a new pipe or queue is created 2200with the same parameters as the original object, and matching packets 2201are sent to it. 2202.Pp 2203Thus, when 2204.Em dynamic pipes 2205are used, each flow will get the same bandwidth as defined by the pipe, 2206whereas when 2207.Em dynamic queues 2208are used, each flow will share the parent's pipe bandwidth evenly 2209with other flows generated by the same queue (note that other queues 2210with different weights might be connected to the same pipe). 2211.br 2212Available mask specifiers are a combination of one or more of the following: 2213.Pp 2214.Cm dst-ip Ar mask , 2215.Cm dst-ip6 Ar mask , 2216.Cm src-ip Ar mask , 2217.Cm src-ip6 Ar mask , 2218.Cm dst-port Ar mask , 2219.Cm src-port Ar mask , 2220.Cm flow-id Ar mask , 2221.Cm proto Ar mask 2222or 2223.Cm all , 2224.Pp 2225where the latter means all bits in all fields are significant. 2226.Pp 2227.It Cm noerror 2228When a packet is dropped by a 2229.Nm dummynet 2230queue or pipe, the error 2231is normally reported to the caller routine in the kernel, in the 2232same way as it happens when a device queue fills up. 2233Setting this 2234option reports the packet as successfully delivered, which can be 2235needed for some experimental setups where you want to simulate 2236loss or congestion at a remote router. 2237.Pp 2238.It Cm plr Ar packet-loss-rate 2239Packet loss rate. 2240Argument 2241.Ar packet-loss-rate 2242is a floating-point number between 0 and 1, with 0 meaning no 2243loss, 1 meaning 100% loss. 2244The loss rate is internally represented on 31 bits. 2245.Pp 2246.It Cm queue Brq Ar slots | size Ns Cm Kbytes 2247Queue size, in 2248.Ar slots 2249or 2250.Cm KBytes . 2251Default value is 50 slots, which 2252is the typical queue size for Ethernet devices. 2253Note that for slow speed links you should keep the queue 2254size short or your traffic might be affected by a significant 2255queueing delay. 2256E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit 2257or 20s of queue on a 30Kbit/s pipe. 2258Even worse effects can result if you get packets from an 2259interface with a much larger MTU, e.g.\& the loopback interface 2260with its 16KB packets. 2261The 2262.Xr sysctl 8 2263variables 2264.Em net.inet.ip.dummynet.pipe_byte_limit 2265and 2266.Em net.inet.ip.dummynet.pipe_slot_limit 2267control the maximum lengths that can be specified. 2268.Pp 2269.It Cm red | gred Ar w_q Ns / Ns Ar min_th Ns / Ns Ar max_th Ns / Ns Ar max_p 2270Make use of the RED (Random Early Detection) queue management algorithm. 2271.Ar w_q 2272and 2273.Ar max_p 2274are floating 2275point numbers between 0 and 1 (0 not included), while 2276.Ar min_th 2277and 2278.Ar max_th 2279are integer numbers specifying thresholds for queue management 2280(thresholds are computed in bytes if the queue has been defined 2281in bytes, in slots otherwise). 2282The 2283.Nm dummynet 2284also supports the gentle RED variant (gred). 2285Three 2286.Xr sysctl 8 2287variables can be used to control the RED behaviour: 2288.Bl -tag -width indent 2289.It Va net.inet.ip.dummynet.red_lookup_depth 2290specifies the accuracy in computing the average queue 2291when the link is idle (defaults to 256, must be greater than zero) 2292.It Va net.inet.ip.dummynet.red_avg_pkt_size 2293specifies the expected average packet size (defaults to 512, must be 2294greater than zero) 2295.It Va net.inet.ip.dummynet.red_max_pkt_size 2296specifies the expected maximum packet size, only used when queue 2297thresholds are in bytes (defaults to 1500, must be greater than zero). 2298.El 2299.El 2300.Pp 2301When used with IPv6 data, 2302.Nm dummynet 2303currently has several limitations. 2304Information necessary to route link-local packets to an 2305interface is not available after processing by 2306.Nm dummynet 2307so those packets are dropped in the output path. 2308Care should be taken to insure that link-local packets are not passed to 2309.Nm dummynet . 2310.Sh CHECKLIST 2311Here are some important points to consider when designing your 2312rules: 2313.Bl -bullet 2314.It 2315Remember that you filter both packets going 2316.Cm in 2317and 2318.Cm out . 2319Most connections need packets going in both directions. 2320.It 2321Remember to test very carefully. 2322It is a good idea to be near the console when doing this. 2323If you cannot be near the console, 2324use an auto-recovery script such as the one in 2325.Pa /usr/share/examples/ipfw/change_rules.sh . 2326.It 2327Do not forget the loopback interface. 2328.El 2329.Sh FINE POINTS 2330.Bl -bullet 2331.It 2332There are circumstances where fragmented datagrams are unconditionally 2333dropped. 2334TCP packets are dropped if they do not contain at least 20 bytes of 2335TCP header, UDP packets are dropped if they do not contain a full 8 2336byte UDP header, and ICMP packets are dropped if they do not contain 23374 bytes of ICMP header, enough to specify the ICMP type, code, and 2338checksum. 2339These packets are simply logged as 2340.Dq pullup failed 2341since there may not be enough good data in the packet to produce a 2342meaningful log entry. 2343.It 2344Another type of packet is unconditionally dropped, a TCP packet with a 2345fragment offset of one. 2346This is a valid packet, but it only has one use, to try 2347to circumvent firewalls. 2348When logging is enabled, these packets are 2349reported as being dropped by rule -1. 2350.It 2351If you are logged in over a network, loading the 2352.Xr kld 4 2353version of 2354.Nm 2355is probably not as straightforward as you would think. 2356The following command line is recommended: 2357.Bd -literal -offset indent 2358kldload ipfw && \e 2359ipfw add 32000 allow ip from any to any 2360.Ed 2361.Pp 2362Along the same lines, doing an 2363.Bd -literal -offset indent 2364ipfw flush 2365.Ed 2366.Pp 2367in similar surroundings is also a bad idea. 2368.It 2369The 2370.Nm 2371filter list may not be modified if the system security level 2372is set to 3 or higher 2373(see 2374.Xr init 8 2375for information on system security levels). 2376.El 2377.Sh PACKET DIVERSION 2378A 2379.Xr divert 4 2380socket bound to the specified port will receive all packets 2381diverted to that port. 2382If no socket is bound to the destination port, or if the divert module is 2383not loaded, or if the kernel was not compiled with divert socket support, 2384the packets are dropped. 2385.Sh NETWORK ADDRESS TRANSLATION (NAT) 2386.Pp 2387.Nm 2388support in-kernel NAT using the kernel version of 2389.Xr libalias 3 . 2390.Pp 2391The nat configuration command is the following: 2392.Bd -ragged -offset indent 2393.Bk -words 2394.Cm nat 2395.Ar nat_number 2396.Cm config 2397.Ar nat-configuration 2398.Ek 2399.Ed 2400.Pp 2401The following parameters can be configured: 2402.Bl -tag -width indent 2403.It Cm ip Ar ip_address 2404Define an ip address to use for aliasing. 2405.It Cm if Ar nic 2406Use ip address of NIC for aliasing, dynamically changing 2407it if NIC's ip address changes. 2408.It Cm log 2409Enable logging on this nat instance. 2410.It Cm deny_in 2411Deny any incoming connection from outside world. 2412.It Cm same_ports 2413Try to leave the alias port numbers unchanged from 2414the actual local port numbers. 2415.It Cm unreg_only 2416Traffic on the local network not originating from an 2417unregistered address spaces will be ignored. 2418.It Cm reset 2419Reset table of the packet aliasing engine on address change. 2420.It Cm reverse 2421Reverse the way libalias handles aliasing. 2422.It Cm proxy_only 2423Obey transparent proxy rules only, packet aliasing is not performed. 2424.El 2425.Pp 2426To let the packet continue after being (de)aliased, set the sysctl variable 2427.Va net.inet.ip.fw.one_pass 2428to 0. 2429For more information about aliasing modes, refer to 2430.Xr libalias 3 . 2431See Section 2432.Sx EXAMPLES 2433for some examples about nat usage. 2434.Ss REDIRECT AND LSNAT SUPPORT IN IPFW 2435Redirect and LSNAT support follow closely the syntax used in 2436.Xr natd 8 . 2437See Section 2438.Sx EXAMPLES 2439for some examples on how to do redirect and lsnat. 2440.Ss SCTP NAT SUPPORT 2441SCTP nat can be configured in a similar manner to TCP through the 2442.Nm 2443command line tool. 2444The main difference is that 2445.Nm sctp nat 2446does not do port translation. 2447Since the local and global side ports will be the same, 2448there is no need to specify both. 2449Ports are redirected as follows: 2450.Bd -ragged -offset indent 2451.Bk -words 2452.Cm nat 2453.Ar nat_number 2454.Cm config if 2455.Ar nic 2456.Cm redirect_port sctp 2457.Ar ip_address [,addr_list] {[port | port-port] [,ports]} 2458.Ek 2459.Ed 2460.Pp 2461Most 2462.Nm sctp nat 2463configuration can be done in real-time through the 2464.Xr sysctl 8 2465interface. 2466All may be changed dynamically, though the hash_table size will only 2467change for new 2468.Nm nat 2469instances. 2470See 2471.Sx SYSCTL VARIABLES 2472for more info. 2473.Sh SYSCTL VARIABLES 2474A set of 2475.Xr sysctl 8 2476variables controls the behaviour of the firewall and 2477associated modules 2478.Pq Nm dummynet , bridge , sctp nat . 2479These are shown below together with their default value 2480(but always check with the 2481.Xr sysctl 8 2482command what value is actually in use) and meaning: 2483.Bl -tag -width indent 2484.It Va net.inet.ip.alias.sctp.accept_global_ootb_addip: No 0 2485Defines how the 2486.Nm nat 2487responds to receipt of global OOTB ASCONF-AddIP: 2488.Bl -tag -width indent 2489.It Cm 0 2490No response (unless a partially matching association exists - 2491ports and vtags match but global address does not) 2492.It Cm 1 2493.Nm nat 2494will accept and process all OOTB global AddIP messages. 2495.El 2496.Pp 2497Option 1 should never be selected as this forms a security risk. 2498An attacker can 2499establish multiple fake associations by sending AddIP messages. 2500.It Va net.inet.ip.alias.sctp.chunk_proc_limit: No 5 2501Defines the maximum number of chunks in an SCTP packet that will be parsed for a 2502packet that matches an existing association. 2503This value is enforced to be greater or equal than 2504.Cm net.inet.ip.alias.sctp.initialising_chunk_proc_limit . 2505A high value is 2506a DoS risk yet setting too low a value may result in important control chunks in 2507the packet not being located and parsed. 2508.It Va net.inet.ip.alias.sctp.error_on_ootb: No 1 2509Defines when the 2510.Nm nat 2511responds to any Out-of-the-Blue (OOTB) packets with ErrorM packets. 2512An OOTB packet is a packet that arrives with no existing association 2513registered in the 2514.Nm nat 2515and is not an INIT or ASCONF-AddIP packet: 2516.Bl -tag -width indent 2517.It Cm 0 2518ErrorM is never sent in response to OOTB packets. 2519.It Cm 1 2520ErrorM is only sent to OOTB packets received on the local side. 2521.It Cm 2 2522ErrorM is sent to the local side and on the global side ONLY if there is a 2523partial match (ports and vtags match but the source global IP does not). 2524This value is only useful if the 2525.Nm nat 2526is tracking global IP addresses. 2527.It Cm 3 2528ErrorM is sent in response to all OOTB packets on both the local and global side 2529(DoS risk). 2530.El 2531.Pp 2532At the moment the default is 0, since the ErrorM packet is not yet 2533supported by most SCTP stacks. 2534When it is supported, and if not tracking 2535global addresses, we recommend setting this value to 1 to allow 2536multi-homed local hosts to function with the 2537.Nm nat . 2538To track global addresses, we recommend setting this value to 2 to 2539allow global hosts to be informed when they need to (re)send an 2540ASCONF-AddIP. 2541Value 3 should never be chosen (except for debugging) as the 2542.Nm nat 2543will respond to all OOTB global packets (a DoS risk). 2544.It Va net.inet.ip.alias.sctp.hashtable_size: No 2003 2545Size of hash tables used for 2546.Nm nat 2547lookups (100 < prime_number > 1000001). 2548This value sets the 2549.Nm hash table 2550size for any future created 2551.Nm nat 2552instance and therefore must be set prior to creating a 2553.Nm nat 2554instance. 2555The table sizes may be changed to suit specific needs. 2556If there will be few 2557concurrent associations, and memory is scarce, you may make these smaller. 2558If there will be many thousands (or millions) of concurrent associations, you 2559should make these larger. 2560A prime number is best for the table size. 2561The sysctl 2562update function will adjust your input value to the next highest prime number. 2563.It Va net.inet.ip.alias.sctp.holddown_time: No 0 2564Hold association in table for this many seconds after receiving a 2565SHUTDOWN-COMPLETE. 2566This allows endpoints to correct shutdown gracefully if a 2567shutdown_complete is lost and retransmissions are required. 2568.It Va net.inet.ip.alias.sctp.init_timer: No 15 2569Timeout value while waiting for (INIT-ACK|AddIP-ACK). 2570This value cannot be 0. 2571.It Va net.inet.ip.alias.sctp.initialising_chunk_proc_limit: No 2 2572Defines the maximum number of chunks in an SCTP packet that will be parsed when 2573no existing association exists that matches that packet. 2574Ideally this packet 2575will only be an INIT or ASCONF-AddIP packet. 2576A higher value may become a DoS 2577risk as malformed packets can consume processing resources. 2578.It Va net.inet.ip.alias.sctp.param_proc_limit: No 25 2579Defines the maximum number of parameters within a chunk that will be parsed in a 2580packet. 2581As for other similar sysctl variables, larger values pose a DoS risk. 2582.It Va net.inet.ip.alias.sctp.log_level: No 0 2583Level of detail in the system log messages (0 \- minimal, 1 \- event, 25842 \- info, 3 \- detail, 4 \- debug, 5 \- max debug). May be a good 2585option in high loss environments. 2586.It Va net.inet.ip.alias.sctp.shutdown_time: No 15 2587Timeout value while waiting for SHUTDOWN-COMPLETE. 2588This value cannot be 0. 2589.It Va net.inet.ip.alias.sctp.track_global_addresses: No 0 2590Enables/disables global IP address tracking within the 2591.Nm nat 2592and places an 2593upper limit on the number of addresses tracked for each association: 2594.Bl -tag -width indent 2595.It Cm 0 2596Global tracking is disabled 2597.It Cm >1 2598Enables tracking, the maximum number of addresses tracked for each 2599association is limited to this value 2600.El 2601.Pp 2602This variable is fully dynamic, the new value will be adopted for all newly 2603arriving associations, existing associations are treated as they were previously. 2604Global tracking will decrease the number of collisions within the 2605.Nm nat 2606at a cost 2607of increased processing load, memory usage, complexity, and possible 2608.Nm nat 2609state 2610problems in complex networks with multiple 2611.Nm nats . 2612We recommend not tracking 2613global IP addresses, this will still result in a fully functional 2614.Nm nat . 2615.It Va net.inet.ip.alias.sctp.up_timer: No 300 2616Timeout value to keep an association up with no traffic. 2617This value cannot be 0. 2618.It Va net.inet.ip.dummynet.expire : No 1 2619Lazily delete dynamic pipes/queue once they have no pending traffic. 2620You can disable this by setting the variable to 0, in which case 2621the pipes/queues will only be deleted when the threshold is reached. 2622.It Va net.inet.ip.dummynet.hash_size : No 64 2623Default size of the hash table used for dynamic pipes/queues. 2624This value is used when no 2625.Cm buckets 2626option is specified when configuring a pipe/queue. 2627.It Va net.inet.ip.dummynet.io_fast : No 0 2628If set to a non-zero value, 2629the 2630.Dq fast 2631mode of 2632.Nm dummynet 2633operation (see above) is enabled. 2634.It Va net.inet.ip.dummynet.io_pkt 2635Number of packets passed to 2636.Nm dummynet . 2637.It Va net.inet.ip.dummynet.io_pkt_drop 2638Number of packets dropped by 2639.Nm dummynet . 2640.It Va net.inet.ip.dummynet.io_pkt_fast 2641Number of packets bypassed by the 2642.Nm dummynet 2643scheduler. 2644.It Va net.inet.ip.dummynet.max_chain_len : No 16 2645Target value for the maximum number of pipes/queues in a hash bucket. 2646The product 2647.Cm max_chain_len*hash_size 2648is used to determine the threshold over which empty pipes/queues 2649will be expired even when 2650.Cm net.inet.ip.dummynet.expire=0 . 2651.It Va net.inet.ip.dummynet.red_lookup_depth : No 256 2652.It Va net.inet.ip.dummynet.red_avg_pkt_size : No 512 2653.It Va net.inet.ip.dummynet.red_max_pkt_size : No 1500 2654Parameters used in the computations of the drop probability 2655for the RED algorithm. 2656.It Va net.inet.ip.dummynet.pipe_byte_limit : No 1048576 2657.It Va net.inet.ip.dummynet.pipe_slot_limit : No 100 2658The maximum queue size that can be specified in bytes or packets. 2659These limits prevent accidental exhaustion of resources such as mbufs. 2660If you raise these limits, 2661you should make sure the system is configured so that sufficient resources 2662are available. 2663.It Va net.inet.ip.fw.autoinc_step : No 100 2664Delta between rule numbers when auto-generating them. 2665The value must be in the range 1..1000. 2666.It Va net.inet.ip.fw.curr_dyn_buckets : Va net.inet.ip.fw.dyn_buckets 2667The current number of buckets in the hash table for dynamic rules 2668(readonly). 2669.It Va net.inet.ip.fw.debug : No 1 2670Controls debugging messages produced by 2671.Nm . 2672.It Va net.inet.ip.fw.default_rule : No 65535 2673The default rule number (read-only). 2674By the design of 2675.Nm , the default rule is the last one, so its number 2676can also serve as the highest number allowed for a rule. 2677.It Va net.inet.ip.fw.dyn_buckets : No 256 2678The number of buckets in the hash table for dynamic rules. 2679Must be a power of 2, up to 65536. 2680It only takes effect when all dynamic rules have expired, so you 2681are advised to use a 2682.Cm flush 2683command to make sure that the hash table is resized. 2684.It Va net.inet.ip.fw.dyn_count : No 3 2685Current number of dynamic rules 2686(read-only). 2687.It Va net.inet.ip.fw.dyn_keepalive : No 1 2688Enables generation of keepalive packets for 2689.Cm keep-state 2690rules on TCP sessions. 2691A keepalive is generated to both 2692sides of the connection every 5 seconds for the last 20 2693seconds of the lifetime of the rule. 2694.It Va net.inet.ip.fw.dyn_max : No 8192 2695Maximum number of dynamic rules. 2696When you hit this limit, no more dynamic rules can be 2697installed until old ones expire. 2698.It Va net.inet.ip.fw.dyn_ack_lifetime : No 300 2699.It Va net.inet.ip.fw.dyn_syn_lifetime : No 20 2700.It Va net.inet.ip.fw.dyn_fin_lifetime : No 1 2701.It Va net.inet.ip.fw.dyn_rst_lifetime : No 1 2702.It Va net.inet.ip.fw.dyn_udp_lifetime : No 5 2703.It Va net.inet.ip.fw.dyn_short_lifetime : No 30 2704These variables control the lifetime, in seconds, of dynamic 2705rules. 2706Upon the initial SYN exchange the lifetime is kept short, 2707then increased after both SYN have been seen, then decreased 2708again during the final FIN exchange or when a RST is received. 2709Both 2710.Em dyn_fin_lifetime 2711and 2712.Em dyn_rst_lifetime 2713must be strictly lower than 5 seconds, the period of 2714repetition of keepalives. 2715The firewall enforces that. 2716.It Va net.inet.ip.fw.enable : No 1 2717Enables the firewall. 2718Setting this variable to 0 lets you run your machine without 2719firewall even if compiled in. 2720.It Va net.inet6.ip6.fw.enable : No 1 2721provides the same functionality as above for the IPv6 case. 2722.It Va net.inet.ip.fw.one_pass : No 1 2723When set, the packet exiting from the 2724.Nm dummynet 2725pipe or from 2726.Xr ng_ipfw 4 2727node is not passed though the firewall again. 2728Otherwise, after an action, the packet is 2729reinjected into the firewall at the next rule. 2730.It Va net.inet.ip.fw.tables_max : No 128 2731Maximum number of tables (read-only). 2732.It Va net.inet.ip.fw.verbose : No 1 2733Enables verbose messages. 2734.It Va net.inet.ip.fw.verbose_limit : No 0 2735Limits the number of messages produced by a verbose firewall. 2736.It Va net.inet6.ip6.fw.deny_unknown_exthdrs : No 1 2737If enabled packets with unknown IPv6 Extension Headers will be denied. 2738.It Va net.link.ether.ipfw : No 0 2739Controls whether layer-2 packets are passed to 2740.Nm . 2741Default is no. 2742.It Va net.link.bridge.ipfw : No 0 2743Controls whether bridged packets are passed to 2744.Nm . 2745Default is no. 2746.El 2747.Pp 2748.Sh EXAMPLES 2749There are far too many possible uses of 2750.Nm 2751so this Section will only give a small set of examples. 2752.Pp 2753.Ss BASIC PACKET FILTERING 2754This command adds an entry which denies all tcp packets from 2755.Em cracker.evil.org 2756to the telnet port of 2757.Em wolf.tambov.su 2758from being forwarded by the host: 2759.Pp 2760.Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet" 2761.Pp 2762This one disallows any connection from the entire cracker's 2763network to my host: 2764.Pp 2765.Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org" 2766.Pp 2767A first and efficient way to limit access (not using dynamic rules) 2768is the use of the following rules: 2769.Pp 2770.Dl "ipfw add allow tcp from any to any established" 2771.Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup" 2772.Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup" 2773.Dl "..." 2774.Dl "ipfw add deny tcp from any to any" 2775.Pp 2776The first rule will be a quick match for normal TCP packets, 2777but it will not match the initial SYN packet, which will be 2778matched by the 2779.Cm setup 2780rules only for selected source/destination pairs. 2781All other SYN packets will be rejected by the final 2782.Cm deny 2783rule. 2784.Pp 2785If you administer one or more subnets, you can take advantage 2786of the address sets and or-blocks and write extremely 2787compact rulesets which selectively enable services to blocks 2788of clients, as below: 2789.Pp 2790.Dl "goodguys=\*q{ 10.1.2.0/24{20,35,66,18} or 10.2.3.0/28{6,3,11} }\*q" 2791.Dl "badguys=\*q10.1.2.0/24{8,38,60}\*q" 2792.Dl "" 2793.Dl "ipfw add allow ip from ${goodguys} to any" 2794.Dl "ipfw add deny ip from ${badguys} to any" 2795.Dl "... normal policies ..." 2796.Pp 2797The 2798.Cm verrevpath 2799option could be used to do automated anti-spoofing by adding the 2800following to the top of a ruleset: 2801.Pp 2802.Dl "ipfw add deny ip from any to any not verrevpath in" 2803.Pp 2804This rule drops all incoming packets that appear to be coming to the 2805system on the wrong interface. 2806For example, a packet with a source 2807address belonging to a host on a protected internal network would be 2808dropped if it tried to enter the system from an external interface. 2809.Pp 2810The 2811.Cm antispoof 2812option could be used to do similar but more restricted anti-spoofing 2813by adding the following to the top of a ruleset: 2814.Pp 2815.Dl "ipfw add deny ip from any to any not antispoof in" 2816.Pp 2817This rule drops all incoming packets that appear to be coming from another 2818directly connected system but on the wrong interface. 2819For example, a packet with a source address of 2820.Li 192.168.0.0/24 , 2821configured on 2822.Li fxp0 , 2823but coming in on 2824.Li fxp1 2825would be dropped. 2826.Ss DYNAMIC RULES 2827In order to protect a site from flood attacks involving fake 2828TCP packets, it is safer to use dynamic rules: 2829.Pp 2830.Dl "ipfw add check-state" 2831.Dl "ipfw add deny tcp from any to any established" 2832.Dl "ipfw add allow tcp from my-net to any setup keep-state" 2833.Pp 2834This will let the firewall install dynamic rules only for 2835those connection which start with a regular SYN packet coming 2836from the inside of our network. 2837Dynamic rules are checked when encountering the first 2838.Cm check-state 2839or 2840.Cm keep-state 2841rule. 2842A 2843.Cm check-state 2844rule should usually be placed near the beginning of the 2845ruleset to minimize the amount of work scanning the ruleset. 2846Your mileage may vary. 2847.Pp 2848To limit the number of connections a user can open 2849you can use the following type of rules: 2850.Pp 2851.Dl "ipfw add allow tcp from my-net/24 to any setup limit src-addr 10" 2852.Dl "ipfw add allow tcp from any to me setup limit src-addr 4" 2853.Pp 2854The former (assuming it runs on a gateway) will allow each host 2855on a /24 network to open at most 10 TCP connections. 2856The latter can be placed on a server to make sure that a single 2857client does not use more than 4 simultaneous connections. 2858.Pp 2859.Em BEWARE : 2860stateful rules can be subject to denial-of-service attacks 2861by a SYN-flood which opens a huge number of dynamic rules. 2862The effects of such attacks can be partially limited by 2863acting on a set of 2864.Xr sysctl 8 2865variables which control the operation of the firewall. 2866.Pp 2867Here is a good usage of the 2868.Cm list 2869command to see accounting records and timestamp information: 2870.Pp 2871.Dl ipfw -at list 2872.Pp 2873or in short form without timestamps: 2874.Pp 2875.Dl ipfw -a list 2876.Pp 2877which is equivalent to: 2878.Pp 2879.Dl ipfw show 2880.Pp 2881Next rule diverts all incoming packets from 192.168.2.0/24 2882to divert port 5000: 2883.Pp 2884.Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in 2885.Pp 2886.Ss TRAFFIC SHAPING 2887The following rules show some of the applications of 2888.Nm 2889and 2890.Nm dummynet 2891for simulations and the like. 2892.Pp 2893This rule drops random incoming packets with a probability 2894of 5%: 2895.Pp 2896.Dl "ipfw add prob 0.05 deny ip from any to any in" 2897.Pp 2898A similar effect can be achieved making use of 2899.Nm dummynet 2900pipes: 2901.Pp 2902.Dl "ipfw add pipe 10 ip from any to any" 2903.Dl "ipfw pipe 10 config plr 0.05" 2904.Pp 2905We can use pipes to artificially limit bandwidth, e.g.\& on a 2906machine acting as a router, if we want to limit traffic from 2907local clients on 192.168.2.0/24 we do: 2908.Pp 2909.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 2910.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes" 2911.Pp 2912note that we use the 2913.Cm out 2914modifier so that the rule is not used twice. 2915Remember in fact that 2916.Nm 2917rules are checked both on incoming and outgoing packets. 2918.Pp 2919Should we want to simulate a bidirectional link with bandwidth 2920limitations, the correct way is the following: 2921.Pp 2922.Dl "ipfw add pipe 1 ip from any to any out" 2923.Dl "ipfw add pipe 2 ip from any to any in" 2924.Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes" 2925.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes" 2926.Pp 2927The above can be very useful, e.g.\& if you want to see how 2928your fancy Web page will look for a residential user who 2929is connected only through a slow link. 2930You should not use only one pipe for both directions, unless 2931you want to simulate a half-duplex medium (e.g.\& AppleTalk, 2932Ethernet, IRDA). 2933It is not necessary that both pipes have the same configuration, 2934so we can also simulate asymmetric links. 2935.Pp 2936Should we want to verify network performance with the RED queue 2937management algorithm: 2938.Pp 2939.Dl "ipfw add pipe 1 ip from any to any" 2940.Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1" 2941.Pp 2942Another typical application of the traffic shaper is to 2943introduce some delay in the communication. 2944This can significantly affect applications which do a lot of Remote 2945Procedure Calls, and where the round-trip-time of the 2946connection often becomes a limiting factor much more than 2947bandwidth: 2948.Pp 2949.Dl "ipfw add pipe 1 ip from any to any out" 2950.Dl "ipfw add pipe 2 ip from any to any in" 2951.Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s" 2952.Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s" 2953.Pp 2954Per-flow queueing can be useful for a variety of purposes. 2955A very simple one is counting traffic: 2956.Pp 2957.Dl "ipfw add pipe 1 tcp from any to any" 2958.Dl "ipfw add pipe 1 udp from any to any" 2959.Dl "ipfw add pipe 1 ip from any to any" 2960.Dl "ipfw pipe 1 config mask all" 2961.Pp 2962The above set of rules will create queues (and collect 2963statistics) for all traffic. 2964Because the pipes have no limitations, the only effect is 2965collecting statistics. 2966Note that we need 3 rules, not just the last one, because 2967when 2968.Nm 2969tries to match IP packets it will not consider ports, so we 2970would not see connections on separate ports as different 2971ones. 2972.Pp 2973A more sophisticated example is limiting the outbound traffic 2974on a net with per-host limits, rather than per-network limits: 2975.Pp 2976.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 2977.Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in" 2978.Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 2979.Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 2980.Ss LOOKUP TABLES 2981In the following example, we need to create several traffic bandwidth 2982classes and we need different hosts/networks to fall into different classes. 2983We create one pipe for each class and configure them accordingly. 2984Then we create a single table and fill it with IP subnets and addresses. 2985For each subnet/host we set the argument equal to the number of the pipe 2986that it should use. 2987Then we classify traffic using a single rule: 2988.Pp 2989.Dl "ipfw pipe 1 config bw 1000Kbyte/s" 2990.Dl "ipfw pipe 4 config bw 4000Kbyte/s" 2991.Dl "..." 2992.Dl "ipfw table 1 add 192.168.2.0/24 1" 2993.Dl "ipfw table 1 add 192.168.0.0/27 4" 2994.Dl "ipfw table 1 add 192.168.0.2 1" 2995.Dl "..." 2996.Dl "ipfw add pipe tablearg ip from table(1) to any" 2997.Pp 2998Using the 2999.Cm fwd 3000action, the table entries may include hostnames and IP addresses. 3001.Pp 3002.Dl "ipfw table 1 add 192.168.2.0/24 10.23.2.1" 3003.Dl "ipfw table 1 add 192.168.0.0/27 router1.dmz" 3004.Dl "..." 3005.Dl "ipfw add 100 fwd tablearg ip from any to table(1)" 3006.Ss SETS OF RULES 3007To add a set of rules atomically, e.g.\& set 18: 3008.Pp 3009.Dl "ipfw set disable 18" 3010.Dl "ipfw add NN set 18 ... # repeat as needed" 3011.Dl "ipfw set enable 18" 3012.Pp 3013To delete a set of rules atomically the command is simply: 3014.Pp 3015.Dl "ipfw delete set 18" 3016.Pp 3017To test a ruleset and disable it and regain control if something goes wrong: 3018.Pp 3019.Dl "ipfw set disable 18" 3020.Dl "ipfw add NN set 18 ... # repeat as needed" 3021.Dl "ipfw set enable 18; echo done; sleep 30 && ipfw set disable 18" 3022.Pp 3023Here if everything goes well, you press control-C before the "sleep" 3024terminates, and your ruleset will be left active. 3025Otherwise, e.g.\& if 3026you cannot access your box, the ruleset will be disabled after 3027the sleep terminates thus restoring the previous situation. 3028.Pp 3029To show rules of the specific set: 3030.Pp 3031.Dl "ipfw set 18 show" 3032.Pp 3033To show rules of the disabled set: 3034.Pp 3035.Dl "ipfw -S set 18 show" 3036.Pp 3037To clear a specific rule counters of the specific set: 3038.Pp 3039.Dl "ipfw set 18 zero NN" 3040.Pp 3041To delete a specific rule of the specific set: 3042.Pp 3043.Dl "ipfw set 18 delete NN" 3044.Ss NAT, REDIRECT AND LSNAT 3045First redirect all the traffic to nat instance 123: 3046.Pp 3047.Dl "ipfw add nat 123 all from any to any" 3048.Pp 3049Then to configure nat instance 123 to alias all the outgoing traffic with ip 3050192.168.0.123, blocking all incoming connections, trying to keep 3051same ports on both sides, clearing aliasing table on address change 3052and keeping a log of traffic/link statistics: 3053.Pp 3054.Dl "ipfw nat 123 config ip 192.168.0.123 log deny_in reset same_ports" 3055.Pp 3056Or to change address of instance 123, aliasing table will be cleared (see 3057reset option): 3058.Pp 3059.Dl "ipfw nat 123 config ip 10.0.0.1" 3060.Pp 3061To see configuration of nat instance 123: 3062.Pp 3063.Dl "ipfw nat 123 show config" 3064.Pp 3065To show logs of all the instances in range 111-999: 3066.Pp 3067.Dl "ipfw nat 111-999 show" 3068.Pp 3069To see configurations of all instances: 3070.Pp 3071.Dl "ipfw nat show config" 3072.Pp 3073Or a redirect rule with mixed modes could looks like: 3074.Pp 3075.Dl "ipfw nat 123 config redirect_addr 10.0.0.1 10.0.0.66" 3076.Dl " redirect_port tcp 192.168.0.1:80 500" 3077.Dl " redirect_proto udp 192.168.1.43 192.168.1.1" 3078.Dl " redirect_addr 192.168.0.10,192.168.0.11" 3079.Dl " 10.0.0.100 # LSNAT" 3080.Dl " redirect_port tcp 192.168.0.1:80,192.168.0.10:22" 3081.Dl " 500 # LSNAT" 3082.Pp 3083or it could be split in: 3084.Pp 3085.Dl "ipfw nat 1 config redirect_addr 10.0.0.1 10.0.0.66" 3086.Dl "ipfw nat 2 config redirect_port tcp 192.168.0.1:80 500" 3087.Dl "ipfw nat 3 config redirect_proto udp 192.168.1.43 192.168.1.1" 3088.Dl "ipfw nat 4 config redirect_addr 192.168.0.10,192.168.0.11,192.168.0.12" 3089.Dl " 10.0.0.100" 3090.Dl "ipfw nat 5 config redirect_port tcp" 3091.Dl " 192.168.0.1:80,192.168.0.10:22,192.168.0.20:25 500" 3092.Pp 3093.Sh SEE ALSO 3094.Xr cpp 1 , 3095.Xr m4 1 , 3096.Xr altq 4 , 3097.Xr divert 4 , 3098.Xr dummynet 4 , 3099.Xr if_bridge 4 , 3100.Xr ip 4 , 3101.Xr ipfirewall 4 , 3102.Xr ng_ipfw 4 , 3103.Xr protocols 5 , 3104.Xr services 5 , 3105.Xr init 8 , 3106.Xr kldload 8 , 3107.Xr reboot 8 , 3108.Xr sysctl 8 , 3109.Xr syslogd 8 3110.Sh HISTORY 3111The 3112.Nm 3113utility first appeared in 3114.Fx 2.0 . 3115.Nm dummynet 3116was introduced in 3117.Fx 2.2.8 . 3118Stateful extensions were introduced in 3119.Fx 4.0 . 3120.Nm ipfw2 3121was introduced in Summer 2002. 3122.Sh AUTHORS 3123.An Ugen J. S. Antsilevich , 3124.An Poul-Henning Kamp , 3125.An Alex Nash , 3126.An Archie Cobbs , 3127.An Luigi Rizzo . 3128.Pp 3129.An -nosplit 3130API based upon code written by 3131.An Daniel Boulet 3132for BSDI. 3133.Pp 3134Dummynet has been introduced by Luigi Rizzo in 1997-1998. 3135.Pp 3136Some early work (1999-2000) on the 3137.Nm dummynet 3138traffic shaper supported by Akamba Corp. 3139.Pp 3140The ipfw core (ipfw2) has been completely redesigned and 3141reimplemented by Luigi Rizzo in summer 2002. Further 3142actions and 3143options have been added by various developer over the years. 3144.Pp 3145.An -nosplit 3146In-kernel NAT support written by 3147.An Paolo Pisati Aq piso@FreeBSD.org 3148as part of a Summer of Code 2005 project. 3149.Pp 3150SCTP 3151.Nm nat 3152support has been developed by 3153.An The Centre for Advanced Internet Architectures (CAIA) Aq http://www.caia.swin.edu.au . 3154The primary developers and maintainers are David Hayes and Jason But. 3155For further information visit: 3156.Aq http://www.caia.swin.edu.au/urp/SONATA 3157.Pp 3158Delay profiles have been developed by Alessandro Cerri and 3159Luigi Rizzo, supported by the 3160European Commission within Projects Onelab and Onelab2. 3161.Sh BUGS 3162The syntax has grown over the years and sometimes it might be confusing. 3163Unfortunately, backward compatibility prevents cleaning up mistakes 3164made in the definition of the syntax. 3165.Pp 3166.Em !!! WARNING !!! 3167.Pp 3168Misconfiguring the firewall can put your computer in an unusable state, 3169possibly shutting down network services and requiring console access to 3170regain control of it. 3171.Pp 3172Incoming packet fragments diverted by 3173.Cm divert 3174are reassembled before delivery to the socket. 3175The action used on those packet is the one from the 3176rule which matches the first fragment of the packet. 3177.Pp 3178Packets diverted to userland, and then reinserted by a userland process 3179may lose various packet attributes. 3180The packet source interface name 3181will be preserved if it is shorter than 8 bytes and the userland process 3182saves and reuses the sockaddr_in 3183(as does 3184.Xr natd 8 ) ; 3185otherwise, it may be lost. 3186If a packet is reinserted in this manner, later rules may be incorrectly 3187applied, making the order of 3188.Cm divert 3189rules in the rule sequence very important. 3190.Pp 3191Dummynet drops all packets with IPv6 link-local addresses. 3192.Pp 3193Rules using 3194.Cm uid 3195or 3196.Cm gid 3197may not behave as expected. 3198In particular, incoming SYN packets may 3199have no uid or gid associated with them since they do not yet belong 3200to a TCP connection, and the uid/gid associated with a packet may not 3201be as expected if the associated process calls 3202.Xr setuid 2 3203or similar system calls. 3204.Pp 3205Rule syntax is subject to the command line environment and some patterns 3206may need to be escaped with the backslash character 3207or quoted appropriately. 3208.Pp 3209Due to the architecture of 3210.Xr libalias 3 , 3211ipfw nat is not compatible with the TCP segmentation offloading (TSO). 3212Thus, to reliably nat your network traffic, please disable TSO 3213on your NICs using 3214.Xr ifconfig 8 . 3215.Pp 3216ICMP error messages are not implicitly matched by dynamic rules 3217for the respective conversations. 3218To avoid failures of network error detection and path MTU discovery, 3219ICMP error messages may need to be allowed explicitly through static 3220rules. 3221