1 .\" $OpenBSD: pf.4,v 1.46 2004/02/19 21:29:51 cedric Exp $
2 .\" $DragonFly: src/share/man/man4/pf.4,v 1.4 2006/10/15 01:46:23 swildner Exp $
4 .\" Copyright (C) 2001, Kjell Wooding. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the project nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
39 Packet filtering takes place in the kernel.
42 allows userland processes to control the
43 behavior of the packet filter through an
46 There are commands to enable and disable the filter, load rulesets,
47 add and remove individual rules or state table entries,
48 and retrieve statistics.
49 The most commonly used functions are covered by
52 Manipulations like loading a ruleset that involve more than a single
53 ioctl call require a so-called ticket, which prevents the occurrence of
54 multiple concurrent manipulations.
56 Fields of ioctl parameter structures that refer to packet data (like
57 addresses and ports) are generally expected in network byte-order.
59 .Bl -tag -width /dev/pf -compact
61 packet filtering device.
64 pf supports the following
67 .Bl -tag -width xxxxxx
69 Starts the packet filter.
71 Stops the packet filter.
73 Starts the ALTQ bandwidth control system.
75 Stops the ALTQ bandwidth control system.
76 .It Dv DIOCBEGINADDRS Fa "struct pfioc_pooladdr"
78 struct pfioc_pooladdr {
86 char anchor[PF_ANCHOR_NAME_SIZE];
87 char ruleset[PF_RULESET_NAME_SIZE];
88 struct pf_pooladdr addr;
92 Clears the buffer address pool
95 for subsequent DIOCADDADDR, DIOCADDRULE and DIOCCHANGERULE calls.
96 .It Dv DIOCADDADDR Fa "struct pfioc_pooladdr"
100 to the buffer address pool to be used in the following
101 DIOCADDRULE or DIOCCHANGERULE call.
102 All other members of the structure are ignored.
103 .It Dv DIOCADDRULE Fa "struct pfioc_rule"
108 u_int32_t pool_ticket;
110 char anchor[PF_ANCHOR_NAME_SIZE];
111 char ruleset[PF_RULESET_NAME_SIZE];
118 at the end of the inactive ruleset.
121 obtained through preceding DIOCXBEGIN call, and
123 obtained through DIOCBEGINADDRS call.
124 DIOCADDADDR must also be called if any pool addresses are required.
129 names indicate the anchor and ruleset in which to append the rule.
134 .It Dv DIOCADDALTQ Fa "struct pfioc_altq"
144 .It Dv DIOCGETRULES Fa "struct pfioc_rule"
147 for subsequent DIOCGETRULE calls and
149 of rules in the active ruleset.
150 .It Dv DIOCGETRULE Fa "struct pfioc_rule"
157 obtained through a preceding DIOCGETRULES call.
158 .It Dv DIOCGETADDRS Fa "struct pfioc_pooladdr"
161 for subsequent DIOCGETADDR calls and
163 of pool addresses in the rule specified with
169 .It Dv DIOCGETADDR Fa "struct pfioc_pooladdr"
174 from the rule specified with
182 obtained through a preceding DIOCGETADDRS call.
183 .It Dv DIOCGETALTQS Fa "struct pfioc_altq"
186 for subsequent DIOCGETALTQ calls and
188 of queues in the active list.
189 .It Dv DIOCGETALTQ Fa "struct pfioc_altq"
196 obtained through a preceding DIOCGETALTQS call.
197 .It Dv DIOCGETQSTATS Fa "struct pfioc_qstats"
198 Returns statistics on a queue.
200 struct pfioc_qstats {
209 A pointer to a buffer of statistics
213 for the queue specified by
215 .It Dv DIOCADDSTATE Fa "struct pfioc_state"
217 .It Dv DIOCGETSTATE Fa "struct pfioc_state"
221 struct pf_state state;
225 Extracts the entry with the specified number from the state table.
226 .It Dv DIOCKILLSTATES Fa "struct pfioc_state_kill"
227 Removes matching entries from the state table.
228 Returns the number of killed states in psk_af.
230 struct pfioc_state_kill {
233 struct pf_rule_addr psk_src;
234 struct pf_rule_addr psk_dst;
235 char psk_ifname[IFNAMSIZ];
238 .It Dv DIOCCLRSTATES Fa "struct pfioc_state_kill"
242 but ignores the psk_af, psk_proto, psk_src and psk_dst fields of the
245 .It Dv DIOCSETSTATUSIF Fa "struct pfioc_if"
248 char ifname[IFNAMSIZ];
252 Specifies the interface for which statistics are accumulated.
253 .It Dv DIOCGETSTATUS Fa "struct pf_status"
256 u_int64_t counters[PFRES_MAX];
257 u_int64_t fcounters[FCNT_MAX];
258 u_int64_t scounters[SCNT_MAX];
259 u_int64_t pcounters[2][2][3];
260 u_int64_t bcounters[2][2];
266 char ifname[IFNAMSIZ];
270 Gets the internal packet filter statistics.
272 Clears the internal packet filter statistics.
273 .It Dv DIOCNATLOOK Fa "struct pfioc_natlook"
274 Looks up a state table entry by source and destination addresses and ports.
276 struct pfioc_natlook {
277 struct pf_addr saddr;
278 struct pf_addr daddr;
279 struct pf_addr rsaddr;
280 struct pf_addr rdaddr;
290 .It Dv DIOCSETDEBUG Fa "u_int32_t"
291 Sets the debug level.
293 enum { PF_DEBUG_NONE=0, PF_DEBUG_URGENT=1, PF_DEBUG_MISC=2 };
295 .It Dv DIOCGETSTATES Fa "struct pfioc_states"
297 struct pfioc_states {
301 struct pf_state *psu_states;
303 #define ps_buf ps_u.psu_buf
304 #define ps_states ps_u.psu_states
307 .It Dv DIOCCHANGERULE Fa "struct pfioc_rule"
310 in the ruleset specified by
313 enum { PF_CHANGE_ADD_HEAD=1, PF_CHANGE_ADD_TAIL=2,
314 PF_CHANGE_ADD_BEFORE=3, PF_CHANGE_ADD_AFTER=4,
315 PF_CHANGE_REMOVE=5, PF_CHANGE_GET_TICKET=6 };
318 The type of operation to be performed is indicated by
322 must be set to the value obtained with PF_CHANGE_GET_TICKET
323 for all actions except PF_CHANGE_GET_TICKET.
325 must be set to the value obtained with the DIOCBEGINADDRS call
326 for all actions except PF_CHANGE_REMOVE and PF_CHANGE_GET_TICKET.
331 indicate which anchor and ruleset the operation applies to.
333 indicates the rule number against which PF_CHANGE_ADD_BEFORE,
334 PF_CHANGE_ADD_AFTER or PF_CHANGE_REMOVE actions are applied.
335 .It Dv DIOCCHANGEADDR Fa "struct pfioc_pooladdr"
336 Adds or removes a pool address
338 from a rule specified with
344 .It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm"
351 .It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm"
352 .It Dv DIOCCLRRULECTRS
353 Clear per-rule statistics.
354 .It Dv DIOCSETLIMIT Fa "struct pfioc_limit"
355 Sets hard limits on the memory pools used by the packet filter.
362 .It Dv DIOCGETLIMIT Fa "struct pfioc_limit"
363 .It Dv DIOCRCLRTABLES Fa "struct pfioc_table"
365 All the IOCTLs that manipulate radix tables
366 use the same structure described below.
368 .Dv DIOCRCLRTABLES, pfrio_ndel contains on exit the number
372 struct pfr_table pfrio_table;
383 #define pfrio_exists pfrio_nadd
384 #define pfrio_nzero pfrio_nadd
385 #define pfrio_nmatch pfrio_nadd
386 #define pfrio_naddr pfrio_size2
387 #define pfrio_setflag pfrio_size2
388 #define pfrio_clrflag pfrio_nadd
390 .It Dv DIOCRADDTABLES Fa "struct pfioc_table"
391 Creates one or more tables.
392 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
393 On exit, pfrio_nadd contains the number of tables effectively created.
396 char pfrt_anchor[PF_ANCHOR_NAME_SIZE];
397 char pfrt_ruleset[PF_RULESET_NAME_SIZE];
398 char pfrt_name[PF_TABLE_NAME_SIZE];
399 u_int32_t pfrt_flags;
403 .It Dv DIOCRDELTABLES Fa "struct pfioc_table"
404 Deletes one or more tables.
405 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
406 On exit, pfrio_nadd contains the number of tables effectively deleted.
407 .It Dv DIOCRGETTABLES Fa "struct pfioc_table"
408 Get the list of all tables.
409 On entry, pfrio_buffer[pfrio_size] contains a valid writeable buffer for
410 pfr_table structures.
411 On exit, pfrio_size contains the number of tables written into the buffer.
412 If the buffer is too small, the kernel does not store anything but just
413 returns the required buffer size, without error.
414 .It Dv DIOCRGETTSTATS Fa "struct pfioc_table"
417 but returns an array of pfr_tstats structures.
420 struct pfr_table pfrts_t;
421 u_int64_t pfrts_packets
422 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
423 u_int64_t pfrts_bytes
424 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
425 u_int64_t pfrts_match;
426 u_int64_t pfrts_nomatch;
429 int pfrts_refcnt[PFR_REFCNT_MAX];
431 #define pfrts_name pfrts_t.pfrt_name
432 #define pfrts_flags pfrts_t.pfrt_flags
434 .It Dv DIOCRCLRTSTATS Fa "struct pfioc_table"
435 Clears the statistics of one or more tables.
436 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
437 On exit, pfrio_nzero contains the number of tables effectively cleared.
438 .It Dv DIOCRCLRADDRS Fa "struct pfioc_table"
439 Clear all addresses in a table.
440 On entry, pfrio_table contains the table to clear.
441 On exit, pfrio_ndel contains the number of addresses removed.
442 .It Dv DIOCRADDADDRS Fa "struct pfioc_table"
443 Add one or more addresses to a table.
444 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
445 contains the list of pfr_addr structures to add.
446 On exit, pfrio_nadd contains the number of addresses effectively added.
450 struct in_addr _pfra_ip4addr;
451 struct in6_addr _pfra_ip6addr;
458 #define pfra_ip4addr pfra_u._pfra_ip4addr
459 #define pfra_ip6addr pfra_u._pfra_ip6addr
461 .It Dv DIOCRDELADDRS Fa "struct pfioc_table"
462 Delete one or more addresses from a table.
463 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
464 contains the list of pfr_addr structures to delete.
465 On exit, pfrio_ndel contains the number of addresses effectively deleted.
466 .It Dv DIOCRSETADDRS Fa "struct pfioc_table"
467 Replace the content of a table by a new address list.
468 This is the most complicated command, which uses all the structure members.
469 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
470 contains the new list of pfr_addr structures.
471 In addition to that, if size2 is nonzero, pfrio_buffer[pfrio_size..pfrio_size2]
472 must be a writeable buffer, into which the kernel can copy the addresses that
473 have been deleted during the replace operation.
474 On exit, pfrio_ndel, pfrio_nadd and pfrio_nchange contain the number of
475 addresses deleted, added and changed by the kernel.
476 If pfrio_size2 was set on
477 entry, pfrio_size2 will point to the size of the buffer used, exactly like
479 .It Dv DIOCRGETADDRS Fa "struct pfioc_table"
480 Get all the addresses of a table.
481 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
482 contains a valid writeable buffer for pfr_addr structures.
483 On exit, pfrio_size contains the number of addresses written into the buffer.
484 If the buffer was too small, the kernel does not store anything but just
485 return the required buffer size, without returning an error.
486 .It Dv DIOCRGETASTATS Fa "struct pfioc_table"
489 but returns an array of pfr_astats structures.
492 struct pfr_addr pfras_a;
493 u_int64_t pfras_packets
494 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
495 u_int64_t pfras_bytes
496 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
500 .It Dv DIOCRCLRASTATS Fa "struct pfioc_table"
501 Clears the statistics of one or more addresses.
502 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
503 contains a table of pfr_addr structures to clear.
504 On exit, pfrio_nzero contains the number of addresses effectively cleared.
505 .It Dv DIOCRTSTADDRS Fa "struct pfioc_table"
506 Test if the given addresses match a table.
507 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
508 contains a table of pfr_addr structures to test.
509 On exit, the kernel updates the pfr_addr table by setting the pfra_fback
510 member appropriately.
511 .It Dv DIOCRSETTFLAGS Fa "struct pfioc_table"
517 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures,
518 and pfrio_setflag contains the flags to add, while pfrio_clrflag contains the
520 On exit, pfrio_nchange and pfrio_ndel contain the number of tables altered
521 or deleted by the kernel.
522 Yes, tables can be deleted if one removes the
524 flag of an unreferenced table.
525 .It Dv DIOCRINADEFINE Fa "struct pfioc_table"
526 Defines a table in the inactive set.
527 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
528 contains the list of pfr_addr structures to put in the table.
529 A valid ticket must also be supplied to pfrio_ticket.
530 On exit, pfrio_nadd contains 0 if the table was already defined in the
531 inactive list, or 1 if a new table has been created.
532 pfrio_naddr contains the number of addresses effectively put in the table.
533 .It Dv DIOCXBEGIN Fa "struct pfioc_trans"
535 #define PF_RULESET_ALTQ (PF_RULESET_MAX)
536 #define PF_RULESET_TABLE (PF_RULESET_MAX+1)
538 int size; /* number of elements */
539 int esize; /* size of each element in bytes */
540 struct pfioc_trans_e {
542 char anchor[PF_ANCHOR_NAME_SIZE];
543 char ruleset[PF_RULESET_NAME_SIZE];
549 Clears all the inactive rulesets specified in the
550 .Fa "struct pfioc_trans_e"
552 For each ruleset, a ticket is returned for subsequent "add rule" IOCTLs,
558 .It Dv DIOCXCOMMIT Fa "struct pfioc_trans"
559 Atomically switch a vector of inactive rulesets to the active rulesets.
560 Implemented as a standard 2-phase commit, which will either fail for all
561 rulesets or completely succeed.
562 All tickets need to be valid.
565 if a concurrent process is trying to update some of the same rulesets
567 .It Dv DIOCXROLLBACK Fa "struct pfioc_trans"
568 Clean up the kernel by undoing all changes that have taken place on the
569 inactive rulesets since the last
572 will silently ignore rulesets for which the ticket is invalid.
574 Flush the passive OS fingerprint table.
575 .It Dv DIOCFPADD Fa "struct pf_osfp_ioctl"
577 struct pf_osfp_ioctl {
578 struct pf_osfp_entry {
579 SLIST_ENTRY(pf_osfp_entry) fp_entry;
581 char fp_class_nm[PF_OSFP_LEN];
582 char fp_version_nm[PF_OSFP_LEN];
583 char fp_subtype_nm[PF_OSFP_LEN];
595 Add a passive OS fingerprint to the table.
598 to the packed fingerprint,
599 .Va fp_os.fp_class_nm
600 to the name of the class (Linux, Windows, etc),
601 .Va fp_os.fp_version_nm
602 to the name of the version (NT, 95, 98), and
603 .Va fp_os.fp_subtype_nm
604 to the name of the subtype or patchlevel.
612 are set to the TCP MSS, the TCP window size, the IP length and the IP TTL of
613 the TCP SYN packet respectively.
616 member is filled according to the
618 include file PF_OSFP_* defines.
621 is not used with this ioctl.
623 The structure's slack space must be zeroed for correct operation; memset
624 the whole structure to zero before filling and sending to the kernel.
625 .It Dv DIOCFPGET Fa "struct pf_osfp_ioctl"
627 struct pf_osfp_ioctl {
628 struct pf_osfp_entry {
629 SLIST_ENTRY(pf_osfp_entry) fp_entry;
631 char fp_class_nm[PF_OSFP_LEN];
632 char fp_version_nm[PF_OSFP_LEN];
633 char fp_subtype_nm[PF_OSFP_LEN];
645 Get the passive OS fingerprint number
647 from the kernel's fingerprint list.
648 The rest of the structure members will come back filled.
649 Get the whole list by repeatedly incrementing the
651 number until the ioctl returns
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
840 and was imported into
842 by Devon H. O'Dell and Simon Schubert.