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