contrib/pf/man/pf.4

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