[src/trunk]: src/usr.sbin/npf/npfctl Improve the "Rules" section: better expl...

[maxv <maxv%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/abdd8ef0767e
branches:  trunk
changeset: 365461:abdd8ef0767e
user:      maxv <maxv%NetBSD.org@localhost>
date:      Thu Aug 16 09:21:00 2018 +0000

description:
Improve the "Rules" section: better explain the "final" keyword (it is
the same as PF's "quick", so use the same wording), and document the
"return" options.

While here simplify the man code, suggested by wiz.

diffstat:

 usr.sbin/npf/npfctl/npf.conf.5 |  41 ++++++++++++++++++++++++++++++-----------
 1 files changed, 30 insertions(+), 11 deletions(-)

diffs (66 lines):

diff -r 9d4e7ea768aa -r abdd8ef0767e usr.sbin/npf/npfctl/npf.conf.5
--- a/usr.sbin/npf/npfctl/npf.conf.5    Thu Aug 16 08:51:53 2018 +0000
+++ b/usr.sbin/npf/npfctl/npf.conf.5    Thu Aug 16 09:21:00 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: npf.conf.5,v 1.55 2018/08/16 08:51:53 maxv Exp $
+.\"    $NetBSD: npf.conf.5,v 1.56 2018/08/16 09:21:00 maxv Exp $
 .\"
 .\" Copyright (c) 2009-2017 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -147,13 +147,36 @@
 or
 .Cd block
 a packet depending on packet header information, transit direction and
-the interface it arrived on, either immediately upon match (keyword
-.Cd final )
-or using the last match.
-The rule can also instruct NPF to create an entry in the state table
+the interface it arrived on, either immediately upon match or using the
+last match.
+.Pp
+If a packet matches a rule which has the
+.Cd final
+option set, this rule is considered the last matching rule, and
+evaluation of subsequent rules is skipped.
+Otherwise, the last matching rule is used.
+.Pp
+A rule can also instruct NPF to create an entry in the state table
 when passing the packet, to notify the sender when blocking it, and
 to apply a procedure to the packet (e.g. "log") in either case.
 .Pp
+To notify the sender of a blocking decision, three
+.Cd return
+options can be used in conjunction with a
+.Cd block
+rule:
+.Bl -tag -width Xreturn-icmpXX -offset indent
+.It return
+Behaves as return-rst or return-icmp, depending on whether the packet
+being blocked is TCP or UDP.
+.It return-rst
+Return a TCP RST message, when the packet being blocked is a TCP packet.
+Applies to IPv4 and IPv6.
+.It return-icmp
+Return an ICMP UNREACHABLE message, when the packet being blocked is a UDP packet.
+Applies to IPv4 and IPv6.
+.El
+.Pp
 A "fully-featured" rule would for example be:
 .Bd -literal
 pass stateful in final family inet4 proto tcp flags S/SA \\
@@ -253,13 +276,9 @@
 .Bl -tag -width XXmin-ttlXXvalueXX -offset indent
 .It Dq random-id
 Randomize the IPv4 ID parameter.
-.It Dq min-ttl Xo
-.Ar value
-.Xc
+.It Do min-ttl Dc Ar value
 Enforce a minimum value for the IPv4 Time To Live (TTL) parameter.
-.It Dq max-mss Xo
-.Ar value
-.Xc
+.It Do max-mss Dc Ar value
 Enforce a maximum value for the MSS on TCP packets.
 .It Dq no-df
 Remove the Don't Fragment (DF) flag from IPv4 packets.