1.\" $OpenBSD: pf.4,v 1.90 2018/12/21 11:16:04 kn 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: December 21 2018 $ 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 time_t since; 273 u_int32_t running; 274 u_int32_t states; 275 u_int32_t states_halfopen; 276 u_int32_t src_nodes; 277 u_int32_t debug; 278 u_int32_t hostid; 279 u_int32_t reass; /* reassembly */ 280 char ifname[IFNAMSIZ]; 281 u_int8_t pf_chksum[PF_MD5_DIGEST_LENGTH]; 282}; 283.Ed 284.It Dv DIOCCLRSTATUS 285Clear the internal packet filter statistics. 286.It Dv DIOCNATLOOK Fa "struct pfioc_natlook *pnl" 287Look up a state table entry by source and destination addresses and ports. 288.Bd -literal 289struct pfioc_natlook { 290 struct pf_addr saddr; 291 struct pf_addr daddr; 292 struct pf_addr rsaddr; 293 struct pf_addr rdaddr; 294 u_int16_t rdomain; 295 u_int16_t rrdomain; 296 u_int16_t sport; 297 u_int16_t dport; 298 u_int16_t rsport; 299 u_int16_t rdport; 300 sa_family_t af; 301 u_int8_t proto; 302 u_int8_t direction; 303}; 304.Ed 305.Pp 306This was primarily used to support transparent proxies with rdr-to rules. 307New proxies should use divert-to rules instead. 308These do not require access to the privileged 309.Pa /dev/pf 310device and preserve the original destination address for 311.Xr getsockname 2 . 312For 313.Dv SOCK_DGRAM 314sockets, the 315.Xr ip 4 316socket options 317.Dv IP_RECVDSTADDR 318and 319.Dv IP_RECVDSTPORT 320can be used to retrieve the destination address and port. 321.It Dv DIOCSETDEBUG Fa "u_int32_t *level" 322Set the debug level. 323See the 324.Xr syslog 3 325man page for a list of valid debug levels. 326.It Dv DIOCGETSTATES Fa "struct pfioc_states *ps" 327Get state table entries. 328.Bd -literal 329struct pfioc_states { 330 int ps_len; 331 union { 332 caddr_t psu_buf; 333 struct pfsync_state *psu_states; 334 } ps_u; 335#define ps_buf ps_u.psu_buf 336#define ps_states ps_u.psu_states 337}; 338.Ed 339.Pp 340If 341.Va ps_len 342is non-zero on entry, as many states as possible that can fit into this 343size will be copied into the supplied buffer 344.Va ps_states . 345On exit, 346.Va ps_len 347is always set to the total size required to hold all state table entries 348(i.e., it is set to 349.Li sizeof(struct pfsync_state) * nr ) . 350.It Dv DIOCCHANGERULE Fa "struct pfioc_rule *pcr" 351Add or remove the 352.Va rule 353in the ruleset specified by 354.Va rule.action . 355.Pp 356The type of operation to be performed is indicated by 357.Va action , 358which can be any of the following: 359.Bd -literal 360enum { PF_CHANGE_NONE, PF_CHANGE_ADD_HEAD, PF_CHANGE_ADD_TAIL, 361 PF_CHANGE_ADD_BEFORE, PF_CHANGE_ADD_AFTER, 362 PF_CHANGE_REMOVE, PF_CHANGE_GET_TICKET }; 363.Ed 364.Pp 365.Va ticket 366must be set to the value obtained with 367.Dv PF_CHANGE_GET_TICKET 368for all actions except 369.Dv PF_CHANGE_GET_TICKET . 370.Va anchor 371indicates to which anchor the operation applies. 372.Va nr 373indicates the rule number against which 374.Dv PF_CHANGE_ADD_BEFORE , 375.Dv PF_CHANGE_ADD_AFTER , 376or 377.Dv PF_CHANGE_REMOVE 378actions are applied. 379.It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm *pt" 380.Bd -literal 381struct pfioc_tm { 382 int timeout; 383 int seconds; 384}; 385.Ed 386.Pp 387Set the state timeout of 388.Va timeout 389to 390.Va seconds . 391The old value will be placed into 392.Va seconds . 393For possible values of 394.Va timeout , 395consult the 396.Dv PFTM_* 397values in 398.In net/pfvar.h . 399.It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm *pt" 400Get the state timeout of 401.Va timeout . 402The value will be placed into the 403.Va seconds 404field. 405.It Dv DIOCSETLIMIT Fa "struct pfioc_limit *pl" 406Set the hard limits on the memory pools used by the packet filter. 407.Bd -literal 408struct pfioc_limit { 409 int index; 410 unsigned limit; 411}; 412 413enum { PF_LIMIT_STATES, PF_LIMIT_SRC_NODES, PF_LIMIT_FRAGS, 414 PF_LIMIT_TABLES, PF_LIMIT_TABLE_ENTRIES, PF_LIMIT_MAX }; 415.Ed 416.It Dv DIOCGETLIMIT Fa "struct pfioc_limit *pl" 417Get the hard 418.Va limit 419for the memory pool indicated by 420.Va index . 421.It Dv DIOCRCLRTABLES Fa "struct pfioc_table *io" 422Clear all tables. 423All the ioctls that manipulate radix tables 424use the same structure described below. 425For 426.Dv DIOCRCLRTABLES , 427.Va pfrio_ndel 428contains on exit the number of tables deleted. 429.Bd -literal 430struct pfioc_table { 431 struct pfr_table pfrio_table; 432 void *pfrio_buffer; 433 int pfrio_esize; 434 int pfrio_size; 435 int pfrio_size2; 436 int pfrio_nadd; 437 int pfrio_ndel; 438 int pfrio_nchange; 439 int pfrio_flags; 440 u_int32_t pfrio_ticket; 441}; 442#define pfrio_exists pfrio_nadd 443#define pfrio_nzero pfrio_nadd 444#define pfrio_nmatch pfrio_nadd 445#define pfrio_naddr pfrio_size2 446#define pfrio_setflag pfrio_size2 447#define pfrio_clrflag pfrio_nadd 448.Ed 449.It Dv DIOCRADDTABLES Fa "struct pfioc_table *io" 450Create one or more tables. 451On entry, 452.Va pfrio_buffer 453must point to an array of 454.Vt struct pfr_table 455containing at least 456.Vt pfrio_size 457elements. 458.Vt pfrio_esize 459must be the size of 460.Vt struct pfr_table . 461On exit, 462.Va pfrio_nadd 463contains the number of tables effectively created. 464.Bd -literal 465struct pfr_table { 466 char pfrt_anchor[PATH_MAX]; 467 char pfrt_name[PF_TABLE_NAME_SIZE]; 468 u_int32_t pfrt_flags; 469 u_int8_t pfrt_fback; 470}; 471.Ed 472.It Dv DIOCRDELTABLES Fa "struct pfioc_table *io" 473Delete one or more tables. 474On entry, 475.Va pfrio_buffer 476must point to an array of 477.Vt struct pfr_table 478containing at least 479.Vt pfrio_size 480elements. 481.Vt pfrio_esize 482must be the size of 483.Vt struct pfr_table . 484On exit, 485.Va pfrio_ndel 486contains the number of tables effectively deleted. 487.It Dv DIOCRGETTABLES Fa "struct pfioc_table *io" 488Get the list of all tables. 489On entry, 490.Va pfrio_buffer[pfrio_size] 491contains a valid writeable buffer for 492.Vt pfr_table 493structures. 494On exit, 495.Va pfrio_size 496contains the number of tables written into the buffer. 497If the buffer is too small, the kernel does not store anything but just 498returns the required buffer size, without error. 499.It Dv DIOCRGETTSTATS Fa "struct pfioc_table *io" 500This call is like 501.Dv DIOCRGETTABLES 502but is used to get an array of 503.Vt pfr_tstats 504structures. 505.Bd -literal 506struct pfr_tstats { 507 struct pfr_table pfrts_t; 508 u_int64_t pfrts_packets 509 [PFR_DIR_MAX][PFR_OP_TABLE_MAX]; 510 u_int64_t pfrts_bytes 511 [PFR_DIR_MAX][PFR_OP_TABLE_MAX]; 512 u_int64_t pfrts_match; 513 u_int64_t pfrts_nomatch; 514 time_t pfrts_tzero; 515 int pfrts_cnt; 516 int pfrts_refcnt[PFR_REFCNT_MAX]; 517}; 518#define pfrts_name pfrts_t.pfrt_name 519#define pfrts_flags pfrts_t.pfrt_flags 520.Ed 521.It Dv DIOCRCLRTSTATS Fa "struct pfioc_table *io" 522Clear the statistics of one or more tables. 523On entry, 524.Va pfrio_buffer 525must point to an array of 526.Vt struct pfr_table 527containing at least 528.Vt pfrio_size 529elements. 530.Vt pfrio_esize 531must be the size of 532.Vt struct pfr_table . 533On exit, 534.Va pfrio_nzero 535contains the number of tables effectively cleared. 536.It Dv DIOCRCLRADDRS Fa "struct pfioc_table *io" 537Clear all addresses in a table. 538On entry, 539.Va pfrio_table 540contains the table to clear. 541On exit, 542.Va pfrio_ndel 543contains the number of addresses removed. 544.It Dv DIOCRADDADDRS Fa "struct pfioc_table *io" 545Add one or more addresses to a table. 546On entry, 547.Va pfrio_table 548contains the table ID and 549.Va pfrio_buffer 550must point to an array of 551.Vt struct pfr_addr 552containing at least 553.Vt pfrio_size 554elements to add to the table. 555.Vt pfrio_esize 556must be the size of 557.Vt struct pfr_addr . 558On exit, 559.Va pfrio_nadd 560contains the number of addresses effectively added. 561.Bd -literal 562struct pfr_addr { 563 union { 564 struct in_addr _pfra_ip4addr; 565 struct in6_addr _pfra_ip6addr; 566 } pfra_u; 567 char pfra_ifname[IFNAMSIZ]; 568 u_int32_t pfra_states; 569 u_int16_t pfra_weight; 570 u_int8_t pfra_af; 571 u_int8_t pfra_net; 572 u_int8_t pfra_not; 573 u_int8_t pfra_fback; 574 u_int8_t pfra_type; 575 u_int8_t pad[7]; 576}; 577#define pfra_ip4addr pfra_u._pfra_ip4addr 578#define pfra_ip6addr pfra_u._pfra_ip6addr 579.Ed 580.It Dv DIOCRDELADDRS Fa "struct pfioc_table *io" 581Delete one or more addresses from a table. 582On entry, 583.Va pfrio_table 584contains the table ID and 585.Va pfrio_buffer 586must point to an array of 587.Vt struct pfr_addr 588containing at least 589.Vt pfrio_size 590elements to delete from the table. 591.Vt pfrio_esize 592must be the size of 593.Vt struct pfr_addr . 594On exit, 595.Va pfrio_ndel 596contains the number of addresses effectively deleted. 597.It Dv DIOCRSETADDRS Fa "struct pfioc_table *io" 598Replace the content of a table by a new address list. 599This is the most complicated command, which uses all the structure members. 600.Pp 601On entry, 602.Va pfrio_table 603contains the table ID and 604.Va pfrio_buffer 605must point to an array of 606.Vt struct pfr_addr 607containing at least 608.Vt pfrio_size 609elements which become the new contents of the table. 610.Vt pfrio_esize 611must be the size of 612.Vt struct pfr_addr . 613Additionally, if 614.Va pfrio_size2 615is non-zero, 616.Va pfrio_buffer[pfrio_size..pfrio_size2] 617must be a writeable buffer, into which the kernel can copy the 618addresses that have been deleted during the replace operation. 619On exit, 620.Va pfrio_ndel , 621.Va pfrio_nadd , 622and 623.Va pfrio_nchange 624contain the number of addresses deleted, added, and changed by the 625kernel. 626If 627.Va pfrio_size2 628was set on entry, 629.Va pfrio_size2 630will point to the size of the buffer used, exactly like 631.Dv DIOCRGETADDRS . 632.It Dv DIOCRGETADDRS Fa "struct pfioc_table *io" 633Get all the addresses of a table. 634On entry, 635.Va pfrio_table 636contains the table ID and 637.Va pfrio_buffer[pfrio_size] 638contains a valid writeable buffer for 639.Vt pfr_addr 640structures. 641On exit, 642.Va pfrio_size 643contains the number of addresses written into the buffer. 644If the buffer was too small, the kernel does not store anything but just 645returns the required buffer size, without returning an error. 646.It Dv DIOCRGETASTATS Fa "struct pfioc_table *io" 647This call is like 648.Dv DIOCRGETADDRS 649but is used to get an array of 650.Vt pfr_astats 651structures. 652.Bd -literal 653struct pfr_astats { 654 struct pfr_addr pfras_a; 655 u_int64_t pfras_packets 656 [PFR_DIR_MAX][PFR_OP_ADDR_MAX]; 657 u_int64_t pfras_bytes 658 [PFR_DIR_MAX][PFR_OP_ADDR_MAX]; 659 time_t pfras_tzero; 660}; 661.Ed 662.It Dv DIOCRCLRASTATS Fa "struct pfioc_table *io" 663Clear the statistics of one or more addresses. 664On entry, 665.Va pfrio_table 666contains the table ID and 667.Va pfrio_buffer 668must point to an array of 669.Vt struct pfr_addr 670containing at least 671.Vt pfrio_size 672elements to be cleared from the table. 673.Vt pfrio_esize 674must be the size of 675.Vt struct pfr_addr . 676On exit, 677.Va pfrio_nzero 678contains the number of addresses effectively cleared. 679.It Dv DIOCRTSTADDRS Fa "struct pfioc_table *io" 680Test if the given addresses match a table. 681On entry, 682.Va pfrio_table 683contains the table ID and 684.Va pfrio_buffer 685must point to an array of 686.Vt struct pfr_addr 687containing at least 688.Vt pfrio_size 689elements, each of which will be tested for a match in the table. 690.Vt pfrio_esize 691must be the size of 692.Vt struct pfr_addr . 693On exit, the kernel updates the 694.Vt pfr_addr 695array by setting the 696.Va pfra_fback 697member appropriately. 698.It Dv DIOCRSETTFLAGS Fa "struct pfioc_table *io" 699Change the 700.Dv PFR_TFLAG_CONST 701or 702.Dv PFR_TFLAG_PERSIST 703flags of a table. 704On entry, 705.Va pfrio_buffer 706must point to an array of 707.Vt struct pfr_table 708containing at least 709.Vt pfrio_size 710elements. 711.Va pfrio_esize 712must be the size of 713.Vt struct pfr_table . 714.Va pfrio_setflag 715must contain the flags to add, while 716.Va pfrio_clrflag 717must contain the flags to remove. 718On exit, 719.Va pfrio_nchange 720and 721.Va pfrio_ndel 722contain the number of tables altered or deleted by the kernel. 723Yes, tables can be deleted if one removes the 724.Dv PFR_TFLAG_PERSIST 725flag of an unreferenced table. 726.It Dv DIOCRINADEFINE Fa "struct pfioc_table *io" 727Defines a table in the inactive set. 728On entry, 729.Va pfrio_table 730contains the table ID and 731.Va pfrio_buffer[pfrio_size] 732contains an array of 733.Vt pfr_addr 734structures to put in the table. 735A valid ticket must also be supplied to 736.Va pfrio_ticket . 737On exit, 738.Va pfrio_nadd 739contains 0 if the table was already defined in the inactive list 740or 1 if a new table has been created. 741.Va pfrio_naddr 742contains the number of addresses effectively put in the table. 743.It Dv DIOCXBEGIN Fa "struct pfioc_trans *io" 744.Bd -literal 745struct pfioc_trans { 746 int size; /* number of elements */ 747 int esize; /* size of each element in bytes */ 748 struct pfioc_trans_e { 749 int type; 750 char anchor[PATH_MAX]; 751 u_int32_t ticket; 752 } *array; 753}; 754.Ed 755.Pp 756Clear all the inactive rulesets specified in the 757.Vt pfioc_trans_e 758array. 759For each ruleset, a ticket is returned for subsequent "add rule" ioctls, 760as well as for the 761.Dv DIOCXCOMMIT 762and 763.Dv DIOCXROLLBACK 764calls. 765.Pp 766Ruleset types, identified by 767.Va type , 768can be one of the following: 769.Pp 770.Bl -tag -width PF_TRANS_RULESET -offset ind -compact 771.It Dv PF_TRANS_RULESET 772Filter rules. 773.It Dv PF_TRANS_TABLE 774Address tables. 775.El 776.It Dv DIOCXCOMMIT Fa "struct pfioc_trans *io" 777Atomically switch a vector of inactive rulesets to the active rulesets. 778This call is implemented as a standard two-phase commit, which will either 779fail for all rulesets or completely succeed. 780All tickets need to be valid. 781This ioctl returns 782.Er EBUSY 783if another process is concurrently updating some of the same rulesets. 784.It Dv DIOCXROLLBACK Fa "struct pfioc_trans *io" 785Clean up the kernel by undoing all changes that have taken place on the 786inactive rulesets since the last 787.Dv DIOCXBEGIN . 788.Dv DIOCXROLLBACK 789will silently ignore rulesets for which the ticket is invalid. 790.It Dv DIOCSETHOSTID Fa "u_int32_t *hostid" 791Set the host ID, which is used by 792.Xr pfsync 4 793to identify which host created state table entries. 794.It Dv DIOCOSFPFLUSH 795Flush the passive OS fingerprint table. 796.It Dv DIOCOSFPADD Fa "struct pf_osfp_ioctl *io" 797.Bd -literal 798struct pf_osfp_ioctl { 799 struct pf_osfp_entry fp_os; 800 pf_tcpopts_t fp_tcpopts; /* packed TCP options */ 801 u_int16_t fp_wsize; /* TCP window size */ 802 u_int16_t fp_psize; /* ip->ip_len */ 803 u_int16_t fp_mss; /* TCP MSS */ 804 u_int16_t fp_flags; 805 u_int8_t fp_optcnt; /* TCP option count */ 806 u_int8_t fp_wscale; /* TCP window scaling */ 807 u_int8_t fp_ttl; /* IPv4 TTL */ 808 809 int fp_getnum; /* DIOCOSFPGET number */ 810}; 811 812struct pf_osfp_entry { 813 SLIST_ENTRY(pf_osfp_entry) fp_entry; 814 pf_osfp_t fp_os; 815 int fp_enflags; 816#define PF_OSFP_EXPANDED 0x001 /* expanded entry */ 817#define PF_OSFP_GENERIC 0x002 /* generic signature */ 818#define PF_OSFP_NODETAIL 0x004 /* no p0f details */ 819#define PF_OSFP_LEN 32 820 u_char fp_class_nm[PF_OSFP_LEN]; 821 u_char fp_version_nm[PF_OSFP_LEN]; 822 u_char fp_subtype_nm[PF_OSFP_LEN]; 823}; 824.Ed 825.Pp 826Add a passive OS fingerprint to the table. 827Set 828.Va fp_os.fp_os 829to the packed fingerprint, 830.Va fp_os.fp_class_nm 831to the name of the class (Linux, Windows, etc), 832.Va fp_os.fp_version_nm 833to the name of the version (NT, 95, 98), and 834.Va fp_os.fp_subtype_nm 835to the name of the subtype or patchlevel. 836The members 837.Va fp_mss , 838.Va fp_wsize , 839.Va fp_psize , 840.Va fp_ttl , 841.Va fp_optcnt , 842and 843.Va fp_wscale 844are set to the TCP MSS, the TCP window size, the IP length, the IP TTL, 845the number of TCP options, and the TCP window scaling constant of the 846TCP SYN packet, respectively. 847.Pp 848The 849.Va fp_flags 850member is filled according to the 851.In net/pfvar.h 852include file 853.Dv PF_OSFP_* 854defines. 855The 856.Va fp_tcpopts 857member contains packed TCP options. 858Each option uses 859.Dv PF_OSFP_TCPOPT_BITS 860bits in the packed value. 861Options include any of 862.Dv PF_OSFP_TCPOPT_NOP , 863.Dv PF_OSFP_TCPOPT_SACK , 864.Dv PF_OSFP_TCPOPT_WSCALE , 865.Dv PF_OSFP_TCPOPT_MSS , 866or 867.Dv PF_OSFP_TCPOPT_TS . 868.Pp 869The 870.Va fp_getnum 871member is not used with this ioctl. 872.Pp 873The structure's slack space must be zeroed for correct operation; 874.Xr memset 3 875the whole structure to zero before filling and sending to the kernel. 876.It Dv DIOCOSFPGET Fa "struct pf_osfp_ioctl *io" 877Get the passive OS fingerprint number 878.Va fp_getnum 879from the kernel's fingerprint list. 880The rest of the structure members will come back filled. 881Get the whole list by repeatedly incrementing the 882.Va fp_getnum 883number until the ioctl returns 884.Er EBUSY . 885.It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes *psn" 886.Bd -literal 887struct pfioc_src_nodes { 888 int psn_len; 889 union { 890 caddr_t psu_buf; 891 struct pf_src_node *psu_src_nodes; 892 } psn_u; 893#define psn_buf psn_u.psu_buf 894#define psn_src_nodes psn_u.psu_src_nodes 895}; 896.Ed 897.Pp 898Get the list of source nodes kept by sticky addresses and source 899tracking. 900The ioctl must be called once with 901.Va psn_len 902set to 0. 903If the ioctl returns without error, 904.Va psn_len 905will be set to the size of the buffer required to hold all the 906.Va pf_src_node 907structures held in the table. 908A buffer of this size should then be allocated, and a pointer to this buffer 909placed in 910.Va psn_buf . 911The ioctl must then be called again to fill this buffer with the actual 912source node data. 913After that call, 914.Va psn_len 915will be set to the length of the buffer actually used. 916.It Dv DIOCCLRSRCNODES 917Clear the tree of source tracking nodes. 918.It Dv DIOCIGETIFACES Fa "struct pfioc_iface *io" 919Get the list of interfaces and interface groups known to 920.Nm . 921All the ioctls that manipulate interfaces 922use the same structure described below: 923.Bd -literal 924struct pfioc_iface { 925 char pfiio_name[IFNAMSIZ]; 926 void *pfiio_buffer; 927 int pfiio_esize; 928 int pfiio_size; 929 int pfiio_nzero; 930 int pfiio_flags; 931}; 932.Ed 933.Pp 934If not empty, 935.Va pfiio_name 936can be used to restrict the search to a specific interface or group. 937.Va pfiio_buffer[pfiio_size] 938is the user-supplied buffer for returning the data. 939On entry, 940.Va pfiio_size 941contains the number of 942.Vt pfi_kif 943entries that can fit into the buffer. 944The kernel will replace this value by the real number of entries it wants 945to return. 946.Va pfiio_esize 947should be set to 948.Li sizeof(struct pfi_kif) . 949.Pp 950The data is returned in the 951.Vt pfi_kif 952structure described below: 953.Bd -literal 954struct pfi_kif { 955 char pfik_name[IFNAMSIZ]; 956 RB_ENTRY(pfi_kif) pfik_tree; 957 u_int64_t pfik_packets[2][2][2]; 958 u_int64_t pfik_bytes[2][2][2]; 959 time_t pfik_tzero; 960 int pfik_flags; 961 int pfik_flags_new; 962 void *pfik_ah_cookie; 963 struct ifnet *pfik_ifp; 964 struct ifg_group *pfik_group; 965 int pfik_states; 966 int pfik_rules; 967 int pfik_routes; 968 TAILQ_HEAD(, pfi_dynaddr) pfik_dynaddrs; 969}; 970.Ed 971.It Dv DIOCSETSTATUSIF Fa "struct pfioc_iface *pi" 972Specify the interface for which statistics are accumulated. 973.It Dv DIOCSETIFFLAG Fa "struct pfioc_iface *io" 974Set the user settable flags (described above) of the 975.Nm 976internal interface description. 977The filtering process is the same as for 978.Dv DIOCIGETIFACES . 979.Bd -literal 980#define PFI_IFLAG_SKIP 0x0100 /* skip filtering on interface */ 981.Ed 982.It Dv DIOCCLRIFFLAG Fa "struct pfioc_iface *io" 983Works as 984.Dv DIOCSETIFFLAG 985above but clears the flags. 986.It Dv DIOCKILLSRCNODES Fa "struct pfioc_src_node_kill *psnk" 987Explicitly remove source tracking nodes. 988.Bd -literal 989struct pfioc_src_node_kill { 990 sa_family_t psnk_af; 991 struct pf_rule_addr psnk_src; 992 struct pf_rule_addr psnk_dst; 993 u_int psnk_killed; 994}; 995.Ed 996.El 997.Sh FILES 998.Bl -tag -width /dev/pf -compact 999.It Pa /dev/pf 1000packet filtering device. 1001.El 1002.Sh EXAMPLES 1003The following example demonstrates how to use the 1004.Dv DIOCGETLIMIT 1005command to show the hard limit of a memory pool used by the packet filter: 1006.Bd -literal 1007#include <sys/types.h> 1008#include <sys/socket.h> 1009#include <sys/ioctl.h> 1010#include <sys/fcntl.h> 1011 1012#include <netinet/in.h> 1013#include <net/if.h> 1014#include <net/pfvar.h> 1015 1016#include <err.h> 1017#include <limits.h> 1018#include <stdio.h> 1019#include <stdlib.h> 1020#include <string.h> 1021 1022static const struct { 1023 const char *name; 1024 int index; 1025} pf_limits[] = { 1026 { "states", PF_LIMIT_STATES }, 1027 { "src-nodes", PF_LIMIT_SRC_NODES }, 1028 { "frags", PF_LIMIT_FRAGS }, 1029 { "tables", PF_LIMIT_TABLES }, 1030 { "table-entries", PF_LIMIT_TABLE_ENTRIES }, 1031 { NULL, 0 } 1032}; 1033 1034void 1035usage(void) 1036{ 1037 int i; 1038 1039 fprintf(stderr, "usage: %s [", getprogname()); 1040 for (i = 0; pf_limits[i].name; i++) 1041 fprintf(stderr, "%s%s", (i > 0 ? "|" : ""), pf_limits[i].name); 1042 fprintf(stderr, "]\en"); 1043 exit(1); 1044} 1045 1046int 1047main(int argc, char *argv[]) 1048{ 1049 struct pfioc_limit pl; 1050 int i, dev; 1051 int pool_index = -1; 1052 1053 if (argc != 2) 1054 usage(); 1055 1056 for (i = 0; pf_limits[i].name; i++) 1057 if (strcmp(argv[1], pf_limits[i].name) == 0) { 1058 pool_index = pf_limits[i].index; 1059 break; 1060 } 1061 1062 if (pool_index == -1) { 1063 warnx("no such memory pool: %s", argv[1]); 1064 usage(); 1065 } 1066 1067 dev = open("/dev/pf", O_RDWR); 1068 if (dev == -1) 1069 err(1, "open(\e"/dev/pf\e") failed"); 1070 1071 memset(&pl, 0, sizeof(struct pfioc_limit)); 1072 pl.index = pool_index; 1073 1074 if (ioctl(dev, DIOCGETLIMIT, &pl) == -1) 1075 err(1, "DIOCGETLIMIT"); 1076 1077 printf("The %s memory pool has ", pf_limits[i].name); 1078 if (pl.limit == UINT_MAX) 1079 printf("unlimited entries.\en"); 1080 else 1081 printf("a hard limit of %u entries.\en", pl.limit); 1082 1083 return 0; 1084} 1085.Ed 1086.Sh SEE ALSO 1087.Xr ioctl 2 , 1088.Xr bridge 4 , 1089.Xr pflog 4 , 1090.Xr pflow 4 , 1091.Xr pfsync 4 , 1092.Xr pf.conf 5 , 1093.Xr pfctl 8 1094.Sh HISTORY 1095The 1096.Nm 1097packet filtering mechanism first appeared in 1098.Ox 3.0 . 1099