Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src/lib/libnpf libnpf(3): improve the wording, fix and expand so...
details: https://anonhg.NetBSD.org/src/rev/608991ac31d3
branches: trunk
changeset: 357988:608991ac31d3
user: rmind <rmind%NetBSD.org@localhost>
date: Thu Dec 07 00:22:06 2017 +0000
description:
libnpf(3): improve the wording, fix and expand some sections.
diffstat:
lib/libnpf/libnpf.3 | 164 ++++++++++++++++++++++++++++-----------------------
1 files changed, 91 insertions(+), 73 deletions(-)
diffs (truncated from 332 to 300 lines):
diff -r 7d977957a22b -r 608991ac31d3 lib/libnpf/libnpf.3
--- a/lib/libnpf/libnpf.3 Wed Dec 06 19:34:00 2017 +0000
+++ b/lib/libnpf/libnpf.3 Thu Dec 07 00:22:06 2017 +0000
@@ -1,6 +1,6 @@
-.\" $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
@@ -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 April 19, 2015
+.Dd December 7, 2017
.Dt LIBNPF 3
.Os
.Sh NAME
@@ -110,23 +110,24 @@
.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
-.Fa ncf
+Submit the configuration object, specified by
+.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
-length in
+Serialize the current configuration and return the binary object as
+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"
@@ -135,7 +136,7 @@
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
.\" ---
@@ -143,91 +144,97 @@
.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.
-Otherwise, rules shall not have duplicate names.
+in which case the rule will have no identifier.
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
-ruleset should be stopped and this rule applied instantly.
+Indicate that on rule match, further processing of the ruleset should
+be stopped and this rule should be applied instantly.
.It Dv NPF_RULE_STATEFUL
-Create a state (session) on match, track the connection and
-therefore pass the backwards stream without inspection.
+Create a state (session) on match, track the connection and pass the
+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
-.Fa ifname ,
-which is a string.
+The interface is specified by the
+.Fa ifname
+string.
.Dv NULL
indicates any interface.
.\" ---
.It Fn npf_rule_setcode "rl" "type" "code" "len"
-Assign compiled code for the rule specified by
-.Fa rl ,
-used for filter criteria.
-Pointer to the binary code is specified by
+Assign the code for the rule specified by
+.Fa rl .
+The code is used to implement the filter criteria.
+The pointer to the binary code is specified by
.Fa code ,
-and size of the memory area by
-.Fa len .
-Type of the code is specified by
+the size of the memory area by
+.Fa len ,
+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
-of the caller.
+The kernel does not check whether key is unique, therefore it is the
+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.
-Lower value means first to process, higher value - last to process.
+The priority is the order of the rule in the ruleset.
+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
@@ -242,9 +249,9 @@
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 ,
@@ -258,7 +265,7 @@
.Xr free 3 .
.\" ---
.It Fn npf_rule_destroy "rl"
-Destroy the given rule.
+Destroy the given rule object.
.El
.\" -----
.Ss Rule procedure interface
@@ -266,15 +273,15 @@
.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
@@ -289,27 +296,28 @@
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.
-Otherwise, port translation is not performed and
+Perform the port translation.
+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
@@ -328,19 +336,29 @@
.Ss Table interface
.Bl -tag -width 4n
.It Fn npf_table_create "name" "index" "type"
-Create NPF table of specified type.
-The following types are supported:
-.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
+Create an NPF table of a specified type.
+The 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
Home |
Main Index |
Thread Index |
Old Index