[src/trunk]: src/usr.sbin/npf/npfctl Improve markup.

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

details:   https://anonhg.NetBSD.org/src/rev/7b2fd8441de9
branches:  trunk
changeset: 836003:7b2fd8441de9
user:      uwe <uwe%NetBSD.org@localhost>
date:      Fri Sep 21 09:42:18 2018 +0000

description:
Improve markup.

diffstat:

 usr.sbin/npf/npfctl/npf.conf.5 |  278 ++++++++++++++++++++++------------------
 1 files changed, 154 insertions(+), 124 deletions(-)

diffs (truncated from 483 to 300 lines):

diff -r 61f5d2301729 -r 7b2fd8441de9 usr.sbin/npf/npfctl/npf.conf.5
--- a/usr.sbin/npf/npfctl/npf.conf.5    Fri Sep 21 08:43:18 2018 +0000
+++ b/usr.sbin/npf/npfctl/npf.conf.5    Fri Sep 21 09:42:18 2018 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: npf.conf.5,v 1.77 2018/09/21 07:22:26 maxv Exp $
+.\"    $NetBSD: npf.conf.5,v 1.78 2018/09/21 09:42:18 uwe Exp $
 .\"
 .\" Copyright (c) 2009-2017 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -46,7 +46,8 @@
 There are multiple structural elements that
 .Nm
 may contain, such as:
-.Bl -bullet -offset indent
+.Pp
+.Bl -bullet -offset indent -compact
 .It
 variables
 .It
@@ -64,40 +65,52 @@
 .El
 .Sh SYNTAX
 .Ss Variables
-Variables are specified using the dollar ($) sign, which is used for both
+Variables are specified using the dollar
+.Pq Li $
+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
-.Ed
+.Pp
+.Dl $var1 = 10.0.0.1
 .Pp
 A variable may also be defined as a set:
-.Bd -literal
-$var2 = { 10.0.0.1, 10.0.0.2 }
-.Ed
+.Pp
+.Dl $var2 = { 10.0.0.1, 10.0.0.2 }
 .Pp
 Common variable definitions are for IP addresses, networks, ports,
 and interfaces.
 .Ss Tables
 Tables are specified using a name between angle brackets
-< and >.
+.Sq Li <
+and
+.Sq Li > .
 The following is an example of table definition:
-.Bd -literal
-table <black> type hash dynamic
+.Pp
+.Dl table <black> type hash dynamic
 .Pp
-.Ed
-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".
+Currently, tables support three data storage types:
+.Cm hash,
+.Cm tree ,
+or
+.Cm cdb .
+Tables can also be set as containing
+.Cm dynamic
+or
+.Cm static
+data i.e. loaded from a specified file.
+Tables of type
+.Dq hash
+and
+.Dq cdb
+can only contain IP addresses.
+Only static data can be used with a storage type of
+.Dq cdb .
 .Pp
 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
+form of
+.Li 10.1.1.1
+or
+.Li 10.0.0.0/24
 .Ss Interfaces
 In NPF, an interface can be referenced directly by using its name, or can be
 passed to an extraction function which will return a list of IP addresses
@@ -113,26 +126,26 @@
 load, whereas with a dynamic list NPF will capture the runtime list of
 addresses, reflecting any changes to the interface, including the attach and
 detach.
-Note that with a dynamic list, marking the interface as ``down'' has no effect,
+Note that with a dynamic list, bringing the interface down has no effect,
 all addresses will remain present.
 .Pp
 Three functions exist, to extract addresses from an interface with a chosen
 list type and IP address type:
-.Bl -tag -width Xifaddrs()XX -offset indent
-.It Fn inet4
-Static list, IPv4 addresses.
-.It Fn inet6
-Static list, IPv6 addresses.
-.It Fn ifaddrs
-Dynamic list, both IPv4 and IPv6.
+.Bl -tag -width "Fn ifaddrs interface" -offset indent
+.It Fn inet4 interface
+Static list.  IPv4 addresses.
+.It Fn inet6 interface
+Static list.  IPv6 addresses.
+.It Fn ifaddrs interface
+Dynamic list.  Both IPv4 and IPv6.
 The
-.Cd family
-keyword can be used in combination of a filtering rule to explicitly select
+.Cm family
+keyword of a filtering rule can be used in combination to explicitly select
 an IP address type.
 .El
 .Pp
 Example of configuration:
-.Bd -literal
+.Bd -literal -offset indent
 $var1 = inet4(wm0)
 $var2 = ifaddrs(wm0)
 group default {
@@ -144,11 +157,14 @@
 }
 .Ed
 .Pp
