[src/trunk]: src/lib/libnpf Update libnpf(3) man page.

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

details:   https://anonhg.NetBSD.org/src/rev/3fd45e65f468
branches:  trunk
changeset: 349902:3fd45e65f468
user:      rmind <rmind%NetBSD.org@localhost>
date:      Tue Dec 27 17:58:56 2016 +0000

description:
Update libnpf(3) man page.

diffstat:

 lib/libnpf/libnpf.3 |  126 ++++++++++++++++++++++++++++++++++++++++-----------
 1 files changed, 98 insertions(+), 28 deletions(-)

diffs (252 lines):

diff -r 1dd43df107b3 -r 3fd45e65f468 lib/libnpf/libnpf.3
--- a/lib/libnpf/libnpf.3       Tue Dec 27 17:13:45 2016 +0000
+++ b/lib/libnpf/libnpf.3       Tue Dec 27 17:58:56 2016 +0000
@@ -1,6 +1,6 @@
-.\"    $NetBSD: libnpf.3,v 1.2 2014/08/03 00:02:56 rmind Exp $
+.\"    $NetBSD: libnpf.3,v 1.3 2016/12/27 17:58:56 rmind Exp $
 .\"
-.\" Copyright (c) 2011-2013 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2011-2015 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This material is based upon work partially supported by The
@@ -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 August 2, 2014
+.Dd April 19, 2015
 .Dt LIBNPF 3
 .Os
 .Sh NAME
@@ -41,11 +41,19 @@
 .Ft nl_config_t *
 .Fn npf_config_create "void"
 .Ft int
-.Fn npf_config_submit "nl_config_t *ncf" "int fd"
+.Fn npf_config_submit "nl_config_t *ncf" "int fd" "nl_error_t *errinfo"
+.Ft nl_config_t *
+.Fn npf_config_retrieve "int fd" "bool *active" "bool *loaded"
+.Ft int
+.Fn npf_config_flush "int fd"
+.Ft void
+.Fn npf_config_export "const nl_config_t *ncf" "size_t *len"
+.Ft nl_config_t *
+.Fn npf_config_import "const void *blob" "size_t len"
+.Ft bool
+.Fn npf_config_active_p "nl_config_t *ncf"
 .Ft void
 .Fn npf_config_destroy "nl_config_t *ncf"
-.Ft int
-.Fn npf_config_flush "int fd"
 .\" ---
 .Ft nl_rule_t *
 .Fn npf_rule_create "char *name" "uint32_t attr" "const char *ifname"
@@ -53,14 +61,18 @@
 .Fn npf_rule_setcode "nl_rule_t *rl" "int type" "const void *code" "size_t len"
 .Ft int
 .Fn npf_rule_setkey "nl_rule_t *rl" "int type" "const void *code" "size_t len"
+.Ft int
+.Fn npf_rule_setinfo "nl_rule_t *rl" "const void *info" "size_t len"
 .Ft bool
 .Fn npf_rule_exists_p "nl_config_t *ncf" "const char *name"
 .Ft int
-.Fn npf_rule_insert "nl_config_t *ncf" "nl_rule_t *parent" "nl_rule_t *rl"
-.Ft int
-.Fn npf_rule_setprio "nl_rule_t *rl" "pri_t pri"
+.Fn npf_rule_setprio "nl_rule_t *rl" "int pri"
 .Ft int
 .Fn npf_rule_setproc "nl_config_t *ncf" "nl_rule_t *rl" "const char *name"
+.Ft int
+.Fn npf_rule_insert "nl_config_t *ncf" "nl_rule_t *parent" "nl_rule_t *rl"
+.Ft void *
+.Fn npf_rule_export "nl_rule_t *rl" "size_t *length"
 .Ft void
 .Fn npf_rule_destroy "nl_rule_t *rl"
 .\" ---
@@ -99,15 +111,32 @@
 .Bl -tag -width 4n
 .It Fn npf_config_create
 Create a configuration.
-.It Fn npf_config_submit "ncf" "fd"
+.It Fn npf_config_submit "ncf" "fd" "errinfo"
 Submit configuration
 .Fa ncf
 to the kernel.
+On error, the the description is written into the structure specified by
+.Fa errinfo .
+.It Fn npf_config_export "fd" "len"
+Serialize the given configuration and return binary object and its
+length in
+.Fa len
+parameter.
+The binary object is dynamically allocated and should be destroyed using
+.Xr free 3 .
+.It Fn npf_config_import "blob" "len"
+Read the configuration from a binary object of the specified length,
+unserialize, construct and return the configuration object.
+.It Fn npf_config_flush "fd"
+Flush the current configuration.
+.It Fn npf_config_retrieve "fd" "active" "loaded"
+Retrieve and return the loaded configuration from the kernel.
+.It Fn npf_config_active_p "ncf"
+Indicate whether the retrievied configuration is active (true if yes
+and false otherwise).
 .It Fn npf_config_destroy "ncf"
 Destroy the configuration
 .Fa ncf .
-.It Fn npf_config_flush "fd"
-Flush the current configuration.
 .El
 .\" ---
 .Ss Rule interface
@@ -124,20 +153,32 @@
 Decision of this rule is "pass".
 If this attribute is not
 specified, then packet "block" (drop) is the default.
