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.4 2006/10/14 23:46:23 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 ALTQ bandwidth control system.
  74 .It Dv DIOCSTOPALTQ
  75 Stops the ALTQ bandwidth control system.
  76 .It Dv DIOCBEGINADDRS  Fa "struct pfioc_pooladdr"
  77 .Bd -literal
  78 struct pfioc_pooladdr {
  79         u_int32_t               action;
  80         u_int32_t               ticket;
  81         u_int32_t               nr;
  82         u_int32_t               r_num;
  83         u_int8_t                r_action;
  84         u_int8_t                r_last;
  85         u_int8_t                af;
  86         char                    anchor[PF_ANCHOR_NAME_SIZE];
  87         char                    ruleset[PF_RULESET_NAME_SIZE];
  88         struct pf_pooladdr      addr;
  89 };
  90 .Ed
  91 .Pp
  92 Clears the buffer address pool
  93 and returns a
  94 .Va ticket
  95 for subsequent DIOCADDADDR, DIOCADDRULE and DIOCCHANGERULE calls.
  96 .It Dv DIOCADDADDR     Fa "struct pfioc_pooladdr"
  97 .Pp
  98 Adds pool address
  99 .Va addr
 100 to the buffer address pool to be used in the following
 101 DIOCADDRULE or DIOCCHANGERULE call.
 102 All other members of the structure are ignored.
 103 .It Dv DIOCADDRULE     Fa "struct pfioc_rule"
 104 .Bd -literal
 105 struct pfioc_rule {
 106         u_int32_t       action;
 107         u_int32_t       ticket;
 108         u_int32_t       pool_ticket;
 109         u_int32_t       nr;
 110         char            anchor[PF_ANCHOR_NAME_SIZE];
 111         char            ruleset[PF_RULESET_NAME_SIZE];
 112         struct pf_rule  rule;
 113 };
 114 .Ed
 115 .Pp
 116 Adds
 117 .Va rule
 118 at the end of the inactive ruleset.
 119 Requires
 120 .Va ticket
 121 obtained through preceding DIOCXBEGIN call, and
 122 .Va pool_ticket
 123 obtained through DIOCBEGINADDRS call.
 124 DIOCADDADDR must also be called if any pool addresses are required.
 125 The optional
 126 .Va anchor
 127 and
 128 .Va ruleset
 129 names indicate the anchor and ruleset in which to append the rule.
 130 .Va nr
 131 and
 132 .Va action
 133 are ignored.
 134 .It Dv DIOCADDALTQ     Fa "struct pfioc_altq"
 135 Adds
 136 .Bd -literal
 137 struct pfioc_altq {
 138         u_int32_t       action;
 139         u_int32_t       ticket;
 140         u_int32_t       nr;
 141         struct pf_altq   altq;
 142 };
 143 .Ed
 144 .It Dv DIOCGETRULES    Fa "struct pfioc_rule"
 145 Returns
 146 .Va ticket
 147 for subsequent DIOCGETRULE calls and
 148 .Va nr
 149 of rules in the active ruleset.
 150 .It Dv DIOCGETRULE     Fa "struct pfioc_rule"
 151 Returns
 152 .Va rule
 153 number
 154 .Va nr
 155 using
 156 .Va ticket
 157 obtained through a preceding DIOCGETRULES call.
 158 .It Dv DIOCGETADDRS    Fa "struct pfioc_pooladdr"
 159 Returns
 160 .Va ticket
 161 for subsequent DIOCGETADDR calls and
 162 .Va nr
 163 of pool addresses in the rule specified with
 164 .Va r_action ,
 165 .Va r_num ,
 166 .Va anchor
 167 and
 168 .Va ruleset .
 169 .It Dv DIOCGETADDR     Fa "struct pfioc_pooladdr"
 170 Returns pool address
 171 .Va addr
 172 number
 173 .Va nr
 174 from the rule specified with
 175 .Va r_action ,
 176 .Va r_num ,
 177 .Va anchor
 178 and
 179 .Va ruleset
 180 using
 181 .Va ticket
 182 obtained through a preceding DIOCGETADDRS call.
 183 .It Dv DIOCGETALTQS    Fa "struct pfioc_altq"
 184 Returns
 185 .Va ticket
 186 for subsequent DIOCGETALTQ calls and
 187 .Va nr
 188 of queues in the active list.
 189 .It Dv DIOCGETALTQ     Fa "struct pfioc_altq"
 190 Returns
 191 .Va altq
 192 number
 193 .Va nr
 194 using
 195 .Va ticket
 196 obtained through a preceding DIOCGETALTQS call.
 197 .It Dv DIOCGETQSTATS   Fa "struct pfioc_qstats"
 198 Returns statistics on a queue.
 199 .Bd -literal
 200 struct pfioc_qstats {
 201         u_int32_t        ticket;
 202         u_int32_t        nr;
 203         void            *buf;
 204         int              nbytes;
 205         u_int8_t         scheduler;
 206 };
 207 .Ed
 208 .Pp
 209 A pointer to a buffer of statistics
 210 .Va buf
 211 of length
 212 .Va nbytes
 213 for the queue specified by
 214 .Va nr .
 215 .It Dv DIOCADDSTATE    Fa "struct pfioc_state"
 216 Adds a state entry.
 217 .It Dv DIOCGETSTATE    Fa "struct pfioc_state"
 218 .Bd -literal
 219 struct pfioc_state {
 220         u_int32_t        nr;
 221         struct pf_state  state;
 222 };
 223 .Ed
 224 .Pp
 225 Extracts the entry with the specified number from the state table.
 226 .It Dv DIOCKILLSTATES  Fa "struct pfioc_state_kill"
 227 Removes matching entries from the state table.
 228 Returns the number of killed states in psk_af.
 229 .Bd -literal
 230 struct pfioc_state_kill {
 231         int                     psk_af;
 232         int                     psk_proto;
 233         struct pf_rule_addr     psk_src;
 234         struct pf_rule_addr     psk_dst;
 235         char                    psk_ifname[IFNAMSIZ];
 236 };
 237 .Ed
 238 .It Dv DIOCCLRSTATES  Fa "struct pfioc_state_kill"
 239 Clears all states.
 240 It works like
 241 .Dv DIOCKILLSTATES ,
 242 but ignores the psk_af, psk_proto, psk_src and psk_dst fields of the
 243 .Fa pfioc_state_kill
 244 structure.
 245 .It Dv DIOCSETSTATUSIF Fa "struct pfioc_if"
 246 .Bd -literal
 247 struct pfioc_if {
 248         char             ifname[IFNAMSIZ];
 249 };
 250 .Ed
 251 .Pp
 252 Specifies the interface for which statistics are accumulated.
 253 .It Dv DIOCGETSTATUS   Fa "struct pf_status"
 254 .Bd -literal
 255 struct pf_status {
 256         u_int64_t       counters[PFRES_MAX];
 257         u_int64_t       fcounters[FCNT_MAX];
 258         u_int64_t       scounters[SCNT_MAX];
 259         u_int64_t       pcounters[2][2][3];
 260         u_int64_t       bcounters[2][2];
 261         u_int32_t       running;
 262         u_int32_t       states;
 263         u_int32_t       src_nodes;
 264         u_int32_t       since;
 265         u_int32_t       debug;
 266         char            ifname[IFNAMSIZ];
 267 };
 268 .Ed
 269 .Pp
 270 Gets the internal packet filter statistics.
 271 .It Dv DIOCCLRSTATUS
 272 Clears the internal packet filter statistics.
 273 .It Dv DIOCNATLOOK     Fa "struct pfioc_natlook"
 274 Looks up a state table entry by source and destination addresses and ports.
 275 .Bd -literal
 276 struct pfioc_natlook {
 277         struct pf_addr   saddr;
 278         struct pf_addr   daddr;
 279         struct pf_addr   rsaddr;
 280         struct pf_addr   rdaddr;
 281         u_int16_t        sport;
 282         u_int16_t        dport;
 283         u_int16_t        rsport;
 284         u_int16_t        rdport;
 285         sa_family_t      af;
 286         u_int8_t         proto;
 287         u_int8_t         direction;
 288 };
 289 .Ed
 290 .It Dv DIOCSETDEBUG    Fa "u_int32_t"
 291 Sets the debug level.
 292 .Bd -literal
 293 enum    { PF_DEBUG_NONE=0, PF_DEBUG_URGENT=1, PF_DEBUG_MISC=2 };
 294 .Ed
 295 .It Dv DIOCGETSTATES   Fa "struct pfioc_states"
 296 .Bd -literal
 297 struct pfioc_states {
 298         int     ps_len;
 299         union {
 300                 caddr_t psu_buf;
 301                 struct pf_state *psu_states;
 302         } ps_u;
 303 #define ps_buf          ps_u.psu_buf
 304 #define ps_states       ps_u.psu_states
 305 };
 306 .Ed
 307 .It Dv DIOCCHANGERULE  Fa "struct pfioc_rule"
 308 Adds or removes the
 309 .Va rule
 310 in the ruleset specified by
 311 .Va rule.action .
 312 .Bd -literal
 313 enum    { PF_CHANGE_ADD_HEAD=1, PF_CHANGE_ADD_TAIL=2,
 314           PF_CHANGE_ADD_BEFORE=3, PF_CHANGE_ADD_AFTER=4,
 315           PF_CHANGE_REMOVE=5, PF_CHANGE_GET_TICKET=6 };
 316 .Ed
 317 .Pp
 318 The type of operation to be performed is indicated by
 319 .Va action .
 320 .Pp
 321 .Va ticket
 322 must be set to the value obtained with PF_CHANGE_GET_TICKET
 323 for all actions except PF_CHANGE_GET_TICKET.
 324 .Va pool_ticket
 325 must be set to the value obtained with the DIOCBEGINADDRS call
 326 for all actions except PF_CHANGE_REMOVE and PF_CHANGE_GET_TICKET.
 327 .Pp
 328 .Va anchor
 329 and
 330 .Va ruleset
 331 indicate which anchor and ruleset the operation applies to.
 332 .Va nr
 333 indicates the rule number against which PF_CHANGE_ADD_BEFORE,
 334 PF_CHANGE_ADD_AFTER or PF_CHANGE_REMOVE actions are applied.
 335 .It Dv DIOCCHANGEADDR  Fa "struct pfioc_pooladdr"
 336 Adds or removes a pool address
 337 .Va addr
 338 from a rule specified with
 339 .Va r_action ,
 340 .Va r_num ,
 341 .Va anchor
 342 and
 343 .Va ruleset .
 344 .It Dv DIOCSETTIMEOUT  Fa "struct pfioc_tm"
 345 .Bd -literal
 346 struct pfioc_tm {
 347         int              timeout;
 348         int              seconds;
 349 };
 350 .Ed
 351 .It Dv DIOCGETTIMEOUT  Fa "struct pfioc_tm"
 352 .It Dv DIOCCLRRULECTRS
 353 Clear per-rule statistics.
 354 .It Dv DIOCSETLIMIT   Fa "struct pfioc_limit"
 355 Sets hard limits on the memory pools used by the packet filter.
 356 .Bd -literal
 357 struct pfioc_limit {
 358         int             index;
 359         unsigned        limit;
 360 };
 361 .Ed
 362 .It Dv DIOCGETLIMIT   Fa "struct pfioc_limit"
 363 .It Dv DIOCRCLRTABLES Fa "struct pfioc_table"
 364 Clear all tables.
 365 All the IOCTLs that manipulate radix tables
 366 use the same structure described below.
 367 For
 368 .Dv DIOCRCLRTABLES, pfrio_ndel contains on exit the number
 369 of tables deleted.
 370 .Bd -literal
 371 struct pfioc_table {
 372         struct pfr_table         pfrio_table;
 373         void                    *pfrio_buffer;
 374         int                      pfrio_esize;
 375         int                      pfrio_size;
 376         int                      pfrio_size2;
 377         int                      pfrio_nadd;
 378         int                      pfrio_ndel;
 379         int                      pfrio_nchange;
 380         int                      pfrio_flags;
 381         int                      pfrio_ticket;
 382 };
 383 #define pfrio_exists    pfrio_nadd
 384 #define pfrio_nzero     pfrio_nadd
 385 #define pfrio_nmatch    pfrio_nadd
 386 #define pfrio_naddr     pfrio_size2
 387 #define pfrio_setflag   pfrio_size2
 388 #define pfrio_clrflag   pfrio_nadd
 389 .Ed
 390 .It Dv DIOCRADDTABLES Fa "struct pfioc_table"
 391 Creates one or more tables.
 392 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
 393 On exit, pfrio_nadd contains the number of tables effectively created.
 394 .Bd -literal
 395 struct pfr_table {
 396         char                     pfrt_anchor[PF_ANCHOR_NAME_SIZE];
 397         char                     pfrt_ruleset[PF_RULESET_NAME_SIZE];
 398         char                     pfrt_name[PF_TABLE_NAME_SIZE];
 399         u_int32_t                pfrt_flags;
 400         u_int8_t                 pfrt_fback;
 401 };
 402 .Ed
 403 .It Dv DIOCRDELTABLES Fa "struct pfioc_table"
 404 Deletes one or more tables.
 405 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
 406 On exit, pfrio_nadd contains the number of tables effectively deleted.
 407 .It Dv DIOCRGETTABLES Fa "struct pfioc_table"
 408 Get the list of all tables.
 409 On entry, pfrio_buffer[pfrio_size] contains a valid writeable buffer for
 410 pfr_table structures.
 411 On exit, pfrio_size contains the number of tables written into the buffer.
 412 If the buffer is too small, the kernel does not store anything but just
 413 returns the required buffer size, without error.
 414 .It Dv DIOCRGETTSTATS Fa "struct pfioc_table"
 415 Like
 416 .Dv DIOCRGETTABLES ,
 417 but returns an array of pfr_tstats structures.
 418 .Bd -literal
 419 struct pfr_tstats {
 420         struct pfr_table pfrts_t;
 421         u_int64_t        pfrts_packets
 422                              [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
 423         u_int64_t        pfrts_bytes
 424                              [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
 425         u_int64_t        pfrts_match;
 426         u_int64_t        pfrts_nomatch;
 427         long             pfrts_tzero;
 428         int              pfrts_cnt;
 429         int              pfrts_refcnt[PFR_REFCNT_MAX];
 430 };
 431 #define pfrts_name      pfrts_t.pfrt_name
 432 #define pfrts_flags     pfrts_t.pfrt_flags
 433 .Ed
 434 .It Dv DIOCRCLRTSTATS Fa "struct pfioc_table"
 435 Clears the statistics of one or more tables.
 436 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
 437 On exit, pfrio_nzero contains the number of tables effectively cleared.
 438 .It Dv DIOCRCLRADDRS Fa "struct pfioc_table"
 439 Clear all addresses in a table.
 440 On entry, pfrio_table contains the table to clear.
 441 On exit, pfrio_ndel contains the number of addresses removed.
 442 .It Dv DIOCRADDADDRS Fa "struct pfioc_table"
 443 Add one or more addresses to a table.
 444 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 445 contains the list of pfr_addr structures to add.
 446 On exit, pfrio_nadd contains the number of addresses effectively added.
 447 .Bd -literal
 448 struct pfr_addr {
 449         union {
 450                 struct in_addr   _pfra_ip4addr;
 451                 struct in6_addr  _pfra_ip6addr;
 452         }                pfra_u;
 453         u_int8_t         pfra_af;
 454         u_int8_t         pfra_net;
 455         u_int8_t         pfra_not;
 456         u_int8_t         pfra_fback;
 457 };
 458 #define pfra_ip4addr    pfra_u._pfra_ip4addr
 459 #define pfra_ip6addr    pfra_u._pfra_ip6addr
 460 .Ed
 461 .It Dv DIOCRDELADDRS Fa "struct pfioc_table"
 462 Delete one or more addresses from a table.
 463 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 464 contains the list of pfr_addr structures to delete.
 465 On exit, pfrio_ndel contains the number of addresses effectively deleted.
 466 .It Dv DIOCRSETADDRS Fa "struct pfioc_table"
 467 Replace the content of a table by a new address list.
 468 This is the most complicated command, which uses all the structure members.
 469 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 470 contains the new list of pfr_addr structures.
 471 In addition to that, if size2 is nonzero, pfrio_buffer[pfrio_size..pfrio_size2]
 472 must be a writeable buffer, into which the kernel can copy the addresses that
 473 have been deleted during the replace operation.
 474 On exit, pfrio_ndel, pfrio_nadd and pfrio_nchange contain the number of
 475 addresses deleted, added and changed by the kernel.
 476 If pfrio_size2 was set on
 477 entry, pfrio_size2 will point to the size of the buffer used, exactly like
 478 .Dv DIOCRGETADDRS .
 479 .It Dv DIOCRGETADDRS Fa "struct pfioc_table"
 480 Get all the addresses of a table.
 481 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 482 contains a valid writeable buffer for pfr_addr structures.
 483 On exit, pfrio_size contains the number of addresses written into the buffer.
 484 If the buffer was too small, the kernel does not store anything but just
 485 return the required buffer size, without returning an error.
 486 .It Dv DIOCRGETASTATS Fa "struct pfioc_table"
 487 Like
 488 .Dv DIOCRGETADDRS ,
 489 but returns an array of pfr_astats structures.
 490 .Bd -literal
 491 struct pfr_astats {
 492         struct pfr_addr  pfras_a;
 493         u_int64_t        pfras_packets
 494                              [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
 495         u_int64_t        pfras_bytes
 496                              [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
 497         long             pfras_tzero;
 498 };
 499 .Ed
 500 .It Dv DIOCRCLRASTATS Fa "struct pfioc_table"
 501 Clears the statistics of one or more addresses.
 502 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 503 contains a table of pfr_addr structures to clear.
 504 On exit, pfrio_nzero contains the number of addresses effectively cleared.
 505 .It Dv DIOCRTSTADDRS Fa "struct pfioc_table"
 506 Test if the given addresses match a table.
 507 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 508 contains a table of pfr_addr structures to test.
 509 On exit, the kernel updates the pfr_addr table by setting the pfra_fback
 510 member appropriately.
 511 .It Dv DIOCRSETTFLAGS Fa "struct pfioc_table"
 512 Change the
 513 .Va const
 514 or
 515 .Va persist
 516 flag of a table.
 517 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures,
 518 and pfrio_setflag contains the flags to add, while pfrio_clrflag contains the
 519 flags to remove.
 520 On exit, pfrio_nchange and pfrio_ndel contain the number of tables altered
 521 or deleted by the kernel.
 522 Yes, tables can be deleted if one removes the
 523 .Va persist
 524 flag of an unreferenced table.
 525 .It Dv DIOCRINADEFINE Fa "struct pfioc_table"
 526 Defines a table in the inactive set.
 527 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
 528 contains the list of pfr_addr structures to put in the table.
 529 A valid ticket must also be supplied to pfrio_ticket.
 530 On exit, pfrio_nadd contains 0 if the table was already defined in the
 531 inactive list, or 1 if a new table has been created.
 532 pfrio_naddr contains the number of addresses effectively put in the table.
 533 .It Dv DIOCXBEGIN Fa "struct pfioc_trans"
 534 .Bd -literal
 535 #define PF_RULESET_ALTQ         (PF_RULESET_MAX)
 536 #define PF_RULESET_TABLE        (PF_RULESET_MAX+1)
 537 struct pfioc_trans {
 538         int              size;  /* number of elements */
 539         int              esize; /* size of each element in bytes */
 540         struct pfioc_trans_e {
 541                 int             rs_num;
 542                 char            anchor[PF_ANCHOR_NAME_SIZE];
 543                 char            ruleset[PF_RULESET_NAME_SIZE];
 544                 u_int32_t       ticket;
 545         }               *array;
 546 };
 547 .Ed
 548 .Pp
 549 Clears all the inactive rulesets specified in the
 550 .Fa "struct pfioc_trans_e"
 551 array.
 552 For each ruleset, a ticket is returned for subsequent "add rule" IOCTLs,
 553 as well as for the
 554 .Dv DIOCXCOMMIT
 555 and
 556 .Dv DIOCXROLLBACK
 557 calls.
 558 .It Dv DIOCXCOMMIT Fa "struct pfioc_trans"
 559 Atomically switch a vector of inactive rulesets to the active rulesets.
 560 Implemented as a standard 2-phase commit, which will either fail for all
 561 rulesets or completely succeed.
 562 All tickets need to be valid.
 563 Returns
 564 .Er EBUSY
 565 if a concurrent process is trying to update some of the same rulesets
 566 concurrently.
 567 .It Dv DIOCXROLLBACK Fa "struct pfioc_trans"
 568 Clean up the kernel by undoing all changes that have taken place on the
 569 inactive rulesets since the last
 570 .Dv DIOCXBEGIN .
 571 .Dv DIOCXROLLBACK
 572 will silently ignore rulesets for which the ticket is invalid.
 573 .It Dv DIOCFPFLUSH
 574 Flush the passive OS fingerprint table.
 575 .It Dv DIOCFPADD Fa "struct pf_osfp_ioctl"
 576 .Bd -literal
 577 struct pf_osfp_ioctl {
 578         struct pf_osfp_entry {
 579                 SLIST_ENTRY(pf_osfp_entry) fp_entry;
 580                 pf_osfp_t               fp_os;
 581                 char                    fp_class_nm[PF_OSFP_LEN];
 582                 char                    fp_version_nm[PF_OSFP_LEN];
 583                 char                    fp_subtype_nm[PF_OSFP_LEN];
 584         }                       fp_os;
 585         u_int16_t               fp_mss;
 586         u_int16_t               fp_wsize;
 587         u_int16_t               fp_psize;
 588         u_int8_t                fp_ttl;
 589         u_int8_t                fp_wscale;
 590         u_int8_t                fp_flags;
 591         int                     fp_getnum;
 592 };
 593 .Ed
 594 .Pp
 595 Add a passive OS fingerprint to the table.
 596 Set
 597 .Va fp_os.fp_os
 598 to the packed fingerprint,
 599 .Va fp_os.fp_class_nm
 600 to the name of the class (Linux, Windows, etc),
 601 .Va fp_os.fp_version_nm
 602 to the name of the version (NT, 95, 98), and
 603 .Va fp_os.fp_subtype_nm
 604 to the name of the subtype or patchlevel.
 605 The members
 606 .Va fp_mss ,
 607 .Va fp_wsize ,
 608 .Va fp_psize ,
 609 .Va fp_ttl ,
 610 and
 611 .Va fp_wscale
 612 are set to the TCP MSS, the TCP window size, the IP length and the IP TTL of
 613 the TCP SYN packet respectively.
 614 The
 615 .Va fp_flags
 616 member is filled according to the
 617 .In net/pf/pfvar.h
 618 include file PF_OSFP_* defines.
 619 The
 620 .Va fp_getnum
 621 is not used with this ioctl.
 622 .Pp
 623 The structure's slack space must be zeroed for correct operation; memset
 624 the whole structure to zero before filling and sending to the kernel.
 625 .It Dv DIOCFPGET Fa "struct pf_osfp_ioctl"
 626 .Bd -literal
 627 struct pf_osfp_ioctl {
 628         struct pf_osfp_entry {
 629                 SLIST_ENTRY(pf_osfp_entry) fp_entry;
 630                 pf_osfp_t               fp_os;
 631                 char                    fp_class_nm[PF_OSFP_LEN];
 632                 char                    fp_version_nm[PF_OSFP_LEN];
 633                 char                    fp_subtype_nm[PF_OSFP_LEN];
 634         }                       fp_os;
 635         u_int16_t               fp_mss;
 636         u_int16_t               fp_wsize;
 637         u_int16_t               fp_psize;
 638         u_int8_t                fp_ttl;
 639         u_int8_t                fp_wscale;
 640         u_int8_t                fp_flags;
 641         int                     fp_getnum;
 642 };
 643 .Ed
 644 .Pp
 645 Get the passive OS fingerprint number
 646 .Va fp_getnum
 647 from the kernel's fingerprint list.
 648 The rest of the structure members will come back filled.
 649 Get the whole list by repeatedly incrementing the
 650 .Va fp_getnum
 651 number until the ioctl returns
 652 .Er 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
 840 and was imported into
 841 .Dx 1.1
 842 by Devon H. O'Dell and Simon Schubert.