1 .\" $OpenBSD: pf.4,v 1.60 2007/12/02 12:08:04 pascoe 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
38 Packet filtering takes place in the kernel.
41 allows userland processes to control the
42 behavior of the packet filter through an
45 There are commands to enable and disable the filter, load rulesets,
46 add and remove individual rules or state table entries,
47 and retrieve statistics.
48 The most commonly used functions are covered by
51 Manipulations like loading a ruleset that involve more than a single
53 call require a so-called
55 which prevents the occurrence of
56 multiple concurrent manipulations.
60 parameter structures that refer to packet data (like
61 addresses and ports) are generally expected in network byte-order.
63 Rules and address tables are contained in so-called
67 request, if the anchor field of the argument structure is empty,
68 the kernel will use the default anchor (i.e., the main ruleset)
70 Anchors are specified by name and may be nested, with components
73 characters, similar to how file system hierarchies are laid out.
74 The final component of the anchor path is the anchor under which
75 operations will be performed.
78 supports the following
80 commands, available through
82 .Bl -tag -width xxxxxx
84 Start the packet filter.
86 Stop the packet filter.
88 Start the ALTQ bandwidth control system (see
91 Stop the ALTQ bandwidth control system.
92 .It Dv DIOCBEGINADDRS Fa "struct pfioc_pooladdr *pp"
94 struct pfioc_pooladdr {
102 char anchor[MAXPATHLEN];
103 struct pf_pooladdr addr;
107 Clear the buffer address pool and get a
115 .It Dv DIOCADDADDR Fa "struct pfioc_pooladdr *pp"
119 to the buffer address pool to be used in the following
124 All other members of the structure are ignored.
125 .It Dv DIOCADDRULE Fa "struct pfioc_rule *pr"
130 u_int32_t pool_ticket;
132 char anchor[MAXPATHLEN];
133 char anchor_call[MAXPATHLEN];
140 at the end of the inactive ruleset.
143 obtained through a preceding
151 must also be called if any pool addresses are required.
154 name indicates the anchor in which to append the rule.
159 .It Dv DIOCADDALTQ Fa "struct pfioc_altq *pa"
160 Add an ALTQ discipline or queue.
169 .It Dv DIOCGETRULES Fa "struct pfioc_rule *pr"
176 of rules in the active ruleset.
177 .It Dv DIOCGETRULE Fa "struct pfioc_rule *pr"
184 obtained through a preceding
190 .Dv PF_GET_CLR_CNTR ,
191 the per-rule statistics on the requested rule are cleared.
192 .It Dv DIOCGETADDRS Fa "struct pfioc_pooladdr *pp"
199 of pool addresses in the rule specified with
204 .It Dv DIOCGETADDR Fa "struct pfioc_pooladdr *pp"
209 from the rule specified with
216 obtained through a preceding
219 .It Dv DIOCGETALTQS Fa "struct pfioc_altq *pa"
226 of queues in the active list.
227 .It Dv DIOCGETALTQ Fa "struct pfioc_altq *pa"
228 Get the queueing discipline
234 obtained through a preceding
237 .It Dv DIOCGETQSTATS Fa "struct pfioc_qstats *pq"
238 Get the statistics on a queue.
240 struct pfioc_qstats {
249 This call fills in a pointer to the buffer of statistics
253 for the queue specified by
255 .It Dv DIOCGETRULESETS Fa "struct pfioc_ruleset *pr"
257 struct pfioc_ruleset {
259 char path[MAXPATHLEN];
260 char name[PF_ANCHOR_NAME_SIZE];
266 of rulesets (i.e., anchors) directly attached to the anchor named by
268 for use in subsequent
271 Nested anchors, since they are not directly attached to the given
272 anchor, will not be included.
275 if the given anchor does not exist.
276 .It Dv DIOCGETRULESET Fa "struct pfioc_ruleset *pr"
277 Get a ruleset (i.e., an anchor)
281 from the given anchor
283 the maximum number of which can be obtained from a preceding
288 if the given anchor does not exist or
290 if another process is concurrently updating a ruleset.
291 .It Dv DIOCADDSTATE Fa "struct pfioc_state *ps"
295 struct pfsync_state state;
298 .It Dv DIOCGETSTATE Fa "struct pfioc_state *ps"
299 Extract the entry identified by the
305 structure from the state table.
306 .It Dv DIOCKILLSTATES Fa "struct pfioc_state_kill *psk"
307 Remove matching entries from the state table.
308 This ioctl returns the number of killed states in
311 struct pfioc_state_kill {
314 struct pf_rule_addr psk_src;
315 struct pf_rule_addr psk_dst;
316 char psk_ifname[IFNAMSIZ];
319 .It Dv DIOCCLRSTATES Fa "struct pfioc_state_kill *psk"
332 .It Dv DIOCSETSTATUSIF Fa "struct pfioc_if *pi"
333 Specify the interface for which statistics are accumulated.
336 char ifname[IFNAMSIZ];
339 .It Dv DIOCGETSTATUS Fa "struct pf_status *s"
340 Get the internal packet filter statistics.
343 u_int64_t counters[PFRES_MAX];
344 u_int64_t lcounters[LCNT_MAX];
345 u_int64_t fcounters[FCNT_MAX];
346 u_int64_t scounters[SCNT_MAX];
347 u_int64_t pcounters[2][2][3];
348 u_int64_t bcounters[2][2];
356 char ifname[IFNAMSIZ];
357 u_int8_t pf_chksum[MD5_DIGEST_LENGTH];
361 Clear the internal packet filter statistics.
362 .It Dv DIOCNATLOOK Fa "struct pfioc_natlook *pnl"
363 Look up a state table entry by source and destination addresses and ports.
365 struct pfioc_natlook {
366 struct pf_addr saddr;
367 struct pf_addr daddr;
368 struct pf_addr rsaddr;
369 struct pf_addr rdaddr;
379 .It Dv DIOCSETDEBUG Fa "u_int32_t *level"
382 enum { PF_DEBUG_NONE, PF_DEBUG_URGENT, PF_DEBUG_MISC,
385 .It Dv DIOCGETSTATES Fa "struct pfioc_states *ps"
386 Get state table entries.
388 struct pfioc_states {
392 struct pf_state *psu_states;
394 #define ps_buf ps_u.psu_buf
395 #define ps_states ps_u.psu_states
401 is non-zero on entry, as many states as possible that can fit into this
402 size will be copied into the supplied buffer
406 is always set to the total size required to hold all state table entries
408 .Li sizeof(struct pf_state) * nr ) .
409 .It Dv DIOCCHANGERULE Fa "struct pfioc_rule *pcr"
412 in the ruleset specified by
415 The type of operation to be performed is indicated by
417 which can be any of the following:
419 enum { PF_CHANGE_NONE, PF_CHANGE_ADD_HEAD, PF_CHANGE_ADD_TAIL,
420 PF_CHANGE_ADD_BEFORE, PF_CHANGE_ADD_AFTER,
421 PF_CHANGE_REMOVE, PF_CHANGE_GET_TICKET };
425 must be set to the value obtained with
426 .Dv PF_CHANGE_GET_TICKET
427 for all actions except
428 .Dv PF_CHANGE_GET_TICKET .
430 must be set to the value obtained with the
432 call for all actions except
435 .Dv PF_CHANGE_GET_TICKET .
437 indicates to which anchor the operation applies.
439 indicates the rule number against which
440 .Dv PF_CHANGE_ADD_BEFORE ,
441 .Dv PF_CHANGE_ADD_AFTER ,
445 .\" It Dv DIOCCHANGEALTQ Fa "struct pfioc_altq *pcr"
446 .It Dv DIOCCHANGEADDR Fa "struct pfioc_pooladdr *pca"
447 Add or remove the pool address
449 from the rule specified by
454 .It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm *pt"
462 Set the state timeout of
466 The old value will be placed into
468 For possible values of
474 .It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm *pt"
475 Get the state timeout of
477 The value will be placed into the
480 .It Dv DIOCCLRRULECTRS
481 Clear per-rule statistics.
482 .It Dv DIOCSETLIMIT Fa "struct pfioc_limit *pl"
483 Set the hard limits on the memory pools used by the packet filter.
490 enum { PF_LIMIT_STATES, PF_LIMIT_SRC_NODES, PF_LIMIT_FRAGS,
491 PF_LIMIT_TABLES, PF_LIMIT_TABLE_ENTRIES, PF_LIMIT_MAX };
493 .It Dv DIOCGETLIMIT Fa "struct pfioc_limit *pl"
496 for the memory pool indicated by
498 .It Dv DIOCRCLRTABLES Fa "struct pfioc_table *io"
500 All the ioctls that manipulate radix tables
501 use the same structure described below.
505 contains on exit the number of tables deleted.
508 struct pfr_table pfrio_table;
517 u_int32_t pfrio_ticket;
519 #define pfrio_exists pfrio_nadd
520 #define pfrio_nzero pfrio_nadd
521 #define pfrio_nmatch pfrio_nadd
522 #define pfrio_naddr pfrio_size2
523 #define pfrio_setflag pfrio_size2
524 #define pfrio_clrflag pfrio_nadd
526 .It Dv DIOCRADDTABLES Fa "struct pfioc_table *io"
527 Create one or more tables.
530 must point to an array of
537 .Vt struct pfr_table .
540 contains the number of tables effectively created.
543 char pfrt_anchor[MAXPATHLEN];
544 char pfrt_name[PF_TABLE_NAME_SIZE];
545 u_int32_t pfrt_flags;
549 .It Dv DIOCRDELTABLES Fa "struct pfioc_table *io"
550 Delete one or more tables.
553 must point to an array of
560 .Vt struct pfr_table .
563 contains the number of tables effectively deleted.
564 .It Dv DIOCRGETTABLES Fa "struct pfioc_table *io"
565 Get the list of all tables.
567 .Va pfrio_buffer[pfrio_size]
568 contains a valid writeable buffer for
573 contains the number of tables written into the buffer.
574 If the buffer is too small, the kernel does not store anything but just
575 returns the required buffer size, without error.
576 .It Dv DIOCRGETTSTATS Fa "struct pfioc_table *io"
579 but is used to get an array of
584 struct pfr_table pfrts_t;
585 u_int64_t pfrts_packets
586 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
587 u_int64_t pfrts_bytes
588 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
589 u_int64_t pfrts_match;
590 u_int64_t pfrts_nomatch;
593 int pfrts_refcnt[PFR_REFCNT_MAX];
595 #define pfrts_name pfrts_t.pfrt_name
596 #define pfrts_flags pfrts_t.pfrt_flags
598 .It Dv DIOCRCLRTSTATS Fa "struct pfioc_table *io"
599 Clear the statistics of one or more tables.
602 must point to an array of
609 .Vt struct pfr_table .
612 contains the number of tables effectively cleared.
613 .It Dv DIOCRCLRADDRS Fa "struct pfioc_table *io"
614 Clear all addresses in a table.
617 contains the table to clear.
620 contains the number of addresses removed.
621 .It Dv DIOCRADDADDRS Fa "struct pfioc_table *io"
622 Add one or more addresses to a table.
625 contains the table ID and
627 must point to an array of
631 elements to add to the table.
634 .Vt struct pfr_addr .
637 contains the number of addresses effectively added.
641 struct in_addr _pfra_ip4addr;
642 struct in6_addr _pfra_ip6addr;
649 #define pfra_ip4addr pfra_u._pfra_ip4addr
650 #define pfra_ip6addr pfra_u._pfra_ip6addr
652 .It Dv DIOCRDELADDRS Fa "struct pfioc_table *io"
653 Delete one or more addresses from a table.
656 contains the table ID and
658 must point to an array of
662 elements to delete from the table.
665 .Vt struct pfr_addr .
668 contains the number of addresses effectively deleted.
669 .It Dv DIOCRSETADDRS Fa "struct pfioc_table *io"
670 Replace the content of a table by a new address list.
671 This is the most complicated command, which uses all the structure members.
675 contains the table ID and
677 must point to an array of
681 elements which become the new contents of the table.
684 .Vt struct pfr_addr .
688 .Va pfrio_buffer[pfrio_size..pfrio_size2]
689 must be a writeable buffer, into which the kernel can copy the
690 addresses that have been deleted during the replace operation.
696 contain the number of addresses deleted, added, and changed by the
702 will point to the size of the buffer used, exactly like
704 .It Dv DIOCRGETADDRS Fa "struct pfioc_table *io"
705 Get all the addresses of a table.
708 contains the table ID and
709 .Va pfrio_buffer[pfrio_size]
710 contains a valid writeable buffer for
715 contains the number of addresses written into the buffer.
716 If the buffer was too small, the kernel does not store anything but just
717 returns the required buffer size, without returning an error.
718 .It Dv DIOCRGETASTATS Fa "struct pfioc_table *io"
721 but is used to get an array of
726 struct pfr_addr pfras_a;
727 u_int64_t pfras_packets
728 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
729 u_int64_t pfras_bytes
730 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
734 .It Dv DIOCRCLRASTATS Fa "struct pfioc_table *io"
735 Clear the statistics of one or more addresses.
738 contains the table ID and
740 must point to an array of
744 elements to be cleared from the table.
747 .Vt struct pfr_addr .
750 contains the number of addresses effectively cleared.
751 .It Dv DIOCRTSTADDRS Fa "struct pfioc_table *io"
752 Test if the given addresses match a table.
755 contains the table ID and
757 must point to an array of
761 elements, each of which will be tested for a match in the table.
764 .Vt struct pfr_addr .
765 On exit, the kernel updates the
769 member appropriately.
770 .It Dv DIOCRSETTFLAGS Fa "struct pfioc_table *io"
774 .Dv PFR_TFLAG_PERSIST
778 must point to an array of
785 .Vt struct pfr_table .
787 must contain the flags to add, while
789 must contain the flags to remove.
794 contain the number of tables altered or deleted by the kernel.
795 Yes, tables can be deleted if one removes the
796 .Dv PFR_TFLAG_PERSIST
797 flag of an unreferenced table.
798 .It Dv DIOCRINADEFINE Fa "struct pfioc_table *io"
799 Defines a table in the inactive set.
802 contains the table ID and
803 .Va pfrio_buffer[pfrio_size]
806 structures to put in the table.
807 A valid ticket must also be supplied to
811 contains 0 if the table was already defined in the inactive list
812 or 1 if a new table has been created.
814 contains the number of addresses effectively put in the table.
815 .It Dv DIOCXBEGIN Fa "struct pfioc_trans *io"
818 int size; /* number of elements */
819 int esize; /* size of each element in bytes */
820 struct pfioc_trans_e {
822 char anchor[MAXPATHLEN];
828 Clear all the inactive rulesets specified in the
831 For each ruleset, a ticket is returned for subsequent "add rule" ioctls,
838 Ruleset types, identified by
840 include the following:
842 .Bl -tag -width PF_RULESET_FILTER -offset ind -compact
843 .It Dv PF_RULESET_SCRUB
844 Scrub (packet normalization) rules.
845 .It Dv PF_RULESET_FILTER
847 .It Dv PF_RULESET_NAT
848 NAT (Network Address Translation) rules.
849 .It Dv PF_RULESET_BINAT
850 Bidirectional NAT rules.
851 .It Dv PF_RULESET_RDR
853 .It Dv PF_RULESET_ALTQ
855 .It Dv PF_RULESET_TABLE
858 .It Dv DIOCXCOMMIT Fa "struct pfioc_trans *io"
859 Atomically switch a vector of inactive rulesets to the active rulesets.
860 This call is implemented as a standard two-phase commit, which will either
861 fail for all rulesets or completely succeed.
862 All tickets need to be valid.
865 if another process is concurrently updating some of the same rulesets.
866 .It Dv DIOCXROLLBACK Fa "struct pfioc_trans *io"
867 Clean up the kernel by undoing all changes that have taken place on the
868 inactive rulesets since the last
871 will silently ignore rulesets for which the ticket is invalid.
872 .It Dv DIOCSETHOSTID Fa "u_int32_t *hostid"
873 Set the host ID, which is used by
875 to identify which host created state table entries.
877 Flush the passive OS fingerprint table.
878 .It Dv DIOCOSFPADD Fa "struct pf_osfp_ioctl *io"
880 struct pf_osfp_ioctl {
881 struct pf_osfp_entry {
882 SLIST_ENTRY(pf_osfp_entry) fp_entry;
884 char fp_class_nm[PF_OSFP_LEN];
885 char fp_version_nm[PF_OSFP_LEN];
886 char fp_subtype_nm[PF_OSFP_LEN];
888 pf_tcpopts_t fp_tcpopts;
900 Add a passive OS fingerprint to the table.
903 to the packed fingerprint,
904 .Va fp_os.fp_class_nm
905 to the name of the class (Linux, Windows, etc),
906 .Va fp_os.fp_version_nm
907 to the name of the version (NT, 95, 98), and
908 .Va fp_os.fp_subtype_nm
909 to the name of the subtype or patchlevel.
918 are set to the TCP MSS, the TCP window size, the IP length, the IP TTL,
919 the number of TCP options, and the TCP window scaling constant of the
920 TCP SYN packet, respectively.
924 member is filled according to the
931 member contains packed TCP options.
933 .Dv PF_OSFP_TCPOPT_BITS
934 bits in the packed value.
935 Options include any of
936 .Dv PF_OSFP_TCPOPT_NOP ,
937 .Dv PF_OSFP_TCPOPT_SACK ,
938 .Dv PF_OSFP_TCPOPT_WSCALE ,
939 .Dv PF_OSFP_TCPOPT_MSS ,
941 .Dv PF_OSFP_TCPOPT_TS .
945 member is not used with this ioctl.
947 The structure's slack space must be zeroed for correct operation;
949 the whole structure to zero before filling and sending to the kernel.
950 .It Dv DIOCOSFPGET Fa "struct pf_osfp_ioctl *io"
951 Get the passive OS fingerprint number
953 from the kernel's fingerprint list.
954 The rest of the structure members will come back filled.
955 Get the whole list by repeatedly incrementing the
957 number until the ioctl returns
959 .It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes *psn"
961 struct pfioc_src_nodes {
965 struct pf_src_node *psu_src_nodes;
967 #define psn_buf psn_u.psu_buf
968 #define psn_src_nodes psn_u.psu_src_nodes
972 Get the list of source nodes kept by sticky addresses and source
974 The ioctl must be called once with
977 If the ioctl returns without error,
979 will be set to the size of the buffer required to hold all the
981 structures held in the table.
982 A buffer of this size should then be allocated, and a pointer to this buffer
985 The ioctl must then be called again to fill this buffer with the actual
989 will be set to the length of the buffer actually used.
990 .It Dv DIOCCLRSRCNODES
991 Clear the tree of source tracking nodes.
992 .It Dv DIOCIGETIFACES Fa "struct pfioc_iface *io"
993 Get the list of interfaces and interface drivers known to
995 All the ioctls that manipulate interfaces
996 use the same structure described below:
999 char pfiio_name[IFNAMSIZ];
1010 can be used to restrict the search to a specific interface or driver.
1011 .Va pfiio_buffer[pfiio_size]
1012 is the user-supplied buffer for returning the data.
1015 contains the number of
1017 entries that can fit into the buffer.
1018 The kernel will replace this value by the real number of entries it wants
1022 .Li sizeof(struct pfi_kif) .
1024 The data is returned in the
1026 structure described below:
1029 RB_ENTRY(pfi_kif) pfik_tree;
1030 char pfik_name[IFNAMSIZ];
1031 u_int64_t pfik_packets[2][2][2];
1032 u_int64_t pfik_bytes[2][2][2];
1033 u_int32_t pfik_tzero;
1035 struct pf_state_tree_lan_ext pfik_lan_ext;
1036 struct pf_state_tree_ext_gwy pfik_ext_gwy;
1037 TAILQ_ENTRY(pfi_kif) pfik_w_states;
1038 void *pfik_ah_cookie;
1039 struct ifnet *pfik_ifp;
1040 struct ifg_group *pfik_group;
1043 TAILQ_HEAD(, pfi_dynaddr) pfik_dynaddrs;
1046 .It Dv DIOCSETIFFLAG Fa "struct pfioc_iface *io"
1047 Set the user settable flags (described above) of the
1049 internal interface description.
1050 The filtering process is the same as for
1051 .Dv DIOCIGETIFACES .
1053 #define PFI_IFLAG_SKIP 0x0100 /* skip filtering on interface */
1055 .It Dv DIOCCLRIFFLAG Fa "struct pfioc_iface *io"
1058 above but clears the flags.
1061 .Bl -tag -width /dev/pf -compact
1063 packet filtering device.
1066 The following example demonstrates how to use the
1068 command to find the internal host/port of a NATed connection:
1070 #include <sys/types.h>
1071 #include <sys/socket.h>
1072 #include <sys/ioctl.h>
1073 #include <sys/fcntl.h>
1075 #include <netinet/in.h>
1076 #include <net/pfvar.h>
1082 read_address(const char *s)
1086 sscanf(s, "%i.%i.%i.%i", &a, &b, &c, &d);
1087 return htonl(a << 24 | b << 16 | c << 8 | d);
1091 print_address(u_int32_t a)
1094 printf("%d.%d.%d.%d", a >> 24 & 255, a >> 16 & 255,
1095 a >> 8 & 255, a & 255);
1099 main(int argc, char *argv[])
1101 struct pfioc_natlook nl;
1105 printf("%s <gwy addr> <gwy port> <ext addr> <ext port>\\n",
1110 dev = open("/dev/pf", O_RDWR);
1112 err(1, "open(\\"/dev/pf\\") failed");
1114 memset(&nl, 0, sizeof(struct pfioc_natlook));
1115 nl.saddr.v4.s_addr = read_address(argv[1]);
1116 nl.sport = htons(atoi(argv[2]));
1117 nl.daddr.v4.s_addr = read_address(argv[3]);
1118 nl.dport = htons(atoi(argv[4]));
1120 nl.proto = IPPROTO_TCP;
1121 nl.direction = PF_IN;
1123 if (ioctl(dev, DIOCNATLOOK, &nl))
1124 err(1, "DIOCNATLOOK");
1126 printf("internal host ");
1127 print_address(nl.rsaddr.v4.s_addr);
1128 printf(":%u\\n", ntohs(nl.rsport));
1142 packet filtering mechanism first appeared in
1144 and was imported into
1146 by Devon H. O'Dell and Simon Schubert.