Index: share/man/man5/pf.conf.5 =================================================================== RCS file: /cvs/src/share/man/man5/pf.conf.5,v diff -u -p -r1.602 pf.conf.5 --- share/man/man5/pf.conf.5 15 Apr 2024 14:06:52 -0000 1.602 +++ share/man/man5/pf.conf.5 19 Jun 2025 00:02:29 -0000 @@ -2148,6 +2148,143 @@ Example: .Bd -literal -offset indent pass in proto tcp from any to any port www synproxy state .Ed +.Ss State Pools +State pools provide a mechanism to limit the number of states created, +or the rate of state creation, +by a set of rules. +State pools are configured and loaded with the main ruleset, but +can be used by rules in any anchor. +The overall number of states is still subject to the limit set with +.Cm set limit states , +but limits on states for a subset of rules can be provided with +state pools. +.Pp +A state pool is configured with the following statement: +.Pp +.Bl -tag -width xxxx -compact +.It Cm state pool Ar id +Each state pool is identified by a number between 1 and 255. +.El +.Pp +State pools support the following configuration: +.Pp +.Bl -tag -width xxxx -compact +.It Cm limit Ar number +Specify the maximum number of states. +This configuration is required. +.It Cm rate Ar number Ns / Ns Ar seconds +Limit the rate at which states can be created over a time interval. +The connection rate is an approximation calculated as a moving +average. +.It Cm description Ar string +Provide a descriptive label for the state pool. +.El +.Pp +Pass rules can specify a state pool using the +.Cm state pool Ar id +state tracking option, as described in +.Sx Stateful Tracking Options . +.Pp +An example use case for a state pool is to limit the number of +connections allowed to a service that is accessible via multiple +protocols, e.g. a DNS server that can be accessed by both TCP and +UDP on port 53, DNS-over-TLS on TCP port 853, and DNS-over-HTTPS +on TCP port 443 can be limited to 1000 concurrent connections: +.Pp +.Bd -literal -offset indent -compact +state pool 1 limit 1000 + +pass in proto { tcp udp } to port domain keep state (state pool 1) +pass in proto tcp to port { 853 443 } keep state (state pool 1) +.Ed +.Ss Source Pools +Source pools apply limits on the number of states, +or the rate of state creation, +for connections coming from a source address or network for a set +of rules. +Source pools are configured and loaded with the main ruleset, but +can be used by rules in any anchor. +The overall number of states is still subject to the limit set with +.Cm set limit states , +but limits on states for a subset of source addresses and rules can +be provided with source pools. +.Pp +Source address entries in source pools are created on demand, +and are used to account for the states created for each source +address or network. +A source pool specifies the maximum number of source address entries +it will track, and can be configured to mask bits in network prefixes +to have source entries cover larger portions of the address space +if needed. +.Pp +A source pool is configured with the following statement: +.Pp +.Bl -tag -width xxxx -compact +.It Cm source pool Ar id +Each source pool is identified by a number between 1 and 255. +.El +.Pp +Source pools support the following configuration: +.Pp +.Bl -tag -width xxxx -compact +.It Cm limit Ar number +Specify the maximum number of source address entries. +This configuration is required. +.It Cm states Ar number +Specify the maximum number of states for each source address entry. +This configuration is required. +.It Cm rate Ar number Ns / Ns Ar seconds +Limit the rate at which states can be created by each source address +entry over a time interval. +The connection rate is an approximation calculated as a moving +average. +.It Cm inet mask Ar prefixlen +Mask IPv4 source addresses using the prefix length specified with +.Ar prefixlen +when creating an address entry. +The default IPv4 prefix length is 32 bits. +.It Cm inet6 mask Ar prefixlen +Mask IPv6 source addresses using the prefix length specified with +.Ar prefixlen +when creating an address entry. +The default IPv6 prefix length is 128 bits. +.It Cm table < Ns Ar table Ns > Cm above Ar hwm Op Cm below Ar lwm +Add the address to the specified +.Ar table +when the number of states goes above the +.Ar hwm +high water mark. +The address will be removed from the table when the number of states +drops below the +.Ar lwm +low water mark. +The default low water mark is 0. +.It Cm description Ar string +Provide a descriptive label for the source pool. +.El +.Pp +Pass rules can specify a source pool using the +.Cm source pool Ar id +state tracking option, as described in +.Sx Stateful Tracking Options . +.Pp +An example use for a source pool is the mitigation of denial of +service caused by the exhaustion of firewall resources by network +or port scans from outside the network. +The states created by any one scanner from any one source address +can be limited to avoid impacting other sources. +Below, up to 10000 IPv4 hosts and IPv6 /64 networks from the external +network are each limited to a maximum of 1000 connections, and are +rate limited to creating 100 states over a 10 second interval: +.Pp +.Bd -literal -offset indent -compact +source pool 1 limit 10000 \e + states 1000 rate 100/10 \e + inet6 mask 64 + +block in on egress +pass in on egress keep state (source pool 1) +.Ed .Ss Stateful Tracking Options A number of options related to stateful tracking can be applied on a per-rule basis. @@ -2192,6 +2329,21 @@ or .Cm synproxy state . For ICMP, this option allows states to be created from replies, not just requests. +.It Cm state pool Ar id +Capacity in the state pool specified by +.Ar id +must be available for the rule to match and create a state. +See +.Sx State Pools +above. +.It Cm source pool Ar id +Capacity in the source pool specified by +.Ar id +must be available for the rule to match and +create a state. +See +.Sx Source Pools +above. .It Ar timeout seconds Changes the .Ar timeout Index: sbin/pfctl/pfctl.8 =================================================================== RCS file: /cvs/src/sbin/pfctl/pfctl.8,v diff -u -p -r1.186 pfctl.8 --- sbin/pfctl/pfctl.8 3 Jun 2025 18:25:46 -0000 1.186 +++ sbin/pfctl/pfctl.8 19 Jun 2025 00:02:29 -0000 @@ -443,6 +443,26 @@ When used together with interface statistics are also shown. .Fl i can be used to select an interface or a group of interfaces. +.It Cm pools +Show information about state pools. +If +.Fl R Ar id +is specified as well, +only the state pool identified by +.Ar id +is shown. +.It Cm Pools +Show information about source pools. +If +.Fl R Ar id +is specified as well, +only the state pool identified by +.Ar id +is shown. +If +.Fl v +is specified, +the address entries for the source pools are shown too. .It Cm all Show all of the above, except for the lists of interfaces and operating system fingerprints.