1.\" $NetBSD: npf.conf.5,v 1.51 2017/12/11 23:07:49 wiz Exp $ 2.\" 3.\" Copyright (c) 2009-2017 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 December 10, 2017 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< and >. 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.Bd -literal 102$pub_if_list = { inet4(wm0), inet4(wm1) } 103.Ed 104.Pp 105In the context of filtering, an interface provides a list of its 106all IP addresses, including IPv4 and IPv6. 107Specific interface addresses can be selected by the family, e.g.: 108.Bd -literal 109$pub_if4 = inet4(wm0) 110$pub_if46 = { inet4(wm0), inet6(wm0) } 111.Ed 112.Pp 113In the above examples, NPF will statically capture the interface 114addresses on configuration load. 115.Pp 116The following can be used for dynamic handling of the interface addresses: 117.Bd -literal 118$pub_if = ifaddrs(wm0) 119.Ed 120.Pp 121In this case, the expression will represent the runtime list of addresses, 122reflecting any changes to the interface, including the attach and detach. 123Marking the interface as ``down'' has no effect, i.e. all addresses will 124remain present. 125.Pp 126The dynamic address list represents both the IPv4 and IPv6 addresses, 127therefore the 128.Cd family 129keyword can be used in combination to make the filtering more narrow. 130.Ss Groups 131Groups may have the following options: name, interface, and direction. 132They are defined in the following form: 133.Bd -literal 134group "my-name" in on wm0 { 135 # List of rules 136} 137.Ed 138.Ss Rules 139With a rule statement NPF is instructed to 140.Cd pass 141or 142.Cd block 143a packet depending on packet header information, transit direction and 144interface it arrives on, either immediately upon match (keyword 145.Cd final ) 146or using the last match. 147The rule can also instruct NPF to create an entry in the state table 148when passing the packet, to notify the sender when blocking it, and 149to apply a procedure to the packet (e.g. "log") in either case. 150.Pp 151A "fully-featured" rule would for example be: 152.Bd -literal 153pass stateful in final family inet4 proto tcp flags S/SA \\ 154 from $source port $sport to $dest port $dport apply "someproc" 155.Ed 156.Pp 157Any protocol in 158.Pa /etc/protocols 159can be specified. 160Further packet 161specification at present is limited to protocol TCP understanding flags, 162TCP and UDP understanding source and destination ports, and ICMP and 163IPv6-ICMP understanding icmp-type. 164.Pp 165Alternatively, NPF supports 166.Xr pcap-filter 7 167syntax, for example: 168.Bd -literal 169block out final pcap-filter "tcp and dst 10.1.1.252" 170.Ed 171.Pp 172Fragments are not selectable since NPF always reassembles packets 173before further processing. 174.Ss Stateful 175Stateful packet inspection is enabled using 176.Cd stateful 177or 178.Cd stateful-ends 179keywords. 180The former creates a state which is uniquely identified by a 5-tuple (source 181and destination IP addresses, port numbers and an interface identifier). 182The latter excludes the interface identifier and must be used with 183precaution. 184In both cases, a full TCP state tracking is performed for TCP connections 185and a limited tracking for message-based protocols (UDP and ICMP). 186.Pp 187By default, a stateful rule implies SYN-only flag check ("flags S/SAFR") 188for the TCP packets. 189It is not advisable to change this behavior; however, 190it can be overridden with the 191.Cd flags 192keyword. 193.Ss Map 194Network Address Translation (NAT) is expressed in a form of segment mapping. 195The translation may be dynamic (stateful) or static (stateless). 196The following mapping types are available: 197.Pp 198.Bl -tag -width <-> -compact 199.It Pa -> 200outbound NAT (translation of the source) 201.It Pa <- 202inbound NAT (translation of the destination) 203.It Pa <-> 204bi-directional NAT (combination of inbound and outbound NAT) 205.El 206.Pp 207The following would translate the source to the IP address specified 208by the $pub_ip for the packets on the interface $ext_if. 209.Bd -literal 210map $ext_if dynamic 10.1.1.0/24 -> $pub_ip 211.Ed 212.Pp 213Translations are implicitly filtered by limiting the operation to the 214network segments specified, that is, translation would be performed only 215on packets originating from 10.1.1.0/24 network. 216Explicit filter criteria can be specified using "pass <criteria>" as 217an additional option of the mapping. 218.Ss Procedures 219A rule procedure is defined as a collection of extension calls (it 220may have none). 221Every extension call has a name and a list of options in the form of 222key-value pairs. 223Depending on the call, the key might represent the argument and the value 224might be optional. 225For example: 226.Bd -literal 227procedure "someproc" { 228 log: npflog0 229 normalize: "random-id", "min-ttl" 64, "max-mss" 1432 230} 231.Ed 232.Pp 233In this case, the procedure calls the logging and normalisation modules. 234The logging facility requires the npf_ext_log kernel module which would 235normally get auto-loaded by NPF. 236The specified npflog interface would also be auto-created once the 237configuration is loaded. 238The log packets can be written to a file using the 239.Xr npfd 8 240daemon. 241.Pp 242Traffic normalisation has a set of different mechanisms. 243In the example above, the normalisation procedure has arguments which 244apply the following mechanisms: IPv4 ID randomisation, Don't Fragment (DF) 245flag cleansing, minimum TTL enforcement and TCP MSS "clamping". 246.Ss Misc 247Text after a hash 248.Pq Sq # 249character is considered a comment. 250The backslash 251.Pq Sq \e 252character at the end of a line marks a continuation line, 253i.e., the next line is considered an extension of the present line. 254.Sh GRAMMAR 255The following is a non-formal BNF-like definition of the grammar. 256The definition is simplified and is intended to be human readable, 257therefore it does not strictly represent the formal grammar. 258.Bd -literal 259; Syntax of a single line. Lines can be separated by LF (\\n) or 260; a semicolon. Comments start with a hash (#) character. 261 262syntax = var-def | set-param | alg | table-def | 263 map | group | rproc | comment 264 265; Variable definition. Names can be alpha-numeric, including "_" character. 266 267var-name = "$" . string 268interface = interface-name | var-name 269var-def = var "=" ( var-value | "{" value *[ "," value ] "}" ) 270 271; Parameter setting. 272set-param = "set" param-value 273 274; Application level gateway. The name should be in the double quotes. 275 276alg = "alg" alg-name 277 278; Table definition. Table ID shall be numeric. Path is in the double quotes. 279 280table-id = <table-name> 281table-def = "table" table-id "type" ( "hash" | "tree" | "cdb" ) 282 ( "dynamic" | "file" path ) 283 284; Mapping for address translation. 285 286map = "map" interface 287 ( "static" [ "algo" algorithm ] | "dynamic" ) 288 [ map-flags ] [ proto ] 289 net-seg ( "->" | "<-" | "<->" ) net-seg 290 [ "pass" [ proto ] filt-opts ] 291 292map-flags = "no-ports" 293 294; Rule procedure definition. The name should be in the double quotes. 295; 296; Each call can have its own options in a form of key-value pairs. 297; Both key and values may be strings (either in double quotes or not) 298; and numbers, depending on the extension. 299 300proc = "procedure" proc-name "{" *( proc-call [ new-line ] ) "}" 301proc-opts = key " " val [ "," proc-opts ] 302proc-call = call-name ":" proc-opts new-line 303 304; Group definition and the rule list. 305 306group = "group" ( "default" | group-opts ) "{" rule-list "}" 307group-opts = name-string [ "in" | "out" ] [ "on" interface ] 308rule-list = [ rule new-line ] rule-list 309 310npf-filter = [ "family" family-opt ] [ proto ] ( "all" | filt-opts ) 311static-rule = ( "block" [ block-opts ] | "pass" ) 312 [ "stateful" | "stateful-ends" ] 313 [ "in" | out" ] [ "final" ] [ "on" interface ] 314 ( npf-filter | "pcap-filter" pcap-filter-expr ) 315 [ "apply" proc-name ] 316 317dynamic-ruleset = "ruleset" group-opts 318rule = static-rule | dynamic-ruleset 319 320proto = "proto" protocol [ proto-opts ] 321block-opts = "return-rst" | "return-icmp" | "return" 322family-opt = "inet4" | "inet6" 323proto-opts = "flags" tcp-flags [ "/" tcp-flag-mask ] | 324 "icmp-type" type [ "code" icmp-code ] 325 326addr-mask = addr [ "/" mask ] 327filt-opts = "from" filt-addr [ port-opts ] "to" filt-addr [ port-opts ] 328filt-addr = [ "!" ] [ interface | var-name | 329 addr-mask | table-id | "any" ] 330filt-port = "port" ( port-num | port-from "-" port-to | var-name ) 331.Ed 332.\" ----- 333.Sh FILES 334.Bl -tag -width /usr/share/examples/npf -compact 335.It Pa /dev/npf 336control device 337.It Pa /etc/npf.conf 338default configuration file 339.It Pa /usr/share/examples/npf 340directory containing further examples 341.El 342.\" ----- 343.Sh EXAMPLES 344.Bd -literal 345$ext_if = { inet4(wm0) } 346$int_if = { inet4(wm1) } 347 348table <blacklist> type hash file "/etc/npf_blacklist" 349table <limited> type tree dynamic 350 351$services_tcp = { http, https, smtp, domain, 6000, 9022 } 352$services_udp = { domain, ntp, 6000 } 353$localnet = { 10.1.1.0/24 } 354 355alg "icmp" 356 357# Note: if $ext_if has multiple IP address (e.g. IPv6 as well), 358# then the translation address has to be specified explicitly. 359map $ext_if dynamic 10.1.1.0/24 -> $ext_if 360map $ext_if dynamic proto tcp 10.1.1.2 port 22 <- $ext_if port 9022 361 362procedure "log" { 363 # The logging facility can be used together with npfd(8). 364 log: npflog0 365} 366 367group "external" on $ext_if { 368 pass stateful out final all 369 370 block in final from <blacklist> 371 pass stateful in final family inet4 proto tcp to $ext_if port ssh apply "log" 372 pass stateful in final proto tcp to $ext_if port $services_tcp 373 pass stateful in final proto udp to $ext_if port $services_udp 374 pass stateful in final proto tcp to $ext_if port 49151-65535 # Passive FTP 375 pass stateful in final proto udp to $ext_if port 33434-33600 # Traceroute 376} 377 378group "internal" on $int_if { 379 block in all 380 block in final from <limited> 381 382 # Ingress filtering as per BCP 38 / RFC 2827. 383 pass in final from $localnet 384 pass out final all 385} 386 387group default { 388 pass final on lo0 all 389 block all 390} 391.Ed 392.\" ----- 393.Sh SEE ALSO 394.Xr bpf 4 , 395.Xr npf 7 , 396.Xr pcap-filter 7 , 397.Xr npfctl 8 , 398.Xr npfd 8 399.Sh HISTORY 400NPF first appeared in 401.Nx 6.0 . 402.Sh AUTHORS 403NPF was designed and implemented by 404.An Mindaugas Rasiukevicius . 405