diff options
Diffstat (limited to 'static/netbsd/man3/libnpf.3')
| -rw-r--r-- | static/netbsd/man3/libnpf.3 | 506 |
1 files changed, 506 insertions, 0 deletions
diff --git a/static/netbsd/man3/libnpf.3 b/static/netbsd/man3/libnpf.3 new file mode 100644 index 00000000..05d56f78 --- /dev/null +++ b/static/netbsd/man3/libnpf.3 @@ -0,0 +1,506 @@ +.\" $NetBSD: libnpf.3,v 1.12 2020/05/30 14:16:56 rmind Exp $ +.\" +.\" Copyright (c) 2011-2019 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 May 30, 2020 +.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 +.Fn npf_config_submit "nl_config_t *ncf" "int fd" "npf_error_t *errinfo" +.Ft nl_config_t * +.Fn npf_config_retrieve "int fd" +.Ft int +.Fn npf_config_flush "int fd" +.Ft void +.Fn npf_config_export "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 bool +.Fn npf_config_loaded_p "nl_config_t *ncf" +.Ft void +.Fn npf_config_destroy "nl_config_t *ncf" +.\" --- +.Ft nl_rule_t * +.Fn npf_rule_create "const char *name" "uint32_t attr" "const char *ifname" +.Ft int +.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" "const void *key" "size_t len" +.Ft int +.Fn npf_rule_setinfo "nl_rule_t *rl" "const void *info" "size_t len" +.Ft int +.Fn npf_rule_setprio "nl_rule_t *rl" "int pri" +.Ft int +.Fn npf_rule_setproc "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 bool +.Fn npf_rule_exists_p "nl_config_t *ncf" "const char *name" +.Ft void * +.Fn npf_rule_export "nl_rule_t *rl" "size_t *length" +.Ft void +.Fn npf_rule_destroy "nl_rule_t *rl" +.\" --- +.Ft nl_rproc_t * +.Fn npf_rproc_create "const char *name" +.Ft int +.Fn npf_rproc_extcall "nl_rproc_t *rp" "nl_ext_t *ext" +.Ft bool +.Fn npf_rproc_exists_p "nl_config_t *ncf" "const char *name" +.Ft int +.Fn npf_rproc_insert "nl_config_t *ncf" "nl_rproc_t *rp" +.\" --- +.Ft nl_nat_t * +.Fn npf_nat_create "int type" "unsigned flags" "const char *ifname" +.Ft int +.Fn npf_nat_setaddr "nl_nat_t *nt" "int af" "npf_addr_t *addr" \ +"npf_netmask_t mask" +.Ft int +.Fn npf_nat_setport "nl_nat_t *nt" "in_port_t port" +.Ft int +.Fn npf_nat_insert "nl_config_t *ncf" "nl_nat_t *nt" +.\" --- +.Ft nl_table_t * +.Fn npf_table_create "const char *name" "unsigned id" "int type" +.Ft int +.Fn npf_table_add_entry "nl_table_t *tl" "int af" \ +"const npf_addr_t *addr" "const npf_netmask_t mask" +.Ft int +.Fn npf_table_insert "nl_config_t *ncf" "nl_table_t *tl" +.Ft int +.Fn npf_table_replace "int fd" "nl_table_t *tl" "npf_error_t *errinfo" +.Ft void +.Fn npf_table_destroy "nl_table_t *tl" +.\" --- +.Ft int +.Fn npf_ruleset_add "int fd" "const char *name" "nl_rule_t *rl" "uint64_t *id" +.Ft int +.Fn npf_ruleset_remove "int fd" "const char *name" "uint64_t id" +.Ft int +.Fn npf_ruleset_remkey "int fd" "const char *name" "const void *key" "size_t len" +.Ft int +.Fn npf_ruleset_flush "int fd" "const char *name" +.\" ----- +.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 new configuration object. +.It Fn npf_config_submit "ncf" "fd" "errinfo" +Submit the configuration object, specified by +.Fa ncf , +to the kernel. +On failure, the error information is written into the structure +specified by +.Fa errinfo . +.It Fn npf_config_export "ncf" "len" +Serialize the given 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, and return the configuration object. +.It Fn npf_config_flush "fd" +Flush the current configuration. +.It Fn npf_config_retrieve "fd" +Retrieve and return the loaded configuration from the kernel. +.It Fn npf_config_active_p "ncf" +Indicate whether the retrieved configuration is active i.e. packet +filtering is enabled (true if yes and false otherwise). +.It Fn npf_config_loaded_p "ncf" +Indicate whether the retrieved configuration is loaded i.e. has any +rules (true if yes and false otherwise). +.It Fn npf_config_destroy "ncf" +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, attributes and priority. +If the name is specified, then it should be unique within the +configuration object. +Otherwise, the name can be +.Dv NULL , +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 +The decision of this rule shall be "pass". +If this attribute is not +specified, then "block" (drop the packet) is the default. +.It Dv NPF_RULE_IN +Match the incoming packets. +.It Dv NPF_RULE_OUT +Match the outgoing packets. +.It Dv NPF_RULE_FINAL +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 pass the +backwards stream (the returning packets) without the ruleset inspection. +The state is uniquely identified by an n-tuple key. +.It Dv NPF_RULE_GSTATEFUL +Exclude the interface identifier from the state key (n-tuple). +This makes the state global with respect to the network interfaces. +The state is also picked for packets travelling in different direction +than originally. +.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 this flag is used with the +.Dv NPF_RULE_DYNAMIC +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 +The interface is specified by the +.Fa ifname +string. +.Dv NULL +indicates any interface. +.\" --- +.It Fn npf_rule_setcode "rl" "type" "code" "len" +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 , +the size of the memory area by +.Fa len , +and the type of the code is specified by +.Fa type . +Currently, only the BPF byte-code is supported and the +.Dv NPF_CODE_BPF +constant should be passed. +.\" --- +.It Fn npf_rule_setkey "rl" "key" "len" +Assign a key for the rule specified by +.Fa rl . +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 check whether key is unique, therefore it is the +responsibility of the caller. +.\" --- +.It Fn npf_rule_setinfo "rl" "info" "len" +Associate an arbitrary information blob specified by +.Fa info , +and its size by +.Fa len . +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 +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, +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 "rl" "name" +Set a procedure for the specified rule. +.\" --- +.It Fn npf_rule_insert "ncf" "parent" "rl" +Insert the rule into the set of the parent rule specified by +.Fa parent . +If the value of +.Fa parent +is +.Dv NULL , +then insert into the main ruleset. +The rule will be consumed (the relevant resourced will be freed) and it +must not be referenced after insertion. +.\" --- +.It Fn npf_rule_exists_p "ncf" "name" +Check whether the rule with a given name is already in the configuration. +.\" --- +.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 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 . +Thr name must be unique for each procedure. +.It Fn npf_rproc_insert "ncf" "rp" +Insert the rule procedure into the specified configuration object. +The rule procedure must not be referenced after insertion. +.El +.\" ----- +.Ss Translation interface +.Bl -tag -width 4n +.It Fn npf_nat_create "type" "flags" "ifname" +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) translation rather than dynamic (stateful). +.It Dv NPF_NAT_PORTS +Perform the port translation. +If this flag is not specified, then the port translation is not performed +and the +.Fa port +parameter is ignored. +.It Dv NPF_NAT_PORTMAP +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. +.El +.Pp +The network interface on which the policy will be applicable is specified by +.Fa ifname . +.\" --- +.It Fn npf_nat_setaddr "nt" "af" "addr" "mask" +Set the translation address, as specified by +.Fa addr , +and its family by +.Fa af . +The family must be either +.Dv AF_INET +for IPv4 or +.Dv AF_INET6 +for IPv6 address. +Additionally, +.Fa mask +may be specified to indicate the translation network; +otherwise, it should be set to +.Dv NPF_NO_NETMASK . +.Pp +In order to use the translation network, a custom algorithm may need to +be specified using the +.Fn npf_nat_setalgo +function. +.\" --- +.It Fn npf_nat_setport "nt" "port" +Set the translation port, specified by +.Fa port . +.\" --- +.It Fn npf_nat_setalgo "nt" "algo" +Set a particular NAT algorithm. +Currently, the following algorithms are supported with dynamic NAT: +.Bl -tag -width "NPF_ALGO_IPHASH" +.It Dv NPF_ALGO_IPHASH +Hash of the source and destination addresses. +.It Dv NPF_ALGO_RR +Round-robin for the translation addresses. +.It Dv NPF_ALGO_NETMAP +Network-to-network map as described below, but with state tracking. +It is used when it is necessary to translate the ports. +.El +.Pp +The following are support with static NAT: +.Bl -tag -width "NPF_ALGO_NETMAP" +.It Dv NPF_ALGO_NETMAP +Network-to-network map where the translation network prefix (address +after applying the mask) is bitwise OR-ed with the host part of the +original address (zero bits of the mask). +.It Dv NPF_ALGO_NPT66 +IPv6-to-IPv6 Network Prefix Translation (NPTv6, defined in RFC 6296). +.El +.\" --- +.It Fn npf_nat_insert "ncf" "nt" +Insert the NAT policy, its rule, into the specified configuration. +The NAT rule must not be referenced after insertion. +.El +.\" ----- +.Ss Table interface +.Bl -tag -width 4n +.It Fn npf_table_create "name" "index" "type" +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_TABLES . +.Pp +The following types are supported: +.Bl -tag -width "NPF_TABLE_IPSET" +.It Dv NPF_TABLE_IPSET +Indicates to use a regular associative array for storage of IP sets. +Currently implemented as a hashmap. +.It Dv NPF_TABLE_LPM +Indicates to the table can contain networks (as well as hosts) and the +longest prefix match should be performed on lookup. +.It Dv NPF_TABLE_CONST +Indicates that the table contents will be constant and the table can be +considered immutable (no inserts/removes after load). +If such constraint is acceptable, this table type will provide the best +performance. +It is currently implemented as a perfect hash table, generated on table +insertion into the configuration. +.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 . +The family, specified by +.Fa af , +must be either +.Dv AF_INET +for IPv4 or +.Dv AF_INET6 +for IPv6 address. +If there is no mask, then +.Fa mask +should be set to +.Dv NPF_NO_NETMASK . +.\" --- +.It Fn npf_table_insert "ncf" "tl" +Add the table to the configuration object. +This routine performs a check for duplicate table IDs. +The table must not be referenced after insertion. +.\" --- +.It Fn npf_table_replace "fd" "tl" "errinfo" +Submit the table object, specified by +.Fa tl , +to the kernel, to replace the existing table with the +corresponding table name and ID. +On failure, the error information is written into the structure +specified by +.Fa errinfo . +.\" --- +.It Fn npf_table_destroy "tl" +Destroy the specified table. +.El +.\" ----- +.Ss Ruleset interface +.Bl -tag -width 4n +.It Fn npf_ruleset_add "fd" "name" "rl" "id" +Add a given rule, specified by +.Fa rl , +into the dynamic ruleset named +.Fa name . +On success, return 0 and a unique rule ID in the +.Fa id +parameter. +.It Fn npf_ruleset_remove "fd" "name" "id" +Remove a rule from the dynamic ruleset, specified by +.Fa name . +The rule is specified by its unique ID in the +.Fa id +parameter. +.It Fn npf_ruleset_remkey "fd" "name" "key" "len" +Remove a rule from the dynamic ruleset, specified by +.Fa name . +The rule is specified by its key, in the +.Fa key +and +.Fa len +parameters. +The key for the rule must have been set during its construction, using the +.Fn npf_rule_setkey +routine. +.It Fn npf_ruleset_flush "fd" "name" +Clear the dynamic ruleset, specified by +.Fa name , +by removing all its rules. +.El +.\" ----- +.Sh SEE ALSO +.Xr bpf 4 , +.Xr npf 7 , +.Xr npfctl 8 +.Sh HISTORY +The NPF library first appeared in +.Nx 6.0 . |