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