diff --git a/share/man/man5/pf.conf.5 b/share/man/man5/pf.conf.5 --- 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 June 21, 2023 +.Dd October 17, 2023 .Dt PF.CONF 5 .Os .Sh NAME @@ -386,7 +386,9 @@ .Ed .Pp sets the maximum number of entries in the memory pool used for fragment -reassembly (generated by +reassembly (generated by the +.Ar set reassemble +option or .Ar scrub rules) to 20000. Using @@ -480,6 +482,29 @@ .Bd -literal -offset indent set optimization aggressive .Ed +.It Ar set 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 +.Cm yes +or +.Cm no . +If +.Cm no-df +is also specified, fragments with the +.Dq dont-fragment +bit set are reassembled too, +instead of being dropped; +the reassembled packet will have the +.Dq dont-fragment +bit cleared. +The default value is +.Cm no . +.Pp +This option is ignored if there are pre-FreeBSD 14 +.Cm scrub +rules present. .It Ar set block-policy The .Ar block-policy @@ -753,19 +778,21 @@ to match the rule. Inverse tag matching can also be done by specifying the ! operator before the tagged keyword. +.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: +Traffic normalization is a broad umbrella term +for aspects of the packet filter which deal with +verifying packets, packet fragments, spoofed traffic, +and other irregularities. +.Ss Scrub +Scrub involves sanitising packet content in such a way +that there are no ambiguities in packet interpretation on the receiving side. +It is invoked with the +.Cm scrub +option, added to filter rules. +.Pp +Parameters are specified enclosed in parentheses. +At least one of the following parameters must be specified: .Bl -tag -width xxxx .It Ar no-df Clears the @@ -824,22 +851,8 @@ for predictable values generated by many hosts. This option only applies to 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. -This is the default behaviour unless no fragment reassemble is specified. -.It Ar no fragment reassemble -Do not reassemble fragments. .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 @@ -891,6 +904,41 @@ .Pp For example, .Bd -literal -offset indent +match in all scrub (no-df random-id max-mss 1440) +.Ed +.Ss Scrub ruleset (pre-FreeBSD 14) +In order to maintain compatibility with older releases of FreeBSD +.Ar scrub +rules can also be specified in their own ruleset. +In such case they are invoked with the +.Ar scrub +directive. +If there are such rules present they determine packet reassembly behaviour. +When no such rules are present the option +.Ar set reassembly +takes precedence. +The +.Ar scrub +rules can take all parameters specified above for a +.Ar scrub +option of filter rules and 2 more parameters controlling fragment reassembly: +.Bl -tag -width xxxx +.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. +This is the default behaviour unless no fragment reassemble is specified. +.It Ar no fragment reassemble +Do not reassemble fragments. +.El +.Pp +For example, +.Bd -literal -offset indent scrub in on $ext_if all fragment reassemble .Ed .Pp @@ -902,6 +950,14 @@ works in the packet filter (see below). This mechanism should be used when it is necessary to exclude specific packets from broader scrub rules. +.Pp +.Ar scrub +rules in the +.Ar scrub +ruleset are evaluated for every packet before stateful filtering. +This means excessive usage of them will cause performance penalty. +.Ar scrub reassemble tcp +rules must not have the direction (in/out) specified. .Sh QUEUEING with ALTQ The ALTQ system is currently not available in the GENERIC kernel nor as loadable modules. @@ -1479,28 +1535,21 @@ .Ar block and .Ar pass -rules in that parameters are set every time a packet matches the rule, not only +rules in that parameters are set for every rule a packet matches, not only on the last matching rule. For the following parameters, this means that the parameter effectively becomes "sticky" until explicitly overridden: .Ar queue , .Ar dnpipe , -.Ar dnqueue +.Ar dnqueue , +.Ar rtable , +.Ar scrub . .It Ar pass The packet is passed; state is created unless the .Ar no state option is specified. -.It Ar match -Action is unaltered, the previously matched rule's action still matters. -Match rules apply queue and rtable assignments for every matched packet, -subsequent matching pass or match rules can overwrite the assignment, -if they don't specify a queue or an rtable, respectively, the previously -set value remains. -Additionally, match rules can contain log statements; the is logging done -for each and every matching match rule, so it is possible to log a single -packet multiple times. .El .Pp By default @@ -2579,6 +2628,8 @@ to filter on things such as TCP ports or to perform NAT. .Pp Besides the use of +.Ar set reassemble +option or .Ar scrub rules as described in .Sx TRAFFIC NORMALIZATION @@ -2587,7 +2638,11 @@ 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. +rule applies to a fragment or +.Ar set reassemble +is set to +.Cm no +, 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. @@ -2620,11 +2675,13 @@ .Pp In most cases, the benefits of reassembly outweigh the additional memory cost, and it's recommended to use +.Ar set reassemble +option or .Ar scrub -rules to reassemble -all fragments via the +rules with the .Ar fragment reassemble -modifier. +modifier to reassemble +all fragments. .Pp The memory allocated for fragment caching can be limited using .Xr pfctl 8 . @@ -2989,12 +3046,12 @@ # (157.161.48.183, the only routable address) # and the private network is 10.0.0.0/8, for which we are doing NAT. +# Reassemble incoming traffic +set reassemble yes + # 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