usr.sbin/npf/npfctl/npf.conf.5
author christos <christos@NetBSD.org>
Fri, 26 Dec 2014 22:44:54 +0000
branchtrunk
changeset 232362 4cfc157334f8
parent 228984 c74631d76788
child 233192 6f7df4138496
permissions -rw-r--r--
allow turning off the bpf jit loading.

.\"    $NetBSD: npf.conf.5,v 1.43 2014/12/26 22:44:54 christos Exp $
.\"
.\" Copyright (c) 2009-2014 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 December 26, 2014
.Dt NPF.CONF 5
.Os
.Sh NAME
.Nm npf.conf
.Nd NPF packet filter configuration file
.\" -----
.Sh DESCRIPTION
.Nm
is the default configuration file for the NPF packet filter.
.Pp
This manual page serves as a reference for editing
.Nm .
Please refer to the official NPF documentation for comprehensive and
in-depth information.
.Pp
There are multiple structural elements
.Nm
may contain:
.Cd variable
and
.Cd table
definitions (with or without content), abstraction
.Cd groups ,
packet filtering
.Cd rules ,
.Cd map
rules for address translation and
.Cd procedure
definitions to call on filtered packets.
The minimal
.Nm
must contain a mandatory
.Cd default group .
.Sh SYNTAX
.Ss 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:
.Bd -literal
$var1 = 10.0.0.1
.Ed
.Pp
A variable may also be defined as a set:
.Bd -literal
$var2 = { 10.0.0.1, 10.0.0.2 }
.Ed
.Pp
Common variable definitions are for IP addresses, networks, ports,
and interfaces.
.Ss Tables
Tables are specified using a name between angle brackets
\*[Lt] and \*[Gt].
The following is an example of table definition:
.Bd -literal
table <black> type hash dynamic
.Pp
.Ed
Currently, tables support three storage types: "hash", "tree", or "cdb".
They can also be "dynamic" or static i.e. loaded from the specified file.
.Pp
The file should contain a list of IP addresses and/or networks in the form of:
.Bd -literal
10.0.0.0/24
10.1.1.1
.Ed
.Pp
Tables of type "hash" and "cdb" can only contain IP addresses.
Also, the latter can only be static.
.Ss Interfaces
Interfaces can be specified as the values of the variables:
.Pp
.Bd -literal
$pub_if_list = { inet4(wm0), inet4(wm1) }
.Ed
.Pp
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.:
.Bd -literal
$pub_if4 = inet4(wm0)
$pub_if46 = { inet4(wm0), inet6(wm0) }
.Ed
.Ss Groups
Groups may have the following options: name, interface, and direction.
They are defined in the following form:
.Pp
.Bd -literal
group "my-name" in on wm0 {
	# List of rules
}
.Ed
.Ss Rules
With a rule statement NPF is instructed to
.Cd pass
or
.Cd block
a packet depending on packet header information, transit direction and
interface it arrives on, either immediately upon match (keyword
.Cd 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.
.Pp
A "fully-featured" rule would for example be:
.Bd -literal
pass stateful in final family inet4 proto tcp flags S/SA \\
	from $source port $sport to $dest port $dport apply "someproc"
.Ed
.Pp
Any protocol in
.Pa /etc/protocols
can be specified.
Further packet
specification 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.
.Pp
Alternatively, NPF supports
.Xr pcap-filter 7
syntax, for example:
.Bd -literal
block out final pcap-filter "tcp and dst 10.1.1.252"
.Ed
.Pp
Fragments are not selectable since NPF always reassembles packets
before further processing.
.Ss Stateful
Stateful packet inspection is enabled using
.Cd stateful
or
.Cd stateful-ends
keywords.
The former creates a state which is uniquely identified by a 5-tuple (source
and destination IP addresses, port numbers and an interface identifier).
The latter excludes the interface identifier and must be used with
precaution.
In both cases, a full TCP state tracking is performed for TCP connections
and a limited tracking for message-based protocols (UDP and ICMP).
.Pp
By default, a stateful rule implies SYN-only flag check ("flags S/SAFR")
for the TCP packets.
It is not advisable to change this behavior; however,
it can be overridden with the
.Cd flags
keyword.
.Ss Map
Network Address Translation (NAT) is expressed in a form of segment mapping.
The translation may be dynamic (stateful) or static (stateless).
The following mapping types are available:
.Pp
.Bl -tag -width <-> -compact
.It Pa ->
outbound NAT (translation of the source)
.It Pa <-
inbound NAT (translation of the destination)
.It Pa <->
bi-directional NAT (combination of inbound and outbound NAT)
.El
.Pp
The following would translate the source to the IP address specified
by the $pub_ip for the packets on the interface $ext_if.
.Bd -literal
map $ext_if dynamic 10.1.1.0/24 -> $pub_ip
.Ed
.Pp
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 criteria can be specified using "pass <criteria>" as
an additional option of the mapping.
.Ss 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:
.Bd -literal
procedure "someproc" {
	log: npflog0
	normalize: "random-id", "min-ttl" 64
}
.Ed
.Pp
In this case, the procedure calls the logging and normalisation modules.
.Ss Misc
Text after a hash
.Pq Sq #
character is considered a comment.
The backslash
.Pq Sq \e
character at the end of a line marks a continuation line,
i.e., the next line is considered an extension of the present line.
.Sh 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.
.Bd -literal
; 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 ] "}" )

