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