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