1.\" $OpenBSD: pf.4,v 1.74 2012/02/10 00:08:20 haesbaert 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 $Mdocdate: February 10 2012 $ 30.Dt PF 4 31.Os 32.Sh NAME 33.Nm pf 34.Nd packet filter 35.Sh SYNOPSIS 36.Cd "pseudo-device pf" 37.Sh DESCRIPTION 38Packet filtering takes place in the kernel. 39A pseudo-device, 40.Pa /dev/pf , 41allows userland processes to control the 42behavior of the packet filter through an 43.Xr ioctl 2 44interface. 45There are commands to enable and disable the filter, load rulesets, 46add and remove individual rules or state table entries, 47and retrieve statistics. 48The most commonly used functions are covered by 49.Xr pfctl 8 . 50.Pp 51Manipulations like loading a ruleset that involve more than a single 52.Xr ioctl 2 53call require a so-called 54.Em ticket , 55which prevents the occurrence of 56multiple concurrent manipulations. 57.Pp 58Fields of 59.Xr ioctl 2 60parameter structures that refer to packet data (like 61addresses and ports) are generally expected in network byte-order. 62.Pp 63Rules and address tables are contained in so-called 64.Em anchors . 65When servicing an 66.Xr ioctl 2 67request, if the anchor field of the argument structure is empty, 68the kernel will use the default anchor (i.e., the main ruleset) 69in operations. 70Anchors are specified by name and may be nested, with components 71separated by 72.Sq / 73characters, similar to how file system hierarchies are laid out. 74The final component of the anchor path is the anchor under which 75operations will be performed. 76Anchor names with characters after the terminating null byte are 77considered invalid; if used in an ioctl, 78.Er EINVAL 79will be returned. 80.Sh IOCTL INTERFACE 81.Nm 82supports the following 83.Xr ioctl 2 84commands, available through 85.Aq Pa net/pfvar.h : 86.Bl -tag -width xxxxxx 87.It Dv DIOCSTART 88Start the packet filter. 89.It Dv DIOCSTOP 90Stop the packet filter. 91.It Dv DIOCSTARTALTQ 92Start the ALTQ bandwidth control system (see 93.Xr altq 9 ) . 94.It Dv DIOCSTOPALTQ 95Stop the ALTQ bandwidth control system. 96.It Dv DIOCADDRULE Fa "struct pfioc_rule *pr" 97.Bd -literal 98struct pfioc_rule { 99 u_int32_t action; 100 u_int32_t ticket; 101 u_int32_t nr; 102 char anchor[MAXPATHLEN]; 103 char anchor_call[MAXPATHLEN]; 104 struct pf_rule rule; 105}; 106.Ed 107.Pp 108Add 109.Va rule 110at the end of the inactive ruleset. 111This call requires a 112.Va ticket 113obtained through a preceding 114.Dv DIOCXBEGIN 115call. 116The optional 117.Va anchor 118name indicates the anchor in which to append the rule. 119.Va nr 120and 121.Va action 122are ignored. 123.It Dv DIOCADDALTQ Fa "struct pfioc_altq *pa" 124Add an ALTQ discipline or queue. 125.Bd -literal 126struct pfioc_altq { 127 u_int32_t action; 128 u_int32_t ticket; 129 u_int32_t nr; 130 struct pf_altq altq; 131}; 132.Ed 133.It Dv DIOCGETRULES Fa "struct pfioc_rule *pr" 134Get a 135.Va ticket 136for subsequent 137.Dv DIOCGETRULE 138calls and the number 139.Va nr 140of rules in the active ruleset. 141.It Dv DIOCGETRULE Fa "struct pfioc_rule *pr" 142Get a 143.Va rule 144by its number 145.Va nr 146using the 147.Va ticket 148obtained through a preceding 149.Dv DIOCGETRULES 150call. 151If 152.Va action 153is set to 154.Dv PF_GET_CLR_CNTR , 155the per-rule statistics on the requested rule are cleared. 156.It Dv DIOCGETALTQS Fa "struct pfioc_altq *pa" 157Get a 158.Va ticket 159for subsequent 160.Dv DIOCGETALTQ 161calls and the number 162.Va nr 163of queues in the active list. 164.It Dv DIOCGETALTQ Fa "struct pfioc_altq *pa" 165Get the queueing discipline 166.Va altq 167by its number 168.Va nr 169using the 170.Va ticket 171obtained through a preceding 172.Dv DIOCGETALTQS 173call. 174.It Dv DIOCGETQSTATS Fa "struct pfioc_qstats *pq" 175Get the statistics on a queue. 176.Bd -literal 177struct pfioc_qstats { 178 u_int32_t ticket; 179 u_int32_t nr; 180 void *buf; 181 int nbytes; 182 u_int8_t scheduler; 183}; 184.Ed 185.Pp 186This call fills in a pointer to the buffer of statistics 187.Va buf , 188of length 189.Va nbytes , 190for the queue specified by 191.Va nr . 192.It Dv DIOCGETRULESETS Fa "struct pfioc_ruleset *pr" 193.Bd -literal 194struct pfioc_ruleset { 195 u_int32_t nr; 196 char path[MAXPATHLEN]; 197 char name[PF_ANCHOR_NAME_SIZE]; 198}; 199.Ed 200.Pp 201Get the number 202.Va nr 203of rulesets (i.e., anchors) directly attached to the anchor named by 204.Va path 205for use in subsequent 206.Dv DIOCGETRULESET 207calls. 208Nested anchors, since they are not directly attached to the given 209anchor, will not be included. 210This ioctl returns 211.Er EINVAL 212if the given anchor does not exist. 213.It Dv DIOCGETRULESET Fa "struct pfioc_ruleset *pr" 214Get a ruleset (i.e., an anchor) 215.Va name 216by its number 217.Va nr 218from the given anchor 219.Va path , 220the maximum number of which can be obtained from a preceding 221.Dv DIOCGETRULESETS 222call. 223This ioctl returns 224.Er EINVAL 225if the given anchor does not exist or 226.Er EBUSY 227if another process is concurrently updating a ruleset. 228.It Dv DIOCADDSTATE Fa "struct pfioc_state *ps" 229Add a state entry. 230.Bd -literal 231struct pfioc_state { 232 struct pfsync_state state; 233}; 234.Ed 235.It Dv DIOCGETSTATE Fa "struct pfioc_state *ps" 236Extract the entry identified by the 237.Va id 238and 239.Va creatorid 240fields of the 241.Va state 242structure from the state table. 243.It Dv DIOCKILLSTATES Fa "struct pfioc_state_kill *psk" 244Remove matching entries from the state table. 245This ioctl returns the number of killed states in 246.Va psk_killed . 247.Bd -literal 248struct pfioc_state_kill { 249 struct pf_state_cmp psk_pfcmp; 250 sa_family_t psk_af; 251 int psk_proto; 252 struct pf_rule_addr psk_src; 253 struct pf_rule_addr psk_dst; 254 char psk_ifname[IFNAMSIZ]; 255 char psk_label[PF_RULE_LABEL_SIZE]; 256 u_int psk_killed; 257 u_int16_t psk_rdomain; 258}; 259.Ed 260.It Dv DIOCCLRSTATES Fa "struct pfioc_state_kill *psk" 261Clear all states. 262It works like 263.Dv DIOCKILLSTATES , 264but ignores all fields of the 265.Vt pfioc_state_kill 266structure, except 267.Va psk_ifname . 268.It Dv DIOCSETSTATUSIF Fa "struct pfioc_if *pi" 269Specify the interface for which statistics are accumulated. 270.Bd -literal 271struct pfioc_if { 272 char ifname[IFNAMSIZ]; 273}; 274.Ed 275.It Dv DIOCGETSTATUS Fa "struct pf_status *s" 276Get the internal packet filter statistics. 277.Bd -literal 278struct pf_status { 279 u_int64_t counters[PFRES_MAX]; 280 u_int64_t lcounters[LCNT_MAX]; /* limit counters */ 281 u_int64_t fcounters[FCNT_MAX]; 282 u_int64_t scounters[SCNT_MAX]; 283 u_int64_t pcounters[2][2][3]; 284 u_int64_t bcounters[2][2]; 285 u_int64_t stateid; 286 u_int32_t running; 287 u_int32_t states; 288 u_int32_t src_nodes; 289 u_int32_t since; 290 u_int32_t debug; 291 u_int32_t hostid; 292 u_int32_t reass; /* reassembly */ 293 char ifname[IFNAMSIZ]; 294 u_int8_t pf_chksum[MD5_DIGEST_LENGTH]; 295}; 296.Ed 297.It Dv DIOCCLRSTATUS 298Clear the internal packet filter statistics. 299.It Dv DIOCNATLOOK Fa "struct pfioc_natlook *pnl" 300Look up a state table entry by source and destination addresses and ports. 301.Bd -literal 302struct pfioc_natlook { 303 struct pf_addr saddr; 304 struct pf_addr daddr; 305 struct pf_addr rsaddr; 306 struct pf_addr rdaddr; 307 u_int16_t rdomain; 308 u_int16_t sport; 309 u_int16_t dport; 310 u_int16_t rsport; 311 u_int16_t rdport; 312 sa_family_t af; 313 u_int8_t proto; 314 u_int8_t direction; 315}; 316.Ed 317.Pp 318This was primarily used to support transparent proxies with rdr-to rules. 319New proxies should use divert-to rules instead. 320These do not require access to the privileged 321.Pa /dev/pf 322device and preserve the original destination address for 323.Xr getsockname 2 . 324For 325.Dv SOCK_DGRAM 326sockets, the 327.Xr ip 4 328socket options 329.Dv IP_RECVDSTADDR 330and 331.Dv IP_RECVDSTPORT 332can be used to retrieve the destination address and port. 333.It Dv DIOCSETDEBUG Fa "u_int32_t *level" 334Set the debug level. 335See the 336.Xr syslog 3 337man page for a list of valid debug levels. 338.It Dv DIOCGETSTATES Fa "struct pfioc_states *ps" 339Get state table entries. 340.Bd -literal 341struct pfioc_states { 342 int ps_len; 343 union { 344 caddr_t psu_buf; 345 struct pfsync_state *psu_states; 346 } ps_u; 347#define ps_buf ps_u.psu_buf 348#define ps_states ps_u.psu_states 349}; 350.Ed 351.Pp 352If 353.Va ps_len 354is non-zero on entry, as many states as possible that can fit into this 355size will be copied into the supplied buffer 356.Va ps_states . 357On exit, 358.Va ps_len 359is always set to the total size required to hold all state table entries 360(i.e., it is set to 361.Li sizeof(struct pfsync_state) * nr ) . 362.It Dv DIOCCHANGERULE Fa "struct pfioc_rule *pcr" 363Add or remove the 364.Va rule 365in the ruleset specified by 366.Va rule.action . 367.Pp 368The type of operation to be performed is indicated by 369.Va action , 370which can be any of the following: 371.Bd -literal 372enum { PF_CHANGE_NONE, PF_CHANGE_ADD_HEAD, PF_CHANGE_ADD_TAIL, 373 PF_CHANGE_ADD_BEFORE, PF_CHANGE_ADD_AFTER, 374 PF_CHANGE_REMOVE, PF_CHANGE_GET_TICKET }; 375.Ed 376.Pp 377.Va ticket 378must be set to the value obtained with 379.Dv PF_CHANGE_GET_TICKET 380for all actions except 381.Dv PF_CHANGE_GET_TICKET . 382.Va anchor 383indicates to which anchor the operation applies. 384.Va nr 385indicates the rule number against which 386.Dv PF_CHANGE_ADD_BEFORE , 387.Dv PF_CHANGE_ADD_AFTER , 388or 389.Dv PF_CHANGE_REMOVE 390actions are applied. 391.\" It Dv DIOCCHANGEALTQ Fa "struct pfioc_altq *pcr" 392.It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm *pt" 393.Bd -literal 394struct pfioc_tm { 395 int timeout; 396 int seconds; 397}; 398.Ed 399.Pp 400Set the state timeout of 401.Va timeout 402to 403.Va seconds . 404The old value will be placed into 405.Va seconds . 406For possible values of 407.Va timeout , 408consult the 409.Dv PFTM_* 410values in 411.Aq Pa net/pfvar.h . 412.It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm *pt" 413Get the state timeout of 414.Va timeout . 415The value will be placed into the 416.Va seconds 417field. 418.It Dv DIOCCLRRULECTRS 419Clear per-rule statistics. 420.It Dv DIOCSETLIMIT Fa "struct pfioc_limit *pl" 421Set the hard limits on the memory pools used by the packet filter. 422.Bd -literal 423struct pfioc_limit { 424 int index; 425 unsigned limit; 426}; 427 428enum { PF_LIMIT_STATES, PF_LIMIT_SRC_NODES, PF_LIMIT_FRAGS, 429 PF_LIMIT_TABLES, PF_LIMIT_TABLE_ENTRIES, PF_LIMIT_MAX }; 430.Ed 431.It Dv DIOCGETLIMIT Fa "struct pfioc_limit *pl" 432Get the hard 433.Va limit 434for the memory pool indicated by 435.Va index . 436.It Dv DIOCRCLRTABLES Fa "struct pfioc_table *io" 437Clear all tables. 438All the ioctls that manipulate radix tables 439use the same structure described below. 440For 441.Dv DIOCRCLRTABLES , 442.Va pfrio_ndel 443contains on exit the number of tables deleted. 444.Bd -literal 445struct pfioc_table { 446 struct pfr_table pfrio_table; 447 void *pfrio_buffer; 448 int pfrio_esize; 449 int pfrio_size; 450 int pfrio_size2; 451 int pfrio_nadd; 452 int pfrio_ndel; 453 int pfrio_nchange; 454 int pfrio_flags; 455 u_int32_t pfrio_ticket; 456}; 457#define pfrio_exists pfrio_nadd 458#define pfrio_nzero pfrio_nadd 459#define pfrio_nmatch pfrio_nadd 460#define pfrio_naddr pfrio_size2 461#define pfrio_setflag pfrio_size2 462#define pfrio_clrflag pfrio_nadd 463.Ed 464.It Dv DIOCRADDTABLES Fa "struct pfioc_table *io" 465Create one or more tables. 466On entry, 467.Va pfrio_buffer 468must point to an array of 469.Vt struct pfr_table 470containing at least 471.Vt pfrio_size 472elements. 473.Vt pfrio_esize 474must be the size of 475.Vt struct pfr_table . 476On exit, 477.Va pfrio_nadd 478contains the number of tables effectively created. 479.Bd -literal 480struct pfr_table { 481 char pfrt_anchor[MAXPATHLEN]; 482 char pfrt_name[PF_TABLE_NAME_SIZE]; 483 u_int32_t pfrt_flags; 484 u_int8_t pfrt_fback; 485}; 486.Ed 487.It Dv DIOCRDELTABLES Fa "struct pfioc_table *io" 488Delete one or more tables. 489On entry, 490.Va pfrio_buffer 491must point to an array of 492.Vt struct pfr_table 493containing at least 494.Vt pfrio_size 495elements. 496.Vt pfrio_esize 497must be the size of 498.Vt struct pfr_table . 499On exit, 500.Va pfrio_ndel 501contains the number of tables effectively deleted. 502.It Dv DIOCRGETTABLES Fa "struct pfioc_table *io" 503Get the list of all tables. 504On entry, 505.Va pfrio_buffer[pfrio_size] 506contains a valid writeable buffer for 507.Vt pfr_table 508structures. 509On exit, 510.Va pfrio_size 511contains the number of tables written into the buffer. 512If the buffer is too small, the kernel does not store anything but just 513returns the required buffer size, without error. 514.It Dv DIOCRGETTSTATS Fa "struct pfioc_table *io" 515This call is like 516.Dv DIOCRGETTABLES 517but is used to get an array of 518.Vt pfr_tstats 519structures. 520.Bd -literal 521struct pfr_tstats { 522 struct pfr_table pfrts_t; 523 u_int64_t pfrts_packets 524 [PFR_DIR_MAX][PFR_OP_TABLE_MAX]; 525 u_int64_t pfrts_bytes 526 [PFR_DIR_MAX][PFR_OP_TABLE_MAX]; 527 u_int64_t pfrts_match; 528 u_int64_t pfrts_nomatch; 529 long pfrts_tzero; 530 int pfrts_cnt; 531 int pfrts_refcnt[PFR_REFCNT_MAX]; 532}; 533#define pfrts_name pfrts_t.pfrt_name 534#define pfrts_flags pfrts_t.pfrt_flags 535.Ed 536.It Dv DIOCRCLRTSTATS Fa "struct pfioc_table *io" 537Clear the statistics of one or more tables. 538On entry, 539.Va pfrio_buffer 540must point to an array of 541.Vt struct pfr_table 542containing at least 543.Vt pfrio_size 544elements. 545.Vt pfrio_esize 546must be the size of 547.Vt struct pfr_table . 548On exit, 549.Va pfrio_nzero 550contains the number of tables effectively cleared. 551.It Dv DIOCRCLRADDRS Fa "struct pfioc_table *io" 552Clear all addresses in a table. 553On entry, 554.Va pfrio_table 555contains the table to clear. 556On exit, 557.Va pfrio_ndel 558contains the number of addresses removed. 559.It Dv DIOCRADDADDRS Fa "struct pfioc_table *io" 560Add one or more addresses to a table. 561On entry, 562.Va pfrio_table 563contains the table ID and 564.Va pfrio_buffer 565must point to an array of 566.Vt struct pfr_addr 567containing at least 568.Vt pfrio_size 569elements to add to the table. 570.Vt pfrio_esize 571must be the size of 572.Vt struct pfr_addr . 573On exit, 574.Va pfrio_nadd 575contains the number of addresses effectively added. 576.Bd -literal 577struct pfr_addr { 578 union { 579 struct in_addr _pfra_ip4addr; 580 struct in6_addr _pfra_ip6addr; 581 } pfra_u; 582 char pfra_ifname[IFNAMSIZ]; 583 u_int8_t pfra_af; 584 u_int8_t pfra_net; 585 u_int8_t pfra_not; 586 u_int8_t pfra_fback; 587 u_int8_t pfra_type; 588 u_int8_t pad[7]; 589}; 590#define pfra_ip4addr pfra_u._pfra_ip4addr 591#define pfra_ip6addr pfra_u._pfra_ip6addr 592.Ed 593.It Dv DIOCRDELADDRS Fa "struct pfioc_table *io" 594Delete one or more addresses from a table. 595On entry, 596.Va pfrio_table 597contains the table ID and 598.Va pfrio_buffer 599must point to an array of 600.Vt struct pfr_addr 601containing at least 602.Vt pfrio_size 603elements to delete from the table. 604.Vt pfrio_esize 605must be the size of 606.Vt struct pfr_addr . 607On exit, 608.Va pfrio_ndel 609contains the number of addresses effectively deleted. 610.It Dv DIOCRSETADDRS Fa "struct pfioc_table *io" 611Replace the content of a table by a new address list. 612This is the most complicated command, which uses all the structure members. 613.Pp 614On entry, 615.Va pfrio_table 616contains the table ID and 617.Va pfrio_buffer 618must point to an array of 619.Vt struct pfr_addr 620containing at least 621.Vt pfrio_size 622elements which become the new contents of the table. 623.Vt pfrio_esize 624must be the size of 625.Vt struct pfr_addr . 626Additionally, if 627.Va pfrio_size2 628is non-zero, 629.Va pfrio_buffer[pfrio_size..pfrio_size2] 630must be a writeable buffer, into which the kernel can copy the 631addresses that have been deleted during the replace operation. 632On exit, 633.Va pfrio_ndel , 634.Va pfrio_nadd , 635and 636.Va pfrio_nchange 637contain the number of addresses deleted, added, and changed by the 638kernel. 639If 640.Va pfrio_size2 641was set on entry, 642.Va pfrio_size2 643will point to the size of the buffer used, exactly like 644.Dv DIOCRGETADDRS . 645.It Dv DIOCRGETADDRS Fa "struct pfioc_table *io" 646Get all the addresses of a table. 647On entry, 648.Va pfrio_table 649contains the table ID and 650.Va pfrio_buffer[pfrio_size] 651contains a valid writeable buffer for 652.Vt pfr_addr 653structures. 654On exit, 655.Va pfrio_size 656contains the number of addresses written into the buffer. 657If the buffer was too small, the kernel does not store anything but just 658returns the required buffer size, without returning an error. 659.It Dv DIOCRGETASTATS Fa "struct pfioc_table *io" 660This call is like 661.Dv DIOCRGETADDRS 662but is used to get an array of 663.Vt pfr_astats 664structures. 665.Bd -literal 666struct pfr_astats { 667 struct pfr_addr pfras_a; 668 u_int64_t pfras_packets 669 [PFR_DIR_MAX][PFR_OP_ADDR_MAX]; 670 u_int64_t pfras_bytes 671 [PFR_DIR_MAX][PFR_OP_ADDR_MAX]; 672 long pfras_tzero; 673}; 674.Ed 675.It Dv DIOCRCLRASTATS Fa "struct pfioc_table *io" 676Clear the statistics of one or more addresses. 677On entry, 678.Va pfrio_table 679contains the table ID and 680.Va pfrio_buffer 681must point to an array of 682.Vt struct pfr_addr 683containing at least 684.Vt pfrio_size 685elements to be cleared from the table. 686.Vt pfrio_esize 687must be the size of 688.Vt struct pfr_addr . 689On exit, 690.Va pfrio_nzero 691contains the number of addresses effectively cleared. 692.It Dv DIOCRTSTADDRS Fa "struct pfioc_table *io" 693Test if the given addresses match a table. 694On entry, 695.Va pfrio_table 696contains the table ID and 697.Va pfrio_buffer 698must point to an array of 699.Vt struct pfr_addr 700containing at least 701.Vt pfrio_size 702elements, each of which will be tested for a match in the table. 703.Vt pfrio_esize 704must be the size of 705.Vt struct pfr_addr . 706On exit, the kernel updates the 707.Vt pfr_addr 708array by setting the 709.Va pfra_fback 710member appropriately. 711.It Dv DIOCRSETTFLAGS Fa "struct pfioc_table *io" 712Change the 713.Dv PFR_TFLAG_CONST 714or 715.Dv PFR_TFLAG_PERSIST 716flags of a table. 717On entry, 718.Va pfrio_buffer 719must point to an array of 720.Vt struct pfr_table 721containing at least 722.Vt pfrio_size 723elements. 724.Va pfrio_esize 725must be the size of 726.Vt struct pfr_table . 727.Va pfrio_setflag 728must contain the flags to add, while 729.Va pfrio_clrflag 730must contain the flags to remove. 731On exit, 732.Va pfrio_nchange 733and 734.Va pfrio_ndel 735contain the number of tables altered or deleted by the kernel. 736Yes, tables can be deleted if one removes the 737.Dv PFR_TFLAG_PERSIST 738flag of an unreferenced table. 739.It Dv DIOCRINADEFINE Fa "struct pfioc_table *io" 740Defines a table in the inactive set. 741On entry, 742.Va pfrio_table 743contains the table ID and 744.Va pfrio_buffer[pfrio_size] 745contains an array of 746.Vt pfr_addr 747structures to put in the table. 748A valid ticket must also be supplied to 749.Va pfrio_ticket . 750On exit, 751.Va pfrio_nadd 752contains 0 if the table was already defined in the inactive list 753or 1 if a new table has been created. 754.Va pfrio_naddr 755contains the number of addresses effectively put in the table. 756.It Dv DIOCXBEGIN Fa "struct pfioc_trans *io" 757.Bd -literal 758struct pfioc_trans { 759 int size; /* number of elements */ 760 int esize; /* size of each element in bytes */ 761 struct pfioc_trans_e { 762 int type; 763 char anchor[MAXPATHLEN]; 764 u_int32_t ticket; 765 } *array; 766}; 767.Ed 768.Pp 769Clear all the inactive rulesets specified in the 770.Vt pfioc_trans_e 771array. 772For each ruleset, a ticket is returned for subsequent "add rule" ioctls, 773as well as for the 774.Dv DIOCXCOMMIT 775and 776.Dv DIOCXROLLBACK 777calls. 778.Pp 779Ruleset types, identified by 780.Va type , 781include the following: 782.Pp 783.Bl -tag -width PF_RULESET_FILTER -offset ind -compact 784.It Dv PF_RULESET_FILTER 785Filter rules. 786.It Dv PF_RULESET_ALTQ 787ALTQ disciplines. 788.It Dv PF_RULESET_TABLE 789Address tables. 790.El 791.It Dv DIOCXCOMMIT Fa "struct pfioc_trans *io" 792Atomically switch a vector of inactive rulesets to the active rulesets. 793This call is implemented as a standard two-phase commit, which will either 794fail for all rulesets or completely succeed. 795All tickets need to be valid. 796This ioctl returns 797.Er EBUSY 798if another process is concurrently updating some of the same rulesets. 799.It Dv DIOCXROLLBACK Fa "struct pfioc_trans *io" 800Clean up the kernel by undoing all changes that have taken place on the 801inactive rulesets since the last 802.Dv DIOCXBEGIN . 803.Dv DIOCXROLLBACK 804will silently ignore rulesets for which the ticket is invalid. 805.It Dv DIOCSETHOSTID Fa "u_int32_t *hostid" 806Set the host ID, which is used by 807.Xr pfsync 4 808to identify which host created state table entries. 809.It Dv DIOCOSFPFLUSH 810Flush the passive OS fingerprint table. 811.It Dv DIOCOSFPADD Fa "struct pf_osfp_ioctl *io" 812.Bd -literal 813struct pf_osfp_ioctl { 814 struct pf_osfp_entry fp_os; 815 pf_tcpopts_t fp_tcpopts; /* packed TCP options */ 816 u_int16_t fp_wsize; /* TCP window size */ 817 u_int16_t fp_psize; /* ip->ip_len */ 818 u_int16_t fp_mss; /* TCP MSS */ 819 u_int16_t fp_flags; 820 u_int8_t fp_optcnt; /* TCP option count */ 821 u_int8_t fp_wscale; /* TCP window scaling */ 822 u_int8_t fp_ttl; /* IPv4 TTL */ 823 824 int fp_getnum; /* DIOCOSFPGET number */ 825}; 826 827struct pf_osfp_entry { 828 SLIST_ENTRY(pf_osfp_entry) fp_entry; 829 pf_osfp_t fp_os; 830 int fp_enflags; 831#define PF_OSFP_EXPANDED 0x001 /* expanded entry */ 832#define PF_OSFP_GENERIC 0x002 /* generic signature */ 833#define PF_OSFP_NODETAIL 0x004 /* no p0f details */ 834#define PF_OSFP_LEN 32 835 char fp_class_nm[PF_OSFP_LEN]; 836 char fp_version_nm[PF_OSFP_LEN]; 837 char fp_subtype_nm[PF_OSFP_LEN]; 838}; 839.Ed 840.Pp 841Add a passive OS fingerprint to the table. 842Set 843.Va fp_os.fp_os 844to the packed fingerprint, 845.Va fp_os.fp_class_nm 846to the name of the class (Linux, Windows, etc), 847.Va fp_os.fp_version_nm 848to the name of the version (NT, 95, 98), and 849.Va fp_os.fp_subtype_nm 850to the name of the subtype or patchlevel. 851The members 852.Va fp_mss , 853.Va fp_wsize , 854.Va fp_psize , 855.Va fp_ttl , 856.Va fp_optcnt , 857and 858.Va fp_wscale 859are set to the TCP MSS, the TCP window size, the IP length, the IP TTL, 860the number of TCP options, and the TCP window scaling constant of the 861TCP SYN packet, respectively. 862.Pp 863The 864.Va fp_flags 865member is filled according to the 866.Aq Pa net/pfvar.h 867include file 868.Dv PF_OSFP_* 869defines. 870The 871.Va fp_tcpopts 872member contains packed TCP options. 873Each option uses 874.Dv PF_OSFP_TCPOPT_BITS 875bits in the packed value. 876Options include any of 877.Dv PF_OSFP_TCPOPT_NOP , 878.Dv PF_OSFP_TCPOPT_SACK , 879.Dv PF_OSFP_TCPOPT_WSCALE , 880.Dv PF_OSFP_TCPOPT_MSS , 881or 882.Dv PF_OSFP_TCPOPT_TS . 883.Pp 884The 885.Va fp_getnum 886member is not used with this ioctl. 887.Pp 888The structure's slack space must be zeroed for correct operation; 889.Xr memset 3 890the whole structure to zero before filling and sending to the kernel. 891.It Dv DIOCOSFPGET Fa "struct pf_osfp_ioctl *io" 892Get the passive OS fingerprint number 893.Va fp_getnum 894from the kernel's fingerprint list. 895The rest of the structure members will come back filled. 896Get the whole list by repeatedly incrementing the 897.Va fp_getnum 898number until the ioctl returns 899.Er EBUSY . 900.It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes *psn" 901.Bd -literal 902struct pfioc_src_nodes { 903 int psn_len; 904 union { 905 caddr_t psu_buf; 906 struct pf_src_node *psu_src_nodes; 907 } psn_u; 908#define psn_buf psn_u.psu_buf 909#define psn_src_nodes psn_u.psu_src_nodes 910}; 911.Ed 912.Pp 913Get the list of source nodes kept by sticky addresses and source 914tracking. 915The ioctl must be called once with 916.Va psn_len 917set to 0. 918If the ioctl returns without error, 919.Va psn_len 920will be set to the size of the buffer required to hold all the 921.Va pf_src_node 922structures held in the table. 923A buffer of this size should then be allocated, and a pointer to this buffer 924placed in 925.Va psn_buf . 926The ioctl must then be called again to fill this buffer with the actual 927source node data. 928After that call, 929.Va psn_len 930will be set to the length of the buffer actually used. 931.It Dv DIOCCLRSRCNODES 932Clear the tree of source tracking nodes. 933.It Dv DIOCIGETIFACES Fa "struct pfioc_iface *io" 934Get the list of interfaces and interface drivers known to 935.Nm . 936All the ioctls that manipulate interfaces 937use the same structure described below: 938.Bd -literal 939struct pfioc_iface { 940 char pfiio_name[IFNAMSIZ]; 941 void *pfiio_buffer; 942 int pfiio_esize; 943 int pfiio_size; 944 int pfiio_nzero; 945 int pfiio_flags; 946}; 947.Ed 948.Pp 949If not empty, 950.Va pfiio_name 951can be used to restrict the search to a specific interface or driver. 952.Va pfiio_buffer[pfiio_size] 953is the user-supplied buffer for returning the data. 954On entry, 955.Va pfiio_size 956contains the number of 957.Vt pfi_kif 958entries that can fit into the buffer. 959The kernel will replace this value by the real number of entries it wants 960to return. 961.Va pfiio_esize 962should be set to 963.Li sizeof(struct pfi_kif) . 964.Pp 965The data is returned in the 966.Vt pfi_kif 967structure described below: 968.Bd -literal 969struct pfi_kif { 970 char pfik_name[IFNAMSIZ]; 971 RB_ENTRY(pfi_kif) pfik_tree; 972 u_int64_t pfik_packets[2][2][2]; 973 u_int64_t pfik_bytes[2][2][2]; 974 u_int32_t pfik_tzero; 975 int pfik_flags; 976 int pfik_flags_new; 977 void *pfik_ah_cookie; 978 struct ifnet *pfik_ifp; 979 struct ifg_group *pfik_group; 980 int pfik_states; 981 int pfik_rules; 982 int pfik_routes; 983 TAILQ_HEAD(, pfi_dynaddr) pfik_dynaddrs; 984}; 985.Ed 986.It Dv DIOCSETIFFLAG Fa "struct pfioc_iface *io" 987Set the user settable flags (described above) of the 988.Nm 989internal interface description. 990The filtering process is the same as for 991.Dv DIOCIGETIFACES . 992.Bd -literal 993#define PFI_IFLAG_SKIP 0x0100 /* skip filtering on interface */ 994.Ed 995.It Dv DIOCCLRIFFLAG Fa "struct pfioc_iface *io" 996Works as 997.Dv DIOCSETIFFLAG 998above but clears the flags. 999.It Dv DIOCKILLSRCNODES Fa "struct pfioc_iface *io" 1000Explicitly remove source tracking nodes. 1001.El 1002.Sh FILES 1003.Bl -tag -width /dev/pf -compact 1004.It Pa /dev/pf 1005packet filtering device. 1006.El 1007.Sh EXAMPLES 1008The following example demonstrates how to use the 1009.Dv DIOCGETLIMIT 1010command to show the hard limit of a memory pool used by the packet filter: 1011.Bd -literal 1012#include <sys/types.h> 1013#include <sys/socket.h> 1014#include <sys/ioctl.h> 1015#include <sys/fcntl.h> 1016#include <net/if.h> 1017#include <net/pfvar.h> 1018#include <stdio.h> 1019#include <stdlib.h> 1020#include <string.h> 1021#include <err.h> 1022 1023static const struct { 1024 const char *name; 1025 int index; 1026} pf_limits[] = { 1027 { "states", PF_LIMIT_STATES }, 1028 { "src-nodes", PF_LIMIT_SRC_NODES }, 1029 { "frags", PF_LIMIT_FRAGS }, 1030 { "tables", PF_LIMIT_TABLES }, 1031 { "table-entries", PF_LIMIT_TABLE_ENTRIES }, 1032 { NULL, 0 } 1033}; 1034 1035void 1036usage(void) 1037{ 1038 extern char *__progname; 1039 int i; 1040 1041 fprintf(stderr, "usage: %s [", __progname); 1042 for (i = 0; pf_limits[i].name; i++) 1043 fprintf(stderr, "%s%s", (i > 0 ? "|" : ""), pf_limits[i].name); 1044 fprintf(stderr, "]\en"); 1045 exit(1); 1046} 1047 1048int 1049main(int argc, char *argv[]) 1050{ 1051 struct pfioc_limit pl; 1052 int i, dev; 1053 int pool_index = -1; 1054 1055 if (argc != 2) 1056 usage(); 1057 1058 for (i = 0; pf_limits[i].name; i++) 1059 if (!strcmp(argv[1], pf_limits[i].name)) { 1060 pool_index = pf_limits[i].index; 1061 break; 1062 } 1063 1064 if (pool_index == -1) { 1065 warnx("no such memory pool: %s", argv[1]); 1066 usage(); 1067 } 1068 1069 dev = open("/dev/pf", O_RDWR); 1070 if (dev == -1) 1071 err(1, "open(\e"/dev/pf\e") failed"); 1072 1073 bzero(&pl, sizeof(struct pfioc_limit)); 1074 pl.index = pool_index; 1075 1076 if (ioctl(dev, DIOCGETLIMIT, &pl)) 1077 err(1, "DIOCGETLIMIT"); 1078 1079 printf("The %s memory pool has ", pf_limits[i].name); 1080 if (pl.limit == UINT_MAX) 1081 printf("unlimited entries.\en"); 1082 else 1083 printf("a hard limit of %u entries.\en", pl.limit); 1084 1085 return (0); 1086} 1087.Ed 1088.Sh SEE ALSO 1089.Xr ioctl 2 , 1090.Xr bridge 4 , 1091.Xr pflog 4 , 1092.Xr pflow 4 , 1093.Xr pfsync 4 , 1094.Xr pf.conf 5 , 1095.Xr pfctl 8 , 1096.Xr altq 9 1097.Sh HISTORY 1098The 1099.Nm 1100packet filtering mechanism first appeared in 1101.Ox 3.0 . 1102