1.\" $NetBSD: npf.conf.5,v 1.4 2011/02/02 02:20:25 rmind Exp $ 2.\" 3.\" Copyright (c) 2009-2011 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 February 2, 2011 31.Dt NPF.CONF 5 32.Os 33.Sh NAME 34.Nm npf.conf 35.Nd NPF packet filter configuration file 36.\" ----- 37.Sh DESCRIPTION 38.Nm 39is the default configuration file for NPF packet filter. 40It can contain definitions, grouped rules, rule procedures, and tables. 41.Sh DEFINITIONS 42Definitions are general purpose keywords which can be used in the 43ruleset to make it more flexible and easier to manage. 44Most commonly, definitions are used to define one of the following: 45IP addresses, networks, ports, or interfaces. 46Definitions can contain multiple elements. 47.Sh GROUPS 48Having one huge ruleset for all interfaces or directions might be 49inefficient; therefore, NPF requires that all rules be defined within groups. 50Groups can be thought of as higher level rules which have subrules. 51The main properties of a group are its interface and traffic direction. 52Packets matching group criteria are passed to the ruleset of that group. 53If a packet does not match any group, it is passed to the default group. 54The default group must always be defined. 55.Sh RULES 56Rules, which are the main part of NPF configuration, describe the criteria 57used to inspect and make decisions about packets. 58Currently, NPF supports filtering on the following criteria: interface, 59traffic direction, protocol, IPv4 address or network, TCP/UDP port 60or range, TCP flags, and ICMP type/code. 61Supported actions are blocking or passing the packet. 62.Pp 63Each rule has a priority, which is set according to its order in the ruleset. 64Rules defined first are accordingly inspected first. 65All rules in the group are inspected sequentially, and the last matching 66dictates the action to be taken. 67Rules, however, may be explicitly marked as final (that is, "quick"). 68In such cases, processing stops after encountering the first matching rule 69marked as final. 70If there is no matching rule in the custom group, then rules in the default 71group will be inspected. 72.Pp 73Stateful filtering is supported using the "keep state" keyword. 74In such cases, state (a session) is created and any further packets 75of the connection are tracked. 76Packets in backwards stream, after having been confirmed to belong to 77the same connection, are passed without ruleset inspection. 78Rules may have associated rule procedures (described in a later section), 79which are applied for all packets of a connection. 80.Pp 81Definitions (prefixed with "$") and tables (specified by an ID within 82"\*[Lt]\*[Gt]" marks) can be used in the filter options of rules. 83.Sh RULE PROCEDURES AND NORMALIZATION 84Rule procedures are provided to perform packet transformations and various 85additional procedures on the packets. 86It should be noted that rule procedures are applied for the connections, 87that is, both for packets which match the rule and for further packets 88of the connection, which are passed without ruleset inspection. 89Currently, two facilities are supported: 90traffic normalization and packet logging. 91Packet normalization has the following functionality: 92IP ID randomization, IP_DF flag cleansing, TCP minimum TTL enforcement, 93and maximum MSS enforcement ("MSS clamping"). 94If a matching rule is going to drop the packet, normalization functions 95are not performed. 96Packet logging is performed both in packet passing and blocking cases. 97.Sh NAT 98Rules for address translation can be added. 99Translation is performed on the specified interface, assigning the specified 100address of said interface. 101There are three types of translation: 102Network Address Port Translation (NAPT) - a regular NAT, 103also known as "outbound NAT"; 104Port forwarding (redirection) - also known as "inbound NAT"; 105Bi-directional NAT - a combination of inbound and outbound NAT. 106.Pp 107Minimal filtering criteria on local network and destination are provided. 108Note that address translation implies routing, therefore IP forwarding 109is required to be enabled: 110net.inet.ip.forwarding = 1. 111See 112.Xr sysctl 7 113for more details. 114.Sh TABLES 115Certain configurations might use very large sets of IP addresses or change 116sets frequently. 117Storing large IP sets in the configuration file or performing frequent 118reloads can have a significant performance cost. 119.Pp 120In order to achieve high performance, NPF has tables. 121NPF tables provide separate storage designed for large IP sets and frequent 122updates without reloading the entire ruleset. 123Tables can be managed dynamically or loaded from a separate file, which 124is useful for large static tables. 125There are two types of storage: "tree" (red-black tree is used) and 126"hash". 127.\" ----- 128.Sh GRAMMAR 129.Bd -literal 130line = ( def | table | nat | group | rproc ) 131 132def = ( \*[Lt]name\*[Gt] "=" "{ a, b, ... }" | "\*[Lt]text\*[Gt]" | "$\*[Lt]interface\*[Gt]" ) 133iface = ( \*[Lt]interface\*[Gt] | def ) 134 135table = "table" \*[Lt]tid\*[Gt] "type" ( "hash" | "tree" ) 136 ( "dynamic" | "file" \*[Lt]path\*[Gt] ) 137 138nat = "nat" iface filt-opts "->" \*[Lt]addr\*[Gt] 139binat = "binat" iface filt-opts "->" \*[Lt]addr\*[Gt] 140rdr = "rdr" iface filt-opts "->" \*[Lt]addr\*[Gt] port-opts 141 142rproc = "procedure" \*[Lt]name\*[Gt] procs 143procs = "{" op1 \*[Lt]newline\*[Gt], op2 \*[Lt]newline\*[Gt], ... "}" 144op = ( "log" iface | "normalize" "(" norm-opt1 "," norm-opt2 ... ")" ) 145norm-opt = [ "random-id" | "min-ttl" \*[Lt]num\*[Gt] | "max-mss" \*[Lt]num\*[Gt] | "no-df" ] 146 147group = "group" "(" ( "default" | group-opts ) ")" ruleset 148group-opts = "interface" iface "," [ "in" | "out" ] 149 150ruleset = "{" rule1 \*[Lt]newline\*[Gt], rule2 \*[Lt]newline\*[Gt], ... "}" 151 152rule = ( "block" block-opts | "pass" ) [ "in" | out" ] [ "quick" ] 153 [ "on" iface ] [ "inet" | "inet6" ] [ "proto" \*[Lt]protocol\*[Gt] ] 154 ( "all" | filt-opts [ "flags" \*[Lt]tcp_flags> \*[Gt] ) 155 [ "keep state" ] [ "apply" rproc } 156 157block-opts = [ "return-rst" | "return-icmp" | "return" ] 158filt-opts = [ "from" ( iface | def | \*[Lt]addr/mask\*[Gt] | \*[Lt]tid\*[Gt] ) port-opts ] 159 [ "to" ( iface | def | \*[Lt]addr/mask\*[Gt] | \*[Lt]tid\*[Gt] ) port-opts ] 160port-opts = [ "port" ( \*[Lt]port-num\*[Gt] | \*[Lt]port-from\*[Gt] ":" \*[Lt]port-to\*[Gt] | def ) ] 161proto-opts = [ "flags" \*[Lt]tcp_flags\*[Gt] | "icmp-type" \*[Lt]type\*[Gt] "code" \*[Lt]code\*[Gt] ] 162.Ed 163.\" ----- 164.Sh FILES 165.Bl -tag -width /dev/npf.conf -compact 166.It Pa /dev/npf 167control device 168.It Pa /etc/npf.conf 169default configuration file 170.El 171.\" ----- 172.Sh EXAMPLES 173.Bd -literal 174ext_if = "wm0" 175int_if = "wm1" 176 177services_tcp = "{ http, https, smtp, domain, 6000 }" 178services_udp = "{ domain, ntp, 6000 }" 179 180table "1" type "hash" file "/etc/npf_blacklist" 181table "2" type "tree" dynamic 182 183nat $ext_if from 192.168.0.0/24 to any -> $ext_if 184 185procedure "log" { 186 log npflog0 187} 188 189procedure "rid" { 190 normalize (random-id) 191} 192 193group (name "external", interface $ext_if) { 194 block in quick from \*[Lt]1\*[Gt] 195 pass out quick from $ext_if keep state apply "rid" 196 197 pass in quick inet proto tcp to $ext_if port ssh apply "log" 198 pass in quick proto tcp to $ext_if port $services_tcp 199 pass in quick proto udp to $ext_if port $services_udp 200 pass in quick proto tcp to $ext_if port 49151:65535 # Passive FTP 201 pass in quick proto udp to $ext_if port 33434:33600 # Traceroute 202} 203 204group (name "internal", interface $int_if) { 205 block in all 206 pass in quick from \*[Lt]2\*[Gt] 207 pass out quick all 208} 209 210group (default) { 211 block all 212} 213.Ed 214.\" ----- 215.Sh SEE ALSO 216.Xr npfctl 8 , 217.Xr npf_ncode 9 218.Sh HISTORY 219NPF first appeared in 220.Nx 6.0 . 221