contrib/pf/man/pf.4

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