 @@ -1,43 +1,43 @@
-.\"	$NetBSD: libnpf.3,v 1.4 2016/12/27 21:25:12 wiz Exp $
+.\"	$NetBSD: libnpf.3,v 1.5 2017/12/07 00:22:06 rmind Exp $
 .\"
-.\" Copyright (c) 2011-2015 The NetBSD Foundation, Inc.
+.\" Copyright (c) 2011-2017 The NetBSD Foundation, Inc.
 .\" All rights reserved.
 .\"
 .\" This material is based upon work partially supported by The
 .\" NetBSD Foundation under a contract with Mindaugas Rasiukevicius.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
 .\" modification, are permitted provided that the following conditions
 .\" are met:
 .\" 1. Redistributions of source code must retain the above copyright
 .\"    notice, this list of conditions and the following disclaimer.
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
 .\"
 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd April 19, 2015
+.Dd December 7, 2017
 .Dt LIBNPF 3
 .Os
 .Sh NAME
 .Nm libnpf
 .Nd NPF packet filter library
 .Sh LIBRARY
 .Lb libnpf
 .Sh SYNOPSIS
 .In npf.h
 .\" ---
 .Ft nl_config_t *
 .Fn npf_config_create "void"
 .Ft int
 @@ -100,275 +100,293 @@
 .Fn npf_table_destroy "nl_table_t *tl"
 .\" -----
 .Sh DESCRIPTION
 The
 .Nm
 library provides an interface to create an NPF configuration having rules,
 tables, procedures, or translation policies.
 The configuration can be submitted to the kernel.
 .\" -----
 .Sh FUNCTIONS
 .Ss Configuration
 .Bl -tag -width 4n
 .It Fn npf_config_create
-Create a configuration.
+Create a new configuration object.
 .It Fn npf_config_submit "ncf" "fd" "errinfo"
-Submit configuration
+Submit the configuration object, specified by
-.Fa ncf
+.Fa ncf ,
 to the kernel.
-On error, the the description is written into the structure specified by
+On failure, the error information 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
+Serialize the current configuration and return the binary object as
-length in
+well as 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.
+unserialize, 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 retrieved configuration is active (true if yes
 and false otherwise).
 .It Fn npf_config_destroy "ncf"
-Destroy the configuration
+Destroy the configuration object, specified by
 .Fa ncf .
 .El
 .\" ---
 .Ss Rule interface
 .Bl -tag -width 4n
 .It Fn npf_rule_create "name" "attr" "ifname"
 Create a rule with a given name, attribute and priorty.
-Name can be
+If the name is specified, then it should be unique within the
 configuration object.
 Otherwise, the name can be
 .Dv NULL ,
-in which case rule has no unique identifier.
+in which case the rule will have no identifier.
 Otherwise, rules shall not have duplicate names.
 The following attributes, which can be ORed, are available:
 .Bl -tag -width indent
 .It Dv NPF_RULE_PASS
-Decision of this rule is "pass".
+The decision of this rule shall be "pass".
 If this attribute is not
-specified, then packet "block" (drop) is the default.
+specified, then "block" (drop the packet) is the default.
 .It Dv NPF_RULE_IN
-Match incoming packets.
+Match the incoming packets.
 .It Dv NPF_RULE_OUT
-Match outgoing packets.
+Match the outgoing packets.
 .It Dv NPF_RULE_FINAL
-Indicates that on rule match, further processing of the
+Indicate that on rule match, further processing of the ruleset should
-ruleset should be stopped and this rule applied instantly.
+be stopped and this rule should be applied instantly.
 .It Dv NPF_RULE_STATEFUL
-Create a state (session) on match, track the connection and
+Create a state (session) on match, track the connection and pass the
-therefore pass the backwards stream without inspection.
+backwards stream (the returning packets) without the ruleset 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.
+Exclude the interface identifier from the state key i.e. use a 4-tuple.
 .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_GROUP
 Allow this rule to have sub-rules.
-If used with
+If this flag is used with the
 .Dv NPF_RULE_DYNAMIC
-flag set, the can be added dynamically.
+flag set, then it is a dynamic group.
 The sub-rules can be added dynamically to a dynamic group, also meaning
 that the sub-rules must have the
 .Dv NPF_RULE_DYNAMIC
 flag set.
 Otherwise rules must be added statically i.e. created with the configuration.
 .It Dv NPF_RULE_DYNAMIC
 Indicate that the rule is dynamic.
 Such rules can only be added to the dynamic groups.
 .El
 .Pp
-Interface is specified by
+The interface is specified by the
-.Fa ifname ,
+.Fa ifname
-which is a string.
+string.
 .Dv NULL
 indicates any interface.
 .\" ---
 .It Fn npf_rule_setcode "rl" "type" "code" "len"
-Assign compiled code for the rule specified by
+Assign the code for the rule specified by
-.Fa rl ,
+.Fa rl .
-used for filter criteria.
+The code is used to implement the filter criteria.
-Pointer to the binary code is specified by
+The pointer to the binary code is specified by
 .Fa code ,
-and size of the memory area by
+the size of the memory area by
-.Fa len .
+.Fa len ,
-Type of the code is specified by
+and the type of the code is specified by
 .Fa type .
-Currently, only BPF byte-code is supported and
+Currently, only the BPF byte-code is supported and the
 .Dv NPF_CODE_BPF
-should be passed.
+constant should be passed.
 .\" ---
 .It Fn npf_rule_setkey "rl" "type" "key" "len"
 Assign a key for the rule specified by
 .Fa rl .
-Binary key is specified by
+The binary key is specified by
 .Fa key ,
 and its size by
 .Fa len .
 The size shall not exceed
 .Dv NPF_RULE_MAXKEYLEN .
