1.\" $NetBSD: libnpf.3,v 1.2 2014/08/03 00:02:56 rmind Exp $ 2.\" 3.\" Copyright (c) 2011-2013 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This material is based upon work partially supported by The 7.\" NetBSD Foundation under a contract with Mindaugas Rasiukevicius. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd August 2, 2014 31.Dt LIBNPF 3 32.Os 33.Sh NAME 34.Nm libnpf 35.Nd NPF packet filter library 36.Sh LIBRARY 37.Lb libnpf 38.Sh SYNOPSIS 39.In npf.h 40.\" --- 41.Ft nl_config_t * 42.Fn npf_config_create "void" 43.Ft int 44.Fn npf_config_submit "nl_config_t *ncf" "int fd" 45.Ft void 46.Fn npf_config_destroy "nl_config_t *ncf" 47.Ft int 48.Fn npf_config_flush "int fd" 49.\" --- 50.Ft nl_rule_t * 51.Fn npf_rule_create "char *name" "uint32_t attr" "const char *ifname" 52.Ft int 53.Fn npf_rule_setcode "nl_rule_t *rl" "int type" "const void *code" "size_t len" 54.Ft int 55.Fn npf_rule_setkey "nl_rule_t *rl" "int type" "const void *code" "size_t len" 56.Ft bool 57.Fn npf_rule_exists_p "nl_config_t *ncf" "const char *name" 58.Ft int 59.Fn npf_rule_insert "nl_config_t *ncf" "nl_rule_t *parent" "nl_rule_t *rl" 60.Ft int 61.Fn npf_rule_setprio "nl_rule_t *rl" "pri_t pri" 62.Ft int 63.Fn npf_rule_setproc "nl_config_t *ncf" "nl_rule_t *rl" "const char *name" 64.Ft void 65.Fn npf_rule_destroy "nl_rule_t *rl" 66.\" --- 67.Ft nl_rproc_t * 68.Fn npf_rproc_create "char *name" 69.Ft bool 70.Fn npf_rproc_exists_p "nl_config_t *ncf" "const char *name" 71.Ft int 72.Fn npf_rproc_insert "nl_config_t *ncf" "nl_rproc_t *rp" 73.\" --- 74.Ft nl_nat_t * 75.Fn npf_nat_create "int type" "u_int flags" "const char *ifname" \ 76"npf_addr_t *addr" "int af" "in_port_t port" 77.Ft int 78.Fn npf_nat_insert "nl_config_t *ncf" "nl_nat_t *nt" "pri_t pri" 79.\" --- 80.Ft nl_table_t * 81.Fn npf_table_create "const char *name" "u_int id" "int type" 82.Ft int 83.Fn npf_table_add_entry "nl_table_t *tl" "int af" \ 84"in_addr_t addr" "in_addr_t mask" 85.Ft int 86.Fn npf_table_insert "nl_config_t *ncf" "nl_table_t *tl" 87.Ft void 88.Fn npf_table_destroy "nl_table_t *tl" 89.\" ----- 90.Sh DESCRIPTION 91The 92.Nm 93library provides an interface to create an NPF configuration having rules, 94tables, procedures, or translation policies. 95The configuration can be submitted to the kernel. 96.\" ----- 97.Sh FUNCTIONS 98.Ss Configuration 99.Bl -tag -width 4n 100.It Fn npf_config_create 101Create a configuration. 102.It Fn npf_config_submit "ncf" "fd" 103Submit configuration 104.Fa ncf 105to the kernel. 106.It Fn npf_config_destroy "ncf" 107Destroy the configuration 108.Fa ncf . 109.It Fn npf_config_flush "fd" 110Flush the current configuration. 111.El 112.\" --- 113.Ss Rule interface 114.Bl -tag -width 4n 115.It Fn npf_rule_create "name" "attr" "ifname" 116Create a rule with a given name, attribute and priorty. 117Name can be 118.Dv NULL , 119in which case rule has no unique identifier. 120Otherwise, rules shall not have duplicate names. 121The following attributes, which can be ORed, are available: 122.Bl -tag -width indent 123.It Dv NPF_RULE_PASS 124Decision of this rule is "pass". 125If this attribute is not 126specified, then packet "block" (drop) is the default. 127.It Dv NPF_RULE_FINAL 128Indicates that on rule match, further processing of the 129ruleset should be stopped and this rule applied instantly. 130.It Dv NPF_RULE_STATEFUL 131Create a state (session) on match, track the connection and 132therefore pass the backwards stream without inspection. 133.It Dv NPF_RULE_RETRST 134Return TCP RST packet in a case of packet block. 135.It Dv NPF_RULE_RETICMP 136Return ICMP destination unreachable in a case of packet block. 137.It Dv NPF_RULE_IN 138Rule may match only if incoming packet. 139.It Dv NPF_RULE_OUT 140Rule may match only if outgoing packet. 141.El 142.Pp 143Interface is specified by 144.Fa ifname , 145which is a string. 146.Dv NULL 147indicates any interface. 148.\" --- 149.It Fn npf_rule_setcode "rl" "type" "code" "len" 150Assign compiled code for the rule specified by 151.Fa rl , 152used for filter criteria. 153Pointer to the binary code is specified by 154.Fa code , 155and size of the memory area by 156.Fa len . 157Type of the code is specified by 158.Fa type . 159Currently, only n-code is supported and 160.Dv NPF_CODE_NC 161should be passed. 162.\" --- 163.It Fn npf_rule_setkey "rl" "type" "key" "len" 164Assign a key for the rule specified by 165.Fa rl . 166Binary key is specified by 167.Fa key , 168and its size by 169.Fa len . 170The size shall not exceed 171.Dv NPF_RULE_MAXKEYLEN . 172.\" --- 173.It Fn npf_rule_insert "ncf" "parent" "rl" 174Insert the rule into the set of parent rule specified by 175.Fa parent . 176If value of 177.Fa parent 178is 179.Dv NULL , 180then insert into the main ruleset. 181.\" --- 182.It Fn npf_rule_setprio "rl" "pri" 183Set priority to the rule. 184Negative priorities are invalid. 185.Pp 186Priority is the order of the rule in the ruleset. 187Lower value means first to process, higher value - last to process. 188If multiple rules are inserted with the same priority, 189the order is unspecified. 190.Pp 191The special constants 192.Dv NPF_PRI_FIRST 193and 194.Dv NPF_PRI_LAST 195can be passed to indicate that the rule should be inserted into the 196beginning or the end of the priority level 0 in the ruleset. 197All rules inserted using these constants will have the priority 0 198assigned and will share this level in the ordered way. 199.It Fn npf_rule_setproc "ncf" "rl" "name" 200Set a procedure for the specified rule. 201.It Fn npf_rule_destroy "rl" 202Destroy the given rule. 203.El 204.\" ----- 205.Ss Rule procedure interface 206.Bl -tag -width 4n 207.It Fn npf_rproc_create "name" 208Create a rule procedure with a given 209.Fa name . 210Name must be unique for each procedure. 211.It Fn npf_rproc_insert "ncf" "rp" 212Insert rule procedure into the specified configuration. 213.El 214.\" ----- 215.Ss Translation interface 216.Bl -tag -width 4n 217.It Fn npf_nat_create "type" "flags" "ifname" "addr" "af" "port" 218Create a NAT translation policy of a specified type. 219There are two types: 220.Bl -tag -width "NPF_NAT_PORTMAP " 221.It Dv NPF_NATIN 222Inbound NAT policy. 223.It Dv NPF_NATOUT 224Outbound NAT policy. 225.El 226.Pp 227A bi-directional NAT is obtained by combining two policies. 228The following 229.Fa flags 230are supported: 231.Bl -tag -width "NPF_NAT_PORTMAP " 232.It Dv NPF_NAT_PORTS 233Indicates to perform port translation. 234Otherwise, port translation is not performed and 235.Fa port 236is ignored. 237.It Dv NPF_NAT_PORTMAP 238Effective only if 239.Dv NPF_NAT_PORTS 240flag is set. 241Indicates to create a port map and select a random port for translation. 242Otherwise, port is translated to the value specified by 243.Fa port 244is used. 245.El 246.Pp 247Translation address is specified by 248.Fa addr , 249and its family by 250.Fa af . 251Family must be either 252.Dv AF_INET 253for IPv4 or 254.Dv AF_INET6 255for IPv6 address. 256.It Fn npf_nat_insert "ncf" "nt" "pri" 257Insert NAT policy, its rule, into the specified configuration. 258.El 259.\" ----- 260.Ss Table interface 261.Bl -tag -width 4n 262.It Fn npf_table_create "name" "index" "type" 263Create NPF table of specified type. 264The following types are supported: 265.Bl -tag -width "NPF_TABLE_TREE " 266.It Dv NPF_TABLE_HASH 267Indicates to use hash table for storage. 268.It Dv NPF_TABLE_TREE 269Indicates to use red-black tree for storage. 270Table is identified by the 271.Fa name 272and 273.Fa index , 274which should be in the range between 1 and 275.Dv NPF_MAX_TABLE_ID . 276.El 277.It Fn npf_table_add_entry "tl" "af" "addr" "mask" 278Add an entry of IP address and mask, specified by 279.Fa addr 280and 281.Fa mask , 282to the table specified by 283.Fa tl . 284Family, specified by 285.Fa af , 286must be either 287.Dv AF_INET 288for IPv4 or 289.Dv AF_INET6 290for IPv6 address. 291.It Fn npf_table_insert "ncf" "tl" 292Insert table into set of configuration. 293Routine performs a check for duplicate table ID. 294.It Fn npf_table_destroy "tl" 295Destroy the specified table. 296.El 297.\" ----- 298.Sh SEE ALSO 299.Xr bpf 4 , 300.Xr npf 7 , 301.Xr npfctl 8 302.Sh HISTORY 303The NPF library first appeared in 304.Nx 6.0 . 305