1.\" 2.\" $FreeBSD$ 3.\" 4.Dd May 31, 2001 5.Dt IPFW 8 6.Os 7.Sh NAME 8.Nm ipfw 9.Nd IP firewall and traffic shaper control program 10.Sh SYNOPSIS 11.Nm 12.Op Fl q 13.Oo 14.Fl p Ar preproc 15.Oo Fl D 16.Ar macro Ns Op = Ns Ar value 17.Oc 18.Op Fl U Ar macro 19.Oc 20.Ar pathname 21.Nm 22.Op Fl f | q 23.Cm flush 24.Nm 25.Op Fl q 26.Es \&{ \&} 27.En Cm zero | resetlog | delete 28.Op Ar number ... 29.Nm 30.Op Fl s Op Ar field 31.Op Fl adeftN 32.Es \&{ \&} 33.En Cm list | show 34.Op Ar number ... 35.Nm 36.Op Fl q 37.Cm add 38.Op Ar number 39.Ar rule-body 40.Nm 41.Cm pipe 42.Ar number 43.Cm config 44.Ar pipe-config-options 45.Nm 46.Cm pipe 47.Es \&{ \&} 48.En Cm delete | list | show 49.Op Ar number ... 50.Nm 51.Cm queue 52.Ar number 53.Cm config 54.Ar queue-config-options 55.Nm 56.Cm queue 57.Es \&{ \&} 58.En Cm delete | list | show 59.Op Ar number ... 60.Sh DESCRIPTION 61.Nm 62is the user interface for controlling the 63.Xr ipfirewall 4 64and the 65.Xr dummynet 4 66traffic shaper in 67.Fx . 68.Pp 69Each incoming or outgoing packet is passed through the 70.Nm 71rules. 72If host is acting as a gateway, packets forwarded by 73the gateway are processed by 74.Nm 75twice. 76In case a host is acting as a bridge, packets forwarded by 77the bridge are processed by 78.Nm 79once. 80.Pp 81A firewall configuration is made of a list of numbered rules, 82which is scanned for each packet until a match is found and 83the relevant action is performed. 84Depending on the action and certain system settings, packets 85can be reinjected into the firewall at the rule after the 86matching one for further processing. 87All rules apply to all interfaces, so it is responsibility 88of the system administrator to write the ruleset in such a 89way as to minimize the number of checks. 90.Pp 91A configuration always includes a 92.Em DEFAULT 93rule (numbered 65535) which cannot be modified by the programmer 94and always matches packets. 95The action associated with the default rule can be either 96.Cm deny 97or 98.Cm allow 99depending on how the kernel is configured. 100.Pp 101If the ruleset includes one or more rules with the 102.Cm keep-state 103option, then 104.Nm 105assumes a 106.Em stateful 107behaviour, i.e. upon a match will create dynamic rules matching 108the exact parameters (addresses and ports) of the matching packet. 109.Pp 110These dynamic rules, which have a limited lifetime, are checked 111at the first occurrence of a 112.Cm check-state 113or 114.Cm keep-state 115rule, and are typically used to open the firewall on-demand to 116legitimate traffic only. 117See the 118.Sx RULE FORMAT 119and 120.Sx EXAMPLES 121sections below for more information on the stateful behaviour of 122.Nm . 123.Pp 124All rules (including dynamic ones) have a few associated counters: 125a packet count, a byte count, a log count and a timestamp 126indicating the time of the last match. 127Counters can be displayed or reset with 128.Nm 129commands. 130.Pp 131Rules can be added with the 132.Cm add 133command; deleted individually with the 134.Cm delete 135command, and globally with the 136.Cm flush 137command; displayed, optionally with the content of the 138counters, using the 139.Cm show 140and 141.Cm list 142commands. 143Finally, counters can be reset with the 144.Cm zero 145and 146.Cm resetlog 147commands. 148.Pp 149The following options are available: 150.Bl -tag -width indent 151.It Fl a 152While listing, show counter values. 153See also the 154.Cm show 155command. 156.It Fl d 157While listing, show dynamic rules in addition to static ones. 158.It Fl e 159While listing, if the 160.Fl d 161option was specified, also show expired dynamic rules. 162.It Fl f 163Don't ask for confirmation for commands that can cause problems 164if misused, 165.No i.e. Cm flush . 166.Em Note , 167if there is no tty associated with the process, this is implied. 168.It Fl q 169While 170.Cm add Ns ing , 171.Cm zero Ns ing , 172.Cm resetlog Ns ging 173or 174.Cm flush Ns ing , 175be quiet about actions 176(implies 177.Fl f ) . 178This is useful for adjusting rules by executing multiple 179.Nm 180commands in a script 181(e.g., 182.Ql sh\ /etc/rc.firewall ) , 183or by processing a file of many 184.Nm 185rules, 186across a remote login session. 187If a 188.Cm flush 189is performed in normal (verbose) mode (with the default kernel 190configuration), it prints a message. 191Because all rules are flushed, the message cannot be delivered 192to the login session. 193This causes the remote login session to be closed and the 194remainder of the ruleset is not processed. 195Access to the console is required to recover. 196.It Fl t 197While listing, show last match timestamp. 198.It Fl N 199Try to resolve addresses and service names in output. 200.It Fl s Op Ar field 201While listing pipes, sort according to one of the four 202counters (total and current packets or bytes). 203.El 204.Pp 205To ease configuration, rules can be put into a file which is 206processed using 207.Nm 208as shown in the first synopsis line. 209An absolute 210.Ar pathname 211must be used. 212The file 213will be read line by line and applied as arguments to the 214.Nm 215utility. 216.Pp 217Optionally, a preprocessor can be specified using 218.Fl p Ar preproc 219where 220.Ar pathname 221is to be piped through. 222Useful preprocessors include 223.Xr cpp 1 224and 225.Xr m4 1 . 226If 227.Ar preproc 228doesn't start with a slash 229.Pq Ql / 230as its first character, the usual 231.Ev PATH 232name search is performed. 233Care should be taken with this in environments where not all 234filesystems are mounted (yet) by the time 235.Nm 236is being run (e.g. when they are mounted over NFS). 237Once 238.Fl p 239has been specified, optional 240.Fl D 241and 242.Fl U 243specifications can follow and will be passed on to the preprocessor. 244This allows for flexible configuration files (like conditionalizing 245them on the local hostname) and the use of macros to centralize 246frequently required arguments like IP addresses. 247.Pp 248The 249.Nm 250.Cm pipe 251commands are used to configure the traffic shaper, as shown in the 252.Sx TRAFFIC SHAPER CONFIGURATION 253section below. 254.Sh RULE FORMAT 255The 256.Nm 257rule format is the following: 258.Bd -ragged 259.Op Cm prob Ar match_probability 260.Ar action 261.Op Cm log Op Cm logamount Ar number 262.Ar proto 263.Cm from Ar src 264.Cm to Ar dst 265.Op Ar interface-spec 266.Op Ar options 267.Ed 268.Pp 269Each packet can be filtered based on the following information that is 270associated with it: 271.Pp 272.Bl -tag -width "Source and destination IP address" -offset indent -compact 273.It Protocol 274(TCP, UDP, ICMP, etc.) 275.It Source and destination IP address 276(possibly masked) 277.It Source and destination port 278(lists, ranges or masks) 279.It Direction 280(incoming or outgoing) 281.It Transmit and receive interface 282(by name or address) 283.It IP version 284.It IP type of service 285.It IP datagram length 286.It IP identification 287.It IP fragment flag 288(non-zero IP offset) 289.It IP time to live 290.It IP options 291.It TCP sequence number 292.It TCP acknowledgment number 293.It TCP flags 294(SYN, FIN, ACK, RST, etc.) 295.It TCP window 296.It TCP options 297.It ICMP types 298(for ICMP packets) 299.It User/group ID of the socket associated with the packet 300.El 301.Pp 302Note that it may be dangerous to filter on the source IP 303address or source TCP/UDP port because either or both could 304easily be spoofed. 305.Bl -tag -width indent 306.It Cm prob Ar match_probability 307A match is only declared with the specified probability 308(floating point number between 0 and 1). 309This can be useful for a number of applications such as 310random packet drop or 311(in conjunction with 312.Xr dummynet 4 ) 313to simulate the effect of multiple paths leading to out-of-order 314packet delivery. 315.It Ar action : 316.Bl -tag -width indent 317.It Cm allow 318Allow packets that match rule. 319The search terminates. 320Aliases are 321.Cm pass , 322.Cm permit 323and 324.Cm accept . 325.It Cm deny 326Discard packets that match this rule. 327The search terminates. 328.Cm drop 329is an alias for 330.Cm deny . 331.It Cm reject 332(Deprecated). 333Discard packets that match this rule, and try to send an ICMP 334host unreachable notice. 335The search terminates. 336.It Cm unreach Ar code 337Discard packets that match this rule, and try to send an ICMP 338unreachable notice with code 339.Ar code , 340where 341.Ar code 342is a number from 0 to 255, or one of these aliases: 343.Cm net , host , protocol , port , 344.Cm needfrag , srcfail , net-unknown , host-unknown , 345.Cm isolated , net-prohib , host-prohib , tosnet , 346.Cm toshost , filter-prohib , host-precedence 347or 348.Cm precedence-cutoff . 349The search terminates. 350.It Cm reset 351TCP packets only. 352Discard packets that match this rule, and try to send a TCP 353reset (RST) notice. 354The search terminates. 355.It Cm count 356Update counters for all packets that match rule. 357The search continues with the next rule. 358.It Cm check-state 359Checks the packet against the dynamic ruleset. 360If a match is found then the search terminates, otherwise 361we move to the next rule. 362If no 363.Cm check-state 364rule is found, the dynamic ruleset is checked at the first 365.Cm keep-state 366rule. 367.It Cm divert Ar port 368Divert packets that match this rule to the 369.Xr divert 4 370socket bound to port 371.Ar port . 372The search terminates. 373.It Cm tee Ar port 374Send a copy of packets matching this rule to the 375.Xr divert 4 376socket bound to port 377.Ar port . 378The search terminates and the original packet is accepted 379(but see section 380.Sx BUGS 381below). 382.It Cm fwd Ar ipaddr Ns Xo 383.Op , Ns Ar port 384.Xc 385Change the next-hop on matching packets to 386.Ar ipaddr , 387which can be an IP address in dotted quad or a host name. 388If 389.Ar ipaddr 390is not a directly-reachable address, the route as found in 391the local routing table for that IP is used instead. 392If 393.Ar ipaddr 394is a local address, then on a packet entering the system 395from a remote host it will be diverted to 396.Ar port 397on the local machine, keeping the local address of the socket 398set to the original IP address the packet was destined for. 399This is intended for use with transparent proxy servers. 400If the IP is not a local address then the port number 401(if specified) is ignored and the rule only applies to packets 402leaving the system. 403This will also map addresses to local ports when packets are 404generated locally. 405The search terminates if this rule matches. 406If the port number is not given then the port number in the 407packet is used, so that a packet for an external machine port 408Y would be forwarded to local port Y. 409The kernel must have been compiled with the 410.Dv IPFIREWALL_FORWARD 411option. 412.It Cm pipe Ar pipe_nr 413Pass packet to a 414.Xr dummynet 4 415.Dq pipe 416(for bandwidth limitation, delay, etc.). 417See the 418.Sx TRAFFIC SHAPER CONFIGURATION 419section for further information. 420The search terminates; however, on exit from the pipe and if 421the 422.Xr sysctl 8 423variable 424.Em net.inet.ip.fw.one_pass 425is not set, the packet is passed again to the firewall code 426starting from the next rule. 427.It Cm queue Ar queue_nr 428Pass packet to a 429.Xr dummynet 4 430.Dq queue 431(for bandwidth limitation using WF2Q). 432.It Cm skipto Ar number 433Skip all subsequent rules numbered less than 434.Ar number . 435The search continues with the first rule numbered 436.Ar number 437or higher. 438.El 439.It Cm log Op Cm logamount Ar number 440If the kernel was compiled with 441.Dv IPFIREWALL_VERBOSE , 442then when a packet matches a rule with the 443.Cm log 444keyword a message will be 445logged to 446.Xr syslogd 8 447with a 448.Dv LOG_SECURITY 449facility. 450.Em Note : 451by default, they are appended to the 452.Pa /var/log/security 453file (see 454.Xr syslog.conf 5 ) . 455If the kernel was compiled with the 456.Dv IPFIREWALL_VERBOSE_LIMIT 457option, then by default logging will cease after the number 458of packets specified by the option are received for that 459particular chain entry, and 460.Em net.inet.ip.fw.verbose_limit 461will be set to that number. 462However, if 463.Cm logamount Ar number 464is used, that 465.Ar number 466will be the logging limit rather than 467.Em net.inet.ip.fw.verbose_limit , 468where the value 469.Dq 0 470removes the logging limit. 471Logging may then be re-enabled by clearing the logging counter 472or the packet counter for that entry. 473.Pp 474Console logging and the log limit are adjustable dynamically 475through the 476.Xr sysctl 8 477interface in the MIB base of 478.Em net.inet.ip.fw . 479.It Ar proto 480An IP protocol specified by number or name (for a complete 481list see 482.Pa /etc/protocols ) . 483The 484.Cm ip 485or 486.Cm all 487keywords mean any protocol will match. 488.It Ar src No and Ar dst : 489.Cm any | me | Op Cm not 490.Aq Ar address Ns / Ns Ar mask 491.Op Ar ports 492.Pp 493Specifying 494.Cm any 495makes the rule match any IP number. 496.Pp 497Specifying 498.Cm me 499makes the rule match any IP number configured on an interface in the system. 500This is a computationally semi-expensive check which should be used with care. 501.Pp 502The 503.Aq Ar address Ns / Ns Ar mask 504may be specified as: 505.Bl -tag -width "ipno/bits" 506.It Ar ipno 507An IP number of the form 1.2.3.4. 508Only this exact IP number will match the rule. 509.It Ar ipno Ns / Ns Ar bits 510An IP number with a mask width of the form 1.2.3.4/24. 511In this case all IP numbers from 1.2.3.0 to 1.2.3.255 will match. 512.It Ar ipno Ns : Ns Ar mask 513An IP number with a mask of the form 1.2.3.4:255.255.240.0. 514In this case all IP numbers from 1.2.0.0 to 1.2.15.255 will match. 515.El 516.Pp 517The sense of the match can be inverted by preceding an address with the 518.Cm not 519modifier, causing all other addresses to be matched instead. 520This does not affect the selection of port numbers. 521.Pp 522With the TCP and UDP protocols, optional 523.Em ports 524may be specified as: 525.Bd -ragged -offset indent 526.Sm off 527.Eo \&{ 528.Ar port | 529.Ar port No \&- Ar port | 530.Ar port : mask 531.Ec \&} Op , Ar port Op , Ar ... 532.Sm on 533.Ed 534.Pp 535The 536.Ql \&- 537notation specifies a range of ports (including boundaries). 538.Pp 539The 540.Ql \&: 541notation specifies a port and a mask, a match is declared if 542the port number in the packet matches the one in the rule, 543limited to the bits which are set in the mask. 544.Pp 545Service names (from 546.Pa /etc/services ) 547may be used instead of numeric port values. 548A range may only be specified as the first value, and the 549length of the port list is limited to 550.Dv IP_FW_MAX_PORTS 551ports (as defined in 552.Pa /usr/src/sys/netinet/ip_fw.h ) . 553A backslash 554.Pq Ql \e 555can be used to escape the dash 556.Pq Ql - 557character in a service name: 558.Pp 559.Dl "ipfw add count tcp from any ftp\e\e-data-ftp to any" 560.Pp 561Fragmented packets which have a non-zero offset (i.e. not the first 562fragment) will never match a rule which has one or more port 563specifications. 564See the 565.Cm frag 566option for details on matching fragmented packets. 567.It Ar interface-spec 568Some combinations of the following specifiers are allowed: 569.Bl -tag -width "via ipno" 570.It Cm in 571Only match incoming packets. 572.It Cm out 573Only match outgoing packets. 574.It Cm via Ar ifX 575Packet must be going through interface 576.Ar ifX . 577.It Cm via Ar if Ns Cm * 578Packet must be going through interface 579.Ar ifX , 580where 581.Ar X 582is any unit number. 583.It Cm via any 584Packet must be going through 585.Em some 586interface. 587.It Cm via Ar ipno 588Packet must be going through the interface having IP address 589.Ar ipno . 590.El 591.Pp 592The 593.Cm via 594keyword causes the interface to always be checked. 595If 596.Cm recv 597or 598.Cm xmit 599is used instead of 600.Cm via , 601then the only receive or transmit interface (respectively) 602is checked. 603By specifying both, it is possible to match packets based on 604both receive and transmit interface, e.g.: 605.Pp 606.Dl "ipfw add 100 deny ip from any to any out recv ed0 xmit ed1" 607.Pp 608The 609.Cm recv 610interface can be tested on either incoming or outgoing packets, 611while the 612.Cm xmit 613interface can only be tested on outgoing packets. 614So 615.Cm out 616is required (and 617.Cm in 618is invalid) whenever 619.Cm xmit 620is used. 621Specifying 622.Cm via 623together with 624.Cm xmit 625or 626.Cm recv 627is invalid. 628.Pp 629A packet may not have a receive or transmit interface: packets 630originating from the local host have no receive interface, 631while packets destined for the local host have no transmit 632interface. 633.It Ar options : 634.Bl -tag -width indent 635.It Cm keep-state Op Ar method 636Upon a match, the firewall will create a dynamic rule, whose 637default behaviour is to matching bidirectional traffic between 638source and destination IP/port using the same protocol. 639The rule has a limited lifetime (controlled by a set of 640.Xr sysctl 8 641variables), and the lifetime is refreshed every time a matching 642packet is found. 643.Pp 644The actual behaviour can be modified by specifying a different 645.Ar method , 646although at the moment only the default one is specified. 647.It Cm bridged 648Matches only bridged packets. 649This can be useful for multicast or broadcast traffic, which 650would otherwise pass through the firewall twice: once during 651bridging, and a second time when the packet is delivered to 652the local stack. 653.Pp 654Apart from a small performance penalty, this would be a problem 655when using 656.Em pipes 657because the same packet would be accounted for twice in terms 658of bandwidth, queue occupation, and also counters. 659.It Cm ipversion Ar ver 660Match if the IP header version is 661.Ar ver . 662.It Cm iptos Ar spec 663Match if the IP header contains the comma separated list of 664service types specified in 665.Ar spec . 666The supported IP types of service are: 667.Pp 668.Cm lowdelay 669.Pq Dv IPTOS_LOWDELAY , 670.Cm throughput 671.Pq Dv IPTOS_THROUGHPUT , 672.Cm reliability 673.Pq Dv IPTOS_RELIABILITY , 674.Cm mincost 675.Pq Dv IPTOS_MINCOST , 676.Cm congestion 677.Pq Dv IPTOS_CE . 678The absence of a particular type may be denoted 679with a 680.Ql \&! . 681.It Cm iplen Ar len 682Match if the total length of a packet, including header and data, is 683.Ar len 684bytes. 685.It Cm ipid Ar id 686Match if the identification of IP datagram is 687.Ar id . 688.It Cm frag 689Match if the packet is a fragment and this is not the first 690fragment of the datagram. 691.Cm frag 692may not be used in conjunction with either 693.Cm tcpflags 694or TCP/UDP port specifications. 695.It Cm ipttl Ar ttl 696Match if the time to live of IP datagram is 697.Ar ttl . 698.It Cm ipoptions Ar spec 699Match if the IP header contains the comma separated list of 700options specified in 701.Ar spec . 702The supported IP options are: 703.Pp 704.Cm ssrr 705(strict source route), 706.Cm lsrr 707(loose source route), 708.Cm rr 709(record packet route) and 710.Cm ts 711(timestamp). 712The absence of a particular option may be denoted 713with a 714.Ql \&! . 715.It Cm tcpseq Ar seq 716TCP packets only. 717Match if the TCP header sequence number field is set to 718.Ar seq . 719.It Cm tcpack Ar ack 720TCP packets only. 721Match if the TCP header acknowledgment number field is set to 722.Ar ack . 723.It Cm tcpflags Ar spec 724TCP packets only. 725Match if the TCP header contains the comma separated list of 726flags specified in 727.Ar spec . 728The supported TCP flags are: 729.Pp 730.Cm fin , 731.Cm syn , 732.Cm rst , 733.Cm psh , 734.Cm ack 735and 736.Cm urg . 737The absence of a particular flag may be denoted 738with a 739.Ql \&! . 740A rule which contains a 741.Cm tcpflags 742specification can never match a fragmented packet which has 743a non-zero offset. 744See the 745.Cm frag 746option for details on matching fragmented packets. 747.It Cm established 748TCP packets only. 749Match packets that have the RST or ACK bits set. 750.It Cm setup 751TCP packets only. 752Match packets that have the SYN bit set but no ACK bit. 753This is the short form of 754.Dq Li tcpflags\ syn,!ack . 755.It Cm tcpwin Ar win 756TCP packets only. 757Match if the TCP header window field is set to 758.Ar win . 759.It Cm tcpoptions Ar spec 760TCP packets only. 761Match if the TCP header contains the comma separated list of 762options specified in 763.Ar spec . 764The supported TCP options are: 765.Pp 766.Cm mss 767(maximum segment size), 768.Cm window 769(tcp window advertisement), 770.Cm sack 771(selective ack), 772.Cm ts 773(rfc1323 timestamp) and 774.Cm cc 775(rfc1644 t/tcp connection count). 776The absence of a particular option may be denoted 777with a 778.Ql \&! . 779.It Cm icmptypes Ar types 780ICMP packets only. 781Match if the ICMP type is in the list 782.Ar types . 783The list may be specified as any combination of ranges or 784individual types separated by commas. 785The supported ICMP types are: 786.Pp 787echo reply 788.Pq Cm 0 , 789destination unreachable 790.Pq Cm 3 , 791source quench 792.Pq Cm 4 , 793redirect 794.Pq Cm 5 , 795echo request 796.Pq Cm 8 , 797router advertisement 798.Pq Cm 9 , 799router solicitation 800.Pq Cm 10 , 801time-to-live exceeded 802.Pq Cm 11 , 803IP header bad 804.Pq Cm 12 , 805timestamp request 806.Pq Cm 13 , 807timestamp reply 808.Pq Cm 14 , 809information request 810.Pq Cm 15 , 811information reply 812.Pq Cm 16 , 813address mask request 814.Pq Cm 17 815and address mask reply 816.Pq Cm 18 . 817.It Cm uid Ar user 818Match all TCP or UDP packets sent by or received for a 819.Ar user . 820A 821.Ar user 822may be matched by name or identification number. 823.It Cm gid Ar group 824Match all TCP or UDP packets sent by or received for a 825.Ar group . 826A 827.Ar group 828may be matched by name or identification number. 829.El 830.El 831.Sh TRAFFIC SHAPER CONFIGURATION 832The 833.Nm 834utility is also the user interface for the 835.Xr dummynet 4 836traffic shaper. 837The shaper operates by dividing packets into 838.Em flows 839according to a user-specified mask on different fields 840of the IP header. 841Packets belonging to the same flow are then passed to two 842different objects, named 843.Em pipe 844or 845.Em queue . 846.Pp 847A 848.Em pipe 849emulates a link with given bandwidth, propagation delay, 850queue size and packet loss rate. 851Packets transit through the pipe according to its parameters. 852.Pp 853A 854.Em queue 855is an abstraction used to implement the WF2Q+ policy. 856The queue associates to each flow a weight and a reference pipe. 857Then, all flows linked to the same pipe are scheduled at the 858rate fixed by the pipe according to the WF2Q+ policy. 859.Pp 860The 861.Nm 862pipe configuration format is the following: 863.Bd -ragged 864.Cm pipe Ar number Cm config 865.Op Cm bw Ar bandwidth | device 866.Op Cm delay Ar ms-delay 867.Oo 868.Cm queue 869.Es \&{ \&} 870.En Ar slots | size 871.Oc 872.Op Cm plr Ar loss-probability 873.Op Cm mask Ar mask-specifier 874.Op Cm buckets Ar hash-table-size 875.Oo 876.Cm red | gred 877.Sm off 878.Ar w_q No / Xo 879.Ar min_th No / 880.Ar max_th No / 881.Ar max_p 882.Xc 883.Sm on 884.Oc 885.Ed 886.Pp 887The 888.Nm 889queue configuration format is the following: 890.Bd -ragged 891.Cm queue Ar number Cm config 892.Op Cm pipe Ar pipe_nr 893.Op Cm weight Ar weight 894.Oo 895.Cm queue 896.Es \&{ \&} 897.En Ar slots | size 898.Oc 899.Op Cm plr Ar loss-probability 900.Op Cm mask Ar mask-specifier 901.Op Cm buckets Ar hash-table-size 902.Oo 903.Cm red | gred 904.Sm off 905.Ar w_q No / Xo 906.Ar min_th No / 907.Ar max_th No / 908.Ar max_p 909.Xc 910.Sm on 911.Oc 912.Ed 913.Pp 914The following parameters can be configured for a pipe: 915.Bl -tag -width indent 916.It Cm bw Ar bandwidth | device 917Bandwidth, measured in 918.Sm off 919.Oo 920.Cm K | M 921.Oc Eo \&{ 922.Cm bit/s | Byte/s 923.Ec \&} . 924.Sm on 925.Pp 926A value of 0 (default) means unlimited bandwidth. 927The unit must follow immediately the number, as in 928.Pp 929.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes" 930.Pp 931If a device name is specified instead of a numeric 932value, then the transmit clock is supplied by the specified 933device. 934At the moment only the 935.Xr tun 4 936device supports this 937functionality, for use in conjunction with 938.Xr ppp 8 . 939.It Cm delay Ar ms-delay 940Propagation delay, measured in milliseconds. 941The value is rounded to the next multiple of the clock tick 942(typically 10ms, but it is a good practice to run kernels 943with 944.Dq "options HZ=1000" 945to reduce 946the granularity to 1ms or less). 947Default value is 0, meaning no delay. 948.It Cm queue Xo 949.Es \&{ \&} 950.En Ar slots | size Ns Cm Kbytes 951.Xc 952Queue size, in 953.Ar slots 954or 955.Cm KBytes . 956Default value is 50 slots, which 957is the typical queue size for Ethernet devices. 958Note that for slow speed links you should keep the queue 959size short or your traffic might be affected by a significant 960queueing delay. 961E.g., 50 max-sized ethernet packets (1500 bytes) mean 600Kbit 962or 20s of queue on a 30Kbit/s pipe. 963Even worse effect can result if you get packets from an 964interface with a much larger MTU, e.g. the loopback interface 965with its 16KB packets. 966.It Cm plr Ar packet-loss-rate 967Packet loss rate. 968Argument 969.Ar packet-loss-rate 970is a floating-point number between 0 and 1, with 0 meaning no 971loss, 1 meaning 100% loss. 972The loss rate is internally represented on 31 bits. 973.It Cm mask Ar mask-specifier 974The 975.Xr dummynet 4 976lets you to create per-flow queues. 977A flow identifier is constructed by masking the IP addresses, 978ports and protocol types as specified in the pipe configuration. 979Packets with the same identifier after masking fall into the 980same queue. 981Available mask specifiers are a combination of the following: 982.Cm dst-ip Ar mask , 983.Cm src-ip Ar mask , 984.Cm dst-port Ar mask , 985.Cm src-port Ar mask , 986.Cm proto Ar mask 987or 988.Cm all , 989where the latter means all bits in all fields are significant. 990When used within a 991.Ar pipe 992configuration, each flow is assigned a rate equal 993to the rate of the pipe. 994When used within a 995.Ar queue 996configuration, each flow is assigned a weight equal to the 997weight of the queue, and all flows insisting on the same pipe 998share bandwidth proportionally to their weight. 999.It Cm buckets Ar hash-table-size 1000Specifies the size of the hash table used for storing the 1001various queues. 1002Default value is 64 controlled by the 1003.Xr sysctl 8 1004variable 1005.Em net.inet.ip.dummynet.hash_size , 1006allowed range is 16 to 1024. 1007.It Cm pipe Ar pipe_nr 1008Connects a queue to the specified pipe. 1009Multiple queues (usually 1010with different weights) can be connected to the same pipe, which 1011specifies the aggregate rate for the set of queues. 1012.It Cm weight Ar weight 1013Specifies the weight to be used for flows matching this queue. 1014The weight must be in the range 1..100, and defaults to 1. 1015.It Cm red | gred Xo 1016.Sm off 1017.Ar w_q No / 1018.Ar min_th No / 1019.Ar max_th No / 1020.Ar max_p 1021.Sm on 1022.Xc 1023Make use of the RED queue management algorithm. 1024.Ar w_q 1025and 1026.Ar max_p 1027are floating 1028point numbers between 0 and 1 (0 not included), while 1029.Ar min_th 1030and 1031.Ar max_th 1032are integer numbers specifying thresholds for queue management 1033(thresholds are computed in bytes if the queue has been defined 1034in bytes, in slots otherwise). 1035The 1036.Xr dummynet 4 1037also supports the gentle RED variant (gred). 1038Three 1039.Xr sysctl 8 1040variables can be used to control the RED behaviour: 1041.Bl -tag -width indent 1042.It Em net.inet.ip.dummynet.red_lookup_depth 1043specifies the accuracy in computing the average queue 1044when the link is idle (defaults to 256, must be greater than zero) 1045.It Em net.inet.ip.dummynet.red_avg_pkt_size 1046specifies the expected average packet size (defaults to 512, must be 1047greater than zero) 1048.It Em net.inet.ip.dummynet.red_max_pkt_size 1049specifies the expected maximum packet size, only used when queue 1050thresholds are in bytes (defaults to 1500, must be greater than zero). 1051.El 1052.El 1053.Sh CHECKLIST 1054Here are some important points to consider when designing your 1055rules: 1056.Bl -bullet 1057.It 1058Remember that you filter both packets going 1059.Cm in 1060and 1061.Cm out . 1062Most connections need packets going in both directions. 1063.It 1064Remember to test very carefully. 1065It is a good idea to be near the console when doing this. 1066If you cannot be near the console, 1067use an auto-recovery script such as the one in 1068.Pa /usr/share/examples/ipfw/change_rules.sh . 1069.It 1070Don't forget the loopback interface. 1071.El 1072.Sh FINE POINTS 1073.Bl -bullet 1074.It 1075There is one kind of packet that the firewall will always 1076discard, that is a TCP packet's fragment with a fragment offset of 1077one. 1078This is a valid packet, but it only has one use, to try 1079to circumvent firewalls. 1080When logging is enabled, these packets are 1081reported as being dropped by rule -1. 1082.It 1083If you are logged in over a network, loading the 1084.Xr kld 4 1085version of 1086.Nm 1087is probably not as straightforward as you would think. 1088I recommend the following command line: 1089.Bd -literal -offset indent 1090kldload /modules/ipfw.ko && \e 1091ipfw add 32000 allow ip from any to any 1092.Ed 1093.Pp 1094Along the same lines, doing an 1095.Bd -literal -offset indent 1096ipfw flush 1097.Ed 1098.Pp 1099in similar surroundings is also a bad idea. 1100.It 1101The 1102.Nm 1103filter list may not be modified if the system security level 1104is set to 3 or higher 1105(see 1106.Xr init 8 1107for information on system security levels). 1108.El 1109.Sh PACKET DIVERSION 1110A 1111.Xr divert 4 1112socket bound to the specified port will receive all packets 1113diverted to that port. 1114If no socket is bound to the destination port, or if the kernel 1115wasn't compiled with divert socket support, the packets are 1116dropped. 1117.Sh SYSCTL VARIABLES 1118A set of 1119.Xr sysctl 8 1120variables controls the behaviour of the firewall. 1121These are shown below together with their default value and 1122meaning: 1123.Bl -tag -width indent 1124.It Em net.inet.ip.fw.debug : No 1 1125Controls debugging messages produced by 1126.Nm . 1127.It Em net.inet.ip.fw.one_pass : No 1 1128When set, the packet exiting from the 1129.Xr dummynet 4 1130pipe is not passed though the firewall again. 1131Otherwise, after a pipe action, the packet is 1132reinjected into the firewall at the next rule. 1133.It Em net.inet.ip.fw.verbose : No 1 1134Enables verbose messages. 1135.It Em net.inet.ip.fw.enable : No 1 1136Enables the firewall. 1137Setting this variable to 0 lets you run your machine without 1138firewall even if compiled in. 1139.It Em net.inet.ip.fw.verbose_limit : No 0 1140Limits the number of messages produced by a verbose firewall. 1141.It Em net.inet.ip.fw.dyn_buckets : No 256 1142.It Em net.inet.ip.fw.curr_dyn_buckets : No 256 1143The configured and current size of the hash table used to 1144hold dynamic rules. 1145This must be a power of 2. 1146The table can only be resized when empty, so in order to 1147resize it on the fly you will probably have to 1148.Cm flush 1149and reload the ruleset. 1150.It Em net.inet.ip.fw.dyn_count : No 3 1151Current number of dynamic rules 1152(read-only). 1153.It Em net.inet.ip.fw.dyn_max : No 1000 1154Maximum number of dynamic rules. 1155When you hit this limit, no more dynamic rules can be 1156installed until old ones expire. 1157.It Em net.inet.ip.fw.dyn_ack_lifetime : No 300 1158.It Em net.inet.ip.fw.dyn_syn_lifetime : No 20 1159.It Em net.inet.ip.fw.dyn_fin_lifetime : No 20 1160.It Em net.inet.ip.fw.dyn_rst_lifetime : No 5 1161.It Em net.inet.ip.fw.dyn_short_lifetime : No 30 1162These variables control the lifetime, in seconds, of dynamic 1163rules. 1164Upon the initial SYN exchange the lifetime is kept short, 1165then increased after both SYN have been seen, then decreased 1166again during the final FIN exchange or when a RST 1167.El 1168.Sh EXAMPLES 1169This command adds an entry which denies all tcp packets from 1170.Em cracker.evil.org 1171to the telnet port of 1172.Em wolf.tambov.su 1173from being forwarded by the host: 1174.Pp 1175.Dl "ipfw add deny tcp from cracker.evil.org to wolf.tambov.su telnet" 1176.Pp 1177This one disallows any connection from the entire crackers 1178network to my host: 1179.Pp 1180.Dl "ipfw add deny ip from 123.45.67.0/24 to my.host.org" 1181.Pp 1182A first and efficient way to limit access (not using dynamic rules) 1183is the use of the following rules: 1184.Pp 1185.Dl "ipfw add allow tcp from any to any established" 1186.Dl "ipfw add allow tcp from net1 portlist1 to net2 portlist2 setup" 1187.Dl "ipfw add allow tcp from net3 portlist3 to net3 portlist3 setup" 1188.Dl "..." 1189.Dl "ipfw add deny tcp from any to any" 1190.Pp 1191The first rule will be a quick match for normal TCP packets, 1192but it will not match the initial SYN packet, which will be 1193matched by the 1194.Cm setup 1195rules only for selected source/destination pairs. 1196All other SYN packets will be rejected by the final 1197.Cm deny 1198rule. 1199.Pp 1200In order to protect a site from flood attacks involving fake 1201TCP packets, it is safer to use dynamic rules: 1202.Pp 1203.Dl "ipfw add check-state" 1204.Dl "ipfw add deny tcp from any to any established" 1205.Dl "ipfw add allow tcp from my-net to any setup keep-state" 1206.Pp 1207This will let the firewall install dynamic rules only for 1208those connection which start with a regular SYN packet coming 1209from the inside of our network. 1210Dynamic rules are checked when encountering the first 1211.Cm check-state 1212or 1213.Cm keep-state 1214rule. 1215A 1216.Cm check-state 1217rule should be usually placed near the beginning of the 1218ruleset to minimize the amount of work scanning the ruleset. 1219Your mileage may vary. 1220.Pp 1221.Em BEWARE : 1222stateful rules can be subject to denial-of-service attacks 1223by a SYN-flood which opens a huge number of dynamic rules. 1224The effects of such attacks can be partially limited by 1225acting on a set of 1226.Xr sysctl 8 1227variables which control the operation of the firewall. 1228.Pp 1229Here is a good usage of the 1230.Cm list 1231command to see accounting records and timestamp information: 1232.Pp 1233.Dl ipfw -at list 1234.Pp 1235or in short form without timestamps: 1236.Pp 1237.Dl ipfw -a list 1238.Pp 1239Next rule diverts all incoming packets from 192.168.2.0/24 1240to divert port 5000: 1241.Pp 1242.Dl ipfw divert 5000 ip from 192.168.2.0/24 to any in 1243.Pp 1244The following rules show some of the applications of 1245.Nm 1246and 1247.Xr dummynet 4 1248for simulations and the like. 1249.Pp 1250This rule drops random incoming packets with a probability 1251of 5%: 1252.Pp 1253.Dl "ipfw add prob 0.05 deny ip from any to any in" 1254.Pp 1255A similar effect can be achieved making use of dummynet pipes: 1256.Pp 1257.Dl "ipfw add pipe 10 ip from any to any" 1258.Dl "ipfw pipe 10 config plr 0.05" 1259.Pp 1260We can use pipes to artificially limit bandwidth, e.g. on a 1261machine acting as a router, if we want to limit traffic from 1262local clients on 192.168.2.0/24 we do: 1263.Pp 1264.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 1265.Dl "ipfw pipe 1 config bw 300Kbit/s queue 50KBytes" 1266.Pp 1267note that we use the 1268.Cm out 1269modifier so that the rule is not used twice. 1270Remember in fact that 1271.Nm 1272rules are checked both on incoming and outgoing packets. 1273.Pp 1274Should we like to simulate a bidirectional link with bandwidth 1275limitations, the correct way is the following: 1276.Pp 1277.Dl "ipfw add pipe 1 ip from any to any out" 1278.Dl "ipfw add pipe 2 ip from any to any in" 1279.Dl "ipfw pipe 1 config bw 64Kbit/s queue 10Kbytes" 1280.Dl "ipfw pipe 2 config bw 64Kbit/s queue 10Kbytes" 1281.Pp 1282The above can be very useful, e.g. if you want to see how 1283your fancy Web page will look for a residential user which 1284is connected only through a slow link. 1285You should not use only one pipe for both directions, unless 1286you want to simulate a half-duplex medium (e.g. AppleTalk, 1287Ethernet, IRDA). 1288It is not necessary that both pipes have the same configuration, 1289so we can also simulate asymmetric links. 1290.Pp 1291Should we like to verify network performance with the RED queue 1292management algorithm: 1293.Pp 1294.Dl "ipfw add pipe 1 ip from any to any" 1295.Dl "ipfw pipe 1 config bw 500Kbit/s queue 100 red 0.002/30/80/0.1" 1296.Pp 1297Another typical application of the traffic shaper is to 1298introduce some delay in the communication. 1299This can affect a lot applications which do a lot of Remote 1300Procedure Calls, and where the round-trip-time of the 1301connection often becomes a limiting factor much more than 1302bandwidth: 1303.Pp 1304.Dl "ipfw add pipe 1 ip from any to any out" 1305.Dl "ipfw add pipe 2 ip from any to any in" 1306.Dl "ipfw pipe 1 config delay 250ms bw 1Mbit/s" 1307.Dl "ipfw pipe 2 config delay 250ms bw 1Mbit/s" 1308.Pp 1309Per-flow queueing can be useful for a variety of purposes. 1310A very simple one is counting traffic: 1311.Pp 1312.Dl "ipfw add pipe 1 tcp from any to any" 1313.Dl "ipfw add pipe 1 udp from any to any" 1314.Dl "ipfw add pipe 1 ip from any to any" 1315.Dl "ipfw pipe 1 config mask all" 1316.Pp 1317The above set of rules will create queues (and collect 1318statistics) for all traffic. 1319Because the pipes have no limitations, the only effect is 1320collecting statistics. 1321Note that we need 3 rules, not just the last one, because 1322when 1323.Nm 1324tries to match IP packets it will not consider ports, so we 1325would not see connections on separate ports as different 1326ones. 1327.Pp 1328A more sophisticated example is limiting the outbound traffic 1329on a net with per-host limits, rather than per-network limits: 1330.Pp 1331.Dl "ipfw add pipe 1 ip from 192.168.2.0/24 to any out" 1332.Dl "ipfw add pipe 2 ip from any to 192.168.2.0/24 in" 1333.Dl "ipfw pipe 1 config mask src-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 1334.Dl "ipfw pipe 2 config mask dst-ip 0x000000ff bw 200Kbit/s queue 20Kbytes" 1335.Sh SEE ALSO 1336.Xr cpp 1 , 1337.Xr m4 1 , 1338.Xr bridge 4 , 1339.Xr divert 4 , 1340.Xr dummynet 4 , 1341.Xr ip 4 , 1342.Xr ipfirewall 4 , 1343.Xr protocols 5 , 1344.Xr services 5 , 1345.Xr init 8 , 1346.Xr kldload 8 , 1347.Xr reboot 8 , 1348.Xr sysctl 8 , 1349.Xr syslogd 8 1350.Sh BUGS 1351The syntax has grown over the years and it is not very clean. 1352.Pp 1353.Em WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!!WARNING!! 1354.Pp 1355This program can put your computer in rather unusable state. 1356When using it for the first time, work on the console of the 1357computer, and do 1358.Em NOT 1359do anything you don't understand. 1360.Pp 1361When manipulating/adding chain entries, service and protocol names 1362are not accepted. 1363.Pp 1364Incoming packet fragments diverted by 1365.Cm divert 1366or 1367.Cm tee 1368are reassembled before delivery to the socket. 1369.Pp 1370Packets that match a 1371.Cm tee 1372rule should not be immediately accepted, but should continue 1373going through the rule list. 1374This may be fixed in a later version. 1375.Sh AUTHORS 1376.An Ugen J. S. Antsilevich , 1377.An Poul-Henning Kamp , 1378.An Alex Nash , 1379.An Archie Cobbs , 1380.An Luigi Rizzo . 1381.Pp 1382.An -nosplit 1383API based upon code written by 1384.An Daniel Boulet 1385for BSDI. 1386.Pp 1387Work on 1388.Xr dummynet 4 1389traffic shaper supported by Akamba Corp. 1390.Sh HISTORY 1391The 1392.Nm 1393utility first appeared in 1394.Fx 2.0 . 1395.Xr dummynet 4 1396was introduced in 1397.Fx 2.2.8 . 1398Stateful extensions were introduced in 1399.Fx 4.0 . 1400