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