share/man/man4/pf.4

   1 .\"     $OpenBSD: pf.4,v 1.46 2004/02/19 21:29:51 cedric Exp $
   2 .\"     $DragonFly: src/share/man/man4/pf.4,v 1.5 2007/05/19 17:32:12 swildner Exp $
   3 .\"
   4 .\" Copyright (C) 2001, Kjell Wooding.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the project nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .Dd June 24, 2001
  31 .Dt PF 4
  32 .Os
  33 .Sh NAME
  34 .Nm pf
  35 .Nd packet filter
  36 .Sh SYNOPSIS
  37 .Cd "device pf"
  38 .Sh DESCRIPTION
  39 Packet filtering takes place in the kernel.
  40 A pseudo-device,
  41 .Pa /dev/pf ,
  42 allows userland processes to control the
  43 behavior of the packet filter through an
  44 .Xr ioctl 2
  45 interface.
  46 There are commands to enable and disable the filter, load rulesets,
  47 add and remove individual rules or state table entries,
  48 and retrieve statistics.
  49 The most commonly used functions are covered by
  50 .Xr pfctl 8 .
  51 .Pp
  52 Manipulations like loading a ruleset that involve more than a single
  53 ioctl call require a so-called ticket, which prevents the occurrence of
  54 multiple concurrent manipulations.
  55 .Pp
  56 Fields of ioctl parameter structures that refer to packet data (like
  57 addresses and ports) are generally expected in network byte-order.
  58 .Sh FILES
  59 .Bl -tag -width /dev/pf -compact
  60 .It Pa /dev/pf
  61 packet filtering device.
  62 .El
  63 .Sh IOCTL INTERFACE
  64 pf supports the following
  65 .Xr ioctl 2
  66 commands:
  67 .Bl -tag -width xxxxxx
  68 .It Dv DIOCSTART
  69 Starts the packet filter.
  70 .It Dv DIOCSTOP
  71 Stops the packet filter.
  72 .It Dv DIOCSTARTALTQ
  73 Starts the
  74 .Xr altq 4
  75 bandwidth control system.
  76 .It Dv DIOCSTOPALTQ
  77 Stops the
  78 .Xr altq 4
  79 bandwidth control system.
  80 .It Dv DIOCBEGINADDRS  Fa "struct pfioc_pooladdr"
  81 .Bd -literal
  82 struct pfioc_pooladdr {
  83         u_int32_t               action;
  84         u_int32_t               ticket;
  85         u_int32_t               nr;
  86         u_int32_t               r_num;
  87         u_int8_t                r_action;
  88         u_int8_t                r_last;
  89         u_int8_t                af;
  90         char                    anchor[PF_ANCHOR_NAME_SIZE];
  91         char                    ruleset[PF_RULESET_NAME_SIZE];
  92         struct pf_pooladdr      addr;
  93 };
  94 .Ed
  95 .Pp
  96 Clears the buffer address pool
  97 and returns a
  98 .Va ticket
  99 for subsequent
 100 .Dv DIOCADDADDR ,
 101 .Dv DIOCADDRULE
 102 and
 103 .Dv DIOCCHANGERULE
 104 calls.
 105 .It Dv DIOCADDADDR     Fa "struct pfioc_pooladdr"
 106 .Pp
 107 Adds pool address
 108 .Va addr
 109 to the buffer address pool to be used in the following
 110 .Dv DIOCADDRULE
 111 or
 112 .Dv DIOCCHANGERULE
 113 call.
 114 All other members of the structure are ignored.
 115 .It Dv DIOCADDRULE     Fa "struct pfioc_rule"
 116 .Bd -literal
 117 struct pfioc_rule {
 118         u_int32_t       action;
 119         u_int32_t       ticket;
 120         u_int32_t       pool_ticket;
 121         u_int32_t       nr;
 122         char            anchor[PF_ANCHOR_NAME_SIZE];
 123         char            ruleset[PF_RULESET_NAME_SIZE];
 124         struct pf_rule  rule;
 125 };
 126 .Ed
 127 .Pp
 128 Adds
 129 .Va rule
 130 at the end of the inactive ruleset.
 131 Requires
 132 .Va ticket
 133 obtained through preceding
 134 .Dv DIOCXBEGIN
 135 call, and
 136 .Va pool_ticket
 137 obtained through
 138 .Dv DIOCBEGINADDRS
 139 call.
 140 .Dv DIOCADDADDR
 141 must also be called if any pool addresses are required.
 142 The optional
 143 .Va anchor
 144 and
 145 .Va ruleset
 146 names indicate the anchor and ruleset in which to append the rule.
 147 .Va nr
 148 and
 149 .Va action
 150 are ignored.
 151 .It Dv DIOCADDALTQ     Fa "struct pfioc_altq"
 152 Adds
 153 .Bd -literal
 154 struct pfioc_altq {
 155         u_int32_t       action;
 156         u_int32_t       ticket;
 157         u_int32_t       nr;
 158         struct pf_altq   altq;
 159 };
 160 .Ed
 161 .It Dv DIOCGETRULES    Fa "struct pfioc_rule"
 162 Returns
 163 .Va ticket
 164 for subsequent
 165 .Dv DIOCGETRULE
 166 calls and
 167 .Va nr
 168 of rules in the active ruleset.
 169 .It Dv DIOCGETRULE     Fa "struct pfioc_rule"
 170 Returns
 171 .Va rule
 172 number
 173 .Va nr
 174 using
 175 .Va ticket
 176 obtained through a preceding
 177 .Dv DIOCGETRULES
 178 call.
 179 .It Dv DIOCGETADDRS    Fa "struct pfioc_pooladdr"
 180 Returns
 181 .Va ticket
 182 for subsequent
 183 .Dv DIOCGETADDR
 184 calls and
 185 .Va nr
 186 of pool addresses in the rule specified with
 187 .Va r_action ,
 188 .Va r_num ,
 189 .Va anchor
 190 and
 191 .Va ruleset .
 192 .It Dv DIOCGETADDR     Fa "struct pfioc_pooladdr"
 193 Returns pool address
 194 .Va addr
 195 number
 196 .Va nr
 197 from the rule specified with
 198 .Va r_action ,
 199 .Va r_num ,
 200 .Va anchor
 201 and
 202 .Va ruleset
 203 using
 204 .Va ticket
 205 obtained through a preceding
 206 .Dv DIOCGETADDRS
 207 call.
 208 .It Dv DIOCGETALTQS    Fa "struct pfioc_altq"
 209 Returns
 210 .Va ticket
 211 for subsequent
 212 .Dv DIOCGETALTQ
 213 calls and
 214 .Va nr
 215 of queues in the active list.
 216 .It Dv DIOCGETALTQ     Fa "struct pfioc_altq"
 217 Returns
 218 .Va altq
 219 number
 220 .Va nr
 221 using
 222 .Va ticket
 223 obtained through a preceding
 224 .Dv DIOCGETALTQS
 225 call.
 226 .It Dv DIOCGETQSTATS   Fa "struct pfioc_qstats"
 227 Returns statistics on a queue.
 228 .Bd -literal
 229 struct pfioc_qstats {
 230         u_int32_t        ticket;
 231         u_int32_t        nr;
 232         void            *buf;
 233         int              nbytes;
 234         u_int8_t         scheduler;
 235 };
 236 .Ed
 237 .Pp
 238 A pointer to a buffer of statistics
 239 .Va buf
 240 of length
 241 .Va nbytes
 242 for the queue specified by
 243 .Va nr .
 244 .It Dv DIOCADDSTATE    Fa "struct pfioc_state"
 245 Adds a state entry.
 246 .It Dv DIOCGETSTATE    Fa "struct pfioc_state"
 247 .Bd -literal
 248 struct pfioc_state {
 249         u_int32_t        nr;
 250         struct pf_state  state;
 251 };
 252 .Ed
 253 .Pp
 254 Extracts the entry with the specified number from the state table.
 255 .It Dv DIOCKILLSTATES  Fa "struct pfioc_state_kill"
 256 Removes matching entries from the state table.
 257 Returns the number of killed states in psk_af.
 258 .Bd -literal
 259 struct pfioc_state_kill {
 260         int                     psk_af;
 261         int                     psk_proto;
 262         struct pf_rule_addr     psk_src;
 263         struct pf_rule_addr     psk_dst;
 264         char                    psk_ifname[IFNAMSIZ];
 265 };
 266 .Ed
 267 .It Dv DIOCCLRSTATES  Fa "struct pfioc_state_kill"
 268 Clears all states.
 269 It works like
 270 .Dv DIOCKILLSTATES ,
 271 but ignores the psk_af, psk_proto, psk_src and psk_dst fields of the
 272 .Fa pfioc_state_kill
 273 structure.
 274 .It Dv DIOCSETSTATUSIF Fa "struct pfioc_if"
 275 .Bd -literal
 276 struct pfioc_if {
 277         char             ifname[IFNAMSIZ];
 278 };
 279 .Ed
 280 .Pp
 281 Specifies the interface for which statistics are accumulated.
 282 .It Dv DIOCGETSTATUS   Fa "struct pf_status"
 283 .Bd -literal
 284 struct pf_status {
 285         u_int64_t       counters[PFRES_MAX];
 286         u_int64_t       fcounters[FCNT_MAX];
 287         u_int64_t       scounters[SCNT_MAX];
 288         u_int64_t       pcounters[2][2][3];
 289         u_int64_t       bcounters[2][2];
 290         u_int32_t       running;
 291         u_int32_t       states;
 292         u_int32_t       src_nodes;
 293         u_int32_t       since;
 294         u_int32_t       debug;
 295         char            ifname[IFNAMSIZ];
 296 };
 297 .Ed
 298 .Pp
 299 Gets the internal packet filter statistics.
 300 .It Dv DIOCCLRSTATUS
 301 Clears the internal packet filter statistics.
 302 .It Dv DIOCNATLOOK     Fa "struct pfioc_natlook"
 303 Looks up a state table entry by source and destination addresses and ports.
 304 .Bd -literal
 305 struct pfioc_natlook {
 306         struct pf_addr   saddr;
 307         struct pf_addr   daddr;
 308         struct pf_addr   rsaddr;
 309         struct pf_addr   rdaddr;
 310         u_int16_t        sport;
 311         u_int16_t        dport;
 312         u_int16_t        rsport;
 313         u_int16_t        rdport;
 314         sa_family_t      af;
 315         u_int8_t         proto;
 316         u_int8_t         direction;
 317 };
 318 .Ed
 319 .It Dv DIOCSETDEBUG    Fa "u_int32_t"
 320 Sets the debug level.
 321 .Bd -literal
 322 enum    { PF_DEBUG_NONE=0, PF_DEBUG_URGENT=1, PF_DEBUG_MISC=2 };
 323 .Ed
 324 .It Dv DIOCGETSTATES   Fa "struct pfioc_states"
 325 .Bd -literal
 326 struct pfioc_states {
 327         int     ps_len;
 328         union {
 329                 caddr_t psu_buf;
 330                 struct pf_state *psu_states;
 331         } ps_u;
 332 #define ps_buf          ps_u.psu_buf
 333 #define ps_states       ps_u.psu_states
 334 };
 335 .Ed
 336 .It Dv DIOCCHANGERULE  Fa "struct pfioc_rule"
 337 Adds or removes the
 338 .Va rule
 339 in the ruleset specified by
 340 .Va rule.action .
 341 .Bd -literal
 342 enum    { PF_CHANGE_ADD_HEAD=1, PF_CHANGE_ADD_TAIL=2,
 343           PF_CHANGE_ADD_BEFORE=3, PF_CHANGE_ADD_AFTER=4,
 344           PF_CHANGE_REMOVE=5, PF_CHANGE_GET_TICKET=6 };
 345 .Ed
 346 .Pp
 347 The type of operation to be performed is indicated by
 348 .Va action .
 349 .Pp
 350 .Va ticket
 351 must be set to the value obtained with PF_CHANGE_GET_TICKET
 352 for all actions except PF_CHANGE_GET_TICKET.
 353 .Va pool_ticket
 354 must be set to the value obtained with the
 355 .Dv DIOCBEGINADDRS
 356 call for all actions except PF_CHANGE_REMOVE and PF_CHANGE_GET_TICKET.
 357 .Pp
 358 .Va anchor
 359 and
 360 .Va ruleset
 361 indicate which anchor and ruleset the operation applies to.
 362 .Va nr
 363 indicates the rule number against which PF_CHANGE_ADD_BEFORE,
 364 PF_CHANGE_ADD_AFTER or PF_CHANGE_REMOVE actions are applied.
 365 .It Dv DIOCCHANGEADDR  Fa "struct pfioc_pooladdr"
 366 Adds or removes a pool address
 367 .Va addr
 368 from a rule specified with
 369 .Va r_action ,
 370 .Va r_num ,
 371 .Va anchor
 372 and
 373 .Va ruleset .
 374 .It Dv DIOCSETTIMEOUT  Fa "struct pfioc_tm"
 375 .Bd -literal
 376 struct pfioc_tm {
 377         int              timeout;
 378         int              seconds;
 379 };
 380 .Ed
 381 .It Dv DIOCGETTIMEOUT  Fa "struct pfioc_tm"
 382 .It Dv DIOCCLRRULECTRS
 383 Clear per-rule statistics.
 384 .It Dv DIOCSETLIMIT   Fa "struct pfioc_limit"
 385 Sets hard limits on the memory pools used by the packet filter.
 386 .Bd -literal
 387 struct pfioc_limit {
 388         int             index;
 389         unsigned        limit;
 390 };
 391 .Ed
 392 .It Dv DIOCGETLIMIT   Fa "struct pfioc_limit"
 393 .It Dv DIOCRCLRTABLES Fa "struct pfioc_table"
 394 Clear all tables.
 395 All the IOCTLs that manipulate radix tables
 396 use the same structure described below.
 397 For
 398 .Dv DIOCRCLRTABLES, pfrio_ndel contains on exit the number
 399 of tables deleted.
 400 .Bd -literal
 401 struct pfioc_table {
 402         struct pfr_table         pfrio_table;
 403         void                    *pfrio_buffer;
 404         int                      pfrio_esize;
 405         int                      pfrio_size;
 406         int                      pfrio_size2;
 407         int                      pfrio_nadd;
 408         int                      pfrio_ndel;
 409         int                      pfrio_nchange;
 410         int                      pfrio_flags;
 411         int                      pfrio_ticket;
 412 };
 413 #define pfrio_exists    pfrio_nadd
 414 #define pfrio_nzero     pfrio_nadd
 415 #define pfrio_nmatch    pfrio_nadd
 416 #define pfrio_naddr     pfrio_size2
 417 #define pfrio_setflag   pfrio_size2
 418 #define pfrio_clrflag   pfrio_nadd
 419 .Ed
 420 .It Dv DIOCRADDTABLES Fa "struct pfioc_table"
 421 Creates one or more tables.
 422 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
 423 On exit, pfrio_nadd contains the number of tables effectively created.
 424 .Bd -literal
 425 struct pfr_table {
 426         char                     pfrt_anchor[PF_ANCHOR_NAME_SIZE];
 427         char                     pfrt_ruleset[PF_RULESET_NAME_SIZE];
 428         char                     pfrt_name[PF_TABLE_NAME_SIZE];
 429         u_int32_t                pfrt_flags;
 430         u_int8_t                 pfrt_fback;
 431 };
 432 .Ed
 433 .It Dv DIOCRDELTABLES Fa "struct pfioc_table"
 434 Deletes one or more tables.
 435 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
 436 On exit, pfrio_nadd contains the number of tables effectively deleted.
 437 .It Dv DIOCRGETTABLES Fa "struct pfioc_table"
 438 Get the list of all tables.
 439 On entry, pfrio_buffer[pfrio_size] contains a valid writeable buffer for
 440 pfr_table structures.
 441 On exit, pfrio_size contains the number of tables written into the buffer.
 442 If the buffer is too small, the kernel does not store anything but just
 443 returns the required buffer size, without error.
 444 .It Dv DIOCRGETTSTATS Fa "struct pfioc_table"
 445 Like
 446 .Dv DIOCRGETTABLES ,
 447 but returns an array of pfr_tstats structures.
 448 .Bd -literal
 449 struct pfr_tstats {
 450         struct pfr_table pfrts_t;
 451         u_int64_t        pfrts_packets
 452                              [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
 453         u_int64_t        pfrts_bytes
 454                              [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
 455         u_int64_t        pfrts_match;
 456         u_int64_t        pfrts_nomatch;
 457         long             pfrts_tzero;
 458         int              pfrts_cnt;
 459         int              pfrts_refcnt[PFR_REFCNT_MAX];
 460 };
 461 #define pfrts_name      pfrts_t.pfrt_name
 462 #define pfrts_flags     pfrts_t.pfrt_flags
 463 .Ed
 464 .It Dv DIOCRCLRTSTATS Fa "struct pfioc_table"
 465 Clears the statistics of one or more tables.
 466 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
 467 On exit, pfrio_nzero contains the number of tables effectively cleared.
 468 .It Dv DIOCRCLRADDRS Fa "struct pfioc_table"
 469 Clear all addresses in a table.
 470 On entry, pfrio_table contains the table to clear.
 471 On exit, pfrio_ndel contains the number of addresses removed.
 472 .It Dv DIOCRADDADDRS Fa "struct pfioc_table"
 473 Add one or more addresses to a table.
 474 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 475 contains the list of pfr_addr structures to add.
 476 On exit, pfrio_nadd contains the number of addresses effectively added.
 477 .Bd -literal
 478 struct pfr_addr {
 479         union {
 480                 struct in_addr   _pfra_ip4addr;
 481                 struct in6_addr  _pfra_ip6addr;
 482         }                pfra_u;
 483         u_int8_t         pfra_af;
 484         u_int8_t         pfra_net;
 485         u_int8_t         pfra_not;
 486         u_int8_t         pfra_fback;
 487 };
 488 #define pfra_ip4addr    pfra_u._pfra_ip4addr
 489 #define pfra_ip6addr    pfra_u._pfra_ip6addr
 490 .Ed
 491 .It Dv DIOCRDELADDRS Fa "struct pfioc_table"
 492 Delete one or more addresses from a table.
 493 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 494 contains the list of pfr_addr structures to delete.
 495 On exit, pfrio_ndel contains the number of addresses effectively deleted.
 496 .It Dv DIOCRSETADDRS Fa "struct pfioc_table"
 497 Replace the content of a table by a new address list.
 498 This is the most complicated command, which uses all the structure members.
 499 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 500 contains the new list of pfr_addr structures.
 501 In addition to that, if size2 is nonzero, pfrio_buffer[pfrio_size..pfrio_size2]
 502 must be a writeable buffer, into which the kernel can copy the addresses that
 503 have been deleted during the replace operation.
 504 On exit, pfrio_ndel, pfrio_nadd and pfrio_nchange contain the number of
 505 addresses deleted, added and changed by the kernel.
 506 If pfrio_size2 was set on
 507 entry, pfrio_size2 will point to the size of the buffer used, exactly like
 508 .Dv DIOCRGETADDRS .
 509 .It Dv DIOCRGETADDRS Fa "struct pfioc_table"
 510 Get all the addresses of a table.
 511 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 512 contains a valid writeable buffer for pfr_addr structures.
 513 On exit, pfrio_size contains the number of addresses written into the buffer.
 514 If the buffer was too small, the kernel does not store anything but just
 515 return the required buffer size, without returning an error.
 516 .It Dv DIOCRGETASTATS Fa "struct pfioc_table"
 517 Like
 518 .Dv DIOCRGETADDRS ,
 519 but returns an array of pfr_astats structures.
 520 .Bd -literal
 521 struct pfr_astats {
 522         struct pfr_addr  pfras_a;
 523         u_int64_t        pfras_packets
 524                              [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
 525         u_int64_t        pfras_bytes
 526                              [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
 527         long             pfras_tzero;
 528 };
 529 .Ed
 530 .It Dv DIOCRCLRASTATS Fa "struct pfioc_table"
 531 Clears the statistics of one or more addresses.
 532 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 533 contains a table of pfr_addr structures to clear.
 534 On exit, pfrio_nzero contains the number of addresses effectively cleared.
 535 .It Dv DIOCRTSTADDRS Fa "struct pfioc_table"
 536 Test if the given addresses match a table.
 537 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 538 contains a table of pfr_addr structures to test.
 539 On exit, the kernel updates the pfr_addr table by setting the pfra_fback
 540 member appropriately.
 541 .It Dv DIOCRSETTFLAGS Fa "struct pfioc_table"
 542 Change the
 543 .Va const
 544 or
 545 .Va persist
 546 flag of a table.
 547 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures,
 548 and pfrio_setflag contains the flags to add, while pfrio_clrflag contains the
 549 flags to remove.
 550 On exit, pfrio_nchange and pfrio_ndel contain the number of tables altered
 551 or deleted by the kernel.
 552 Yes, tables can be deleted if one removes the
 553 .Va persist
 554 flag of an unreferenced table.
 555 .It Dv DIOCRINADEFINE Fa "struct pfioc_table"
 556 Defines a table in the inactive set.
 557 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 558 contains the list of pfr_addr structures to put in the table.
 559 A valid ticket must also be supplied to pfrio_ticket.
 560 On exit, pfrio_nadd contains 0 if the table was already defined in the
 561 inactive list, or 1 if a new table has been created.
 562 pfrio_naddr contains the number of addresses effectively put in the table.
 563 .It Dv DIOCXBEGIN Fa "struct pfioc_trans"
 564 .Bd -literal
 565 #define PF_RULESET_ALTQ         (PF_RULESET_MAX)
 566 #define PF_RULESET_TABLE        (PF_RULESET_MAX+1)
 567 struct pfioc_trans {
 568         int              size;  /* number of elements */
 569         int              esize; /* size of each element in bytes */
 570         struct pfioc_trans_e {
 571                 int             rs_num;
 572                 char            anchor[PF_ANCHOR_NAME_SIZE];
 573                 char            ruleset[PF_RULESET_NAME_SIZE];
 574                 u_int32_t       ticket;
 575         }               *array;
 576 };
 577 .Ed
 578 .Pp
 579 Clears all the inactive rulesets specified in the
 580 .Fa "struct pfioc_trans_e"
 581 array.
 582 For each ruleset, a ticket is returned for subsequent "add rule" IOCTLs,
 583 as well as for the
 584 .Dv DIOCXCOMMIT
 585 and
 586 .Dv DIOCXROLLBACK
 587 calls.
 588 .It Dv DIOCXCOMMIT Fa "struct pfioc_trans"
 589 Atomically switch a vector of inactive rulesets to the active rulesets.
 590 Implemented as a standard 2-phase commit, which will either fail for all
 591 rulesets or completely succeed.
 592 All tickets need to be valid.
 593 Returns
 594 .Er EBUSY
 595 if a concurrent process is trying to update some of the same rulesets
 596 concurrently.
 597 .It Dv DIOCXROLLBACK Fa "struct pfioc_trans"
 598 Clean up the kernel by undoing all changes that have taken place on the
 599 inactive rulesets since the last
 600 .Dv DIOCXBEGIN .
 601 .Dv DIOCXROLLBACK
 602 will silently ignore rulesets for which the ticket is invalid.
 603 .It Dv DIOCFPFLUSH
 604 Flush the passive OS fingerprint table.
 605 .It Dv DIOCFPADD Fa "struct pf_osfp_ioctl"
 606 .Bd -literal
 607 struct pf_osfp_ioctl {
 608         struct pf_osfp_entry {
 609                 SLIST_ENTRY(pf_osfp_entry) fp_entry;
 610                 pf_osfp_t               fp_os;
 611                 char                    fp_class_nm[PF_OSFP_LEN];
 612                 char                    fp_version_nm[PF_OSFP_LEN];
 613                 char                    fp_subtype_nm[PF_OSFP_LEN];
 614         }                       fp_os;
 615         u_int16_t               fp_mss;
 616         u_int16_t               fp_wsize;
 617         u_int16_t               fp_psize;
 618         u_int8_t                fp_ttl;
 619         u_int8_t                fp_wscale;
 620         u_int8_t                fp_flags;
 621         int                     fp_getnum;
 622 };
 623 .Ed
 624 .Pp
 625 Add a passive OS fingerprint to the table.
 626 Set
 627 .Va fp_os.fp_os
 628 to the packed fingerprint,
 629 .Va fp_os.fp_class_nm
 630 to the name of the class (Linux, Windows, etc),
 631 .Va fp_os.fp_version_nm
 632 to the name of the version (NT, 95, 98), and
 633 .Va fp_os.fp_subtype_nm
 634 to the name of the subtype or patchlevel.
 635 The members
 636 .Va fp_mss ,
 637 .Va fp_wsize ,
 638 .Va fp_psize ,
 639 .Va fp_ttl ,
 640 and
 641 .Va fp_wscale
 642 are set to the TCP MSS, the TCP window size, the IP length and the IP TTL of
 643 the TCP SYN packet respectively.
 644 The
 645 .Va fp_flags
 646 member is filled according to the
 647 .In net/pf/pfvar.h
 648 include file PF_OSFP_* defines.
 649 The
 650 .Va fp_getnum
 651 is not used with this ioctl.
 652 .Pp
 653 The structure's slack space must be zeroed for correct operation; memset
 654 the whole structure to zero before filling and sending to the kernel.
 655 .It Dv DIOCFPGET Fa "struct pf_osfp_ioctl"
 656 .Bd -literal
 657 struct pf_osfp_ioctl {
 658         struct pf_osfp_entry {
 659                 SLIST_ENTRY(pf_osfp_entry) fp_entry;
 660                 pf_osfp_t               fp_os;
 661                 char                    fp_class_nm[PF_OSFP_LEN];
 662                 char                    fp_version_nm[PF_OSFP_LEN];
 663                 char                    fp_subtype_nm[PF_OSFP_LEN];
 664         }                       fp_os;
 665         u_int16_t               fp_mss;
 666         u_int16_t               fp_wsize;
 667         u_int16_t               fp_psize;
 668         u_int8_t                fp_ttl;
 669         u_int8_t                fp_wscale;
 670         u_int8_t                fp_flags;
 671         int                     fp_getnum;
 672 };
 673 .Ed
 674 .Pp
 675 Get the passive OS fingerprint number
 676 .Va fp_getnum
 677 from the kernel's fingerprint list.
 678 The rest of the structure members will come back filled.
 679 Get the whole list by repeatedly incrementing the
 680 .Va fp_getnum
 681 number until the ioctl returns
 682 .Er EBUSY .
 683 .It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes"
 684 .Bd -literal
 685 struct pfioc_src_nodes {
 686         int     psn_len;
 687         union {
 688                 caddr_t          psu_buf;
 689                 struct pf_src_node      *psu_src_nodes;
 690         } psn_u;
 691 #define psn_buf         psn_u.psu_buf
 692 #define psn_src_nodes   psn_u.psu_src_nodes
 693 };
 694 .Ed
 695 .Pp
 696 Get the list of source nodes kept by the
 697 .Ar sticky-address
 698 and
 699 .Ar source-track
 700 options.
 701 The ioctl must be called once with
 702 .Va psn_len
 703 set to 0.
 704 If the ioctl returns without error,
 705 .Va psn_len
 706 will be set to the size of the buffer required to hold all the
 707 .Va pf_src_node
 708 structures held in the table.
 709 A buffer of this size should then be allocated, and a pointer to this buffer
 710 placed in
 711 .Va psn_buf .
 712 The ioctl must then be called again to fill this buffer with the actual
 713 source node data.
 714 After the ioctl call
 715 .Va psn_len
 716 will be set to the length of the buffer actually used.
 717 .It Dv DIOCCLRSRCNODES Fa "struct pfioc_table"
 718 Clear the tree of source tracking nodes.
 719 .It Dv DIOCIGETIFACES Fa "struct pfioc_iface"
 720 Gets the list of interfaces and interface drivers known to
 721 .Nm .
 722 All the IOCTLs that manipulate interfaces
 723 use the same structure described below:
 724 .Bd -literal
 725 struct pfioc_iface {
 726         char                     pfiio_name[IFNAMSIZ];
 727         void                    *pfiio_buffer;
 728         int                      pfiio_esize;
 729         int                      pfiio_size;
 730         int                      pfiio_nzero;
 731         int                      pfiio_flags;
 732 };
 733
 734 #define PFI_FLAG_GROUP     0x0001  /* gets groups of interfaces */
 735 #define PFI_FLAG_INSTANCE  0x0002  /* gets single interfaces */
 736 #define PFI_FLAG_ALLMASK   0x0003
 737 .Ed
 738 .Pp
 739 If not empty,
 740 .Va pfiio_name
 741 can be used to restrict the search to a specific interface or driver.
 742 .Va pfiio_buffer[pfiio_size]
 743 is the user-supplied buffer for returning the data.
 744 On entry,
 745 .Va pfiio_size
 746 represents the number of
 747 .Va pfi_if
 748 entries that can fit into the buffer.
 749 The kernel will replace this value by the real number of entries it wants
 750 to return.
 751 .Va pfiio_esize
 752 should be set to sizeof(struct pfi_if).
 753 .Va pfiio_flags
 754 should be set to
 755 .Dv PFI_FLAG_GROUP , PFI_FLAG_INSTANCE ,
 756 or both to tell the kernel to return a group of interfaces
 757 (drivers, like "fxp"), real interface instances (like "fxp1") or both.
 758 The data is returned in the
 759 .Va pfi_if
 760 structure described below:
 761 .Bd -literal
 762 struct pfi_if {
 763         char                             pfif_name[IFNAMSIZ];
 764         u_int64_t                        pfif_packets[2][2][2];
 765         u_int64_t                        pfif_bytes[2][2][2];
 766         u_int64_t                        pfif_addcnt;
 767         u_int64_t                        pfif_delcnt;
 768         long                             pfif_tzero;
 769         int                              pfif_states;
 770         int                              pfif_rules;
 771         int                              pfif_flags;
 772 };
 773
 774 #define PFI_IFLAG_GROUP         0x0001  /* group of interfaces */
 775 #define PFI_IFLAG_INSTANCE      0x0002  /* single instance */
 776 #define PFI_IFLAG_CLONABLE      0x0010  /* clonable group */
 777 #define PFI_IFLAG_DYNAMIC       0x0020  /* dynamic group */
 778 #define PFI_IFLAG_ATTACHED      0x0040  /* interface attached */
 779 #define PFI_IFLAG_REFERENCED    0x0080  /* referenced by rules */
 780 .Ed
 781 .It Dv DIOCICLRISTATS Fa "struct pfioc_iface"
 782 Clear the statistics counters of one or more interfaces.
 783 .Va pfiio_name
 784 and
 785 .Va pfrio_flags
 786 can be used to select which interfaces need to be cleared.
 787 The filtering process is the same as for
 788 .Dv DIOCIGETIFACES .
 789 .Va pfiio_nzero
 790 will be set by the kernel to the number of interfaces and drivers
 791 that have been cleared.
 792 .El
 793 .Sh EXAMPLES
 794 The following example demonstrates how to use the
 795 .Dv DIOCNATLOOK
 796 command to find the internal host/port of a NATed connection.
 797 .Bd -literal
 798 #include <sys/types.h>
 799 #include <sys/socket.h>
 800 #include <sys/ioctl.h>
 801 #include <sys/fcntl.h>
 802 #include <net/if.h>
 803 #include <netinet/in.h>
 804 #include <net/pfvar.h>
 805 #include <err.h>
 806 #include <stdio.h>
 807 #include <stdlib.h>
 808
 809 u_int32_t
 810 read_address(const char *s)
 811 {
 812         int a, b, c, d;
 813
 814         sscanf(s, "%i.%i.%i.%i", &a, &b, &c, &d);
 815         return htonl(a << 24 | b << 16 | c << 8 | d);
 816 }
 817
 818 void
 819 print_address(u_int32_t a)
 820 {
 821         a = ntohl(a);
 822         printf("%d.%d.%d.%d", a >> 24 & 255, a >> 16 & 255,
 823             a >> 8 & 255, a & 255);
 824 }
 825
 826 int
 827 main(int argc, char *argv[])
 828 {
 829         struct pfioc_natlook nl;
 830         int dev;
 831
 832         if (argc != 5) {
 833                 printf("%s <gwy addr> <gwy port> <ext addr> <ext port>\\n",
 834                     argv[0]);
 835                 return 1;
 836         }
 837
 838         dev = open("/dev/pf", O_RDWR);
 839         if (dev == -1)
 840                 err(1, "open(\\"/dev/pf\\") failed");
 841
 842         memset(&nl, 0, sizeof(struct pfioc_natlook));
 843         nl.saddr.v4.s_addr      = read_address(argv[1]);
 844         nl.sport                = htons(atoi(argv[2]));
 845         nl.daddr.v4.s_addr      = read_address(argv[3]);
 846         nl.dport                = htons(atoi(argv[4]));
 847         nl.af                   = AF_INET;
 848         nl.proto                = IPPROTO_TCP;
 849         nl.direction            = PF_IN;
 850
 851         if (ioctl(dev, DIOCNATLOOK, &nl))
 852                 err(1, "DIOCNATLOOK");
 853
 854         printf("internal host ");
 855         print_address(nl.rsaddr.v4.s_addr);
 856         printf(":%u\\n", ntohs(nl.rsport));
 857         return 0;
 858 }
 859 .Ed
 860 .Sh SEE ALSO
 861 .Xr ioctl 2 ,
 862 .Xr bridge 4 ,
 863 .Xr pflog 4 ,
 864 .Xr pfsync 4 ,
 865 .Xr pfctl 8
 866 .Sh HISTORY
 867 The
 868 .Nm
 869 packet filtering mechanism first appeared in
 870 .Ox 3.0
 871 and was imported into
 872 .Dx 1.1
 873 by Devon H. O'Dell and Simon Schubert.