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
99 for subsequent DIOCADDADDR, DIOCADDRULE and DIOCCHANGERULE calls.
100 .It Dv DIOCADDADDR Fa "struct pfioc_pooladdr"
104 to the buffer address pool to be used in the following
105 DIOCADDRULE or DIOCCHANGERULE call.
106 All other members of the structure are ignored.
107 .It Dv DIOCADDRULE Fa "struct pfioc_rule"
112 u_int32_t pool_ticket;
114 char anchor[PF_ANCHOR_NAME_SIZE];
115 char ruleset[PF_RULESET_NAME_SIZE];
122 at the end of the inactive ruleset.
125 obtained through preceding DIOCXBEGIN call, and
127 obtained through DIOCBEGINADDRS call.
128 DIOCADDADDR must also be called if any pool addresses are required.
133 names indicate the anchor and ruleset in which to append the rule.
138 .It Dv DIOCADDALTQ Fa "struct pfioc_altq"
148 .It Dv DIOCGETRULES Fa "struct pfioc_rule"
151 for subsequent DIOCGETRULE calls and
153 of rules in the active ruleset.
154 .It Dv DIOCGETRULE Fa "struct pfioc_rule"
161 obtained through a preceding DIOCGETRULES call.
162 .It Dv DIOCGETADDRS Fa "struct pfioc_pooladdr"
165 for subsequent DIOCGETADDR calls and
167 of pool addresses in the rule specified with
173 .It Dv DIOCGETADDR Fa "struct pfioc_pooladdr"
178 from the rule specified with
186 obtained through a preceding DIOCGETADDRS call.
187 .It Dv DIOCGETALTQS Fa "struct pfioc_altq"
190 for subsequent DIOCGETALTQ calls and
192 of queues in the active list.
193 .It Dv DIOCGETALTQ Fa "struct pfioc_altq"
200 obtained through a preceding DIOCGETALTQS call.
201 .It Dv DIOCGETQSTATS Fa "struct pfioc_qstats"
202 Returns statistics on a queue.
204 struct pfioc_qstats {
213 A pointer to a buffer of statistics
217 for the queue specified by
219 .It Dv DIOCADDSTATE Fa "struct pfioc_state"
221 .It Dv DIOCGETSTATE Fa "struct pfioc_state"
225 struct pf_state state;
229 Extracts the entry with the specified number from the state table.
230 .It Dv DIOCKILLSTATES Fa "struct pfioc_state_kill"
231 Removes matching entries from the state table.
232 Returns the number of killed states in psk_af.
234 struct pfioc_state_kill {
237 struct pf_rule_addr psk_src;
238 struct pf_rule_addr psk_dst;
239 char psk_ifname[IFNAMSIZ];
242 .It Dv DIOCCLRSTATES Fa "struct pfioc_state_kill"
246 but ignores the psk_af, psk_proto, psk_src and psk_dst fields of the
249 .It Dv DIOCSETSTATUSIF Fa "struct pfioc_if"
252 char ifname[IFNAMSIZ];
256 Specifies the interface for which statistics are accumulated.
257 .It Dv DIOCGETSTATUS Fa "struct pf_status"
260 u_int64_t counters[PFRES_MAX];
261 u_int64_t fcounters[FCNT_MAX];
262 u_int64_t scounters[SCNT_MAX];
263 u_int64_t pcounters[2][2][3];
264 u_int64_t bcounters[2][2];
270 char ifname[IFNAMSIZ];
274 Gets the internal packet filter statistics.
276 Clears the internal packet filter statistics.
277 .It Dv DIOCNATLOOK Fa "struct pfioc_natlook"
278 Looks up a state table entry by source and destination addresses and ports.
280 struct pfioc_natlook {
281 struct pf_addr saddr;
282 struct pf_addr daddr;
283 struct pf_addr rsaddr;
284 struct pf_addr rdaddr;
294 .It Dv DIOCSETDEBUG Fa "u_int32_t"
295 Sets the debug level.
297 enum { PF_DEBUG_NONE=0, PF_DEBUG_URGENT=1, PF_DEBUG_MISC=2 };
299 .It Dv DIOCGETSTATES Fa "struct pfioc_states"
301 struct pfioc_states {
305 struct pf_state *psu_states;
307 #define ps_buf ps_u.psu_buf
308 #define ps_states ps_u.psu_states
311 .It Dv DIOCCHANGERULE Fa "struct pfioc_rule"
314 in the ruleset specified by
317 enum { PF_CHANGE_ADD_HEAD=1, PF_CHANGE_ADD_TAIL=2,
318 PF_CHANGE_ADD_BEFORE=3, PF_CHANGE_ADD_AFTER=4,
319 PF_CHANGE_REMOVE=5, PF_CHANGE_GET_TICKET=6 };
322 The type of operation to be performed is indicated by
326 must be set to the value obtained with PF_CHANGE_GET_TICKET
327 for all actions except PF_CHANGE_GET_TICKET.
329 must be set to the value obtained with the DIOCBEGINADDRS call
330 for all actions except PF_CHANGE_REMOVE and PF_CHANGE_GET_TICKET.
335 indicate which anchor and ruleset the operation applies to.
337 indicates the rule number against which PF_CHANGE_ADD_BEFORE,
338 PF_CHANGE_ADD_AFTER or PF_CHANGE_REMOVE actions are applied.
339 .It Dv DIOCCHANGEADDR Fa "struct pfioc_pooladdr"
340 Adds or removes a pool address
342 from a rule specified with
348 .It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm"
355 .It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm"
356 .It Dv DIOCCLRRULECTRS
357 Clear per-rule statistics.
358 .It Dv DIOCSETLIMIT Fa "struct pfioc_limit"
359 Sets hard limits on the memory pools used by the packet filter.
366 .It Dv DIOCGETLIMIT Fa "struct pfioc_limit"
367 .It Dv DIOCRCLRTABLES Fa "struct pfioc_table"
369 All the IOCTLs that manipulate radix tables
370 use the same structure described below.
372 .Dv DIOCRCLRTABLES, pfrio_ndel contains on exit the number
376 struct pfr_table pfrio_table;
387 #define pfrio_exists pfrio_nadd
388 #define pfrio_nzero pfrio_nadd
389 #define pfrio_nmatch pfrio_nadd
390 #define pfrio_naddr pfrio_size2
391 #define pfrio_setflag pfrio_size2
392 #define pfrio_clrflag pfrio_nadd
394 .It Dv DIOCRADDTABLES Fa "struct pfioc_table"
395 Creates one or more tables.
396 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
397 On exit, pfrio_nadd contains the number of tables effectively created.
400 char pfrt_anchor[PF_ANCHOR_NAME_SIZE];
401 char pfrt_ruleset[PF_RULESET_NAME_SIZE];
402 char pfrt_name[PF_TABLE_NAME_SIZE];
403 u_int32_t pfrt_flags;
407 .It Dv DIOCRDELTABLES Fa "struct pfioc_table"
408 Deletes one or more tables.
409 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
410 On exit, pfrio_nadd contains the number of tables effectively deleted.
411 .It Dv DIOCRGETTABLES Fa "struct pfioc_table"
412 Get the list of all tables.
413 On entry, pfrio_buffer[pfrio_size] contains a valid writeable buffer for
414 pfr_table structures.
415 On exit, pfrio_size contains the number of tables written into the buffer.
416 If the buffer is too small, the kernel does not store anything but just
417 returns the required buffer size, without error.
418 .It Dv DIOCRGETTSTATS Fa "struct pfioc_table"
421 but returns an array of pfr_tstats structures.
424 struct pfr_table pfrts_t;
425 u_int64_t pfrts_packets
426 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
427 u_int64_t pfrts_bytes
428 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
429 u_int64_t pfrts_match;
430 u_int64_t pfrts_nomatch;
433 int pfrts_refcnt[PFR_REFCNT_MAX];
435 #define pfrts_name pfrts_t.pfrt_name
436 #define pfrts_flags pfrts_t.pfrt_flags
438 .It Dv DIOCRCLRTSTATS Fa "struct pfioc_table"
439 Clears the statistics of one or more tables.
440 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures.
441 On exit, pfrio_nzero contains the number of tables effectively cleared.
442 .It Dv DIOCRCLRADDRS Fa "struct pfioc_table"
443 Clear all addresses in a table.
444 On entry, pfrio_table contains the table to clear.
445 On exit, pfrio_ndel contains the number of addresses removed.
446 .It Dv DIOCRADDADDRS Fa "struct pfioc_table"
447 Add one or more addresses to a table.
448 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
449 contains the list of pfr_addr structures to add.
450 On exit, pfrio_nadd contains the number of addresses effectively added.
454 struct in_addr _pfra_ip4addr;
455 struct in6_addr _pfra_ip6addr;
462 #define pfra_ip4addr pfra_u._pfra_ip4addr
463 #define pfra_ip6addr pfra_u._pfra_ip6addr
465 .It Dv DIOCRDELADDRS Fa "struct pfioc_table"
466 Delete one or more addresses from a table.
467 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
468 contains the list of pfr_addr structures to delete.
469 On exit, pfrio_ndel contains the number of addresses effectively deleted.
470 .It Dv DIOCRSETADDRS Fa "struct pfioc_table"
471 Replace the content of a table by a new address list.
472 This is the most complicated command, which uses all the structure members.
473 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
474 contains the new list of pfr_addr structures.
475 In addition to that, if size2 is nonzero, pfrio_buffer[pfrio_size..pfrio_size2]
476 must be a writeable buffer, into which the kernel can copy the addresses that
477 have been deleted during the replace operation.
478 On exit, pfrio_ndel, pfrio_nadd and pfrio_nchange contain the number of
479 addresses deleted, added and changed by the kernel.
480 If pfrio_size2 was set on
481 entry, pfrio_size2 will point to the size of the buffer used, exactly like
483 .It Dv DIOCRGETADDRS Fa "struct pfioc_table"
484 Get all the addresses of a table.
485 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
486 contains a valid writeable buffer for pfr_addr structures.
487 On exit, pfrio_size contains the number of addresses written into the buffer.
488 If the buffer was too small, the kernel does not store anything but just
489 return the required buffer size, without returning an error.
490 .It Dv DIOCRGETASTATS Fa "struct pfioc_table"
493 but returns an array of pfr_astats structures.
496 struct pfr_addr pfras_a;
497 u_int64_t pfras_packets
498 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
499 u_int64_t pfras_bytes
500 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
504 .It Dv DIOCRCLRASTATS Fa "struct pfioc_table"
505 Clears the statistics of one or more addresses.
506 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
507 contains a table of pfr_addr structures to clear.
508 On exit, pfrio_nzero contains the number of addresses effectively cleared.
509 .It Dv DIOCRTSTADDRS Fa "struct pfioc_table"
510 Test if the given addresses match a table.
511 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
512 contains a table of pfr_addr structures to test.
513 On exit, the kernel updates the pfr_addr table by setting the pfra_fback
514 member appropriately.
515 .It Dv DIOCRSETTFLAGS Fa "struct pfioc_table"
521 On entry, pfrio_buffer[pfrio_size] contains a table of pfr_table structures,
522 and pfrio_setflag contains the flags to add, while pfrio_clrflag contains the
524 On exit, pfrio_nchange and pfrio_ndel contain the number of tables altered
525 or deleted by the kernel.
526 Yes, tables can be deleted if one removes the
528 flag of an unreferenced table.
529 .It Dv DIOCRINADEFINE Fa "struct pfioc_table"
530 Defines a table in the inactive set.
531 On entry, pfrio_table contains the table id and pfrio_buffer[pfrio_size]
532 contains the list of pfr_addr structures to put in the table.
533 A valid ticket must also be supplied to pfrio_ticket.
534 On exit, pfrio_nadd contains 0 if the table was already defined in the
535 inactive list, or 1 if a new table has been created.
536 pfrio_naddr contains the number of addresses effectively put in the table.
537 .It Dv DIOCXBEGIN Fa "struct pfioc_trans"
539 #define PF_RULESET_ALTQ (PF_RULESET_MAX)
540 #define PF_RULESET_TABLE (PF_RULESET_MAX+1)
542 int size; /* number of elements */
543 int esize; /* size of each element in bytes */
544 struct pfioc_trans_e {
546 char anchor[PF_ANCHOR_NAME_SIZE];
547 char ruleset[PF_RULESET_NAME_SIZE];
553 Clears all the inactive rulesets specified in the
554 .Fa "struct pfioc_trans_e"
556 For each ruleset, a ticket is returned for subsequent "add rule" IOCTLs,
562 .It Dv DIOCXCOMMIT Fa "struct pfioc_trans"
563 Atomically switch a vector of inactive rulesets to the active rulesets.
564 Implemented as a standard 2-phase commit, which will either fail for all
565 rulesets or completely succeed.
566 All tickets need to be valid.
569 if a concurrent process is trying to update some of the same rulesets
571 .It Dv DIOCXROLLBACK Fa "struct pfioc_trans"
572 Clean up the kernel by undoing all changes that have taken place on the
573 inactive rulesets since the last
576 will silently ignore rulesets for which the ticket is invalid.
578 Flush the passive OS fingerprint table.
579 .It Dv DIOCFPADD Fa "struct pf_osfp_ioctl"
581 struct pf_osfp_ioctl {
582 struct pf_osfp_entry {
583 SLIST_ENTRY(pf_osfp_entry) fp_entry;
585 char fp_class_nm[PF_OSFP_LEN];
586 char fp_version_nm[PF_OSFP_LEN];
587 char fp_subtype_nm[PF_OSFP_LEN];
599 Add a passive OS fingerprint to the table.
602 to the packed fingerprint,
603 .Va fp_os.fp_class_nm
604 to the name of the class (Linux, Windows, etc),
605 .Va fp_os.fp_version_nm
606 to the name of the version (NT, 95, 98), and
607 .Va fp_os.fp_subtype_nm
608 to the name of the subtype or patchlevel.
616 are set to the TCP MSS, the TCP window size, the IP length and the IP TTL of
617 the TCP SYN packet respectively.
620 member is filled according to the
622 include file PF_OSFP_* defines.
625 is not used with this ioctl.
627 The structure's slack space must be zeroed for correct operation; memset
628 the whole structure to zero before filling and sending to the kernel.
629 .It Dv DIOCFPGET Fa "struct pf_osfp_ioctl"
631 struct pf_osfp_ioctl {
632 struct pf_osfp_entry {
633 SLIST_ENTRY(pf_osfp_entry) fp_entry;
635 char fp_class_nm[PF_OSFP_LEN];
636 char fp_version_nm[PF_OSFP_LEN];
637 char fp_subtype_nm[PF_OSFP_LEN];
649 Get the passive OS fingerprint number
651 from the kernel's fingerprint list.
652 The rest of the structure members will come back filled.
653 Get the whole list by repeatedly incrementing the
655 number until the ioctl returns
657 .It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes"
659 struct pfioc_src_nodes {
663 struct pf_src_node *psu_src_nodes;
665 #define psn_buf psn_u.psu_buf
666 #define psn_src_nodes psn_u.psu_src_nodes
670 Get the list of source nodes kept by the
675 The ioctl must be called once with
678 If the ioctl returns without error,
680 will be set to the size of the buffer required to hold all the
682 structures held in the table.
683 A buffer of this size should then be allocated, and a pointer to this buffer
686 The ioctl must then be called again to fill this buffer with the actual
690 will be set to the length of the buffer actually used.
691 .It Dv DIOCCLRSRCNODES Fa "struct pfioc_table"
692 Clear the tree of source tracking nodes.
693 .It Dv DIOCIGETIFACES Fa "struct pfioc_iface"
694 Gets the list of interfaces and interface drivers known to
696 All the IOCTLs that manipulate interfaces
697 use the same structure described below:
700 char pfiio_name[IFNAMSIZ];
708 #define PFI_FLAG_GROUP 0x0001 /* gets groups of interfaces */
709 #define PFI_FLAG_INSTANCE 0x0002 /* gets single interfaces */
710 #define PFI_FLAG_ALLMASK 0x0003
715 can be used to restrict the search to a specific interface or driver.
716 .Va pfiio_buffer[pfiio_size]
717 is the user-supplied buffer for returning the data.
720 represents the number of
722 entries that can fit into the buffer.
723 The kernel will replace this value by the real number of entries it wants
726 should be set to sizeof(struct pfi_if).
729 .Dv PFI_FLAG_GROUP , PFI_FLAG_INSTANCE ,
730 or both to tell the kernel to return a group of interfaces
731 (drivers, like "fxp"), real interface instances (like "fxp1") or both.
732 The data is returned in the
734 structure described below:
737 char pfif_name[IFNAMSIZ];
738 u_int64_t pfif_packets[2][2][2];
739 u_int64_t pfif_bytes[2][2][2];
740 u_int64_t pfif_addcnt;
741 u_int64_t pfif_delcnt;
748 #define PFI_IFLAG_GROUP 0x0001 /* group of interfaces */
749 #define PFI_IFLAG_INSTANCE 0x0002 /* single instance */
750 #define PFI_IFLAG_CLONABLE 0x0010 /* clonable group */
751 #define PFI_IFLAG_DYNAMIC 0x0020 /* dynamic group */
752 #define PFI_IFLAG_ATTACHED 0x0040 /* interface attached */
753 #define PFI_IFLAG_REFERENCED 0x0080 /* referenced by rules */
755 .It Dv DIOCICLRISTATS Fa "struct pfioc_iface"
756 Clear the statistics counters of one or more interfaces.
760 can be used to select which interfaces need to be cleared.
761 The filtering process is the same as for
764 will be set by the kernel to the number of interfaces and drivers
765 that have been cleared.
768 The following example demonstrates how to use the DIOCNATLOOK command
769 to find the internal host/port of a NATed connection.
771 #include <sys/types.h>
772 #include <sys/socket.h>
773 #include <sys/ioctl.h>
774 #include <sys/fcntl.h>
776 #include <netinet/in.h>
777 #include <net/pfvar.h>
783 read_address(const char *s)
787 sscanf(s, "%i.%i.%i.%i", &a, &b, &c, &d);
788 return htonl(a << 24 | b << 16 | c << 8 | d);
792 print_address(u_int32_t a)
795 printf("%d.%d.%d.%d", a >> 24 & 255, a >> 16 & 255,
796 a >> 8 & 255, a & 255);
800 main(int argc, char *argv[])
802 struct pfioc_natlook nl;
806 printf("%s <gwy addr> <gwy port> <ext addr> <ext port>\\n",
811 dev = open("/dev/pf", O_RDWR);
813 err(1, "open(\\"/dev/pf\\") failed");
815 memset(&nl, 0, sizeof(struct pfioc_natlook));
816 nl.saddr.v4.s_addr = read_address(argv[1]);
817 nl.sport = htons(atoi(argv[2]));
818 nl.daddr.v4.s_addr = read_address(argv[3]);
819 nl.dport = htons(atoi(argv[4]));
821 nl.proto = IPPROTO_TCP;
822 nl.direction = PF_IN;
824 if (ioctl(dev, DIOCNATLOOK, &nl))
825 err(1, "DIOCNATLOOK");
827 printf("internal host ");
828 print_address(nl.rsaddr.v4.s_addr);
829 printf(":%u\\n", ntohs(nl.rsport));
842 packet filtering mechanism first appeared in
844 and was imported into
846 by Devon H. O'Dell and Simon Schubert.