1.\" $NetBSD: pf.conf.5,v 1.5 2005/08/07 00:53:13 peter Exp $ 2.\" $OpenBSD: pf.conf.5,v 1.326 2005/03/01 18:10:44 jmc Exp $ 3.\" 4.\" Copyright (c) 2002, Daniel Hartmeier 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" - Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" - Redistributions in binary form must reproduce the above 14.\" copyright notice, this list of conditions and the following 15.\" disclaimer in the documentation and/or other materials provided 16.\" with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 21.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 22.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 23.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 24.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 25.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 26.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 28.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 29.\" POSSIBILITY OF SUCH DAMAGE. 30.\" 31.Dd November 19, 2002 32.Dt PF.CONF 5 33.Os 34.Sh NAME 35.Nm pf.conf 36.Nd packet filter configuration file 37.Sh DESCRIPTION 38The 39.Xr pf 4 40packet filter modifies, drops or passes packets according to rules or 41definitions specified in 42.Nm pf.conf . 43.Sh STATEMENT ORDER 44There are seven types of statements in 45.Nm pf.conf : 46.Bl -tag -width xxxx 47.It Cm Macros 48User-defined variables may be defined and used later, simplifying 49the configuration file. 50Macros must be defined before they are referenced in 51.Nm pf.conf . 52.It Cm Tables 53Tables provide a mechanism for increasing the performance and flexibility of 54rules with large numbers of source or destination addresses. 55.It Cm Options 56Options tune the behaviour of the packet filtering engine. 57.It Cm Traffic Normalization Li (e.g. Em scrub ) 58Traffic normalization protects internal machines against inconsistencies 59in Internet protocols and implementations. 60.It Cm Queueing 61Queueing provides rule-based bandwidth control. 62.It Cm Translation Li (Various forms of NAT) 63Translation rules specify how addresses are to be mapped or redirected to 64other addresses. 65.It Cm Packet Filtering 66Stateful and stateless packet filtering provides rule-based blocking or 67passing of packets. 68.El 69.Pp 70With the exception of 71.Cm macros 72and 73.Cm tables , 74the types of statements should be grouped and appear in 75.Nm pf.conf 76in the order shown above, as this matches the operation of the underlying 77packet filtering engine. 78By default 79.Xr pfctl 8 80enforces this order (see 81.Ar set require-order 82below). 83.Sh MACROS 84Much like 85.Xr cpp 1 86or 87.Xr m4 1 , 88macros can be defined that will later be expanded in context. 89Macro names must start with a letter, and may contain letters, digits 90and underscores. 91Macro names may not be reserved words (for example 92.Ar pass , 93.Ar in , 94.Ar out ) . 95Macros are not expanded inside quotes. 96.Pp 97For example, 98.Bd -literal -offset indent 99ext_if = \&"kue0\&" 100all_ifs = \&"{\&" $ext_if lo0 \&"}\&" 101pass out on $ext_if from any to any keep state 102pass in on $ext_if proto tcp from any to any port 25 keep state 103.Ed 104.Sh TABLES 105Tables are named structures which can hold a collection of addresses and 106networks. 107Lookups against tables in 108.Xr pf 4 109are relatively fast, making a single rule with tables much more efficient, 110in terms of 111processor usage and memory consumption, than a large number of rules which 112differ only in IP address (either created explicitly or automatically by rule 113expansion). 114.Pp 115Tables can be used as the source or destination of filter rules, 116.Ar scrub 117rules 118or 119translation rules such as 120.Ar nat 121or 122.Ar rdr 123(see below for details on the various rule types). 124Tables can also be used for the redirect address of 125.Ar nat 126and 127.Ar rdr 128rules and in the routing options of filter rules, but only for 129.Ar round-robin 130pools. 131.Pp 132Tables can be defined with any of the following 133.Xr pfctl 8 134mechanisms. 135As with macros, reserved words may not be used as table names. 136.Bl -tag -width "manually" 137.It Ar manually 138Persistent tables can be manually created with the 139.Ar add 140or 141.Ar replace 142option of 143.Xr pfctl 8 , 144before or after the ruleset has been loaded. 145.It Pa pf.conf 146Table definitions can be placed directly in this file, and loaded at the 147same time as other rules are loaded, atomically. 148Table definitions inside 149.Nm pf.conf 150use the 151.Ar table 152statement, and are especially useful to define non-persistent tables. 153The contents of a pre-existing table defined without a list of addresses 154to initialize it is not altered when 155.Nm pf.conf 156is loaded. 157A table initialized with the empty list, 158.Li { } , 159will be cleared on load. 160.El 161.Pp 162Tables may be defined with the following two attributes: 163.Bl -tag -width persist 164.It Ar persist 165The 166.Ar persist 167flag forces the kernel to keep the table even when no rules refer to it. 168If the flag is not set, the kernel will automatically remove the table 169when the last rule referring to it is flushed. 170.It Ar const 171The 172.Ar const 173flag prevents the user from altering the contents of the table once it 174has been created. 175Without that flag, 176.Xr pfctl 8 177can be used to add or remove addresses from the table at any time, even 178when running with securelevel = 2. 179.El 180.Pp 181For example, 182.Bd -literal -offset indent 183table <private> const { 10/8, 172.16/12, 192.168/16 } 184table <badhosts> persist 185block on fxp0 from { <private>, <badhosts> } to any 186.Ed 187.Pp 188creates a table called private, to hold RFC 1918 private network 189blocks, and a table called badhosts, which is initially empty. 190A filter rule is set up to block all traffic coming from addresses listed in 191either table. 192The private table cannot have its contents changed and the badhosts table 193will exist even when no active filter rules reference it. 194Addresses may later be added to the badhosts table, so that traffic from 195these hosts can be blocked by using 196.Bd -literal -offset indent 197# pfctl -t badhosts -Tadd 204.92.77.111 198.Ed 199.Pp 200A table can also be initialized with an address list specified in one or more 201external files, using the following syntax: 202.Bd -literal -offset indent 203table <spam> persist file \&"/etc/spammers\&" file \&"/etc/openrelays\&" 204block on fxp0 from <spam> to any 205.Ed 206.Pp 207The files 208.Pa /etc/spammers 209and 210.Pa /etc/openrelays 211list IP addresses, one per line. 212Any lines beginning with a # are treated as comments and ignored. 213In addition to being specified by IP address, hosts may also be 214specified by their hostname. 215When the resolver is called to add a hostname to a table, 216.Em all 217resulting IPv4 and IPv6 addresses are placed into the table. 218IP addresses can also be entered in a table by specifying a valid interface 219name or the 220.Em self 221keyword, in which case all addresses assigned to the interface(s) will be 222added to the table. 223.Sh OPTIONS 224.Xr pf 4 225may be tuned for various situations using the 226.Ar set 227command. 228.Bl -tag -width xxxx 229.It Ar set timeout 230.Pp 231.Bl -tag -width "src.track" -compact 232.It Ar interval 233Interval between purging expired states and fragments. 234.It Ar frag 235Seconds before an unassembled fragment is expired. 236.It Ar src.track 237Length of time to retain a source tracking entry after the last state 238expires. 239.El 240.Pp 241When a packet matches a stateful connection, the seconds to live for the 242connection will be updated to that of the 243.Ar proto.modifier 244which corresponds to the connection state. 245Each packet which matches this state will reset the TTL. 246Tuning these values may improve the performance of the 247firewall at the risk of dropping valid idle connections. 248.Pp 249.Bl -tag -width xxxx -compact 250.It Ar tcp.first 251The state after the first packet. 252.It Ar tcp.opening 253The state before the destination host ever sends a packet. 254.It Ar tcp.established 255The fully established state. 256.It Ar tcp.closing 257The state after the first FIN has been sent. 258.It Ar tcp.finwait 259The state after both FINs have been exchanged and the connection is closed. 260Some hosts (notably web servers on Solaris) send TCP packets even after closing 261the connection. 262Increasing 263.Ar tcp.finwait 264(and possibly 265.Ar tcp.closing ) 266can prevent blocking of such packets. 267.It Ar tcp.closed 268The state after one endpoint sends an RST. 269.El 270.Pp 271ICMP and UDP are handled in a fashion similar to TCP, but with a much more 272limited set of states: 273.Pp 274.Bl -tag -width xxxx -compact 275.It Ar udp.first 276The state after the first packet. 277.It Ar udp.single 278The state if the source host sends more than one packet but the destination 279host has never sent one back. 280.It Ar udp.multiple 281The state if both hosts have sent packets. 282.It Ar icmp.first 283The state after the first packet. 284.It Ar icmp.error 285The state after an ICMP error came back in response to an ICMP packet. 286.El 287.Pp 288Other protocols are handled similarly to UDP: 289.Pp 290.Bl -tag -width xxxx -compact 291.It Ar other.first 292.It Ar other.single 293.It Ar other.multiple 294.El 295.Pp 296Timeout values can be reduced adaptively as the number of state table 297entries grows. 298.Pp 299.Bl -tag -width xxxx -compact 300.It Ar adaptive.start 301When the number of state entries exceeds this value, adaptive scaling 302begins. 303All timeout values are scaled linearly with factor 304(adaptive.end - number of states) / (adaptive.end - adaptive.start). 305.It Ar adaptive.end 306When reaching this number of state entries, all timeout values become 307zero, effectively purging all state entries immediately. 308This value is used to define the scale factor, it should not actually 309be reached (set a lower state limit, see below). 310.El 311.Pp 312These values can be defined both globally and for each rule. 313When used on a per-rule basis, the values relate to the number of 314states created by the rule, otherwise to the total number of 315states. 316.Pp 317For example: 318.Bd -literal -offset indent 319set timeout tcp.first 120 320set timeout tcp.established 86400 321set timeout { adaptive.start 6000, adaptive.end 12000 } 322set limit states 10000 323.Ed 324.Pp 325With 9000 state table entries, the timeout values are scaled to 50% 326(tcp.first 60, tcp.established 43200). 327.Pp 328.It Ar set loginterface 329Enable collection of packet and byte count statistics for the given interface. 330These statistics can be viewed using 331.Bd -literal -offset indent 332# pfctl -s info 333.Ed 334.Pp 335In this example 336.Xr pf 4 337collects statistics on the interface named dc0: 338.Bd -literal -offset indent 339set loginterface dc0 340.Ed 341.Pp 342One can disable the loginterface using: 343.Bd -literal -offset indent 344set loginterface none 345.Ed 346.Pp 347.It Ar set limit 348Sets hard limits on the memory pools used by the packet filter. 349See 350.Xr pool 9 351for an explanation of memory pools. 352.Pp 353For example, 354.Bd -literal -offset indent 355set limit states 20000 356.Ed 357.Pp 358sets the maximum number of entries in the memory pool used by state table 359entries (generated by 360.Ar keep state 361rules) to 20000. 362Using 363.Bd -literal -offset indent 364set limit frags 20000 365.Ed 366.Pp 367sets the maximum number of entries in the memory pool used for fragment 368reassembly (generated by 369.Ar scrub 370rules) to 20000. 371Finally, 372.Bd -literal -offset indent 373set limit src-nodes 2000 374.Ed 375.Pp 376sets the maximum number of entries in the memory pool used for tracking 377source IP addresses (generated by the 378.Ar sticky-address 379and 380.Ar source-track 381options) to 2000. 382.Pp 383These can be combined: 384.Bd -literal -offset indent 385set limit { states 20000, frags 20000, src-nodes 2000 } 386.Ed 387.Pp 388.It Ar set optimization 389Optimize the engine for one of the following network environments: 390.Pp 391.Bl -tag -width xxxx -compact 392.It Ar normal 393A normal network environment. 394Suitable for almost all networks. 395.It Ar high-latency 396A high-latency environment (such as a satellite connection). 397.It Ar satellite 398Alias for 399.Ar high-latency . 400.It Ar aggressive 401Aggressively expire connections. 402This can greatly reduce the memory usage of the firewall at the cost of 403dropping idle connections early. 404.It Ar conservative 405Extremely conservative settings. 406Avoid dropping legitimate connections at the 407expense of greater memory utilization (possibly much greater on a busy 408network) and slightly increased processor utilization. 409.El 410.Pp 411For example: 412.Bd -literal -offset indent 413set optimization aggressive 414.Ed 415.Pp 416.It Ar set block-policy 417The 418.Ar block-policy 419option sets the default behaviour for the packet 420.Ar block 421action: 422.Pp 423.Bl -tag -width xxxxxxxx -compact 424.It Ar drop 425Packet is silently dropped. 426.It Ar return 427A TCP RST is returned for blocked TCP packets, 428an ICMP UNREACHABLE is returned for blocked UDP packets, 429and all other packets are silently dropped. 430.El 431.Pp 432For example: 433.Bd -literal -offset indent 434set block-policy return 435.Ed 436.It Ar set state-policy 437The 438.Ar state-policy 439option sets the default behaviour for states: 440.Pp 441.Bl -tag -width group-bound -compact 442.It Ar if-bound 443States are bound to interface. 444.It Ar group-bound 445States are bound to interface group (i.e. ppp) 446.It Ar floating 447States can match packets on any interfaces (the default). 448.El 449.Pp 450For example: 451.Bd -literal -offset indent 452set state-policy if-bound 453.Ed 454.It Ar set require-order 455By default 456.Xr pfctl 8 457enforces an ordering of the statement types in the ruleset to: 458.Em options , 459.Em normalization , 460.Em queueing , 461.Em translation , 462.Em filtering . 463Setting this option to 464.Ar no 465disables this enforcement. 466There may be non-trivial and non-obvious implications to an out of 467order ruleset. 468Consider carefully before disabling the order enforcement. 469.It Ar set fingerprints 470Load fingerprints of known operating systems from the given filename. 471By default fingerprints of known operating systems are automatically 472loaded from 473.Xr pf.os 5 474in 475.Pa /etc 476but can be overridden via this option. 477Setting this option may leave a small period of time where the fingerprints 478referenced by the currently active ruleset are inconsistent until the new 479ruleset finishes loading. 480.Pp 481For example: 482.Pp 483.Dl set fingerprints \&"/etc/pf.os.devel\&" 484.Pp 485.It Ar set skip on <ifspec> 486List interfaces for which packets should not be filtered. 487Packets passing in or out on such interfaces are passed as if pf was 488disabled, i.e. pf does not process them in any way. 489This can be useful on loopback and other virtual interfaces, when 490packet filtering is not desired and can have unexpected effects. 491For example: 492.Pp 493.Dl set skip on lo0 494.Pp 495.It Ar set debug 496Set the debug 497.Ar level 498to one of the following: 499.Pp 500.Bl -tag -width xxxxxxxxxxxx -compact 501.It Ar none 502Don't generate debug messages. 503.It Ar urgent 504Generate debug messages only for serious errors. 505.It Ar misc 506Generate debug messages for various errors. 507.It Ar loud 508Generate debug messages for common conditions. 509.El 510.El 511.Sh TRAFFIC NORMALIZATION 512Traffic normalization is used to sanitize packet content in such 513a way that there are no ambiguities in packet interpretation on 514the receiving side. 515The normalizer does IP fragment reassembly to prevent attacks 516that confuse intrusion detection systems by sending overlapping 517IP fragments. 518Packet normalization is invoked with the 519.Ar scrub 520directive. 521.Pp 522.Ar scrub 523has the following options: 524.Bl -tag -width xxxx 525.It Ar no-df 526Clears the 527.Ar dont-fragment 528bit from a matching IP packet. 529Some operating systems are known to generate fragmented packets with the 530.Ar dont-fragment 531bit set. 532This is particularly true with NFS. 533.Ar Scrub 534will drop such fragmented 535.Ar dont-fragment 536packets unless 537.Ar no-df 538is specified. 539.Pp 540Unfortunately some operating systems also generate their 541.Ar dont-fragment 542packets with a zero IP identification field. 543Clearing the 544.Ar dont-fragment 545bit on packets with a zero IP ID may cause deleterious results if an 546upstream router later fragments the packet. 547Using the 548.Ar random-id 549modifier (see below) is recommended in combination with the 550.Ar no-df 551modifier to ensure unique IP identifiers. 552.It Ar min-ttl <number> 553Enforces a minimum TTL for matching IP packets. 554.It Ar max-mss <number> 555Enforces a maximum MSS for matching TCP packets. 556.It Ar random-id 557Replaces the IP identification field with random values to compensate 558for predictable values generated by many hosts. 559This option only applies to packets that are not fragmented 560after the optional fragment reassembly. 561.It Ar fragment reassemble 562Using 563.Ar scrub 564rules, fragments can be reassembled by normalization. 565In this case, fragments are buffered until they form a complete 566packet, and only the completed packet is passed on to the filter. 567The advantage is that filter rules have to deal only with complete 568packets, and can ignore fragments. 569The drawback of caching fragments is the additional memory cost. 570But the full reassembly method is the only method that currently works 571with NAT. 572This is the default behavior of a 573.Ar scrub 574rule if no fragmentation modifier is supplied. 575.It Ar fragment crop 576The default fragment reassembly method is expensive, hence the option 577to crop is provided. 578In this case, 579.Xr pf 4 580will track the fragments and cache a small range descriptor. 581Duplicate fragments are dropped and overlaps are cropped. 582Thus data will only occur once on the wire with ambiguities resolving to 583the first occurrence. 584Unlike the 585.Ar fragment reassemble 586modifier, fragments are not buffered, they are passed as soon as they 587are received. 588The 589.Ar fragment crop 590reassembly mechanism does not yet work with NAT. 591.Pp 592.It Ar fragment drop-ovl 593This option is similar to the 594.Ar fragment crop 595modifier except that all overlapping or duplicate fragments will be 596dropped, and all further corresponding fragments will be 597dropped as well. 598.It Ar reassemble tcp 599Statefully normalizes TCP connections. 600.Ar scrub reassemble tcp 601rules may not have the direction (in/out) specified. 602.Ar reassemble tcp 603performs the following normalizations: 604.Pp 605.Bl -tag -width timeout -compact 606.It ttl 607Neither side of the connection is allowed to reduce their IP TTL. 608An attacker may send a packet such that it reaches the firewall, affects 609the firewall state, and expires before reaching the destination host. 610.Ar reassemble tcp 611will raise the TTL of all packets back up to the highest value seen on 612the connection. 613.It timestamp modulation 614Modern TCP stacks will send a timestamp on every TCP packet and echo 615the other endpoint's timestamp back to them. 616Many operating systems will merely start the timestamp at zero when 617first booted, and increment it several times a second. 618The uptime of the host can be deduced by reading the timestamp and multiplying 619by a constant. 620Also observing several different timestamps can be used to count hosts 621behind a NAT device. 622And spoofing TCP packets into a connection requires knowing or guessing 623valid timestamps. 624Timestamps merely need to be monotonically increasing and not derived off a 625guessable base time. 626.Ar reassemble tcp 627will cause 628.Ar scrub 629to modulate the TCP timestamps with a random number. 630.It extended PAWS checks 631There is a problem with TCP on long fat pipes, in that a packet might get 632delayed for longer than it takes the connection to wrap its 32-bit sequence 633space. 634In such an occurrence, the old packet would be indistinguishable from a 635new packet and would be accepted as such. 636The solution to this is called PAWS: Protection Against Wrapped Sequence 637numbers. 638It protects against it by making sure the timestamp on each packet does 639not go backwards. 640.Ar reassemble tcp 641also makes sure the timestamp on the packet does not go forward more 642than the RFC allows. 643By doing this, 644.Xr pf 4 645artificially extends the security of TCP sequence numbers by 10 to 18 646bits when the host uses appropriately randomized timestamps, since a 647blind attacker would have to guess the timestamp as well. 648.El 649.El 650.Pp 651For example, 652.Bd -literal -offset indent 653scrub in on $ext_if all fragment reassemble 654.Ed 655.Pp 656The 657.Ar no 658option prefixed to a scrub rule causes matching packets to remain unscrubbed, 659much in the same way as 660.Ar drop quick 661works in the packet filter (see below). 662This mechanism should be used when it is necessary to exclude specific packets 663from broader scrub rules. 664.Sh QUEUEING 665Packets can be assigned to queues for the purpose of bandwidth 666control. 667At least two declarations are required to configure queues, and later 668any packet filtering rule can reference the defined queues by name. 669During the filtering component of 670.Nm pf.conf , 671the last referenced 672.Ar queue 673name is where any packets from 674.Ar pass 675rules will be queued, while for 676.Ar block 677rules it specifies where any resulting ICMP or TCP RST 678packets should be queued. 679The 680.Ar scheduler 681defines the algorithm used to decide which packets get delayed, dropped, or 682sent out immediately. 683There are three 684.Ar schedulers 685currently supported. 686.Bl -tag -width xxxx 687.It Ar cbq 688Class Based Queueing. 689.Ar Queues 690attached to an interface build a tree, thus each 691.Ar queue 692can have further child 693.Ar queues . 694Each queue can have a 695.Ar priority 696and a 697.Ar bandwidth 698assigned. 699.Ar Priority 700mainly controls the time packets take to get sent out, while 701.Ar bandwidth 702has primarily effects on throughput. 703.Ar cbq 704achieves both partitioning and sharing of link bandwidth 705by hierarchically structured classes. 706Each class has its own 707.Ar queue 708and is assigned its share of 709.Ar bandwidth . 710A child class can borrow bandwidth from its parent class 711as long as excess bandwidth is available 712(see the option 713.Ar borrow , 714below). 715.It Ar priq 716Priority Queueing. 717.Ar Queues 718are flat attached to the interface, thus, 719.Ar queues 720cannot have further child 721.Ar queues . 722Each 723.Ar queue 724has a unique 725.Ar priority 726assigned, ranging from 0 to 15. 727Packets in the 728.Ar queue 729with the highest 730.Ar priority 731are processed first. 732.It Ar hfsc 733Hierarchical Fair Service Curve. 734.Ar Queues 735attached to an interface build a tree, thus each 736.Ar queue 737can have further child 738.Ar queues . 739Each queue can have a 740.Ar priority 741and a 742.Ar bandwidth 743assigned. 744.Ar Priority 745mainly controls the time packets take to get sent out, while 746.Ar bandwidth 747has primarily effects on throughput. 748.Ar hfsc 749supports both link-sharing and guaranteed real-time services. 750It employs a service curve based QoS model, 751and its unique feature is an ability to decouple 752.Ar delay 753and 754.Ar bandwidth 755allocation. 756.El 757.Pp 758The interfaces on which queueing should be activated are declared using 759the 760.Ar altq on 761declaration. 762.Ar altq on 763has the following keywords: 764.Bl -tag -width xxxx 765.It Ar <interface> 766Queueing is enabled on the named interface. 767.It Ar <scheduler> 768Specifies which queueing scheduler to use. 769Currently supported values 770are 771.Ar cbq 772for Class Based Queueing, 773.Ar priq 774for Priority Queueing and 775.Ar hfsc 776for the Hierarchical Fair Service Curve scheduler. 777.It Ar bandwidth <bw> 778The maximum bitrate for all queues on an 779interface may be specified using the 780.Ar bandwidth 781keyword. 782The value can be specified as an absolute value or as a 783percentage of the interface bandwidth. 784When using an absolute value, the suffixes 785.Ar b , 786.Ar Kb , 787.Ar Mb , 788and 789.Ar Gb 790are used to represent bits, kilobits, megabits, and 791gigabits per second, respectively. 792The value must not exceed the interface bandwidth. 793If 794.Ar bandwidth 795is not specified, the interface bandwidth is used. 796.It Ar qlimit <limit> 797The maximum number of packets held in the queue. 798The default is 50. 799.It Ar tbrsize <size> 800Adjusts the size, in bytes, of the token bucket regulator. 801If not specified, heuristics based on the 802interface bandwidth are used to determine the size. 803.It Ar queue <list> 804Defines a list of subqueues to create on an interface. 805.El 806.Pp 807In the following example, the interface dc0 808should queue up to 5 Mbit/s in four second-level queues using 809Class Based Queueing. 810Those four queues will be shown in a later example. 811.Bd -literal -offset indent 812altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh } 813.Ed 814.Pp 815Once interfaces are activated for queueing using the 816.Ar altq 817directive, a sequence of 818.Ar queue 819directives may be defined. 820The name associated with a 821.Ar queue 822must match a queue defined in the 823.Ar altq 824directive (e.g. mail), or, except for the 825.Ar priq 826.Ar scheduler , 827in a parent 828.Ar queue 829declaration. 830The following keywords can be used: 831.Bl -tag -width xxxx 832.It Ar on <interface> 833Specifies the interface the queue operates on. 834If not given, it operates on all matching interfaces. 835.It Ar bandwidth <bw> 836Specifies the maximum bitrate to be processed by the queue. 837This value must not exceed the value of the parent 838.Ar queue 839and can be specified as an absolute value or a percentage of the parent 840queue's bandwidth. 841If not specified, defaults to 100% of the parent queue's bandwidth. 842The 843.Ar priq 844scheduler does not support bandwidth specification. 845.It Ar priority <level> 846Between queues a priority level can be set. 847For 848.Ar cbq 849and 850.Ar hfsc , 851the range is 0 to 7 and for 852.Ar priq , 853the range is 0 to 15. 854The default for all is 1. 855.Ar Priq 856queues with a higher priority are always served first. 857.Ar Cbq 858and 859.Ar Hfsc 860queues with a higher priority are preferred in the case of overload. 861.It Ar qlimit <limit> 862The maximum number of packets held in the queue. 863The default is 50. 864.El 865.Pp 866The 867.Ar scheduler 868can get additional parameters with 869.Ar <scheduler> Ns Li (\& Ar <parameters> No ) . 870Parameters are as follows: 871.Bl -tag -width Fl 872.It Ar default 873Packets not matched by another queue are assigned to this one. 874Exactly one default queue is required. 875.It Ar red 876Enable RED (Random Early Detection) on this queue. 877RED drops packets with a probability proportional to the average 878queue length. 879.It Ar rio 880Enables RIO on this queue. 881RIO is RED with IN/OUT, thus running 882RED two times more than RIO would achieve the same effect. 883RIO is currently not supported in the GENERIC kernel. 884.It Ar ecn 885Enables ECN (Explicit Congestion Notification) on this queue. 886ECN implies RED. 887.El 888.Pp 889The 890.Ar cbq 891.Ar scheduler 892supports an additional option: 893.Bl -tag -width Fl 894.It Ar borrow 895The queue can borrow bandwidth from the parent. 896.El 897.Pp 898The 899.Ar hfsc 900.Ar scheduler 901supports some additional options: 902.Bl -tag -width Fl 903.It Ar realtime <sc> 904The minimum required bandwidth for the queue. 905.It Ar upperlimit <sc> 906The maximum allowed bandwidth for the queue. 907.It Ar linkshare <sc> 908The bandwidth share of a backlogged queue. 909.El 910.Pp 911<sc> is an acronym for 912.Ar service curve . 913.Pp 914The format for service curve specifications is 915.Ar ( m1 , d , m2 ) . 916.Ar m2 917controls the bandwidth assigned to the queue. 918.Ar m1 919and 920.Ar d 921are optional and can be used to control the initial bandwidth assignment. 922For the first 923.Ar d 924milliseconds the queue gets the bandwidth given as 925.Ar m1 , 926afterwards the value given in 927.Ar m2 . 928.Pp 929Furthermore, with 930.Ar cbq 931and 932.Ar hfsc , 933child queues can be specified as in an 934.Ar altq 935declaration, thus building a tree of queues using a part of 936their parent's bandwidth. 937.Pp 938Packets can be assigned to queues based on filter rules by using the 939.Ar queue 940keyword. 941Normally only one 942.Ar queue 943is specified; when a second one is specified it will instead be used for 944packets which have a 945.Em TOS 946of 947.Em lowdelay 948and for TCP ACKs with no data payload. 949.Pp 950To continue the previous example, the examples below would specify the 951four referenced 952queues, plus a few child queues. 953Interactive 954.Xr ssh 1 955sessions get priority over bulk transfers like 956.Xr scp 1 957and 958.Xr sftp 1 . 959The queues may then be referenced by filtering rules (see 960.Sx PACKET FILTERING 961below). 962.Bd -literal 963queue std bandwidth 10% cbq(default) 964queue http bandwidth 60% priority 2 cbq(borrow red) \e 965 { employees, developers } 966queue developers bandwidth 75% cbq(borrow) 967queue employees bandwidth 15% 968queue mail bandwidth 10% priority 0 cbq(borrow ecn) 969queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk } 970queue ssh_interactive bandwidth 50% priority 7 cbq(borrow) 971queue ssh_bulk bandwidth 50% priority 0 cbq(borrow) 972 973block return out on dc0 inet all queue std 974pass out on dc0 inet proto tcp from $developerhosts to any port 80 \e 975 keep state queue developers 976pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e 977 keep state queue employees 978pass out on dc0 inet proto tcp from any to any port 22 \e 979 keep state queue(ssh_bulk, ssh_interactive) 980pass out on dc0 inet proto tcp from any to any port 25 \e 981 keep state queue mail 982.Ed 983.Sh TRANSLATION 984Translation rules modify either the source or destination address of the 985packets associated with a stateful connection. 986A stateful connection is automatically created to track packets matching 987such a rule as long as they are not blocked by the filtering section of 988.Nm pf.conf . 989The translation engine modifies the specified address and/or port in the 990packet, recalculates IP, TCP and UDP checksums as necessary, and passes it to 991the packet filter for evaluation. 992.Pp 993Since translation occurs before filtering the filter 994engine will see packets as they look after any 995addresses and ports have been translated. 996Filter rules will therefore have to filter based on the translated 997address and port number. 998Packets that match a translation rule are only automatically passed if 999the 1000.Ar pass 1001modifier is given, otherwise they are 1002still subject to 1003.Ar block 1004and 1005.Ar pass 1006rules. 1007.Pp 1008The state entry created permits 1009.Xr pf 4 1010to keep track of the original address for traffic associated with that state 1011and correctly direct return traffic for that connection. 1012.Pp 1013Various types of translation are possible with pf: 1014.Bl -tag -width xxxx 1015.It Ar binat 1016A 1017.Ar binat 1018rule specifies a bidirectional mapping between an external IP netblock 1019and an internal IP netblock. 1020.It Ar nat 1021A 1022.Ar nat 1023rule specifies that IP addresses are to be changed as the packet 1024traverses the given interface. 1025This technique allows one or more IP addresses 1026on the translating host to support network traffic for a larger range of 1027machines on an "inside" network. 1028Although in theory any IP address can be used on the inside, it is strongly 1029recommended that one of the address ranges defined by RFC 1918 be used. 1030These netblocks are: 1031.Bd -literal 103210.0.0.0 - 10.255.255.255 (all of net 10, i.e., 10/8) 1033172.16.0.0 - 172.31.255.255 (i.e., 172.16/12) 1034192.168.0.0 - 192.168.255.255 (i.e., 192.168/16) 1035.Ed 1036.It Pa rdr 1037The packet is redirected to another destination and possibly a 1038different port. 1039.Ar rdr 1040rules can optionally specify port ranges instead of single ports. 1041rdr ... port 2000:2999 -> ... port 4000 1042redirects ports 2000 to 2999 (inclusive) to port 4000. 1043rdr ... port 2000:2999 -> ... port 4000:* 1044redirects port 2000 to 4000, 2001 to 4001, ..., 2999 to 4999. 1045.El 1046.Pp 1047In addition to modifying the address, some translation rules may modify 1048source or destination ports for 1049.Xr tcp 4 1050or 1051.Xr udp 4 1052connections; implicitly in the case of 1053.Ar nat 1054rules and explicitly in the case of 1055.Ar rdr 1056rules. 1057Port numbers are never translated with a 1058.Ar binat 1059rule. 1060.Pp 1061For each packet processed by the translator, the translation rules are 1062evaluated in sequential order, from first to last. 1063The first matching rule decides what action is taken. 1064.Pp 1065The 1066.Ar no 1067option prefixed to a translation rule causes packets to remain untranslated, 1068much in the same way as 1069.Ar drop quick 1070works in the packet filter (see below). 1071If no rule matches the packet it is passed to the filter engine unmodified. 1072.Pp 1073Translation rules apply only to packets that pass through 1074the specified interface, and if no interface is specified, 1075translation is applied to packets on all interfaces. 1076For instance, redirecting port 80 on an external interface to an internal 1077web server will only work for connections originating from the outside. 1078Connections to the address of the external interface from local hosts will 1079not be redirected, since such packets do not actually pass through the 1080external interface. 1081Redirections cannot reflect packets back through the interface they arrive 1082on, they can only be redirected to hosts connected to different interfaces 1083or to the firewall itself. 1084.Pp 1085Note that redirecting external incoming connections to the loopback 1086address, as in 1087.Bd -literal -offset indent 1088rdr on ne3 inet proto tcp to port 8025 -> 127.0.0.1 port 25 1089.Ed 1090.Pp 1091will effectively allow an external host to connect to daemons 1092bound solely to the loopback address, circumventing the traditional 1093blocking of such connections on a real interface. 1094Unless this effect is desired, any of the local non-loopback addresses 1095should be used as redirection target instead, which allows external 1096connections only to daemons bound to this address or not bound to 1097any address. 1098.Pp 1099See 1100.Sx TRANSLATION EXAMPLES 1101below. 1102.Sh PACKET FILTERING 1103.Xr pf 4 1104has the ability to 1105.Ar block 1106and 1107.Ar pass 1108packets based on attributes of their layer 3 (see 1109.Xr ip 4 1110and 1111.Xr ip6 4 ) 1112and layer 4 (see 1113.Xr icmp 4 , 1114.Xr icmp6 4 , 1115.Xr tcp 4 , 1116.Xr udp 4 ) 1117headers. 1118In addition, packets may also be 1119assigned to queues for the purpose of bandwidth control. 1120.Pp 1121For each packet processed by the packet filter, the filter rules are 1122evaluated in sequential order, from first to last. 1123The last matching rule decides what action is taken. 1124.Pp 1125The following actions can be used in the filter: 1126.Bl -tag -width xxxx 1127.It Ar block 1128The packet is blocked. 1129There are a number of ways in which a 1130.Ar block 1131rule can behave when blocking a packet. 1132The default behaviour is to 1133.Ar drop 1134packets silently, however this can be overridden or made 1135explicit either globally, by setting the 1136.Ar block-policy 1137option, or on a per-rule basis with one of the following options: 1138.Pp 1139.Bl -tag -width xxxx -compact 1140.It Ar drop 1141The packet is silently dropped. 1142.It Ar return-rst 1143This applies only to 1144.Xr tcp 4 1145packets, and issues a TCP RST which closes the 1146connection. 1147.It Ar return-icmp 1148.It Ar return-icmp6 1149This causes ICMP messages to be returned for packets which match the rule. 1150By default this is an ICMP UNREACHABLE message, however this 1151can be overridden by specifying a message as a code or number. 1152.It Ar return 1153This causes a TCP RST to be returned for 1154.Xr tcp 4 1155packets and an ICMP UNREACHABLE for UDP and other packets. 1156.El 1157.Pp 1158Options returning ICMP packets currently have no effect if 1159.Xr pf 4 1160operates on a 1161.Xr bridge 4 , 1162as the code to support this feature has not yet been implemented. 1163.It Ar pass 1164The packet is passed. 1165.El 1166.Pp 1167If no rule matches the packet, the default action is 1168.Ar pass . 1169.Pp 1170To block everything by default and only pass packets 1171that match explicit rules, one uses 1172.Bd -literal -offset indent 1173block all 1174.Ed 1175.Pp 1176as the first filter rule. 1177.Pp 1178See 1179.Sx FILTER EXAMPLES 1180below. 1181.Sh PARAMETERS 1182The rule parameters specify the packets to which a rule applies. 1183A packet always comes in on, or goes out through, one interface. 1184Most parameters are optional. 1185If a parameter is specified, the rule only applies to packets with 1186matching attributes. 1187Certain parameters can be expressed as lists, in which case 1188.Xr pfctl 8 1189generates all needed rule combinations. 1190.Bl -tag -width xxxx 1191.It Ar in No or Ar out 1192This rule applies to incoming or outgoing packets. 1193If neither 1194.Ar in 1195nor 1196.Ar out 1197are specified, the rule will match packets in both directions. 1198.It Ar log 1199In addition to the action specified, a log message is generated. 1200All packets for that connection are logged, unless the 1201.Ar keep state , 1202.Ar modulate state 1203or 1204.Ar synproxy state 1205options are specified, in which case only the 1206packet that establishes the state is logged. 1207(See 1208.Ar keep state , 1209.Ar modulate state 1210and 1211.Ar synproxy state 1212below). 1213The logged packets are sent to the 1214.Xr pflog 4 1215interface. 1216This interface is monitored by the 1217.Xr pflogd 8 1218logging daemon, which dumps the logged packets to the file 1219.Pa /var/log/pflog 1220in 1221.Xr pcap 3 1222binary format. 1223.It Ar log-all 1224Used with 1225.Ar keep state , 1226.Ar modulate state 1227or 1228.Ar synproxy state 1229rules to force logging of all packets for a connection. 1230As with 1231.Ar log , 1232packets are logged to 1233.Xr pflog 4 . 1234.It Ar quick 1235If a packet matches a rule which has the 1236.Ar quick 1237option set, this rule 1238is considered the last matching rule, and evaluation of subsequent rules 1239is skipped. 1240.It Ar on <interface> 1241This rule applies only to packets coming in on, or going out through, this 1242particular interface. 1243It is also possible to simply give the interface driver name, like ppp or fxp, 1244to make the rule match packets flowing through a group of interfaces. 1245.It Ar <af> 1246This rule applies only to packets of this address family. 1247Supported values are 1248.Ar inet 1249and 1250.Ar inet6 . 1251.It Ar proto <protocol> 1252This rule applies only to packets of this protocol. 1253Common protocols are 1254.Xr icmp 4 , 1255.Xr icmp6 4 , 1256.Xr tcp 4 , 1257and 1258.Xr udp 4 . 1259For a list of all the protocol name to number mappings used by 1260.Xr pfctl 8 , 1261see the file 1262.Em /etc/protocols . 1263.It Xo 1264.Ar from <source> port <source> os <source> 1265.Ar to <dest> port <dest> 1266.Xc 1267This rule applies only to packets with the specified source and destination 1268addresses and ports. 1269.Pp 1270Addresses can be specified in CIDR notation (matching netblocks), as 1271symbolic host names or interface names, or as any of the following keywords: 1272.Pp 1273.Bl -tag -width xxxxxxxxxxxxxx -compact 1274.It Ar any 1275Any address. 1276.It Ar route <label> 1277Any address whose associated route has label 1278.Ar <label> . 1279See 1280.Xr route 4 1281and 1282.Xr route 8 . 1283.It Ar no-route 1284Any address which is not currently routable. 1285.It Ar <table> 1286Any address that matches the given table. 1287.El 1288.Pp 1289Interface names can have modifiers appended: 1290.Pp 1291.Bl -tag -width xxxxxxxxxxxx -compact 1292.It Ar :network 1293Translates to the network(s) attached to the interface. 1294.It Ar :broadcast 1295Translates to the interface's broadcast address(es). 1296.It Ar :peer 1297Translates to the point to point interface's peer address(es). 1298.It Ar :0 1299Do not include interface aliases. 1300.El 1301.Pp 1302Host names may also have the 1303.Ar :0 1304option appended to restrict the name resolution to the first of each 1305v4 and v6 address found. 1306.Pp 1307Host name resolution and interface to address translation are done at 1308ruleset load-time. 1309When the address of an interface (or host name) changes (under DHCP or PPP, 1310for instance), the ruleset must be reloaded for the change to be reflected 1311in the kernel. 1312Surrounding the interface name (and optional modifiers) in parentheses 1313changes this behaviour. 1314When the interface name is surrounded by parentheses, the rule is 1315automatically updated whenever the interface changes its address. 1316The ruleset does not need to be reloaded. 1317This is especially useful with 1318.Ar nat . 1319.Pp 1320Ports can be specified either by number or by name. 1321For example, port 80 can be specified as 1322.Em www . 1323For a list of all port name to number mappings used by 1324.Xr pfctl 8 , 1325see the file 1326.Pa /etc/services . 1327.Pp 1328Ports and ranges of ports are specified by using these operators: 1329.Bd -literal -offset indent 1330= (equal) 1331!= (unequal) 1332< (less than) 1333<= (less than or equal) 1334> (greater than) 1335>= (greater than or equal) 1336: (range including boundaries) 1337>< (range excluding boundaries) 1338<> (except range) 1339.Ed 1340.Pp 1341><, <> and : 1342are binary operators (they take two arguments). 1343For instance: 1344.Bl -tag -width Fl 1345.It Ar port 2000:2004 1346means 1347.Sq all ports >= 2000 and <= 2004 , 1348hence ports 2000, 2001, 2002, 2003 and 2004. 1349.It Ar port 2000 >< 2004 1350means 1351.Sq all ports > 2000 and < 2004 , 1352hence ports 2001, 2002 and 2003. 1353.It Ar port 2000 <> 2004 1354means 1355.Sq all ports < 2000 or > 2004 , 1356hence ports 1-1999 and 2005-65535. 1357.El 1358.Pp 1359The operating system of the source host can be specified in the case of TCP 1360rules with the 1361.Ar OS 1362modifier. 1363See the 1364.Sx OPERATING SYSTEM FINGERPRINTING 1365section for more information. 1366.Pp 1367The host, port and OS specifications are optional, as in the following examples: 1368.Bd -literal -offset indent 1369pass in all 1370pass in from any to any 1371pass in proto tcp from any port <= 1024 to any 1372pass in proto tcp from any to any port 25 1373pass in proto tcp from 10.0.0.0/8 port > 1024 \e 1374 to ! 10.1.2.3 port != ssh 1375pass in proto tcp from any os "OpenBSD" flags S/SA 1376pass in proto tcp from route "DTAG" 1377.Ed 1378.It Ar all 1379This is equivalent to "from any to any". 1380.It Ar group <group> 1381Similar to 1382.Ar user , 1383this rule only applies to packets of sockets owned by the specified group. 1384.It Ar user <user> 1385This rule only applies to packets of sockets owned by the specified user. 1386For outgoing connections initiated from the firewall, this is the user 1387that opened the connection. 1388For incoming connections to the firewall itself, this is the user that 1389listens on the destination port. 1390For forwarded connections, where the firewall is not a connection endpoint, 1391the user and group are 1392.Em unknown . 1393.Pp 1394All packets, both outgoing and incoming, of one connection are associated 1395with the same user and group. 1396Only TCP and UDP packets can be associated with users; for other protocols 1397these parameters are ignored. 1398.Pp 1399User and group refer to the effective (as opposed to the real) IDs, in 1400case the socket is created by a setuid/setgid process. 1401User and group IDs are stored when a socket is created; 1402when a process creates a listening socket as root (for instance, by 1403binding to a privileged port) and subsequently changes to another 1404user ID (to drop privileges), the credentials will remain root. 1405.Pp 1406User and group IDs can be specified as either numbers or names. 1407The syntax is similar to the one for ports. 1408The value 1409.Em unknown 1410matches packets of forwarded connections. 1411.Em unknown 1412can only be used with the operators 1413.Cm = 1414and 1415.Cm != . 1416Other constructs like 1417.Cm user >= unknown 1418are invalid. 1419Forwarded packets with unknown user and group ID match only rules 1420that explicitly compare against 1421.Em unknown 1422with the operators 1423.Cm = 1424or 1425.Cm != . 1426For instance 1427.Cm user >= 0 1428does not match forwarded packets. 1429The following example allows only selected users to open outgoing 1430connections: 1431.Bd -literal -offset indent 1432block out proto { tcp, udp } all 1433pass out proto { tcp, udp } all \e 1434 user { < 1000, dhartmei } keep state 1435.Ed 1436.It Ar flags <a>/<b> | /<b> 1437This rule only applies to TCP packets that have the flags 1438.Ar <a> 1439set out of set 1440.Ar <b> . 1441Flags not specified in 1442.Ar <b> 1443are ignored. 1444The flags are: (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, (E)CE, and C(W)R. 1445.Bl -tag -width Fl 1446.It Ar flags S/S 1447Flag SYN is set. 1448The other flags are ignored. 1449.It Ar flags S/SA 1450Out of SYN and ACK, exactly SYN may be set. 1451SYN, SYN+PSH and SYN+RST match, but SYN+ACK, ACK and ACK+RST do not. 1452This is more restrictive than the previous example. 1453.It Ar flags /SFRA 1454If the first set is not specified, it defaults to none. 1455All of SYN, FIN, RST and ACK must be unset. 1456.El 1457.It Ar icmp-type <type> code <code> 1458.It Ar icmp6-type <type> code <code> 1459This rule only applies to ICMP or ICMPv6 packets with the specified type 1460and code. 1461Text names for ICMP types and codes are listed in 1462.Xr icmp 4 1463and 1464.Xr icmp6 4 . 1465This parameter is only valid for rules that cover protocols ICMP or 1466ICMP6. 1467The protocol and the ICMP type indicator 1468.Po 1469.Ar icmp-type 1470or 1471.Ar icmp6-type 1472.Pc 1473must match. 1474.It Ar allow-opts 1475By default, packets which contain IP options are blocked. 1476When 1477.Ar allow-opts 1478is specified for a 1479.Ar pass 1480rule, packets that pass the filter based on that rule (last matching) 1481do so even if they contain IP options. 1482For packets that match state, the rule that initially created the 1483state is used. 1484The implicit 1485.Ar pass 1486rule that is used when a packet does not match any rules does not 1487allow IP options. 1488.It Ar label <string> 1489Adds a label (name) to the rule, which can be used to identify the rule. 1490For instance, 1491pfctl -s labels 1492shows per-rule statistics for rules that have labels. 1493.Pp 1494The following macros can be used in labels: 1495.Pp 1496.Bl -tag -width $srcaddr -compact -offset indent 1497.It Ar $if 1498The interface. 1499.It Ar $srcaddr 1500The source IP address. 1501.It Ar $dstaddr 1502The destination IP address. 1503.It Ar $srcport 1504The source port specification. 1505.It Ar $dstport 1506The destination port specification. 1507.It Ar $proto 1508The protocol name. 1509.It Ar $nr 1510The rule number. 1511.El 1512.Pp 1513For example: 1514.Bd -literal -offset indent 1515ips = \&"{ 1.2.3.4, 1.2.3.5 }\&" 1516pass in proto tcp from any to $ips \e 1517 port > 1023 label \&"$dstaddr:$dstport\&" 1518.Ed 1519.Pp 1520expands to 1521.Bd -literal -offset indent 1522pass in inet proto tcp from any to 1.2.3.4 \e 1523 port > 1023 label \&"1.2.3.4:>1023\&" 1524pass in inet proto tcp from any to 1.2.3.5 \e 1525 port > 1023 label \&"1.2.3.5:>1023\&" 1526.Ed 1527.Pp 1528The macro expansion for the 1529.Ar label 1530directive occurs only at configuration file parse time, not during runtime. 1531.It Ar queue <queue> | ( <queue> , <queue> ) 1532Packets matching this rule will be assigned to the specified queue. 1533If two queues are given, packets which have a 1534.Em tos 1535of 1536.Em lowdelay 1537and TCP ACKs with no data payload will be assigned to the second one. 1538See 1539.Sx QUEUEING 1540for setup details. 1541.Pp 1542For example: 1543.Bd -literal -offset indent 1544pass in proto tcp to port 25 queue mail 1545pass in proto tcp to port 22 queue(ssh_bulk, ssh_prio) 1546.Ed 1547.It Ar tag <string> 1548Packets matching this rule will be tagged with the 1549specified string. 1550The tag acts as an internal marker that can be used to 1551identify these packets later on. 1552This can be used, for example, to provide trust between 1553interfaces and to determine if packets have been 1554processed by translation rules. 1555Tags are 1556.Qq sticky , 1557meaning that the packet will be tagged even if the rule 1558is not the last matching rule. 1559Further matching rules can replace the tag with a 1560new one but will not remove a previously applied tag. 1561A packet is only ever assigned one tag at a time. 1562.Ar pass 1563rules that use the 1564.Ar tag 1565keyword must also use 1566.Ar keep state , 1567.Ar modulate state 1568or 1569.Ar synproxy state . 1570Packet tagging can be done during 1571.Ar nat , 1572.Ar rdr , 1573or 1574.Ar binat 1575rules in addition to filter rules. 1576Tags take the same macros as labels (see above). 1577.It Ar tagged <string> 1578Used with filter or translation rules to specify that packets must already 1579be tagged with the given tag in order to match the rule. 1580Inverse tag matching can also be done 1581by specifying the 1582.Cm !\& 1583operator before the 1584.Ar tagged 1585keyword. 1586.It Ar probability <number> 1587A probability attribute can be attached to a rule, with a value set between 15880 and 1, bounds not included. 1589In that case, the rule will be honoured using the given probability value 1590only. 1591For example, the following rule will drop 20% of incoming ICMP packets: 1592.Bd -literal -offset indent 1593block in proto icmp probability 20% 1594.Ed 1595.El 1596.Sh ROUTING 1597If a packet matches a rule with a route option set, the packet filter will 1598route the packet according to the type of route option. 1599When such a rule creates state, the route option is also applied to all 1600packets matching the same connection. 1601.Bl -tag -width xxxx 1602.It Ar fastroute 1603The 1604.Ar fastroute 1605option does a normal route lookup to find the next hop for the packet. 1606.It Ar route-to 1607The 1608.Ar route-to 1609option routes the packet to the specified interface with an optional address 1610for the next hop. 1611When a 1612.Ar route-to 1613rule creates state, only packets that pass in the same direction as the 1614filter rule specifies will be routed in this way. 1615Packets passing in the opposite direction (replies) are not affected 1616and are routed normally. 1617.It Ar reply-to 1618The 1619.Ar reply-to 1620option is similar to 1621.Ar route-to , 1622but routes packets that pass in the opposite direction (replies) to the 1623specified interface. 1624Opposite direction is only defined in the context of a state entry, and 1625.Ar reply-to 1626is useful only in rules that create state. 1627It can be used on systems with multiple external connections to 1628route all outgoing packets of a connection through the interface 1629the incoming connection arrived through (symmetric routing enforcement). 1630.It Ar dup-to 1631The 1632.Ar dup-to 1633option creates a duplicate of the packet and routes it like 1634.Ar route-to . 1635The original packet gets routed as it normally would. 1636.El 1637.Sh POOL OPTIONS 1638For 1639.Ar nat 1640and 1641.Ar rdr 1642rules, (as well as for the 1643.Ar route-to , 1644.Ar reply-to 1645and 1646.Ar dup-to 1647rule options) for which there is a single redirection address which has a 1648subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP 1649address), a variety of different methods for assigning this address can be 1650used: 1651.Bl -tag -width xxxx 1652.It Ar bitmask 1653The 1654.Ar bitmask 1655option applies the network portion of the redirection address to the address 1656to be modified (source with 1657.Ar nat , 1658destination with 1659.Ar rdr ) . 1660.It Ar random 1661The 1662.Ar random 1663option selects an address at random within the defined block of addresses. 1664.It Ar source-hash 1665The 1666.Ar source-hash 1667option uses a hash of the source address to determine the redirection address, 1668ensuring that the redirection address is always the same for a given source. 1669An optional key can be specified after this keyword either in hex or as a 1670string; by default 1671.Xr pfctl 8 1672randomly generates a key for source-hash every time the 1673ruleset is reloaded. 1674.It Ar round-robin 1675The 1676.Ar round-robin 1677option loops through the redirection address(es). 1678.Pp 1679When more than one redirection address is specified, 1680.Ar round-robin 1681is the only permitted pool type. 1682.It Ar static-port 1683With 1684.Ar nat 1685rules, the 1686.Ar static-port 1687option prevents 1688.Xr pf 4 1689from modifying the source port on TCP and UDP packets. 1690.El 1691.Pp 1692Additionally, the 1693.Ar sticky-address 1694option can be specified to help ensure that multiple connections from the 1695same source are mapped to the same redirection address. 1696This option can be used with the 1697.Ar random 1698and 1699.Ar round-robin 1700pool options. 1701Note that by default these associations are destroyed as soon as there are 1702no longer states which refer to them; in order to make the mappings last 1703beyond the lifetime of the states, increase the global options with 1704.Ar set timeout source-track 1705See 1706.Sx STATEFUL TRACKING OPTIONS 1707for more ways to control the source tracking. 1708.Sh STATEFUL INSPECTION 1709.Xr pf 4 1710is a stateful packet filter, which means it can track the state of 1711a connection. 1712Instead of passing all traffic to port 25, for instance, it is possible 1713to pass only the initial packet, and then begin to keep state. 1714Subsequent traffic will flow because the filter is aware of the connection. 1715.Pp 1716If a packet matches a 1717.Ar pass ... keep state 1718rule, the filter creates a state for this connection and automatically 1719lets pass all subsequent packets of that connection. 1720.Pp 1721Before any rules are evaluated, the filter checks whether the packet 1722matches any state. 1723If it does, the packet is passed without evaluation of any rules. 1724.Pp 1725States are removed after the connection is closed or has timed out. 1726.Pp 1727This has several advantages. 1728Comparing a packet to a state involves checking its sequence numbers. 1729If the sequence numbers are outside the narrow windows of expected 1730values, the packet is dropped. 1731This prevents spoofing attacks, such as when an attacker sends packets with 1732a fake source address/port but does not know the connection's sequence 1733numbers. 1734.Pp 1735Also, looking up states is usually faster than evaluating rules. 1736If there are 50 rules, all of them are evaluated sequentially in O(n). 1737Even with 50000 states, only 16 comparisons are needed to match a 1738state, since states are stored in a binary search tree that allows 1739searches in O(log2 n). 1740.Pp 1741For instance: 1742.Bd -literal -offset indent 1743block all 1744pass out proto tcp from any to any flags S/SA keep state 1745pass in proto tcp from any to any port 25 flags S/SA keep state 1746.Ed 1747.Pp 1748This ruleset blocks everything by default. 1749Only outgoing connections and incoming connections to port 25 are allowed. 1750The initial packet of each connection has the SYN 1751flag set, will be passed and creates state. 1752All further packets of these connections are passed if they match a state. 1753.Pp 1754By default, packets coming in and out of any interface can match a state, 1755but it is also possible to change that behaviour by assigning states to a 1756single interface or a group of interfaces. 1757.Pp 1758The default policy is specified by the 1759.Ar state-policy 1760global option, but this can be adjusted on a per-rule basis by adding one 1761of the 1762.Ar if-bound , 1763.Ar group-bound 1764or 1765.Ar floating 1766keywords to the 1767.Ar keep state 1768option. 1769For example, if a rule is defined as: 1770.Bd -literal -offset indent 1771pass out on ppp from any to 10.12/16 keep state (group-bound) 1772.Ed 1773.Pp 1774A state created on ppp0 would match packets an all PPP interfaces, 1775but not packets flowing through fxp0 or any other interface. 1776.Pp 1777Keeping rules 1778.Ar floating 1779is the more flexible option when the firewall is in a dynamic routing 1780environment. 1781However, this has some security implications since a state created by one 1782trusted network could allow potentially hostile packets coming in from other 1783interfaces. 1784.Pp 1785Specifying 1786.Ar flags S/SA 1787restricts state creation to the initial SYN 1788packet of the TCP handshake. 1789One can also be less restrictive, and allow state creation from 1790intermediate 1791.Pq non-SYN 1792packets. 1793This will cause 1794.Xr pf 4 1795to synchronize to existing connections, for instance 1796if one flushes the state table. 1797.Pp 1798For UDP, which is stateless by nature, 1799.Ar keep state 1800will create state as well. 1801UDP packets are matched to states using only host addresses and ports. 1802.Pp 1803ICMP messages fall into two categories: ICMP error messages, which always 1804refer to a TCP or UDP packet, are matched against the referred to connection. 1805If one keeps state on a TCP connection, and an ICMP source quench message 1806referring to this TCP connection arrives, it will be matched to the right 1807state and get passed. 1808.Pp 1809For ICMP queries, 1810.Ar keep state 1811creates an ICMP state, and 1812.Xr pf 4 1813knows how to match ICMP replies to states. 1814For example, 1815.Bd -literal -offset indent 1816pass out inet proto icmp all icmp-type echoreq keep state 1817.Ed 1818.Pp 1819allows echo requests (such as those created by 1820.Xr ping 8 ) 1821out, creates state, and matches incoming echo replies correctly to states. 1822.Pp 1823Note: 1824.Ar nat , binat No and Ar rdr 1825rules implicitly create state for connections. 1826.Sh STATE MODULATION 1827Much of the security derived from TCP is attributable to how well the 1828initial sequence numbers (ISNs) are chosen. 1829Some popular stack implementations choose 1830.Em very 1831poor ISNs and thus are normally susceptible to ISN prediction exploits. 1832By applying a 1833.Ar modulate state 1834rule to a TCP connection, 1835.Xr pf 4 1836will create a high quality random sequence number for each connection 1837endpoint. 1838.Pp 1839The 1840.Ar modulate state 1841directive implicitly keeps state on the rule and is 1842only applicable to TCP connections. 1843.Pp 1844For instance: 1845.Bd -literal -offset indent 1846block all 1847pass out proto tcp from any to any modulate state 1848pass in proto tcp from any to any port 25 flags S/SA modulate state 1849.Ed 1850.Pp 1851There are two caveats associated with state modulation: 1852A 1853.Ar modulate state 1854rule can not be applied to a pre-existing but unmodulated connection. 1855Such an application would desynchronize TCP's strict 1856sequencing between the two endpoints. 1857Instead, 1858.Xr pf 4 1859will treat the 1860.Ar modulate state 1861modifier as a 1862.Ar keep state 1863modifier and the pre-existing connection will be inferred without 1864the protection conferred by modulation. 1865.Pp 1866The other caveat affects currently modulated states when the state table 1867is lost (firewall reboot, flushing the state table, etc...). 1868.Xr pf 4 1869will not be able to infer a connection again after the state table flushes 1870the connection's modulator. 1871When the state is lost, the connection may be left dangling until the 1872respective endpoints time out the connection. 1873It is possible on a fast local network for the endpoints to start an ACK 1874storm while trying to resynchronize after the loss of the modulator. 1875Using a 1876.Ar flags S/SA 1877modifier on 1878.Ar modulate state 1879rules between fast networks is suggested to prevent ACK storms. 1880.Sh SYN PROXY 1881By default, 1882.Xr pf 4 1883passes packets that are part of a 1884.Xr tcp 4 1885handshake between the endpoints. 1886The 1887.Ar synproxy state 1888option can be used to cause 1889.Xr pf 4 1890itself to complete the handshake with the active endpoint, perform a handshake 1891with the passive endpoint, and then forward packets between the endpoints. 1892.Pp 1893No packets are sent to the passive endpoint before the active endpoint has 1894completed the handshake, hence so-called SYN floods with spoofed source 1895addresses will not reach the passive endpoint, as the sender can't complete the 1896handshake. 1897.Pp 1898The proxy is transparent to both endpoints, they each see a single 1899connection from/to the other endpoint. 1900.Xr pf 4 1901chooses random initial sequence numbers for both handshakes. 1902Once the handshakes are completed, the sequence number modulators 1903(see previous section) are used to translate further packets of the 1904connection. 1905Hence, 1906.Ar synproxy state 1907includes 1908.Ar modulate state 1909and 1910.Ar keep state . 1911.Pp 1912Rules with 1913.Ar synproxy 1914will not work if 1915.Xr pf 4 1916operates on a 1917.Xr bridge 4 . 1918.Pp 1919Example: 1920.Bd -literal -offset indent 1921pass in proto tcp from any to any port www flags S/SA synproxy state 1922.Ed 1923.Sh STATEFUL TRACKING OPTIONS 1924All three of 1925.Ar keep state , 1926.Ar modulate state 1927and 1928.Ar synproxy state 1929support the following options: 1930.Pp 1931.Bl -tag -width xxxx -compact 1932.It Ar max <number> 1933Limits the number of concurrent states the rule may create. 1934When this limit is reached, further packets matching the rule that would 1935create state are dropped, until existing states time out. 1936.It Ar no-sync 1937Prevent state changes for states created by this rule from appearing on the 1938.Xr pfsync 4 1939interface. 1940.It Ar <timeout> <seconds> 1941Changes the timeout values used for states created by this rule. 1942For a list of all valid timeout names, see 1943.Sx OPTIONS 1944above. 1945.El 1946.Pp 1947Multiple options can be specified, separated by commas: 1948.Bd -literal -offset indent 1949pass in proto tcp from any to any \e 1950 port www flags S/SA keep state \e 1951 (max 100, source-track rule, max-src-nodes 75, \e 1952 max-src-states 3, tcp.established 60, tcp.closing 5) 1953.Ed 1954.Pp 1955When the 1956.Ar source-track 1957keyword is specified, the number of states per source IP is tracked. 1958.Pp 1959.Bl -tag -width xxxx -compact 1960.It Ar source-track rule 1961The maximum number of states created by this rule is limited by the rule's 1962.Ar max-src-nodes 1963and 1964.Ar max-src-state 1965options. 1966Only state entries created by this particular rule count toward the rule's 1967limits. 1968.It Ar source-track global 1969The number of states created by all rules that use this option is limited. 1970Each rule can specify different 1971.Ar max-src-nodes 1972and 1973.Ar max-src-states 1974options, however state entries created by any participating rule count towards 1975each individual rule's limits. 1976.El 1977.Pp 1978The following limits can be set: 1979.Pp 1980.Bl -tag -width xxxx -compact 1981.It Ar max-src-nodes <number> 1982Limits the maximum number of source addresses which can simultaneously 1983have state table entries. 1984.It Ar max-src-states <number> 1985Limits the maximum number of simultaneous state entries that a single 1986source address can create with this rule. 1987.El 1988.Pp 1989For stateful TCP connections, limits on established connections (connections 1990which have completed the TCP 3-way handshake) can also be enforced 1991per source IP. 1992.Pp 1993.Bl -tag -width xxxx -compact 1994.It Ar max-src-conn <number> 1995Limits the maximum number of simultaneous TCP connections which have 1996completed the 3-way handshake that a single host can make. 1997.It Ar max-src-conn-rate <number> / <seconds> 1998Limit the rate of new connections over a time interval. 1999The connection rate is an approximation calculated as a moving average. 2000.El 2001.Pp 2002Because the 3-way handshake ensures that the source address is not being 2003spoofed, more aggressive action can be taken based on these limits. 2004With the 2005.Ar overload <table> 2006state option, source IP addresses which hit either of the limits on 2007established connections will be added to the named table. 2008This table can be used in the ruleset to block further activity from 2009the offending host, redirect it to a tarpit process, or restrict its 2010bandwidth. 2011.Pp 2012The optional 2013.Ar flush 2014keyword kills all states created by the matching rule which originate 2015from the host which exceeds these limits. 2016The 2017.Ar global 2018modifier to the flush command kills all states originating from the 2019offending host, regardless of which rule created the state. 2020.Pp 2021For example, the following rules will protect the webserver against 2022hosts making more than 100 connections in 10 seconds. 2023Any host which connects faster than this rate will have its address added 2024to the <bad_hosts> table and have all states originating from it flushed. 2025Any new packets arriving from this host will be dropped unconditionally 2026by the block rule. 2027.Bd -literal -offset indent 2028block quick from <bad_hosts> 2029pass in on $ext_if proto tcp to $webserver port www flags S/SA keep state \e 2030 (max-src-conn-rate 100/10, overload <bad_hosts> flush global) 2031.Ed 2032.Sh OPERATING SYSTEM FINGERPRINTING 2033Passive OS Fingerprinting is a mechanism to inspect nuances of a TCP 2034connection's initial SYN packet and guess at the host's operating system. 2035Unfortunately these nuances are easily spoofed by an attacker so the 2036fingerprint is not useful in making security decisions. 2037But the fingerprint is typically accurate enough to make policy decisions 2038upon. 2039.Pp 2040The fingerprints may be specified by operating system class, by 2041version, or by subtype/patchlevel. 2042The class of an operating system is typically the vendor or genre 2043and would be OpenBSD for the 2044.Xr pf 4 2045firewall itself. 2046The version of the oldest available OpenBSD release on the main ftp site 2047would be 2.6 and the fingerprint would be written 2048.Pp 2049.Dl \&"OpenBSD 2.6\&" 2050.Pp 2051The subtype of an operating system is typically used to describe the 2052patchlevel if that patch led to changes in the TCP stack behavior. 2053In the case of OpenBSD, the only subtype is for a fingerprint that was 2054normalized by the 2055.Ar no-df 2056scrub option and would be specified as 2057.Pp 2058.Dl \&"OpenBSD 3.3 no-df\&" 2059.Pp 2060Fingerprints for most popular operating systems are provided by 2061.Xr pf.os 5 . 2062Once 2063.Xr pf 4 2064is running, a complete list of known operating system fingerprints may 2065be listed by running: 2066.Pp 2067.Dl # pfctl -so 2068.Pp 2069Filter rules can enforce policy at any level of operating system specification 2070assuming a fingerprint is present. 2071Policy could limit traffic to approved operating systems or even ban traffic 2072from hosts that aren't at the latest service pack. 2073.Pp 2074The 2075.Ar unknown 2076class can also be used as the fingerprint which will match packets for 2077which no operating system fingerprint is known. 2078.Pp 2079Examples: 2080.Bd -literal -offset indent 2081pass out proto tcp from any os OpenBSD keep state 2082block out proto tcp from any os Doors 2083block out proto tcp from any os "Doors PT" 2084block out proto tcp from any os "Doors PT SP3" 2085block out from any os "unknown" 2086pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0" keep state 2087.Ed 2088.Pp 2089Operating system fingerprinting is limited only to the TCP SYN packet. 2090This means that it will not work on other protocols and will not match 2091a currently established connection. 2092.Pp 2093Caveat: operating system fingerprints are occasionally wrong. 2094There are three problems: an attacker can trivially craft his packets to 2095appear as any operating system he chooses; 2096an operating system patch could change the stack behavior and no fingerprints 2097will match it until the database is updated; 2098and multiple operating systems may have the same fingerprint. 2099.Sh BLOCKING SPOOFED TRAFFIC 2100"Spoofing" is the faking of IP addresses, typically for malicious 2101purposes. 2102The 2103.Ar antispoof 2104directive expands to a set of filter rules which will block all 2105traffic with a source IP from the network(s) directly connected 2106to the specified interface(s) from entering the system through 2107any other interface. 2108.Pp 2109For example, the line 2110.Bd -literal -offset indent 2111antispoof for lo0 2112.Ed 2113.Pp 2114expands to 2115.Bd -literal -offset indent 2116block drop in on ! lo0 inet from 127.0.0.1/8 to any 2117block drop in on ! lo0 inet6 from ::1 to any 2118.Ed 2119.Pp 2120For non-loopback interfaces, there are additional rules to block incoming 2121packets with a source IP address identical to the interface's IP(s). 2122For example, assuming the interface wi0 had an IP address of 10.0.0.1 and a 2123netmask of 255.255.255.0, 2124the line 2125.Bd -literal -offset indent 2126antispoof for wi0 inet 2127.Ed 2128.Pp 2129expands to 2130.Bd -literal -offset indent 2131block drop in on ! wi0 inet from 10.0.0.0/24 to any 2132block drop in inet from 10.0.0.1 to any 2133.Ed 2134.Pp 2135Caveat: Rules created by the 2136.Ar antispoof 2137directive interfere with packets sent over loopback interfaces 2138to local addresses. 2139One should pass these explicitly. 2140.Sh FRAGMENT HANDLING 2141The size of IP datagrams (packets) can be significantly larger than the 2142maximum transmission unit (MTU) of the network. 2143In cases when it is necessary or more efficient to send such large packets, 2144the large packet will be fragmented into many smaller packets that will each 2145fit onto the wire. 2146Unfortunately for a firewalling device, only the first logical fragment will 2147contain the necessary header information for the subprotocol that allows 2148.Xr pf 4 2149to filter on things such as TCP ports or to perform NAT. 2150.Pp 2151Besides the use of 2152.Ar scrub 2153rules as described in 2154.Sx TRAFFIC NORMALIZATION 2155above, there are three options for handling fragments in the packet filter. 2156.Pp 2157One alternative is to filter individual fragments with filter rules. 2158If no 2159.Ar scrub 2160rule applies to a fragment, it is passed to the filter. 2161Filter rules with matching IP header parameters decide whether the 2162fragment is passed or blocked, in the same way as complete packets 2163are filtered. 2164Without reassembly, fragments can only be filtered based on IP header 2165fields (source/destination address, protocol), since subprotocol header 2166fields are not available (TCP/UDP port numbers, ICMP code/type). 2167The 2168.Ar fragment 2169option can be used to restrict filter rules to apply only to 2170fragments, but not complete packets. 2171Filter rules without the 2172.Ar fragment 2173option still apply to fragments, if they only specify IP header fields. 2174For instance, the rule 2175.Bd -literal -offset indent 2176pass in proto tcp from any to any port 80 2177.Ed 2178.Pp 2179never applies to a fragment, even if the fragment is part of a TCP 2180packet with destination port 80, because without reassembly this information 2181is not available for each fragment. 2182This also means that fragments cannot create new or match existing 2183state table entries, which makes stateful filtering and address 2184translation (NAT, redirection) for fragments impossible. 2185.Pp 2186It's also possible to reassemble only certain fragments by specifying 2187source or destination addresses or protocols as parameters in 2188.Ar scrub 2189rules. 2190.Pp 2191In most cases, the benefits of reassembly outweigh the additional 2192memory cost, and it's recommended to use 2193.Ar scrub 2194rules to reassemble 2195all fragments via the 2196.Ar fragment reassemble 2197modifier. 2198.Pp 2199The memory allocated for fragment caching can be limited using 2200.Xr pfctl 8 . 2201Once this limit is reached, fragments that would have to be cached 2202are dropped until other entries time out. 2203The timeout value can also be adjusted. 2204.Pp 2205Currently, only IPv4 fragments are supported and IPv6 fragments 2206are blocked unconditionally. 2207.Sh ANCHORS 2208Besides the main ruleset, 2209.Xr pfctl 8 2210can load rulesets into 2211.Ar anchor 2212attachment points. 2213An 2214.Ar anchor 2215is a container that can hold rules, address tables, and other anchors. 2216.Pp 2217An 2218.Ar anchor 2219has a name which specifies the path where 2220.Xr pfctl 8 2221can be used to access the anchor to perform operations on it, such as 2222attaching child anchors to it or loading rules into it. 2223Anchors may be nested, with components separated by 2224.Sq / 2225characters, similar to how file system hierarchies are laid out. 2226The main ruleset is actually the default anchor, so filter and 2227translation rules, for example, may also be contained in any anchor. 2228.Pp 2229An anchor can reference another 2230.Ar anchor 2231attachment point 2232using the following kinds 2233of rules: 2234.Bl -tag -width xxxx 2235.It Ar nat-anchor <name> 2236Evaluates the 2237.Ar nat 2238rules in the specified 2239.Ar anchor . 2240.It Ar rdr-anchor <name> 2241Evaluates the 2242.Ar rdr 2243rules in the specified 2244.Ar anchor . 2245.It Ar binat-anchor <name> 2246Evaluates the 2247.Ar binat 2248rules in the specified 2249.Ar anchor . 2250.It Ar anchor <name> 2251Evaluates the filter rules in the specified 2252.Ar anchor . 2253.It Ar load anchor <name> from <file> 2254Loads the rules from the specified file into the 2255anchor 2256.Ar name . 2257.El 2258.Pp 2259When evaluation of the main ruleset reaches an 2260.Ar anchor 2261rule, 2262.Xr pf 4 2263will proceed to evaluate all rules specified in that anchor. 2264.Pp 2265Matching filter and translation rules in anchors with the 2266.Ar quick 2267option are final and abort the evaluation of the rules in other 2268anchors 2269and the main ruleset. 2270.Pp 2271.Ar anchor 2272rules are evaluated relative to the anchor in which they are contained. 2273For example, all 2274.Ar anchor 2275rules specified in the main ruleset will reference anchor 2276attachment points underneath the main ruleset, and 2277.Ar anchor 2278rules specified in a file loaded from a 2279.Ar load anchor 2280rule will be attached under that anchor point. 2281.Pp 2282Rules may be contained in 2283.Ar anchor 2284attachment points which do not contain any rules when the main ruleset 2285is loaded, and later such anchors can be manipulated through 2286.Xr pfctl 8 2287without reloading the main ruleset or other anchors. 2288For example, 2289.Bd -literal -offset indent 2290ext_if = \&"kue0\&" 2291block on $ext_if all 2292anchor spam 2293pass out on $ext_if all keep state 2294pass in on $ext_if proto tcp from any \e 2295 to $ext_if port smtp keep state 2296.Ed 2297.Pp 2298blocks all packets on the external interface by default, then evaluates 2299all rules in the 2300.Ar anchor 2301named "spam", and finally passes all outgoing connections and 2302incoming connections to port 25. 2303.Bd -literal -offset indent 2304# echo \&"block in quick from 1.2.3.4 to any\&" \&| \e 2305 pfctl -a spam -f - 2306.Ed 2307.Pp 2308This loads a single rule into the 2309.Ar anchor , 2310which blocks all packets from a specific address. 2311.Pp 2312The anchor can also be populated by adding a 2313.Ar load anchor 2314rule after the 2315.Ar anchor 2316rule: 2317.Bd -literal -offset indent 2318anchor spam 2319load anchor spam from "/etc/pf-spam.conf" 2320.Ed 2321.Pp 2322When 2323.Xr pfctl 8 2324loads 2325.Nm pf.conf , 2326it will also load all the rules from the file 2327.Pa /etc/pf-spam.conf 2328into the anchor. 2329.Pp 2330Optionally, 2331.Ar anchor 2332rules can specify the parameter's 2333direction, interface, address family, protocol and source/destination 2334address/port 2335using the same syntax as filter rules. 2336When parameters are used, the 2337.Ar anchor 2338rule is only evaluated for matching packets. 2339This allows conditional evaluation of anchors, like: 2340.Bd -literal -offset indent 2341block on $ext_if all 2342anchor spam proto tcp from any to any port smtp 2343pass out on $ext_if all keep state 2344pass in on $ext_if proto tcp from any to $ext_if port smtp keep state 2345.Ed 2346.Pp 2347The rules inside 2348.Ar anchor 2349spam are only evaluated for 2350.Ar tcp 2351packets with destination port 25. 2352Hence, 2353.Bd -literal -offset indent 2354# echo \&"block in quick from 1.2.3.4 to any" \&| \e 2355 pfctl -a spam -f - 2356.Ed 2357.Pp 2358will only block connections from 1.2.3.4 to port 25. 2359.Pp 2360Anchors may end with the asterisk 2361.Pq Sq * 2362character, which signifies that all anchors attached at that point 2363should be evaluated in the alphabetical ordering of their anchor name. 2364For example, 2365.Bd -literal -offset indent 2366anchor "spam/*" 2367.Ed 2368.Pp 2369will evaluate each rule in each anchor attached to the 2370.Li spam 2371anchor. 2372Note that it will only evaluate anchors that are directly attached to the 2373.Li spam 2374anchor, and will not descend to evaluate anchors recursively. 2375.Pp 2376Since anchors are evaluated relative to the anchor in which they are 2377contained, there is a mechanism for accessing the parent and ancestor 2378anchors of a given anchor. 2379Similar to file system path name resolution, if the sequence 2380.Dq .. 2381appears as an anchor path component, the parent anchor of the current 2382anchor in the path evaluation at that point will become the new current 2383anchor. 2384As an example, consider the following: 2385.Bd -literal -offset indent 2386# echo ' anchor "spam/allowed" ' | pfctl -f - 2387# echo -e ' anchor "../banned" \en pass' | \e 2388 pfctl -a spam/allowed -f - 2389.Ed 2390.Pp 2391Evaluation of the main ruleset will lead into the 2392.Li spam/allowed 2393anchor, which will evaluate the rules in the 2394.Li spam/banned 2395anchor, if any, before finally evaluating the 2396.Ar pass 2397rule. 2398.Pp 2399Since the parser specification for anchor names is a string, any 2400reference to an anchor name containing solidus 2401.Pq Sq / 2402characters will require double quote 2403.Pq Sq \&" 2404characters around the anchor name. 2405.Sh TRANSLATION EXAMPLES 2406This example maps incoming requests on port 80 to port 8080, on 2407which a daemon is running (because, for example, it is not run as root, 2408and therefore lacks permission to bind to port 80). 2409.Bd -literal 2410# use a macro for the interface name, so it can be changed easily 2411ext_if = \&"ne3\&" 2412 2413# map daemon on 8080 to appear to be on 80 2414rdr on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 port 8080 2415.Ed 2416.Pp 2417If the 2418.Ar pass 2419modifier is given, packets matching the translation rule are passed without 2420inspecting the filter rules: 2421.Bd -literal 2422rdr pass on $ext_if proto tcp from any to any port 80 -> 127.0.0.1 \e 2423 port 8080 2424.Ed 2425.Pp 2426In the example below, vlan12 is configured as 192.168.168.1; 2427the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111 2428when they are going out any interface except vlan12. 2429This has the net effect of making traffic from the 192.168.168.0/24 2430network appear as though it is the Internet routable address 2431204.92.77.111 to nodes behind any interface on the router except 2432for the nodes on vlan12. 2433(Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.) 2434.Bd -literal 2435nat on ! vlan12 from 192.168.168.0/24 to any -> 204.92.77.111 2436.Ed 2437.Pp 2438In the example below, the machine sits between a fake internal 144.19.74.* 2439network, and a routable external IP of 204.92.77.100. 2440The 2441.Ar no nat 2442rule excludes protocol AH from being translated. 2443.Bd -literal 2444# NO NAT 2445no nat on $ext_if proto ah from 144.19.74.0/24 to any 2446nat on $ext_if from 144.19.74.0/24 to any -> 204.92.77.100 2447.Ed 2448.Pp 2449In the example below, packets bound for one specific server, as well as those 2450generated by the sysadmins are not proxied; all other connections are. 2451.Bd -literal 2452# NO RDR 2453no rdr on $int_if proto { tcp, udp } from any to $server port 80 2454no rdr on $int_if proto { tcp, udp } from $sysadmins to any port 80 2455rdr on $int_if proto { tcp, udp } from any to any port 80 -> 127.0.0.1 \e 2456 port 80 2457.Ed 2458.Pp 2459This longer example uses both a NAT and a redirection. 2460The external interface has the address 157.161.48.183. 2461On the internal interface, we are running 2462.Xr ftp-proxy 8 , 2463listening for outbound ftp sessions captured to port 8021. 2464.Bd -literal 2465# NAT 2466# Translate outgoing packets' source addresses (any protocol). 2467# In this case, any address but the gateway's external address is mapped. 2468nat on $ext_if inet from ! ($ext_if) to any -> ($ext_if) 2469 2470# NAT PROXYING 2471# Map outgoing packets' source port to an assigned proxy port instead of 2472# an arbitrary port. 2473# In this case, proxy outgoing isakmp with port 500 on the gateway. 2474nat on $ext_if inet proto udp from any port = isakmp to any -> ($ext_if) \e 2475 port 500 2476 2477# BINAT 2478# Translate outgoing packets' source address (any protocol). 2479# Translate incoming packets' destination address to an internal machine 2480# (bidirectional). 2481binat on $ext_if from 10.1.2.150 to any -> $ext_if 2482 2483# RDR 2484# Translate incoming packets' destination addresses. 2485# As an example, redirect a TCP and UDP port to an internal machine. 2486rdr on $ext_if inet proto tcp from any to ($ext_if) port 8080 \e 2487 -> 10.1.2.151 port 22 2488rdr on $ext_if inet proto udp from any to ($ext_if) port 8080 \e 2489 -> 10.1.2.151 port 53 2490 2491# RDR 2492# Translate outgoing ftp control connections to send them to localhost 2493# for proxying with ftp-proxy(8) running on port 8021. 2494rdr on $int_if proto tcp from any to any port 21 -> 127.0.0.1 port 8021 2495.Ed 2496.Pp 2497In this example, a NAT gateway is set up to translate internal addresses 2498using a pool of public addresses (192.0.2.16/28) and to redirect 2499incoming web server connections to a group of web servers on the internal 2500network. 2501.Bd -literal 2502# NAT LOAD BALANCE 2503# Translate outgoing packets' source addresses using an address pool. 2504# A given source address is always translated to the same pool address by 2505# using the source-hash keyword. 2506nat on $ext_if inet from any to any -> 192.0.2.16/28 source-hash 2507 2508# RDR ROUND ROBIN 2509# Translate incoming web server connections to a group of web servers on 2510# the internal network. 2511rdr on $ext_if proto tcp from any to any port 80 \e 2512 -> { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin 2513.Ed 2514.Sh FILTER EXAMPLES 2515.Bd -literal 2516# The external interface is kue0 2517# (157.161.48.183, the only routable address) 2518# and the private network is 10.0.0.0/8, for which we are doing NAT. 2519 2520# use a macro for the interface name, so it can be changed easily 2521ext_if = \&"kue0\&" 2522 2523# normalize all incoming traffic 2524scrub in on $ext_if all fragment reassemble 2525 2526# block and log everything by default 2527block return log on $ext_if all 2528 2529# block anything coming from source we have no back routes for 2530block in from no-route to any 2531 2532# block and log outgoing packets that do not have our address as source, 2533# they are either spoofed or something is misconfigured (NAT disabled, 2534# for instance), we want to be nice and do not send out garbage. 2535block out log quick on $ext_if from ! 157.161.48.183 to any 2536 2537# silently drop broadcasts (cable modem noise) 2538block in quick on $ext_if from any to 255.255.255.255 2539 2540# block and log incoming packets from reserved address space and invalid 2541# addresses, they are either spoofed or misconfigured, we cannot reply to 2542# them anyway (hence, no return-rst). 2543block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e 2544 192.168.0.0/16, 255.255.255.255/32 } to any 2545 2546# ICMP 2547 2548# pass out/in certain ICMP queries and keep state (ping) 2549# state matching is done on host addresses and ICMP id (not type/code), 2550# so replies (like 0/0 for 8/0) will match queries 2551# ICMP error messages (which always refer to a TCP/UDP packet) are 2552# handled by the TCP/UDP states 2553pass on $ext_if inet proto icmp all icmp-type 8 code 0 keep state 2554 2555# UDP 2556 2557# pass out all UDP connections and keep state 2558pass out on $ext_if proto udp all keep state 2559 2560# pass in certain UDP connections and keep state (DNS) 2561pass in on $ext_if proto udp from any to any port domain keep state 2562 2563# TCP 2564 2565# pass out all TCP connections and modulate state 2566pass out on $ext_if proto tcp all modulate state 2567 2568# pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT) 2569pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e 2570 auth } flags S/SA keep state 2571 2572# pass in data mode connections for ftp-proxy running on this host. 2573# (see ftp-proxy(8) for details) 2574pass in on $ext_if proto tcp from any to 157.161.48.183 port >= 49152 \e 2575 flags S/SA keep state 2576 2577# Do not allow Windows 9x SMTP connections since they are typically 2578# a viral worm. Alternately we could limit these OSes to 1 connection each. 2579block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e 2580 to any port smtp 2581 2582# Packet Tagging 2583 2584# three interfaces: $int_if, $ext_if, and $wifi_if (wireless). NAT is 2585# being done on $ext_if for all outgoing packets. tag packets in on 2586# $int_if and pass those tagged packets out on $ext_if. all other 2587# outgoing packets (i.e., packets from the wireless network) are only 2588# permitted to access port 80. 2589 2590pass in on $int_if from any to any tag INTNET keep state 2591pass in on $wifi_if from any to any keep state 2592 2593block out on $ext_if from any to any 2594pass out quick on $ext_if tagged INTNET keep state 2595pass out on $ext_if proto tcp from any to any port 80 keep state 2596 2597# tag incoming packets as they are redirected to spamd(8). use the tag 2598# to pass those packets through the packet filter. 2599 2600rdr on $ext_if inet proto tcp from <spammers> to port smtp \e 2601 tag SPAMD -> 127.0.0.1 port spamd 2602 2603block in on $ext_if 2604pass in on $ext_if inet proto tcp tagged SPAMD keep state 2605.Ed 2606.Sh GRAMMAR 2607Syntax for 2608.Nm 2609in BNF: 2610.Bd -literal 2611line = ( option | pf-rule | nat-rule | binat-rule | rdr-rule | 2612 antispoof-rule | altq-rule | queue-rule | anchor-rule | 2613 trans-anchors | load-anchors | table-rule ) 2614 2615option = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] | 2616 [ "optimization" [ "default" | "normal" | 2617 "high-latency" | "satellite" | 2618 "aggressive" | "conservative" ] ] 2619 [ "limit" ( limit-item | "{" limit-list "}" ) ] | 2620 [ "loginterface" ( interface-name | "none" ) ] | 2621 [ "block-policy" ( "drop" | "return" ) ] | 2622 [ "state-policy" ( "if-bound" | "group-bound" | 2623 "floating" ) ] 2624 [ "require-order" ( "yes" | "no" ) ] 2625 [ "fingerprints" filename ] | 2626 [ "debug" ( "none" | "urgent" | "misc" | "loud" ) ] ) 2627 2628pf-rule = action [ ( "in" | "out" ) ] 2629 [ "log" | "log-all" ] [ "quick" ] 2630 [ "on" ifspec ] [ route ] [ af ] [ protospec ] 2631 hosts [ filteropt-list ] 2632 2633filteropt-list = filteropt-list filteropt | filteropt 2634filteropt = user | group | flags | icmp-type | icmp6-type | tos | 2635 ( "keep" | "modulate" | "synproxy" ) "state" 2636 [ "(" state-opts ")" ] | 2637 "fragment" | "no-df" | "min-ttl" number | 2638 "max-mss" number | "random-id" | "reassemble tcp" | 2639 fragmentation | "allow-opts" | 2640 "label" string | "tag" string | [ ! ] "tagged" string 2641 "queue" ( string | "(" string [ [ "," ] string ] ")" ) | 2642 "probability" number"%" 2643 2644nat-rule = [ "no" ] "nat" [ "pass" ] [ "on" ifspec ] [ af ] 2645 [ protospec ] hosts [ "tag" string ] [ "tagged" string ] 2646 [ "->" ( redirhost | "{" redirhost-list "}" ) 2647 [ portspec ] [ pooltype ] [ "static-port" ] ] 2648 2649binat-rule = [ "no" ] "binat" [ "pass" ] [ "on" interface-name ] 2650 [ af ] [ "proto" ( proto-name | proto-number ) ] 2651 "from" address [ "/" mask-bits ] "to" ipspec 2652 [ "tag" string ] [ "tagged" string ] 2653 [ "->" address [ "/" mask-bits ] ] 2654 2655rdr-rule = [ "no" ] "rdr" [ "pass" ] [ "on" ifspec ] [ af ] 2656 [ protospec ] hosts [ "tag" string ] [ "tagged" string ] 2657 [ "->" ( redirhost | "{" redirhost-list "}" ) 2658 [ portspec ] [ pooltype ] ] 2659 2660antispoof-rule = "antispoof" [ "log" ] [ "quick" ] 2661 "for" ( interface-name | "{" interface-list "}" ) 2662 [ af ] [ "label" string ] 2663 2664table-rule = "table" "<" string ">" [ tableopts-list ] 2665tableopts-list = tableopts-list tableopts | tableopts 2666tableopts = "persist" | "const" | "file" string | 2667 "{" [ tableaddr-list ] "}" 2668tableaddr-list = tableaddr-list [ "," ] tableaddr-spec | tableaddr-spec 2669tableaddr-spec = [ "!" ] tableaddr [ "/" mask-bits ] 2670tableaddr = hostname | ipv4-dotted-quad | ipv6-coloned-hex | 2671 interface-name | "self" 2672 2673altq-rule = "altq on" interface-name queueopts-list 2674 "queue" subqueue 2675queue-rule = "queue" string [ "on" interface-name ] queueopts-list 2676 subqueue 2677 2678anchor-rule = "anchor" string [ ( "in" | "out" ) ] [ "on" ifspec ] 2679 [ af ] [ "proto" ] [ protospec ] [ hosts ] 2680 2681trans-anchors = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string 2682 [ "on" ifspec ] [ af ] [ "proto" ] [ protospec ] [ hosts ] 2683 2684load-anchor = "load anchor" string "from" filename 2685 2686queueopts-list = queueopts-list queueopts | queueopts 2687queueopts = [ "bandwidth" bandwidth-spec ] | 2688 [ "qlimit" number ] | [ "tbrsize" number ] | 2689 [ "priority" number ] | [ schedulers ] 2690schedulers = ( cbq-def | priq-def | hfsc-def ) 2691bandwidth-spec = "number" ( "b" | "Kb" | "Mb" | "Gb" | "%" ) 2692 2693action = "pass" | "block" [ return ] | [ "no" ] "scrub" 2694return = "drop" | "return" | "return-rst" [ "( ttl" number ")" ] | 2695 "return-icmp" [ "(" icmpcode ["," icmp6code ] ")" ] | 2696 "return-icmp6" [ "(" icmp6code ")" ] 2697icmpcode = ( icmp-code-name | icmp-code-number ) 2698icmp6code = ( icmp6-code-name | icmp6-code-number ) 2699 2700ifspec = ( [ "!" ] interface-name ) | "{" interface-list "}" 2701interface-list = [ "!" ] interface-name [ [ "," ] interface-list ] 2702route = "fastroute" | 2703 ( "route-to" | "reply-to" | "dup-to" ) 2704 ( routehost | "{" routehost-list "}" ) 2705 [ pooltype ] 2706af = "inet" | "inet6" 2707 2708protospec = "proto" ( proto-name | proto-number | 2709 "{" proto-list "}" ) 2710proto-list = ( proto-name | proto-number ) [ [ "," ] proto-list ] 2711 2712hosts = "all" | 2713 "from" ( "any" | "no-route" | "self" | host | 2714 "{" host-list "}" | "route" string ) [ port ] [ os ] 2715 "to" ( "any" | "no-route" | "self" | host | 2716 "{" host-list "}" | "route" string ) [ port ] 2717 2718ipspec = "any" | host | "{" host-list "}" 2719host = [ "!" ] ( address [ "/" mask-bits ] | "<" string ">" ) 2720redirhost = address [ "/" mask-bits ] 2721routehost = ( interface-name [ address [ "/" mask-bits ] ] ) 2722address = ( interface-name | "(" interface-name ")" | hostname | 2723 ipv4-dotted-quad | ipv6-coloned-hex ) 2724host-list = host [ [ "," ] host-list ] 2725redirhost-list = redirhost [ [ "," ] redirhost-list ] 2726routehost-list = routehost [ [ "," ] routehost-list ] 2727 2728port = "port" ( unary-op | binary-op | "{" op-list "}" ) 2729portspec = "port" ( number | name ) [ ":" ( "*" | number | name ) ] 2730os = "os" ( os-name | "{" os-list "}" ) 2731user = "user" ( unary-op | binary-op | "{" op-list "}" ) 2732group = "group" ( unary-op | binary-op | "{" op-list "}" ) 2733 2734unary-op = [ "=" | "!=" | "<" | "<=" | ">" | ">=" ] 2735 ( name | number ) 2736binary-op = number ( "<>" | "><" | ":" ) number 2737op-list = ( unary-op | binary-op ) [ [ "," ] op-list ] 2738 2739os-name = operating-system-name 2740os-list = os-name [ [ "," ] os-list ] 2741 2742flags = "flags" [ flag-set ] "/" flag-set 2743flag-set = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ] 2744 [ "W" ] 2745 2746icmp-type = "icmp-type" ( icmp-type-code | "{" icmp-list "}" ) 2747icmp6-type = "icmp6-type" ( icmp-type-code | "{" icmp-list "}" ) 2748icmp-type-code = ( icmp-type-name | icmp-type-number ) 2749 [ "code" ( icmp-code-name | icmp-code-number ) ] 2750icmp-list = icmp-type-code [ [ "," ] icmp-list ] 2751 2752tos = "tos" ( "lowdelay" | "throughput" | "reliability" | 2753 [ "0x" ] number ) 2754 2755state-opts = state-opt [ [ "," ] state-opts ] 2756state-opt = ( "max" number | "no-sync" | timeout | 2757 "source-track" [ ( "rule" | "global" ) ] | 2758 "max-src-nodes" number | "max-src-states" number | 2759 "max-src-conn" number | 2760 "max-src-conn-rate" number "/" number | 2761 "overload" "<" string ">" [ "flush" ] | 2762 "if-bound" | "group-bound" | "floating" ) 2763 2764fragmentation = [ "fragment reassemble" | "fragment crop" | 2765 "fragment drop-ovl" ] 2766 2767timeout-list = timeout [ [ "," ] timeout-list ] 2768timeout = ( "tcp.first" | "tcp.opening" | "tcp.established" | 2769 "tcp.closing" | "tcp.finwait" | "tcp.closed" | 2770 "udp.first" | "udp.single" | "udp.multiple" | 2771 "icmp.first" | "icmp.error" | 2772 "other.first" | "other.single" | "other.multiple" | 2773 "frag" | "interval" | "src.track" | 2774 "adaptive.start" | "adaptive.end" ) number 2775 2776limit-list = limit-item [ [ "," ] limit-list ] 2777limit-item = ( "states" | "frags" | "src-nodes" ) number 2778 2779pooltype = ( "bitmask" | "random" | 2780 "source-hash" [ ( hex-key | string-key ) ] | 2781 "round-robin" ) [ sticky-address ] 2782 2783subqueue = string | "{" queue-list "}" 2784queue-list = string [ [ "," ] string ] 2785cbq-def = "cbq" [ "(" cbq-opt [ [ "," ] cbq-opt ] ")" ] 2786priq-def = "priq" [ "(" priq-opt [ [ "," ] priq-opt ] ")" ] 2787hfsc-def = "hfsc" [ "(" hfsc-opt [ [ "," ] hfsc-opt ] ")" ] 2788cbq-opt = ( "default" | "borrow" | "red" | "ecn" | "rio" ) 2789priq-opt = ( "default" | "red" | "ecn" | "rio" ) 2790hfsc-opt = ( "default" | "red" | "ecn" | "rio" | 2791 linkshare-sc | realtime-sc | upperlimit-sc ) 2792linkshare-sc = "linkshare" sc-spec 2793realtime-sc = "realtime" sc-spec 2794upperlimit-sc = "upperlimit" sc-spec 2795sc-spec = ( bandwidth-spec | 2796 "(" bandwidth-spec number bandwidth-spec ")" ) 2797.Ed 2798.Sh FILES 2799.Bl -tag -width "/etc/protocols" -compact 2800.It Pa /etc/hosts 2801Host name database. 2802.It Pa /etc/pf.conf 2803Default location of the ruleset file. 2804.It Pa /etc/pf.os 2805Default location of OS fingerprints. 2806.It Pa /etc/protocols 2807Protocol name database. 2808.It Pa /etc/services 2809Service name database. 2810.It Pa /usr/share/examples/pf 2811Example rulesets. 2812.El 2813.Sh SEE ALSO 2814.Xr icmp 4 , 2815.Xr icmp6 4 , 2816.Xr ip 4 , 2817.Xr ip6 4 , 2818.Xr pf 4 , 2819.Xr pfsync 4 , 2820.Xr route 4 , 2821.Xr tcp 4 , 2822.Xr udp 4 , 2823.Xr hosts 5 , 2824.Xr pf.os 5 , 2825.Xr protocols 5 , 2826.Xr services 5 , 2827.Xr ftp-proxy 8 , 2828.Xr pfctl 8 , 2829.Xr pflogd 8 , 2830.Xr route 8 2831.Sh HISTORY 2832The 2833.Nm 2834file format first appeared in 2835.Ox 3.0 . 2836