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