Hello, my oracle fellow pointed out [1] a PF documentation can be improved a bit, when it comes to newly introduced 'pfctl -FR' (a reset flush modifier). I've decided to make manpage changes in separate diff as I expect some discussion on how much detailed the manpage should be. The diff here is my proposal.
The patch at the end of email updates pfctl(8) and pf.conf(5) manpages. Since diff to pf.conf is fairly large and I'd like to focus at content first I'm also sending a plain text diff, which IMO is more convenient. .mdoc patch follows the plaintext. >From 'pfctl -FR' perspective the most important is to document whether particular option is parameter for PF driver (a.k.a. runtime option) or is just interpreted by parser as rules are being loaded. Documenting default values is just bonus, which I think might be useful for administrators. On the other hand it adds more work to keep pf.conf(5) up-to-date when doing changes in code. I full understand the trade here between being precise and up-to-date. thanks and regards sashan [1] https://marc.info/?l=openbsd-tech&m=155419736328573&w=2 --------8<---------------8<---------------8<------------------8<-------- plain-text-diff does not apply as patch @@ -749,44 +749,57 @@ can be used. OPTIONS - pf(4) may be tuned for various situations using the set command. + pf(4) may be tuned for various situations using the set command. Two + sorts of options should be distinguished. runtime options, which define + parameters for pf(4) driver and parser options, which fine-tune + interpretation of rules, while they are being loaded from file. The + runtime options may be restored to their default values using: + # pfctl -FReset + set block-policy drop | return - The block-policy option sets the default behaviour for the packet - block action: + The block-policy parser option sets the default behaviour for the + packet block action: drop Packet is silently dropped. 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. + The default value is drop. + set debug level - Set the debug level, which limits the severity of log messages - printed by pf(4). This should be a keyword from the following - ordered list (highest to lowest): emerg, alert, crit, err, - warning, notice, info, and debug. These keywords correspond to - the similar (LOG_) values specified to the syslog(3) library - routine. + The debug runtime option defines level, which limits the severity + of log messages printed by pf(4). This should be a keyword from + the following ordered list (highest to lowest): emerg, alert, + crit, err, warning, notice, info, and debug. These keywords + correspond to the similar (LOG_) values specified to the + syslog(3) library routine. The default value is err. set fingerprints filename - Load fingerprints of known operating systems from the given - filename. By default fingerprints of known operating systems are - automatically loaded from pf.os(5), 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. + Parser option loads fingerprints of known operating systems from + the given filename. By default fingerprints of known operating + systems are automatically loaded from pf.os(5), 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 + /etc/pf.os file. set hostid number - The 32-bit hostid number identifies this firewall's state table - entries to other firewalls in a pfsync(4) failover cluster. By - default the hostid is set to a pseudo-random value, however it - may be desirable to manually configure it, for example to more - easily identify the source of state table entries. The hostid - may be specified in either decimal or hexadecimal. + The runtime option specifies 32-bit hostid number, which + identifies this firewall's state table entries to other firewalls + in a pfsync(4) failover cluster. By default the hostid is set to + a pseudo-random value, however it may be desirable to manually + configure it, for example to more easily identify the source of + state table entries. The hostid may be specified in either + decimal or hexadecimal. The hostid option value does not get + changed by pfctl(8) -F Reset. set limit limit-item number Sets hard limits on the memory pools used by the packet filter. - See pool(9) for an explanation of memory pools. + See pool(9) for an explanation of memory pools. All limits are + runtime options. For example, to set the maximum number of entries in the memory pool used by state table entries (generated by pass rules which @@ -822,10 +835,24 @@ set limit { states 20000, frags 2000, src-nodes 2000 } + pf(4) uses defaults as follows: + + states PFSTATE_HIWAT (100000) + tables PFR_KTABLE_HIWAT (1000) + table-entries PFR_KENTRY_HIWAT (200000) + PFR_KENTRY_HIWAT_SMALL (100000) + frags NMBCLUSTERS/32 (platform dependent) + + NMBCLUSTERS defines the total number of packets, which can exist + in system at any instance of the time. Refer to sys/arch/`uname + -p`/param.h to find out a value for your platform. The number of + fragments should not exceed the number of NMBCLUSTERS. + + set loginterface interface | none - Enable collection of packet and byte count statistics for the - given interface or interface group. These statistics can be - viewed using: + Runtime option enables collection of packet and byte count + statistics for the given interface or interface group. These + statistics can be viewed using: # pfctl -s info @@ -838,9 +865,11 @@ set loginterface none + The default value is none. + set optimization environment - Optimize state timeouts for one of the following network - environments: + Runtime option hints how to adjust state timeouts for particular + network environment. There are following values possible: aggressive Aggressively expire connections. This can greatly reduce @@ -859,14 +888,18 @@ satellite Alias for high-latency. + The default value is normal. + set reassemble yes | no [no-df] - The reassemble option is used to enable or disable the reassembly - of fragmented packets, and can be set to yes (the default) or no. - If no-df is also specified, fragments with the "dont-fragment" - bit set are reassembled too, instead of being dropped; the - reassembled packet will have the "dont-fragment" bit cleared. + The reassemble runtime option is used to enable or disable the + reassembly of fragmented packets, and can be set to yes (the + default) or no. If no-df is also specified, fragments with the + "dont-fragment" bit set are reassembled too, instead of being + dropped; the reassembled packet will have the "dont-fragment" bit + cleared. set ruleset-optimization level + Parser option can be set by either three possible values: basic Enable basic ruleset optimization. This is the default behaviour. Basic ruleset optimization does four things to improve the performance of ruleset evaluations: @@ -894,17 +927,19 @@ pfctl(8), overriding the settings in pf.conf. set skip on ifspec - List interfaces for which packets should not be filtered. - Packets passing in or out on such interfaces are passed as if pf - was disabled, i.e. pf does not process them in any way. This can - be useful on loopback and other virtual interfaces, when packet - filtering is not desired and can have unexpected effects. ifspec - is only evaluated when the ruleset is loaded; interfaces created - later will not be skipped. + Runtime option lists interfaces for which packets should not be + filtered. Packets passing in or out on such interfaces are + passed as if pf was disabled, i.e. pf does not process them in + any way. This can be useful on loopback and other virtual + interfaces, when packet filtering is not desired and can have + unexpected effects. ifspec is only evaluated when the ruleset is + loaded; interfaces created later will not be skipped. PF filters + traffic on all interfaces by default. set state-defaults state-option, ... - The state-defaults option sets the state options for states - created from rules without an explicit keep state. For example: + The state-defaults parser option sets the state options for + states created from rules without an explicit keep state. For + example: set state-defaults pflow, no-sync @@ -916,17 +951,18 @@ default). set syncookies never | always | adaptive - When syncookies are active, pf will answer each and every - incoming TCP SYN with a syncookie SYNACK, without allocating any - resources. Upon reception of the client's ACK in response to the - syncookie SYNACK, pf will evaluate the ruleset and create state - if the ruleset permits it, complete the three way handshake with - the target host, and continue the connection with synproxy in - place. This allows pf to be resilient against large synflood - attacks, which could otherwise exhaust the state table. Due to - the blind answers to each and every SYN, syncookies share the - caveats of synproxy: seemingly accepting connections that will be - dropped later on. + Runtime option allows/prevents PF to use syncookies. When + syncookies are active, pf will answer each and every incoming TCP + SYN with a syncookie SYNACK, without allocating any resources. + Upon reception of the client's ACK in response to the syncookie + SYNACK, pf will evaluate the ruleset and create state if the + ruleset permits it, complete the three way handshake with the + target host, and continue the connection with synproxy in place. + This allows pf to be resilient against large synflood attacks, + which could otherwise exhaust the state table. Due to the blind + answers to each and every SYN, syncookies share the caveats of + synproxy: seemingly accepting connections that will be dropped + later on. never pf will never send syncookie SYNACKs (the default). always pf will always send syncookie SYNACKs. @@ -940,10 +976,16 @@ set syncookies adaptive (start 25%, end 12%) set timeout variable value - frag Seconds before an unassembled fragment is expired. - interval Interval between purging expired states and fragments. + + All timeouts are runtime options. + frag Seconds before an unassembled fragment is expired (60 + secs by default). + interval Interval between purging expired states and fragments + (10 secs by default). src.track Length of time to retain a source tracking entry after - the last state expires. + the last state expires (0 by default, which means + there is no global limit, value is defined by rule, + which creates state). When a packet matches a stateful connection, the seconds to live for the connection will be updated to that of the protocol and @@ -952,56 +994,56 @@ may improve the performance of the firewall at the risk of dropping valid idle connections. - tcp.closed + tcp.closed (90 secs. by default) The state after one endpoint sends an RST. - tcp.closing + tcp.closing (900 secs. by default) The state after the first FIN has been sent. - tcp.established + tcp.established (24 hours by default). The fully established state. - tcp.finwait + tcp.finwait (45 secs. by default) 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 tcp.finwait (and possibly tcp.closing) can prevent blocking of such packets. - tcp.first + tcp.first (120 secs. by default) The state after the first packet. - tcp.opening + tcp.opening (30 secs. by default) The state after the second packet but before both endpoints have acknowledged the connection. ICMP and UDP are handled in a fashion similar to TCP, but with a much more limited set of states: - icmp.error + icmp.error (10 secs. by default) The state after an ICMP error came back in response to an ICMP packet. - icmp.first + icmp.first (20 secs. by default) The state after the first packet. - udp.first + udp.first (60 secs. by default) The state after the first packet. - udp.multiple + udp.multiple (60 secs. by default) The state if both hosts have sent packets. - udp.single + udp.single (30 secs. by default) The state if the source host sends more than one packet but the destination host has never sent one back. Other protocols are handled similarly to UDP: - other.first - other.multiple - other.single + other.first (60 secs. by default) + other.multiple (60 secs. by default) + other.single (30 secs. by default) Timeout values can be reduced adaptively as the number of state table entries grows. - adaptive.end + adaptive.end (60000 states by default) 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). - adaptive.start + adaptive.start (120000 states by default) 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) / --------8<---------------8<---------------8<------------------8<-------- diff --git a/sbin/pfctl/pfctl.8 b/sbin/pfctl/pfctl.8 index b7e941991ba..aa24a5de561 100644 --- a/sbin/pfctl/pfctl.8 +++ b/sbin/pfctl/pfctl.8 @@ -198,7 +198,7 @@ Flush the tables. .It Fl F Cm osfp Flush the passive operating system fingerprints. .It Fl F Cm Reset -Reset limits, timeouts and options back to default settings. +Reset limits, timeouts and other runtime options back to default settings. .It Fl F Cm all Flush all of the above. .El diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5 index 247ceef40a5..ab6b8c0447e 100644 --- a/share/man/man5/pf.conf.5 +++ b/share/man/man5/pf.conf.5 @@ -1129,12 +1129,24 @@ can be used. .Xr pf 4 may be tuned for various situations using the .Ic set -command. +command. Two sorts of options should be distinguished. +.Em runtime +options, which define parameters for +.Xr pf 4 +driver and +.Em parser +options, which fine-tune interpretation of rules, while +they are being loaded from file. The runtime options +may be restored to their default values using: +.Pp +.Dl # pfctl -FReset +.Pp + .Bl -tag -width Ds .It Ic set Cm block-policy drop | return The .Cm block-policy -option sets the default behaviour for the packet +parser option sets the default behaviour for the packet .Ic block action: .Pp @@ -1146,8 +1158,13 @@ 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 +The default value is +.Cm drop . .It Ic set Cm debug Ar level -Set the debug +The +.Cm debug +runtime option defines .Ar level , which limits the severity of log messages printed by .Xr pf 4 . @@ -1164,9 +1181,10 @@ and .Cm debug . These keywords correspond to the similar (LOG_) values specified to the .Xr syslog 3 -library routine. +library routine. The default value is +.Cm err . .It Cm set Cm fingerprints Ar filename -Load fingerprints of known operating systems from the given +Parser option loads fingerprints of known operating systems from the given .Ar filename . By default fingerprints of known operating systems are automatically loaded from @@ -1174,23 +1192,29 @@ loaded from 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. +ruleset finishes loading. The default location for fingerprints is +/etc/pf.os file. .It Ic set Cm hostid Ar number -The 32-bit hostid -.Ar number -identifies this firewall's state table entries to other firewalls +The runtime option specifies 32-bit hostid +.Ar number , +which identifies this firewall's state table entries to other firewalls in a .Xr pfsync 4 failover cluster. By default the hostid is set to a pseudo-random value, however it may be desirable to manually configure it, for example to more easily identify the source of state table entries. -The hostid may be specified in either decimal or hexadecimal. +The hostid may be specified in either decimal or hexadecimal. The +.Cm hostid +option value does not get changed by +.Xr pfctl 8 +.Fl F +.Cm Reset . .It Ic set Cm limit Ar limit-item number Sets hard limits on the memory pools used by the packet filter. See .Xr pool 9 -for an explanation of memory pools. +for an explanation of memory pools. All limits are runtime options. .Pp For example, to set the maximum number of entries in the memory pool used by state table @@ -1235,9 +1259,28 @@ Various limits can be combined on a single line: .Bd -literal -offset indent set limit { states 20000, frags 2000, src-nodes 2000 } .Ed +.Pp +.Xr pf 4 +uses defaults as follows: +.Bd -literal -offset indent +states PFSTATE_HIWAT (100000) +tables PFR_KTABLE_HIWAT (1000) +table-entries PFR_KENTRY_HIWAT (200000) + PFR_KENTRY_HIWAT_SMALL (100000) +frags NMBCLUSTERS/32 (platform dependent) +.Ed +.Pp +.Cm NMBCLUSTERS +defines the total number of packets, which can exist in system at any +instance of the time. Refer to +.Sy sys/arch/`uname -p`/param.h +to find out a value for your platform. The number of fragments should +not exceed the number of +.Cm NMBCLUSTERS . + .It Ic set Cm loginterface Ar interface | Cm none -Enable collection of packet and byte count statistics for the given -interface or interface group. +Runtime option enables collection of packet and byte count statistics for the +given interface or interface group. These statistics can be viewed using: .Pp .Dl # pfctl -s info @@ -1251,8 +1294,12 @@ collects statistics on the interface named dc0: One can disable the loginterface using: .Pp .Dl set loginterface none +.Pp +The default value is +.Cm none . .It Ic set Cm optimization Ar environment -Optimize state timeouts for one of the following network environments: +Runtime option hints how to adjust state timeouts for particular +network environment. There are following values possible: .Pp .Bl -tag -width Ds -compact .It Cm aggressive @@ -1273,11 +1320,14 @@ Suitable for almost all networks. Alias for .Cm high-latency . .El +.Pp +The default value is +.Cm normal . .It Ic set Cm reassemble yes | no Op Cm no-df The .Cm reassemble -option is used to enable or disable the reassembly of fragmented packets, -and can be set to +runtime option is used to enable or disable the reassembly of fragmented +packets, and can be set to .Cm yes (the default) or .Cm no . @@ -1291,6 +1341,7 @@ the reassembled packet will have the .Dq dont-fragment bit cleared. .It Ic set Cm ruleset-optimization Ar level +Parser option can be set by either three possible values: .Bl -tag -width profile -compact .It Cm basic Enable basic ruleset optimization. @@ -1331,18 +1382,18 @@ Optimization can also be set as a command-line argument to overriding the settings in .Nm . .It Ic set Cm skip on Ar ifspec -List interfaces for which packets should not be filtered. -Packets passing in or out on such interfaces are passed as if pf was -disabled, i.e. pf does not process them in any way. -This can be useful on loopback and other virtual interfaces, when -packet filtering is not desired and can have unexpected effects. +Runtime option lists interfaces for which packets should not be filtered. +Packets passing in or out on such interfaces are passed as if pf was disabled, +i.e. pf does not process them in any way. This can be useful on loopback and +other virtual interfaces, when packet filtering is not desired and can have +unexpected effects. .Ar ifspec is only evaluated when the ruleset is loaded; interfaces created -later will not be skipped. +later will not be skipped. PF filters traffic on all interfaces by default. .It Ic set Cm state-defaults Ar state-option , ... The .Cm state-defaults -option sets the state options for states created from rules +parser option sets the state options for states created from rules without an explicit .Cm keep state . For example: @@ -1360,7 +1411,7 @@ States are bound to an interface. States can match packets on any interfaces (the default). .El .It Ic set Cm syncookies never | always | adaptive -When +Runtime option allows/prevents PF to use syncookies. When .Cm syncookies are active, pf will answer each and every incoming TCP SYN with a syncookie SYNACK, without allocating any resources. @@ -1389,14 +1440,17 @@ set syncookies adaptive (start 25%, end 12%) .Ed .El .It Ic set Cm timeout Ar variable value +.Pp +All timeouts are runtime options. .Bl -tag -width "src.track" -compact .It Cm frag -Seconds before an unassembled fragment is expired. +Seconds before an unassembled fragment is expired (60 secs by default). .It Cm interval -Interval between purging expired states and fragments. +Interval between purging expired states and fragments (10 secs by default). .It Cm src.track Length of time to retain a source tracking entry after the last state -expires. +expires (0 by default, which means there is no global limit, value is +defined by rule, which creates state). .El .Pp When a packet matches a stateful connection, the seconds to live for the @@ -1408,13 +1462,13 @@ Tuning these values may improve the performance of the firewall at the risk of dropping valid idle connections. .Pp .Bl -tag -width Ds -compact -.It Cm tcp.closed +.It Cm tcp.closed No (90 secs. by default) The state after one endpoint sends an RST. -.It Cm tcp.closing +.It Cm tcp.closing No (900 secs. by default) The state after the first FIN has been sent. -.It Cm tcp.established +.It Cm tcp.established No (24 hours by default). The fully established state. -.It Cm tcp.finwait +.It Cm tcp.finwait No (45 secs. by default) 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. @@ -1423,9 +1477,9 @@ Increasing (and possibly .Cm tcp.closing ) can prevent blocking of such packets. -.It Cm tcp.first +.It Cm tcp.first No (120 secs. by default) The state after the first packet. -.It Cm tcp.opening +.It Cm tcp.opening No (30 secs. by default) The state after the second packet but before both endpoints have acknowledged the connection. .El @@ -1434,15 +1488,15 @@ ICMP and UDP are handled in a fashion similar to TCP, but with a much more limited set of states: .Pp .Bl -tag -width Ds -compact -.It Cm icmp.error +.It Cm icmp.error (10 secs. by default) The state after an ICMP error came back in response to an ICMP packet. -.It Cm icmp.first +.It Cm icmp.first (20 secs. by default) The state after the first packet. -.It Cm udp.first +.It Cm udp.first (60 secs. by default) The state after the first packet. -.It Cm udp.multiple +.It Cm udp.multiple (60 secs. by default) The state if both hosts have sent packets. -.It Cm udp.single +.It Cm udp.single (30 secs. by default) The state if the source host sends more than one packet but the destination host has never sent one back. .El @@ -1450,21 +1504,21 @@ host has never sent one back. Other protocols are handled similarly to UDP: .Pp .Bl -tag -width xxxx -compact -.It Cm other.first -.It Cm other.multiple -.It Cm other.single +.It Cm other.first No (60 secs. by default) +.It Cm other.multiple No (60 secs. by default) +.It Cm other.single No (30 secs. by default) .El .Pp Timeout values can be reduced adaptively as the number of state table entries grows. .Pp .Bl -tag -width Ds -compact -.It Cm adaptive.end +.It Cm adaptive.end No (60000 states by default) 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). -.It Cm adaptive.start +.It Cm adaptive.start No (120000 states by default) When the number of state entries exceeds this value, adaptive scaling begins. All timeout values are scaled linearly with factor
