394 lines
12 KiB
Groff
394 lines
12 KiB
Groff
.\" $NetBSD: libnpf.3,v 1.6 2018/09/29 14:41:36 rmind Exp $
|
|
.\"
|
|
.\" 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 June 10, 2018
|
|
.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" "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"
|
|
.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" "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_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"
|
|
.\" ---
|
|
.Ft nl_rproc_t *
|
|
.Fn npf_rproc_create "char *name"
|
|
.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" "u_int flags" "const char *ifname" \
|
|
"npf_addr_t *addr" "int af" "in_port_t port"
|
|
.Ft int
|
|
.Fn npf_nat_insert "nl_config_t *ncf" "nl_nat_t *nt" "pri_t pri"
|
|
.\" ---
|
|
.Ft nl_table_t *
|
|
.Fn npf_table_create "const char *name" "u_int id" "int type"
|
|
.Ft int
|
|
.Fn npf_table_add_entry "nl_table_t *tl" "int af" \
|
|
"in_addr_t addr" "in_addr_t mask"
|
|
.Ft int
|
|
.Fn npf_table_insert "nl_config_t *ncf" "nl_table_t *tl"
|
|
.Ft void
|
|
.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 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 "fd" "len"
|
|
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, 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 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.
|
|
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 a 5-tuple (source and destination
|
|
IP addresses, port numbers and an interface identifier).
|
|
.It Dv NPF_RULE_MULTIENDS
|
|
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 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" "type" "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 "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 the parent rule specified by
|
|
.Fa parent .
|
|
If the value of
|
|
.Fa parent
|
|
is
|
|
.Dv NULL ,
|
|
then insert into the main ruleset.
|
|
The rule must not be referenced after insertion.
|
|
.\" ---
|
|
.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" "addr" "af" "port"
|
|
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 translation address is 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.
|
|
.\" ---
|
|
.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.
|
|
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_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, which will be generated on table insertion
|
|
into the configuration.
|
|
Such table will be immutable.
|
|
.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.
|
|
.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_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 .
|