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