+.It Dv NPF_RULE_IN
+Match incoming packets.
+.It Dv NPF_RULE_OUT
+Match outgoing packets.
 .It Dv NPF_RULE_FINAL
 Indicates that on rule match, further processing of the
 ruleset should be stopped and this rule applied instantly.
 .It Dv NPF_RULE_STATEFUL
 Create a state (session) on match, track the connection and
 therefore pass the backwards stream without inspection.
+The state is uniquely identified by a 5-tuple (source and destination
+IP addresses, port numbers and an interface identifier).
+.It Dv NPF_RULE_MULTIENDS
+Exclude the interface from the state identifier.
 .It Dv NPF_RULE_RETRST
 Return TCP RST packet in a case of packet block.
 .It Dv NPF_RULE_RETICMP
 Return ICMP destination unreachable in a case of packet block.
-.It Dv NPF_RULE_IN
-Rule may match only if incoming packet.
-.It Dv NPF_RULE_OUT
-Rule may match only if outgoing packet.
+.It Dv NPF_RULE_GROUP
+Allow this rule to have sub-rules.
+If used with
+.Dv NPF_RULE_DYNAMIC
+flag set, the can be added dynamically.
+Otherwise rules must be added statically i.e. created with the configuration.
+.It Dv NPF_RULE_DYNAMIC
+Indicate that the rule is dynamic.
 .El
 .Pp
 Interface is specified by
@@ -156,8 +197,8 @@
 .Fa len .
 Type of the code is specified by
 .Fa type .
-Currently, only n-code is supported and
-.Dv NPF_CODE_NC
+Currently, only BPF byte-code is supported and
+.Dv NPF_CODE_BPF
 should be passed.
 .\" ---
 .It Fn npf_rule_setkey "rl" "type" "key" "len"
@@ -169,15 +210,15 @@
 .Fa len .
 The size shall not exceed
 .Dv NPF_RULE_MAXKEYLEN .
+The kernel does not validate the key is unique, it is the responsibilty
+of the caller.
 .\" ---
-.It Fn npf_rule_insert "ncf" "parent" "rl"
-Insert the rule into the set of parent rule specified by
-.Fa parent .
-If value of
-.Fa parent
-is
-.Dv NULL ,
-then insert into the main ruleset.
+.It Fn npf_rule_setinfo "rl" "info" "len"
+Associate arbitrary information blob specified by
+.Fa info ,
+and its size by
+.Fa len .
+This may be used for such purposes as byte-code annotation.
 .\" ---
 .It Fn npf_rule_setprio "rl" "pri"
 Set priority to the rule.
@@ -196,8 +237,26 @@
 beginning or the end of the priority level 0 in the ruleset.
 All rules inserted using these constants will have the priority 0
 assigned and will share this level in the ordered way.
+.\" ---
 .It Fn npf_rule_setproc "ncf" "rl" "name"
 Set a procedure for the specified rule.
+.\" ---
+.It Fn npf_rule_insert "ncf" "parent" "rl"
+Insert the rule into the set of parent rule specified by
+.Fa parent .
+If value of
+.Fa parent
+is
+.Dv NULL ,
+then insert into the main ruleset.
+.\" ---
+.It Fn npf_rule_export "rl" "length"
+Serialize the rule (including the byte-code), return a binary object
+and set its
+.Fa length .
+The binary object is dynamically allocated and should be destroyed using
+.Xr free 3 .
+.\" ---
 .It Fn npf_rule_destroy "rl"
 Destroy the given rule.
 .El
@@ -219,9 +278,9 @@
 There are two types:
 .Bl -tag -width "NPF_NAT_PORTMAP "
 .It Dv NPF_NATIN
-Inbound NAT policy.
+Inbound NAT policy (rewrite destination).
 .It Dv NPF_NATOUT
-Outbound NAT policy.
+Outbound NAT policy (rewrite source).
 .El
 .Pp
 A bi-directional NAT is obtained by combining two policies.
@@ -229,6 +288,8 @@
 .Fa flags
 are supported:
 .Bl -tag -width "NPF_NAT_PORTMAP "
+.It Dv NPF_NAT_STATIC
+Perform static (stateless) NAT rather than dynamic (stateful).
 .It Dv NPF_NAT_PORTS
 Indicates to perform port translation.
 Otherwise, port translation is not performed and
@@ -253,6 +314,13 @@
 for IPv4 or
 .Dv AF_INET6
 for IPv6 address.
+.\" ---
+.It Fn npf_nat_setalgo "nt" "algo"
+Set a particular NAT algorithm.
+Currently, only
+.Dv NPF_ALGO_NPT66
+algorithm is supported for NPTv6 (RFC 6296).
+.\" ---
 .It Fn npf_nat_insert "ncf" "nt" "pri"
 Insert NAT policy, its rule, into the specified configuration.
 .El
@@ -274,6 +342,7 @@
 which should be in the range between 1 and
 .Dv NPF_MAX_TABLE_ID .
 .El
+.\" ---
 .It Fn npf_table_add_entry "tl" "af" "addr" "mask"
 Add an entry of IP address and mask, specified by
 .Fa addr
@@ -291,6 +360,7 @@
 .It Fn npf_table_insert "ncf" "tl"
 Insert table into set of configuration.
 Routine performs a check for duplicate table ID.
+.\" ---
 .It Fn npf_table_destroy "tl"
 Destroy the specified table.
 .El