diff options
Diffstat (limited to 'share/man/man5/pf.conf.5')
| -rw-r--r-- | share/man/man5/pf.conf.5 | 199 |
1 files changed, 136 insertions, 63 deletions
diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5 index a9fd9e8b29e1..da02f10aac01 100644 --- a/share/man/man5/pf.conf.5 +++ b/share/man/man5/pf.conf.5 @@ -27,7 +27,7 @@ .\" ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" -.Dd May 29, 2025 +.Dd August 28, 2025 .Dt PF.CONF 5 .Os .Sh NAME @@ -92,14 +92,22 @@ keyword, for example: include "/etc/pf/sub.filter.conf" .Ed .Sh MACROS -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 +A macro is defined with a command of the form +.Ar name Ns = Ns Ar value . +The macro +.Ar name +can contain letters, digits, and underscores and cannot be a reserved word +(for example, .Ar pass , .Ar in , +or .Ar out ) . -Macros are not expanded inside quotes. +Within unquoted arguments, the string +.Pf $ Ar name +is later expanded to +.Ar value . +Ranges of network addresses used in macros that will be expanded in lists +later on must be quoted with additional simple quotes. .Pp For example, .Bd -literal -offset indent @@ -107,6 +115,11 @@ ext_if = \&"kue0\&" all_ifs = \&"{\&" $ext_if lo0 \&"}\&" pass out on $ext_if from any to any pass in on $ext_if proto tcp from any to any port 25 + +usr_lan_range = "'192.0.2.0/24'" +srv_lan_range = "'198.51.100.0 - 198.51.100.255'" +nat_ranges = \&"{\&" $usr_lan_range $srv_lan_range \&"}\&" +nat on $ext_if from $nat_ranges to any -> ($ext_if) .Ed .Sh TABLES Tables are named structures which can hold a collection of addresses and @@ -260,6 +273,10 @@ 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. +Alternatively, these values may be adjusted collectively +in a manner suitable for a specific environment using +.Cm set optimization +(see above). .Pp .Bl -tag -width xxxx -compact .It Ar tcp.first @@ -267,6 +284,9 @@ The state after the first packet. .It Ar tcp.opening The state after the second packet but before both endpoints have acknowledged the connection. +.It Ar tcp.tsdiff +Maximum allowed time difference between RFC 1323 compliant packet timestamps. +30 seconds by default. .It Ar tcp.established The fully established state. .It Ar tcp.closing @@ -354,11 +374,11 @@ 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 +set timeout { adaptive.start 60000, adaptive.end 120000 } +set limit states 100000 .Ed .Pp -With 9000 state table entries, the timeout values are scaled to 50% +With 90000 state table entries, the timeout values are scaled to 50% (tcp.first 60, tcp.established 43200). .It Ar set loginterface Enable collection of packet and byte count statistics for the given @@ -385,50 +405,37 @@ See .Xr zone 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 +Limits can be set on the following: +.Bl -tag -width pktdelay_pkts +.It Cm states +Set the maximum number of entries in the memory pool used by state table +entries (those generated by .Ar pass rules which do not specify -.Ar no state ) -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 the -.Ar set reassemble -option or -.Ar scrub -rules) to 20000. -Using -.Bd -literal -offset indent -set limit src-nodes 2000 -.Ed -.Pp -sets the maximum number of entries in the memory pool used for tracking +.Cm no state ) . +The default is 100000. +.It Cm src-nodes +Set the maximum number of entries in the memory pool used for tracking source IP addresses (generated by the .Ar sticky-address and .Ar src.track -options) to 2000. -Using -.Bd -literal -offset indent -set limit table-entries 100000 -.Ed -.Pp -sets the limit on the overall number of addresses that can be stored -in tables to 100000. +options). +The default is 10000. +.It Cm table-entries +Set the number of addresses that can be stored in tables. +The default is 200000. +.It Cm anchors +Set the number of anchors that can exist. +The default is 512. +.It Cm eth-anchors +Set the number of anchors that can exist. +The default is 512. +.El .Pp -Various limits can be combined on a single line: +Multiple limits can be combined on a single line: .Bd -literal -offset indent -set limit { states 20000, frags 20000, src-nodes 2000 } +set limit { states 20000, frags 2000, src-nodes 2000 } .Ed .It Ar set ruleset-optimization .Bl -tag -width xxxxxxxx -compact @@ -535,6 +542,9 @@ an ICMP UNREACHABLE is returned for blocked UDP packets, and all other packets are silently dropped. .El .Pp +The default value is +.Cm drop . +.Pp For example: .Bd -literal -offset indent set block-policy return @@ -659,6 +669,8 @@ 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. +The default location for fingerprints is +.Pa /etc/pf.os . .Pp For example: .Pp @@ -719,7 +731,7 @@ Unlike for layer 3 traffic the packet is always silently dropped. The packet is passed; no state is created for layer 2 traffic. .El -.Sh PARAMETERS +.Ss Parameters applicable to layer 2 rules 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. @@ -843,7 +855,15 @@ modifier to ensure unique IP identifiers. .It Ar min-ttl Aq Ar number Enforces a minimum TTL for matching IP packets. .It Ar max-mss Aq Ar number -Enforces a maximum MSS for matching TCP packets. +Reduces the maximum segment size (MSS) +on TCP SYN packets to be no greater than +.Ar number . +This is sometimes required in scenarios where the two endpoints +of a TCP connection are not able to carry similar sized packets +and the resulting mismatch can lead to packet fragmentation or loss. +Note that setting the MSS this way can have undesirable effects, +such as interfering with the OS detection features of +.Xr pf 4 . .It Xo Ar set-tos Aq Ar string .No \*(Ba Aq Ar number .Xc @@ -1375,7 +1395,7 @@ part of the new destination address according to the specified subnet. It is possible to embed a complete IPv4 address into an IPv6 address using a network prefix of /96 or smaller. .Pp -When a destination address is not specified it is assumed that the host +When a destination address is not specified, it is assumed that the host part is 32-bit long. For IPv6 to IPv4 translation this would mean using only the lower 32 bits of the original IPv6 destination address. @@ -1472,11 +1492,7 @@ A .Ar rdr-to opion may cause the source port to be modified if doing so avoids a conflict with an existing connection. -A random source port in the range 50001-65535 is chosen in this case; to -avoid excessive CPU consumption, the number of searches for a free port is -limited by the -.Va net.pf.rdqr_srcport_rewrite_tries -sysctl. +A random source port in the range 50001-65535 is chosen in this case. Port numbers are never translated with a .Ar binat-to option. @@ -1743,7 +1759,7 @@ handles state tracking. See .Sx STATEFUL TRACKING OPTIONS below for further details. -.Sh PARAMETERS +.Ss 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. @@ -2039,6 +2055,21 @@ connections: block out proto { tcp, udp } all pass out proto { tcp, udp } all user { < 1000, dhartmei } .Ed +.Pp +The example below permits users with uid between 1000 and 1500 +to open connections: +.Bd -literal -offset indent +block out proto tcp all +pass out proto tcp from self user { 999 >< 1501 } +.Ed +.Pp +The +.Sq \&: +operator, which works for port number matching, does not work for +.Cm user +and +.Cm group +match. .It Xo Ar flags Aq Ar a .Pf / Ns Aq Ar b .No \*(Ba / Ns Aq Ar b @@ -2099,10 +2130,10 @@ options, or scrubbed with will also not be recoverable from intermediate packets. Such connections will stall and time out. .It Xo Ar icmp-type Aq Ar type -.Ar code Aq Ar code +.Ar Op code Aq Ar code .Xc .It Xo Ar icmp6-type Aq Ar type -.Ar code Aq Ar code +.Ar Op code Aq Ar code .Xc This rule only applies to ICMP or ICMPv6 packets with the specified type and code. @@ -2209,6 +2240,31 @@ directive occurs only at configuration file parse time, not during runtime. .It Ar ridentifier Aq Ar number Add an identifier (number) to the rule, which can be used to correlate the rule to pflog entries, even after ruleset updates. +.It Cm max-pkt-rate Ar number Ns / Ns Ar seconds +Measure the rate of packets matching the rule and states created by it. +When the specified rate is exceeded, the rule stops matching. +Only packets in the direction in which the state was created are considered, +so that typically requests are counted and replies are not. +For example, +to pass up to 100 ICMP packets per 10 seconds: +.Bd -literal -offset indent +block in proto icmp +pass in proto icmp max-pkt-rate 100/10 +.Ed +.Pp +When the rate is exceeded, all ICMP is blocked until the rate falls below +100 per 10 seconds again. +.Pp +.It Ar max-pkt-size Aq Ar number +Limit each packet to be no more than the specified number of bytes. +This includes the IP header, but not any layer 2 header. +.It Ar once +Create a one shot rule. +The first matching packet marks the rule as expired. +Expired rules are skipped and hidden, unless +.Xr pfctl 8 +is used in debug or verbose mode. +.Pp .It Xo Ar queue Aq Ar queue .No \*(Ba ( Aq Ar queue , .Aq Ar queue ) @@ -2434,7 +2490,13 @@ NAT address and port. This feature implements "full-cone" NAT behavior. .El .Pp -Additionally, the +Additionally, options +.Ar sticky-address +and +.Ar prefer-ipv6-nexthop +can be specified to influence how IP addresses selected from pools. +.Pp +The .Ar sticky-address option can be specified to help ensure that multiple connections from the same source are mapped to the same redirection address. @@ -2450,6 +2512,14 @@ beyond the lifetime of the states, increase the global options with See .Sx STATEFUL TRACKING OPTIONS for more ways to control the source tracking. +.Pp +The +.Ar prefer-ipv6-nexthop +option allows for IPv6 addresses to be used as the nexthop +for IPv4 packets routed with the +.Ar route-to +rule option. If a table is used with IPv4 and IPv6 addresses, first the IPv6 addresses +will be used in round-robin fashion, then IPv4 addresses. .Sh STATE MODULATION Much of the security derived from TCP is attributable to how well the initial sequence numbers (ISNs) are chosen. @@ -2533,6 +2603,7 @@ will not work if .Xr pf 4 operates on a .Xr bridge 4 . +Also they act on incoming SYN packets only. .Pp Example: .Bd -literal -offset indent @@ -2742,8 +2813,8 @@ 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; +There are three problems: an attacker can trivially craft packets to +appear as any operating system; 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. @@ -3070,7 +3141,7 @@ rule can also contain a filter ruleset in a brace-delimited block. In that case, no separate loading of rules into the anchor is required. Brace delimited blocks may contain rules or other brace-delimited blocks. -When an anchor is populated this way the anchor name becomes optional. +When an anchor is populated this way, the anchor name becomes optional. .Bd -literal -offset indent anchor "external" on $ext_if { block @@ -3379,9 +3450,11 @@ filteropt = user | group | flags | icmp-type | icmp6-type | "tos" tos | [ "(" state-opts ")" ] | "fragment" | "no-df" | "min-ttl" number | "set-tos" tos | "max-mss" number | "random-id" | "reassemble tcp" | - fragmentation | "allow-opts" | + fragmentation | "allow-opts" | "once" | "label" string | "tag" string | [ "!" ] "tagged" string | + "max-pkt-rate" number "/" seconds | "set prio" ( number | "(" number [ [ "," ] number ] ")" ) | + "max-pkt-size" number | "queue" ( string | "(" string [ [ "," ] string ] ")" ) | "rtable" number | "probability" number"%" | "prio" number | "dnpipe" ( number | "(" number "," number ")" ) | @@ -3527,7 +3600,7 @@ fragmentation = [ "fragment reassemble" ] timeout-list = timeout [ [ "," ] timeout-list ] timeout = ( "tcp.first" | "tcp.opening" | "tcp.established" | - "tcp.closing" | "tcp.finwait" | "tcp.closed" | + "tcp.closing" | "tcp.finwait" | "tcp.closed" | "tcp.tsdiff" | "sctp.first" | "sctp.opening" | "sctp.established" | "sctp.closing" | "sctp.closed" | "udp.first" | "udp.single" | "udp.multiple" | @@ -3541,7 +3614,7 @@ limit-item = ( "states" | "frags" | "src-nodes" ) number pooltype = ( "bitmask" | "random" | "source-hash" [ ( hex-key | string-key ) ] | - "round-robin" ) [ sticky-address ] + "round-robin" ) [ sticky-address | prefer-ipv6-nexthop ] subqueue = string | "{" queue-list "}" queue-list = string [ [ "," ] string ] |