-The kernel does not validate the key is unique, it is the responsibility
+The kernel does not check whether key is unique, therefore it is the
-of the caller.
+responsibility of the caller.
 .\" ---
 .It Fn npf_rule_setinfo "rl" "info" "len"
-Associate arbitrary information blob specified by
+Associate an arbitrary information blob specified by
 .Fa info ,
 and its size by
 .Fa len .
-This may be used for such purposes as byte-code annotation.
+This may be used for such purposes as the byte-code annotation.
 .\" ---
 .It Fn npf_rule_setprio "rl" "pri"
 Set priority to the rule.
 Negative priorities are invalid.
 .Pp
-Priority is the order of the rule in the ruleset.
+The priority is the order of the rule in the ruleset.
-Lower value means first to process, higher value - last to process.
+The lower value means first to process, the higher value - last to process.
 If multiple rules are inserted with the same priority,
-the order is unspecified.
+then the order is unspecified.
 .Pp
 The special constants
 .Dv NPF_PRI_FIRST
 and
 .Dv NPF_PRI_LAST
 can be passed to indicate that the rule should be inserted into the
 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
+Insert the rule into the set of the parent rule specified by
 .Fa parent .
-If value of
+If the 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.
+Destroy the given rule object.
 .El
 .\" -----
 .Ss Rule procedure interface
 .Bl -tag -width 4n
 .It Fn npf_rproc_create "name"
 Create a rule procedure with a given
 .Fa name .
-Name must be unique for each procedure.
+Thr name must be unique for each procedure.
 .It Fn npf_rproc_insert "ncf" "rp"
-Insert rule procedure into the specified configuration.
+Insert the rule procedure into the specified configuration object.
 .El
 .\" -----
 .Ss Translation interface
 .Bl -tag -width 4n
 .It Fn npf_nat_create "type" "flags" "ifname" "addr" "af" "port"
-Create a NAT translation policy of a specified type.
+Create a NAT policy of a specified type.
 There are two types:
 .Bl -tag -width "NPF_NAT_PORTMAP "
 .It Dv NPF_NATIN
 Inbound NAT policy (rewrite destination).
 .It Dv NPF_NATOUT
 Outbound NAT policy (rewrite source).
 .El
 .Pp
 A bi-directional NAT is obtained by combining two policies.
 The following
 .Fa flags
 are supported:
 .Bl -tag -width "NPF_NAT_PORTMAP "
 .It Dv NPF_NAT_STATIC
-Perform static (stateless) NAT rather than dynamic (stateful).
+Perform static (stateless) translation rather than dynamic (stateful).
 .It Dv NPF_NAT_PORTS
-Indicates to perform port translation.
+Perform the port translation.
-Otherwise, port translation is not performed and
+If this flag is not specified, then the port translation is not performed
 and the
 .Fa port
-is ignored.
+parameter is ignored.
 .It Dv NPF_NAT_PORTMAP
-Effective only if
+Create a port map and select a random port for translation.
 If enabled, then the value specified by the
 .Fa port
 parameter is ignored.
 This flag is effective only if the
 .Dv NPF_NAT_PORTS
 flag is set.
 Indicates to create a port map and select a random port for translation.
 Otherwise, port is translated to the value specified by
 .Fa port
 is used.
 .El
 .Pp
-Translation address is specified by
+The translation address is specified by
 .Fa addr ,
 and its family by
 .Fa af .
-Family must be either
+The family must be either
 .Dv AF_INET
 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
 .\" -----
 .Ss Table interface
 .Bl -tag -width 4n
 .It Fn npf_table_create "name" "index" "type"
-Create NPF table of specified type.
+Create an NPF table of a specified type.
-The following types are supported:
+The table is identified by the
 .Bl -tag -width "NPF_TABLE_TREE "
 .It Dv NPF_TABLE_HASH
 Indicates to use hash table for storage.
 .It Dv NPF_TABLE_TREE
 Indicates to use red-black tree for storage.
 Table is identified by the
 .Fa name
 and
 .Fa index ,
 which should be in the range between 1 and
 .Dv NPF_MAX_TABLE_ID .
 .Pp
 The following types are supported:
 .Bl -tag -width "NPF_TABLE_HASH"
 .It Dv NPF_TABLE_HASH
 Indicates to use a hash table for storage.
 .It Dv NPF_TABLE_TREE
 Indicates to use a tree for storage, supporting the longest
 prefix match.
 .It Dv NPF_TABLE_CDB
 Indicates to use constant database for storage, typically using
 a perfect hash table.
 In such case, the database produced by
 .Xr cdbw 3
 should be set using the
 .Fn npf_table_setdata
 function.
 .El
 .\" ---
 .It Fn npf_table_add_entry "tl" "af" "addr" "mask"
 Add an entry of IP address and mask, specified by
 .Fa addr
 and
 .Fa mask ,
 to the table specified by
 .Fa tl .
-Family, specified by
+The family, specified by
 .Fa af ,
 must be either
 .Dv AF_INET
 for IPv4 or
 .Dv AF_INET6
 for IPv6 address.
 .It Fn npf_table_insert "ncf" "tl"
-Insert table into set of configuration.
+Add the table to the configuration object.
-Routine performs a check for duplicate table ID.
+This routine performs a check for duplicate table IDs.
 .\" ---
 .It Fn npf_table_destroy "tl"
 Destroy the specified table.
 .El
 .\" -----
 .Sh SEE ALSO
 .Xr bpf 4 ,
 .Xr npf 7 ,
 .Xr npfctl 8
 .Sh HISTORY
 The NPF library first appeared in
 .Nx 6.0 .