[src/trunk]: src/usr.sbin/npf/npfctl npf.conf(5): add syntax section and a fi...

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

details:   https://anonhg.NetBSD.org/src/rev/d40eaa99087d
branches:  trunk
changeset: 781772:d40eaa99087d
user:      rmind <rmind%NetBSD.org@localhost>
date:      Sat Sep 29 19:50:03 2012 +0000

description:
npf.conf(5): add syntax section and a first cut describing the structural
elements.  Some improvements and fixes from spz@.

diffstat:

 usr.sbin/npf/npfctl/npf.conf.5 |  117 +++++++++++++++++++++++++++++++++++-----
 1 files changed, 100 insertions(+), 17 deletions(-)

diffs (150 lines):

diff -r 68b1c697871c -r d40eaa99087d usr.sbin/npf/npfctl/npf.conf.5
--- a/usr.sbin/npf/npfctl/npf.conf.5    Sat Sep 29 14:19:43 2012 +0000
+++ b/usr.sbin/npf/npfctl/npf.conf.5    Sat Sep 29 19:50:03 2012 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: npf.conf.5,v 1.17 2012/09/28 18:36:02 spz Exp $
+.\"    $NetBSD: npf.conf.5,v 1.18 2012/09/29 19:50:03 rmind Exp $
 .\"
 .\" Copyright (c) 2009-2012 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 September 26, 2012
+.Dd September 29, 2012
 .Dt NPF.CONF 5
 .Os
 .Sh NAME
@@ -38,25 +38,108 @@
 .Nm
 is the default configuration file for the NPF packet filter.
 .Pp
+This manual page serves as a reference for editing
+.Nm .
+Please refer to the official NPF documentation for comprehensive and
+in-depth information.
+.Pp
+There are multiple structural elements
+.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
-consists of the mandatory
+must contain a mandatory
 .Cd default group.
+.Sh SYNTAX
+.Ss Variables
+Variables are specified using the dollar ($) sign, which is used both
+in definitions and uses of a variable.
+Variables are defined by assigning a value to them as follows:
+.Bd -literal
+$var1 = 10.0.0.1
+.Ed
+.Pp
+A variable may also be defined as a set:
+.Bd -literal
+$var2 = { 10.0.0.1, 10.0.0.2 }
+.Ed
+.Pp
+Common variable definitions are for IP addresses, networks, ports,
+and interfaces.
+.Ss Tables
+Tables are specified using a number between angle brackets
+\*[Lt] and \*[Gt].
+The number used to specify a table should be between 0 and 15.
+The following is an example of table definition:
+.Bd -literal
+table <1> type hash dynamic
+.Pp
+.Ed
+Currently, tables support two storage types: "hash" or "tree".
+They can also be "dynamic" or static i.e. loaded from the specified file.
+.Pp
+The 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" can only contain IP addresses.
 .Pp
-.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.
+.Ss Groups
+Groups may have the following options: name, interface, and direction.
+They are defined in the following form:
+.Pp
+.Bd -literal
+group (name "my_group", interface wm0, in) {
+       # List of rules
+}
+.Ed
+.Pp
+.Ss Rules
+.Pp
+.Ss Map
+Network Address Translation (NAT) is expressed in a form of segment mapping.
+At present, only dynamic translation is supported.
+The following mapping types are available:
 .Pp
-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.
+.Bl -tag -width <-> -compact
+.It Pa ->
+outbound NAT (translation of the source)
+.It Pa <-
+inbound NAT (translation of the destination)
+.It Pa <->
+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.
+.Bd -literal
+map $ext_if dynamic 10.1.1.0/24 -> $pub_if
+.Ed
+.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.
+Explicit filter criteria can be specified using "pass <criteria>" as
+an additional option of the mapping.
+.Ss Procedures
+.Pp
+.Ss Misc
+Text after a hash (#) character is considered a comment.
+The \\ character at the end of a line marks a continuation line,
+i.e. the next line is considered an extension of the present line.
 .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,
@@ -119,7 +202,7 @@
 .Ed
 .\" -----
 .Sh FILES
-.Bl -tag -width /dev/npf.conf -compact
+.Bl -tag -width /usr/share/examples/npf -compact
 .It Pa /dev/npf
 control device
 .It Pa /etc/npf.conf