contrib/pf/man/pf.4

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