share/man/man4/pf.4

   1 .\"     $OpenBSD: pf.4,v 1.62 2008/09/10 14:57:37 jmc Exp $
   2 .\"
   3 .\" Copyright (C) 2001, Kjell Wooding.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. Neither the name of the project nor the names of its contributors
  14 .\"    may be used to endorse or promote products derived from this software
  15 .\"    without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd November 14, 2013
  32 .Dt PF 4
  33 .Os
  34 .Sh NAME
  35 .Nm pf
  36 .Nd packet filter
  37 .Sh SYNOPSIS
  38 .Cd "device pf"
  39 .Cd "options PF_DEFAULT_TO_DROP"
  40 .Sh DESCRIPTION
  41 Packet filtering takes place in the kernel.
  42 A pseudo-device,
  43 .Pa /dev/pf ,
  44 allows userland processes to control the
  45 behavior of the packet filter through an
  46 .Xr ioctl 2
  47 interface.
  48 There are commands to enable and disable the filter, load rulesets,
  49 add and remove individual rules or state table entries,
  50 and retrieve statistics.
  51 The most commonly used functions are covered by
  52 .Xr pfctl 8 .
  53 .Pp
  54 Manipulations like loading a ruleset that involve more than a single
  55 .Xr ioctl 2
  56 call require a so-called
  57 .Em ticket ,
  58 which prevents the occurrence of
  59 multiple concurrent manipulations.
  60 .Pp
  61 Fields of
  62 .Xr ioctl 2
  63 parameter structures that refer to packet data (like
  64 addresses and ports) are generally expected in network byte-order.
  65 .Pp
  66 Rules and address tables are contained in so-called
  67 .Em anchors .
  68 When servicing an
  69 .Xr ioctl 2
  70 request, if the anchor field of the argument structure is empty,
  71 the kernel will use the default anchor (i.e., the main ruleset)
  72 in operations.
  73 Anchors are specified by name and may be nested, with components
  74 separated by
  75 .Sq /
  76 characters, similar to how file system hierarchies are laid out.
  77 The final component of the anchor path is the anchor under which
  78 operations will be performed.
  79 .Sh SYSCTL VARIABLES AND LOADER TUNABLES
  80 The following
  81 .Xr loader 8
  82 tunables are available.
  83 .Bl -tag -width indent
  84 .It Va net.pf.states_hashsize
  85 Size of hash tables that store states.
  86 Should be power of 2.
  87 Default value is 32768.
  88 .It Va net.pf.source_nodes_hashsize
  89 Size of hash table that store source nodes.
  90 Should be power of 2.
  91 Default value is 8192.
  92 .El
  93 .Pp
  94 Read only
  95 .Xr sysctl 8
  96 variables with matching names are provided to obtain current values
  97 at runtime.
  98 .Sh KERNEL OPTIONS
  99 The following options in the kernel configuration file are related to
 100 .Nm
 101 operation:
 102 .Pp
 103 .Bl -tag -width ".Dv PF_DEFAULT_TO_DROP" -compact
 104 .It Dv PF_DEFAULT_TO_DROP
 105 Change default policy to drop by default
 106 .El
 107 .Sh IOCTL INTERFACE
 108 .Nm
 109 supports the following
 110 .Xr ioctl 2
 111 commands, available through
 112 .Aq Pa net/pfvar.h :
 113 .Bl -tag -width xxxxxx
 114 .It Dv DIOCSTART
 115 Start the packet filter.
 116 .It Dv DIOCSTOP
 117 Stop the packet filter.
 118 .It Dv DIOCSTARTALTQ
 119 Start the ALTQ bandwidth control system (see
 120 .Xr altq 9 ) .
 121 .It Dv DIOCSTOPALTQ
 122 Stop the ALTQ bandwidth control system.
 123 .It Dv DIOCBEGINADDRS Fa "struct pfioc_pooladdr *pp"
 124 .Bd -literal
 125 struct pfioc_pooladdr {
 126         u_int32_t               action;
 127         u_int32_t               ticket;
 128         u_int32_t               nr;
 129         u_int32_t               r_num;
 130         u_int8_t                r_action;
 131         u_int8_t                r_last;
 132         u_int8_t                af;
 133         char                    anchor[MAXPATHLEN];
 134         struct pf_pooladdr      addr;
 135 };
 136 .Ed
 137 .Pp
 138 Clear the buffer address pool and get a
 139 .Va ticket
 140 for subsequent
 141 .Dv DIOCADDADDR ,
 142 .Dv DIOCADDRULE ,
 143 and
 144 .Dv DIOCCHANGERULE
 145 calls.
 146 .It Dv DIOCADDADDR Fa "struct pfioc_pooladdr *pp"
 147 .Pp
 148 Add the pool address
 149 .Va addr
 150 to the buffer address pool to be used in the following
 151 .Dv DIOCADDRULE
 152 or
 153 .Dv DIOCCHANGERULE
 154 call.
 155 All other members of the structure are ignored.
 156 .It Dv DIOCADDRULE Fa "struct pfioc_rule *pr"
 157 .Bd -literal
 158 struct pfioc_rule {
 159         u_int32_t       action;
 160         u_int32_t       ticket;
 161         u_int32_t       pool_ticket;
 162         u_int32_t       nr;
 163         char            anchor[MAXPATHLEN];
 164         char            anchor_call[MAXPATHLEN];
 165         struct pf_rule  rule;
 166 };
 167 .Ed
 168 .Pp
 169 Add
 170 .Va rule
 171 at the end of the inactive ruleset.
 172 This call requires a
 173 .Va ticket
 174 obtained through a preceding
 175 .Dv DIOCXBEGIN
 176 call and a
 177 .Va pool_ticket
 178 obtained through a
 179 .Dv DIOCBEGINADDRS
 180 call.
 181 .Dv DIOCADDADDR
 182 must also be called if any pool addresses are required.
 183 The optional
 184 .Va anchor
 185 name indicates the anchor in which to append the rule.
 186 .Va nr
 187 and
 188 .Va action
 189 are ignored.
 190 .It Dv DIOCADDALTQ Fa "struct pfioc_altq *pa"
 191 Add an ALTQ discipline or queue.
 192 .Bd -literal
 193 struct pfioc_altq {
 194         u_int32_t       action;
 195         u_int32_t       ticket;
 196         u_int32_t       nr;
 197         struct pf_altq  altq;
 198 };
 199 .Ed
 200 .It Dv DIOCGETRULES Fa "struct pfioc_rule *pr"
 201 Get a
 202 .Va ticket
 203 for subsequent
 204 .Dv DIOCGETRULE
 205 calls and the number
 206 .Va nr
 207 of rules in the active ruleset.
 208 .It Dv DIOCGETRULE Fa "struct pfioc_rule *pr"
 209 Get a
 210 .Va rule
 211 by its number
 212 .Va nr
 213 using the
 214 .Va ticket
 215 obtained through a preceding
 216 .Dv DIOCGETRULES
 217 call.
 218 If
 219 .Va action
 220 is set to
 221 .Dv PF_GET_CLR_CNTR ,
 222 the per-rule statistics on the requested rule are cleared.
 223 .It Dv DIOCGETADDRS Fa "struct pfioc_pooladdr *pp"
 224 Get a
 225 .Va ticket
 226 for subsequent
 227 .Dv DIOCGETADDR
 228 calls and the number
 229 .Va nr
 230 of pool addresses in the rule specified with
 231 .Va r_action ,
 232 .Va r_num ,
 233 and
 234 .Va anchor .
 235 .It Dv DIOCGETADDR Fa "struct pfioc_pooladdr *pp"
 236 Get the pool address
 237 .Va addr
 238 by its number
 239 .Va nr
 240 from the rule specified with
 241 .Va r_action ,
 242 .Va r_num ,
 243 and
 244 .Va anchor
 245 using the
 246 .Va ticket
 247 obtained through a preceding
 248 .Dv DIOCGETADDRS
 249 call.
 250 .It Dv DIOCGETALTQS Fa "struct pfioc_altq *pa"
 251 Get a
 252 .Va ticket
 253 for subsequent
 254 .Dv DIOCGETALTQ
 255 calls and the number
 256 .Va nr
 257 of queues in the active list.
 258 .It Dv DIOCGETALTQ Fa "struct pfioc_altq *pa"
 259 Get the queueing discipline
 260 .Va altq
 261 by its number
 262 .Va nr
 263 using the
 264 .Va ticket
 265 obtained through a preceding
 266 .Dv DIOCGETALTQS
 267 call.
 268 .It Dv DIOCGETQSTATS Fa "struct pfioc_qstats *pq"
 269 Get the statistics on a queue.
 270 .Bd -literal
 271 struct pfioc_qstats {
 272         u_int32_t        ticket;
 273         u_int32_t        nr;
 274         void            *buf;
 275         int              nbytes;
 276         u_int8_t         scheduler;
 277 };
 278 .Ed
 279 .Pp
 280 This call fills in a pointer to the buffer of statistics
 281 .Va buf ,
 282 of length
 283 .Va nbytes ,
 284 for the queue specified by
 285 .Va nr .
 286 .It Dv DIOCGETRULESETS Fa "struct pfioc_ruleset *pr"
 287 .Bd -literal
 288 struct pfioc_ruleset {
 289         u_int32_t        nr;
 290         char             path[MAXPATHLEN];
 291         char             name[PF_ANCHOR_NAME_SIZE];
 292 };
 293 .Ed
 294 .Pp
 295 Get the number
 296 .Va nr
 297 of rulesets (i.e., anchors) directly attached to the anchor named by
 298 .Va path
 299 for use in subsequent
 300 .Dv DIOCGETRULESET
 301 calls.
 302 Nested anchors, since they are not directly attached to the given
 303 anchor, will not be included.
 304 This ioctl returns
 305 .Er EINVAL
 306 if the given anchor does not exist.
 307 .It Dv DIOCGETRULESET Fa "struct pfioc_ruleset *pr"
 308 Get a ruleset (i.e., an anchor)
 309 .Va name
 310 by its number
 311 .Va nr
 312 from the given anchor
 313 .Va path ,
 314 the maximum number of which can be obtained from a preceding
 315 .Dv DIOCGETRULESETS
 316 call.
 317 This ioctl returns
 318 .Er EINVAL
 319 if the given anchor does not exist or
 320 .Er EBUSY
 321 if another process is concurrently updating a ruleset.
 322 .It Dv DIOCADDSTATE Fa "struct pfioc_state *ps"
 323 Add a state entry.
 324 .Bd -literal
 325 struct pfioc_state {
 326         struct pfsync_state     state;
 327 };
 328 .Ed
 329 .It Dv DIOCGETSTATE Fa "struct pfioc_state *ps"
 330 Extract the entry identified by the
 331 .Va id
 332 and
 333 .Va creatorid
 334 fields of the
 335 .Va state
 336 structure from the state table.
 337 .It Dv DIOCKILLSTATES Fa "struct pfioc_state_kill *psk"
 338 Remove matching entries from the state table.
 339 This ioctl returns the number of killed states in
 340 .Va psk_killed .
 341 .Bd -literal
 342 struct pfioc_state_kill {
 343         struct pf_state_cmp     psk_pfcmp;
 344         sa_family_t             psk_af;
 345         int                     psk_proto;
 346         struct pf_rule_addr     psk_src;
 347         struct pf_rule_addr     psk_dst;
 348         char                    psk_ifname[IFNAMSIZ];
 349         char                    psk_label[PF_RULE_LABEL_SIZE];
 350         u_int                   psk_killed;
 351 };
 352 .Ed
 353 .It Dv DIOCCLRSTATES Fa "struct pfioc_state_kill *psk"
 354 Clear all states.
 355 It works like
 356 .Dv DIOCKILLSTATES ,
 357 but ignores the
 358 .Va psk_af ,
 359 .Va psk_proto ,
 360 .Va psk_src ,
 361 and
 362 .Va psk_dst
 363 fields of the
 364 .Vt pfioc_state_kill
 365 structure.
 366 .It Dv DIOCSETSTATUSIF Fa "struct pfioc_if *pi"
 367 Specify the interface for which statistics are accumulated.
 368 .Bd -literal
 369 struct pfioc_if {
 370         char             ifname[IFNAMSIZ];
 371 };
 372 .Ed
 373 .It Dv DIOCGETSTATUS Fa "struct pf_status *s"
 374 Get the internal packet filter statistics.
 375 .Bd -literal
 376 struct pf_status {
 377         u_int64_t       counters[PFRES_MAX];
 378         u_int64_t       lcounters[LCNT_MAX];
 379         u_int64_t       fcounters[FCNT_MAX];
 380         u_int64_t       scounters[SCNT_MAX];
 381         u_int64_t       pcounters[2][2][3];
 382         u_int64_t       bcounters[2][2];
 383         u_int32_t       running;
 384         u_int32_t       states;
 385         u_int32_t       src_nodes;
 386         u_int32_t       since;
 387         u_int32_t       debug;
 388         u_int32_t       hostid;
 389         char            ifname[IFNAMSIZ];
 390         u_int8_t        pf_chksum[MD5_DIGEST_LENGTH];
 391 };
 392 .Ed
 393 .It Dv DIOCCLRSTATUS
 394 Clear the internal packet filter statistics.
 395 .It Dv DIOCNATLOOK Fa "struct pfioc_natlook *pnl"
 396 Look up a state table entry by source and destination addresses and ports.
 397 .Bd -literal
 398 struct pfioc_natlook {
 399         struct pf_addr   saddr;
 400         struct pf_addr   daddr;
 401         struct pf_addr   rsaddr;
 402         struct pf_addr   rdaddr;
 403         u_int16_t        sport;
 404         u_int16_t        dport;
 405         u_int16_t        rsport;
 406         u_int16_t        rdport;
 407         sa_family_t      af;
 408         u_int8_t         proto;
 409         u_int8_t         direction;
 410 };
 411 .Ed
 412 .It Dv DIOCSETDEBUG Fa "u_int32_t *level"
 413 Set the debug level.
 414 .Bd -literal
 415 enum    { PF_DEBUG_NONE, PF_DEBUG_URGENT, PF_DEBUG_MISC,
 416           PF_DEBUG_NOISY };
 417 .Ed
 418 .It Dv DIOCGETSTATES Fa "struct pfioc_states *ps"
 419 Get state table entries.
 420 .Bd -literal
 421 struct pfioc_states {
 422         int     ps_len;
 423         union {
 424                 caddr_t          psu_buf;
 425                 struct pf_state *psu_states;
 426         } ps_u;
 427 #define ps_buf          ps_u.psu_buf
 428 #define ps_states       ps_u.psu_states
 429 };
 430 .Ed
 431 .Pp
 432 If
 433 .Va ps_len
 434 is non-zero on entry, as many states as possible that can fit into this
 435 size will be copied into the supplied buffer
 436 .Va ps_states .
 437 On exit,
 438 .Va ps_len
 439 is always set to the total size required to hold all state table entries
 440 (i.e., it is set to
 441 .Li sizeof(struct pf_state) * nr ) .
 442 .It Dv DIOCCHANGERULE Fa "struct pfioc_rule *pcr"
 443 Add or remove the
 444 .Va rule
 445 in the ruleset specified by
 446 .Va rule.action .
 447 .Pp
 448 The type of operation to be performed is indicated by
 449 .Va action ,
 450 which can be any of the following:
 451 .Bd -literal
 452 enum    { PF_CHANGE_NONE, PF_CHANGE_ADD_HEAD, PF_CHANGE_ADD_TAIL,
 453           PF_CHANGE_ADD_BEFORE, PF_CHANGE_ADD_AFTER,
 454           PF_CHANGE_REMOVE, PF_CHANGE_GET_TICKET };
 455 .Ed
 456 .Pp
 457 .Va ticket
 458 must be set to the value obtained with
 459 .Dv PF_CHANGE_GET_TICKET
 460 for all actions except
 461 .Dv PF_CHANGE_GET_TICKET .
 462 .Va pool_ticket
 463 must be set to the value obtained with the
 464 .Dv DIOCBEGINADDRS
 465 call for all actions except
 466 .Dv PF_CHANGE_REMOVE
 467 and
 468 .Dv PF_CHANGE_GET_TICKET .
 469 .Va anchor
 470 indicates to which anchor the operation applies.
 471 .Va nr
 472 indicates the rule number against which
 473 .Dv PF_CHANGE_ADD_BEFORE ,
 474 .Dv PF_CHANGE_ADD_AFTER ,
 475 or
 476 .Dv PF_CHANGE_REMOVE
 477 actions are applied.
 478 .\" It Dv DIOCCHANGEALTQ Fa "struct pfioc_altq *pcr"
 479 .It Dv DIOCCHANGEADDR Fa "struct pfioc_pooladdr *pca"
 480 Add or remove the pool address
 481 .Va addr
 482 from the rule specified by
 483 .Va r_action ,
 484 .Va r_num ,
 485 and
 486 .Va anchor .
 487 .It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm *pt"
 488 .Bd -literal
 489 struct pfioc_tm {
 490         int              timeout;
 491         int              seconds;
 492 };
 493 .Ed
 494 .Pp
 495 Set the state timeout of
 496 .Va timeout
 497 to
 498 .Va seconds .
 499 The old value will be placed into
 500 .Va seconds .
 501 For possible values of
 502 .Va timeout ,
 503 consult the
 504 .Dv PFTM_*
 505 values in
 506 .Aq Pa net/pfvar.h .
 507 .It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm *pt"
 508 Get the state timeout of
 509 .Va timeout .
 510 The value will be placed into the
 511 .Va seconds
 512 field.
 513 .It Dv DIOCCLRRULECTRS
 514 Clear per-rule statistics.
 515 .It Dv DIOCSETLIMIT Fa "struct pfioc_limit *pl"
 516 Set the hard limits on the memory pools used by the packet filter.
 517 .Bd -literal
 518 struct pfioc_limit {
 519         int             index;
 520         unsigned        limit;
 521 };
 522
 523 enum    { PF_LIMIT_STATES, PF_LIMIT_SRC_NODES, PF_LIMIT_FRAGS,
 524           PF_LIMIT_TABLE_ENTRIES, PF_LIMIT_MAX };
 525 .Ed
 526 .It Dv DIOCGETLIMIT Fa "struct pfioc_limit *pl"
 527 Get the hard
 528 .Va limit
 529 for the memory pool indicated by
 530 .Va index .
 531 .It Dv DIOCRCLRTABLES Fa "struct pfioc_table *io"
 532 Clear all tables.
 533 All the ioctls that manipulate radix tables
 534 use the same structure described below.
 535 For
 536 .Dv DIOCRCLRTABLES ,
 537 .Va pfrio_ndel
 538 contains on exit the number of tables deleted.
 539 .Bd -literal
 540 struct pfioc_table {
 541         struct pfr_table         pfrio_table;
 542         void                    *pfrio_buffer;
 543         int                      pfrio_esize;
 544         int                      pfrio_size;
 545         int                      pfrio_size2;
 546         int                      pfrio_nadd;
 547         int                      pfrio_ndel;
 548         int                      pfrio_nchange;
 549         int                      pfrio_flags;
 550         u_int32_t                pfrio_ticket;
 551 };
 552 #define pfrio_exists    pfrio_nadd
 553 #define pfrio_nzero     pfrio_nadd
 554 #define pfrio_nmatch    pfrio_nadd
 555 #define pfrio_naddr     pfrio_size2
 556 #define pfrio_setflag   pfrio_size2
 557 #define pfrio_clrflag   pfrio_nadd
 558 .Ed
 559 .It Dv DIOCRADDTABLES Fa "struct pfioc_table *io"
 560 Create one or more tables.
 561 On entry,
 562 .Va pfrio_buffer
 563 must point to an array of
 564 .Vt struct pfr_table
 565 containing at least
 566 .Vt pfrio_size
 567 elements.
 568 .Vt pfrio_esize
 569 must be the size of
 570 .Vt struct pfr_table .
 571 On exit,
 572 .Va pfrio_nadd
 573 contains the number of tables effectively created.
 574 .Bd -literal
 575 struct pfr_table {
 576         char            pfrt_anchor[MAXPATHLEN];
 577         char            pfrt_name[PF_TABLE_NAME_SIZE];
 578         u_int32_t       pfrt_flags;
 579         u_int8_t        pfrt_fback;
 580 };
 581 .Ed
 582 .It Dv DIOCRDELTABLES Fa "struct pfioc_table *io"
 583 Delete one or more tables.
 584 On entry,
 585 .Va pfrio_buffer
 586 must point to an array of
 587 .Vt struct pfr_table
 588 containing at least
 589 .Vt pfrio_size
 590 elements.
 591 .Vt pfrio_esize
 592 must be the size of
 593 .Vt struct pfr_table .
 594 On exit,
 595 .Va pfrio_ndel
 596 contains the number of tables effectively deleted.
 597 .It Dv DIOCRGETTABLES Fa "struct pfioc_table *io"
 598 Get the list of all tables.
 599 On entry,
 600 .Va pfrio_buffer[pfrio_size]
 601 contains a valid writeable buffer for
 602 .Vt pfr_table
 603 structures.
 604 On exit,
 605 .Va pfrio_size
 606 contains the number of tables written into the buffer.
 607 If the buffer is too small, the kernel does not store anything but just
 608 returns the required buffer size, without error.
 609 .It Dv DIOCRGETTSTATS Fa "struct pfioc_table *io"
 610 This call is like
 611 .Dv DIOCRGETTABLES
 612 but is used to get an array of
 613 .Vt pfr_tstats
 614 structures.
 615 .Bd -literal
 616 struct pfr_tstats {
 617         struct pfr_table pfrts_t;
 618         u_int64_t        pfrts_packets
 619                              [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
 620         u_int64_t        pfrts_bytes
 621                              [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
 622         u_int64_t        pfrts_match;
 623         u_int64_t        pfrts_nomatch;
 624         long             pfrts_tzero;
 625         int              pfrts_cnt;
 626         int              pfrts_refcnt[PFR_REFCNT_MAX];
 627 };
 628 #define pfrts_name       pfrts_t.pfrt_name
 629 #define pfrts_flags      pfrts_t.pfrt_flags
 630 .Ed
 631 .It Dv DIOCRCLRTSTATS Fa "struct pfioc_table *io"
 632 Clear the statistics of one or more tables.
 633 On entry,
 634 .Va pfrio_buffer
 635 must point to an array of
 636 .Vt struct pfr_table
 637 containing at least
 638 .Vt pfrio_size
 639 elements.
 640 .Vt pfrio_esize
 641 must be the size of
 642 .Vt struct pfr_table .
 643 On exit,
 644 .Va pfrio_nzero
 645 contains the number of tables effectively cleared.
 646 .It Dv DIOCRCLRADDRS Fa "struct pfioc_table *io"
 647 Clear all addresses in a table.
 648 On entry,
 649 .Va pfrio_table
 650 contains the table to clear.
 651 On exit,
 652 .Va pfrio_ndel
 653 contains the number of addresses removed.
 654 .It Dv DIOCRADDADDRS Fa "struct pfioc_table *io"
 655 Add one or more addresses to a table.
 656 On entry,
 657 .Va pfrio_table
 658 contains the table ID and
 659 .Va pfrio_buffer
 660 must point to an array of
 661 .Vt struct pfr_addr
 662 containing at least
 663 .Vt pfrio_size
 664 elements to add to the table.
 665 .Vt pfrio_esize
 666 must be the size of
 667 .Vt struct pfr_addr .
 668 On exit,
 669 .Va pfrio_nadd
 670 contains the number of addresses effectively added.
 671 .Bd -literal
 672 struct pfr_addr {
 673         union {
 674                 struct in_addr   _pfra_ip4addr;
 675                 struct in6_addr  _pfra_ip6addr;
 676         }                pfra_u;
 677         u_int8_t         pfra_af;
 678         u_int8_t         pfra_net;
 679         u_int8_t         pfra_not;
 680         u_int8_t         pfra_fback;
 681 };
 682 #define pfra_ip4addr    pfra_u._pfra_ip4addr
 683 #define pfra_ip6addr    pfra_u._pfra_ip6addr
 684 .Ed
 685 .It Dv DIOCRDELADDRS Fa "struct pfioc_table *io"
 686 Delete one or more addresses from a table.
 687 On entry,
 688 .Va pfrio_table
 689 contains the table ID and
 690 .Va pfrio_buffer
 691 must point to an array of
 692 .Vt struct pfr_addr
 693 containing at least
 694 .Vt pfrio_size
 695 elements to delete from the table.
 696 .Vt pfrio_esize
 697 must be the size of
 698 .Vt struct pfr_addr .
 699 On exit,
 700 .Va pfrio_ndel
 701 contains the number of addresses effectively deleted.
 702 .It Dv DIOCRSETADDRS Fa "struct pfioc_table *io"
 703 Replace the content of a table by a new address list.
 704 This is the most complicated command, which uses all the structure members.
 705 .Pp
 706 On entry,
 707 .Va pfrio_table
 708 contains the table ID and
 709 .Va pfrio_buffer
 710 must point to an array of
 711 .Vt struct pfr_addr
 712 containing at least
 713 .Vt pfrio_size
 714 elements which become the new contents of the table.
 715 .Vt pfrio_esize
 716 must be the size of
 717 .Vt struct pfr_addr .
 718 Additionally, if
 719 .Va pfrio_size2
 720 is non-zero,
 721 .Va pfrio_buffer[pfrio_size..pfrio_size2]
 722 must be a writeable buffer, into which the kernel can copy the
 723 addresses that have been deleted during the replace operation.
 724 On exit,
 725 .Va pfrio_ndel ,
 726 .Va pfrio_nadd ,
 727 and
 728 .Va pfrio_nchange
 729 contain the number of addresses deleted, added, and changed by the
 730 kernel.
 731 If
 732 .Va pfrio_size2
 733 was set on entry,
 734 .Va pfrio_size2
 735 will point to the size of the buffer used, exactly like
 736 .Dv DIOCRGETADDRS .
 737 .It Dv DIOCRGETADDRS Fa "struct pfioc_table *io"
 738 Get all the addresses of a table.
 739 On entry,
 740 .Va pfrio_table
 741 contains the table ID and
 742 .Va pfrio_buffer[pfrio_size]
 743 contains a valid writeable buffer for
 744 .Vt pfr_addr
 745 structures.
 746 On exit,
 747 .Va pfrio_size
 748 contains the number of addresses written into the buffer.
 749 If the buffer was too small, the kernel does not store anything but just
 750 returns the required buffer size, without returning an error.
 751 .It Dv DIOCRGETASTATS Fa "struct pfioc_table *io"
 752 This call is like
 753 .Dv DIOCRGETADDRS
 754 but is used to get an array of
 755 .Vt pfr_astats
 756 structures.
 757 .Bd -literal
 758 struct pfr_astats {
 759         struct pfr_addr  pfras_a;
 760         u_int64_t        pfras_packets
 761                              [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
 762         u_int64_t        pfras_bytes
 763                              [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
 764         long             pfras_tzero;
 765 };
 766 .Ed
 767 .It Dv DIOCRCLRASTATS Fa "struct pfioc_table *io"
 768 Clear the statistics of one or more addresses.
 769 On entry,
 770 .Va pfrio_table
 771 contains the table ID and
 772 .Va pfrio_buffer
 773 must point to an array of
 774 .Vt struct pfr_addr
 775 containing at least
 776 .Vt pfrio_size
 777 elements to be cleared from the table.
 778 .Vt pfrio_esize
 779 must be the size of
 780 .Vt struct pfr_addr .
 781 On exit,
 782 .Va pfrio_nzero
 783 contains the number of addresses effectively cleared.
 784 .It Dv DIOCRTSTADDRS Fa "struct pfioc_table *io"
 785 Test if the given addresses match a table.
 786 On entry,
 787 .Va pfrio_table
 788 contains the table ID and
 789 .Va pfrio_buffer
 790 must point to an array of
 791 .Vt struct pfr_addr
 792 containing at least
 793 .Vt pfrio_size
 794 elements, each of which will be tested for a match in the table.
 795 .Vt pfrio_esize
 796 must be the size of
 797 .Vt struct pfr_addr .
 798 On exit, the kernel updates the
 799 .Vt pfr_addr
 800 array by setting the
 801 .Va pfra_fback
 802 member appropriately.
 803 .It Dv DIOCRSETTFLAGS Fa "struct pfioc_table *io"
 804 Change the
 805 .Dv PFR_TFLAG_CONST
 806 or
 807 .Dv PFR_TFLAG_PERSIST
 808 flags of a table.
 809 On entry,
 810 .Va pfrio_buffer
 811 must point to an array of
 812 .Vt struct pfr_table
 813 containing at least
 814 .Vt pfrio_size
 815 elements.
 816 .Va pfrio_esize
 817 must be the size of
 818 .Vt struct pfr_table .
 819 .Va pfrio_setflag
 820 must contain the flags to add, while
 821 .Va pfrio_clrflag
 822 must contain the flags to remove.
 823 On exit,
 824 .Va pfrio_nchange
 825 and
 826 .Va pfrio_ndel
 827 contain the number of tables altered or deleted by the kernel.
 828 Yes, tables can be deleted if one removes the
 829 .Dv PFR_TFLAG_PERSIST
 830 flag of an unreferenced table.
 831 .It Dv DIOCRINADEFINE Fa "struct pfioc_table *io"
 832 Defines a table in the inactive set.
 833 On entry,
 834 .Va pfrio_table
 835 contains the table ID and
 836 .Va pfrio_buffer[pfrio_size]
 837 contains an array of
 838 .Vt pfr_addr
 839 structures to put in the table.
 840 A valid ticket must also be supplied to
 841 .Va pfrio_ticket .
 842 On exit,
 843 .Va pfrio_nadd
 844 contains 0 if the table was already defined in the inactive list
 845 or 1 if a new table has been created.
 846 .Va pfrio_naddr
 847 contains the number of addresses effectively put in the table.
 848 .It Dv DIOCXBEGIN Fa "struct pfioc_trans *io"
 849 .Bd -literal
 850 struct pfioc_trans {
 851         int              size;  /* number of elements */
 852         int              esize; /* size of each element in bytes */
 853         struct pfioc_trans_e {
 854                 int             rs_num;
 855                 char            anchor[MAXPATHLEN];
 856                 u_int32_t       ticket;
 857         }               *array;
 858 };
 859 .Ed
 860 .Pp
 861 Clear all the inactive rulesets specified in the
 862 .Vt pfioc_trans_e
 863 array.
 864 For each ruleset, a ticket is returned for subsequent "add rule" ioctls,
 865 as well as for the
 866 .Dv DIOCXCOMMIT
 867 and
 868 .Dv DIOCXROLLBACK
 869 calls.
 870 .Pp
 871 Ruleset types, identified by
 872 .Va rs_num ,
 873 include the following:
 874 .Pp
 875 .Bl -tag -width PF_RULESET_FILTER -offset ind -compact
 876 .It Dv PF_RULESET_SCRUB
 877 Scrub (packet normalization) rules.
 878 .It Dv PF_RULESET_FILTER
 879 Filter rules.
 880 .It Dv PF_RULESET_NAT
 881 NAT (Network Address Translation) rules.
 882 .It Dv PF_RULESET_BINAT
 883 Bidirectional NAT rules.
 884 .It Dv PF_RULESET_RDR
 885 Redirect rules.
 886 .It Dv PF_RULESET_ALTQ
 887 ALTQ disciplines.
 888 .It Dv PF_RULESET_TABLE
 889 Address tables.
 890 .El
 891 .It Dv DIOCXCOMMIT Fa "struct pfioc_trans *io"
 892 Atomically switch a vector of inactive rulesets to the active rulesets.
 893 This call is implemented as a standard two-phase commit, which will either
 894 fail for all rulesets or completely succeed.
 895 All tickets need to be valid.
 896 This ioctl returns
 897 .Er EBUSY
 898 if another process is concurrently updating some of the same rulesets.
 899 .It Dv DIOCXROLLBACK Fa "struct pfioc_trans *io"
 900 Clean up the kernel by undoing all changes that have taken place on the
 901 inactive rulesets since the last
 902 .Dv DIOCXBEGIN .
 903 .Dv DIOCXROLLBACK
 904 will silently ignore rulesets for which the ticket is invalid.
 905 .It Dv DIOCSETHOSTID Fa "u_int32_t *hostid"
 906 Set the host ID, which is used by
 907 .Xr pfsync 4
 908 to identify which host created state table entries.
 909 .It Dv DIOCOSFPFLUSH
 910 Flush the passive OS fingerprint table.
 911 .It Dv DIOCOSFPADD Fa "struct pf_osfp_ioctl *io"
 912 .Bd -literal
 913 struct pf_osfp_ioctl {
 914         struct pf_osfp_entry {
 915                 SLIST_ENTRY(pf_osfp_entry) fp_entry;
 916                 pf_osfp_t               fp_os;
 917                 char                    fp_class_nm[PF_OSFP_LEN];
 918                 char                    fp_version_nm[PF_OSFP_LEN];
 919                 char                    fp_subtype_nm[PF_OSFP_LEN];
 920         }                       fp_os;
 921         pf_tcpopts_t            fp_tcpopts;
 922         u_int16_t               fp_wsize;
 923         u_int16_t               fp_psize;
 924         u_int16_t               fp_mss;
 925         u_int16_t               fp_flags;
 926         u_int8_t                fp_optcnt;
 927         u_int8_t                fp_wscale;
 928         u_int8_t                fp_ttl;
 929         int                     fp_getnum;
 930 };
 931 .Ed
 932 .Pp
 933 Add a passive OS fingerprint to the table.
 934 Set
 935 .Va fp_os.fp_os
 936 to the packed fingerprint,
 937 .Va fp_os.fp_class_nm
 938 to the name of the class (Linux, Windows, etc),
 939 .Va fp_os.fp_version_nm
 940 to the name of the version (NT, 95, 98), and
 941 .Va fp_os.fp_subtype_nm
 942 to the name of the subtype or patchlevel.
 943 The members
 944 .Va fp_mss ,
 945 .Va fp_wsize ,
 946 .Va fp_psize ,
 947 .Va fp_ttl ,
 948 .Va fp_optcnt ,
 949 and
 950 .Va fp_wscale
 951 are set to the TCP MSS, the TCP window size, the IP length, the IP TTL,
 952 the number of TCP options, and the TCP window scaling constant of the
 953 TCP SYN packet, respectively.
 954 .Pp
 955 The
 956 .Va fp_flags
 957 member is filled according to the
 958 .Aq Pa net/pfvar.h
 959 include file
 960 .Dv PF_OSFP_*
 961 defines.
 962 The
 963 .Va fp_tcpopts
 964 member contains packed TCP options.
 965 Each option uses
 966 .Dv PF_OSFP_TCPOPT_BITS
 967 bits in the packed value.
 968 Options include any of
 969 .Dv PF_OSFP_TCPOPT_NOP ,
 970 .Dv PF_OSFP_TCPOPT_SACK ,
 971 .Dv PF_OSFP_TCPOPT_WSCALE ,
 972 .Dv PF_OSFP_TCPOPT_MSS ,
 973 or
 974 .Dv PF_OSFP_TCPOPT_TS .
 975 .Pp
 976 The
 977 .Va fp_getnum
 978 member is not used with this ioctl.
 979 .Pp
 980 The structure's slack space must be zeroed for correct operation;
 981 .Xr memset 3
 982 the whole structure to zero before filling and sending to the kernel.
 983 .It Dv DIOCOSFPGET Fa "struct pf_osfp_ioctl *io"
 984 Get the passive OS fingerprint number
 985 .Va fp_getnum
 986 from the kernel's fingerprint list.
 987 The rest of the structure members will come back filled.
 988 Get the whole list by repeatedly incrementing the
 989 .Va fp_getnum
 990 number until the ioctl returns
 991 .Er EBUSY .
 992 .It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes *psn"
 993 .Bd -literal
 994 struct pfioc_src_nodes {
 995         int     psn_len;
 996         union {
 997                 caddr_t         psu_buf;
 998                 struct pf_src_node      *psu_src_nodes;
 999         } psn_u;
1000 #define psn_buf         psn_u.psu_buf
1001 #define psn_src_nodes   psn_u.psu_src_nodes
1002 };
1003 .Ed
1004 .Pp
1005 Get the list of source nodes kept by sticky addresses and source
1006 tracking.
1007 The ioctl must be called once with
1008 .Va psn_len
1009 set to 0.
1010 If the ioctl returns without error,
1011 .Va psn_len
1012 will be set to the size of the buffer required to hold all the
1013 .Va pf_src_node
1014 structures held in the table.
1015 A buffer of this size should then be allocated, and a pointer to this buffer
1016 placed in
1017 .Va psn_buf .
1018 The ioctl must then be called again to fill this buffer with the actual
1019 source node data.
1020 After that call,
1021 .Va psn_len
1022 will be set to the length of the buffer actually used.
1023 .It Dv DIOCCLRSRCNODES
1024 Clear the tree of source tracking nodes.
1025 .It Dv DIOCIGETIFACES Fa "struct pfioc_iface *io"
1026 Get the list of interfaces and interface drivers known to
1027 .Nm .
1028 All the ioctls that manipulate interfaces
1029 use the same structure described below:
1030 .Bd -literal
1031 struct pfioc_iface {
1032         char                     pfiio_name[IFNAMSIZ];
1033         void                    *pfiio_buffer;
1034         int                      pfiio_esize;
1035         int                      pfiio_size;
1036         int                      pfiio_nzero;
1037         int                      pfiio_flags;
1038 };
1039 .Ed
1040 .Pp
1041 If not empty,
1042 .Va pfiio_name
1043 can be used to restrict the search to a specific interface or driver.
1044 .Va pfiio_buffer[pfiio_size]
1045 is the user-supplied buffer for returning the data.
1046 On entry,
1047 .Va pfiio_size
1048 contains the number of
1049 .Vt pfi_kif
1050 entries that can fit into the buffer.
1051 The kernel will replace this value by the real number of entries it wants
1052 to return.
1053 .Va pfiio_esize
1054 should be set to
1055 .Li sizeof(struct pfi_kif) .
1056 .Pp
1057 The data is returned in the
1058 .Vt pfi_kif
1059 structure described below:
1060 .Bd -literal
1061 struct pfi_kif {
1062         RB_ENTRY(pfi_kif)                pfik_tree;
1063         char                             pfik_name[IFNAMSIZ];
1064         u_int64_t                        pfik_packets[2][2][2];
1065         u_int64_t                        pfik_bytes[2][2][2];
1066         u_int32_t                        pfik_tzero;
1067         int                              pfik_flags;
1068         struct pf_state_tree_lan_ext     pfik_lan_ext;
1069         struct pf_state_tree_ext_gwy     pfik_ext_gwy;
1070         TAILQ_ENTRY(pfi_kif)             pfik_w_states;
1071         void                            *pfik_ah_cookie;
1072         struct ifnet                    *pfik_ifp;
1073         struct ifg_group                *pfik_group;
1074         int                              pfik_states;
1075         int                              pfik_rules;
1076         TAILQ_HEAD(, pfi_dynaddr)        pfik_dynaddrs;
1077 };
1078 .Ed
1079 .It Dv DIOCSETIFFLAG Fa "struct pfioc_iface *io"
1080 Set the user setable flags (described above) of the
1081 .Nm
1082 internal interface description.
1083 The filtering process is the same as for
1084 .Dv DIOCIGETIFACES .
1085 .Bd -literal
1086 #define PFI_IFLAG_SKIP  0x0100  /* skip filtering on interface */
1087 .Ed
1088 .It Dv DIOCCLRIFFLAG Fa "struct pfioc_iface *io"
1089 Works as
1090 .Dv DIOCSETIFFLAG
1091 above but clears the flags.
1092 .It Dv DIOCKILLSRCNODES Fa "struct pfioc_iface *io"
1093 Explicitly remove source tracking nodes.
1094 .El
1095 .Sh FILES
1096 .Bl -tag -width /dev/pf -compact
1097 .It Pa /dev/pf
1098 packet filtering device.
1099 .El
1100 .Sh EXAMPLES
1101 The following example demonstrates how to use the
1102 .Dv DIOCNATLOOK
1103 command to find the internal host/port of a NATed connection:
1104 .Bd -literal
1105 #include <sys/types.h>
1106 #include <sys/socket.h>
1107 #include <sys/ioctl.h>
1108 #include <sys/fcntl.h>
1109 #include <net/if.h>
1110 #include <netinet/in.h>
1111 #include <net/pfvar.h>
1112 #include <err.h>
1113 #include <stdio.h>
1114 #include <stdlib.h>
1115
1116 u_int32_t
1117 read_address(const char *s)
1118 {
1119         int a, b, c, d;
1120
1121         sscanf(s, "%i.%i.%i.%i", &a, &b, &c, &d);
1122         return htonl(a << 24 | b << 16 | c << 8 | d);
1123 }
1124
1125 void
1126 print_address(u_int32_t a)
1127 {
1128         a = ntohl(a);
1129         printf("%d.%d.%d.%d", a >> 24 & 255, a >> 16 & 255,
1130             a >> 8 & 255, a & 255);
1131 }
1132
1133 int
1134 main(int argc, char *argv[])
1135 {
1136         struct pfioc_natlook nl;
1137         int dev;
1138
1139         if (argc != 5) {
1140                 printf("%s <gwy addr> <gwy port> <ext addr> <ext port>\\n",
1141                     argv[0]);
1142                 return 1;
1143         }
1144
1145         dev = open("/dev/pf", O_RDWR);
1146         if (dev == -1)
1147                 err(1, "open(\\"/dev/pf\\") failed");
1148
1149         memset(&nl, 0, sizeof(struct pfioc_natlook));
1150         nl.saddr.v4.s_addr      = read_address(argv[1]);
1151         nl.sport                = htons(atoi(argv[2]));
1152         nl.daddr.v4.s_addr      = read_address(argv[3]);
1153         nl.dport                = htons(atoi(argv[4]));
1154         nl.af                   = AF_INET;
1155         nl.proto                = IPPROTO_TCP;
1156         nl.direction            = PF_IN;
1157
1158         if (ioctl(dev, DIOCNATLOOK, &nl))
1159                 err(1, "DIOCNATLOOK");
1160
1161         printf("internal host ");
1162         print_address(nl.rsaddr.v4.s_addr);
1163         printf(":%u\\n", ntohs(nl.rsport));
1164         return 0;
1165 }
1166 .Ed
1167 .Sh SEE ALSO
1168 .Xr ioctl 2 ,
1169 .Xr altq 4 ,
1170 .Xr if_bridge 4 ,
1171 .Xr pflog 4 ,
1172 .Xr pflow 4 ,
1173 .Xr pfsync 4 ,
1174 .Xr pfctl 8 ,
1175 .Xr altq 9
1176 .Sh HISTORY
1177 The
1178 .Nm
1179 packet filtering mechanism first appeared in
1180 .Ox 3.0
1181 and then
1182 .Fx 5.2 .
1183 .Pp
1184 This implementation is derived from
1185 .Ox 4.5 .
1186 It has been heavily modified to be capable of running in multithreaded
1187 .Fx
1188 kernel and scale its performance on multiple CPUs.