 @@ -1,235 +1,255 @@
-.\"    $NetBSD: npf.conf.5,v 1.15 2012/08/13 01:18:31 rmind Exp $
+.\"    $NetBSD: npf.conf.5,v 1.16 2012/09/26 21:58:27 rmind Exp $
 .\"
 .\" Copyright (c) 2009-2012 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 August 12, 2012
+.Dd September 26, 2012
 .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 NPF packet filter.
 It can contain definitions, grouped rules, rule procedures,
 translation policies, and tables.
 .Ss Definitions
 Definitions are general purpose keywords which can be used in the
 ruleset to make it more flexible and easier to manage.
 Most commonly, definitions are used to define one of the following:
 IP addresses, networks, ports, or interfaces.
 Definitions can contain multiple elements.
 .Ss Groups
 Having one huge ruleset for all interfaces or directions might be
 inefficient; therefore, NPF requires that all rules be defined within groups.
 Groups can be thought of as higher level rules which have subrules.
 The main properties of a group are its interface and traffic direction.
 Packets matching group criteria are passed to the ruleset of that group.
 If a packet does not match any group, it is passed to the default group.
 The default group must always be defined.
 .Ss Rules
 Rules, which are the main part of NPF configuration, describe the criteria
 used to inspect and make decisions about packets.
 Currently, NPF supports filtering on the following criteria: interface,
 traffic direction, protocol, IP address or network, TCP/UDP port
 or range, TCP flags, and ICMP type/code.
 Supported actions are blocking or passing the packet.
 .Pp
 Each rule has a priority, which is set according to its order in the ruleset.
 Rules defined first are accordingly inspected first.
 All rules in the group are inspected sequentially, and the last matching
 dictates the action to be taken.
 Rules, however, may be explicitly marked as final.
 In such cases, processing stops after encountering the first matching rule
 marked as final.
 If there is no matching rule in the custom group, then rules in the default
 group will be inspected.
 .Pp
 Stateful filtering is supported using the "stateful" keyword.
 In such cases, state (a session) is created and any further packets
 of the connection are tracked.
 Packets in backwards stream, after having been confirmed to belong to
 the same connection, are passed without ruleset inspection.
 Rules may have associated rule procedures (described in a later section),
 which are applied for all packets of a connection.
 .Pp
 Definitions (prefixed with "$") and tables (specified by an ID within
 "\*[Lt]\*[Gt]" marks) can be used in the filter options of rules.
 .Ss Rule procedures and normalisation
 Rule procedures are provided to perform packet transformations and various
 additional procedures on the packets.
 It should be noted that rule procedures are applied for the connections,
 that is, both for packets which match the rule and for further packets
 of the connection, which are passed without ruleset inspection.
 Currently, two facilities are supported:
 traffic normalisation and packet logging.
 Packet normalisation has the following functionality:
 IP ID randomisation, IP_DF flag cleansing, TCP minimum TTL enforcement,
 and maximum MSS enforcement ("MSS clamping").
 If a matching rule is going to drop the packet, normalisation functions
 are not performed.
 Packet logging is performed both in packet passing and blocking cases.
 Note that the logging interface has to be created manually, using
 .Xr ifconfig 8
 routine, for example:
 .Pp
 ifconfig npflog0 create
 .Ss Network address translation
 Rules for address translation can be added.
 Translation is performed on the specified interface, assigning the specified
 address of said interface.
 Currently, three types of translation are supported:
 Network Address Port Translation (NAPT) - a regular NAT,
 also known as "outbound NAT";
 Port forwarding (redirection) - also known as "inbound NAT";
 Bi-directional NAT - a combination of inbound and outbound NAT.
 .Pp
 Minimal filtering criteria on local network and destination are provided.
 Note that address translation implies routing, therefore IP forwarding
 is required to be enabled:
 net.inet.ip.forwarding = 1.
 See
 .Xr sysctl 7
 for more details.
 .Ss Tables
 Certain configurations might use very large sets of IP addresses or change
 sets frequently.
 Storing large IP sets in the configuration file or performing frequent
 reloads can have a significant performance cost.
 .Pp
 In order to achieve high performance, NPF has tables.
 NPF tables provide separate storage designed for large IP sets and frequent
 updates without reloading the entire ruleset.
 Tables can be managed dynamically or loaded from a separate file, which
 is useful for large static tables.
 There are two types of storage: "tree" (red-black tree is used) and
 "hash".
 .\" -----
 .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
