1 .\" $OpenBSD: pf.4,v 1.48 2004/03/27 17:15:30 henning Exp $
3 .\" Copyright (C) 2001, Kjell Wooding. All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
31 .Dd September 26, 2001
40 Packet filtering takes place in the kernel.
43 allows userland processes to control the
44 behavior of the packet filter through an
47 There are commands to enable and disable the filter, load rulesets,
48 add and remove individual rules or state table entries,
49 and retrieve statistics.
50 The most commonly used functions are covered by
53 Manipulations like loading a ruleset that involve more than a single
54 ioctl call require a so-called ticket, which prevents the occurrence of
55 multiple concurrent manipulations.
57 Fields of ioctl parameter structures that refer to packet data (like
58 addresses and ports) are generally expected in network byte-order.
60 .Bl -tag -width /dev/pf -compact
62 packet filtering device.
65 pf supports the following
68 .Bl -tag -width xxxxxx
70 Starts the packet filter.
72 Stops the packet filter.
74 Starts the ALTQ bandwidth control system.
76 Stops the ALTQ bandwidth control system.
77 .It Dv DIOCBEGINADDRS Fa "struct pfioc_pooladdr"
79 struct pfioc_pooladdr {
87 char anchor[PF_ANCHOR_NAME_SIZE];
88 char ruleset[PF_RULESET_NAME_SIZE];
89 struct pf_pooladdr addr;
93 Clears the buffer address pool
96 for subsequent DIOCADDADDR, DIOCADDRULE and DIOCCHANGERULE calls.
97 .It Dv DIOCADDADDR Fa "struct pfioc_pooladdr"
101 to the buffer address pool to be used in the following
102 DIOCADDRULE or DIOCCHANGERULE call.
103 All other members of the structure are ignored.
104 .It Dv DIOCADDRULE Fa "struct pfioc_rule"
109 u_int32_t pool_ticket;
111 char anchor[PF_ANCHOR_NAME_SIZE];
112 char ruleset[PF_RULESET_NAME_SIZE];
119 at the end of the inactive ruleset.
122 obtained through preceding DIOCXBEGIN call, and
124 obtained through DIOCBEGINADDRS call.
125 DIOCADDADDR must also be called if any pool addresses are required.
130 names indicate the anchor and ruleset in which to append the rule.
135 .It Dv DIOCADDALTQ Fa "struct pfioc_altq"
145 .It Dv DIOCGETRULES Fa "struct pfioc_rule"
148 for subsequent DIOCGETRULE calls and
150 of rules in the active ruleset.
151 .It Dv DIOCGETRULE Fa "struct pfioc_rule"
158 obtained through a preceding DIOCGETRULES call.
159 .It Dv DIOCGETADDRS Fa "struct pfioc_pooladdr"
162 for subsequent DIOCGETADDR calls and
164 of pool addresses in the rule specified with
170 .It Dv DIOCGETADDR Fa "struct pfioc_pooladdr"
175 from the rule specified with
183 obtained through a preceding DIOCGETADDRS call.
184 .It Dv DIOCGETALTQS Fa "struct pfioc_altq"
187 for subsequent DIOCGETALTQ calls and
189 of queues in the active list.
190 .It Dv DIOCGETALTQ Fa "struct pfioc_altq"
197 obtained through a preceding DIOCGETALTQS call.
198 .It Dv DIOCGETQSTATS Fa "struct pfioc_qstats"
199 Returns statistics on a queue.
201 struct pfioc_qstats {
210 A pointer to a buffer of statistics
214 for the queue specified by
216 .It Dv DIOCADDSTATE Fa "struct pfioc_state"
218 .It Dv DIOCGETSTATE Fa "struct pfioc_state"
222 struct pf_state state;
226 Extracts the entry with the specified number from the state table.
227 .It Dv DIOCKILLSTATES Fa "struct pfioc_state_kill"
228 Removes matching entries from the state table.
229 Returns the number of killed states in psk_af.
231 struct pfioc_state_kill {
234 struct pf_rule_addr psk_src;
235 struct pf_rule_addr psk_dst;
236 char psk_ifname[IFNAMSIZ];
239 .It Dv DIOCCLRSTATES Fa "struct pfioc_state_kill"
243 but ignores the psk_af, psk_proto, psk_src and psk_dst fields of the
246 .It Dv DIOCSETSTATUSIF Fa "struct pfioc_if"
249 char ifname[IFNAMSIZ];
253 Specifies the interface for which statistics are accumulated.
254 .It Dv DIOCGETSTATUS Fa "struct pf_status"
257 u_int64_t counters[PFRES_MAX];
258 u_int64_t fcounters[FCNT_MAX];
259 u_int64_t scounters[SCNT_MAX];
260 u_int64_t pcounters[2][2][3];
261 u_int64_t bcounters[2][2];
269 char ifname[IFNAMSIZ];
273 Gets the internal packet filter statistics.
275 Clears the internal packet filter statistics.
276 .It Dv DIOCNATLOOK Fa "struct pfioc_natlook"
277 Looks up a state table entry by source and destination addresses and ports.
279 struct pfioc_natlook {
280 struct pf_addr saddr;
281 struct pf_addr daddr;
282 struct pf_addr rsaddr;
283 struct pf_addr rdaddr;
293 .It Dv DIOCSETDEBUG Fa "u_int32_t"
294 Sets the debug level.
296 enum { PF_DEBUG_NONE=0, PF_DEBUG_URGENT=1, PF_DEBUG_MISC=2 };
298 .It Dv DIOCGETSTATES Fa "struct pfioc_states"
300 struct pfioc_states {
304 struct pf_state *psu_states;
306 #define ps_buf ps_u.psu_buf
307 #define ps_states ps_u.psu_states
310 .It Dv DIOCCHANGERULE Fa "struct pfioc_rule"
313 in the ruleset specified by
316 enum { PF_CHANGE_ADD_HEAD=1, PF_CHANGE_ADD_TAIL=2,
317 PF_CHANGE_ADD_BEFORE=3, PF_CHANGE_ADD_AFTER=4,
318 PF_CHANGE_REMOVE=5, PF_CHANGE_GET_TICKET=6 };
321 The type of operation to be performed is indicated by
325 must be set to the value obtained with PF_CHANGE_GET_TICKET
326 for all actions except PF_CHANGE_GET_TICKET.
328 must be set to the value obtained with the DIOCBEGINADDRS call
329 for all actions except PF_CHANGE_REMOVE and PF_CHANGE_GET_TICKET.
334 indicate which anchor and ruleset the operation applies to.
336 indicates the rule number against which PF_CHANGE_ADD_BEFORE,
337 PF_CHANGE_ADD_AFTER or PF_CHANGE_REMOVE actions are applied.
338 .It Dv DIOCCHANGEADDR Fa "struct pfioc_pooladdr"
339 Adds or removes a pool address
341 from a rule specified with
347 .It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm"
354 .It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm"
355 .It Dv DIOCCLRRULECTRS
356 Clear per-rule statistics.
357 .It Dv DIOCSETLIMIT Fa "struct pfioc_limit"
358 Sets hard limits on the memory pools used by the packet filter.
365 .It Dv DIOCGETLIMIT Fa "struct pfioc_limit"
366 .It Dv DIOCRCLRTABLES Fa "struct pfioc_table"
368 All the IOCTLs that manipulate radix tables
369 use the same structure described below.
371 .Dv DIOCRCLRTABLES, pfrio_ndel contains on exit the number
375 struct pfr_table pfrio_table;
386 #define pfrio_exists pfrio_nadd
387 #define pfrio_nzero pfrio_nadd
388 #define pfrio_nmatch pfrio_nadd
389 #define pfrio_naddr pfrio_size2
390 #define pfrio_setflag pfrio_size2
391 #define pfrio_clrflag pfrio_nadd
393 .It Dv DIOCRADDTABLES Fa "struct pfioc_table"
394 Creates one or more tables.
395 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
396 On exit, pfrio_nadd contains the number of tables effectively created.
399 char pfrt_anchor[PF_ANCHOR_NAME_SIZE];
400 char pfrt_ruleset[PF_RULESET_NAME_SIZE];
401 char pfrt_name[PF_TABLE_NAME_SIZE];
402 u_int32_t pfrt_flags;
406 .It Dv DIOCRDELTABLES Fa "struct pfioc_table"
407 Deletes one or more tables.
408 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
409 On exit, pfrio_nadd contains the number of tables effectively deleted.
410 .It Dv DIOCRGETTABLES Fa "struct pfioc_table"
411 Get the list of all tables.
412 On entry, pfrio_buffer[pfrio_size] contains a valid writeable buffer for
413 pfr_table structures.
414 On exit, pfrio_size contains the number of tables written into the buffer.
415 If the buffer is too small, the kernel does not store anything but just
416 returns the required buffer size, without error.
417 .It Dv DIOCRGETTSTATS Fa "struct pfioc_table"
420 but returns an array of pfr_tstats structures.
423 struct pfr_table pfrts_t;
424 u_int64_t pfrts_packets
425 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
426 u_int64_t pfrts_bytes
427 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
428 u_int64_t pfrts_match;
429 u_int64_t pfrts_nomatch;
432 int pfrts_refcnt[PFR_REFCNT_MAX];
434 #define pfrts_name pfrts_t.pfrt_name
435 #define pfrts_flags pfrts_t.pfrt_flags
437 .It Dv DIOCRCLRTSTATS Fa "struct pfioc_table"
438 Clears the statistics of one or more tables.
439 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
440 On exit, pfrio_nzero contains the number of tables effectively cleared.
441 .It Dv DIOCRCLRADDRS Fa "struct pfioc_table"
442 Clear all addresses in a table.
443 On entry, pfrio_table contains the table to clear.
444 On exit, pfrio_ndel contains the number of addresses removed.
445 .It Dv DIOCRADDADDRS Fa "struct pfioc_table"
446 Add one or more addresses to a table.
447 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
448 contains the list of pfr_addr structures to add.
449 On exit, pfrio_nadd contains the number of addresses effectively added.
453 struct in_addr _pfra_ip4addr;
454 struct in6_addr _pfra_ip6addr;
461 #define pfra_ip4addr pfra_u._pfra_ip4addr
462 #define pfra_ip6addr pfra_u._pfra_ip6addr
464 .It Dv DIOCRDELADDRS Fa "struct pfioc_table"
465 Delete one or more addresses from a table.
466 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
467 contains the list of pfr_addr structures to delete.
468 On exit, pfrio_ndel contains the number of addresses effectively deleted.
469 .It Dv DIOCRSETADDRS Fa "struct pfioc_table"
470 Replace the content of a table by a new address list.
471 This is the most complicated command, which uses all the structure members.
472 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
473 contains the new list of pfr_addr structures.
474 In addition to that, if size2 is nonzero, pfrio_buffer[pfrio_size..pfrio_size2]
475 must be a writeable buffer, into which the kernel can copy the addresses that
476 have been deleted during the replace operation.
477 On exit, pfrio_ndel, pfrio_nadd and pfrio_nchange contain the number of
478 addresses deleted, added and changed by the kernel.
479 If pfrio_size2 was set on
480 entry, pfrio_size2 will point to the size of the buffer used, exactly like
482 .It Dv DIOCRGETADDRS Fa "struct pfioc_table"
483 Get all the addresses of a table.
484 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
485 contains a valid writeable buffer for pfr_addr structures.
486 On exit, pfrio_size contains the number of addresses written into the buffer.
487 If the buffer was too small, the kernel does not store anything but just
488 return the required buffer size, without returning an error.
489 .It Dv DIOCRGETASTATS Fa "struct pfioc_table"
492 but returns an array of pfr_astats structures.
495 struct pfr_addr pfras_a;
496 u_int64_t pfras_packets
497 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
498 u_int64_t pfras_bytes
499 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
503 .It Dv DIOCRCLRASTATS Fa "struct pfioc_table"
504 Clears the statistics of one or more addresses.
505 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
506 contains a table of pfr_addr structures to clear.
507 On exit, pfrio_nzero contains the number of addresses effectively cleared.
508 .It Dv DIOCRTSTADDRS Fa "struct pfioc_table"
509 Test if the given addresses match a table.
510 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
511 contains a table of pfr_addr structures to test.
512 On exit, the kernel updates the pfr_addr table by setting the pfra_fback
513 member appropriately.
514 .It Dv DIOCRSETTFLAGS Fa "struct pfioc_table"
520 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures,
521 and pfrio_setflag contains the flags to add, while pfrio_clrflag contains the
523 On exit, pfrio_nchange and pfrio_ndel contain the number of tables altered
524 or deleted by the kernel.
525 Yes, tables can be deleted if one removes the
527 flag of an unreferenced table.
528 .It Dv DIOCRINADEFINE Fa "struct pfioc_table"
529 Defines a table in the inactive set.
530 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
531 contains the list of pfr_addr structures to put in the table.
532 A valid ticket must also be supplied to pfrio_ticket.
533 On exit, pfrio_nadd contains 0 if the table was already defined in the
534 inactive list, or 1 if a new table has been created.
535 pfrio_naddr contains the number of addresses effectively put in the table.
536 .It Dv DIOCXBEGIN Fa "struct pfioc_trans"
538 #define PF_RULESET_ALTQ (PF_RULESET_MAX)
539 #define PF_RULESET_TABLE (PF_RULESET_MAX+1)
541 int size; /* number of elements */
542 int esize; /* size of each element in bytes */
543 struct pfioc_trans_e {
545 char anchor[PF_ANCHOR_NAME_SIZE];
546 char ruleset[PF_RULESET_NAME_SIZE];
552 Clears all the inactive rulesets specified in the
553 .Fa "struct pfioc_trans_e"
555 For each ruleset, a ticket is returned for subsequent "add rule" IOCTLs,
561 .It Dv DIOCXCOMMIT Fa "struct pfioc_trans"
562 Atomically switch a vector of inactive rulesets to the active rulesets.
563 Implemented as a standard 2-phase commit, which will either fail for all
564 rulesets or completely succeed.
565 All tickets need to be valid.
568 if a concurrent process is trying to update some of the same rulesets
570 .It Dv DIOCXROLLBACK Fa "struct pfioc_trans"
571 Clean up the kernel by undoing all changes that have taken place on the
572 inactive rulesets since the last
575 will silently ignore rulesets for which the ticket is invalid.
577 Flush the passive OS fingerprint table.
578 .It Dv DIOCFPADD Fa "struct pf_osfp_ioctl"
580 struct pf_osfp_ioctl {
581 struct pf_osfp_entry {
582 SLIST_ENTRY(pf_osfp_entry) fp_entry;
584 char fp_class_nm[PF_OSFP_LEN];
585 char fp_version_nm[PF_OSFP_LEN];
586 char fp_subtype_nm[PF_OSFP_LEN];
598 Add a passive OS fingerprint to the table.
601 to the packed fingerprint,
602 .Va fp_os.fp_class_nm
603 to the name of the class (Linux, Windows, etc),
604 .Va fp_os.fp_version_nm
605 to the name of the version (NT, 95, 98), and
606 .Va fp_os.fp_subtype_nm
607 to the name of the subtype or patchlevel.
615 are set to the TCP MSS, the TCP window size, the IP length and the IP TTL of
616 the TCP SYN packet respectively.
619 member is filled according to the net/pfvar.h include file PF_OSFP_* defines.
622 is not used with this ioctl.
624 The structure's slack space must be zeroed for correct operation; memset
625 the whole structure to zero before filling and sending to the kernel.
626 .It Dv DIOCFPGET Fa "struct pf_osfp_ioctl"
628 struct pf_osfp_ioctl {
629 struct pf_osfp_entry {
630 SLIST_ENTRY(pf_osfp_entry) fp_entry;
632 char fp_class_nm[PF_OSFP_LEN];
633 char fp_version_nm[PF_OSFP_LEN];
634 char fp_subtype_nm[PF_OSFP_LEN];
646 Get the passive OS fingerprint number
648 from the kernel's fingerprint list.
649 The rest of the structure members will come back filled.
650 Get the whole list by repeatedly incrementing the
652 number until the ioctl returns EBUSY.
653 .It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes"
655 struct pfioc_src_nodes {
659 struct pf_src_node *psu_src_nodes;
661 #define psn_buf psn_u.psu_buf
662 #define psn_src_nodes psn_u.psu_src_nodes
666 Get the list of source nodes kept by the
671 The ioctl must be called once with
674 If the ioctl returns without error,
676 will be set to the size of the buffer required to hold all the
678 structures held in the table.
679 A buffer of this size should then be allocated, and a pointer to this buffer
682 The ioctl must then be called again to fill this buffer with the actual
686 will be set to the length of the buffer actually used.
687 .It Dv DIOCCLRSRCNODES Fa "struct pfioc_table"
688 Clear the tree of source tracking nodes.
689 .It Dv DIOCIGETIFACES Fa "struct pfioc_iface"
690 Gets the list of interfaces and interface drivers known to
692 All the IOCTLs that manipulate interfaces
693 use the same structure described below:
696 char pfiio_name[IFNAMSIZ];
704 #define PFI_FLAG_GROUP 0x0001 /* gets groups of interfaces */
705 #define PFI_FLAG_INSTANCE 0x0002 /* gets single interfaces */
706 #define PFI_FLAG_ALLMASK 0x0003
711 can be used to restrict the search to a specific interface or driver.
712 .Va pfiio_buffer[pfiio_size]
713 is the user-supplied buffer for returning the data.
716 represents the number of
718 entries that can fit into the buffer.
719 The kernel will replace this value by the real number of entries it wants
722 should be set to sizeof(struct pfi_if).
725 .Dv PFI_FLAG_GROUP , PFI_FLAG_INSTANCE ,
726 or both to tell the kernel to return a group of interfaces
727 (drivers, like "fxp"), real interface instances (like "fxp1") or both.
728 The data is returned in the
730 structure described below:
733 char pfif_name[IFNAMSIZ];
734 u_int64_t pfif_packets[2][2][2];
735 u_int64_t pfif_bytes[2][2][2];
736 u_int64_t pfif_addcnt;
737 u_int64_t pfif_delcnt;
744 #define PFI_IFLAG_GROUP 0x0001 /* group of interfaces */
745 #define PFI_IFLAG_INSTANCE 0x0002 /* single instance */
746 #define PFI_IFLAG_CLONABLE 0x0010 /* clonable group */
747 #define PFI_IFLAG_DYNAMIC 0x0020 /* dynamic group */
748 #define PFI_IFLAG_ATTACHED 0x0040 /* interface attached */
749 #define PFI_IFLAG_REFERENCED 0x0080 /* referenced by rules */
751 .It Dv DIOCICLRISTATS Fa "struct pfioc_iface"
752 Clear the statistics counters of one or more interfaces.
756 can be used to select which interfaces need to be cleared.
757 The filtering process is the same as for
760 will be set by the kernel to the number of interfaces and drivers
761 that have been cleared.
764 The following example demonstrates how to use the DIOCNATLOOK command
765 to find the internal host/port of a NATed connection.
767 #include <sys/types.h>
768 #include <sys/socket.h>
769 #include <sys/ioctl.h>
770 #include <sys/fcntl.h>
772 #include <netinet/in.h>
773 #include <net/pfvar.h>
779 read_address(const char *s)
783 sscanf(s, "%i.%i.%i.%i", &a, &b, &c, &d);
784 return htonl(a << 24 | b << 16 | c << 8 | d);
788 print_address(u_int32_t a)
791 printf("%d.%d.%d.%d", a >> 24 & 255, a >> 16 & 255,
792 a >> 8 & 255, a & 255);
796 main(int argc, char *argv[])
798 struct pfioc_natlook nl;
802 printf("%s <gwy addr> <gwy port> <ext addr> <ext port>\\n",
807 dev = open("/dev/pf", O_RDWR);
809 err(1, "open(\\"/dev/pf\\") failed");
811 memset(&nl, 0, sizeof(struct pfioc_natlook));
812 nl.saddr.v4.s_addr = read_address(argv[1]);
813 nl.sport = htons(atoi(argv[2]));
814 nl.daddr.v4.s_addr = read_address(argv[3]);
815 nl.dport = htons(atoi(argv[4]));
817 nl.proto = IPPROTO_TCP;
818 nl.direction = PF_IN;
820 if (ioctl(dev, DIOCNATLOOK, &nl))
821 err(1, "DIOCNATLOOK");
823 printf("internal host ");
824 print_address(nl.rsaddr.v4.s_addr);
825 printf(":%u\\n", ntohs(nl.rsport));
838 packet filtering mechanism first appeared in