On Mon, Apr 29, 2019 at 07:48:35PM +0200, Alexandr Nedvedicky wrote:
> Hello,
>
> sorry for extra delay.
>
> </snip>
> > i have to say upfront that i dislike this idea of dividing options into
> > classes and then for every option, altering the text to something
> > unwieldy like:
> >
> > This runtime option...
> >
> > it reads very poorly, and this page is big enough as is without fleshing
> > it out more.
>
> thanks for that comment it helps to keep the manpage practical.
> I've killed that taxonomy (runtime vs. parser)
>
> </snip>
> >
> > you've suggested another idea, which is to add an option to display the
> > defaults. so i don;t really want to dig in to your diff until i see
> > whether this stuff is going in or not. but i think if it does, i'd like
> > to find another way to do it.
>
> let's forget that idea at least for now. I feel the plan is
> controversial. we can always revive that idea later.
>
> </snip>
> >
> > another possibility would be to just add a text such as "Can be Reset".
>
> that's the way I've opted for in my next diff below.
>
> thanks and
> regards
> sashan
>
hi.
this looks better, i think. i've inlined some comments on your text.
jmc
> --------8<---------------8<---------------8<------------------8<--------
> diff --git a/sbin/pfctl/pfctl.8 b/sbin/pfctl/pfctl.8
> index b7e941991ba..064308548d9 100644
> --- a/sbin/pfctl/pfctl.8
> +++ b/sbin/pfctl/pfctl.8
> @@ -198,7 +198,10 @@ 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 options back to default settings.
> +See
> +.Xr pf.conf 5 ,
> +section 'OPTIONS', for details.
probably just
See
.Xr pf.conf.5
.Sx OPTIONS
for details.
> .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..7b9f2356271 100644
> --- a/share/man/man5/pf.conf.5
> +++ b/share/man/man5/pf.conf.5
> @@ -1146,6 +1146,9 @@ 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
> .Ar level ,
> @@ -1165,6 +1168,11 @@ and
> These keywords correspond to the similar (LOG_) values specified to the
> .Xr syslog 3
> library routine.
> +The default value is
> +.Cm err .
> +.Xr pfctl 8
> +.Fl F Cm Reset
> +restores customized value back to default.
i want to be sure this text is grammatically correct. does Reset work on
a number of changed settings at once? if so, then "restores customized
values back to their defaults" or sth like that.
> .It Cm set Cm fingerprints Ar filename
> Load fingerprints of known operating systems from the given
> .Ar filename .
> @@ -1175,6 +1183,7 @@ 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.
...is
.Pa /etc/pf.os .
> .It Ic set Cm hostid Ar number
> The 32-bit hostid
> .Ar number
> @@ -1235,6 +1244,27 @@ 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:
"has the following defaults"?
> +.Bl -column table-entries PFR_KENTRY_HIWAT_SMALL platform_dependent
> +.It states Ta Dv PFSTATE_HIWAT Ta Pq 100000
> +.It tables Ta Dv PFR_KTABLE_HIWAT Ta Pq 1000
> +.It table-entries Ta Dv PFR_KENTRY_HIWAT Ta Pq 200000
> +.It table-entries Ta Dv PFR_KENTRY_HIWAT_SMALL Ta Pq 100000
> +.It frags Ta Dv NMBCLUSTERS/32 Ta Pq platform dependent
> +.El
> +.Pp
> +.Cm NMBCLUSTERS
> +defines the total number of packets, which can exist in system at any
...of packets which can exist in-system at any one time.
> +instance of the time.
> +Refer to
> +.Sy sys/arch/`uname -p`/param.h
> +to find out a value for your platform.
for system specific values.
> +.Xr pfctl 8
> +.Fl F Cm Reset
> +restores customized settings back to default.
> +.sp
what's the .sp for? if you want vertical blank space, use .Pp
> .It Ic set Cm loginterface Ar interface | Cm none
> Enable collection of packet and byte count statistics for the given
> interface or interface group.
> @@ -1251,6 +1281,13 @@ 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 .
> +.sp
> +.Xr pfctl 8
> +.Fl F Cm Reset
> +restores customized settings back to default.
> .It Ic set Cm optimization Ar environment
> Optimize state timeouts for one of the following network environments:
> .Pp
> @@ -1273,6 +1310,9 @@ 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
> @@ -1290,6 +1330,10 @@ instead of being dropped;
> the reassembled packet will have the
> .Dq dont-fragment
> bit cleared.
> +Default value is yes.
above you said "The default value is". here "Default value is". use one
text. i think "The default value is" is better.
> +.Xr pfctl 8
> +.Fl F Cm Reset
> +restores customized settings back to default.
> .It Ic set Cm ruleset-optimization Ar level
> .Bl -tag -width profile -compact
> .It Cm basic
> @@ -1339,6 +1383,10 @@ 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.
> +PF filters traffic on all interfaces by default.
> +.Xr pfctl 8
> +.Fl F Cm Reset
> +makes PF to filter on all interfaces again.
s/to//
> .It Ic set Cm state-defaults Ar state-option , ...
> The
> .Cm state-defaults
> @@ -1388,15 +1436,20 @@ The thresholds for entering and leaving syncookie
> mode can be specified using:
> set syncookies adaptive (start 25%, end 12%)
> .Ed
> .El
> +.Pp
> +.Xr pfctl 8
> +.Fl F Cm Reset
> +restores customized setting back to default.
> .It Ic set Cm timeout Ar variable value
> .Bl -tag -width "src.track" -compact
> .It Cm frag
> -Seconds before an unassembled fragment is expired.
> +Seconds before an unassembled fragment is expired (60 by default).
> .It Cm interval
> -Interval between purging expired states and fragments.
> +Interval between purging expired states and fragments (10 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).
i think this should read
The value is defined by the rule which creates state.
> .El
> .Pp
> When a packet matches a stateful connection, the seconds to live for the
> @@ -1408,13 +1461,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 seconds by default)
> The state after one endpoint sends an RST.
> -.It Cm tcp.closing
> +.It Cm tcp.closing No (900 seconds 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 seconds 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 +1476,9 @@ Increasing
> (and possibly
> .Cm tcp.closing )
> can prevent blocking of such packets.
> -.It Cm tcp.first
> +.It Cm tcp.first No (120 seconds by default)
> The state after the first packet.
> -.It Cm tcp.opening
> +.It Cm tcp.opening No (30 seconds by default)
> The state after the second packet but before both endpoints have
> acknowledged the connection.
> .El
> @@ -1434,15 +1487,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 No (10 seconds by default)
> The state after an ICMP error came back in response to an ICMP packet.
> -.It Cm icmp.first
> +.It Cm icmp.first No (20 seconds by default)
> The state after the first packet.
> -.It Cm udp.first
> +.It Cm udp.first No (60 seconds by default)
> The state after the first packet.
> -.It Cm udp.multiple
> +.It Cm udp.multiple No (60 seconds by default)
> The state if both hosts have sent packets.
> -.It Cm udp.single
> +.It Cm udp.single No (30 seconds 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 +1503,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 seconds by default)
> +.It Cm other.multiple No (60 seconds by default)
> +.It Cm other.single No (30 seconds 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
> @@ -1491,6 +1544,10 @@ set limit states 100000
> .Pp
> With 9000 state table entries, the timeout values are scaled to 50%
> (tcp.first 60, tcp.established 43200).
> +.Pp
> +.Xr pfctl 8
> +.Fl F Cm Reset
> +restores customized any timeout setting back to default.
this reads weird!
> .El
> .Sh QUEUEING
> Packets can be assigned to queues for the purpose of bandwidth
>
i'm fine with this direction, but oks from people who know this stuff
would be good.
jmc
