[src/netbsd-8]: src/usr.sbin/npf/npfctl Sync the following with -current, wit...

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

details:   https://anonhg.NetBSD.org/src/rev/aa7f0805e4f6
branches:  netbsd-8
changeset: 851966:aa7f0805e4f6
user:      martin <martin%NetBSD.org@localhost>
date:      Sat Sep 01 06:19:12 2018 +0000

description:
Sync the following with -current, with minor modifications as the
"[ map-flags ]" feature is not available in netbsd-8, requested by
maxv in ticket #1001:

        usr.sbin/npf/npfctl/npf.conf.5  1.49,1.50(partly),1.51-1.70 (via patch)

Remove workaround for ancient HTML generation code.

 -

npfctl: add support for the 'no-ports' flag in the 'map' statements.
This allows us to create a NAT policy without the port translation.

 -

Remove superfluous Pp.

 -

First pass at editing this manual.
Add a link to the NPF documentation website and refer to it.
Switch the multiple structural elements to a list to make it easier to read and
extend.
Clarify tables, re-order so all terms are before the example.
Clarify obtaining addresses per family
Move the minimum requirement for a default group to the group section.

 -

Add missing El. Remove trailing whitespace.

 -

Enlighten the "Procedures" section. In particular document the "no-df"
option. Also replace "normalisation" -> "normalization", to match the
name of the rule.

 -

Add quotes around the option names, to match the actual npf conf.

 -

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.

 -

Document the "flags" keyword.

 -

Improve the "Map" section a little.

 -

Improve wording.

 -

Replace () by [] in tcp-flags.

Fix proc-opts, the value is optional, noted by he@.

 -

Replace "rproc"->"proc" in the grammar (spotted by he@), and slightly
reword.

 -

Add missing quote in static-rule, it causes man-k.org (and other tools)
to wrongly highlight the grammar.

 -

Add the values of "algo" in the grammar, and use # as comment marker for
man-k.org (and others) not to highlight things in an incorrect way.

 -

Document ALGs.

 -

Improve the "Map" section.

 -

Add missing -width; remove unnecessary .Pp.

 -

Clarify the "Groups" section.

 -

should be port-opts

 -

"interface" already contains "var-name", so don't mention it in "filt-addr",
that's redundant

 -

rename net-seg -> map-seg, and document it

diffstat:

 usr.sbin/npf/npfctl/npf.conf.5 |  304 +++++++++++++++++++++++++++++-----------
 1 files changed, 219 insertions(+), 85 deletions(-)

diffs (truncated from 507 to 300 lines):

diff -r 98ac2c5832ec -r aa7f0805e4f6 usr.sbin/npf/npfctl/npf.conf.5
--- a/usr.sbin/npf/npfctl/npf.conf.5    Sat Sep 01 06:04:16 2018 +0000
+++ b/usr.sbin/npf/npfctl/npf.conf.5    Sat Sep 01 06:19:12 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: npf.conf.5,v 1.48 2017/01/20 08:48:14 wiz Exp $
+.\"    $NetBSD: npf.conf.5,v 1.48.4.1 2018/09/01 06:19:12 martin Exp $
 .\"
 .\" Copyright (c) 2009-2017 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd January 19, 2017
+.Dd August 31, 2018
 .Dt NPF.CONF 5
 .Os
 .Sh NAME
@@ -40,31 +40,32 @@
 .Pp
 This manual page serves as a reference for editing
 .Nm .
-Please refer to the official NPF documentation for comprehensive and
+Please refer to the official NPF documentation website for comprehensive and
 in-depth information.
 .Pp
-There are multiple structural elements
+There are multiple structural elements that
 .Nm
-may contain:
-.Cd variable
-and
-.Cd table
-definitions (with or without content), abstraction
-.Cd groups ,
-packet filtering
-.Cd rules ,
-.Cd map
-rules for address translation and
-.Cd procedure
-definitions to call on filtered packets.
-The minimal
-.Nm
-must contain a mandatory
-.Cd default group .
+may contain, such as:
+.Bl -bullet -offset indent
+.It
+variables
+.It
+table definitions (with or without content)
+.It
+abstraction groups
+.It
+packet filtering rules
+.It
+map rules for address translation
+.It
+application level gateways
+.It
+procedure definitions to call on filtered packets.
+.El
 .Sh SYNTAX
 .Ss Variables
-Variables are specified using the dollar ($) sign, which is used both
-in definitions and uses of a variable.
+Variables are specified using the dollar ($) sign, which is used for both
+definition and referencing of a variable.
 Variables are defined by assigning a value to them as follows:
 .Bd -literal
 $var1 = 10.0.0.1
@@ -79,33 +80,34 @@
 and interfaces.
 .Ss Tables
 Tables are specified using a name between angle brackets
-\*[Lt] and \*[Gt].
+< and >.
 The following is an example of table definition:
 .Bd -literal
 table <black> type hash dynamic
 .Pp
 .Ed
-Currently, tables support three storage types: "hash", "tree", or "cdb".
-They can also be "dynamic" or static i.e. loaded from the specified file.
+Currently, tables support three data storage types: "hash", "tree", or "cdb".
+Tables can also be set as containing "dynamic" or "static" data i.e. loaded from
+ a specified file.
+Tables of type "hash" and "cdb" can only contain IP addresses.
+Only static data can be used with a storage type of "cdb".
 .Pp
-The file should contain a list of IP addresses and/or networks in the form of:
+The specified file should contain a list of IP addresses and/or networks in the
+form of:
 .Bd -literal
 10.0.0.0/24
 10.1.1.1
 .Ed
