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