share/man/man4/pf.4

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