share/man/man4/pf.4

   1 .\"     $OpenBSD: pf.4,v 1.62 2008/09/10 14:57:37 jmc 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 November 14, 2013
  32 .Dt PF 4
  33 .Os
  34 .Sh NAME
  35 .Nm pf
  36 .Nd packet filter
  37 .Sh SYNOPSIS
  38 .Cd "device pf"
  39 .Cd "options PF_DEFAULT_TO_DROP"
  40 .Sh DESCRIPTION
  41 Packet filtering takes place in the kernel.
  42 A pseudo-device,
  43 .Pa /dev/pf ,
  44 allows userland processes to control the
  45 behavior of the packet filter through an
  46 .Xr ioctl 2
  47 interface.
  48 There are commands to enable and disable the filter, load rulesets,
  49 add and remove individual rules or state table entries,
  50 and retrieve statistics.
  51 The most commonly used functions are covered by
  52 .Xr pfctl 8 .
  53 .Pp
  54 Manipulations like loading a ruleset that involve more than a single
  55 .Xr ioctl 2
  56 call require a so-called
  57 .Em ticket ,
  58 which prevents the occurrence of
  59 multiple concurrent manipulations.
  60 .Pp
  61 Fields of
  62 .Xr ioctl 2
  63 parameter structures that refer to packet data (like
  64 addresses and ports) are generally expected in network byte-order.
  65 .Pp
  66 Rules and address tables are contained in so-called
  67 .Em anchors .
  68 When servicing an
  69 .Xr ioctl 2
  70 request, if the anchor field of the argument structure is empty,
  71 the kernel will use the default anchor (i.e., the main ruleset)
  72 in operations.
  73 Anchors are specified by name and may be nested, with components
  74 separated by
  75 .Sq /
  76 characters, similar to how file system hierarchies are laid out.
  77 The final component of the anchor path is the anchor under which
  78 operations will be performed.
  79 .Sh SYSCTL VARIABLES AND LOADER TUNABLES
  80 The following
  81 .Xr loader 8
  82 tunables are available.
  83 .Bl -tag -width indent
  84 .It Va net.pf.states_hashsize
  85 Size of hash tables that store states.
  86 Should be power of 2.
  87 Default value is 32768.
  88 .It Va net.pf.source_nodes_hashsize
  89 Size of hash table that store source nodes.
  90 Should be power of 2.
  91 Default value is 8192.
  92 .El
  93 .Pp
  94 Read only
  95 .Xr sysctl 8
  96 variables with matching names are provided to obtain current values
  97 at runtime.
  98 .Sh KERNEL OPTIONS
  99 The following options in the kernel configuration file are related to
 100 .Nm
 101 operation:
 102 .Pp
 103 .Bl -tag -width ".Dv PF_DEFAULT_TO_DROP" -compact
 104 .It Dv PF_DEFAULT_TO_DROP
 105 Change default policy to drop by default
 106 .El
 107 .Sh IOCTL INTERFACE
 108 .Nm
 109 supports the following
 110 .Xr ioctl 2
 111 commands, available through
 112 .Aq Pa net/pfvar.h :
 113 .Bl -tag -width xxxxxx
 114 .It Dv DIOCSTART
 115 Start the packet filter.
 116 .It Dv DIOCSTOP
 117 Stop the packet filter.
 118 .It Dv DIOCSTARTALTQ
 119 Start the ALTQ bandwidth control system (see
 120 .Xr altq 9 ) .
 121 .It Dv DIOCSTOPALTQ
 122 Stop the ALTQ bandwidth control system.
 123 .It Dv DIOCBEGINADDRS Fa "struct pfioc_pooladdr *pp"
 124 .Bd -literal
 125 struct pfioc_pooladdr {
 126         u_int32_t               action;
 127         u_int32_t               ticket;
 128         u_int32_t               nr;
 129         u_int32_t               r_num;
 130         u_int8_t                r_action;
 131         u_int8_t                r_last;
 132         u_int8_t                af;
 133         char                    anchor[MAXPATHLEN];
 134         struct pf_pooladdr      addr;
 135 };
 136 .Ed
 137 .Pp
 138 Clear the buffer address pool and get a
 139 .Va ticket
 140 for subsequent
 141 .Dv DIOCADDADDR ,
 142 and
 143 .Dv DIOCADDRULE
 144 calls.
 145 .It Dv DIOCADDADDR Fa "struct pfioc_pooladdr *pp"
 146 .Pp
 147 Add the pool address
 148 .Va addr
 149 to the buffer address pool to be used in the following
 150 .Dv DIOCADDRULE
 151 call.
 152 All other members of the structure are ignored.
 153 .It Dv DIOCADDRULE Fa "struct pfioc_rule *pr"
 154 .Bd -literal
 155 struct pfioc_rule {
 156         u_int32_t       action;
 157         u_int32_t       ticket;
 158         u_int32_t       pool_ticket;
 159         u_int32_t       nr;
 160         char            anchor[MAXPATHLEN];
 161         char            anchor_call[MAXPATHLEN];
 162         struct pf_rule  rule;
 163 };
 164 .Ed
 165 .Pp
 166 Add
 167 .Va rule
 168 at the end of the inactive ruleset.
 169 This call requires a
 170 .Va ticket
 171 obtained through a preceding
 172 .Dv DIOCXBEGIN
 173 call and a
 174 .Va pool_ticket
 175 obtained through a
 176 .Dv DIOCBEGINADDRS
 177 call.
 178 .Dv DIOCADDADDR
 179 must also be called if any pool addresses are required.
 180 The optional
 181 .Va anchor
 182 name indicates the anchor in which to append the rule.
 183 .Va nr
 184 and
 185 .Va action
 186 are ignored.
 187 .It Dv DIOCADDALTQ Fa "struct pfioc_altq *pa"
 188 Add an ALTQ discipline or queue.
 189 .Bd -literal
 190 struct pfioc_altq {
 191         u_int32_t       action;
 192         u_int32_t       ticket;
 193         u_int32_t       nr;
 194         struct pf_altq  altq;
 195 };
 196 .Ed
 197 .It Dv DIOCGETRULES Fa "struct pfioc_rule *pr"
 198 Get a
 199 .Va ticket
 200 for subsequent
 201 .Dv DIOCGETRULE
 202 calls and the number
 203 .Va nr
 204 of rules in the active ruleset.
 205 .It Dv DIOCGETRULE Fa "struct pfioc_rule *pr"
 206 Get a
 207 .Va rule
 208 by its number
 209 .Va nr
 210 using the
 211 .Va ticket
 212 obtained through a preceding
 213 .Dv DIOCGETRULES
 214 call.
 215 If
 216 .Va action
 217 is set to
 218 .Dv PF_GET_CLR_CNTR ,
 219 the per-rule statistics on the requested rule are cleared.
 220 .It Dv DIOCGETADDRS Fa "struct pfioc_pooladdr *pp"
 221 Get a
 222 .Va ticket
 223 for subsequent
 224 .Dv DIOCGETADDR
 225 calls and the number
 226 .Va nr
 227 of pool addresses in the rule specified with
 228 .Va r_action ,
 229 .Va r_num ,
 230 and
 231 .Va anchor .
 232 .It Dv DIOCGETADDR Fa "struct pfioc_pooladdr *pp"
 233 Get the pool address
 234 .Va addr
 235 by its number
 236 .Va nr
 237 from the rule specified with
 238 .Va r_action ,
 239 .Va r_num ,
 240 and
 241 .Va anchor
 242 using the
 243 .Va ticket
 244 obtained through a preceding
 245 .Dv DIOCGETADDRS
 246 call.
 247 .It Dv DIOCGETALTQS Fa "struct pfioc_altq *pa"
 248 Get a
 249 .Va ticket
 250 for subsequent
 251 .Dv DIOCGETALTQ
 252 calls and the number
 253 .Va nr
 254 of queues in the active list.
 255 .It Dv DIOCGETALTQ Fa "struct pfioc_altq *pa"
 256 Get the queueing discipline
 257 .Va altq
 258 by its number
 259 .Va nr
 260 using the
 261 .Va ticket
 262 obtained through a preceding
 263 .Dv DIOCGETALTQS
 264 call.
 265 .It Dv DIOCGETQSTATS Fa "struct pfioc_qstats *pq"
 266 Get the statistics on a queue.
 267 .Bd -literal
 268 struct pfioc_qstats {
 269         u_int32_t        ticket;
 270         u_int32_t        nr;
 271         void            *buf;
 272         int              nbytes;
 273         u_int8_t         scheduler;
 274 };
 275 .Ed
 276 .Pp
 277 This call fills in a pointer to the buffer of statistics
 278 .Va buf ,
 279 of length
 280 .Va nbytes ,
 281 for the queue specified by
 282 .Va nr .
 283 .It Dv DIOCGETRULESETS Fa "struct pfioc_ruleset *pr"
 284 .Bd -literal
 285 struct pfioc_ruleset {
 286         u_int32_t        nr;
 287         char             path[MAXPATHLEN];
 288         char             name[PF_ANCHOR_NAME_SIZE];
 289 };
 290 .Ed
 291 .Pp
 292 Get the number
 293 .Va nr
 294 of rulesets (i.e., anchors) directly attached to the anchor named by
 295 .Va path
 296 for use in subsequent
 297 .Dv DIOCGETRULESET
 298 calls.
 299 Nested anchors, since they are not directly attached to the given
 300 anchor, will not be included.
 301 This ioctl returns
 302 .Er EINVAL
 303 if the given anchor does not exist.
 304 .It Dv DIOCGETRULESET Fa "struct pfioc_ruleset *pr"
 305 Get a ruleset (i.e., an anchor)
 306 .Va name
 307 by its number
 308 .Va nr
 309 from the given anchor
 310 .Va path ,
 311 the maximum number of which can be obtained from a preceding
 312 .Dv DIOCGETRULESETS
 313 call.
 314 This ioctl returns
 315 .Er EINVAL
 316 if the given anchor does not exist or
 317 .Er EBUSY
 318 if another process is concurrently updating a ruleset.
 319 .It Dv DIOCKILLSTATES Fa "struct pfioc_state_kill *psk"
 320 Remove matching entries from the state table.
 321 This ioctl returns the number of killed states in
 322 .Va psk_killed .
 323 .Bd -literal
 324 struct pfioc_state_kill {
 325         struct pf_state_cmp     psk_pfcmp;
 326         sa_family_t             psk_af;
 327         int                     psk_proto;
 328         struct pf_rule_addr     psk_src;
 329         struct pf_rule_addr     psk_dst;
 330         char                    psk_ifname[IFNAMSIZ];
 331         char                    psk_label[PF_RULE_LABEL_SIZE];
 332         u_int                   psk_killed;
 333 };
 334 .Ed
 335 .It Dv DIOCCLRSTATES Fa "struct pfioc_state_kill *psk"
 336 Clear all states.
 337 It works like
 338 .Dv DIOCKILLSTATES ,
 339 but ignores the
 340 .Va psk_af ,
 341 .Va psk_proto ,
 342 .Va psk_src ,
 343 and
 344 .Va psk_dst
 345 fields of the
 346 .Vt pfioc_state_kill
 347 structure.
 348 .It Dv DIOCSETSTATUSIF Fa "struct pfioc_if *pi"
 349 Specify the interface for which statistics are accumulated.
 350 .Bd -literal
 351 struct pfioc_if {
 352         char             ifname[IFNAMSIZ];
 353 };
 354 .Ed
 355 .It Dv DIOCGETSTATUS Fa "struct pf_status *s"
 356 Get the internal packet filter statistics.
 357 .Bd -literal
 358 struct pf_status {
 359         u_int64_t       counters[PFRES_MAX];
 360         u_int64_t       lcounters[LCNT_MAX];
 361         u_int64_t       fcounters[FCNT_MAX];
 362         u_int64_t       scounters[SCNT_MAX];
 363         u_int64_t       pcounters[2][2][3];
 364         u_int64_t       bcounters[2][2];
 365         u_int32_t       running;
 366         u_int32_t       states;
 367         u_int32_t       src_nodes;
 368         u_int32_t       since;
 369         u_int32_t       debug;
 370         u_int32_t       hostid;
 371         char            ifname[IFNAMSIZ];
 372         u_int8_t        pf_chksum[MD5_DIGEST_LENGTH];
 373 };
 374 .Ed
 375 .It Dv DIOCCLRSTATUS
 376 Clear the internal packet filter statistics.
 377 .It Dv DIOCNATLOOK Fa "struct pfioc_natlook *pnl"
 378 Look up a state table entry by source and destination addresses and ports.
 379 .Bd -literal
 380 struct pfioc_natlook {
 381         struct pf_addr   saddr;
 382         struct pf_addr   daddr;
 383         struct pf_addr   rsaddr;
 384         struct pf_addr   rdaddr;
 385         u_int16_t        sport;
 386         u_int16_t        dport;
 387         u_int16_t        rsport;
 388         u_int16_t        rdport;
 389         sa_family_t      af;
 390         u_int8_t         proto;
 391         u_int8_t         direction;
 392 };
 393 .Ed
 394 .It Dv DIOCSETDEBUG Fa "u_int32_t *level"
 395 Set the debug level.
 396 .Bd -literal
 397 enum    { PF_DEBUG_NONE, PF_DEBUG_URGENT, PF_DEBUG_MISC,
 398           PF_DEBUG_NOISY };
 399 .Ed
 400 .It Dv DIOCGETSTATES Fa "struct pfioc_states *ps"
 401 Get state table entries.
 402 .Bd -literal
 403 struct pfioc_states {
 404         int     ps_len;
 405         union {
 406                 caddr_t          psu_buf;
 407                 struct pf_state *psu_states;
 408         } ps_u;
 409 #define ps_buf          ps_u.psu_buf
 410 #define ps_states       ps_u.psu_states
 411 };
 412 .Ed
 413 .Pp
 414 If
 415 .Va ps_len
 416 is non-zero on entry, as many states as possible that can fit into this
 417 size will be copied into the supplied buffer
 418 .Va ps_states .
 419 On exit,
 420 .Va ps_len
 421 is always set to the total size required to hold all state table entries
 422 (i.e., it is set to
 423 .Li sizeof(struct pf_state) * nr ) .
 424 .Pp
 425 The type of operation to be performed is indicated by
 426 .Va action ,
 427 which can be any of the following:
 428 .Bd -literal
 429 enum    { PF_CHANGE_NONE, PF_CHANGE_ADD_HEAD, PF_CHANGE_ADD_TAIL,
 430           PF_CHANGE_ADD_BEFORE, PF_CHANGE_ADD_AFTER,
 431           PF_CHANGE_REMOVE, PF_CHANGE_GET_TICKET };
 432 .Ed
 433 .Pp
 434 .Va ticket
 435 must be set to the value obtained with
 436 .Dv PF_CHANGE_GET_TICKET
 437 for all actions except
 438 .Dv PF_CHANGE_GET_TICKET .
 439 .Va pool_ticket
 440 must be set to the value obtained with the
 441 .Dv DIOCBEGINADDRS
 442 call for all actions except
 443 .Dv PF_CHANGE_REMOVE
 444 and
 445 .Dv PF_CHANGE_GET_TICKET .
 446 .Va anchor
 447 indicates to which anchor the operation applies.
 448 .Va nr
 449 indicates the rule number against which
 450 .Dv PF_CHANGE_ADD_BEFORE ,
 451 .Dv PF_CHANGE_ADD_AFTER ,
 452 or
 453 .Dv PF_CHANGE_REMOVE
 454 actions are applied.
 455 .It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm *pt"
 456 .Bd -literal
 457 struct pfioc_tm {
 458         int              timeout;
 459         int              seconds;
 460 };
 461 .Ed
 462 .Pp
 463 Set the state timeout of
 464 .Va timeout
 465 to
 466 .Va seconds .
 467 The old value will be placed into
 468 .Va seconds .
 469 For possible values of
 470 .Va timeout ,
 471 consult the
 472 .Dv PFTM_*
 473 values in
 474 .Aq Pa net/pfvar.h .
 475 .It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm *pt"
 476 Get the state timeout of
 477 .Va timeout .
 478 The value will be placed into the
 479 .Va seconds
 480 field.
 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_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 settable 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 .It Dv DIOCKILLSRCNODES Fa "struct pfioc_iface *io"
