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 May 7, 2021
  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 131072.
  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 32768.
  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 DIOCGETSTATENV Fa "struct pfioc_nv *nv"
 330 Extract the entry identified by the
 331 .Va id
 332 and
 333 .Va creatorid
 334 fields of the
 335 .Va state
 336 nvlist 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 DIOCGETSTATESNV Fa "struct pfioc_nv *nv"
 419 Get state table entries.
 420 .Bd -literal
 421 nvlist pf_state_key {
 422         nvlist pf_addr  addr[2];
 423         number          port[2];
 424         number          af;
 425         number          proto;
 426 };
 427
 428 nvlist pf_state_scrub {
 429         bool    timestamp;
 430         number  ttl;
 431         number  ts_mod;
 432 };
 433
 434 nvlist pf_state_peer {
 435         nvlist pf_state_scrub   scrub;
 436         number                  seqlo;
 437         number                  seqhi;
 438         number                  seqdiff;
 439         number                  max_win;
 440         number                  mss;
 441         number                  state;
 442         number                  wscale;
 443 };
 444
 445 nvlist pf_state {
 446         number                  id;
 447         string                  ifname;
 448         nvlist pf_state_key     stack_key;
 449         nvlist pf_state_key     wire_key;
 450         nvlist pf_state_peer    src;
 451         nvlist pf_state_peer    dst;
 452         nvlist pf_addr          rt_addr;
 453         number                  rule;
 454         number                  anchor;
 455         number                  nat_rule;
 456         number                  expire;
 457         number                  packets[2];
 458         number                  bytes[2];
 459         number                  creatorid;
 460         number                  direction;
 461         number                  log;
 462         number                  state_flags;
 463         number                  timeout;
 464         number                  sync_flags;
 465 };
 466
 467 nvlist pf_states {
 468         number          count;
 469         nvlist pf_state states[];
 470 };
 471 .Ed
 472 .Pp
 473 If
 474 .Va pfioc_nv.size
 475 is insufficiently large, as many states as possible that can fit into this
 476 size will be copied into the supplied buffer.
 477 .It Dv DIOCCHANGERULE Fa "struct pfioc_rule *pcr"
 478 Add or remove the
 479 .Va rule
 480 in the ruleset specified by
 481 .Va rule.action .
 482 .Pp
 483 The type of operation to be performed is indicated by
 484 .Va action ,
 485 which can be any of the following:
 486 .Bd -literal
 487 enum    { PF_CHANGE_NONE, PF_CHANGE_ADD_HEAD, PF_CHANGE_ADD_TAIL,
 488           PF_CHANGE_ADD_BEFORE, PF_CHANGE_ADD_AFTER,
 489           PF_CHANGE_REMOVE, PF_CHANGE_GET_TICKET };
 490 .Ed
 491 .Pp
 492 .Va ticket
 493 must be set to the value obtained with
 494 .Dv PF_CHANGE_GET_TICKET
 495 for all actions except
 496 .Dv PF_CHANGE_GET_TICKET .
 497 .Va pool_ticket
 498 must be set to the value obtained with the
 499 .Dv DIOCBEGINADDRS
 500 call for all actions except
 501 .Dv PF_CHANGE_REMOVE
 502 and
 503 .Dv PF_CHANGE_GET_TICKET .
 504 .Va anchor
 505 indicates to which anchor the operation applies.
 506 .Va nr
 507 indicates the rule number against which
 508 .Dv PF_CHANGE_ADD_BEFORE ,
 509 .Dv PF_CHANGE_ADD_AFTER ,
 510 or
 511 .Dv PF_CHANGE_REMOVE
 512 actions are applied.
 513 .\" It Dv DIOCCHANGEALTQ Fa "struct pfioc_altq *pcr"
 514 .It Dv DIOCCHANGEADDR Fa "struct pfioc_pooladdr *pca"
 515 Add or remove the pool address
 516 .Va addr
 517 from the rule specified by
 518 .Va r_action ,
 519 .Va r_num ,
 520 and
 521 .Va anchor .
 522 .It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm *pt"
 523 .Bd -literal
 524 struct pfioc_tm {
 525         int              timeout;
 526         int              seconds;
 527 };
 528 .Ed
 529 .Pp
 530 Set the state timeout of
 531 .Va timeout
 532 to
 533 .Va seconds .
 534 The old value will be placed into
 535 .Va seconds .
 536 For possible values of
 537 .Va timeout ,
 538 consult the
 539 .Dv PFTM_*
 540 values in
 541 .Aq Pa net/pfvar.h .
 542 .It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm *pt"
 543 Get the state timeout of
 544 .Va timeout .
 545 The value will be placed into the
 546 .Va seconds
 547 field.
 548 .It Dv DIOCCLRRULECTRS
 549 Clear per-rule statistics.
 550 .It Dv DIOCSETLIMIT Fa "struct pfioc_limit *pl"
 551 Set the hard limits on the memory pools used by the packet filter.
 552 .Bd -literal
 553 struct pfioc_limit {
 554         int             index;
 555         unsigned        limit;
 556 };
 557
 558 enum    { PF_LIMIT_STATES, PF_LIMIT_SRC_NODES, PF_LIMIT_FRAGS,
 559           PF_LIMIT_TABLE_ENTRIES, PF_LIMIT_MAX };
 560 .Ed
 561 .It Dv DIOCGETLIMIT Fa "struct pfioc_limit *pl"
 562 Get the hard
 563 .Va limit
 564 for the memory pool indicated by
 565 .Va index .
 566 .It Dv DIOCRCLRTABLES Fa "struct pfioc_table *io"
 567 Clear all tables.
 568 All the ioctls that manipulate radix tables
 569 use the same structure described below.
 570 For
 571 .Dv DIOCRCLRTABLES ,
 572 .Va pfrio_ndel
 573 contains on exit the number of tables deleted.
 574 .Bd -literal
 575 struct pfioc_table {
 576         struct pfr_table         pfrio_table;
 577         void                    *pfrio_buffer;
 578         int                      pfrio_esize;
 579         int                      pfrio_size;
 580         int                      pfrio_size2;
 581         int                      pfrio_nadd;
 582         int                      pfrio_ndel;
 583         int                      pfrio_nchange;
 584         int                      pfrio_flags;
 585         u_int32_t                pfrio_ticket;
 586 };
 587 #define pfrio_exists    pfrio_nadd
 588 #define pfrio_nzero     pfrio_nadd
 589 #define pfrio_nmatch    pfrio_nadd
 590 #define pfrio_naddr     pfrio_size2
 591 #define pfrio_setflag   pfrio_size2
 592 #define pfrio_clrflag   pfrio_nadd
 593 .Ed
 594 .It Dv DIOCRADDTABLES Fa "struct pfioc_table *io"
 595 Create one or more tables.
 596 On entry,
 597 .Va pfrio_buffer
 598 must point to an array of
 599 .Vt struct pfr_table
 600 containing at least
 601 .Vt pfrio_size
 602 elements.
 603 .Vt pfrio_esize
 604 must be the size of
 605 .Vt struct pfr_table .
 606 On exit,
 607 .Va pfrio_nadd
 608 contains the number of tables effectively created.
 609 .Bd -literal
 610 struct pfr_table {
 611         char            pfrt_anchor[MAXPATHLEN];
 612         char            pfrt_name[PF_TABLE_NAME_SIZE];
 613         u_int32_t       pfrt_flags;
 614         u_int8_t        pfrt_fback;
 615 };
 616 .Ed
 617 .It Dv DIOCRDELTABLES Fa "struct pfioc_table *io"
 618 Delete one or more tables.
 619 On entry,
 620 .Va pfrio_buffer
 621 must point to an array of
 622 .Vt struct pfr_table
 623 containing at least
 624 .Vt pfrio_size
 625 elements.
 626 .Vt pfrio_esize
 627 must be the size of
 628 .Vt struct pfr_table .
 629 On exit,
 630 .Va pfrio_ndel
 631 contains the number of tables effectively deleted.
 632 .It Dv DIOCRGETTABLES Fa "struct pfioc_table *io"
 633 Get the list of all tables.
 634 On entry,
 635 .Va pfrio_buffer[pfrio_size]
 636 contains a valid writeable buffer for
 637 .Vt pfr_table
 638 structures.
 639 On exit,
 640 .Va pfrio_size
 641 contains the number of tables written into the buffer.
 642 If the buffer is too small, the kernel does not store anything but just
 643 returns the required buffer size, without error.
 644 .It Dv DIOCRGETTSTATS Fa "struct pfioc_table *io"
 645 This call is like
 646 .Dv DIOCRGETTABLES
 647 but is used to get an array of
 648 .Vt pfr_tstats
 649 structures.
 650 .Bd -literal
 651 struct pfr_tstats {
 652         struct pfr_table pfrts_t;
 653         u_int64_t        pfrts_packets
 654                              [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
 655         u_int64_t        pfrts_bytes
 656                              [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
 657         u_int64_t        pfrts_match;
 658         u_int64_t        pfrts_nomatch;
 659         long             pfrts_tzero;
 660         int              pfrts_cnt;
 661         int              pfrts_refcnt[PFR_REFCNT_MAX];
 662 };
 663 #define pfrts_name       pfrts_t.pfrt_name
 664 #define pfrts_flags      pfrts_t.pfrt_flags
 665 .Ed
 666 .It Dv DIOCRCLRTSTATS Fa "struct pfioc_table *io"
 667 Clear the statistics of one or more tables.
 668 On entry,
 669 .Va pfrio_buffer
 670 must point to an array of
 671 .Vt struct pfr_table
 672 containing at least
 673 .Vt pfrio_size
 674 elements.
 675 .Vt pfrio_esize
 676 must be the size of
 677 .Vt struct pfr_table .
 678 On exit,
 679 .Va pfrio_nzero
 680 contains the number of tables effectively cleared.
 681 .It Dv DIOCRCLRADDRS Fa "struct pfioc_table *io"
 682 Clear all addresses in a table.
 683 On entry,
 684 .Va pfrio_table
 685 contains the table to clear.
 686 On exit,
 687 .Va pfrio_ndel
 688 contains the number of addresses removed.
 689 .It Dv DIOCRADDADDRS Fa "struct pfioc_table *io"
 690 Add one or more addresses to a table.
 691 On entry,
 692 .Va pfrio_table
 693 contains the table ID and
 694 .Va pfrio_buffer
 695 must point to an array of
 696 .Vt struct pfr_addr
 697 containing at least
 698 .Vt pfrio_size
 699 elements to add to the table.
 700 .Vt pfrio_esize
 701 must be the size of
 702 .Vt struct pfr_addr .
 703 On exit,
 704 .Va pfrio_nadd
 705 contains the number of addresses effectively added.
 706 .Bd -literal
 707 struct pfr_addr {
 708         union {
 709                 struct in_addr   _pfra_ip4addr;
 710                 struct in6_addr  _pfra_ip6addr;
 711         }                pfra_u;
 712         u_int8_t         pfra_af;
 713         u_int8_t         pfra_net;
 714         u_int8_t         pfra_not;
 715         u_int8_t         pfra_fback;
 716 };
 717 #define pfra_ip4addr    pfra_u._pfra_ip4addr
 718 #define pfra_ip6addr    pfra_u._pfra_ip6addr
 719 .Ed
 720 .It Dv DIOCRDELADDRS Fa "struct pfioc_table *io"
 721 Delete one or more addresses from a table.
 722 On entry,
 723 .Va pfrio_table
 724 contains the table ID and
 725 .Va pfrio_buffer
 726 must point to an array of
 727 .Vt struct pfr_addr
 728 containing at least
 729 .Vt pfrio_size
 730 elements to delete from the table.
 731 .Vt pfrio_esize
 732 must be the size of
 733 .Vt struct pfr_addr .
 734 On exit,
 735 .Va pfrio_ndel
 736 contains the number of addresses effectively deleted.
 737 .It Dv DIOCRSETADDRS Fa "struct pfioc_table *io"
 738 Replace the content of a table by a new address list.
 739 This is the most complicated command, which uses all the structure members.
 740 .Pp
 741 On entry,
 742 .Va pfrio_table
 743 contains the table ID and
 744 .Va pfrio_buffer
 745 must point to an array of
 746 .Vt struct pfr_addr
 747 containing at least
 748 .Vt pfrio_size
 749 elements which become the new contents of the table.
 750 .Vt pfrio_esize
 751 must be the size of
 752 .Vt struct pfr_addr .
 753 Additionally, if
 754 .Va pfrio_size2
 755 is non-zero,
 756 .Va pfrio_buffer[pfrio_size..pfrio_size2]
 757 must be a writeable buffer, into which the kernel can copy the
 758 addresses that have been deleted during the replace operation.
 759 On exit,
 760 .Va pfrio_ndel ,
 761 .Va pfrio_nadd ,
 762 and
 763 .Va pfrio_nchange
 764 contain the number of addresses deleted, added, and changed by the
 765 kernel.
 766 If
 767 .Va pfrio_size2
 768 was set on entry,
 769 .Va pfrio_size2
 770 will point to the size of the buffer used, exactly like
 771 .Dv DIOCRGETADDRS .
 772 .It Dv DIOCRGETADDRS Fa "struct pfioc_table *io"
 773 Get all the addresses of a table.
 774 On entry,
 775 .Va pfrio_table
 776 contains the table ID and
 777 .Va pfrio_buffer[pfrio_size]
 778 contains a valid writeable buffer for
 779 .Vt pfr_addr
 780 structures.
 781 On exit,
 782 .Va pfrio_size
 783 contains the number of addresses written into the buffer.
 784 If the buffer was too small, the kernel does not store anything but just
 785 returns the required buffer size, without returning an error.
 786 .It Dv DIOCRGETASTATS Fa "struct pfioc_table *io"
 787 This call is like
 788 .Dv DIOCRGETADDRS
 789 but is used to get an array of
 790 .Vt pfr_astats
 791 structures.
 792 .Bd -literal
 793 struct pfr_astats {
 794         struct pfr_addr  pfras_a;
 795         u_int64_t        pfras_packets
 796                              [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
 797         u_int64_t        pfras_bytes
 798                              [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
 799         long             pfras_tzero;
 800 };
 801 .Ed
 802 .It Dv DIOCRCLRASTATS Fa "struct pfioc_table *io"
 803 Clear the statistics of one or more addresses.
 804 On entry,
 805 .Va pfrio_table
 806 contains the table ID and
 807 .Va pfrio_buffer
 808 must point to an array of
 809 .Vt struct pfr_addr
 810 containing at least
 811 .Vt pfrio_size
 812 elements to be cleared from the table.
 813 .Vt pfrio_esize
 814 must be the size of
 815 .Vt struct pfr_addr .
 816 On exit,
 817 .Va pfrio_nzero
 818 contains the number of addresses effectively cleared.
 819 .It Dv DIOCRTSTADDRS Fa "struct pfioc_table *io"
 820 Test if the given addresses match a table.
 821 On entry,
 822 .Va pfrio_table
 823 contains the table ID and
 824 .Va pfrio_buffer
 825 must point to an array of
 826 .Vt struct pfr_addr
 827 containing at least
 828 .Vt pfrio_size
 829 elements, each of which will be tested for a match in the table.
 830 .Vt pfrio_esize
 831 must be the size of
 832 .Vt struct pfr_addr .
 833 On exit, the kernel updates the
 834 .Vt pfr_addr
 835 array by setting the
 836 .Va pfra_fback
 837 member appropriately.
 838 .It Dv DIOCRSETTFLAGS Fa "struct pfioc_table *io"
 839 Change the
 840 .Dv PFR_TFLAG_CONST
 841 or
 842 .Dv PFR_TFLAG_PERSIST
 843 flags of a table.
 844 On entry,
 845 .Va pfrio_buffer
 846 must point to an array of
 847 .Vt struct pfr_table
 848 containing at least
 849 .Vt pfrio_size
 850 elements.
 851 .Va pfrio_esize
 852 must be the size of
 853 .Vt struct pfr_table .
 854 .Va pfrio_setflag
 855 must contain the flags to add, while
 856 .Va pfrio_clrflag
 857 must contain the flags to remove.
 858 On exit,
 859 .Va pfrio_nchange
 860 and
 861 .Va pfrio_ndel
 862 contain the number of tables altered or deleted by the kernel.
 863 Yes, tables can be deleted if one removes the
 864 .Dv PFR_TFLAG_PERSIST
 865 flag of an unreferenced table.
 866 .It Dv DIOCRINADEFINE Fa "struct pfioc_table *io"
 867 Defines a table in the inactive set.
 868 On entry,
 869 .Va pfrio_table
 870 contains the table ID and
 871 .Va pfrio_buffer[pfrio_size]
 872 contains an array of
 873 .Vt pfr_addr
 874 structures to put in the table.
 875 A valid ticket must also be supplied to
 876 .Va pfrio_ticket .
 877 On exit,
 878 .Va pfrio_nadd
 879 contains 0 if the table was already defined in the inactive list
 880 or 1 if a new table has been created.
 881 .Va pfrio_naddr
 882 contains the number of addresses effectively put in the table.
 883 .It Dv DIOCXBEGIN Fa "struct pfioc_trans *io"
 884 .Bd -literal
 885 struct pfioc_trans {
 886         int              size;  /* number of elements */
 887         int              esize; /* size of each element in bytes */
 888         struct pfioc_trans_e {
 889                 int             rs_num;
 890                 char            anchor[MAXPATHLEN];
 891                 u_int32_t       ticket;
 892         }               *array;
 893 };
 894 .Ed
 895 .Pp
 896 Clear all the inactive rulesets specified in the
 897 .Vt pfioc_trans_e
 898 array.
 899 For each ruleset, a ticket is returned for subsequent "add rule" ioctls,
 900 as well as for the
 901 .Dv DIOCXCOMMIT
 902 and
 903 .Dv DIOCXROLLBACK
 904 calls.
 905 .Pp
 906 Ruleset types, identified by
 907 .Va rs_num ,
 908 include the following:
 909 .Pp
 910 .Bl -tag -width PF_RULESET_FILTER -offset ind -compact
 911 .It Dv PF_RULESET_SCRUB
 912 Scrub (packet normalization) rules.
 913 .It Dv PF_RULESET_FILTER
 914 Filter rules.
 915 .It Dv PF_RULESET_NAT
 916 NAT (Network Address Translation) rules.
 917 .It Dv PF_RULESET_BINAT
 918 Bidirectional NAT rules.
 919 .It Dv PF_RULESET_RDR
 920 Redirect rules.
 921 .It Dv PF_RULESET_ALTQ
 922 ALTQ disciplines.
 923 .It Dv PF_RULESET_TABLE
 924 Address tables.
 925 .El
 926 .It Dv DIOCXCOMMIT Fa "struct pfioc_trans *io"
 927 Atomically switch a vector of inactive rulesets to the active rulesets.
 928 This call is implemented as a standard two-phase commit, which will either
 929 fail for all rulesets or completely succeed.
 930 All tickets need to be valid.
 931 This ioctl returns
 932 .Er EBUSY
 933 if another process is concurrently updating some of the same rulesets.
 934 .It Dv DIOCXROLLBACK Fa "struct pfioc_trans *io"
 935 Clean up the kernel by undoing all changes that have taken place on the
 936 inactive rulesets since the last
 937 .Dv DIOCXBEGIN .
 938 .Dv DIOCXROLLBACK
 939 will silently ignore rulesets for which the ticket is invalid.
 940 .It Dv DIOCSETHOSTID Fa "u_int32_t *hostid"
 941 Set the host ID, which is used by
 942 .Xr pfsync 4
 943 to identify which host created state table entries.
 944 .It Dv DIOCOSFPFLUSH
 945 Flush the passive OS fingerprint table.
 946 .It Dv DIOCOSFPADD Fa "struct pf_osfp_ioctl *io"
 947 .Bd -literal
 948 struct pf_osfp_ioctl {
 949         struct pf_osfp_entry {
 950                 SLIST_ENTRY(pf_osfp_entry) fp_entry;
 951                 pf_osfp_t               fp_os;
 952                 char                    fp_class_nm[PF_OSFP_LEN];
 953                 char                    fp_version_nm[PF_OSFP_LEN];
 954                 char                    fp_subtype_nm[PF_OSFP_LEN];
 955         }                       fp_os;
 956         pf_tcpopts_t            fp_tcpopts;
 957         u_int16_t               fp_wsize;
 958         u_int16_t               fp_psize;
 959         u_int16_t               fp_mss;
 960         u_int16_t               fp_flags;
 961         u_int8_t                fp_optcnt;
 962         u_int8_t                fp_wscale;
 963         u_int8_t                fp_ttl;
 964         int                     fp_getnum;
 965 };
 966 .Ed
 967 .Pp
 968 Add a passive OS fingerprint to the table.
 969 Set
 970 .Va fp_os.fp_os
 971 to the packed fingerprint,
 972 .Va fp_os.fp_class_nm
 973 to the name of the class (Linux, Windows, etc),
 974 .Va fp_os.fp_version_nm
 975 to the name of the version (NT, 95, 98), and
 976 .Va fp_os.fp_subtype_nm
 977 to the name of the subtype or patchlevel.
 978 The members
 979 .Va fp_mss ,
 980 .Va fp_wsize ,
 981 .Va fp_psize ,
 982 .Va fp_ttl ,
 983 .Va fp_optcnt ,
 984 and
 985 .Va fp_wscale
 986 are set to the TCP MSS, the TCP window size, the IP length, the IP TTL,
 987 the number of TCP options, and the TCP window scaling constant of the
 988 TCP SYN packet, respectively.
 989 .Pp
 990 The
 991 .Va fp_flags
 992 member is filled according to the
 993 .Aq Pa net/pfvar.h
 994 include file
 995 .Dv PF_OSFP_*
 996 defines.
 997 The
 998 .Va fp_tcpopts
 999 member contains packed TCP options.
1000 Each option uses
1001 .Dv PF_OSFP_TCPOPT_BITS
1002 bits in the packed value.
1003 Options include any of
1004 .Dv PF_OSFP_TCPOPT_NOP ,
1005 .Dv PF_OSFP_TCPOPT_SACK ,
1006 .Dv PF_OSFP_TCPOPT_WSCALE ,
1007 .Dv PF_OSFP_TCPOPT_MSS ,
1008 or
1009 .Dv PF_OSFP_TCPOPT_TS .
1010 .Pp
1011 The
1012 .Va fp_getnum
1013 member is not used with this ioctl.
1014 .Pp
1015 The structure's slack space must be zeroed for correct operation;
1016 .Xr memset 3
1017 the whole structure to zero before filling and sending to the kernel.
1018 .It Dv DIOCOSFPGET Fa "struct pf_osfp_ioctl *io"
1019 Get the passive OS fingerprint number
1020 .Va fp_getnum
1021 from the kernel's fingerprint list.
1022 The rest of the structure members will come back filled.
1023 Get the whole list by repeatedly incrementing the
1024 .Va fp_getnum
1025 number until the ioctl returns
1026 .Er EBUSY .
1027 .It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes *psn"
1028 .Bd -literal
1029 struct pfioc_src_nodes {
1030         int     psn_len;
1031         union {
1032                 caddr_t         psu_buf;
1033                 struct pf_src_node      *psu_src_nodes;
1034         } psn_u;
1035 #define psn_buf         psn_u.psu_buf
1036 #define psn_src_nodes   psn_u.psu_src_nodes
1037 };
1038 .Ed
1039 .Pp
1040 Get the list of source nodes kept by sticky addresses and source
1041 tracking.
1042 The ioctl must be called once with
1043 .Va psn_len
1044 set to 0.
1045 If the ioctl returns without error,
1046 .Va psn_len
1047 will be set to the size of the buffer required to hold all the
1048 .Va pf_src_node
1049 structures held in the table.
1050 A buffer of this size should then be allocated, and a pointer to this buffer
1051 placed in
1052 .Va psn_buf .
1053 The ioctl must then be called again to fill this buffer with the actual
1054 source node data.
1055 After that call,
1056 .Va psn_len
1057 will be set to the length of the buffer actually used.
1058 .It Dv DIOCCLRSRCNODES
1059 Clear the tree of source tracking nodes.
1060 .It Dv DIOCIGETIFACES Fa "struct pfioc_iface *io"
1061 Get the list of interfaces and interface drivers known to
1062 .Nm .
1063 All the ioctls that manipulate interfaces
1064 use the same structure described below:
1065 .Bd -literal
1066 struct pfioc_iface {
1067         char                     pfiio_name[IFNAMSIZ];
1068         void                    *pfiio_buffer;
1069         int                      pfiio_esize;
1070         int                      pfiio_size;
1071         int                      pfiio_nzero;
1072         int                      pfiio_flags;
1073 };
1074 .Ed
1075 .Pp
1076 If not empty,
1077 .Va pfiio_name
1078 can be used to restrict the search to a specific interface or driver.
1079 .Va pfiio_buffer[pfiio_size]
1080 is the user-supplied buffer for returning the data.
1081 On entry,
1082 .Va pfiio_size
1083 contains the number of
1084 .Vt pfi_kif
1085 entries that can fit into the buffer.
1086 The kernel will replace this value by the real number of entries it wants
1087 to return.
1088 .Va pfiio_esize
1089 should be set to
1090 .Li sizeof(struct pfi_kif) .
1091 .Pp
1092 The data is returned in the
1093 .Vt pfi_kif
1094 structure described below:
1095 .Bd -literal
1096 struct pfi_kif {
1097         RB_ENTRY(pfi_kif)                pfik_tree;
1098         char                             pfik_name[IFNAMSIZ];
1099         u_int64_t                        pfik_packets[2][2][2];
1100         u_int64_t                        pfik_bytes[2][2][2];
1101         u_int32_t                        pfik_tzero;
1102         int                              pfik_flags;
1103         struct pf_state_tree_lan_ext     pfik_lan_ext;
1104         struct pf_state_tree_ext_gwy     pfik_ext_gwy;
1105         TAILQ_ENTRY(pfi_kif)             pfik_w_states;
1106         void                            *pfik_ah_cookie;
1107         struct ifnet                    *pfik_ifp;
1108         struct ifg_group                *pfik_group;
1109         int                              pfik_states;
1110         int                              pfik_rules;
1111         TAILQ_HEAD(, pfi_dynaddr)        pfik_dynaddrs;
1112 };
1113 .Ed
1114 .It Dv DIOCSETIFFLAG Fa "struct pfioc_iface *io"
1115 Set the user settable flags (described above) of the
1116 .Nm
1117 internal interface description.
1118 The filtering process is the same as for
1119 .Dv DIOCIGETIFACES .
1120 .Bd -literal
1121 #define PFI_IFLAG_SKIP  0x0100  /* skip filtering on interface */
1122 .Ed
1123 .It Dv DIOCCLRIFFLAG Fa "struct pfioc_iface *io"
1124 Works as
1125 .Dv DIOCSETIFFLAG
1126 above but clears the flags.
1127 .It Dv DIOCKILLSRCNODES Fa "struct pfioc_iface *io"
1128 Explicitly remove source tracking nodes.
1129 .El
1130 .Sh FILES
1131 .Bl -tag -width /dev/pf -compact
1132 .It Pa /dev/pf
1133 packet filtering device.
1134 .El
1135 .Sh EXAMPLES
1136 The following example demonstrates how to use the
1137 .Dv DIOCNATLOOK
1138 command to find the internal host/port of a NATed connection:
1139 .Bd -literal
1140 #include <sys/types.h>
1141 #include <sys/socket.h>
1142 #include <sys/ioctl.h>
1143 #include <sys/fcntl.h>
1144 #include <net/if.h>
1145 #include <netinet/in.h>
1146 #include <net/pfvar.h>
1147 #include <err.h>
1148 #include <stdio.h>
1149 #include <stdlib.h>
1150
1151 u_int32_t
1152 read_address(const char *s)
1153 {
1154         int a, b, c, d;
1155
1156         sscanf(s, "%i.%i.%i.%i", &a, &b, &c, &d);
1157         return htonl(a << 24 | b << 16 | c << 8 | d);
1158 }
1159
1160 void
1161 print_address(u_int32_t a)
1162 {
1163         a = ntohl(a);
1164         printf("%d.%d.%d.%d", a >> 24 & 255, a >> 16 & 255,
1165             a >> 8 & 255, a & 255);
1166 }
1167
1168 int
1169 main(int argc, char *argv[])
1170 {
1171         struct pfioc_natlook nl;
1172         int dev;
1173
1174         if (argc != 5) {
1175                 printf("%s <gwy addr> <gwy port> <ext addr> <ext port>\\n",
1176                     argv[0]);
1177                 return 1;
1178         }
1179
1180         dev = open("/dev/pf", O_RDWR);
1181         if (dev == -1)
1182                 err(1, "open(\\"/dev/pf\\") failed");
1183
1184         memset(&nl, 0, sizeof(struct pfioc_natlook));
1185         nl.saddr.v4.s_addr      = read_address(argv[1]);
1186         nl.sport                = htons(atoi(argv[2]));
1187         nl.daddr.v4.s_addr      = read_address(argv[3]);
1188         nl.dport                = htons(atoi(argv[4]));
1189         nl.af                   = AF_INET;
1190         nl.proto                = IPPROTO_TCP;
1191         nl.direction            = PF_IN;
1192
1193         if (ioctl(dev, DIOCNATLOOK, &nl))
1194                 err(1, "DIOCNATLOOK");
1195
1196         printf("internal host ");
1197         print_address(nl.rsaddr.v4.s_addr);
1198         printf(":%u\\n", ntohs(nl.rsport));
1199         return 0;
1200 }
1201 .Ed
1202 .Sh SEE ALSO
1203 .Xr ioctl 2 ,
1204 .Xr altq 4 ,
1205 .Xr if_bridge 4 ,
1206 .Xr pflog 4 ,
1207 .Xr pfsync 4 ,
1208 .Xr pfctl 8 ,
1209 .Xr altq 9
1210 .Sh HISTORY
1211 The
1212 .Nm
1213 packet filtering mechanism first appeared in
1214 .Ox 3.0
1215 and then
1216 .Fx 5.2 .
1217 .Pp
1218 This implementation is derived from
1219 .Ox 4.5 .
1220 It has been heavily modified to be capable of running in multithreaded
1221 .Fx
1222 kernel and scale its performance on multiple CPUs.