1.\" $NetBSD: npf.conf.5,v 1.41 2014/05/15 23:52:32 wiz Exp $ 2.\" 3.\" Copyright (c) 2009-2014 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 May 15, 2014 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 the NPF packet filter. 40.Pp 41This manual page serves as a reference for editing 42.Nm . 43Please refer to the official NPF documentation for comprehensive and 44in-depth information. 45.Pp 46There are multiple structural elements 47.Nm 48may contain: 49.Cd variable 50and 51.Cd table 52definitions (with or without content), abstraction 53.Cd groups , 54packet filtering 55.Cd rules , 56.Cd map 57rules for address translation and 58.Cd procedure 59definitions to call on filtered packets. 60The minimal 61.Nm 62must contain a mandatory 63.Cd default group . 64.Sh SYNTAX 65.Ss Variables 66Variables are specified using the dollar ($) sign, which is used both 67in definitions and uses of a variable. 68Variables are defined by assigning a value to them as follows: 69.Bd -literal 70$var1 = 10.0.0.1 71.Ed 72.Pp 73A variable may also be defined as a set: 74.Bd -literal 75$var2 = { 10.0.0.1, 10.0.0.2 } 76.Ed 77.Pp 78Common variable definitions are for IP addresses, networks, ports, 79and interfaces. 80.Ss Tables 81Tables are specified using a name between angle brackets 82\*[Lt] and \*[Gt]. 83The following is an example of table definition: 84.Bd -literal 85table <black> type hash dynamic 86.Pp 87.Ed 88Currently, tables support three storage types: "hash", "tree", or "cdb". 89They can also be "dynamic" or static i.e. loaded from the specified file. 90.Pp 91The file should contain a list of IP addresses and/or networks in the form of: 92.Bd -literal 9310.0.0.0/24 9410.1.1.1 95.Ed 96.Pp 97Tables of type "hash" and "cdb" can only contain IP addresses. 98Also, the latter can only be static. 99.Ss Interfaces 100Interfaces can be specified as the values of the variables: 101.Pp 102.Bd -literal 103$pub_if_list = { inet4(wm0), inet4(wm1) } 104.Ed 105.Pp 106In the context of filtering, an interface provides a list of its 107all IP addresses, including IPv4 and IPv6. 108Specific interface addresses can be selected by the family, e.g.: 109.Bd -literal 110$pub_if4 = inet4(wm0) 111$pub_if46 = { inet4(wm0), inet6(wm0) } 112.Ed 113.Ss Groups 114Groups may have the following options: name, interface, and direction. 115They are defined in the following form: 116.Pp 117.Bd -literal 118group "my-name" in on wm0 { 119 # List of rules 120} 121.Ed 122.Ss Rules 123With a rule statement NPF is instructed to 124.Cd pass 125or 126.Cd block 127a packet depending on packet header information, transit direction and 128interface it arrives on, either immediately upon match (keyword 129.Cd final ) 130or using the last match. 131The rule can also instruct NPF to create an entry in the state table 132when passing the packet, to notify the sender when blocking it, and 133to apply a procedure to the packet (e.g. "log") in either case. 134.Pp 135A "fully-featured" rule would for example be: 136.Bd -literal 137pass stateful in final family inet4 proto tcp flags S/SA \\ 138 from $source port $sport to $dest port $dport apply "someproc" 139.Ed 140.Pp 141Any protocol in 142.Pa /etc/protocols 143can be specified. 144Further packet 145specification at present is limited to protocol TCP understanding flags, 146TCP and UDP understanding source and destination ports, and ICMP and 147IPv6-ICMP understanding icmp-type. 148.Pp 149Alternatively, NPF supports 150.Xr pcap-filter 7 151syntax, for example: 152.Bd -literal 153block out final pcap-filter "tcp and dst 10.1.1.252" 154.Ed 155.Pp 156Fragments are not selectable since NPF always reassembles packets 157before further processing. 158.Ss Stateful 159Stateful packet inspection is enabled using 160.Cd stateful 161or 162.Cd stateful-ends 163keywords. 164The former creates a state which is uniquely identified by a 5-tuple (source 165and destination IP addresses, port numbers and an interface identifier). 166The latter excludes the interface identifier and must be used with 167precaution. 168In both cases, a full TCP state tracking is performed for TCP connections 169and a limited tracking for message-based protocols (UDP and ICMP). 170.Pp 171By default, a stateful rule implies SYN-only flag check ("flags S/SAFR") 172for the TCP packets. 173It is not advisable to change this behavior; however, 174it can be overridden with the 175.Cd flags 176keyword. 177.Ss Map 178Network Address Translation (NAT) is expressed in a form of segment mapping. 179The translation may be dynamic (stateful) or static (stateless). 180The following mapping types are available: 181.Pp 182.Bl -tag -width <-> -compact 183.It Pa -> 184outbound NAT (translation of the source) 185.It Pa <- 186inbound NAT (translation of the destination) 187.It Pa <-> 188bi-directional NAT (combination of inbound and outbound NAT) 189.El 190.Pp 191The following would translate the source to the IP address specified 192by the $pub_ip for the packets on the interface $ext_if. 193.Bd -literal 194map $ext_if dynamic 10.1.1.0/24 -> $pub_ip 195.Ed 196.Pp 197Translations are implicitly filtered by limiting the operation to the 198network segments specified, that is, translation would be performed only 199on packets originating from 10.1.1.0/24 network. 200Explicit filter criteria can be specified using "pass <criteria>" as 201an additional option of the mapping. 202.Ss Procedures 203A rule procedure is defined as a collection of extension calls (it 204may have none). 205Every extension call has a name and a list of options in the form of 206key-value pairs. 207Depending on the call, the key might represent the argument and the value 208might be optional. 209For example: 210.Bd -literal 211procedure "someproc" { 212 log: npflog0 213 normalize: "random-id", "min-ttl" 64 214} 215.Ed 216.Pp 217In this case, the procedure calls the logging and normalisation modules. 218.Ss Misc 219Text after a hash 220.Pq Sq # 221character is considered a comment. 222The backslash 223.Pq Sq \e 224character at the end of a line marks a continuation line, 225i.e., the next line is considered an extension of the present line. 226.Sh GRAMMAR 227The following is a non-formal BNF-like definition of the grammar. 228The definition is simplified and is intended to be human readable, 229therefore it does not strictly represent the full syntax, which 230is more flexible. 231.Bd -literal 232; Syntax of a single line. Lines can be separated by LF (\\n) or 233; a semicolon. Comments start with a hash (#) character. 234 235syntax = var-def | table-def | map | group | rproc | comment 236 237; Variable definition. Names can be alpha-numeric, including "_" character. 238 239var-name = "$" . string 240interface = interface-name | var-name 241var-def = var "=" ( var-value | "{" value *[ "," value ] "}" ) 242 243; Table definition. Table ID shall be numeric. Path is in the double quotes. 244 245table-id = \*[Lt]table-name\*[Gt] 246table-def = "table" table-id "type" ( "hash" | "tree" | "cdb" ) 247 ( "dynamic" | "file" path ) 248 249; Mapping for address translation. 250 251map = "map" interface 252 ( "static" [ "algo" algorithm ] | "dynamic" ) 253 net-seg ( "->" | "<-" | "<->" ) net-seg 254 [ "pass" filt-opts ] 255 256; Rule procedure definition. The name should be in the double quotes. 257; 258; Each call can have its own options in a form of key-value pairs. 259; Both key and values may be strings (either in double quotes or not) 260; and numbers, depending on the extension. 261 262proc = "procedure" proc-name "{" *( proc-call [ new-line ] ) "}" 263proc-opts = key " " val [ "," proc-opts ] 264proc-call = call-name ":" proc-opts new-line 265 266; Group definition and the rule list. 267 268group = "group" ( "default" | group-opts ) "{" rule-list "}" 269group-opts = name-string [ "in" | "out" ] [ "on" interface ] 270rule-list = [ rule new-line ] rule-list 271 272npf-filter = [ "family" family-opt ] [ "proto" protocol [ proto-opts ] ] 273 ( "all" | filt-opts ) 274static-rule = ( "block" [ block-opts ] | "pass" ) 275 [ "stateful" | "stateful-ends" ] 276 [ "in" | out" ] [ "final" ] [ "on" interface ] 277 ( npf-filter | "pcap-filter" pcap-filter-expr ) 278 [ "apply" proc-name ] 279 280dynamic-ruleset = "ruleset" group-opts 281rule = static-rule | dynamic-ruleset 282 283block-opts = "return-rst" | "return-icmp" | "return" 284family-opt = "inet4" | "inet6" 285proto-opts = "flags" tcp-flags [ "/" tcp-flag-mask ] | 286 "icmp-type" type [ "code" icmp-code ] 287 288addr-mask = addr [ "/" mask ] 289filt-opts = "from" filt-addr [ port-opts ] "to" filt-addr [ port-opts ] 290filt-addr = [ interface | var-name | addr-mask | table-id | "any" ] 291filt-port = "port" ( port-num | port-from "-" port-to | var-name ) 292.Ed 293.\" ----- 294.Sh FILES 295.Bl -tag -width /usr/share/examples/npf -compact 296.It Pa /dev/npf 297control device 298.It Pa /etc/npf.conf 299default configuration file 300.It Pa /usr/share/examples/npf 301directory containing further examples 302.El 303.\" ----- 304.Sh EXAMPLES 305.Bd -literal 306$ext_if = { inet4(wm0), inet6(wm0) } 307$int_if = { inet4(wm1), inet6(wm1) } 308 309table <blacklist> type hash file "/etc/npf_blacklist" 310table <limited> type tree dynamic 311 312$services_tcp = { http, https, smtp, domain, 6000, 9022 } 313$services_udp = { domain, ntp, 6000 } 314$localnet = { 10.1.1.0/24 } 315 316# Note: if $ext_if has multiple IP address (e.g. IPv6 as well), 317# then the translation address has to be specified explicitly. 318map $ext_if dynamic 10.1.1.0/24 -> $ext_if 319map $ext_if dynamic 10.1.1.2 port 22 <- $ext_if port 9022 320 321procedure "log" { 322 # Note: npf_ext_log kernel module should be loaded, if not built-in. 323 # Also, the interface created, e.g.: ifconfig npflog0 create 324 log: npflog0 325} 326 327group "external" on $ext_if { 328 pass stateful out final all 329 330 block in final from \*[Lt]blacklist\*[Gt] 331 pass stateful in final family inet4 proto tcp to $ext_if port ssh apply "log" 332 pass stateful in final proto tcp to $ext_if port $services_tcp 333 pass stateful in final proto udp to $ext_if port $services_udp 334 pass stateful in final proto tcp to $ext_if port 49151-65535 # Passive FTP 335 pass stateful in final proto udp to $ext_if port 33434-33600 # Traceroute 336} 337 338group "internal" on $int_if { 339 block in all 340 block in final from \*[Lt]limited\*[Gt] 341 342 # Ingress filtering as per BCP 38 / RFC 2827. 343 pass in final from $localnet 344 pass out final all 345} 346 347group default { 348 pass final on lo0 all 349 block all 350} 351.Ed 352.\" ----- 353.Sh SEE ALSO 354.Xr bpf 4 , 355.Xr pcap-filter 7 , 356.Xr npfctl 8 357.Sh HISTORY 358NPF first appeared in 359.Nx 6.0 . 360.Sh AUTHORS 361NPF was designed and implemented by 362.An Mindaugas Rasiukevicius . 363