Module Name: src Committed By: rmind Date: Tue Dec 27 17:58:56 UTC 2016
Modified Files: src/lib/libnpf: libnpf.3 Log Message: Update libnpf(3) man page. To generate a diff of this commit: cvs rdiff -u -r1.2 -r1.3 src/lib/libnpf/libnpf.3 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/lib/libnpf/libnpf.3 diff -u src/lib/libnpf/libnpf.3:1.2 src/lib/libnpf/libnpf.3:1.3 --- src/lib/libnpf/libnpf.3:1.2 Sun Aug 3 00:02:56 2014 +++ src/lib/libnpf/libnpf.3 Tue Dec 27 17:58:56 2016 @@ -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" -.Ft void -.Fn npf_config_destroy "nl_config_t *ncf" +.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 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 @@ The configuration can be submitted to th .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 @@ The following attributes, which can be O 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 @@ and size of the memory area by .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 @@ 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 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 @@ can be passed to indicate that the rule 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 @@ Create a NAT translation policy of a spe 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 @@ 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). .It Dv NPF_NAT_PORTS Indicates to perform port translation. Otherwise, port translation is not performed and @@ -253,6 +314,13 @@ Family must be either 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 @@ and 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 @@ for IPv6 address. .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