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