NAME
libnpf —
NPF packet filter
library
LIBRARY
NPF Packet Filter Library (libnpf, -lnpf)
SYNOPSIS
#include <npf.h>
nl_config_t *
npf_config_create(
void);
int
npf_config_submit(
nl_config_t
*ncf,
int fd,
nl_error_t *errinfo);
nl_config_t *
npf_config_retrieve(
int
fd,
bool *active,
bool *loaded);
int
npf_config_flush(
int
fd);
void
npf_config_export(
const
nl_config_t *ncf,
size_t
*len);
nl_config_t *
npf_config_import(
const
void *blob,
size_t
len);
bool
npf_config_active_p(
nl_config_t
*ncf);
void
npf_config_destroy(
nl_config_t
*ncf);
nl_rule_t *
npf_rule_create(
char
*name,
uint32_t attr,
const char *ifname);
int
npf_rule_setcode(
nl_rule_t
*rl,
int type,
const void *code,
size_t len);
int
npf_rule_setkey(
nl_rule_t
*rl,
int type,
const void *code,
size_t len);
int
npf_rule_setinfo(
nl_rule_t
*rl,
const void
*info,
size_t len);
bool
npf_rule_exists_p(
nl_config_t
*ncf,
const char
*name);
int
npf_rule_setprio(
nl_rule_t
*rl,
int pri);
int
npf_rule_setproc(
nl_config_t
*ncf,
nl_rule_t *rl,
const char *name);
int
npf_rule_insert(
nl_config_t
*ncf,
nl_rule_t
*parent,
nl_rule_t
*rl);
void *
npf_rule_export(
nl_rule_t
*rl,
size_t *length);
void
npf_rule_destroy(
nl_rule_t
*rl);
nl_rproc_t *
npf_rproc_create(
char
*name);
bool
npf_rproc_exists_p(
nl_config_t
*ncf,
const char
*name);
int
npf_rproc_insert(
nl_config_t
*ncf,
nl_rproc_t
*rp);
nl_nat_t *
npf_nat_create(
int
type,
u_int flags,
const char *ifname,
npf_addr_t *addr,
int af,
in_port_t port);
int
npf_nat_insert(
nl_config_t
*ncf,
nl_nat_t *nt,
pri_t pri);
nl_table_t *
npf_table_create(
const
char *name,
u_int id,
int type);
int
npf_table_add_entry(
nl_table_t
*tl,
int af,
in_addr_t addr,
in_addr_t mask);
int
npf_table_insert(
nl_config_t
*ncf,
nl_table_t
*tl);
void
npf_table_destroy(
nl_table_t
*tl);
DESCRIPTION
The
libnpf library provides an interface to create an NPF
configuration having rules, tables, procedures, or translation policies. The
configuration can be submitted to the kernel.
FUNCTIONS
Configuration
-
-
- npf_config_create()
- Create a new configuration object.
-
-
- npf_config_submit(ncf,
fd, errinfo)
- Submit the configuration object, specified by
ncf, to the kernel. On failure, the error
information is written into the structure specified by
errinfo.
-
-
- npf_config_export(fd,
len)
- Serialize the current configuration and return the binary
object as well as its length in len parameter. The
binary object is dynamically allocated and should be destroyed using
free(3).
-
-
- npf_config_import(blob,
len)
- Read the configuration from a binary object of the
specified length, unserialize, and return the configuration object.
-
-
- npf_config_flush(fd)
- Flush the current configuration.
-
-
- npf_config_retrieve(fd,
active, loaded)
- Retrieve and return the loaded configuration from the
kernel.
-
-
- npf_config_active_p(ncf)
- Indicate whether the retrieved configuration is active
(true if yes and false otherwise).
-
-
- npf_config_destroy(ncf)
- Destroy the configuration object, specified by
ncf.
Rule interface
-
-
- 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
NULL
, in which
case the rule will have no identifier. The following attributes, which can
be ORed, are available:
-
-
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.
-
-
NPF_RULE_IN
- Match the incoming packets.
-
-
NPF_RULE_OUT
- Match the outgoing packets.
-
-
NPF_RULE_FINAL
- Indicate that on rule match, further processing of the
ruleset should be stopped and this rule should be applied
instantly.
-
-
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).
-
-
NPF_RULE_MULTIENDS
- Exclude the interface identifier from the state key
i.e. use a 4-tuple.
-
-
NPF_RULE_RETRST
- Return TCP RST packet in a case of packet block.
-
-
NPF_RULE_RETICMP
- Return ICMP destination unreachable in a case of packet
block.
-
-
NPF_RULE_GROUP
- Allow this rule to have sub-rules. If this flag is used
with the
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
NPF_RULE_DYNAMIC
flag set. Otherwise rules
must be added statically i.e. created with the configuration.
-
-
NPF_RULE_DYNAMIC
- Indicate that the rule is dynamic. Such rules can only
be added to the dynamic groups.
The interface is specified by the ifname string.
NULL
indicates any interface.
-
-
- npf_rule_setcode(rl,
type, code,
len)
- Assign the code for the rule specified by
rl. The code is used to implement the filter
criteria. The pointer to the binary code is specified by
code, the size of the memory area by
len, and the type of the code is specified by
type. Currently, only the BPF byte-code is supported
and the
NPF_CODE_BPF
constant should be
passed.
-
-
- npf_rule_setkey(rl,
type, key,
len)
- Assign a key for the rule specified by
rl. The binary key is specified by
key, and its size by len. The
size shall not exceed
NPF_RULE_MAXKEYLEN
. The
kernel does not check whether key is unique, therefore it is the
responsibility of the caller.
-
-
- npf_rule_setinfo(rl,
info, len)
- Associate an arbitrary information blob specified by
info, and its size by len.
This may be used for such purposes as the byte-code annotation.
-
-
- npf_rule_setprio(rl,
pri)
- Set priority to the rule. Negative priorities are invalid.
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.
The special constants
NPF_PRI_FIRST
and
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.
-
-
- npf_rule_setproc(ncf,
rl, name)
- Set a procedure for the specified rule.
-
-
- npf_rule_insert(ncf,
parent, rl)
- Insert the rule into the set of the parent rule specified
by parent. If the value of
parent is
NULL
, then insert
into the main ruleset.
-
-
- npf_rule_export(rl,
length)
- Serialize the rule (including the byte-code), return a
binary object and set its length. The binary object
is dynamically allocated and should be destroyed using
free(3).
-
-
- npf_rule_destroy(rl)
- Destroy the given rule object.
Rule procedure interface
-
-
- npf_rproc_create(name)
- Create a rule procedure with a given
name. Thr name must be unique for each
procedure.
-
-
- npf_rproc_insert(ncf,
rp)
- Insert the rule procedure into the specified configuration
object.
Translation interface
-
-
- npf_nat_create(type,
flags, ifname,
addr, af,
port)
- Create a NAT policy of a specified type. There are two
types:
-
-
NPF_NATIN
- Inbound NAT policy (rewrite destination).
-
-
NPF_NATOUT
- Outbound NAT policy (rewrite source).
A bi-directional NAT is obtained by combining two policies. The following
flags are supported:
-
-
NPF_NAT_STATIC
- Perform static (stateless) translation rather than
dynamic (stateful).
-
-
NPF_NAT_PORTS
- Perform the port translation. If this flag is not
specified, then the port translation is not performed and the
port parameter is ignored.
-
-
NPF_NAT_PORTMAP
- Create a port map and select a random port for
translation. If enabled, then the value specified by the
port parameter is ignored. This flag is
effective only if the
NPF_NAT_PORTS
flag is
set.
The translation address is specified by addr, and its
family by af. The family must be either
AF_INET
for IPv4 or
AF_INET6
for IPv6 address.
-
-
- npf_nat_setalgo(nt,
algo)
- Set a particular NAT algorithm. Currently, only
NPF_ALGO_NPT66
algorithm is supported for NPTv6
(RFC 6296).
-
-
- npf_nat_insert(ncf,
nt, pri)
- Insert NAT policy, its rule, into the specified
configuration.
Table interface
-
-
- npf_table_create(name,
index, type)
- Create an NPF table of a specified type. The table is
identified by the name and
index, which should be in the range between 1 and
NPF_MAX_TABLE_ID
.
The following types are supported:
-
-
NPF_TABLE_HASH
- Indicates to use a hash table for storage.
-
-
NPF_TABLE_TREE
- Indicates to use a tree for storage, supporting the
longest prefix match.
-
-
NPF_TABLE_CDB
- Indicates to use constant database for storage,
typically using a perfect hash table. In such case, the database
produced by cdbw(3) should
be set using the npf_table_setdata() function.
-
-
- npf_table_add_entry(tl,
af, addr,
mask)
- Add an entry of IP address and mask, specified by
addr and mask, to the table
specified by tl. The family, specified by
af, must be either
AF_INET
for IPv4 or AF_INET6
for IPv6 address.
-
-
- npf_table_insert(ncf,
tl)
- Add the table to the configuration object. This routine
performs a check for duplicate table IDs.
-
-
- npf_table_destroy(tl)
- Destroy the specified table.
SEE ALSO
bpf(4),
npf(7),
npfctl(8)
HISTORY
The NPF library first appeared in
NetBSD 6.0.