1 .\" $OpenBSD: pf.4,v 1.58 2007/02/09 11:39:06 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
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
55 call require a so-called
57 which prevents the occurrence of
58 multiple concurrent manipulations.
62 parameter structures that refer to packet data (like
63 addresses and ports) are generally expected in network byte-order.
65 Rules and address tables are contained in so-called
69 request, if the anchor field of the argument structure is empty,
70 the kernel will use the default anchor (i.e., the main ruleset)
72 Anchors are specified by name and may be nested, with components
75 characters, similar to how file system hierarchies are laid out.
76 The final component of the anchor path is the anchor under which
77 operations will be performed.
80 supports the following
82 commands, available through
84 .Bl -tag -width xxxxxx
86 Start the packet filter.
88 Stop the packet filter.
90 Start the ALTQ bandwidth control system (see
93 Stop the ALTQ bandwidth control system.
94 .It Dv DIOCBEGINADDRS Fa "struct pfioc_pooladdr *pp"
96 struct pfioc_pooladdr {
104 char anchor[MAXPATHLEN];
105 struct pf_pooladdr addr;
109 Clear the buffer address pool and get a
117 .It Dv DIOCADDADDR Fa "struct pfioc_pooladdr *pp"
121 to the buffer address pool to be used in the following
126 All other members of the structure are ignored.
127 .It Dv DIOCADDRULE Fa "struct pfioc_rule *pr"
132 u_int32_t pool_ticket;
134 char anchor[MAXPATHLEN];
135 char anchor_call[MAXPATHLEN];
142 at the end of the inactive ruleset.
145 obtained through a preceding
153 must also be called if any pool addresses are required.
156 name indicates the anchor in which to append the rule.
161 .It Dv DIOCADDALTQ Fa "struct pfioc_altq *pa"
162 Add an ALTQ discipline or queue.
171 .It Dv DIOCGETRULES Fa "struct pfioc_rule *pr"
178 of rules in the active ruleset.
179 .It Dv DIOCGETRULE Fa "struct pfioc_rule *pr"
186 obtained through a preceding
192 .Dv PF_GET_CLR_CNTR ,
193 the per-rule statistics on the requested rule are cleared.
194 .It Dv DIOCGETADDRS Fa "struct pfioc_pooladdr *pp"
201 of pool addresses in the rule specified with
206 .It Dv DIOCGETADDR Fa "struct pfioc_pooladdr *pp"
211 from the rule specified with
218 obtained through a preceding
221 .It Dv DIOCGETALTQS Fa "struct pfioc_altq *pa"
228 of queues in the active list.
229 .It Dv DIOCGETALTQ Fa "struct pfioc_altq *pa"
230 Get the queueing discipline
236 obtained through a preceding
239 .It Dv DIOCGETQSTATS Fa "struct pfioc_qstats *pq"
240 Get the statistics on a queue.
242 struct pfioc_qstats {
251 This call fills in a pointer to the buffer of statistics
255 for the queue specified by
257 .It Dv DIOCGETRULESETS Fa "struct pfioc_ruleset *pr"
259 struct pfioc_ruleset {
261 char path[MAXPATHLEN];
262 char name[PF_ANCHOR_NAME_SIZE];
268 of rulesets (i.e., anchors) directly attached to the anchor named by
270 for use in subsequent
273 Nested anchors, since they are not directly attached to the given
274 anchor, will not be included.
277 if the given anchor does not exist.
278 .It Dv DIOCGETRULESET Fa "struct pfioc_ruleset *pr"
279 Get a ruleset (i.e., an anchor)
283 from the given anchor
285 the maximum number of which can be obtained from a preceding
290 if the given anchor does not exist or
292 if another process is concurrently updating a ruleset.
293 .It Dv DIOCADDSTATE Fa "struct pfioc_state *ps"
298 struct pf_state state;
301 .It Dv DIOCGETSTATE Fa "struct pfioc_state *ps"
302 Extract the entry with the specified number
304 from the state table.
305 .It Dv DIOCKILLSTATES Fa "struct pfioc_state_kill *psk"
306 Remove matching entries from the state table.
307 This ioctl returns the number of killed states in
310 struct pfioc_state_kill {
313 struct pf_rule_addr psk_src;
314 struct pf_rule_addr psk_dst;
315 char psk_ifname[IFNAMSIZ];
318 .It Dv DIOCCLRSTATES Fa "struct pfioc_state_kill *psk"
331 .It Dv DIOCSETSTATUSIF Fa "struct pfioc_if *pi"
332 Specify the interface for which statistics are accumulated.
335 char ifname[IFNAMSIZ];
338 .It Dv DIOCGETSTATUS Fa "struct pf_status *s"
339 Get the internal packet filter statistics.
342 u_int64_t counters[PFRES_MAX];
343 u_int64_t lcounters[LCNT_MAX];
344 u_int64_t fcounters[FCNT_MAX];
345 u_int64_t scounters[SCNT_MAX];
346 u_int64_t pcounters[2][2][3];
347 u_int64_t bcounters[2][2];
355 char ifname[IFNAMSIZ];
356 u_int8_t pf_chksum[MD5_DIGEST_LENGTH];
360 Clear the internal packet filter statistics.
361 .It Dv DIOCNATLOOK Fa "struct pfioc_natlook *pnl"
362 Look up a state table entry by source and destination addresses and ports.
364 struct pfioc_natlook {
365 struct pf_addr saddr;
366 struct pf_addr daddr;
367 struct pf_addr rsaddr;
368 struct pf_addr rdaddr;
378 .It Dv DIOCSETDEBUG Fa "u_int32_t *level"
381 enum { PF_DEBUG_NONE, PF_DEBUG_URGENT, PF_DEBUG_MISC,
384 .It Dv DIOCGETSTATES Fa "struct pfioc_states *ps"
385 Get state table entries.
387 struct pfioc_states {
391 struct pf_state *psu_states;
393 #define ps_buf ps_u.psu_buf
394 #define ps_states ps_u.psu_states
400 is non-zero on entry, as many states as possible that can fit into this
401 size will be copied into the supplied buffer
405 is always set to the total size required to hold all state table entries
407 .Li sizeof(struct pf_state) * nr ) .
408 .It Dv DIOCCHANGERULE Fa "struct pfioc_rule *pcr"
411 in the ruleset specified by
414 The type of operation to be performed is indicated by
416 which can be any of the following:
418 enum { PF_CHANGE_NONE, PF_CHANGE_ADD_HEAD, PF_CHANGE_ADD_TAIL,
419 PF_CHANGE_ADD_BEFORE, PF_CHANGE_ADD_AFTER,
420 PF_CHANGE_REMOVE, PF_CHANGE_GET_TICKET };
424 must be set to the value obtained with
425 .Dv PF_CHANGE_GET_TICKET
426 for all actions except
427 .Dv PF_CHANGE_GET_TICKET .
429 must be set to the value obtained with the
431 call for all actions except
434 .Dv PF_CHANGE_GET_TICKET .
436 indicates to which anchor the operation applies.
438 indicates the rule number against which
439 .Dv PF_CHANGE_ADD_BEFORE ,
440 .Dv PF_CHANGE_ADD_AFTER ,
444 .\" It Dv DIOCCHANGEALTQ Fa "struct pfioc_altq *pcr"
445 .It Dv DIOCCHANGEADDR Fa "struct pfioc_pooladdr *pca"
446 Add or remove the pool address
448 from the rule specified by
453 .It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm *pt"
461 Set the state timeout of
465 The old value will be placed into
467 For possible values of
473 .It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm *pt"
474 Get the state timeout of
476 The value will be placed into the
479 .It Dv DIOCCLRRULECTRS
480 Clear per-rule statistics.
481 .It Dv DIOCSETLIMIT Fa "struct pfioc_limit *pl"
482 Set the hard limits on the memory pools used by the packet filter.
489 enum { PF_LIMIT_STATES, PF_LIMIT_SRC_NODES, PF_LIMIT_FRAGS,
490 PF_LIMIT_TABLES, PF_LIMIT_TABLE_ENTRIES, PF_LIMIT_MAX };
492 .It Dv DIOCGETLIMIT Fa "struct pfioc_limit *pl"
495 for the memory pool indicated by
497 .It Dv DIOCRCLRTABLES Fa "struct pfioc_table *io"
499 All the ioctls that manipulate radix tables
500 use the same structure described below.
504 contains on exit the number of tables deleted.
507 struct pfr_table pfrio_table;
516 u_int32_t pfrio_ticket;
518 #define pfrio_exists pfrio_nadd
519 #define pfrio_nzero pfrio_nadd
520 #define pfrio_nmatch pfrio_nadd
521 #define pfrio_naddr pfrio_size2
522 #define pfrio_setflag pfrio_size2
523 #define pfrio_clrflag pfrio_nadd
525 .It Dv DIOCRADDTABLES Fa "struct pfioc_table *io"
526 Create one or more tables.
529 must point to an array of
536 .Vt struct pfr_table .
539 contains the number of tables effectively created.
542 char pfrt_anchor[MAXPATHLEN];
543 char pfrt_name[PF_TABLE_NAME_SIZE];
544 u_int32_t pfrt_flags;
548 .It Dv DIOCRDELTABLES Fa "struct pfioc_table *io"
549 Delete one or more tables.
552 must point to an array of
559 .Vt struct pfr_table .
562 contains the number of tables effectively deleted.
563 .It Dv DIOCRGETTABLES Fa "struct pfioc_table *io"
564 Get the list of all tables.
566 .Va pfrio_buffer[pfrio_size]
567 contains a valid writeable buffer for
572 contains the number of tables written into the buffer.
573 If the buffer is too small, the kernel does not store anything but just
574 returns the required buffer size, without error.
575 .It Dv DIOCRGETTSTATS Fa "struct pfioc_table *io"
578 but is used to get an array of
583 struct pfr_table pfrts_t;
584 u_int64_t pfrts_packets
585 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
586 u_int64_t pfrts_bytes
587 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
588 u_int64_t pfrts_match;
589 u_int64_t pfrts_nomatch;
592 int pfrts_refcnt[PFR_REFCNT_MAX];
594 #define pfrts_name pfrts_t.pfrt_name
595 #define pfrts_flags pfrts_t.pfrt_flags
597 .It Dv DIOCRCLRTSTATS Fa "struct pfioc_table *io"
598 Clear the statistics of one or more tables.
601 must point to an array of
608 .Vt struct pfr_table .
611 contains the number of tables effectively cleared.
612 .It Dv DIOCRCLRADDRS Fa "struct pfioc_table *io"
613 Clear all addresses in a table.
616 contains the table to clear.
619 contains the number of addresses removed.
620 .It Dv DIOCRADDADDRS Fa "struct pfioc_table *io"
621 Add one or more addresses to a table.
624 contains the table ID and
626 must point to an array of
630 elements to add to the table.
633 .Vt struct pfr_addr .
636 contains the number of addresses effectively added.
640 struct in_addr _pfra_ip4addr;
641 struct in6_addr _pfra_ip6addr;
648 #define pfra_ip4addr pfra_u._pfra_ip4addr
649 #define pfra_ip6addr pfra_u._pfra_ip6addr
651 .It Dv DIOCRDELADDRS Fa "struct pfioc_table *io"
652 Delete one or more addresses from a table.
655 contains the table ID and
657 must point to an array of
661 elements to delete from the table.
664 .Vt struct pfr_addr .
667 contains the number of addresses effectively deleted.
668 .It Dv DIOCRSETADDRS Fa "struct pfioc_table *io"
669 Replace the content of a table by a new address list.
670 This is the most complicated command, which uses all the structure members.
674 contains the table ID and
676 must point to an array of
680 elements which become the new contents of the table.
683 .Vt struct pfr_addr .
687 .Va pfrio_buffer[pfrio_size..pfrio_size2]
688 must be a writeable buffer, into which the kernel can copy the
689 addresses that have been deleted during the replace operation.
695 contain the number of addresses deleted, added, and changed by the
701 will point to the size of the buffer used, exactly like
703 .It Dv DIOCRGETADDRS Fa "struct pfioc_table *io"
704 Get all the addresses of a table.
707 contains the table ID and
708 .Va pfrio_buffer[pfrio_size]
709 contains a valid writeable buffer for
714 contains the number of addresses written into the buffer.
715 If the buffer was too small, the kernel does not store anything but just
716 returns the required buffer size, without returning an error.
717 .It Dv DIOCRGETASTATS Fa "struct pfioc_table *io"
720 but is used to get an array of
725 struct pfr_addr pfras_a;
726 u_int64_t pfras_packets
727 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
728 u_int64_t pfras_bytes
729 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
733 .It Dv DIOCRCLRASTATS Fa "struct pfioc_table *io"
734 Clear the statistics of one or more addresses.
737 contains the table ID and
739 must point to an array of
743 elements to be cleared from the table.
746 .Vt struct pfr_addr .
749 contains the number of addresses effectively cleared.
750 .It Dv DIOCRTSTADDRS Fa "struct pfioc_table *io"
751 Test if the given addresses match a table.
754 contains the table ID and
756 must point to an array of
760 elements, each of which will be tested for a match in the table.
763 .Vt struct pfr_addr .
764 On exit, the kernel updates the
768 member appropriately.
769 .It Dv DIOCRSETTFLAGS Fa "struct pfioc_table *io"
773 .Dv PFR_TFLAG_PERSIST
777 must point to an array of
784 .Vt struct pfr_table .
786 must contain the flags to add, while
788 must contain the flags to remove.
793 contain the number of tables altered or deleted by the kernel.
794 Yes, tables can be deleted if one removes the
795 .Dv PFR_TFLAG_PERSIST
796 flag of an unreferenced table.
797 .It Dv DIOCRINADEFINE Fa "struct pfioc_table *io"
798 Defines a table in the inactive set.
801 contains the table ID and
802 .Va pfrio_buffer[pfrio_size]
805 structures to put in the table.
806 A valid ticket must also be supplied to
810 contains 0 if the table was already defined in the inactive list
811 or 1 if a new table has been created.
813 contains the number of addresses effectively put in the table.
814 .It Dv DIOCXBEGIN Fa "struct pfioc_trans *io"
817 int size; /* number of elements */
818 int esize; /* size of each element in bytes */
819 struct pfioc_trans_e {
821 char anchor[MAXPATHLEN];
827 Clear all the inactive rulesets specified in the
830 For each ruleset, a ticket is returned for subsequent "add rule" ioctls,
837 Ruleset types, identified by
839 include the following:
841 .Bl -tag -width PF_RULESET_FILTER -offset ind -compact
842 .It Dv PF_RULESET_SCRUB
843 Scrub (packet normalization) rules.
844 .It Dv PF_RULESET_FILTER
846 .It Dv PF_RULESET_NAT
847 NAT (Network Address Translation) rules.
848 .It Dv PF_RULESET_BINAT
849 Bidirectional NAT rules.
850 .It Dv PF_RULESET_RDR
852 .It Dv PF_RULESET_ALTQ
854 .It Dv PF_RULESET_TABLE
857 .It Dv DIOCXCOMMIT Fa "struct pfioc_trans *io"
858 Atomically switch a vector of inactive rulesets to the active rulesets.
859 This call is implemented as a standard two-phase commit, which will either
860 fail for all rulesets or completely succeed.
861 All tickets need to be valid.
864 if another process is concurrently updating some of the same rulesets.
865 .It Dv DIOCXROLLBACK Fa "struct pfioc_trans *io"
866 Clean up the kernel by undoing all changes that have taken place on the
867 inactive rulesets since the last
870 will silently ignore rulesets for which the ticket is invalid.
871 .It Dv DIOCSETHOSTID Fa "u_int32_t *hostid"
872 Set the host ID, which is used by
874 to identify which host created state table entries.
876 Flush the passive OS fingerprint table.
877 .It Dv DIOCOSFPADD Fa "struct pf_osfp_ioctl *io"
879 struct pf_osfp_ioctl {
880 struct pf_osfp_entry {
881 SLIST_ENTRY(pf_osfp_entry) fp_entry;
883 char fp_class_nm[PF_OSFP_LEN];
884 char fp_version_nm[PF_OSFP_LEN];
885 char fp_subtype_nm[PF_OSFP_LEN];
887 pf_tcpopts_t fp_tcpopts;
899 Add a passive OS fingerprint to the table.
902 to the packed fingerprint,
903 .Va fp_os.fp_class_nm
904 to the name of the class (Linux, Windows, etc),
905 .Va fp_os.fp_version_nm
906 to the name of the version (NT, 95, 98), and
907 .Va fp_os.fp_subtype_nm
908 to the name of the subtype or patchlevel.
917 are set to the TCP MSS, the TCP window size, the IP length, the IP TTL,
918 the number of TCP options, and the TCP window scaling constant of the
919 TCP SYN packet, respectively.
923 member is filled according to the
930 member contains packed TCP options.
932 .Dv PF_OSFP_TCPOPT_BITS
933 bits in the packed value.
934 Options include any of
935 .Dv PF_OSFP_TCPOPT_NOP ,
936 .Dv PF_OSFP_TCPOPT_SACK ,
937 .Dv PF_OSFP_TCPOPT_WSCALE ,
938 .Dv PF_OSFP_TCPOPT_MSS ,
940 .Dv PF_OSFP_TCPOPT_TS .
944 member is not used with this ioctl.
946 The structure's slack space must be zeroed for correct operation;
948 the whole structure to zero before filling and sending to the kernel.
949 .It Dv DIOCOSFPGET Fa "struct pf_osfp_ioctl *io"
950 Get the passive OS fingerprint number
952 from the kernel's fingerprint list.
953 The rest of the structure members will come back filled.
954 Get the whole list by repeatedly incrementing the
956 number until the ioctl returns
958 .It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes *psn"
960 struct pfioc_src_nodes {
964 struct pf_src_node *psu_src_nodes;
966 #define psn_buf psn_u.psu_buf
967 #define psn_src_nodes psn_u.psu_src_nodes
971 Get the list of source nodes kept by sticky addresses and source
973 The ioctl must be called once with
976 If the ioctl returns without error,
978 will be set to the size of the buffer required to hold all the
980 structures held in the table.
981 A buffer of this size should then be allocated, and a pointer to this buffer
984 The ioctl must then be called again to fill this buffer with the actual
988 will be set to the length of the buffer actually used.
989 .It Dv DIOCCLRSRCNODES
990 Clear the tree of source tracking nodes.
991 .It Dv DIOCIGETIFACES Fa "struct pfioc_iface *io"
992 Get the list of interfaces and interface drivers known to
994 All the ioctls that manipulate interfaces
995 use the same structure described below:
998 char pfiio_name[IFNAMSIZ];
1009 can be used to restrict the search to a specific interface or driver.
1010 .Va pfiio_buffer[pfiio_size]
1011 is the user-supplied buffer for returning the data.
1014 contains the number of
1016 entries that can fit into the buffer.
1017 The kernel will replace this value by the real number of entries it wants
1021 .Li sizeof(struct pfi_kif) .
1023 The data is returned in the
1025 structure described below:
1028 RB_ENTRY(pfi_kif) pfik_tree;
1029 char pfik_name[IFNAMSIZ];
1030 u_int64_t pfik_packets[2][2][2];
1031 u_int64_t pfik_bytes[2][2][2];
1032 u_int32_t pfik_tzero;
1034 struct pf_state_tree_lan_ext pfik_lan_ext;
1035 struct pf_state_tree_ext_gwy pfik_ext_gwy;
1036 TAILQ_ENTRY(pfi_kif) pfik_w_states;
1037 void *pfik_ah_cookie;
1038 struct ifnet *pfik_ifp;
1039 struct ifg_group *pfik_group;
1042 TAILQ_HEAD(, pfi_dynaddr) pfik_dynaddrs;
1045 .It Dv DIOCSETIFFLAG Fa "struct pfioc_iface *io"
1046 Set the user setable flags (described above) of the
1048 internal interface description.
1049 The filtering process is the same as for
1050 .Dv DIOCIGETIFACES .
1052 #define PFI_IFLAG_SKIP 0x0100 /* skip filtering on interface */
1054 .It Dv DIOCCLRIFFLAG Fa "struct pfioc_iface *io"
1057 above but clears the flags.
1060 .Bl -tag -width /dev/pf -compact
1062 packet filtering device.
1065 The following example demonstrates how to use the
1067 command to find the internal host/port of a NATed connection:
1069 #include <sys/types.h>
1070 #include <sys/socket.h>
1071 #include <sys/ioctl.h>
1072 #include <sys/fcntl.h>
1074 #include <netinet/in.h>
1075 #include <net/pfvar.h>
1081 read_address(const char *s)
1085 sscanf(s, "%i.%i.%i.%i", &a, &b, &c, &d);
1086 return htonl(a << 24 | b << 16 | c << 8 | d);
1090 print_address(u_int32_t a)
1093 printf("%d.%d.%d.%d", a >> 24 & 255, a >> 16 & 255,
1094 a >> 8 & 255, a & 255);
1098 main(int argc, char *argv[])
1100 struct pfioc_natlook nl;
1104 printf("%s <gwy addr> <gwy port> <ext addr> <ext port>\\n",
1109 dev = open("/dev/pf", O_RDWR);
1111 err(1, "open(\\"/dev/pf\\") failed");
1113 memset(&nl, 0, sizeof(struct pfioc_natlook));
1114 nl.saddr.v4.s_addr = read_address(argv[1]);
1115 nl.sport = htons(atoi(argv[2]));
1116 nl.daddr.v4.s_addr = read_address(argv[3]);
1117 nl.dport = htons(atoi(argv[4]));
1119 nl.proto = IPPROTO_TCP;
1120 nl.direction = PF_IN;
1122 if (ioctl(dev, DIOCNATLOOK, &nl))
1123 err(1, "DIOCNATLOOK");
1125 printf("internal host ");
1126 print_address(nl.rsaddr.v4.s_addr);
1127 printf(":%u\\n", ntohs(nl.rsport));
1142 packet filtering mechanism first appeared in