363 lines
11 KiB
Groff
363 lines
11 KiB
Groff
.\" $NetBSD: npf.conf.5,v 1.41 2014/05/15 23:52:32 wiz 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 May 15, 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 ] "}" )
|
|
|
|
; 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 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 .
|