1059 Explicitly remove source tracking nodes.
1060 .El
1061 .Sh FILES
1062 .Bl -tag -width /dev/pf -compact
1063 .It Pa /dev/pf
1064 packet filtering device.
1065 .El
1066 .Sh EXAMPLES
1067 The following example demonstrates how to use the
1068 .Dv DIOCNATLOOK
1069 command to find the internal host/port of a NATed connection:
1070 .Bd -literal
1071 #include <sys/types.h>
1072 #include <sys/socket.h>
1073 #include <sys/ioctl.h>
1074 #include <sys/fcntl.h>
1075 #include <net/if.h>
1076 #include <netinet/in.h>
1077 #include <net/pfvar.h>
1078 #include <err.h>
1079 #include <stdio.h>
1080 #include <stdlib.h>
1081
1082 u_int32_t
1083 read_address(const char *s)
1084 {
1085         int a, b, c, d;
1086
1087         sscanf(s, "%i.%i.%i.%i", &a, &b, &c, &d);
1088         return htonl(a << 24 | b << 16 | c << 8 | d);
1089 }
1090
1091 void
1092 print_address(u_int32_t a)
1093 {
1094         a = ntohl(a);
1095         printf("%d.%d.%d.%d", a >> 24 & 255, a >> 16 & 255,
1096             a >> 8 & 255, a & 255);
1097 }
1098
1099 int
1100 main(int argc, char *argv[])
1101 {
1102         struct pfioc_natlook nl;
1103         int dev;
1104
1105         if (argc != 5) {
1106                 printf("%s <gwy addr> <gwy port> <ext addr> <ext port>\\n",
1107                     argv[0]);
1108                 return 1;
1109         }
1110
1111         dev = open("/dev/pf", O_RDWR);
1112         if (dev == -1)
1113                 err(1, "open(\\"/dev/pf\\") failed");
1114
1115         memset(&nl, 0, sizeof(struct pfioc_natlook));
1116         nl.saddr.v4.s_addr      = read_address(argv[1]);
1117         nl.sport                = htons(atoi(argv[2]));
1118         nl.daddr.v4.s_addr      = read_address(argv[3]);
1119         nl.dport                = htons(atoi(argv[4]));
1120         nl.af                   = AF_INET;
1121         nl.proto                = IPPROTO_TCP;
1122         nl.direction            = PF_IN;
1123
1124         if (ioctl(dev, DIOCNATLOOK, &nl))
1125                 err(1, "DIOCNATLOOK");
1126
1127         printf("internal host ");
1128         print_address(nl.rsaddr.v4.s_addr);
1129         printf(":%u\\n", ntohs(nl.rsport));
1130         return 0;
1131 }
1132 .Ed
1133 .Sh SEE ALSO
1134 .Xr ioctl 2 ,
1135 .Xr altq 4 ,
1136 .Xr if_bridge 4 ,
1137 .Xr pflog 4 ,
1138 .Xr pfsync 4 ,
1139 .Xr pfctl 8 ,
1140 .Xr altq 9
1141 .Sh HISTORY
1142 The
1143 .Nm
1144 packet filtering mechanism first appeared in
1145 .Ox 3.0
1146 and then
1147 .Fx 5.2 .
1148 .Pp
1149 This implementation is derived from
1150 .Ox 4.5 .
1151 It has been heavily modified to be capable of running in multithreaded
1152 .Fx
1153 kernel and scale its performance on multiple CPUs.