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