-In the above example, $var1 is the static list of IPv4 addresses configured
-on wm0, and $var2 is the dynamic list of all the IPv4 and IPv6 addresses
-configured on wm0.
+In the above example,
+.Li $var1
+is the static list of IPv4 addresses configured
+on wm0, and
+.Li $var2
+is the dynamic list of all the IPv4 and IPv6 addresses configured on wm0.
 The first three rules are equivalent, because with the
-.Cd block ... on <interface>
+.Li Ic block Ar "..." Cm on Li < Ns Ar interface Ns Li >
 syntax, NPF expects a direct reference to an interface, and therefore does
 not consider the extraction functions.
 The fourth and fifth rules are equivalent, for the same reason.
@@ -158,13 +174,14 @@
 Groups may have the following options: name, interface, and direction.
 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 .
+.Dv default
+group.
 The
-.Cd default group
-must always be defined.
+.Dv default
+group must always be defined.
 .Pp
 Example of configuration:
-.Bd -literal
+.Bd -literal -offset indent
 group "my-name" in on wm0 {
        # List of rules, for packets received on wm0
 }
@@ -174,21 +191,21 @@
 .Ed
 .Ss Rules
 With a rule statement NPF is instructed to
-.Cd pass
+.Ic pass
 or
-.Cd block
+.Ic block
 a packet depending on packet header information, transit direction and
 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
+.Cm 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
 The
-.Cd proto
+.Cm proto
 keyword can be used to filter packets by layer 4 protocol (TCP, UDP, ICMP
 or other).
 Its parameter should be a protocol number or its symbolic name,
@@ -196,38 +213,48 @@
 .Pa /etc/protocols
 file.
 This keyword can additionally have protocol-specific options, such as
-.Cd flags .
+.Cm flags .
 .Pp
 The
 .Cd flags
 keyword can be used to match the packets against specific TCP flags,
 according to the following syntax:
-.Bl -tag -width protoXX -offset indent
-.It proto tcp flags Ar match[/mask]
-.El
+.Pp
+.Dl Ic proto Cm tcp flags Ar match Ns Li [/ Ns Ar mask Ns Li ]
 .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
+set, both sets being represented as a string combination of:
+.Sq Cm S
+(SYN),
+.Sq Cm A
+(ACK),
+.Sq Cm F
+(FIN), and
+.Sq Cm R
+(RST).
+The flags that are not present in
 .Ar mask
 are ignored.
 .Pp
 To notify the sender of a blocking decision, three
-.Cd return
+.Cm return
 options can be used in conjunction with a
-.Cd block
+.Ic 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
+.Bl -tag -width "Cm return-icmp" -offset indent
+.It Cm return
+Behaves as
+.Cm return-rst
+or
+.Cm return-icmp ,
+depending on whether the packet being blocked is TCP or UDP.
+.It Cm return-rst
 Return a TCP RST message, when the packet being blocked is a TCP packet.
 Applies to IPv4 and IPv6.
-.It return-icmp
+.It Cm return-icmp
 Return an ICMP UNREACHABLE message, when the packet being blocked is a UDP packet.
 Applies to IPv4 and IPv6.
 .El
@@ -239,26 +266,28 @@
 A rule can also instruct NPF to create an entry in the state table when
 passing the packet or to apply a procedure to the packet (e.g. "log").
 .Pp
-A "fully-featured" rule would for example be:
-.Bd -literal
-pass stateful in final family inet4 proto tcp flags S/SA \\
-       from $source port $sport to $dest port $dport apply "someproc"
+A
+.Dq fully-featured
+rule would for example be:
+.Bd -literal -offset indent
+pass stateful in final family inet4 proto tcp flags S/SA \e
+        from $source port $sport to $dest port $dport    \e
+        apply \*qsomeproc\*q
 .Ed
 .Pp
 Alternatively, NPF supports
 .Xr pcap-filter 7
 syntax, for example:
-.Bd -literal
-block out final pcap-filter "tcp and dst 10.1.1.252"
-.Ed
+.Pp
+.Dl block out final pcap-filter \*qtcp and dst 10.1.1.252\*q
 .Pp
 Fragments are not selectable since NPF always reassembles packets
 before further processing.
 .Ss Stateful
 Stateful packet inspection is enabled using the
-.Cd stateful
+.Cm stateful
 or
-.Cd stateful-ends
+.Cm stateful-ends
 keywords.
 The former creates a state which is uniquely identified by a 5-tuple (source
 and destination IP addresses, port numbers and an interface identifier).
@@ -267,60 +296,61 @@
 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