usr.sbin/pfctl/pfctl.8

   1 .\" $OpenBSD: pfctl.8,v 1.110 2004/03/20 09:31:42 david Exp $
   2 .\" $DragonFly: src/usr.sbin/pfctl/pfctl.8,v 1.1 2004/09/21 21:25:28 joerg Exp $
   3 .\"
   4 .\" Copyright (c) 2001 Kjell Wooding.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. The name of the author may not be used to endorse or promote products
  15 .\"    derived from this software without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  18 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  19 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  21 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  22 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  23 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  24 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  25 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  26 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  27 .\"
  28 .Dd November 20, 2002
  29 .Dt PFCTL 8
  30 .Os
  31 .Sh NAME
  32 .Nm pfctl
  33 .Nd "control the packet filter (PF) and network address translation (NAT) device"
  34 .Sh SYNOPSIS
  35 .Nm pfctl
  36 .Bk -words
  37 .Op Fl AdeghNnOqRrvz
  38 .Op Fl a Ar anchor Ns Op Ar :ruleset
  39 .Op Fl D Ar macro=value
  40 .Op Fl F Ar modifier
  41 .Op Fl f Ar file
  42 .Op Fl i Ar interface
  43 .Op Fl k Ar host
  44 .Op Fl p Ar device
  45 .Op Fl s Ar modifier
  46 .Op Fl T Ar command Op Ar address ...
  47 .Op Fl t Ar table
  48 .Op Fl x Ar level
  49 .Ek
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 utility communicates with the packet filter device using the
  54 ioctl interface described in
  55 .Xr pf 4 .
  56 It allows ruleset and parameter configuration and retrieval of status
  57 information from the packet filter.
  58 .Pp
  59 Packet filtering restricts the types of packets that pass through
  60 network interfaces entering or leaving the host based on filter
  61 rules as described in
  62 .Xr pf.conf 5 .
  63 The packet filter can also replace addresses and ports of packets.
  64 Replacing source addresses and ports of outgoing packets is called
  65 NAT (Network Address Translation) and is used to connect an internal
  66 network (usually reserved address space) to an external one (the
  67 Internet) by making all connections to external hosts appear to
  68 come from the gateway.
  69 Replacing destination addresses and ports of incoming packets
  70 is used to redirect connections to different hosts and/or ports.
  71 A combination of both translations, bidirectional NAT, is also
  72 supported.
  73 Translation rules are described in
  74 .Xr pf.conf 5 .
  75 .Pp
  76 When the variable pf is set to YES in
  77 .Xr rc.conf 8 ,
  78 the rule file specified with the variable pf_rules
  79 is loaded automatically by the
  80 .Xr rc 8
  81 scripts and the packet filter is enabled.
  82 .Pp
  83 The packet filter does not itself forward packets between interfaces.
  84 Forwarding can be enabled by setting the
  85 .Xr sysctl 8
  86 variables
  87 .Em net.inet.ip.forwarding
  88 and/or
  89 .Em net.inet6.ip6.forwarding ,
  90 to 1.
  91 Set them permanently in
  92 .Xr sysctl.conf 5 .
  93 .Pp
  94 The
  95 .Nm
  96 utility provides several commands.
  97 The options are as follows:
  98 .Bl -tag -width Ds
  99 .It Fl A
 100 Load only the queue rules present in the rule file.
 101 Other rules and options are ignored.
 102 .It Fl a Ar anchor Ns Op Ar :ruleset
 103 Apply flags
 104 .Fl f ,
 105 .Fl F
 106 and
 107 .Fl s
 108 only to the rules in the specified
 109 .Ar anchor
 110 and optional named ruleset
 111 .Ar ruleset .
 112 In addition to the main ruleset,
 113 .Nm
 114 can load and manipulate additional rulesets by name.
 115 Named rulesets are attached at
 116 .Ar anchor
 117 points, which are also referenced by name.
 118 Evaluation of
 119 .Ar anchor
 120 rules from the main ruleset is described in
 121 .Xr pf.conf 5 .
 122 For example, to show all filter rules inside anchor
 123 .Li foo :
 124 .Bd -literal -offset indent
 125 # pfctl -a foo -s rules
 126 .Ed
 127 .Pp
 128 Private tables can also be put inside subrulesets, either by having table
 129 statements in the
 130 .Xr pf.conf 5
 131 file that is loaded in the anchor, or by using regular table commands as in:
 132 .Bd -literal -offset indent
 133 # pfctl -a foo:bar -t mytable -T add 1.2.3.4 5.6.7.8
 134 .Ed
 135 .Pp
 136 When a rule referring to a table is loaded in an anchor, the rule will use the
 137 private table if one is defined, and then fallback to the table defined in the
 138 main ruleset, if there is one.
 139 This is similar to C rules for variables.
 140 It is possible to create distinct tables with the same name in the global
 141 ruleset and in an anchor, but this is often bad design and a warning will be
 142 issued in that case.
 143 .It Fl D Ar macro=value
 144 Define
 145 .Ar macro
 146 to be set to
 147 .Ar value
 148 on the command line.
 149 Overrides the definition of
 150 .Ar macro
 151 in the ruleset.
 152 .It Fl d
 153 Disable the packet filter.
 154 .It Fl e
 155 Enable the packet filter.
 156 .It Fl F Ar modifier
 157 Flush the filter parameters specified by
 158 .Ar modifier
 159 (may be abbreviated):
 160 .Pp
 161 .Bl -tag -width xxxxxxxxxxxx -compact
 162 .It Fl F Ar nat
 163 Flush the NAT rules.
 164 .It Fl F Ar queue
 165 Flush the queue rules.
 166 .It Fl F Ar rules
 167 Flush the filter rules.
 168 .It Fl F Ar state
 169 Flush the state table (NAT and filter).
 170 .It Fl F Ar Sources
 171 Flush the source tracking table.
 172 .It Fl F Ar info
 173 Flush the filter information (statistics that are not bound to rules).
 174 .It Fl F Ar Tables
 175 Flush the tables.
 176 .It Fl F Ar osfp
 177 Flush the passive operating system fingerprints.
 178 .It Fl F Ar all
 179 Flush all of the above.
 180 .El
 181 .It Fl f Ar file
 182 Load the rules contained in
 183 .Ar file .
 184 This
 185 .Ar file
 186 may contain macros, tables, options, and normalization, queueing,
 187 translation, and filtering rules.
 188 With the exception of macros and tables, the statements must appear in that
 189 order.
 190 .It Fl g
 191 Include output helpful for debugging.
 192 .It Fl h
 193 Help.
 194 .It Fl i Ar interface
 195 Restrict the operation to the given
 196 .Ar interface .
 197 .It Fl k Ar host
 198 Kill all of the state entries originating from the specified
 199 .Ar host .
 200 A second
 201 .Fl k Ar host
 202 option may be specified, which will kill all the state entries
 203 from the first
 204 .Ar host
 205 to the second
 206 .Ar host .
 207 For example, to kill all of the state entries originating from
 208 .Li host :
 209 .Bd -literal -offset indent
 210 # pfctl -k host
 211 .Ed
 212 .Pp
 213 To kill all of the state entries from
 214 .Li host1
 215 to
 216 .Li host2 :
 217 .Bd -literal -offset indent
 218 # pfctl -k host1 -k host2
 219 .Ed
 220 .It Fl N
 221 Load only the NAT rules present in the rule file.
 222 Other rules and options are ignored.
 223 .It Fl n
 224 Do not actually load rules, just parse them.
 225 .It Fl O
 226 Load only the options present in the rule file.
 227 Other rules and options are ignored.
 228 .It Fl p Ar device
 229 Use the device file
 230 .Ar device
 231 instead of the default
 232 .Pa /dev/pf .
 233 .It Fl q
 234 Only print errors and warnings.
 235 .It Fl R
 236 Load only the filter rules present in the rule file.
 237 Other rules and options are ignored.
 238 .It Fl r
 239 Perform reverse DNS lookups on states when displaying them.
 240 .It Fl s Ar modifier
 241 Show the filter parameters specified by
 242 .Ar modifier
 243 (may be abbreviated):
 244 .Pp
 245 .Bl -tag -width xxxxxxxxxxxxx -compact
 246 .It Fl s Ar nat
 247 Show the currently loaded NAT rules.
 248 .It Fl s Ar queue
 249 Show the currently loaded queue rules.
 250 When used together with
 251 .Fl v ,
 252 per-queue statistics are also shown.
 253 When used together with
 254 .Fl v v ,
 255 .Nm
 256 will loop and show updated queue statistics every five seconds, including
 257 measured bandwidth and packets per second.
 258 .It Fl s Ar rules
 259 Show the currently loaded filter rules.
 260 When used together with
 261 .Fl v ,
 262 the per-rule statistics (number of evaluations,
 263 packets and bytes) are also shown.
 264 Note that the 'skip step' optimization done automatically by the kernel
 265 will skip evaluation of rules where possible.
 266 Packets passed statefully are counted in the rule that created the state
 267 (even though the rule isn't evaluated more than once for the entire
 268 connection).
 269 .It Fl s Ar Anchors
 270 Show the currently loaded anchors.
 271 If
 272 .Fl a Ar anchor
 273 is specified as well, the named rulesets currently loaded in the specified
 274 anchor are shown instead.
 275 .It Fl s Ar state
 276 Show the contents of the state table.
 277 .It Fl s Ar Sources
 278 Show the contents of the source tracking table.
 279 .It Fl s Ar info
 280 Show filter information (statistics and counters).
 281 When used together with
 282 .Fl v ,
 283 source tracking statistics are also shown.
 284 .It Fl s Ar labels
 285 Show per-rule statistics (label, evaluations, packets, bytes) of
 286 filter rules with labels, useful for accounting.
 287 .It Fl s Ar timeouts
 288 Show the current global timeouts.
 289 .It Fl s Ar memory
 290 Show the current pool memory hard limits.
 291 .It Fl s Ar Tables
 292 Show the list of tables.
 293 .It Fl s Ar osfp
 294 Show the list of operating system fingerprints.
 295 .It Fl s Ar Interfaces
 296 Show the list of interfaces and interface drivers available to PF.
 297 When used together with a double
 298 .Fl v ,
 299 interface statistics are also shown.
 300 .Fl i
 301 can be used to select an interface or a group of interfaces.
 302 .It Fl s Ar all
 303 Show all of the above, except for the lists of interfaces and operating
 304 system fingerprints.
 305 .El
 306 .It Fl T Ar command Op Ar address ...
 307 Specify the
 308 .Ar command
 309 (may be abbreviated) to apply to the table.
 310 Commands include:
 311 .Pp
 312 .Bl -tag -width xxxxxxxxxxxx -compact
 313 .It Fl T Ar kill
 314 Kill a table.
 315 .It Fl T Ar flush
 316 Flush all addresses of a table.
 317 .It Fl T Ar add
 318 Add one or more addresses in a table.
 319 Automatically create a nonexisting table.
 320 .It Fl T Ar delete
 321 Delete one or more addresses from a table.
 322 .It Fl T Ar replace
 323 Replace the addresses of the table.
 324 Automatically create a nonexisting table.
 325 .It Fl T Ar show
 326 Show the content (addresses) of a table.
 327 .It Fl T Ar test
 328 Test if the given addresses match a table.
 329 .It Fl T Ar zero
 330 Clear all the statistics of a table.
 331 .It Fl T Ar load
 332 Load only the table definitions from
 333 .Xr pf.conf 5 .
 334 This is used in conjunction with the
 335 .Fl f
 336 flag, as in:
 337 .Bd -literal -offset indent
 338 # pfctl -Tl -f pf.conf
 339 .Ed
 340 .El
 341 .Pp
 342 For the
 343 .Ar add ,
 344 .Ar delete ,
 345 .Ar replace
 346 and
 347 .Ar test
 348 commands, the list of addresses can be specified either directly on the command
 349 line and/or in an unformatted text file, using the
 350 .Fl f
 351 flag.
 352 Comments starting with a "#" are allowed in the text file.
 353 With these commands, the
 354 .Fl v
 355 flag can also be used once or twice, in which case
 356 .Nm
 357 will print the
 358 detailed result of the operation for each individual address, prefixed by
 359 one of the following letters:
 360 .Pp
 361 .Bl -tag -width XXX -compact
 362 .It A
 363 The address/network has been added.
 364 .It C
 365 The address/network has been changed (negated).
 366 .It D
 367 The address/network has been deleted.
 368 .It M
 369 The address matches (test operation only).
 370 .It X
 371 The address/network is duplicated and therefore ignored.
 372 .It Y
 373 The address/network cannot be added/deleted due to conflicting "!" attribute.
 374 .It Z
 375 The address/network has been cleared (statistics).
 376 .El
 377 .Pp
 378 Each table maintains a set of counters that can be retrieved using the
 379 .Fl v
 380 flag of
 381 .Nm .
 382 For example, the following commands define a wide open firewall which will keep
 383 track of packets going to or coming from the
 384 .Ox
 385 ftp server.
 386 The following commands configure the firewall and send 10 pings to the ftp
 387 server:
 388 .Bd -literal -offset indent
 389 # printf "table <test> { ftp.openbsd.org }\en \e
 390     pass out to <test> keep state\en" | pfctl -f-
 391 # ping -qc10 ftp.openbsd.org
 392 .Ed
 393 .Pp
 394 We can now use the table
 395 .Ar show
 396 command to output, for each address and packet direction, the number of packets
 397 and bytes that are being passed or blocked by rules referencing the table.
 398 The time at which the current accounting started is also shown with the
 399 .Ar Cleared
 400 line.
 401 .Bd -literal -offset indent
 402 # pfctl -t test -vTshow
 403    129.128.5.191
 404     Cleared:     Thu Feb 13 18:55:18 2003
 405     In/Block:    [ Packets: 0        Bytes: 0        ]
 406     In/Pass:     [ Packets: 10       Bytes: 840      ]
 407     Out/Block:   [ Packets: 0        Bytes: 0        ]
 408     Out/Pass:    [ Packets: 10       Bytes: 840      ]
 409 .Ed
 410 .Pp
 411 Similarly, it is possible to view global information about the tables
 412 by using the
 413 .Fl v
 414 modifier twice and the
 415 .Ar show Tables
 416 command.
 417 This will display the number of addresses on each table,
 418 the number of rules which reference the table, and the global
 419 packet statistics for the whole table:
 420 .Bd -literal -offset indent
 421 # pfctl -vvsTables
 422 --a-r-  test
 423     Addresses:   1
 424     Cleared:     Thu Feb 13 18:55:18 2003
 425     References:  [ Anchors: 0        Rules: 1        ]
 426     Evaluations: [ NoMatch: 3496     Match: 1        ]
 427     In/Block:    [ Packets: 0        Bytes: 0        ]
 428     In/Pass:     [ Packets: 10       Bytes: 840      ]
 429     In/XPass:    [ Packets: 0        Bytes: 0        ]
 430     Out/Block:   [ Packets: 0        Bytes: 0        ]
 431     Out/Pass:    [ Packets: 10       Bytes: 840      ]
 432     Out/XPass:   [ Packets: 0        Bytes: 0        ]
 433 .Ed
 434 .Pp
 435 As we can see here, only one packet \- the initial ping request \- matched the
 436 table; but all packets passing as the result of the state are correctly
 437 accounted for.
 438 Reloading the table(s) or ruleset will not affect packet accounting in any way.
 439 The two
 440 .Ar XPass
 441 counters are incremented instead of the
 442 .Ar Pass
 443 counters when a "stateful" packet is passed but doesn't match the table
 444 anymore.
 445 This will happen in our example if someone flushes the table while the ping
 446 command is running.
 447 .Pp
 448 When used with a single
 449 .Fl v ,
 450 .Nm
 451 will only display the first line containing the table flags and name.
 452 The flags are defined as follows:
 453 .Pp
 454 .Bl -tag -width XXX -compact
 455 .It c
 456 For constant tables, which cannot be altered outside
 457 .Xr pf.conf 5 .
 458 .It p
 459 For persistent tables, which don't get automatically flushed when no rules
 460 refer to them.
 461 .It a
 462 For tables which are part of the
 463 .Ar active
 464 tableset.
 465 Tables without this flag do not really exist, cannot contain addresses, and are
 466 only listed if the
 467 .Fl g
 468 flag is given.
 469 .It i
 470 For tables which are part of the
 471 .Ar inactive
 472 tableset.
 473 This flag can only be witnessed briefly during the loading of
 474 .Xr pf.conf 5 .
 475 .It r
 476 For tables which are referenced (used) by rules.
 477 .It h
 478 This flag is set when a table in the main ruleset is hidden by one or more
 479 tables of the same name in sub-rulesets (anchors).
 480 .El
 481 .It Fl t Ar table
 482 Specify the name of the table.
 483 .It Fl v
 484 Produce more verbose output.
 485 A second use of
 486 .Fl v
 487 will produce even more verbose output including ruleset warnings.
 488 See previous section for its effect on table commands.
 489 .It Fl x Ar level
 490 Set the debug
 491 .Ar level
 492 (may be abbreviated) to one of the following:
 493 .Pp
 494 .Bl -tag -width xxxxxxxxxxxx -compact
 495 .It Fl x Ar none
 496 Don't generate debug messages.
 497 .It Fl x Ar urgent
 498 Generate debug messages only for serious errors.
 499 .It Fl x Ar misc
 500 Generate debug messages for various errors.
 501 .It Fl x Ar loud
 502 Generate debug messages for common conditions.
 503 .El
 504 .It Fl z
 505 Clear per-rule statistics.
 506 .El
 507 .Sh FILES
 508 .Bl -tag -width "/etc/pf.conf" -compact
 509 .It Pa /etc/pf.conf
 510 Packet filter rules file.
 511 .El
 512 .Sh SEE ALSO
 513 .Xr pf 4 ,
 514 .Xr pf.conf 5 ,
 515 .Xr pf.os 5 ,
 516 .Xr sysctl.conf 5 ,
 517 .Xr ftp-proxy 8 ,
 518 .Xr rc 8 ,
 519 .Xr rc.conf 8 ,
 520 .Xr sysctl 8
 521 .Sh HISTORY
 522 The
 523 .Nm
 524 program and the
 525 .Xr pf 4
 526 filter mechanism first appeared in
 527 .Ox 3.0 .