Return to npf.3 CVS log

Up to [cvs.NetBSD.org] / src / lib / libnpf

New sentence, new line. Mark up NULL.

.\"	$NetBSD: npf.3,v 1.2 2011/02/02 09:05:01 wiz Exp $
.\"
.\" Copyright (c) 2011 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 February 2, 2011
.Dt NPF 3
.Os
.Sh NAME
.Nm npf
.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"
.Ft void
.Fn npf_config_destroy "nl_config_t *ncf"
.\" ---
.Ft nl_rule_t *
.Fn npf_rule_create "char *name" "uint32_t attr" "u_int if_idx"
.Ft int
.Fn npf_rule_setcode "nl_rule_t *rl" "int type" "const void *code" "size_t sz"
.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" "pri_t pri"
.Ft int
.Fn npf_rule_setproc "nl_config_t *ncf" "nl_rule_t *rl" "const char *name"
.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" "int flags" "u_int if_idx" \
"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 "int index" "int type"
.Ft int
.Fn npf_table_add_entry "nl_table_t *tl" "in_addr_t addr" "in_addr_t mask"
.Fa bool
.Fn npf_table_exists_p "nl_config_t *ncf" "u_int tid"
.Ft int
.Fn npf_table_insert "nl_config_t *ncf" "nl_table_t *tl"
.Ft void
.Fn npf_table_destroy "nl_table_t *tl"
.\" ---
.Ft int
.Fn npf_update_rule "int fd" "char *rname" "nl_rule_t *rl"
.Ft int
.Fn npf_sessions_send "int fd" "const char *fpath"
.Ft int
.Fn npf_sessions_recv "int fd" "const char *fpath"
.\" -----
.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 CONFIGURATION
.Bl -tag -width 4n
.It Fn npf_config_create
Create a configuration.
.It Fn npf_config_submit
Submit configuration to the kernel.
.It Fn npf_config_destroy
Destroy the configuration.
.El
.\" ---
.Sh RULE INTERFACE
.Bl -tag -width 4n
.It Fn npf_rule_create
Create a rule with a given name, attribute and priorty.
Name can be
.Dv NULL ,
in which case rule has no unique identifier.
Otherwise, rules shall not have duplicate names.
The following attributes, which can be ORed, are available:
.Bl -tag -width indent
.It Dv NPF_RULE_PASS
Decision of this rule is "pass".
If this attribute is not
specified, then packet "block" (drop) is the default.
.It Dv NPF_RULE_DEFAULT
This a default rule in the ruleset.
There can only be a
single rule having this attribute set in the ruleset.
.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_KEEPSTATE
Create a state (session) on match, track the connection and
therefore pass the backwards stream without inspection.
.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.
.El
.Pp
Interface is specified by
.Fa if_idx ,
which is a numeral representation of an
interface, given by
.Xr if_nametoindex 3 .
Zero indicates any interface.
.\" ---
.It Fn npf_rule_setcode
Assign compiled code for the rule specified by
.Fa rl ,
used for filter criteria.
Pointer to the binary code is specified by
.Fa code ,
and size of the memory area by
.Fa sz .
Type of the code is specified by
.Fa type .
Currently, only n-code is supported and
.Dv NPF_CODE_NCODE
should be passed.
.\" ---
.It Fn npf_rule_insert
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.
.Pp
Priority is the order of the rule in the ruleset.
Lower value means first to process, higher value - last to process.
If multiple rules have the same priority - order is unspecified.
A special constant
.Dv NPF_PRI_NEXT
may be passed to use the value of last used priority incremented by 1.
.It npf_rule_setproc
Set procedure for the specified rule.
.It Fn npf_rule_destroy
Destroy the given rule.
.El
.\" -----
.Sh RULE PROCEDURE INTERFACE
.Bl -tag -width 4n
.It Fn npf_rproc_create
Create a rule procedure with a given
.Fa name .
Name must be unique for each procedure.
.It Fn npf_rproc_insert
Insert rule procedure into the specified configuration.
.El
.\" -----
.Sh TRANSLATION INTERFACE
.Bl -tag -width 4n
.It Fn npf_nat_create
Create a NAT translation policy of a specified type.
There are two types:
.Bl -tag -width indent
.It Dv NPF_NATIN
Inbound NAT policy.
.It Dv NPF_NATOUT
Outbound NAT policy.
.El
.Pp
A bi-directional NAT is obtained by combining two policies.
The following flags are supported:
.Bl -tag -width indent
.It Dv NPF_NAT_PORTS
Indicates to perform port translation.
Otherwise, port translation is not performed and
.Fa port
is ignored.
.It Dv NPF_NAT_PORTMAP
Effective only if
.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
.Fa addr ,
and its family by
.Fa fa .
Family must be either
.Dv AF_INET
for IPv4 or
.Dv AF_INET6
for IPv6 address.
.It Fn npf_nat_insert
Insert NAT policy, its rule, into the specified configuration.
.El
.\" -----
.Sh TABLE INTERFACE
.Bl -tag -width 4n
.It Fn npf_table_create
Create NPF table of specified type.
The following types are supported:
.Bl -tag -width indent
.It Dv NPF_TABLE_HASH
Indicates to use hash table for storage.
.It Dv NPF_TABLE_RBTREE
Indicates to use red-black tree for storage.
Table is identified by
.Fa index ,
which should be in the range between 1 and
.Dv NPF_MAX_TABLE_ID .
.El
.It Fn npf_table_add_entry
Add an entry of IPv4 address and mask, specified by
.Fa addr
and
.Fa mask ,
to the table specified by
.Fa tl .
.It Fn npf_table_exists_p
Determine whether table with ID
.Fa tid
exists in the configuration
.Fa ncf .
Return
.Dv true
if exists, and
.Dv false
otherwise.
.It Fn npf_table_insert
Insert table into set of configuration.
Routine performs a check for duplicate table ID.
.It Fn npf_table_destroy
Destroy the specified table.
.El
.\" -----
.Sh TABLE INTERFACE
.Bl -tag -width 4n
.It Fn npf_update_rule
.It Fn npf_sessions_send
Read the file specified by
.Fa fpath ,
and send sessions saved in it to the kernel.
.It Fn npf_sessions_recv
Receive currently loaded session from the kernel, and save them to a file
specified by
.Fa fpath .
.El
.\" -----
.Sh SEE ALSO
.Xr npfctl 8 ,
.Xr npf_ncode 9
.Sh HISTORY
The NPF library first appeared in
.Nx 6.0 .