-.Pp
-Tables of type "hash" and "cdb" can only contain IP addresses.
-Also, the latter can only be static.
 .Ss Interfaces
 Interfaces can be specified as the values of the variables:
-.Pp
 .Bd -literal
 $pub_if_list = { inet4(wm0), inet4(wm1) }
 .Ed
 .Pp
-In the context of filtering, an interface provides a list of its
-all IP addresses, including IPv4 and IPv6.
-Specific interface addresses can be selected by the family, e.g.:
+In the context of filtering, an interface provides a list of all its IP
+addresses, both IPv4 and IPv6.
+Specific addresses configured on an interface can also be selected by family,
+e.g.:
 .Bd -literal
 $pub_if4 = inet4(wm0)
 $pub_if46 = { inet4(wm0), inet6(wm0) }
@@ -124,17 +126,29 @@
 Marking the interface as ``down'' has no effect, i.e. all addresses will
 remain present.
 .Pp
-The dynamic address list represents both the IPv4 and IPv6 addresses,
-therefore the
+A dynamic address list represents both the IPv4 and IPv6 addresses configured on
+an interface.
+The
 .Cd family
-keyword can be used in combination to make the filtering more narrow.
+keyword can be used in combination of a filtering rule to be explicit.
 .Ss Groups
+NPF requires that all rules be defined within groups.
+Groups can be thought of as higher level rules which can contain subrules.
 Groups may have the following options: name, interface, and direction.
-They are defined in the following form:
+Packets matching group criteria are passed to the ruleset of that group.
+If a packet does not match any group, it is passed to the
+.Cd default group .
+The
+.Cd default group
+must always be defined.
 .Pp
+Example of configuration:
 .Bd -literal
 group "my-name" in on wm0 {
-       # List of rules
+       # List of rules, for packets received on wm0
+}
+group default {
+       # List of rules, for the other packets
 }
 .Ed
 .Ss Rules
@@ -143,13 +157,36 @@
 or
 .Cd block
 a packet depending on packet header information, transit direction and
-interface it arrives 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 \\
@@ -174,7 +211,7 @@
 Fragments are not selectable since NPF always reassembles packets
 before further processing.
 .Ss Stateful
-Stateful packet inspection is enabled using
+Stateful packet inspection is enabled using the
 .Cd stateful
 or
 .Cd stateful-ends
@@ -186,18 +223,40 @@
 In both cases, a full TCP state tracking is performed for TCP connections
 and a limited tracking for message-based protocols (UDP and ICMP).
 .Pp
+The
+.Cd flags
+keyword can be used in conjunction with the
+.Cd stateful
+keyword to match the packets against specific TCP flags, according to
+the following syntax:
+.Bl -tag -width flagsXX -offset indent
+.It flags Ar match[/mask]
+.El
+.Pp
+Where
+.Ar match
+is the set of TCP flags to be matched, out of the
+.Ar mask
+set, both sets being represented as a string combination of: S (SYN),
+A (ACK), F (FIN), R (RST). The flags that are not present in
+.Ar mask
+are ignored.
+.Pp
 By default, a stateful rule implies SYN-only flag check ("flags S/SAFR")
 for the TCP packets.
 It is not advisable to change this behavior; however,
-it can be overridden with the
+it can be overridden with the aforementioned
 .Cd flags
 keyword.
 .Ss Map
 Network Address Translation (NAT) is expressed in a form of segment mapping.
-The translation may be dynamic (stateful) or static (stateless).
+The translation may be
+.Cd dynamic
+(stateful) or
+.Cd static
+(stateless).
 The following mapping types are available:
-.Pp
-.Bl -tag -width <-> -compact
+.Bl -tag -width <-> -offset indent
 .It Pa ->
 outbound NAT (translation of the source)
 .It Pa <-
@@ -206,17 +265,56 @@
 bi-directional NAT (combination of inbound and outbound NAT)
 .El
 .Pp
-The following would translate the source to the IP address specified
-by the $pub_ip for the packets on the interface $ext_if.
+The following would translate the source (10.1.1.0/24) to the IP address
+specified by $pub_ip for the packets on the interface $ext_if.
 .Bd -literal
 map $ext_if dynamic 10.1.1.0/24 -> $pub_ip
 .Ed
 .Pp
+Several NAT algorithms are available, and can be chosen using the
+.Cd algo
+keyword.
+By default, NPF will use the NAPT algorithm.
+The other available algorithms are:
+.Bl -tag -width Xnpt66XX -offset indent
+.It npt66
+IPv6-to-IPv6 network prefix translation (NPTv6).
+.El
+.Pp
 Translations are implicitly filtered by limiting the operation to the
 network segments specified, that is, translation would be performed only
-on packets originating from 10.1.1.0/24 network.
+on packets originating from the 10.1.1.0/24 network.
 Explicit filter criteria can be specified using "pass <criteria>" as
 an additional option of the mapping.
+.Ss Application Level Gateways
+Certain application layer protocols are not compatible with NAT and require
+translation outside layers 3 and 4.
+Such translation is performed by packet filter extensions called
+Application Level Gateways (ALGs).
+.Pp
+NPF supports the following ALGs:
+.Bl -tag -width XicmpXX -offset indent
+.It icmp
+ICMP ALG.
+Allows to find an active connection by looking at the ICMP payload, and to
+perform NAT translation of the ICMP payload.
+Applies to IPv4 and IPv6.
+.El
+.Pp
+The ALGs are built-in, unless NPF is used as kernel module, in which case
+they come as kernel modules too.
+In that case, the ALG kernel modules can be autoloaded through the
+configuration, using the
+.Cd alg
+keyword.
+.Pp
+For example:
+.Bd -literal
+alg "icmp"