NPF.CONF(5) BSD File Formats Manual NPF.CONF(5)NAMEnpf.conf — NPF packet filter configuration file
DESCRIPTIONnpf.conf is the default configuration file for the NPF packet filter.
This manual page serves as a reference for editing npf.conf. Please
refer to the official NPF documentation for comprehensive and in-depth
information.
There are multiple structural elements npf.conf may contain: variable and
table definitions (with or without content), abstraction groups, packet
filtering rules, map rules for address translation and procedure defini‐
tions to call on filtered packets. The minimal npf.conf must contain a
mandatory default group.
SYNTAX
Variables
Variables are specified using the dollar ($) sign, which is used both in
definitions and uses of a variable. Variables are defined by assigning a
value to them as follows:
$var1 = 10.0.0.1
A variable may also be defined as a set:
$var2 = { 10.0.0.1, 10.0.0.2 }
Common variable definitions are for IP addresses, networks, ports, and
interfaces.
Tables
Tables are specified using a number between angle brackets < and >. The
number used to specify a table should be between 0 and 15. The following
is an example of table definition:
table <1> type hash dynamic
Currently, tables support two storage types: "hash" or "tree". They can
also be "dynamic" or static i.e. loaded from the specified file.
The file should contain a list of IP addresses and/or networks in the
form of:
10.0.0.0/24
10.1.1.1
Tables of type "hash" can only contain IP addresses.
Interfaces
Interfaces can be specified as the values of the variables:
$pub_if_list = { ifnet(wm0), ifnet(wm1) }
In the context of filtering, an interface provides a list of its all IP
addresses, including IPv4 and IPv6. Specific interface addresses can be
selected by the family, e.g.:
$pub_if4 = inet4(wm0)
$pub_if6 = { inet6(wm0) }
Groups
Groups may have the following options: name, interface, and direction.
They are defined in the following form:
group (name "my_group", interface wm0, in) {
# List of rules
}
Rules
With a rule statement NPF is instructed to pass or block a packet depend‐
ing on packet header information, transit direction and interface it
arrives on, either immediately upon match (keyword final) or using the
last match. The rule can also instruct NPF to create an entry in the
state table when passing the packet, to notify the sender when blocking
it, and to apply a procedure to the packet (e.g. "log") in either case.
A "fully-featured" rule would for example be:
pass stateful in final family inet proto tcp flags S/SA \
from $source port $sport to $dest port $dport apply "someproc"
Any protocol in /etc/protocols can be specified. Further packet specifi‐
cation at present is limited to protocol TCP understanding flags, TCP and
UDP understanding source and destination ports, and ICMP and IPv6-ICMP
understanding icmp-type.
Fragments are not selectable since NPF always reassembles packets before
further processing.
Map
Network Address Translation (NAT) is expressed in a form of segment map‐
ping. At present, only dynamic translation is supported. The following
mapping types are available:
-> outbound NAT (translation of the source)
<- inbound NAT (translation of the destination)
<-> bi-directional NAT (combination of inbound and outbound NAT)
The following would translate the source to the IP address specified by
the $pub_ip for the packets on the interface $ext_if.
map $ext_if dynamic 10.1.1.0/24 -> $pub_ip
Translations are implicitly filtered by limiting the operation to the
network segments specified, that is, translation would be performed only
on packets originating from 10.1.1.0/24 network. Explicit filter crite‐
ria can be specified using "pass <criteria>" as an additional option of
the mapping.
Procedures
A rule procedure is defined as a collection of extension calls (it may
have none). Every extension call has a name and a list of options in the
form of key-value pairs. Depending on the call, the key might represent
the argument and the value might be optional. For example:
procedure "someproc" {
log: npflog0
normalise: "random-id", "min-ttl" 64
}
In this case, the procedure calls the logging and normalisation modules.
Misc
Text after a hash (‘#’) character is considered a comment. The backslash
(‘\’) character at the end of a line marks a continuation line, i.e., the
next line is considered an extension of the present line.
GRAMMAR
The following is a non-formal BNF-like definition of the grammar. The
definition is simplified and is intended to be human readable, therefore
it does not strictly represent the full syntax, which is more flexible.
; Syntax of a single line. Lines can be separated by LF (\n) or
; a semicolon. Comments start with a hash (#) character.
syntax = var-def | table-def | map | group | rproc | comment
; Variable definition. Names can be alpha-numeric, including "_" character.
var-name = "$" . string
interface = interface-name | var-name
var-def = var "=" ( var-value | "{" value *[ "," value ] "}" )
; Table definition. Table ID shall be numeric. Path is in the double quotes.
table-id = <tid>
table-def = "table" table-id "type" ( "hash" | "tree" )
( "dynamic" | "file" path )
; Mapping for address translation.
map = "map" interface ( "static" | "dynamic" )
net-seg ( "->" | "<-" | "<->" ) net-seg
[ "pass" filt-opts ]
; Rule procedure definition. The name should be in the double quotes.
;
; Each call can have its own options in a form of key-value pairs.
; Both key and values may be strings (either in double quotes or not)
; and numbers, depending on the extension.
proc = "procedure" proc-name "{" *( proc-call [ new-line ] ) "}"
proc-opts = key " " val [ "," proc-opts ]
proc-call = call-name ":" proc-opts new-line
; Group definition and the ruleset.
group = "group" "(" ( "default" | group-opts ) ")" "{" ruleset "}"
group-opts = [ "name" string ] [ "interface" interface ] [ "in" | "out" ]
ruleset = [ rule new-line ] [ ruleset ]
rule = ( "block" [ block-opts ] | "pass" ) [ "stateful" ]
[ "in" | out" ] [ "final" ] [ "on" iface ]
[ "family" fam-opt ] [ "proto" protocol [ proto-opts ] ]
( "all" | filt-opts ) [ "apply" proc-name ]
block-opts = "return-rst" | "return-icmp" | "return"
fam-opt = "inet" | "inet6"
proto-opts = "flags" tcp-flags [ "/" tcp-flag-mask ] |
"icmp-type" type [ "code" icmp-code ]
addr-mask = addr [ "/" mask ]
filt-opts = "from" filt-addr [ port-opts ] "to" filt-addr [ port-opts ]
filt-addr = [ interface | var-name | addr-mask | table-id | "any" ]
filt-port = "port" ( port-num | port-from "-" port-to | var-name )
FILES
/dev/npf control device
/etc/npf.conf default configuration file
/usr/share/examples/npf directory containing further examples
EXAMPLES
$ext_if = ifnet(wm0)
$int_if = ifnet(wm1)
table <1> type hash file "/etc/npf_blacklist"
table <2> type tree dynamic
$services_tcp = { http, https, smtp, domain, 6000, 9022 }
$services_udp = { domain, ntp, 6000 }
$localnet = { 10.1.1.0/24 }
# Note: if $ext_if has multiple IP address (e.g. IPv6 as well),
# then the translation address has to be specified explicitly.
map $ext_if dynamic 10.1.1.0/24 -> $ext_if
map $ext_if dynamic 10.1.1.2 port 22 <- $ext_if port 9022
procedure "log" {
# Note: npf_ext_log kernel module should be loaded, if not built-in.
# Also, the interface created, e.g.: ifconfig npflog0 create
log: npflog0
}
group (name "external", interface $ext_if) {
pass stateful out final all
block in final from <1>
pass stateful in final family inet proto tcp to $ext_if port ssh apply "log"
pass stateful in final proto tcp to $ext_if port $services_tcp
pass stateful in final proto udp to $ext_if port $services_udp
pass stateful in final proto tcp to $ext_if port 49151-65535 # Passive FTP
pass stateful in final proto udp to $ext_if port 33434-33600 # Traceroute
}
group (name "internal", interface $int_if) {
block in all
pass in final from <2>
pass out final all
}
group (default) {
pass final on lo0 all
block all
}
SEE ALSOnpfctl(8), npf_ncode(9)HISTORY
NPF first appeared in NetBSD 6.0.
AUTHORS
NPF was designed and implemented by Mindaugas Rasiukevicius.
BSD January 11, 2013 BSD
