[src/trunk]: src/usr.sbin/npf/npfctl re-work the description part of the man ...

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

details:   https://anonhg.NetBSD.org/src/rev/0d65cbc00da2
branches:  trunk
changeset: 781764:0d65cbc00da2
user:      spz <spz%NetBSD.org@localhost>
date:      Fri Sep 28 18:36:02 2012 +0000

description:
re-work the description part of the man page, as discussed with rmind@

diffstat:

 usr.sbin/npf/npfctl/npf.conf.5 |  114 +++++++---------------------------------
 1 files changed, 21 insertions(+), 93 deletions(-)

diffs (138 lines):

diff -r 367ae9f943a9 -r 0d65cbc00da2 usr.sbin/npf/npfctl/npf.conf.5
--- a/usr.sbin/npf/npfctl/npf.conf.5    Fri Sep 28 06:07:05 2012 +0000
+++ b/usr.sbin/npf/npfctl/npf.conf.5    Fri Sep 28 18:36:02 2012 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: npf.conf.5,v 1.16 2012/09/26 21:58:27 rmind Exp $
+.\"    $NetBSD: npf.conf.5,v 1.17 2012/09/28 18:36:02 spz Exp $
 .\"
 .\" Copyright (c) 2009-2012 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -36,101 +36,27 @@
 .\" -----
 .Sh DESCRIPTION
 .Nm
-is the default configuration file for NPF packet filter.
-It can contain definitions, grouped rules, rule procedures,
-translation policies, and tables.
-.Ss Definitions
-Definitions are general purpose keywords which can be used in the
-ruleset to make it more flexible and easier to manage.
-Most commonly, definitions are used to define one of the following:
-IP addresses, networks, ports, or interfaces.
-Definitions can contain multiple elements.
-.Ss Groups
-Having one huge ruleset for all interfaces or directions might be
-inefficient; therefore, NPF requires that all rules be defined within groups.
-Groups can be thought of as higher level rules which have subrules.
-The main properties of a group are its interface and traffic 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 default group.
-The default group must always be defined.
-.Ss Rules
-Rules, which are the main part of NPF configuration, describe the criteria
-used to inspect and make decisions about packets.
-Currently, NPF supports filtering on the following criteria: interface,
-traffic direction, protocol, IP address or network, TCP/UDP port
-or range, TCP flags, and ICMP type/code.
-Supported actions are blocking or passing the packet.
+is the default configuration file for the NPF packet filter.
 .Pp
-Each rule has a priority, which is set according to its order in the ruleset.
-Rules defined first are accordingly inspected first.
-All rules in the group are inspected sequentially, and the last matching
-dictates the action to be taken.
-Rules, however, may be explicitly marked as final.
-In such cases, processing stops after encountering the first matching rule
-marked as final.
-If there is no matching rule in the custom group, then rules in the default
-group will be inspected.
-.Pp
-Stateful filtering is supported using the "stateful" keyword.
-In such cases, state (a session) is created and any further packets
-of the connection are tracked.
-Packets in backwards stream, after having been confirmed to belong to
-the same connection, are passed without ruleset inspection.
-Rules may have associated rule procedures (described in a later section),
-which are applied for all packets of a connection.
+The minimal
+.Nm
+consists of the mandatory
+.Cd default group.
 .Pp
-Definitions (prefixed with "$") and tables (specified by an ID within
-"\*[Lt]\*[Gt]" marks) can be used in the filter options of rules.
-.Ss Rule procedures and normalisation
-Rule procedures are provided to perform packet transformations and various
-additional procedures on the packets.
-It should be noted that rule procedures are applied for the connections,
-that is, both for packets which match the rule and for further packets
-of the connection, which are passed without ruleset inspection.
-Currently, two facilities are supported:
-traffic normalisation and packet logging.
-Packet normalisation has the following functionality:
-IP ID randomisation, IP_DF flag cleansing, TCP minimum TTL enforcement,
-and maximum MSS enforcement ("MSS clamping").
-If a matching rule is going to drop the packet, normalisation functions
-are not performed.
-Packet logging is performed both in packet passing and blocking cases.
-Note that the logging interface has to be created manually, using
-.Xr ifconfig 8
-routine, for example:
+.Nm
+may also contain variable and
+.Cd table
+definitions (with or without content), packet filtering
+.Cd rule
+and address translation
+.Cd map
+instructions and
+.Cd procedure
+definitions to call with select packets.
 .Pp
-ifconfig npflog0 create
-.Ss Network address translation
-Rules for address translation can be added.
-Translation is performed on the specified interface, assigning the specified
-address of said interface.
-Currently, three types of translation are supported:
-Network Address Port Translation (NAPT) - a regular NAT,
-also known as "outbound NAT";
-Port forwarding (redirection) - also known as "inbound NAT";
-Bi-directional NAT - a combination of inbound and outbound NAT.
-.Pp
-Minimal filtering criteria on local network and destination are provided.
-Note that address translation implies routing, therefore IP forwarding
-is required to be enabled:
-net.inet.ip.forwarding = 1.
-See
-.Xr sysctl 7
-for more details.
-.Ss Tables
-Certain configurations might use very large sets of IP addresses or change
-sets frequently.
-Storing large IP sets in the configuration file or performing frequent
-reloads can have a significant performance cost.
-.Pp
-In order to achieve high performance, NPF has tables.
-NPF tables provide separate storage designed for large IP sets and frequent
-updates without reloading the entire ruleset.
-Tables can be managed dynamically or loaded from a separate file, which
-is useful for large static tables.
-There are two types of storage: "tree" (red-black tree is used) and
-"hash".
-.\" -----
+This man page is supposed to serve as a reference for editing npf.conf.
+For in-depth information about the behaviour of NPF please
+consult the documentation in /usr/share/doc/npf.
 .Sh GRAMMAR
 The following is a non-formal BNF-like definition of the grammar.
 The definition is simplified and is intended to be human readable,
@@ -198,6 +124,8 @@
 control device
 .It Pa /etc/npf.conf
 default configuration file
+.It Pa /usr/share/examples/npf
+directory containing further examples
 .El
 .\" -----
 .Sh EXAMPLES