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