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.5 2007/05/19 17:32:12 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.
75 bandwidth control system.
79 bandwidth control system.
80 .It Dv DIOCBEGINADDRS Fa "struct pfioc_pooladdr"
82 struct pfioc_pooladdr {
90 char anchor[PF_ANCHOR_NAME_SIZE];
91 char ruleset[PF_RULESET_NAME_SIZE];
92 struct pf_pooladdr addr;
96 Clears the buffer address pool
105 .It Dv DIOCADDADDR Fa "struct pfioc_pooladdr"
109 to the buffer address pool to be used in the following
114 All other members of the structure are ignored.
115 .It Dv DIOCADDRULE Fa "struct pfioc_rule"
120 u_int32_t pool_ticket;
122 char anchor[PF_ANCHOR_NAME_SIZE];
123 char ruleset[PF_RULESET_NAME_SIZE];
130 at the end of the inactive ruleset.
133 obtained through preceding
141 must also be called if any pool addresses are required.
146 names indicate the anchor and ruleset in which to append the rule.
151 .It Dv DIOCADDALTQ Fa "struct pfioc_altq"
161 .It Dv DIOCGETRULES Fa "struct pfioc_rule"
168 of rules in the active ruleset.
169 .It Dv DIOCGETRULE Fa "struct pfioc_rule"
176 obtained through a preceding
179 .It Dv DIOCGETADDRS Fa "struct pfioc_pooladdr"
186 of pool addresses in the rule specified with
192 .It Dv DIOCGETADDR Fa "struct pfioc_pooladdr"
197 from the rule specified with
205 obtained through a preceding
208 .It Dv DIOCGETALTQS Fa "struct pfioc_altq"
215 of queues in the active list.
216 .It Dv DIOCGETALTQ Fa "struct pfioc_altq"
223 obtained through a preceding
226 .It Dv DIOCGETQSTATS Fa "struct pfioc_qstats"
227 Returns statistics on a queue.
229 struct pfioc_qstats {
238 A pointer to a buffer of statistics
242 for the queue specified by
244 .It Dv DIOCADDSTATE Fa "struct pfioc_state"
246 .It Dv DIOCGETSTATE Fa "struct pfioc_state"
250 struct pf_state state;
254 Extracts the entry with the specified number from the state table.
255 .It Dv DIOCKILLSTATES Fa "struct pfioc_state_kill"
256 Removes matching entries from the state table.
257 Returns the number of killed states in psk_af.
259 struct pfioc_state_kill {
262 struct pf_rule_addr psk_src;
263 struct pf_rule_addr psk_dst;
264 char psk_ifname[IFNAMSIZ];
267 .It Dv DIOCCLRSTATES Fa "struct pfioc_state_kill"
271 but ignores the psk_af, psk_proto, psk_src and psk_dst fields of the
274 .It Dv DIOCSETSTATUSIF Fa "struct pfioc_if"
277 char ifname[IFNAMSIZ];
281 Specifies the interface for which statistics are accumulated.
282 .It Dv DIOCGETSTATUS Fa "struct pf_status"
285 u_int64_t counters[PFRES_MAX];
286 u_int64_t fcounters[FCNT_MAX];
287 u_int64_t scounters[SCNT_MAX];
288 u_int64_t pcounters[2][2][3];
289 u_int64_t bcounters[2][2];
295 char ifname[IFNAMSIZ];
299 Gets the internal packet filter statistics.
301 Clears the internal packet filter statistics.
302 .It Dv DIOCNATLOOK Fa "struct pfioc_natlook"
303 Looks up a state table entry by source and destination addresses and ports.
305 struct pfioc_natlook {
306 struct pf_addr saddr;
307 struct pf_addr daddr;
308 struct pf_addr rsaddr;
309 struct pf_addr rdaddr;
319 .It Dv DIOCSETDEBUG Fa "u_int32_t"
320 Sets the debug level.
322 enum { PF_DEBUG_NONE=0, PF_DEBUG_URGENT=1, PF_DEBUG_MISC=2 };
324 .It Dv DIOCGETSTATES Fa "struct pfioc_states"
326 struct pfioc_states {
330 struct pf_state *psu_states;
332 #define ps_buf ps_u.psu_buf
333 #define ps_states ps_u.psu_states
336 .It Dv DIOCCHANGERULE Fa "struct pfioc_rule"
339 in the ruleset specified by
342 enum { PF_CHANGE_ADD_HEAD=1, PF_CHANGE_ADD_TAIL=2,
343 PF_CHANGE_ADD_BEFORE=3, PF_CHANGE_ADD_AFTER=4,
344 PF_CHANGE_REMOVE=5, PF_CHANGE_GET_TICKET=6 };
347 The type of operation to be performed is indicated by
351 must be set to the value obtained with PF_CHANGE_GET_TICKET
352 for all actions except PF_CHANGE_GET_TICKET.
354 must be set to the value obtained with the
356 call for all actions except PF_CHANGE_REMOVE and PF_CHANGE_GET_TICKET.
361 indicate which anchor and ruleset the operation applies to.
363 indicates the rule number against which PF_CHANGE_ADD_BEFORE,
364 PF_CHANGE_ADD_AFTER or PF_CHANGE_REMOVE actions are applied.
365 .It Dv DIOCCHANGEADDR Fa "struct pfioc_pooladdr"
366 Adds or removes a pool address
368 from a rule specified with
374 .It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm"
381 .It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm"
382 .It Dv DIOCCLRRULECTRS
383 Clear per-rule statistics.
384 .It Dv DIOCSETLIMIT Fa "struct pfioc_limit"
385 Sets hard limits on the memory pools used by the packet filter.
392 .It Dv DIOCGETLIMIT Fa "struct pfioc_limit"
393 .It Dv DIOCRCLRTABLES Fa "struct pfioc_table"
395 All the IOCTLs that manipulate radix tables
396 use the same structure described below.
398 .Dv DIOCRCLRTABLES, pfrio_ndel contains on exit the number
402 struct pfr_table pfrio_table;
413 #define pfrio_exists pfrio_nadd
414 #define pfrio_nzero pfrio_nadd
415 #define pfrio_nmatch pfrio_nadd
416 #define pfrio_naddr pfrio_size2
417 #define pfrio_setflag pfrio_size2
418 #define pfrio_clrflag pfrio_nadd
420 .It Dv DIOCRADDTABLES Fa "struct pfioc_table"
421 Creates one or more tables.
422 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
423 On exit, pfrio_nadd contains the number of tables effectively created.
426 char pfrt_anchor[PF_ANCHOR_NAME_SIZE];
427 char pfrt_ruleset[PF_RULESET_NAME_SIZE];
428 char pfrt_name[PF_TABLE_NAME_SIZE];
429 u_int32_t pfrt_flags;
433 .It Dv DIOCRDELTABLES Fa "struct pfioc_table"
434 Deletes one or more tables.
435 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
436 On exit, pfrio_nadd contains the number of tables effectively deleted.
437 .It Dv DIOCRGETTABLES Fa "struct pfioc_table"
438 Get the list of all tables.
439 On entry, pfrio_buffer[pfrio_size] contains a valid writeable buffer for
440 pfr_table structures.
441 On exit, pfrio_size contains the number of tables written into the buffer.
442 If the buffer is too small, the kernel does not store anything but just
443 returns the required buffer size, without error.
444 .It Dv DIOCRGETTSTATS Fa "struct pfioc_table"
447 but returns an array of pfr_tstats structures.
450 struct pfr_table pfrts_t;
451 u_int64_t pfrts_packets
452 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
453 u_int64_t pfrts_bytes
454 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
455 u_int64_t pfrts_match;
456 u_int64_t pfrts_nomatch;
459 int pfrts_refcnt[PFR_REFCNT_MAX];
461 #define pfrts_name pfrts_t.pfrt_name
462 #define pfrts_flags pfrts_t.pfrt_flags
464 .It Dv DIOCRCLRTSTATS Fa "struct pfioc_table"
465 Clears the statistics of one or more tables.
466 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
467 On exit, pfrio_nzero contains the number of tables effectively cleared.
468 .It Dv DIOCRCLRADDRS Fa "struct pfioc_table"
469 Clear all addresses in a table.
470 On entry, pfrio_table contains the table to clear.
471 On exit, pfrio_ndel contains the number of addresses removed.
472 .It Dv DIOCRADDADDRS Fa "struct pfioc_table"
473 Add one or more addresses to a table.
474 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
475 contains the list of pfr_addr structures to add.
476 On exit, pfrio_nadd contains the number of addresses effectively added.
480 struct in_addr _pfra_ip4addr;
481 struct in6_addr _pfra_ip6addr;
488 #define pfra_ip4addr pfra_u._pfra_ip4addr
489 #define pfra_ip6addr pfra_u._pfra_ip6addr
491 .It Dv DIOCRDELADDRS Fa "struct pfioc_table"
492 Delete one or more addresses from a table.
493 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
494 contains the list of pfr_addr structures to delete.
495 On exit, pfrio_ndel contains the number of addresses effectively deleted.
496 .It Dv DIOCRSETADDRS Fa "struct pfioc_table"
497 Replace the content of a table by a new address list.
498 This is the most complicated command, which uses all the structure members.
499 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
500 contains the new list of pfr_addr structures.
501 In addition to that, if size2 is nonzero, pfrio_buffer[pfrio_size..pfrio_size2]
502 must be a writeable buffer, into which the kernel can copy the addresses that
503 have been deleted during the replace operation.
504 On exit, pfrio_ndel, pfrio_nadd and pfrio_nchange contain the number of
505 addresses deleted, added and changed by the kernel.
506 If pfrio_size2 was set on
507 entry, pfrio_size2 will point to the size of the buffer used, exactly like
509 .It Dv DIOCRGETADDRS Fa "struct pfioc_table"
510 Get all the addresses of a table.
511 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
512 contains a valid writeable buffer for pfr_addr structures.
513 On exit, pfrio_size contains the number of addresses written into the buffer.
514 If the buffer was too small, the kernel does not store anything but just
515 return the required buffer size, without returning an error.
516 .It Dv DIOCRGETASTATS Fa "struct pfioc_table"
519 but returns an array of pfr_astats structures.
522 struct pfr_addr pfras_a;
523 u_int64_t pfras_packets
524 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
525 u_int64_t pfras_bytes
526 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
530 .It Dv DIOCRCLRASTATS Fa "struct pfioc_table"
531 Clears the statistics of one or more addresses.
532 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
533 contains a table of pfr_addr structures to clear.
534 On exit, pfrio_nzero contains the number of addresses effectively cleared.
535 .It Dv DIOCRTSTADDRS Fa "struct pfioc_table"
536 Test if the given addresses match a table.
537 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
538 contains a table of pfr_addr structures to test.
539 On exit, the kernel updates the pfr_addr table by setting the pfra_fback
540 member appropriately.
541 .It Dv DIOCRSETTFLAGS Fa "struct pfioc_table"
547 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures,
548 and pfrio_setflag contains the flags to add, while pfrio_clrflag contains the
550 On exit, pfrio_nchange and pfrio_ndel contain the number of tables altered
551 or deleted by the kernel.
552 Yes, tables can be deleted if one removes the
554 flag of an unreferenced table.
555 .It Dv DIOCRINADEFINE Fa "struct pfioc_table"
556 Defines a table in the inactive set.
557 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
558 contains the list of pfr_addr structures to put in the table.
559 A valid ticket must also be supplied to pfrio_ticket.
560 On exit, pfrio_nadd contains 0 if the table was already defined in the
561 inactive list, or 1 if a new table has been created.
562 pfrio_naddr contains the number of addresses effectively put in the table.
563 .It Dv DIOCXBEGIN Fa "struct pfioc_trans"
565 #define PF_RULESET_ALTQ (PF_RULESET_MAX)
566 #define PF_RULESET_TABLE (PF_RULESET_MAX+1)
568 int size; /* number of elements */
569 int esize; /* size of each element in bytes */
570 struct pfioc_trans_e {
572 char anchor[PF_ANCHOR_NAME_SIZE];
573 char ruleset[PF_RULESET_NAME_SIZE];
579 Clears all the inactive rulesets specified in the
580 .Fa "struct pfioc_trans_e"
582 For each ruleset, a ticket is returned for subsequent "add rule" IOCTLs,
588 .It Dv DIOCXCOMMIT Fa "struct pfioc_trans"
589 Atomically switch a vector of inactive rulesets to the active rulesets.
590 Implemented as a standard 2-phase commit, which will either fail for all
591 rulesets or completely succeed.
592 All tickets need to be valid.
595 if a concurrent process is trying to update some of the same rulesets
597 .It Dv DIOCXROLLBACK Fa "struct pfioc_trans"
598 Clean up the kernel by undoing all changes that have taken place on the
599 inactive rulesets since the last
602 will silently ignore rulesets for which the ticket is invalid.
604 Flush the passive OS fingerprint table.
605 .It Dv DIOCFPADD Fa "struct pf_osfp_ioctl"
607 struct pf_osfp_ioctl {
608 struct pf_osfp_entry {
609 SLIST_ENTRY(pf_osfp_entry) fp_entry;
611 char fp_class_nm[PF_OSFP_LEN];
612 char fp_version_nm[PF_OSFP_LEN];
613 char fp_subtype_nm[PF_OSFP_LEN];
625 Add a passive OS fingerprint to the table.
628 to the packed fingerprint,
629 .Va fp_os.fp_class_nm
630 to the name of the class (Linux, Windows, etc),
631 .Va fp_os.fp_version_nm
632 to the name of the version (NT, 95, 98), and
633 .Va fp_os.fp_subtype_nm
634 to the name of the subtype or patchlevel.
642 are set to the TCP MSS, the TCP window size, the IP length and the IP TTL of
643 the TCP SYN packet respectively.
646 member is filled according to the
648 include file PF_OSFP_* defines.
651 is not used with this ioctl.
653 The structure's slack space must be zeroed for correct operation; memset
654 the whole structure to zero before filling and sending to the kernel.
655 .It Dv DIOCFPGET Fa "struct pf_osfp_ioctl"
657 struct pf_osfp_ioctl {
658 struct pf_osfp_entry {
659 SLIST_ENTRY(pf_osfp_entry) fp_entry;
661 char fp_class_nm[PF_OSFP_LEN];
662 char fp_version_nm[PF_OSFP_LEN];
663 char fp_subtype_nm[PF_OSFP_LEN];
675 Get the passive OS fingerprint number
677 from the kernel's fingerprint list.
678 The rest of the structure members will come back filled.
679 Get the whole list by repeatedly incrementing the
681 number until the ioctl returns
683 .It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes"
685 struct pfioc_src_nodes {
689 struct pf_src_node *psu_src_nodes;
691 #define psn_buf psn_u.psu_buf
692 #define psn_src_nodes psn_u.psu_src_nodes
696 Get the list of source nodes kept by the
701 The ioctl must be called once with
704 If the ioctl returns without error,
706 will be set to the size of the buffer required to hold all the
708 structures held in the table.
709 A buffer of this size should then be allocated, and a pointer to this buffer
712 The ioctl must then be called again to fill this buffer with the actual
716 will be set to the length of the buffer actually used.
717 .It Dv DIOCCLRSRCNODES Fa "struct pfioc_table"
718 Clear the tree of source tracking nodes.
719 .It Dv DIOCIGETIFACES Fa "struct pfioc_iface"
720 Gets the list of interfaces and interface drivers known to
722 All the IOCTLs that manipulate interfaces
723 use the same structure described below:
726 char pfiio_name[IFNAMSIZ];
734 #define PFI_FLAG_GROUP 0x0001 /* gets groups of interfaces */
735 #define PFI_FLAG_INSTANCE 0x0002 /* gets single interfaces */
736 #define PFI_FLAG_ALLMASK 0x0003
741 can be used to restrict the search to a specific interface or driver.
742 .Va pfiio_buffer[pfiio_size]
743 is the user-supplied buffer for returning the data.
746 represents the number of
748 entries that can fit into the buffer.
749 The kernel will replace this value by the real number of entries it wants
752 should be set to sizeof(struct pfi_if).
755 .Dv PFI_FLAG_GROUP , PFI_FLAG_INSTANCE ,
756 or both to tell the kernel to return a group of interfaces
757 (drivers, like "fxp"), real interface instances (like "fxp1") or both.
758 The data is returned in the
760 structure described below:
763 char pfif_name[IFNAMSIZ];
764 u_int64_t pfif_packets[2][2][2];
765 u_int64_t pfif_bytes[2][2][2];
766 u_int64_t pfif_addcnt;
767 u_int64_t pfif_delcnt;
774 #define PFI_IFLAG_GROUP 0x0001 /* group of interfaces */
775 #define PFI_IFLAG_INSTANCE 0x0002 /* single instance */
776 #define PFI_IFLAG_CLONABLE 0x0010 /* clonable group */
777 #define PFI_IFLAG_DYNAMIC 0x0020 /* dynamic group */
778 #define PFI_IFLAG_ATTACHED 0x0040 /* interface attached */
779 #define PFI_IFLAG_REFERENCED 0x0080 /* referenced by rules */
781 .It Dv DIOCICLRISTATS Fa "struct pfioc_iface"
782 Clear the statistics counters of one or more interfaces.
786 can be used to select which interfaces need to be cleared.
787 The filtering process is the same as for
790 will be set by the kernel to the number of interfaces and drivers
791 that have been cleared.
794 The following example demonstrates how to use the
796 command to find the internal host/port of a NATed connection.
798 #include <sys/types.h>
799 #include <sys/socket.h>
800 #include <sys/ioctl.h>
801 #include <sys/fcntl.h>
803 #include <netinet/in.h>
804 #include <net/pfvar.h>
810 read_address(const char *s)
814 sscanf(s, "%i.%i.%i.%i", &a, &b, &c, &d);
815 return htonl(a << 24 | b << 16 | c << 8 | d);
819 print_address(u_int32_t a)
822 printf("%d.%d.%d.%d", a >> 24 & 255, a >> 16 & 255,
823 a >> 8 & 255, a & 255);
827 main(int argc, char *argv[])
829 struct pfioc_natlook nl;
833 printf("%s <gwy addr> <gwy port> <ext addr> <ext port>\\n",
838 dev = open("/dev/pf", O_RDWR);
840 err(1, "open(\\"/dev/pf\\") failed");
842 memset(&nl, 0, sizeof(struct pfioc_natlook));
843 nl.saddr.v4.s_addr = read_address(argv[1]);
844 nl.sport = htons(atoi(argv[2]));
845 nl.daddr.v4.s_addr = read_address(argv[3]);
846 nl.dport = htons(atoi(argv[4]));
848 nl.proto = IPPROTO_TCP;
849 nl.direction = PF_IN;
851 if (ioctl(dev, DIOCNATLOOK, &nl))
852 err(1, "DIOCNATLOOK");
854 printf("internal host ");
855 print_address(nl.rsaddr.v4.s_addr);
856 printf(":%u\\n", ntohs(nl.rsport));
869 packet filtering mechanism first appeared in
871 and was imported into
873 by Devon H. O'Dell and Simon Schubert.