diff options
Diffstat (limited to 'contrib/pf/man/pf.conf.5')
-rw-r--r-- | contrib/pf/man/pf.conf.5 | 2486 |
1 files changed, 2486 insertions, 0 deletions
diff --git a/contrib/pf/man/pf.conf.5 b/contrib/pf/man/pf.conf.5 new file mode 100644 index 0000000..9881318 --- /dev/null +++ b/contrib/pf/man/pf.conf.5 @@ -0,0 +1,2486 @@ +.\" $OpenBSD: pf.conf.5,v 1.271 2003/09/02 18:37:08 jmc Exp $ +.\" +.\" Copyright (c) 2002, Daniel Hartmeier +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" +.\" - Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" - Redistributions in binary form must reproduce the above +.\" copyright notice, this list of conditions and the following +.\" disclaimer in the documentation and/or other materials provided +.\" with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS +.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE +.\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN +.\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd November 19, 2002 +.Dt PF.CONF 5 +.Os +.Sh NAME +.Nm pf.conf +.Nd packet filter configuration file +.Sh DESCRIPTION +The +.Xr pf 4 +packet filter modifies, drops or passes packets according to rules or +definitions specified in +.Nm pf.conf . +.Sh STATEMENT ORDER +There are seven types of statements in +.Nm pf.conf : +.Bl -tag -width xxxx +.It Cm Macros +User-defined variables may be defined and used later, simplifying +the configuration file. +Macros must be defined before they are referenced in +.Nm pf.conf . +.It Cm Tables +Tables provide a mechanism for increasing the performance and flexibility of +rules with large numbers of source or destination addresses. +.It Cm Options +Options tune the behaviour of the packet filtering engine. +.It Cm Traffic Normalization Li (e.g. Em scrub ) +Traffic normalization protects internal machines against inconsistencies +in Internet protocols and implementations. +.It Cm Queueing +Queueing provides rule-based bandwidth control. +.It Cm Translation Li (Various forms of NAT) +Translation rules specify how addresses are to be mapped or redirected to +other addresses. +.It Cm Packet Filtering +Stateful and stateless packet filtering provides rule-based blocking or +passing of packets. +.El +.Pp +With the exception of +.Cm macros +and +.Cm tables , +the types of statements should be grouped and appear in +.Nm pf.conf +in the order shown above, as this matches the operation of the underlying +packet filtering engine. +By default +.Xr pfctl 8 +enforces this order (see +.Ar set require-order +below). +.Sh MACROS +Much like +.Xr cpp 1 +or +.Xr m4 1 , +macros can be defined that will later be expanded in context. +Macro names must start with a letter, and may contain letters, digits +and underscores. +Macro names may not be reserved words (for example +.Ar pass , +.Ar in , +.Ar out ) . +Macros are not expanded inside quotes. +.Pp +For example, +.Bd -literal -offset indent +ext_if = \&"kue0\&" +all_ifs = \&"{\&" $ext_if lo0 \&"}\&" +pass out on $ext_if from any to any keep state +pass in on $ext_if proto tcp from any to any port 25 keep state +.Ed +.Sh TABLES +Tables are named structures which can hold a collection of addresses and +networks. +Lookups against tables in +.Xr pf 4 +are relatively fast, making a single rule with tables much more efficient, +in terms of +processor usage and memory consumption, than a large number of rules which +differ only in IP address (either created explicitly or automatically by rule +expansion). +.Pp +Tables can be used as the source or destination of filter rules, +.Ar scrub +rules +or +translation rules such as +.Ar nat +or +.Ar rdr +(see below for details on the various rule types). +Tables can also be used for the redirect address of +.Ar nat +and +.Ar rdr +rules and in the routing options of filter rules, but only for +.Ar round-robin +pools. +.Pp +Tables can be defined with any of the following +.Xr pfctl 8 +mechanisms. +As with macros, reserved words may not be used as table names. +.Bl -tag -width "manually" +.It Ar manually +Persistent tables can be manually created with the +.Ar add +or +.Ar replace +option of +.Xr pfctl 8 , +before or after the ruleset has been loaded. +.It Pa pf.conf +Table definitions can be placed directly in this file, and loaded at the +same time as other rules are loaded, atomically. +Table definitions inside +.Nm pf.conf +use the +.Ar table +statement, and are especially useful to define non-persistent tables. +The contents of a pre-existing table defined without a list of addresses +to initialize it is not altered when +.Nm pf.conf +is loaded. +A table initialized with the empty list, +.Li { } , +will be cleared on load. +.El +.Pp +Tables may be defined with the following two attributes: +.Bl -tag -width persist +.It Ar persist +The +.Ar persist +flag forces the kernel to keep the table even when no rules refer to it. +If the flag is not set, the kernel will automatically remove the table +when the last rule referring to it is flushed. +.It Ar const +The +.Ar const +flag prevents the user from altering the contents of the table once it +has been created. +Without that flag, +.Xr pfctl 8 +can be used to add or remove addresses from the table at any time, even +when running with +.Xr securelevel 7 += 2. +.El +.Pp +For example, +.Bd -literal -offset indent +table <private> const { 10/8, 172.16/12, 192.168/16 } +table <badhosts> persist +block on fxp0 from { <private>, <badhosts> } to any +.Ed +.Pp +creates a table called private, to hold RFC 1918 private network +blocks, and a table called badhosts, which is initially empty. +A filter rule is set up to block all traffic coming from addresses listed in +either table. +The private table cannot have its contents changed and the badhosts table +will exist even when no active filter rules reference it. +Addresses may later be added to the badhosts table, so that traffic from +these hosts can be blocked by using +.Bd -literal -offset indent +# pfctl -t badhosts -Tadd 204.92.77.111 +.Ed +.Pp +A table can also be initialized with an address list specified in one or more +external files, using the following syntax: +.Bd -literal -offset indent +table <spam> persist file \&"/etc/spammers\&" file \&"/etc/openrelays\&" +block on fxp0 from <spam> to any +.Ed +.Pp +The files +.Pa /etc/spammers +and +.Pa /etc/openrelays +list IP addresses, one per line. +Any lines beginning with a # are treated as comments and ignored. +In addition to being specified by IP address, hosts may also be +specified by their hostname. +When the resolver is called to add a hostname to a table, +.Em all +resulting IPv4 and IPv6 addresses are placed into the table. +IP addresses can also be entered in a table by specifying a valid interface +name or the +.Em self +keyword, in which case all addresses assigned to the interface(s) will be +added to the table. +.Sh OPTIONS +.Xr pf 4 +may be tuned for various situations using the +.Ar set +command. +.Bl -tag -width xxxx +.It Ar set timeout +.Pp +.Bl -tag -width interval -compact +.It Ar interval +Interval between purging expired states and fragments. +.It Ar frag +Seconds before an unassembled fragment is expired. +.El +.Pp +When a packet matches a stateful connection, the seconds to live for the +connection will be updated to that of the +.Ar proto.modifier +which corresponds to the connection state. +Each packet which matches this state will reset the TTL. +Tuning these values may improve the performance of the +firewall at the risk of dropping valid idle connections. +.Pp +.Bl -tag -width xxxx -compact +.It Ar tcp.first +The state after the first packet. +.It Ar tcp.opening +The state before the destination host ever sends a packet. +.It Ar tcp.established +The fully established state. +.It Ar tcp.closing +The state after the first FIN has been sent. +.It Ar tcp.finwait +The state after both FINs have been exchanged and the connection is closed. +Some hosts (notably web servers on Solaris) send TCP packets even after closing +the connection. +Increasing +.Ar tcp.finwait +(and possibly +.Ar tcp.closing ) +can prevent blocking of such packets. +.It Ar tcp.closed +The state after one endpoint sends an RST. +.El +.Pp +ICMP and UDP are handled in a fashion similar to TCP, but with a much more +limited set of states: +.Pp +.Bl -tag -width xxxx -compact +.It Ar udp.first +The state after the first packet. +.It Ar udp.single +The state if the source host sends more than one packet but the destination +host has never sent one back. +.It Ar udp.multiple +The state if both hosts have sent packets. +.It Ar icmp.first +The state after the first packet. +.It Ar icmp.error +The state after an ICMP error came back in response to an ICMP packet. +.El +.Pp +Other protocols are handled similarly to UDP: +.Pp +.Bl -tag -width xxxx -compact +.It Ar other.first +.It Ar other.single +.It Ar other.multiple +.El +.Pp +Timeout values can be reduced adaptively as the number of state table +entries grows. +.Pp +.Bl -tag -width xxxx -compact +.It Ar adaptive.start +When the number of state entries exceeds this value, adaptive scaling +begins. +All timeout values are scaled linearly with factor +(adaptive.end - number of states) / (adaptive.end - adaptive.start). +.It Ar adaptive.end +When reaching this number of state entries, all timeout values become +zero, effectively purging all state entries immediately. +This value is used to define the scale factor, it should not actually +be reached (set a lower state limit, see below). +.El +.Pp +These values can be defined both globally and for each rule. +When used on a per-rule basis, the values relate to the number of +states created by the rule, otherwise to the total number of +states. +.Pp +For example: +.Bd -literal -offset indent +set timeout tcp.first 120 +set timeout tcp.established 86400 +set timeout { adaptive.start 6000, adaptive.end 12000 } +set limit states 10000 +.Ed +.Pp +With 9000 state table entries, the timeout values are scaled to 50% +(tcp.first 60, tcp.established 43200). +.Pp +.It Ar set loginterface +Enable collection of packet and byte count statistics for the given interface. +These statistics can be viewed using +.Bd -literal -offset indent +# pfctl -s info +.Ed +.Pp +In this example +.Xr pf 4 +collects statistics on the interface named dc0: +.Bd -literal -offset indent +set loginterface dc0 +.Ed +.Pp +One can disable the loginterface using: +.Bd -literal -offset indent +set loginterface none +.Ed +.Pp +.It Ar set limit +Sets hard limits on the memory pools used by the packet filter. +See +.Xr pool 9 +for an explanation of memory pools. +.Pp +For example, +.Bd -literal -offset indent +set limit states 20000 +.Ed +.Pp +sets the maximum number of entries in the memory pool used by state table +entries (generated by +.Ar keep state +rules) to 20000. +Using +.Bd -literal -offset indent +set limit frags 20000 +.Ed +.Pp +sets the maximum number of entries in the memory pool used for fragment +reassembly (generated by +.Ar scrub +rules) to 20000. +.Pp +These can be combined: +.Bd -literal -offset indent +set limit { states 20000, frags 20000 } +.Ed +.Pp +.It Ar set optimization +Optimize the engine for one of the following network environments: +.Pp +.Bl -tag -width xxxx -compact +.It Ar normal +A normal network environment. +Suitable for almost all networks. +.It Ar high-latency +A high-latency environment (such as a satellite connection). +.It Ar satellite +Alias for +.Ar high-latency . +.It Ar aggressive +Aggressively expire connections. +This can greatly reduce the memory usage of the firewall at the cost of +dropping idle connections early. +.It Ar conservative +Extremely conservative settings. +Avoid dropping legitimate connections at the +expense of greater memory utilization (possibly much greater on a busy +network) and slightly increased processor utilization. +.El +.Pp +For example: +.Bd -literal -offset indent +set optimization aggressive +.Ed +.Pp +.It Ar set block-policy +The +.Ar block-policy +option sets the default behaviour for the packet +.Ar block +action: +.Pp +.Bl -tag -width xxxxxxxx -compact +.It Ar drop +Packet is silently dropped. +.It Ar return +A TCP RST is returned for blocked TCP packets, +an ICMP UNREACHABLE is returned for blocked UDP packets, +and all other packets are silently dropped. +.El +.Pp +For example: +.Bd -literal -offset indent +set block-policy return +.Ed +.It Ar set require-order +By default +.Xr pfctl 8 +enforces an ordering of the statement types in the ruleset to: +.Em options , +.Em normalization , +.Em queueing , +.Em translation , +.Em filtering . +Setting this option to +.Ar no +disables this enforcement. +There may be non-trivial and non-obvious implications to an out of +order ruleset. +Consider carefully before disabling the order enforcement. +.It Ar set fingerprints +Load fingerprints of known operating systems from the given filename. +By default fingerprints of known operating systems are automatically +loaded from +.Xr pf.os 5 +in +.Pa /etc +but can be overridden via this option. +Setting this option may leave a small period of time where the fingerprints +referenced by the currently active ruleset are inconsistent until the new +ruleset finishes loading. +.Pp +For example: +.Pp +.Dl set fingerprints \&"/etc/pf.os.devel\&" +.El +.Sh TRAFFIC NORMALIZATION +Traffic normalization is used to sanitize packet content in such +a way that there are no ambiguities in packet interpretation on +the receiving side. +The normalizer does IP fragment reassembly to prevent attacks +that confuse intrusion detection systems by sending overlapping +IP fragments. +Packet normalization is invoked with the +.Ar scrub +directive. +.Pp +.Ar scrub +has the following options: +.Bl -tag -width xxxx +.It Ar no-df +Clears the +.Ar dont-fragment +bit from a matching IP packet. +Some operating systems are known to generate fragmented packets with the +.Ar dont-fragment +bit set. +This is particularly true with NFS. +.Ar Scrub +will drop such fragmented +.Ar dont-fragment +packets unless +.Ar no-df +is specified. +.Pp +Unfortunately some operating systems also generate their +.Ar dont-fragment +packets with a zero IP identification field. +Clearing the +.Ar dont-fragment +bit on packets with a zero IP ID may cause deleterious results if an +upstream router later fragments the packet. +Using the +.Ar random-id +modifier (see below) is recommended in combination with the +.Ar no-df +modifier to ensure unique IP identifiers. +.It Ar min-ttl <number> +Enforces a minimum TTL for matching IP packets. +.It Ar max-mss <number> +Enforces a maximum MSS for matching TCP packets. +.It Ar random-id +Replaces the IP identification field with random values to compensate +for predictable values generated by many hosts. +This option only applies to outgoing packets that are not fragmented +after the optional fragment reassembly. +.It Ar fragment reassemble +Using +.Ar scrub +rules, fragments can be reassembled by normalization. +In this case, fragments are buffered until they form a complete +packet, and only the completed packet is passed on to the filter. +The advantage is that filter rules have to deal only with complete +packets, and can ignore fragments. +The drawback of caching fragments is the additional memory cost. +But the full reassembly method is the only method that currently works +with NAT. +This is the default behavior of a +.Ar scrub +rule if no fragmentation modifier is supplied. +.It Ar fragment crop +The default fragment reassembly method is expensive, hence the option +to crop is provided. +In this case, +.Xr pf 4 +will track the fragments and cache a small range descriptor. +Duplicate fragments are dropped and overlaps are cropped. +Thus data will only occur once on the wire with ambiguities resolving to +the first occurrence. +Unlike the +.Ar fragment reassemble +modifier, fragments are not buffered, they are passed as soon as they +are received. +The +.Ar fragment crop +reassembly mechanism does not yet work with NAT. +.Pp +.It Ar fragment drop-ovl +This option is similar to the +.Ar fragment crop +modifier except that all overlapping or duplicate fragments will be +dropped, and all further corresponding fragments will be +dropped as well. +.It Ar reassemble tcp +Statefully normalizes TCP connections. +.Ar scrub reassemble tcp +rules may not have the direction (in/out) specified. +.Ar reassemble tcp +performs the following normalizations: +.Pp +.Bl -tag -width timeout -compact +.It ttl +Neither side of the connection is allowed to reduce their IP TTL. +An attacker may send a packet such that it reaches the firewall, affects +the firewall state, and expires before reaching the destination host. +.Ar reassemble tcp +will raise the TTL of all packets back up to the highest value seen on +the connection. +.It timeout modulation +Modern TCP stacks will send a timestamp on every TCP packet and echo +the other endpoint's timestamp back to them. +Many operating systems will merely start the timestamp at zero when +first booted, and increment it several times a second. +The uptime of the host can be deduced by reading the timestamp and multiplying +by a constant. +Also observing several different timestamps can be used to count hosts +behind a NAT device. +And spoofing TCP packets into a connection requires knowing or guessing +valid timestamps. +Timestamps merely need to be monotonically increasing and not derived off a +guessable base time. +.Ar reassemble tcp +will cause +.Ar scrub +to modulate the TCP timestamps with a random number. +.El +.El +.Pp +For example, +.Bd -literal -offset indent +scrub in on $ext_if all fragment reassemble +.Ed +.Sh QUEUEING +Packets can be assigned to queues for the purpose of bandwidth +control. +At least two declarations are required to configure queues, and later +any packet filtering rule can reference the defined queues by name. +During the filtering component of +.Nm pf.conf , +the last referenced +.Ar queue +name is where any packets from +.Ar pass +rules will be queued, while for +.Ar block +rules it specifies where any resulting ICMP or TCP RST +packets should be queued. +The +.Ar scheduler +defines the algorithm used to decide which packets get delayed, dropped, or +sent out immediately. +There are three +.Ar schedulers +currently supported. +.Bl -tag -width xxxx +.It Ar cbq +Class Based Queueing. +.Ar Queues +attached to an interface build a tree, thus each +.Ar queue +can have further child +.Ar queues . +Each queue can have a +.Ar priority +and a +.Ar bandwidth +assigned. +.Ar Priority +mainly controls the time packets take to get sent out, while +.Ar bandwidth +has primarily effects on throughput. +.It Ar priq +Priority Queueing. +.Ar Queues +are flat attached to the interface, thus, +.Ar queues +cannot have further child +.Ar queues . +Each +.Ar queue +has a unique +.Ar priority +assigned, ranging from 0 to 15. +Packets in the +.Ar queue +with the highest +.Ar priority +are processed first. +.It Ar hfsc +Hierarchical Fair Service Curve. +.Ar Queues +attached to an interface build a tree, thus each +.Ar queue +can have further child +.Ar queues . +Each queue can have a +.Ar priority +and a +.Ar bandwidth +assigned. +.Ar Priority +mainly controls the time packets take to get sent out, while +.Ar bandwidth +has primarily effects on throughput. +.El +.Pp +The interfaces on which queueing should be activated are declared using +the +.Ar altq on +declaration. +.Ar altq on +has the following keywords: +.Bl -tag -width xxxx +.It Ar <interface> +Queueing is enabled on the named interface. +.It Ar <scheduler> +Specifies which queueing scheduler to use. +Currently supported values +are +.Ar cbq +for Class Based Queueing, +.Ar priq +for Priority Queueing and +.Ar hfsc +for the Hierarchical Fair Service Curve scheduler. +.It Ar bandwidth <bw> +The maximum bitrate for all queues on an +interface may be specified using the +.Ar bandwidth +keyword. +The value can be specified as an absolute value or as a +percentage of the interface bandwidth. +When using an absolute value, the suffixes +.Ar b , +.Ar Kb , +.Ar Mb , +and +.Ar Gb +are used to represent bits, kilobits, megabits, and +gigabits per second, respectively. +The value must not exceed the interface bandwidth. +If +.Ar bandwidth +is not specified, the interface bandwidth is used. +.It Ar qlimit <limit> +The maximum number of packets held in the queue. +The default is 50. +.It Ar tbrsize <size> +Adjusts the size, in bytes, of the token bucket regulator. +If not specified, heuristics based on the +interface bandwidth are used to determine the size. +.It Ar queue <list> +Defines a list of subqueues to create on an interface. +.El +.Pp +In the following example, the interface dc0 +should queue up to 5 Mbit/s in four second-level queues using +Class Based Queueing. +Those four queues will be shown in a later example. +.Bd -literal -offset indent +altq on dc0 cbq bandwidth 5Mb queue { std, http, mail, ssh } +.Ed +.Pp +Once interfaces are activated for queueing using the +.Ar altq +directive, a sequence of +.Ar queue +directives may be defined. +The name associated with a +.Ar queue +must match a queue defined in the +.Ar altq +directive (e.g. mail), or, except for the +.Ar priq +.Ar scheduler , +in a parent +.Ar queue +declaration. +The following keywords can be used: +.Bl -tag -width xxxx +.It Ar on <interface> +Specifies the interface the queue operates on. +If not given, it operates on all matching interfaces. +.It Ar bandwidth <bw> +Specifies the maximum bitrate to be processed by the queue. +This value must not exceed the value of the parent +.Ar queue +and can be specified as an absolute value or a percentage of the parent +queue's bandwidth. +The +.Ar priq +scheduler does not support bandwidth specification. +.It Ar priority <level> +Between queues a priority level can be set. +For +.Ar cbq +and +.Ar hfsc , +the range is 0 to 7 and for +.Ar priq , +the range is 0 to 15. +The default for all is 1. +.Ar Priq +queues with a higher priority are always served first. +.Ar Cbq +and +.Ar Hfsc +queues with a higher priority are preferred in the case of overload. +.It Ar qlimit <limit> +The maximum number of packets held in the queue. +The default is 50. +.El +.Pp +The +.Ar scheduler +can get additional parameters with +.Ar <scheduler> Ns Li (\& Ar <parameters> No ) . +Parameters are as follows: +.Bl -tag -width Fl +.It Ar default +Packets not matched by another queue are assigned to this one. +Exactly one default queue is required. +.It Ar red +Enable RED (Random Early Detection) on this queue. +RED drops packets with a probability proportional to the average +queue length. +.It Ar rio +Enables RIO on this queue. +RIO is RED with IN/OUT, thus running +RED two times more than RIO would achieve the same effect. +RIO is currently not supported in the GENERIC kernel. +.It Ar ecn +Enables ECN (Explicit Congestion Notification) on this queue. +ECN implies RED. +.El +.Pp +The +.Ar cbq +.Ar scheduler +supports an additional option: +.Bl -tag -width Fl +.It Ar borrow +The queue can borrow bandwidth from the parent. +.El +.Pp +The +.Ar hfsc +.Ar scheduler +supports some additional options: +.Bl -tag -width Fl +.It Ar realtime <sc> +The minimum required bandwidth for the queue. +.It Ar upperlimit <sc> +The maximum allowed bandwidth for the queue. +.It Ar linkshare <sc> +The bandwidth share of a backlogged queue. +.El +.Pp +<sc> is an acronym for +.Ar service curve . +.Pp +The format for service curve specifications is +.Ar ( m1 , d , m2 ) . +.Ar m2 +controls the bandwidth assigned to the queue. +.Ar m1 +and +.Ar d +are optional and can be used to control the initial bandwidth assignment. +For the first +.Ar d +milliseconds the queue gets the bandwidth given as +.Ar m1 , +afterwards the value given in +.Ar m2 . +.Pp +Furthermore, with +.Ar cbq +and +.Ar hfsc , +child queues can be specified as in an +.Ar altq +declaration, thus building a tree of queues using a part of +their parent's bandwidth. +.Pp +Packets can be assigned to queues based on filter rules by using the +.Ar queue +keyword. +Normally only one +.Ar queue +is specified; when a second one is specified it will instead be used for +packets which have a +.Em TOS +of +.Em lowdelay +and for TCP ACKs with no data payload. +.Pp +To continue the previous example, the examples below would specify the +four referenced +queues, plus a few child queues. +Interactive +.Xr ssh 1 +sessions get priority over bulk transfers like +.Xr scp 1 +and +.Xr sftp 1 . +The queues may then be referenced by filtering rules (see +.Sx PACKET FILTERING +below). +.Bd -literal +queue std bandwidth 10% cbq(default) +queue http bandwidth 60% priority 2 cbq(borrow red) \e + { employees, developers } +queue developers bandwidth 75% cbq(borrow) +queue employees bandwidth 15% +queue mail bandwidth 10% priority 0 cbq(borrow ecn) +queue ssh bandwidth 20% cbq(borrow) { ssh_interactive, ssh_bulk } +queue ssh_interactive priority 7 +queue ssh_bulk priority 0 + +block return out on dc0 inet all queue std +pass out on dc0 inet proto tcp from $developerhosts to any port 80 \e + keep state queue developers +pass out on dc0 inet proto tcp from $employeehosts to any port 80 \e + keep state queue employees +pass out on dc0 inet proto tcp from any to any port 22 \e + keep state queue(ssh_bulk, ssh_interactive) +pass out on dc0 inet proto tcp from any to any port 25 \e + keep state queue mail +.Ed +.Sh TRANSLATION +Translation rules modify either the source or destination address of the +packets associated with a stateful connection. +A stateful connection is automatically created to track packets matching +such a rule as long as they are not blocked by the filtering section of +.Nm pf.conf . +The translation engine modifies the specified address and/or port in the +packet, recalculates IP, TCP and UDP checksums as necessary, and passes it to +the packet filter for evaluation. +.Pp +Since translation occurs before filtering the filter +engine will see packets as they look after any +addresses and ports have been translated. Filter rules +will therefore have to filter based on the translated +address and port number. +Packets that match a translation rule are only automatically passed if +the +.Ar pass +modifier is given, otherwise they are +still subject to +.Ar block +and +.Ar pass +rules. +.Pp +The state entry created permits +.Xr pf 4 +to keep track of the original address for traffic associated with that state +and correctly direct return traffic for that connection. +.Pp +Various types of translation are possible with pf: +.Bl -tag -width xxxx +.It Ar binat +A +.Ar binat +rule specifies a bidirectional mapping between an external IP netblock +and an internal IP netblock. +.It Ar nat +A +.Ar nat +rule specifies that IP addresses are to be changed as the packet +traverses the given interface. +This technique allows one or more IP addresses +on the translating host to support network traffic for a larger range of +machines on an "inside" network. +Although in theory any IP address can be used on the inside, it is strongly +recommended that one of the address ranges defined by RFC 1918 be used. +These netblocks are: +.Bd -literal +10.0.0.0 - 10.255.255.255 (all of net 10, i.e., 10/8) +172.16.0.0 - 172.31.255.255 (i.e., 172.16/12) +192.168.0.0 - 192.168.255.255 (i.e., 192.168/16) +.Ed +.It Pa rdr +The packet is redirected to another destination and possibly a +different port. +.Ar rdr +rules can optionally specify port ranges instead of single ports. +rdr ... port 2000:2999 -> ... port 4000 +redirects ports 2000 to 2999 (inclusive) to port 4000. +rdr ... port 2000:2999 -> ... port 4000:* +redirects port 2000 to 4000, 2001 to 4001, ..., 2999 to 4999. +.El +.Pp +In addition to modifying the address, some translation rules may modify +source or destination ports for +.Xr tcp 4 +or +.Xr udp 4 +connections; implicitly in the case of +.Ar nat +rules and explicitly in the case of +.Ar rdr +rules. +Port numbers are never translated with a +.Ar binat +rule. +.Pp +For each packet processed by the translator, the translation rules are +evaluated in sequential order, from first to last. +The first matching rule decides what action is taken. +.Pp +The +.Ar no +option prefixed to a translation rule causes packets to remain untranslated, +much in the same way as +.Ar drop quick +works in the packet filter (see below). +If no rule matches the packet it is passed to the filter engine unmodified. +.Pp +Translation rules apply only to packets that pass through +the specified interface, and if no interface is specified, +translation is applied to packets on all interfaces. +For instance, redirecting port 80 on an external interface to an internal +web server will only work for connections originating from the outside. +Connections to the address of the external interface from local hosts will +not be redirected, since such packets do not actually pass through the +external interface. +Redirections cannot reflect packets back through the interface they arrive +on, they can only be redirected to hosts connected to different interfaces +or to the firewall itself. +.Pp +Note that redirecting external incoming connections to the loopback +address, as in +.Bd -literal -offset indent +rdr on ne3 inet proto tcp to port 8025 -> 127.0.0.1 port 25 +.Ed +.Pp +will effectively allow an external host to connect to daemons +bound solely to the loopback address, circumventing the traditional +blocking of such connections on a real interface. +Unless this effect is desired, any of the local non-loopback addresses +should be used as redirection target instead, which allows external +connections only to daemons bound to this address or not bound to +any address. +.Pp +See +.Sx TRANSLATION EXAMPLES +below. +.Sh PACKET FILTERING +.Xr pf 4 +has the ability to +.Ar block +and +.Ar pass +packets based on attributes of their layer 3 (see +.Xr ip 4 +and +.Xr ip6 4 ) +and layer 4 (see +.Xr icmp 4 , +.Xr icmp6 4 , +.Xr tcp 4 , +.Xr udp 4 ) +headers. +In addition, packets may also be +assigned to queues for the purpose of bandwidth control. +.Pp +For each packet processed by the packet filter, the filter rules are +evaluated in sequential order, from first to last. +The last matching rule decides what action is taken. +.Pp +The following actions can be used in the filter: +.Bl -tag -width xxxx +.It Ar block +The packet is blocked. +There are a number of ways in which a +.Ar block +rule can behave when blocking a packet. +The default behaviour is to +.Ar drop +packets silently, however this can be overridden or made +explicit either globally, by setting the +.Ar block-policy +option, or on a per-rule basis with one of the following options: +.Pp +.Bl -tag -width xxxx -compact +.It Ar drop +The packet is silently dropped. +.It Ar return-rst +This applies only to +.Xr tcp 4 +packets, and issues a TCP RST which closes the +connection. +.It Ar return-icmp +.It Ar return-icmp6 +This causes ICMP messages to be returned for packets which match the rule. +By default this is an ICMP UNREACHABLE message, however this +can be overridden by specifying a message as a code or number. +.It Ar return +This causes a TCP RST to be returned for +.Xr tcp 4 +packets and an ICMP UNREACHABLE for UDP and other packets. +.El +.Pp +Options returning packets have no effect if +.Xr pf 4 +operates on a +.Xr bridge 4 . +.It Ar pass +The packet is passed. +.El +.Pp +If no rule matches the packet, the default action is +.Ar pass . +.Pp +To block everything by default and only pass packets +that match explicit rules, one uses +.Bd -literal -offset indent +block all +.Ed +.Pp +as the first filter rule. +.Pp +See +.Sx FILTER EXAMPLES +below. +.Sh PARAMETERS +The rule parameters specify the packets to which a rule applies. +A packet always comes in on, or goes out through, one interface. +Most parameters are optional. +If a parameter is specified, the rule only applies to packets with +matching attributes. +Certain parameters can be expressed as lists, in which case +.Xr pfctl 8 +generates all needed rule combinations. +.Bl -tag -width xxxx +.It Ar in No or Ar out +This rule applies to incoming or outgoing packets. +If neither +.Ar in +nor +.Ar out +are specified, the rule will match packets in both directions. +.It Ar log +In addition to the action specified, a log message is generated. +All packets for that connection are logged, unless the +.Ar keep state +or +.Ar modulate state +options are specified, in which case only the +packet that establishes the state is logged. +(See +.Ar keep state +and +.Ar modulate state +below). +The logged packets are sent to the +.Xr pflog 4 +interface. +This interface is monitored by the +.Xr pflogd 8 +logging daemon, which dumps the logged packets to the file +.Pa /var/log/pflog +in +.Xr pcap 3 +binary format. +.It Ar log-all +Used with +.Ar keep state +or +.Ar modulate state +rules to force logging of all packets for a connection. +As with +.Ar log , +packets are logged to +.Xr pflog 4 . +.It Ar quick +If a packet matches a rule which has the +.Ar quick +option set, this rule +is considered the last matching rule, and evaluation of subsequent rules +is skipped. +.It Ar on <interface> +This rule applies only to packets coming in on, or going out through, this +particular interface. +.It Ar <af> +This rule applies only to packets of this address family. +Supported values are +.Ar inet +and +.Ar inet6 . +.It Ar proto <protocol> +This rule applies only to packets of this protocol. +Common protocols are +.Xr icmp 4 , +.Xr icmp6 4 , +.Xr tcp 4 , +and +.Xr udp 4 . +For a list of all the protocol name to number mappings used by +.Xr pfctl 8 , +see the file +.Em /etc/protocols . +.It Xo +.Ar from <source> port <source> os <source> +.Ar to <dest> port <dest> +.Xc +This rule applies only to packets with the specified source and destination +addresses and ports. +.Pp +Addresses can be specified in CIDR notation (matching netblocks), as +symbolic host names or interface names, or as any of the following keywords: +.Pp +.Bl -tag -width xxxxxxxxxxxx -compact +.It Ar any +Any address. +.It Ar no-route +Any address which is not currently routable. +.It Ar <table> +Any address that matches the given table. +.El +.Pp +Interface names can have modifiers appended: +.Pp +.Bl -tag -width xxxxxxxxxxxx -compact +.It Ar :network +Translates to the network(s) attached to the interface. +.It Ar :broadcast +Translates to the interface's broadcast address(es). +.El +.Pp +Host name resolution and interface to address translation are done at +ruleset load-time. +When the address of an interface (or host name) changes (under DHCP or PPP, +for instance), the ruleset must be reloaded for the change to be reflected +in the kernel. +Surrounding the interface name in parentheses changes this behaviour. +When the interface name is surrounded by parentheses, the rule is +automatically updated whenever the interface changes its address. +The ruleset does not need to be reloaded. +This is especially useful with +.Ar nat . +.Pp +Ports can be specified either by number or by name. +For example, port 80 can be specified as +.Em www . +For a list of all port name to number mappings used by +.Xr pfctl 8 , +see the file +.Pa /etc/services . +.Pp +Ports and ranges of ports are specified by using these operators: +.Bd -literal -offset indent += (equal) +!= (unequal) +< (less than) +<= (less than or equal) +> (greater than) +>= (greater than or equal) +>< (range) +<> (except range) +.Ed +.Pp +>< and <> +are binary operators (they take two arguments), and the range +does not include the limits. +For instance: +.Bl -tag -width Fl +.It Ar port 2000 >< 2004 +means +.Sq all ports > 2000 and < 2004 , +hence ports 2001, 2002 and 2003. +.It Ar port 2000 <> 2004 +means +.Sq all ports < 2000 or > 2004 , +hence ports 1-1999 and 2005-65535. +.El +.Pp +The operating system of the source host can be specified in the case of TCP +rules with the +.Ar OS +modifier. +See the +.Sx OPERATING SYSTEM FINGERPRINTING +section for more information. +.Pp +The host, port and OS specifications are optional, as in the following examples: +.Bd -literal -offset indent +pass in all +pass in from any to any +pass in proto tcp from any port <= 1024 to any +pass in proto tcp from any to any port 25 +pass in proto tcp from 10.0.0.0/8 port > 1024 \e + to ! 10.1.2.3 port != ssh +pass in proto tcp from any os "OpenBSD" flags S/SA +.Ed +.It Ar all +This is equivalent to "from any to any". +.It Ar group <group> +Similar to +.Ar user , +this rule only applies to packets of sockets owned by the specified group. +.It Ar user <user> +This rule only applies to packets of sockets owned by the specified user. +For outgoing connections initiated from the firewall, this is the user +that opened the connection. +For incoming connections to the firewall itself, this is the user that +listens on the destination port. +For forwarded connections, where the firewall is not a connection endpoint, +the user and group are +.Em unknown . +.Pp +All packets, both outgoing and incoming, of one connection are associated +with the same user and group. +Only TCP and UDP packets can be associated with users; for other protocols +these parameters are ignored. +.Pp +User and group refer to the effective (as opposed to the real) IDs, in +case the socket is created by a setuid/setgid process. +User and group IDs are stored when a socket is created; +when a process creates a listening socket as root (for instance, by +binding to a privileged port) and subsequently changes to another +user ID (to drop privileges), the credentials will remain root. +.Pp +User and group IDs can be specified as either numbers or names. +The syntax is similar to the one for ports. +The value +.Em unknown +matches packets of forwarded connections. +.Em unknown +can only be used with the operators +.Cm = +and +.Cm != . +Other constructs like +.Cm user >= unknown +are invalid. +Forwarded packets with unknown user and group ID match only rules +that explicitly compare against +.Em unknown +with the operators +.Cm = +or +.Cm != . +For instance +.Cm user >= 0 +does not match forwarded packets. +The following example allows only selected users to open outgoing +connections: +.Bd -literal -offset indent +block out proto { tcp, udp } all +pass out proto { tcp, udp } all \e + user { < 1000, dhartmei } keep state +.Ed +.It Ar flags <a>/<b> | /<b> +This rule only applies to TCP packets that have the flags +.Ar <a> +set out of set +.Ar <b> . +Flags not specified in +.Ar <b> +are ignored. +The flags are: (F)IN, (S)YN, (R)ST, (P)USH, (A)CK, (U)RG, (E)CE, and C(W)R. +.Bl -tag -width Fl +.It Ar flags S/S +Flag SYN is set. +The other flags are ignored. +.It Ar flags S/SA +Out of SYN and ACK, exactly SYN may be set. +SYN, SYN+PSH and SYN+RST match, but SYN+ACK, ACK and ACK+RST do not. +This is more restrictive than the previous example. +.It Ar flags /SFRA +If the first set is not specified, it defaults to none. +All of SYN, FIN, RST and ACK must be unset. +.El +.It Ar icmp-type <type> code <code> +.It Ar icmp6-type <type> code <code> +This rule only applies to ICMP or ICMPv6 packets with the specified type +and code. +This parameter is only valid for rules that cover protocols ICMP or +ICMP6. +The protocol and the ICMP type indicator (icmp-type or icmp6-type) +must match. +.It Ar allow-opts +By default, packets which contain IP options are blocked. +When +.Ar allow-opts +is specified for a +.Ar pass +rule, packets that pass the filter based on that rule (last matching) +do so even if they contain IP options. +For packets that match state, the rule that initially created the +state is used. +The implicit +.Ar pass +rule that is used when a packet does not match any rules does not +allow IP options. +.It Ar label <string> +Adds a label (name) to the rule, which can be used to identify the rule. +For instance, +pfctl -s labels +shows per-rule statistics for rules that have labels. +.Pp +The following macros can be used in labels: +.Pp +.Bl -tag -width $srcaddr -compact -offset indent +.It Ar $if +The interface. +.It Ar $srcaddr +The source IP address. +.It Ar $dstaddr +The destination IP address. +.It Ar $srcport +The source port specification. +.It Ar $dstport +The destination port specification. +.It Ar $proto +The protocol name. +.It Ar $nr +The rule number. +.El +.Pp +For example: +.Bd -literal -offset indent +ips = \&"{ 1.2.3.4, 1.2.3.5 }\&" +pass in proto tcp from any to $ips \e + port > 1023 label \&"$dstaddr:$dstport\&" +.Ed +.Pp +expands to +.Bd -literal -offset indent +pass in inet proto tcp from any to 1.2.3.4 \e + port > 1023 label \&"1.2.3.4:>1023\&" +pass in inet proto tcp from any to 1.2.3.5 \e + port > 1023 label \&"1.2.3.5:>1023\&" +.Ed +.Pp +The macro expansion for the +.Ar label +directive occurs only at configuration file parse time, not during runtime. +.It Ar queue <queue> | ( <queue> , <queue> ) +Packets matching this rule will be assigned to the specified queue. +If two queues are given, packets which have a +.Em tos +of +.Em lowdelay +and TCP ACKs with no data payload will be assigned to the second one. +See +.Sx QUEUEING +for setup details. +.Pp +For example: +.Bd -literal -offset indent +pass in proto tcp to port 25 queue mail +pass in proto tcp to port 22 queue(ssh_bulk, ssh_prio) +.Ed +.It Ar tag <string> +Packets matching this rule will be tagged with the +specified string. +The tag acts as an internal marker that can be used to +identify these packets later on. +This can be used, for example, to provide trust between +interfaces and to determine if packets have been +processed by translation rules. +Tags are +.Qq sticky , +meaning that the packet will be tagged even if the rule +is not the last matching rule. +Further matching rules can replace the tag with a +new one but will not remove a previously applied tag. +A packet is only ever assigned one tag at a time. +.Ar pass +rules that use the +.Ar tag +keyword must also use +.Ar keep state . +Packet tagging can be done during +.Ar nat , +.Ar rdr , +or +.Ar binat +rules in addition to filter rules. +.It Ar tagged <string> +Used with filter rules to specify that packets must already +be tagged with the given tag in order to match the rule. +Inverse tag matching can also be done +by specifying the +.Cm !\& +operator before the +.Ar tagged +keyword. +.El +.Sh ROUTING +If a packet matches a rule with a route option set, the packet filter will +route the packet according to the type of route option. +When such a rule creates state, the route option is also applied to all +packets matching the same connection. +.Bl -tag -width xxxx +.It Ar fastroute +The +.Ar fastroute +option does a normal route lookup to find the next hop for the packet. +.It Ar route-to +The +.Ar route-to +option routes the packet to the specified interface with an optional address +for the next hop. +When a +.Ar route-to +rule creates state, only packets that pass in the same direction as the +filter rule specifies will be routed in this way. +Packets passing in the opposite direction (replies) are not affected +and are routed normally. +.It Ar reply-to +The +.Ar reply-to +option is similar to +.Ar route-to , +but routes packets that pass in the opposite direction (replies) to the +specified interface. +Opposite direction is only defined in the context of a state entry, and +.Ar route-to +is useful only in rules that create state. +It can be used on systems with multiple external connections to +route all outgoing packets of a connection through the interface +the incoming connection arrived through (symmetric routing enforcement). +.It Ar dup-to +The +.Ar dup-to +option creates a duplicate of the packet and routes it like +.Ar route-to . +The original packet gets routed as it normally would. +.El +.Sh POOL OPTIONS +For +.Ar nat +and +.Ar rdr +rules, (as well as for the +.Ar route-to , +.Ar reply-to +and +.Ar dup-to +rule options) for which there is a single redirection address which has a +subnet mask smaller than 32 for IPv4 or 128 for IPv6 (more than one IP +address), a variety of different methods for assigning this address can be +used: +.Bl -tag -width xxxx +.It Ar bitmask +The +.Ar bitmask +option applies the network portion of the redirection address to the address +to be modified (source with +.Ar nat , +destination with +.Ar rdr ) . +.It Ar random +The +.Ar random +option selects an address at random within the defined block of addresses. +.It Ar source-hash +The +.Ar source-hash +option uses a hash of the source address to determine the redirection address, +ensuring that the redirection address is always the same for a given source. +An optional key can be specified after this keyword either in hex or as a +string; by default +.Xr pfctl 8 +randomly generates a key for source-hash every time the +ruleset is reloaded. +.It Ar round-robin +The +.Ar round-robin +option loops through the redirection address(es). +.Pp +When more than one redirection address is specified, +.Ar round-robin +is the only permitted pool type. +.It Ar static-port +With +.Ar nat +rules, the +.Ar static-port +option prevents +.Xr pf 4 +from modifying the source port on TCP and UDP packets. +.El +.Sh STATEFUL INSPECTION +.Xr pf 4 +is a stateful packet filter, which means it can track the state of +a connection. +Instead of passing all traffic to port 25, for instance, it is possible +to pass only the initial packet, and then begin to keep state. +Subsequent traffic will flow because the filter is aware of the connection. +.Pp +If a packet matches a +.Ar pass ... keep state +rule, the filter creates a state for this connection and automatically +lets pass all subsequent packets of that connection. +.Pp +Before any rules are evaluated, the filter checks whether the packet +matches any state. +If it does, the packet is passed without evaluation of any rules. +.Pp +States are removed after the connection is closed or has timed out. +.Pp +This has several advantages. +Comparing a packet to a state involves checking its sequence numbers. +If the sequence numbers are outside the narrow windows of expected +values, the packet is dropped. +This prevents spoofing attacks, such as when an attacker sends packets with +a fake source address/port but does not know the connection's sequence +numbers. +.Pp +Also, looking up states is usually faster than evaluating rules. +If there are 50 rules, all of them are evaluated sequentially in O(n). +Even with 50000 states, only 16 comparisons are needed to match a +state, since states are stored in a binary search tree that allows +searches in O(log2 n). +.Pp +For instance: +.Bd -literal -offset indent +block all +pass out proto tcp from any to any flags S/SA keep state +pass in proto tcp from any to any port 25 flags S/SA keep state +.Ed +.Pp +This ruleset blocks everything by default. +Only outgoing connections and incoming connections to port 25 are allowed. +The initial packet of each connection has the SYN +flag set, will be passed and creates state. +All further packets of these connections are passed if they match a state. +.Pp +Specifying +.Ar flags S/SA +restricts state creation to the initial SYN +packet of the TCP handshake. +One can also be less restrictive, and allow state creation from +intermediate +.Pq non-SYN +packets. +This will cause +.Xr pf 4 +to synchronize to existing connections, for instance +if one flushes the state table. +.Pp +For UDP, which is stateless by nature, +.Ar keep state +will create state as well. +UDP packets are matched to states using only host addresses and ports. +.Pp +ICMP messages fall into two categories: ICMP error messages, which always +refer to a TCP or UDP packet, are matched against the referred to connection. +If one keeps state on a TCP connection, and an ICMP source quench message +referring to this TCP connection arrives, it will be matched to the right +state and get passed. +.Pp +For ICMP queries, +.Ar keep state +creates an ICMP state, and +.Xr pf 4 +knows how to match ICMP replies to states. +For example, +.Bd -literal -offset indent +pass out inet proto icmp all icmp-type echoreq keep state +.Ed +.Pp +allows echo requests (such as those created by +.Xr ping 8 ) +out, creates state, and matches incoming echo replies correctly to states. +.Pp +Note: +.Ar nat , binat No and Ar rdr +rules implicitly create state for connections. +.Sh STATE MODULATION +Much of the security derived from TCP is attributable to how well the +initial sequence numbers (ISNs) are chosen. +Some popular stack implementations choose +.Em very +poor ISNs and thus are normally susceptible to ISN prediction exploits. +By applying a +.Ar modulate state +rule to a TCP connection, +.Xr pf 4 +will create a high quality random sequence number for each connection +endpoint. +.Pp +The +.Ar modulate state +directive implicitly keeps state on the rule and is +only applicable to TCP connections. +.Pp +For instance: +.Bd -literal -offset indent +block all +pass out proto tcp from any to any modulate state +pass in proto tcp from any to any port 25 flags S/SA modulate state +.Ed +.Pp +There are two caveats associated with state modulation: +A +.Ar modulate state +rule can not be applied to a pre-existing but unmodulated connection. +Such an application would desynchronize TCP's strict +sequencing between the two endpoints. +Instead, +.Xr pf 4 +will treat the +.Ar modulate state +modifier as a +.Ar keep state +modifier and the pre-existing connection will be inferred without +the protection conferred by modulation. +.Pp +The other caveat affects currently modulated states when the state table +is lost (firewall reboot, flushing the state table, etc...). +.Xr pf 4 +will not be able to infer a connection again after the state table flushes +the connection's modulator. +When the state is lost, the connection may be left dangling until the +respective endpoints time out the connection. +It is possible on a fast local network for the endpoints to start an ACK +storm while trying to resynchronize after the loss of the modulator. +Using a +.Ar flags S/SA +modifier on +.Ar modulate state +rules between fast networks is suggested to prevent ACK storms. +.Sh SYN PROXY +By default, +.Xr pf 4 +passes packets that are part of a +.Xr tcp 4 +handshake between the endpoints. +The +.Ar synproxy state +option can be used to cause +.Xr pf 4 +itself to complete the handshake with the active endpoint, perform a handshake +with the passive endpoint, and then forward packets between the endpoints. +.Pp +No packets are sent to the passive endpoint before the active endpoint has +completed the handshake, hence so-called SYN floods with spoofed source +addresses will not reach the passive endpoint, as the sender can't complete the +handshake. +.Pp +The proxy is transparent to both endpoints, they each see a single +connection from/to the other endpoint. +.Xr pf 4 +choses random initial sequence numbers for both handshakes. +Once the handshakes are completed, the sequence number modulators +(see previous section) are used to translate further packets of the +connection. +Hence, +.Ar synproxy state +includes +.Ar modulate state +and +.Ar keep state . +.Pp +Rules with +.Ar synproxy +will not work if +.Xr pf 4 +operates on a +.Xr bridge 4 . +.Pp +Example: +.Bd -literal -offset indent +pass in proto tcp from any to any port www flags S/SA synproxy state +.Ed +.Sh STATEFUL TRACKING OPTIONS +All three of +.Ar keep state , +.Ar modulate state +and +.Ar synproxy state +support the following options: +.Pp +.Bl -tag -width xxxx -compact +.It Ar max <number> +Limits the number of concurrent states the rule may create. +When this limit is reached, further packets matching the rule that would +create state are dropped, until existing states time out. +.It Ar <timeout> <seconds> +Changes the timeout values used for states created by this rule. +For a list of all valid timeout names, see +.Sx OPTIONS +above. +.Pp +Multiple options can be specified, separated by commas: +.Bd -literal +pass in proto tcp from any to any \e + port www flags S/SA keep state \e + (max 100, tcp.established 60, tcp.closing 5) +.Ed +.El +.Sh OPERATING SYSTEM FINGERPRINTING +Passive OS Fingerprinting is a mechanism to inspect nuances of a TCP +connection's initial SYN packet and guess at the host's operating system. +Unfortunately these nuances are easily spoofed by an attacker so the +fingerprint is not useful in making security decisions. +But the fingerprint is typically accurate enough to make policy decisions +upon. +.Pp +The fingerprints may be specified by operating system class, by +version, or by subtype/patchlevel. +The class of an operating system is typically the vender or genre +and would be OpenBSD for the +.Xr pf 4 +firewall itself. +The version of the oldest available OpenBSD release on the main ftp site +would be 2.6 and the fingerprint would be written +.Pp +.Dl \&"OpenBSD 2.6\&" +.Pp +The subtype of an operating system is typically used to describe the +patchlevel if that patch led to changes in the TCP stack behavior. +In the case of OpenBSD, the only subtype is for a fingerprint that was +normalized by the +.Ar no-df +scrub option and would be specified as +.Pp +.Dl \&"OpenBSD 3.3 no-df\&" +.Pp +Fingerprints for most popular operating systems are provided by +.Xr pf.os 5 . +Once +.Xr pf 4 +is running, a complete list of known operating system fingerprints may +be listed by running: +.Pp +.Dl # pfctl -so +.Pp +Filter rules can enforce policy at any level of operating system specification +assuming a fingerprint is present. +Policy could limit traffic to approved operating systems or even ban traffic +from hosts that aren't at the latest service pack. +.Pp +The +.Ar unknown +class can also be used as the fingerprint which will match packets for +which no operating system fingerprint is known. +.Pp +Examples: +.Bd -literal -offset indent +pass out proto tcp from any os OpenBSD keep state +block out proto tcp from any os Doors +block out proto tcp from any os "Doors PT" +block out proto tcp from any os "Doors PT SP3" +block out from any os "unknown" +pass on lo0 proto tcp from any os "OpenBSD 3.3 lo0" keep state +.Ed +.Pp +Operating system fingerprinting is limited only to the TCP SYN packet. +This means that it will not work on other protocols and will not match +a currently established connection. +.Pp +Caveat: operating system fingerprints are occasionally wrong. +There are three problems: an attacker can trivially craft his packets to +appear as any operating system he chooses; +an operating system patch could change the stack behavior and no fingerprints +will match it until the database is updated; +and multiple operating systems may have the same fingerprint. +.Sh BLOCKING SPOOFED TRAFFIC +"Spoofing" is the faking of IP addresses, typically for malicious +purposes. +The +.Ar antispoof +directive expands to a set of filter rules which will block all +traffic with a source IP from the network(s) directly connected +to the specified interface(s) from entering the system through +any other interface. +.Pp +For example, the line +.Bd -literal -offset indent +antispoof for lo0 +.Ed +.Pp +expands to +.Bd -literal -offset indent +block drop in on ! lo0 inet from 127.0.0.1/8 to any +block drop in on ! lo0 inet6 from ::1 to any +.Ed +.Pp +For non-loopback interfaces, there are additional rules to block incoming +packets with a source IP address identical to the interface's IP(s). +For example, assuming the interface wi0 had an IP address of 10.0.0.1 and a +netmask of 255.255.255.0, +the line +.Bd -literal -offset indent +antispoof for wi0 inet +.Ed +.Pp +expands to +.Bd -literal -offset indent +block drop in on ! wi0 inet from 10.0.0.0/24 to any +block drop in inet from 10.0.0.1 to any +.Ed +.Pp +Caveat: Rules created by the +.Ar antispoof +directive interfere with packets sent over loopback interfaces +to local addresses. +One should pass these explicitly. +.Sh FRAGMENT HANDLING +The size of IP datagrams (packets) can be significantly larger than the +the maximum transmission unit (MTU) of the network. +In cases when it is necessary or more efficient to send such large packets, +the large packet will be fragmented into many smaller packets that will each +fit onto the wire. +Unfortunately for a firewalling device, only the first logical fragment will +contain the necessary header information for the subprotocol that allows +.Xr pf 4 +to filter on things such as TCP ports or to perform NAT. +.Pp +Besides the use of +.Ar scrub +rules as described in +.Sx TRAFFIC NORMALIZATION +above, there are three options for handling fragments in the packet filter. +.Pp +One alternative is to filter individual fragments with filter rules. +If no +.Ar scrub +rule applies to a fragment, it is passed to the filter. +Filter rules with matching IP header parameters decide whether the +fragment is passed or blocked, in the same way as complete packets +are filtered. +Without reassembly, fragments can only be filtered based on IP header +fields (source/destination address, protocol), since subprotocol header +fields are not available (TCP/UDP port numbers, ICMP code/type). +The +.Ar fragment +option can be used to restrict filter rules to apply only to +fragments, but not complete packets. +Filter rules without the +.Ar fragment +option still apply to fragments, if they only specify IP header fields. +For instance, the rule +.Bd -literal -offset indent +pass in proto tcp from any to any port 80 +.Ed +.Pp +never applies to a fragment, even if the fragment is part of a TCP +packet with destination port 80, because without reassembly this information +is not available for each fragment. +This also means that fragments cannot create new or match existing +state table entries, which makes stateful filtering and address +translation (NAT, redirection) for fragments impossible. +.Pp +It's also possible to reassemble only certain fragments by specifying +source or destination addresses or protocols as parameters in +.Ar scrub +rules. +.Pp +In most cases, the benefits of reassembly outweigh the additional +memory cost, and it's recommended to use +.Ar scrub +rules to reassemble +all fragments via the +.Ar fragment reassemble +modifier. +.Pp +The memory allocated for fragment caching can be limited using +.Xr pfctl 8 . +Once this limit is reached, fragments that would have to be cached +are dropped until other entries time out. +The timeout value can also be adjusted. +.Pp +Currently, only IPv4 fragments are supported and IPv6 fragments +are blocked unconditionally. +.Sh ANCHORS AND NAMED RULESETS +Besides the main ruleset, +.Xr pfctl 8 +can load named rulesets into +.Ar anchor +attachment points. +An +.Ar anchor +contains a list of named rulesets. +An +.Ar anchor +has a name which specifies where +.Xr pfctl 8 +can be used to attach sub-rulesets. +A named ruleset contains filter and translation rules, like the +main ruleset. +The main ruleset can reference +.Ar anchor +attachment points +using the following kinds +of rules: +.Bl -tag -width xxxx +.It Ar nat-anchor <name> +Evaluates the +.Ar nat +rules of all named rulesets in the specified +.Ar anchor . +.It Ar rdr-anchor <name> +Evaluates the +.Ar rdr +rules of all named rulesets in the specified +.Ar anchor . +.It Ar binat-anchor <name> +Evaluates the +.Ar binat +rules of all named rulesets in the specified +.Ar anchor . +.It Ar anchor <name> +Evaluates the filter rules of all named rulesets in the specified +.Ar anchor . +.It Ar load anchor <name>:<ruleset> from <file> +Loads the rules from the specified file into the named +ruleset +.Ar <ruleset> +attached to the anchor +.Ar <name> . +.El +.Pp +When evaluation of the main ruleset reaches an +.Ar anchor +rule, +.Xr pf 4 +will proceed to evaluate all rules specified in the +named rulesets attached to that +.Ar anchor . +.Pp +Matching filter rules in named rulesets with the +.Ar quick +option and matching translation rules are final and abort the +evaluation of both the rules in the +.Ar anchor +and the main ruleset. +.Pp +Only the main ruleset can contain +.Ar anchor +rules. +.Pp +When an +.Ar anchor +contains more than one named ruleset, they are evaluated +in the alphabetical order of their names. +.Pp +Rules may contain +.Ar anchor +attachment points which do not contain any rules when the main ruleset +is loaded, and later such named rulesets can be manipulated through +.Xr pfctl 8 +without reloading the main ruleset. +For example, +.Bd -literal -offset indent +ext_if = \&"kue0\&" +block on $ext_if all +anchor spam +pass out on $ext_if all keep state +pass in on $ext_if proto tcp from any \e + to $ext_if port smtp keep state +.Ed +.Pp +blocks all packets on the external interface by default, then evaluates +all rulesets in the +.Ar anchor +named "spam", and finally passes all outgoing connections and +incoming connections to port 25. +.Bd -literal -offset indent +# echo \&"block in quick from 1.2.3.4 to any\&" \&| \e + pfctl -a spam:manual -f - +.Ed +.Pp +loads a single ruleset containing a single rule into the +.Ar anchor , +which blocks all packets from a specific address. +.Pp +The named ruleset can also be populated by adding a +.Ar load anchor +rule after the +.Ar anchor +rule: +.Bd -literal -offset indent +anchor spam +load anchor spam:manual from /etc/pf-spam.conf +.Ed +.Pp +When +.Xr pfctl 8 +loads +.Nm pf.conf , +it will also load all the rules from the file +.Pa /etc/pf-spam.conf +into the named ruleset. +.Pp +Optionally, +.Ar anchor +rules can specify the parameter's +direction, interface, address family, protocol and source/destination +address/port +using the same syntax as filter rules. +When parameters are used, the +.Ar anchor +rule is only evaluated for matching packets. +This allows conditional evaluation of named rulesets, like: +.Bd -literal -offset indent +block on $ext_if all +anchor spam proto tcp from any to any port smtp +pass out on $ext_if all keep state +pass in on $ext_if proto tcp from any to $ext_if port smtp keep state +.Ed +.Pp +The rules inside +.Ar anchor +spam are only evaluated for +.Ar tcp +packets with destination port 25. +Hence, +.Bd -literal -offset indent +# echo \&"block in quick from 1.2.3.4 to any" \&| \e + pfctl -a spam:manual -f - +.Ed +.Pp +will only block connections from 1.2.3.4 to port 25. +.Sh TRANSLATION EXAMPLES +This example maps incoming requests on port 80 to port 8080, on +which a daemon is running (because, for example, it is not run as root, +and therefore lacks permission to bind to port 80). +.Bd -literal +# map daemon on 8080 to appear to be on 80 +rdr on ne3 proto tcp from any to any port 80 -> 127.0.0.1 port 8080 +.Ed +.Pp +If the +.Ar pass +modifier is given, packets matching the translation rule are passed without +inspecting the filter rules: +.Bd -literal +rdr pass on ne3 proto tcp from any to any port 80 -> 127.0.0.1 port 8080 +.Ed +.Pp +In the example below, vlan12 is configured as 192.168.168.1; +the machine translates all packets coming from 192.168.168.0/24 to 204.92.77.111 +when they are going out any interface except vlan12. +This has the net effect of making traffic from the 192.168.168.0/24 +network appear as though it is the Internet routable address +204.92.77.111 to nodes behind any interface on the router except +for the nodes on vlan12. +(Thus, 192.168.168.1 can talk to the 192.168.168.0/24 nodes.) +.Bd -literal +nat on ! vlan12 from 192.168.168.0/24 to any -> 204.92.77.111 +.Ed +.Pp +In the example below, fxp1 is the outside interface; the machine sits between a +fake internal 144.19.74.* network, and a routable external IP of 204.92.77.100. +The +.Ar no nat +rule excludes protocol AH from being translated. +.Bd -literal +# NO NAT +no nat on fxp1 proto ah from 144.19.74.0/24 to any +nat on fxp1 from 144.19.74.0/24 to any -> 204.92.77.100 +.Ed +.Pp +In the example below, fxp0 is the internal interface. +Packets bound +for one specific server, as well as those generated by the sysadmins +are not proxied; all other connections are. +.Bd -literal +# NO RDR +no rdr on fxp0 proto { tcp, udp } from any to $server port 80 +no rdr on fxp0 proto { tcp, udp } from $sysadmins to any port 80 +rdr on fxp0 proto { tcp, udp } from any to any port 80 -> 127.0.0.1 port 80 +.Ed +.Pp +This longer example uses both a NAT and a redirection. +Interface kue0 is the outside interface, and its external address is +157.161.48.183. +Interface fxp0 is the inside interface, and we are running +.Xr ftp-proxy 8 , +listening for outbound ftp sessions captured to port 8021. +.Bd -literal +# NAT +# Translate outgoing packets' source addresses (any protocol). +# In this case, any address but the gateway's external address is mapped. +nat on kue0 inet from ! (kue0) to any -> (kue0) + +# NAT PROXYING +# Map outgoing packets' source port to an assigned proxy port instead of +# an arbitrary port. +# In this case, proxy outgoing isakmp with port 500 on the gateway. +nat on kue0 inet proto udp from any port = isakmp to any -> (kue0) \e + port 500 + +# BINAT +# Translate outgoing packets' source address (any protocol). +# Translate incoming packets' destination address to an internal machine +# (bidirectional). +binat on kue0 from 10.1.2.150 to any -> (kue0) + +# RDR +# Translate incoming packets' destination addresses. +# As an example, redirect a TCP and UDP port to an internal machine. +rdr on kue0 inet proto tcp from any to (kue0) port 8080 -> 10.1.2.151 \e + port 22 +rdr on kue0 inet proto udp from any to (kue0) port 8080 -> 10.1.2.151 \e + port 53 + +# RDR +# Translate outgoing ftp control connections to send them to localhost +# for proxying with ftp-proxy(8) running on port 8021. +rdr on fxp0 proto tcp from any to any port 21 -> 127.0.0.1 port 8021 +.Ed +.Pp +In this example, a NAT gateway is set up to translate internal addresses +using a pool of public addresses (192.0.2.16/28) and to redirect +incoming web server connections to a group of web servers on the internal +network. +Interface fxp0 is the external interface. +.Bd -literal +# NAT LOAD BALANCE +# Translate outgoing packets' source addresses using an address pool. +# A given source address is always translated to the same pool address by +# using the source-hash keyword. +nat on fxp0 inet from any to any -> 192.0.2.16/28 source-hash + +# RDR ROUND ROBIN +# Translate incoming web server connections to a group of web servers on +# the internal network. +rdr on fxp0 proto tcp from any to any port 80 \e + -> { 10.1.2.155, 10.1.2.160, 10.1.2.161 } round-robin +.Ed +.Sh FILTER EXAMPLES +.Bd -literal +# The external interface is kue0 +# (157.161.48.183, the only routable address) +# and the private network is 10.0.0.0/8, for which we are doing NAT. + +# use a macro for the interface name, so it can be changed easily +ext_if = \&"kue0\&" + +# normalize all incoming traffic +scrub in on $ext_if all fragment reassemble + +# block and log everything by default +block return log on $ext_if all + +# block anything coming from source we have no back routes for +block in from no-route to any + +# block and log outgoing packets that do not have our address as source, +# they are either spoofed or something is misconfigured (NAT disabled, +# for instance), we want to be nice and do not send out garbage. +block out log quick on $ext_if from ! 157.161.48.183 to any + +# silently drop broadcasts (cable modem noise) +block in quick on $ext_if from any to 255.255.255.255 + +# block and log incoming packets from reserved address space and invalid +# addresses, they are either spoofed or misconfigured, we cannot reply to +# them anyway (hence, no return-rst). +block in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, \e + 192.168.0.0/16, 255.255.255.255/32 } to any + +# ICMP + +# pass out/in certain ICMP queries and keep state (ping) +# state matching is done on host addresses and ICMP id (not type/code), +# so replies (like 0/0 for 8/0) will match queries +# ICMP error messages (which always refer to a TCP/UDP packet) are +# handled by the TCP/UDP states +pass on $ext_if inet proto icmp all icmp-type 8 code 0 keep state + +# UDP + +# pass out all UDP connections and keep state +pass out on $ext_if proto udp all keep state + +# pass in certain UDP connections and keep state (DNS) +pass in on $ext_if proto udp from any to any port domain keep state + +# TCP + +# pass out all TCP connections and modulate state +pass out on $ext_if proto tcp all modulate state + +# pass in certain TCP connections and keep state (SSH, SMTP, DNS, IDENT) +pass in on $ext_if proto tcp from any to any port { ssh, smtp, domain, \e + auth } flags S/SA keep state + +# pass in data mode connections for ftp-proxy running on this host. +# (see ftp-proxy(8) for details) +pass in on $ext_if proto tcp from any to 157.161.48.183 port >= 49152 \e + flags S/SA keep state + +# Do not allow Windows 9x SMTP connections since they are typically +# a viral worm. Alternately we could limit these OSes to 1 connection each. +block in on $ext_if proto tcp from any os {"Windows 95", "Windows 98"} \e + to any port smtp + +# Packet Tagging + +# three interfaces: $int_if, $ext_if, and $wifi_if (wireless). NAT is +# being done on $ext_if for all outgoing packets. tag packets in on +# $int_if and pass those tagged packets out on $ext_if. all other +# outgoing packets (i.e., packets from the wireless network) are only +# permitted to access port 80. + +pass in on $int_if from any to any tag INTNET keep state +pass in on $wifi_if from any to any keep state + +block out on $ext_if from any to any +pass out quick on $ext_if tagged INTNET keep state +pass out on $ext_if from any to any port 80 keep state + +# tag incoming packets as they are redirected to spamd(8). use the tag +# to pass those packets through the packet filter. + +rdr on $ext_if inet proto tcp from <spammers> to port smtp \e + tag SPAMD -> 127.0.0.1 port spamd + +block in on $ext_if +pass in on $ext_if inet proto tcp tagged SPAMD keep state +.Ed +.Sh GRAMMAR +Syntax for +.Nm +in BNF: +.Bd -literal +line = ( option | pf-rule | nat-rule | binat-rule | rdr-rule | + antispoof-rule | altq-rule | queue-rule | anchor-rule | + trans-anchors | load-anchors | table-rule ) + +option = "set" ( [ "timeout" ( timeout | "{" timeout-list "}" ) ] | + [ "optimization" [ "default" | "normal" | + "high-latency" | "satellite" | + "aggressive" | "conservative" ] ] + [ "limit" ( limit-item | "{" limit-list "}" ) ] | + [ "loginterface" ( interface-name | "none" ) ] | + [ "block-policy" ( "drop" | "return" ) ] | + [ "require-order" ( "yes" | "no" ) ] + [ "fingerprints" filename ] ) + +pf-rule = action [ ( "in" | "out" ) ] + [ "log" | "log-all" ] [ "quick" ] + [ "on" ifspec ] [ route ] [ af ] [ protospec ] + hosts [ filteropt-list ] + +filteropt-list = filteropt-list filteropt | filteropt +filteropt = user | group | flags | icmp-type | icmp6-type | tos | + ( "keep" | "modulate" | "synproxy" ) "state" + [ "(" state-opts ")" ] | + "fragment" | "no-df" | "min-ttl" number | + "max-mss" number | "random-id" | "reassemble tcp" | + fragmentation | "allow-opts" | + "label" string | "tag" string | [ ! ] "tagged" string + "queue" "(" string | ( string [ [ "," ] string ] ) ")" + +nat-rule = [ "no" ] "nat" [ "pass" ] [ "on" ifspec ] [ af ] + [ protospec ] hosts [ "tag" string ] + [ "->" ( redirhost | "{" redirhost-list "}" ) + [ portspec ] [ pooltype ] [ "static-port" ] ] + +binat-rule = [ "no" ] "binat" [ "pass" ] [ "on" interface-name ] + [ af ] [ "proto" ( proto-name | proto-number ) ] + "from" address [ "/" mask-bits ] "to" ipspec + [ "tag" string ] + [ "->" address [ "/" mask-bits ] ] + +rdr-rule = [ "no" ] "rdr" [ "pass" ] [ "on" ifspec ] [ af ] + [ protospec ] hosts [ "tag" string ] + [ "->" ( redirhost | "{" redirhost-list "}" ) + [ portspec ] [ pooltype ] ] + +antispoof-rule = "antispoof" [ "log" ] [ "quick" ] + "for" ( interface-name | "{" interface-list "}" ) + [ af ] [ "label" string ] + +table-rule = "table" "<" string ">" [ tableopts-list ] +tableopts-list = tableopts-list tableopts | tableopts +tableopts = "persist" | "const" | "file" string | + "{" [ tableaddr-list ] "}" +tableaddr-list = tableaddr-list [ "," ] tableaddr-spec | tableaddr-spec +tableaddr-spec = [ "!" ] tableaddr [ "/" mask-bits ] +tableaddr = hostname | ipv4-dotted-quad | ipv6-coloned-hex | + interface-name | "self" + +altq-rule = "altq on" interface-name queueopts-list + "queue" subqueue +queue-rule = "queue" string [ "on" interface-name ] queueopts-list + subqueue + +anchor-rule = "anchor" string [ ( "in" | "out" ) ] [ "on" ifspec ] + [ af ] [ "proto" ] [ protospec ] [ hosts ] + +trans-anchors = ( "nat-anchor" | "rdr-anchor" | "binat-anchor" ) string + [ "on" ifspec ] [ af ] [ "proto" ] [ protospec ] [ hosts ] + +load-anchor = "load" anchorname:rulesetname "from" filename + +queueopts-list = queueopts-list queueopts | queueopts +queueopts = [ "bandwidth" bandwidth-spec ] | + [ "qlimit" number ] | [ "tbrsize" number ] | + [ "priority" number ] | [ schedulers ] +schedulers = ( cbq-def | priq-def | hfsc-def ) +bandwidth-spec = "number" ( "b" | "Kb" | "Mb" | "Gb" | "%" ) + +action = "pass" | "block" [ "return" ] | "scrub" +return = "drop" | "return" | "return-rst" [ "( ttl" number ")" ] | + "return-icmp" [ "(" icmpcode ["," icmp6code ] ")" ] | + "return-icmp6" [ "(" icmp6code ")" ] +icmpcode = ( icmp-code-name | icmp-code-number ) +icmp6code = ( icmp6-code-name | icmp6-code-number ) + +ifspec = ( [ "!" ] interface-name ) | "{" interface-list "}" +interface-list = [ "!" ] interface-name [ [ "," ] interface-list ] +route = "fastroute" | + ( "route-to" | "reply-to" | "dup-to" ) + ( routehost | "{" routehost-list "}" ) + [ pooltype ] +af = "inet" | "inet6" + +protospec = "proto" ( proto-name | proto-number | + "{" proto-list "}" ) +proto-list = ( proto-name | proto-number ) [ [ "," ] proto-list ] + +hosts = "all" | + "from" ( "any" | "no-route" | "self" | host | + "{" host-list "}" ) [ port ] [ os ] + "to" ( "any" | "no-route" | "self" | host | + "{" host-list "}" ) [ port ] + +ipspec = "any" | host | "{" host-list "}" +host = [ "!" ] ( address [ "/" mask-bits ] | "<" string ">" ) +redirhost = address [ "/" mask-bits ] +routehost = ( interface-name [ address [ "/" mask-bits ] ] ) +address = ( interface-name | "(" interface-name ")" | hostname | + ipv4-dotted-quad | ipv6-coloned-hex ) +host-list = host [ [ "," ] host-list ] +redirhost-list = redirhost [ [ "," ] redirhost-list ] +routehost-list = routehost [ [ "," ] routehost-list ] + +port = "port" ( unary-op | binary-op | "{" op-list "}" ) +portspec = "port" ( number | name ) [ ":" ( "*" | number | name ) ] +os = "os" ( os-name | "{" os-list "}" ) +user = "user" ( unary-op | binary-op | "{" op-list "}" ) +group = "group" ( unary-op | binary-op | "{" op-list "}" ) + +unary-op = [ "=" | "!=" | "<" | "<=" | ">" | ">=" ] + ( name | number ) +binary-op = number ( "<>" | "><" | ":" ) number +op-list = ( unary-op | binary-op ) [ [ "," ] op-list ] + +os-name = operating-system-name +os-list = os-name [ [ "," ] os-list ] + +flags = "flags" [ flag-set ] "/" flag-set +flag-set = [ "F" ] [ "S" ] [ "R" ] [ "P" ] [ "A" ] [ "U" ] [ "E" ] + [ "W" ] + +icmp-type = "icmp-type" ( icmp-type-code | "{" icmp-list "}" ) +icmp6-type = "icmp6-type" ( icmp-type-code | "{" icmp-list "}" ) +icmp-type-code = ( icmp-type-name | icmp-type-number ) + [ "code" ( icmp-code-name | icmp-code-number ) ] +icmp-list = icmp-type-code [ [ "," ] icmp-list ] + +tos = "tos" ( "lowdelay" | "throughput" | "reliability" | + [ "0x" ] number ) + +state-opts = state-opt [ [ "," ] state-opts ] +state-opt = ( "max" number ) | ( timeout ) + +fragmentation = [ "fragment reassemble" | "fragment crop" | + "fragment drop-ovl" ] + +timeout-list = timeout [ [ "," ] timeout-list ] +timeout = ( "tcp.first" | "tcp.opening" | "tcp.established" | + "tcp.closing" | "tcp.finwait" | "tcp.closed" | + "udp.first" | "udp.single" | "udp.multiple" | + "icmp.first" | "icmp.error" | + "other.first" | "other.single" | "other.multiple" | + "frag" | "interval" | + "adaptive.start" | "adaptive.end" ) number + +limit-list = limit-item [ [ "," ] limit-list ] +limit-item = ( "states" | "frags" ) number + +pooltype = ( "bitmask" | "random" | + "source-hash" [ ( hex-key | string-key ) ] | + "round-robin" ) + +subqueue = string | "{" queue-list "}" +queue-list = string [ [ "," ] string ] +cbq-def = "cbq" [ "(" cbq-opt [ [ "," ] cbq-opt ] ")" ] +priq-def = "priq" [ "(" priq-opt [ [ "," ] priq-opt ] ")" ] +hfsc-def = "hfsc" [ "(" hfsc-opt [ [ "," ] hfsc-opt ] ")" ] +cbq-opt = ( "default" | "borrow" | "red" | "ecn" | "rio" ) +priq-opt = ( "default" | "red" | "ecn" | "rio" ) +hfsc-opt = ( "default" | "red" | "ecn" | "rio" | + linkshare-sc | realtime-sc | upperlimit-sc ) +linkshare-sc = "linkshare" sc-spec +realtime-sc = "realtime" sc-spec +upperlimit-sc = "upperlimit" sc-spec +sc-spec = ( bandwidth-spec | + "(" bandwidth-spec number bandwidth-spec ")" ) +.Ed +.Sh FILES +.Bl -tag -width "/etc/protocols" -compact +.It Pa /etc/hosts +Host name database. +.It Pa /etc/pf.conf +Default location of the ruleset file. +.It Pa /etc/pf.os +Default location of OS fingerprints. +.It Pa /etc/protocols +Protocol name database. +.It Pa /etc/services +Service name database. +.It Pa /usr/share/pf +Example rulesets. +.El +.Sh SEE ALSO +.Xr icmp 4 , +.Xr icmp6 4 , +.Xr ip 4 , +.Xr ip6 4 , +.Xr pf 4 , +.Xr tcp 4 , +.Xr udp 4 , +.Xr hosts 5 , +.Xr pf.os 5 , +.Xr protocols 5 , +.Xr services 5 , +.Xr ftp-proxy 8 , +.Xr pfctl 8 , +.Xr pflogd 8 +.Sh HISTORY +The +.Nm +file format first appeared in +.Ox 3.0 . |