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