-line		= ( def | table | map | group | rproc )
+; Syntax of a single line.  Lines can be separated by LF (\n) or
 ; a semicolon.  Comments start with a hash (#) character.
-var		= $\*[Lt]name\*[Gt]
+syntax		= var-def | table-def | map | group | rproc | comment
 iface		= ( \*[Lt]interface\*[Gt] | var )
-def		= ( var "=" "{ "\*[Lt]value_1\*[Gt]", "\*[Lt]value_2\*[Gt]", ... }" | "\*[Lt]value\*[Gt]" )
+; Variable definition.  Names can be alpha-numeric, including "_" character.
-table		= "table" \*[Lt]tid\*[Gt] "type" ( "hash" | "tree" )
+var-name	= "$" . string
-		  ( "dynamic" | "file" \*[Lt]path\*[Gt] )
+interface	= interface-name | var-name
 var-def		= var "=" ( var-value | "{" value *[ "," value ] "}" )
 map-di		= ( "->" | "<-" | "<->" )
-map-type	= ( "static" | "dynamic" )
+; Table definition.  Table ID shall be numeric.  Path is in the double quotes.
 map		= "map" iface map-type \*[Lt]seg1\*[Gt] map-di \*[Lt]seg2\*[Gt] [ "pass" filt-opts ]
 table-id	= \*[Lt]tid\*[Gt]
-rproc		= "procedure" \*[Lt]name\*[Gt] procs
+table-def	= "table" table-id "type" ( "hash" | "tree" )
-procs		= "{" op1 \*[Lt]newline\*[Gt], op2 \*[Lt]newline\*[Gt], ... "}"
+		  ( "dynamic" | "file" path )
 op		= ( "log" iface | "normalise" "(" norm-opt1 "," norm-opt2 ... ")" )
-norm-opt	= [ "random-id" | "min-ttl" \*[Lt]num\*[Gt] | "max-mss" \*[Lt]num\*[Gt] | "no-df" ]
+; Mapping for address translation.
-group		= "group" "(" ( "default" | group-opts ) ")" ruleset
+map		= "map" interface ( "static" | "dynamic" )
-group-opts	= [ name \*[Lt]name\*[Gt] "," ] "interface" iface [ "," ( "in" | "out" ) ]
+		  net-seg ( "->" | "<-" | "<->" ) net-seg
 		  [ "pass" filt-opts ]
 ruleset		= "{" rule1 \*[Lt]newline\*[Gt], rule2 \*[Lt]newline\*[Gt], ... "}"
 ; Rule procedure definition.  The name should be in the double quotes.
 rule		= ( "block" block-opts | "pass" ) [ "stateful" ] [ "in" | out" ] [ "final" ]
-		  [ "on" iface ] [ "family" fam-opt ] [ "proto" \*[Lt]protocol\*[Gt] [ proto-opts ] ]
+; Each call can have its own options in a form of key-value pairs.
-		  ( "all" | filt-opts ) [ "apply" rproc ] }
+; Both key and values may be strings (either in double quotes or not)
 ; and numbers, depending on the extension.
 fam-opt		= [ "inet" | "inet6" ]
-block-opts	= [ "return-rst" | "return-icmp" | "return" ]
+proc		= "procedure" proc-name "{" *( proc-call [ new-line ] ) "}"
-filt-addr	= iface | var | \*[Lt]addr/mask\*[Gt] | \*[Lt]tid\*[Gt]
+proc-opts	= key " " val [ "," proc-opts ]
-port-opts	= [ "port" ( \*[Lt]port-num\*[Gt] | \*[Lt]port-from\*[Gt] "-" \*[Lt]port-to\*[Gt] | var ) ]
+proc-call	= call-name ":" proc-opts new-line
 filt-opts	= [ "from" filt-addr [ port-opts ] ] [ "to" filt-addr [ port-opts ] ]
-proto-opts	= [ "flags" \*[Lt]tcp_flags\*[Gt] | "icmp-type" \*[Lt]type\*[Gt] "code" \*[Lt]code\*[Gt] ]
+; 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 )
 .Ed
 .\" -----
 .Sh FILES
 .Bl -tag -width /dev/npf.conf -compact
 .It Pa /dev/npf
 control device
 .It Pa /etc/npf.conf
 default configuration file
 .El
 .\" -----
 .Sh EXAMPLES
 .Bd -literal
 $ext_if = "wm0"
 $int_if = "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 9022
 procedure "log" {
 	log: npflog0
+}
 procedure "rid" {
 	normalise: "random-id"
 group (name "external", interface $ext_if) {
-	pass stateful out final from $ext_if apply "rid"
+	pass stateful out final from $ext_if
 	block in final from \*[Lt]1\*[Gt]
 	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 \*[Lt]2\*[Gt]
 	pass out final all
+}
 group (default) {
 	pass final on lo0 all
 	block all
+}
 .Ed
 .\" -----
 .Sh SEE ALSO
 .Xr npfctl 8 ,
 .Xr npf_ncode 9
 .Sh HISTORY
 NPF first appeared in
 .Nx 6.0 .
 .Sh AUTHORS
 NPF was designed and implemented by
 .An Mindaugas Rasiukevicius .