; Parameter setting
set-statement	= "set" parameter value

; Table definition.  Table ID shall be numeric.  Path is in the double quotes.

table-id	= \*[Lt]table-name\*[Gt]
table-def	= "table" table-id "type" ( "hash" | "tree" | "cdb" )
		  ( "dynamic" | "file" path )

; Mapping for address translation.

map		= "map" interface
		  ( "static" [ "algo" algorithm ] | "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 rule list.

group		= "group" ( "default" | group-opts ) "{" rule-list "}"
group-opts	= name-string [ "in" | "out" ] [ "on" interface ]
rule-list	= [ rule new-line ] rule-list

npf-filter	= [ "family" family-opt ] [ "proto" protocol [ proto-opts ] ]
		  ( "all" | filt-opts )
static-rule	= ( "block" [ block-opts ] | "pass" )
		  [ "stateful" | "stateful-ends" ]
		  [ "in" | out" ] [ "final" ] [ "on" interface ]
		  ( npf-filter | "pcap-filter" pcap-filter-expr )
		  [ "apply" proc-name ]

dynamic-ruleset	= "ruleset" group-opts
rule		= static-rule | dynamic-ruleset

block-opts	= "return-rst" | "return-icmp" | "return"
family-opt	= "inet4" | "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 )
.Ed
.\" -----
.Sh FILES
.Bl -tag -width /usr/share/examples/npf -compact
.It Pa /dev/npf
control device
.It Pa /etc/npf.conf
default configuration file
.It Pa /usr/share/examples/npf
directory containing further examples
.El
.\" -----
.Sh EXAMPLES
.Bd -literal
$ext_if = { inet4(wm0), inet6(wm0) }
$int_if = { inet4(wm1), inet6(wm1) }

table <blacklist> type hash file "/etc/npf_blacklist"
table <limited> 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 "external" on $ext_if {
	pass stateful out final all

	block in final from \*[Lt]blacklist\*[Gt]
	pass stateful in final family inet4 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 "internal" on $int_if {
	block in all
	block in final from \*[Lt]limited\*[Gt]

	# Ingress filtering as per BCP 38 / RFC 2827.
	pass in final from $localnet
	pass out final all
}

group default {
	pass final on lo0 all
	block all
}
.Ed
.\" -----
.Sh SEE ALSO
.Xr bpf 4 ,
.Xr npf 7 ,
.Xr pcap-filter 7 ,
.Xr npfctl 8
.Sh HISTORY
NPF first appeared in
.Nx 6.0 .
.Sh AUTHORS
NPF was designed and implemented by
.An Mindaugas Rasiukevicius .