| blob | c69a83d0573091652169e93ae6581bb09c71a47a |
1 .\" $NetBSD: pf.4,v 1.11 2009/09/14 11:17:49 wiz Exp $
2 .\" $OpenBSD: pf.4,v 1.59 2007/05/31 19:19:51 jmc Exp $
3 .\"
4 .\" Copyright (C) 2001, Kjell Wooding. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
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.
17 .\"
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
28 .\" SUCH DAMAGE.
29 .\"
30 .Dd December 19, 2009
31 .Dt PF 4
32 .Os
33 .Sh NAME
34 .Nm pf
35 .Nd packet filter
36 .Sh SYNOPSIS
37 .Cd "pseudo-device pf"
38 .Sh DESCRIPTION
39 Packet filtering takes place in the kernel.
40 A pseudo-device,
41 .Pa /dev/pf ,
42 allows userland processes to control the
43 behavior of the packet filter through an
44 .Xr ioctl 2
45 interface.
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
50 .Xr pfctl 8 .
51 .Pp
52 Manipulations like loading a ruleset that involve more than a single
53 .Xr ioctl 2
54 call require a so-called
55 .Em ticket ,
56 which prevents the occurrence of
57 multiple concurrent manipulations.
58 .Pp
59 Fields of
60 .Xr ioctl 2
61 parameter structures that refer to packet data (like
62 addresses and ports) are generally expected in network byte-order.
63 .Pp
64 Rules and address tables are contained in so-called
65 .Em anchors .
66 When servicing an
67 .Xr ioctl 2
68 request, if the anchor field of the argument structure is empty,
69 the kernel will use the default anchor (i.e., the main ruleset)
70 in operations.
71 Anchors are specified by name and may be nested, with components
72 separated by
73 .Sq /
74 characters, similar to how file system hierarchies are laid out.
75 The final component of the anchor path is the anchor under which
76 operations will be performed.
77 .Sh IOCTL INTERFACE
78 .Nm
79 supports the following
80 .Xr ioctl 2
81 commands, available through
82 .Aq Pa net/pfvar.h :
83 .Bl -tag -width xxxxxx
84 .It Dv DIOCSTART
85 Start the packet filter.
86 .It Dv DIOCSTOP
87 Stop the packet filter.
88 .It Dv DIOCSTARTALTQ
89 Start the ALTQ bandwidth control system (see
90 .Xr altq 9 ) .
91 .It Dv DIOCSTOPALTQ
92 Stop the ALTQ bandwidth control system.
93 .It Dv DIOCBEGINADDRS Fa "struct pfioc_pooladdr *pp"
94 .Bd -literal
95 struct pfioc_pooladdr {
96 u_int32_t action;
97 u_int32_t ticket;
98 u_int32_t nr;
99 u_int32_t r_num;
100 u_int8_t r_action;
101 u_int8_t r_last;
102 u_int8_t af;
103 char anchor[MAXPATHLEN];
104 struct pf_pooladdr addr;
105 };
106 .Ed
107 .Pp
108 Clear the buffer address pool and get a
109 .Va ticket
110 for subsequent
111 .Dv DIOCADDADDR ,
112 .Dv DIOCADDRULE ,
113 and
114 .Dv DIOCCHANGERULE
115 calls.
116 .It Dv DIOCADDADDR Fa "struct pfioc_pooladdr *pp"
117 .Pp
118 Add the pool address
119 .Va addr
120 to the buffer address pool to be used in the following
121 .Dv DIOCADDRULE
122 or
123 .Dv DIOCCHANGERULE
124 call.
125 All other members of the structure are ignored.
126 .It Dv DIOCADDRULE Fa "struct pfioc_rule *pr"
127 .Bd -literal
128 struct pfioc_rule {
129 u_int32_t action;
130 u_int32_t ticket;
131 u_int32_t pool_ticket;
132 u_int32_t nr;
133 char anchor[MAXPATHLEN];
134 char anchor_call[MAXPATHLEN];
135 struct pf_rule rule;
136 };
137 .Ed
138 .Pp
139 Add
140 .Va rule
141 at the end of the inactive ruleset.
142 This call requires a
143 .Va ticket
144 obtained through a preceding
145 .Dv DIOCXBEGIN
146 call and a
147 .Va pool_ticket
148 obtained through a
149 .Dv DIOCBEGINADDRS
150 call.
151 .Dv DIOCADDADDR
152 must also be called if any pool addresses are required.
153 The optional
154 .Va anchor
155 name indicates the anchor in which to append the rule.
156 .Va nr
157 and
158 .Va action
159 are ignored.
160 .It Dv DIOCADDALTQ Fa "struct pfioc_altq *pa"
161 Add an ALTQ discipline or queue.
162 .Bd -literal
163 struct pfioc_altq {
164 u_int32_t action;
165 u_int32_t ticket;
166 u_int32_t nr;
167 struct pf_altq altq;
168 };
169 .Ed
170 .It Dv DIOCGETRULES Fa "struct pfioc_rule *pr"
171 Get a
172 .Va ticket
173 for subsequent
174 .Dv DIOCGETRULE
175 calls and the number
176 .Va nr
177 of rules in the active ruleset.
178 .It Dv DIOCGETRULE Fa "struct pfioc_rule *pr"
179 Get a
180 .Va rule
181 by its number
182 .Va nr
183 using the
184 .Va ticket
185 obtained through a preceding
186 .Dv DIOCGETRULES
187 call.
188 If
189 .Va action
190 is set to
191 .Dv PF_GET_CLR_CNTR ,
192 the per-rule statistics on the requested rule are cleared.
193 .It Dv DIOCGETADDRS Fa "struct pfioc_pooladdr *pp"
194 Get a
195 .Va ticket
196 for subsequent
197 .Dv DIOCGETADDR
198 calls and the number
199 .Va nr
200 of pool addresses in the rule specified with
201 .Va r_action ,
202 .Va r_num ,
203 and
204 .Va anchor .
205 .It Dv DIOCGETADDR Fa "struct pfioc_pooladdr *pp"
206 Get the pool address
207 .Va addr
208 by its number
209 .Va nr
210 from the rule specified with
211 .Va r_action ,
212 .Va r_num ,
213 and
214 .Va anchor
215 using the
216 .Va ticket
217 obtained through a preceding
218 .Dv DIOCGETADDRS
219 call.
220 .It Dv DIOCGETALTQS Fa "struct pfioc_altq *pa"
221 Get a
222 .Va ticket
223 for subsequent
224 .Dv DIOCGETALTQ
225 calls and the number
226 .Va nr
227 of queues in the active list.
228 .It Dv DIOCGETALTQ Fa "struct pfioc_altq *pa"
229 Get the queueing discipline
230 .Va altq
231 by its number
232 .Va nr
233 using the
234 .Va ticket
235 obtained through a preceding
236 .Dv DIOCGETALTQS
237 call.
238 .It Dv DIOCGETQSTATS Fa "struct pfioc_qstats *pq"
239 Get the statistics on a queue.
240 .Bd -literal
241 struct pfioc_qstats {
242 u_int32_t ticket;
243 u_int32_t nr;
244 void *buf;
245 int nbytes;
246 u_int8_t scheduler;
247 };
248 .Ed
249 .Pp
250 This call fills in a pointer to the buffer of statistics
251 .Va buf ,
252 of length
253 .Va nbytes ,
254 for the queue specified by
255 .Va nr .
256 .It Dv DIOCGETRULESETS Fa "struct pfioc_ruleset *pr"
257 .Bd -literal
258 struct pfioc_ruleset {
259 u_int32_t nr;
260 char path[MAXPATHLEN];
261 char name[PF_ANCHOR_NAME_SIZE];
262 };
263 .Ed
264 .Pp
265 Get the number
266 .Va nr
267 of rulesets (i.e., anchors) directly attached to the anchor named by
268 .Va path
269 for use in subsequent
270 .Dv DIOCGETRULESET
271 calls.
272 Nested anchors, since they are not directly attached to the given
273 anchor, will not be included.
274 This ioctl returns
275 .Er EINVAL
276 if the given anchor does not exist.
277 .It Dv DIOCGETRULESET Fa "struct pfioc_ruleset *pr"
278 Get a ruleset (i.e., an anchor)
279 .Va name
280 by its number
281 .Va nr
282 from the given anchor
283 .Va path ,
284 the maximum number of which can be obtained from a preceding
285 .Dv DIOCGETRULESETS
286 call.
287 This ioctl returns
288 .Er EINVAL
289 if the given anchor does not exist or
290 .Er EBUSY
291 if another process is concurrently updating a ruleset.
292 .It Dv DIOCADDSTATE Fa "struct pfioc_state *ps"
293 Add a state entry.
294 .Bd -literal
295 struct pfioc_state {
296 u_int32_t nr;
297 struct pf_state state;
298 };
299 .Ed
300 .It Dv DIOCGETSTATE Fa "struct pfioc_state *ps"
301 Extract the entry with the specified number
302 .Va nr
303 from the state table.
304 .It Dv DIOCKILLSTATES Fa "struct pfioc_state_kill *psk"
305 Remove matching entries from the state table.
306 This ioctl returns the number of killed states in
307 .Va psk_af .
308 .Bd -literal
309 struct pfioc_state_kill {
310 sa_family_t psk_af;
311 int psk_proto;
312 struct pf_rule_addr psk_src;
313 struct pf_rule_addr psk_dst;
314 char psk_ifname[IFNAMSIZ];
315 };
316 .Ed
317 .It Dv DIOCCLRSTATES Fa "struct pfioc_state_kill *psk"
318 Clear all states.
319 It works like
320 .Dv DIOCKILLSTATES ,
321 but ignores the
322 .Va psk_af ,
323 .Va psk_proto ,
324 .Va psk_src ,
325 and
326 .Va psk_dst
327 fields of the
328 .Vt pfioc_state_kill
329 structure.
330 .It Dv DIOCSETSTATUSIF Fa "struct pfioc_if *pi"
331 Specify the interface for which statistics are accumulated.
332 .Bd -literal
333 struct pfioc_if {
334 char ifname[IFNAMSIZ];
335 };
336 .Ed
337 .It Dv DIOCGETSTATUS Fa "struct pf_status *s"
338 Get the internal packet filter statistics.
339 .Bd -literal
340 struct pf_status {
341 u_int64_t counters[PFRES_MAX];
342 u_int64_t lcounters[LCNT_MAX];
343 u_int64_t fcounters[FCNT_MAX];
344 u_int64_t scounters[SCNT_MAX];
345 u_int64_t pcounters[2][2][3];
346 u_int64_t bcounters[2][2];
347 u_int64_t stateid;
348 u_int32_t running;
349 u_int32_t states;
350 u_int32_t src_nodes;
351 u_int32_t since;
352 u_int32_t debug;
353 u_int32_t hostid;
354 char ifname[IFNAMSIZ];
355 u_int8_t pf_chksum[MD5_DIGEST_LENGTH];
356 };
357 .Ed
358 .It Dv DIOCCLRSTATUS
359 Clear the internal packet filter statistics.
360 .It Dv DIOCNATLOOK Fa "struct pfioc_natlook *pnl"
361 Look up a state table entry by source and destination addresses and ports.
362 .Bd -literal
363 struct pfioc_natlook {
364 struct pf_addr saddr;
365 struct pf_addr daddr;
366 struct pf_addr rsaddr;
367 struct pf_addr rdaddr;
368 u_int16_t sport;
369 u_int16_t dport;
370 u_int16_t rsport;
371 u_int16_t rdport;
372 sa_family_t af;
373 u_int8_t proto;
374 u_int8_t direction;
375 };
376 .Ed
377 .It Dv DIOCSETDEBUG Fa "u_int32_t *level"
378 Set the debug level.
379 .Bd -literal
380 enum { PF_DEBUG_NONE, PF_DEBUG_URGENT, PF_DEBUG_MISC,
381 PF_DEBUG_NOISY };
382 .Ed
383 .It Dv DIOCGETSTATES Fa "struct pfioc_states *ps"
384 Get state table entries.
385 .Bd -literal
386 struct pfioc_states {
387 int ps_len;
388 union {
389 caddr_t psu_buf;
390 struct pf_state *psu_states;
391 } ps_u;
392 #define ps_buf ps_u.psu_buf
393 #define ps_states ps_u.psu_states
394 };
395 .Ed
396 .Pp
397 If
398 .Va ps_len
399 is non-zero on entry, as many states as possible that can fit into this
400 size will be copied into the supplied buffer
401 .Va ps_states .
402 On exit,
403 .Va ps_len
404 is always set to the total size required to hold all state table entries
405 (i.e., it is set to
406 .Li sizeof(struct pf_state) * nr ) .
407 .It Dv DIOCCHANGERULE Fa "struct pfioc_rule *pcr"
408 Add or remove the
409 .Va rule
410 in the ruleset specified by
411 .Va rule.action .
412 .Pp
413 The type of operation to be performed is indicated by
414 .Va action ,
415 which can be any of the following:
416 .Bd -literal
417 enum { PF_CHANGE_NONE, PF_CHANGE_ADD_HEAD, PF_CHANGE_ADD_TAIL,
418 PF_CHANGE_ADD_BEFORE, PF_CHANGE_ADD_AFTER,
419 PF_CHANGE_REMOVE, PF_CHANGE_GET_TICKET };
420 .Ed
421 .Pp
422 .Va ticket
423 must be set to the value obtained with
424 .Dv PF_CHANGE_GET_TICKET
425 for all actions except
426 .Dv PF_CHANGE_GET_TICKET .
427 .Va pool_ticket
428 must be set to the value obtained with the
429 .Dv DIOCBEGINADDRS
430 call for all actions except
431 .Dv PF_CHANGE_REMOVE
432 and
433 .Dv PF_CHANGE_GET_TICKET .
434 .Va anchor
435 indicates to which anchor the operation applies.
436 .Va nr
437 indicates the rule number against which
438 .Dv PF_CHANGE_ADD_BEFORE ,
439 .Dv PF_CHANGE_ADD_AFTER ,
440 or
441 .Dv PF_CHANGE_REMOVE
442 actions are applied.
443 .\" It Dv DIOCCHANGEALTQ Fa "struct pfioc_altq *pcr"
444 .It Dv DIOCCHANGEADDR Fa "struct pfioc_pooladdr *pca"
445 Add or remove the pool address
446 .Va addr
447 from the rule specified by
448 .Va r_action ,
449 .Va r_num ,
450 and
451 .Va anchor .
452 .It Dv DIOCSETTIMEOUT Fa "struct pfioc_tm *pt"
453 .Bd -literal
454 struct pfioc_tm {
455 int timeout;
456 int seconds;
457 };
458 .Ed
459 .Pp
460 Set the state timeout of
461 .Va timeout
462 to
463 .Va seconds .
464 The old value will be placed into
465 .Va seconds .
466 For possible values of
467 .Va timeout ,
468 consult the
469 .Dv PFTM_*
470 values in
471 .Aq Pa net/pfvar.h .
472 .It Dv DIOCGETTIMEOUT Fa "struct pfioc_tm *pt"
473 Get the state timeout of
474 .Va timeout .
475 The value will be placed into the
476 .Va seconds
477 field.
478 .It Dv DIOCCLRRULECTRS
479 Clear per-rule statistics.
480 .It Dv DIOCSETLIMIT Fa "struct pfioc_limit *pl"
481 Set the hard limits on the memory pools used by the packet filter.
482 .Bd -literal
483 struct pfioc_limit {
484 int index;
485 unsigned limit;
486 };
488 enum { PF_LIMIT_STATES, PF_LIMIT_SRC_NODES, PF_LIMIT_FRAGS,
489 PF_LIMIT_TABLES, PF_LIMIT_TABLE_ENTRIES, PF_LIMIT_MAX };
490 .Ed
491 .It Dv DIOCGETLIMIT Fa "struct pfioc_limit *pl"
492 Get the hard
493 .Va limit
494 for the memory pool indicated by
495 .Va index .
496 .It Dv DIOCRCLRTABLES Fa "struct pfioc_table *io"
497 Clear all tables.
498 All the ioctls that manipulate radix tables
499 use the same structure described below.
500 For
501 .Dv DIOCRCLRTABLES ,
502 .Va pfrio_ndel
503 contains on exit the number of tables deleted.
504 .Bd -literal
505 struct pfioc_table {
506 struct pfr_table pfrio_table;
507 void *pfrio_buffer;
508 int pfrio_esize;
509 int pfrio_size;
510 int pfrio_size2;
511 int pfrio_nadd;
512 int pfrio_ndel;
513 int pfrio_nchange;
514 int pfrio_flags;
515 u_int32_t pfrio_ticket;
516 };
517 #define pfrio_exists pfrio_nadd
518 #define pfrio_nzero pfrio_nadd
519 #define pfrio_nmatch pfrio_nadd
520 #define pfrio_naddr pfrio_size2
521 #define pfrio_setflag pfrio_size2
522 #define pfrio_clrflag pfrio_nadd
523 .Ed
524 .It Dv DIOCRADDTABLES Fa "struct pfioc_table *io"
525 Create one or more tables.
526 On entry,
527 .Va pfrio_buffer
528 must point to an array of
529 .Vt struct pfr_table
530 containing at least
531 .Vt pfrio_size
532 elements.
533 .Vt pfrio_esize
534 must be the size of
535 .Vt struct pfr_table .
536 On exit,
537 .Va pfrio_nadd
538 contains the number of tables effectively created.
539 .Bd -literal
540 struct pfr_table {
541 char pfrt_anchor[MAXPATHLEN];
542 char pfrt_name[PF_TABLE_NAME_SIZE];
543 u_int32_t pfrt_flags;
544 u_int8_t pfrt_fback;
545 };
546 .Ed
547 .It Dv DIOCRDELTABLES Fa "struct pfioc_table *io"
548 Delete one or more tables.
549 On entry,
550 .Va pfrio_buffer
551 must point to an array of
552 .Vt struct pfr_table
553 containing at least
554 .Vt pfrio_size
555 elements.
556 .Vt pfrio_esize
557 must be the size of
558 .Vt struct pfr_table .
559 On exit,
560 .Va pfrio_ndel
561 contains the number of tables effectively deleted.
562 .It Dv DIOCRGETTABLES Fa "struct pfioc_table *io"
563 Get the list of all tables.
564 On entry,
565 .Va pfrio_buffer[pfrio_size]
566 contains a valid writeable buffer for
567 .Vt pfr_table
568 structures.
569 On exit,
570 .Va pfrio_size
571 contains the number of tables written into the buffer.
572 If the buffer is too small, the kernel does not store anything but just
573 returns the required buffer size, without error.
574 .It Dv DIOCRGETTSTATS Fa "struct pfioc_table *io"
575 This call is like
576 .Dv DIOCRGETTABLES
577 but is used to get an array of
578 .Vt pfr_tstats
579 structures.
580 .Bd -literal
581 struct pfr_tstats {
582 struct pfr_table pfrts_t;
583 u_int64_t pfrts_packets
584 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
585 u_int64_t pfrts_bytes
586 [PFR_DIR_MAX][PFR_OP_TABLE_MAX];
587 u_int64_t pfrts_match;
588 u_int64_t pfrts_nomatch;
589 long pfrts_tzero;
590 int pfrts_cnt;
591 int pfrts_refcnt[PFR_REFCNT_MAX];
592 };
593 #define pfrts_name pfrts_t.pfrt_name
594 #define pfrts_flags pfrts_t.pfrt_flags
595 .Ed
596 .It Dv DIOCRCLRTSTATS Fa "struct pfioc_table *io"
597 Clear the statistics of one or more tables.
598 On entry,
599 .Va pfrio_buffer
600 must point to an array of
601 .Vt struct pfr_table
602 containing at least
603 .Vt pfrio_size
604 elements.
605 .Vt pfrio_esize
606 must be the size of
607 .Vt struct pfr_table .
608 On exit,
609 .Va pfrio_nzero
610 contains the number of tables effectively cleared.
611 .It Dv DIOCRCLRADDRS Fa "struct pfioc_table *io"
612 Clear all addresses in a table.
613 On entry,
614 .Va pfrio_table
615 contains the table to clear.
616 On exit,
617 .Va pfrio_ndel
618 contains the number of addresses removed.
619 .It Dv DIOCRADDADDRS Fa "struct pfioc_table *io"
620 Add one or more addresses to a table.
621 On entry,
622 .Va pfrio_table
623 contains the table ID and
624 .Va pfrio_buffer
625 must point to an array of
626 .Vt struct pfr_addr
627 containing at least
628 .Vt pfrio_size
629 elements to add to the table.
630 .Vt pfrio_esize
631 must be the size of
632 .Vt struct pfr_addr .
633 On exit,
634 .Va pfrio_nadd
635 contains the number of addresses effectively added.
636 .Bd -literal
637 struct pfr_addr {
638 union {
639 struct in_addr _pfra_ip4addr;
640 struct in6_addr _pfra_ip6addr;
641 } pfra_u;
642 u_int8_t pfra_af;
643 u_int8_t pfra_net;
644 u_int8_t pfra_not;
645 u_int8_t pfra_fback;
646 };
647 #define pfra_ip4addr pfra_u._pfra_ip4addr
648 #define pfra_ip6addr pfra_u._pfra_ip6addr
649 .Ed
650 .It Dv DIOCRDELADDRS Fa "struct pfioc_table *io"
651 Delete one or more addresses from a table.
652 On entry,
653 .Va pfrio_table
654 contains the table ID and
655 .Va pfrio_buffer
656 must point to an array of
657 .Vt struct pfr_addr
658 containing at least
659 .Vt pfrio_size
660 elements to delete from the table.
661 .Vt pfrio_esize
662 must be the size of
663 .Vt struct pfr_addr .
664 On exit,
665 .Va pfrio_ndel
666 contains the number of addresses effectively deleted.
667 .It Dv DIOCRSETADDRS Fa "struct pfioc_table *io"
668 Replace the content of a table by a new address list.
669 This is the most complicated command, which uses all the structure members.
670 .Pp
671 On entry,
672 .Va pfrio_table
673 contains the table ID and
674 .Va pfrio_buffer
675 must point to an array of
676 .Vt struct pfr_addr
677 containing at least
678 .Vt pfrio_size
679 elements which become the new contents of the table.
680 .Vt pfrio_esize
681 must be the size of
682 .Vt struct pfr_addr .
683 Additionally, if
684 .Va pfrio_size2
685 is non-zero,
686 .Va pfrio_buffer[pfrio_size..pfrio_size2]
687 must be a writeable buffer, into which the kernel can copy the
688 addresses that have been deleted during the replace operation.
689 On exit,
690 .Va pfrio_ndel ,
691 .Va pfrio_nadd ,
692 and
693 .Va pfrio_nchange
694 contain the number of addresses deleted, added, and changed by the
695 kernel.
696 If
697 .Va pfrio_size2
698 was set on entry,
699 .Va pfrio_size2
700 will point to the size of the buffer used, exactly like
701 .Dv DIOCRGETADDRS .
702 .It Dv DIOCRGETADDRS Fa "struct pfioc_table *io"
703 Get all the addresses of a table.
704 On entry,
705 .Va pfrio_table
706 contains the table ID and
707 .Va pfrio_buffer[pfrio_size]
708 contains a valid writeable buffer for
709 .Vt pfr_addr
710 structures.
711 On exit,
712 .Va pfrio_size
713 contains the number of addresses written into the buffer.
714 If the buffer was too small, the kernel does not store anything but just
715 returns the required buffer size, without returning an error.
716 .It Dv DIOCRGETASTATS Fa "struct pfioc_table *io"
717 This call is like
718 .Dv DIOCRGETADDRS
719 but is used to get an array of
720 .Vt pfr_astats
721 structures.
722 .Bd -literal
723 struct pfr_astats {
724 struct pfr_addr pfras_a;
725 u_int64_t pfras_packets
726 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
727 u_int64_t pfras_bytes
728 [PFR_DIR_MAX][PFR_OP_ADDR_MAX];
729 long pfras_tzero;
730 };
731 .Ed
732 .It Dv DIOCRCLRASTATS Fa "struct pfioc_table *io"
733 Clear the statistics of one or more addresses.
734 On entry,
735 .Va pfrio_table
736 contains the table ID and
737 .Va pfrio_buffer
738 must point to an array of
739 .Vt struct pfr_addr
740 containing at least
741 .Vt pfrio_size
742 elements to be cleared from the table.
743 .Vt pfrio_esize
744 must be the size of
745 .Vt struct pfr_addr .
746 On exit,
747 .Va pfrio_nzero
748 contains the number of addresses effectively cleared.
749 .It Dv DIOCRTSTADDRS Fa "struct pfioc_table *io"
750 Test if the given addresses match a table.
751 On entry,
752 .Va pfrio_table
753 contains the table ID and
754 .Va pfrio_buffer
755 must point to an array of
756 .Vt struct pfr_addr
757 containing at least
758 .Vt pfrio_size
759 elements, each of which will be tested for a match in the table.
760 .Vt pfrio_esize
761 must be the size of
762 .Vt struct pfr_addr .
763 On exit, the kernel updates the
764 .Vt pfr_addr
765 array by setting the
766 .Va pfra_fback
767 member appropriately.
768 .It Dv DIOCRSETTFLAGS Fa "struct pfioc_table *io"
769 Change the
770 .Dv PFR_TFLAG_CONST
771 or
772 .Dv PFR_TFLAG_PERSIST
773 flags of a table.
774 On entry,
775 .Va pfrio_buffer
776 must point to an array of
777 .Vt struct pfr_table
778 containing at least
779 .Vt pfrio_size
780 elements.
781 .Va pfrio_esize
782 must be the size of
783 .Vt struct pfr_table .
784 .Va pfrio_setflag
785 must contain the flags to add, while
786 .Va pfrio_clrflag
787 must contain the flags to remove.
788 On exit,
789 .Va pfrio_nchange
790 and
791 .Va pfrio_ndel
792 contain the number of tables altered or deleted by the kernel.
793 Yes, tables can be deleted if one removes the
794 .Dv PFR_TFLAG_PERSIST
795 flag of an unreferenced table.
796 .It Dv DIOCRINADEFINE Fa "struct pfioc_table *io"
797 Defines a table in the inactive set.
798 On entry,
799 .Va pfrio_table
800 contains the table ID and
801 .Va pfrio_buffer[pfrio_size]
802 contains an array of
803 .Vt pfr_addr
804 structures to put in the table.
805 A valid ticket must also be supplied to
806 .Va pfrio_ticket .
807 On exit,
808 .Va pfrio_nadd
809 contains 0 if the table was already defined in the inactive list
810 or 1 if a new table has been created.
811 .Va pfrio_naddr
812 contains the number of addresses effectively put in the table.
813 .It Dv DIOCXBEGIN Fa "struct pfioc_trans *io"
814 .Bd -literal
815 struct pfioc_trans {
816 int size; /* number of elements */
817 int esize; /* size of each element in bytes */
818 struct pfioc_trans_e {
819 int rs_num;
820 char anchor[MAXPATHLEN];
821 u_int32_t ticket;
822 } *array;
823 };
824 .Ed
825 .Pp
826 Clear all the inactive rulesets specified in the
827 .Vt pfioc_trans_e
828 array.
829 For each ruleset, a ticket is returned for subsequent "add rule" ioctls,
830 as well as for the
831 .Dv DIOCXCOMMIT
832 and
833 .Dv DIOCXROLLBACK
834 calls.
835 .Pp
836 Ruleset types, identified by
837 .Va rs_num ,
838 include the following:
839 .Pp
840 .Bl -tag -width PF_RULESET_FILTER -offset ind -compact
841 .It Dv PF_RULESET_SCRUB
842 Scrub (packet normalization) rules.
843 .It Dv PF_RULESET_FILTER
844 Filter rules.
845 .It Dv PF_RULESET_NAT
846 NAT (Network Address Translation) rules.
847 .It Dv PF_RULESET_BINAT
848 Bidirectional NAT rules.
849 .It Dv PF_RULESET_RDR
850 Redirect rules.
851 .It Dv PF_RULESET_ALTQ
852 ALTQ disciplines.
853 .It Dv PF_RULESET_TABLE
854 Address tables.
855 .El
856 .It Dv DIOCXCOMMIT Fa "struct pfioc_trans *io"
857 Atomically switch a vector of inactive rulesets to the active rulesets.
858 This call is implemented as a standard two-phase commit, which will either
859 fail for all rulesets or completely succeed.
860 All tickets need to be valid.
861 This ioctl returns
862 .Er EBUSY
863 if another process is concurrently updating some of the same rulesets.
864 .It Dv DIOCXROLLBACK Fa "struct pfioc_trans *io"
865 Clean up the kernel by undoing all changes that have taken place on the
866 inactive rulesets since the last
867 .Dv DIOCXBEGIN .
868 .Dv DIOCXROLLBACK
869 will silently ignore rulesets for which the ticket is invalid.
870 .It Dv DIOCSETHOSTID Fa "u_int32_t *hostid"
871 Set the host ID, which is used by
872 .Xr pfsync 4
873 to identify which host created state table entries.
874 .It Dv DIOCOSFPFLUSH
875 Flush the passive OS fingerprint table.
876 .It Dv DIOCOSFPADD Fa "struct pf_osfp_ioctl *io"
877 .Bd -literal
878 struct pf_osfp_ioctl {
879 struct pf_osfp_entry {
880 SLIST_ENTRY(pf_osfp_entry) fp_entry;
881 pf_osfp_t fp_os;
882 char fp_class_nm[PF_OSFP_LEN];
883 char fp_version_nm[PF_OSFP_LEN];
884 char fp_subtype_nm[PF_OSFP_LEN];
885 } fp_os;
886 pf_tcpopts_t fp_tcpopts;
887 u_int16_t fp_wsize;
888 u_int16_t fp_psize;
889 u_int16_t fp_mss;
890 u_int16_t fp_flags;
891 u_int8_t fp_optcnt;
892 u_int8_t fp_wscale;
893 u_int8_t fp_ttl;
894 int fp_getnum;
895 };
896 .Ed
897 .Pp
898 Add a passive OS fingerprint to the table.
899 Set
900 .Va fp_os.fp_os
901 to the packed fingerprint,
902 .Va fp_os.fp_class_nm
903 to the name of the class (Linux, Windows, etc),
904 .Va fp_os.fp_version_nm
905 to the name of the version (NT, 95, 98), and
906 .Va fp_os.fp_subtype_nm
907 to the name of the subtype or patchlevel.
908 The members
909 .Va fp_mss ,
910 .Va fp_wsize ,
911 .Va fp_psize ,
912 .Va fp_ttl ,
913 .Va fp_optcnt ,
914 and
915 .Va fp_wscale
916 are set to the TCP MSS, the TCP window size, the IP length, the IP TTL,
917 the number of TCP options, and the TCP window scaling constant of the
918 TCP SYN packet, respectively.
919 .Pp
920 The
921 .Va fp_flags
922 member is filled according to the
923 .Aq Pa net/pfvar.h
924 include file
925 .Dv PF_OSFP_*
926 defines.
927 The
928 .Va fp_tcpopts
929 member contains packed TCP options.
930 Each option uses
931 .Dv PF_OSFP_TCPOPT_BITS
932 bits in the packed value.
933 Options include any of
934 .Dv PF_OSFP_TCPOPT_NOP ,
935 .Dv PF_OSFP_TCPOPT_SACK ,
936 .Dv PF_OSFP_TCPOPT_WSCALE ,
937 .Dv PF_OSFP_TCPOPT_MSS ,
938 or
939 .Dv PF_OSFP_TCPOPT_TS .
940 .Pp
941 The
942 .Va fp_getnum
943 member is not used with this ioctl.
944 .Pp
945 The structure's slack space must be zeroed for correct operation;
946 .Xr memset 3
947 the whole structure to zero before filling and sending to the kernel.
948 .It Dv DIOCOSFPGET Fa "struct pf_osfp_ioctl *io"
949 Get the passive OS fingerprint number
950 .Va fp_getnum
951 from the kernel's fingerprint list.
952 The rest of the structure members will come back filled.
953 Get the whole list by repeatedly incrementing the
954 .Va fp_getnum
955 number until the ioctl returns
956 .Er EBUSY .
957 .It Dv DIOCGETSRCNODES Fa "struct pfioc_src_nodes *psn"
958 .Bd -literal
959 struct pfioc_src_nodes {
960 int psn_len;
961 union {
962 caddr_t psu_buf;
963 struct pf_src_node *psu_src_nodes;
964 } psn_u;
965 #define psn_buf psn_u.psu_buf
966 #define psn_src_nodes psn_u.psu_src_nodes
967 };
968 .Ed
969 .Pp
970 Get the list of source nodes kept by sticky addresses and source
971 tracking.
972 The ioctl must be called once with
973 .Va psn_len
974 set to 0.
975 If the ioctl returns without error,
976 .Va psn_len
977 will be set to the size of the buffer required to hold all the
978 .Va pf_src_node
979 structures held in the table.
980 A buffer of this size should then be allocated, and a pointer to this buffer
981 placed in
982 .Va psn_buf .
983 The ioctl must then be called again to fill this buffer with the actual
984 source node data.
985 After that call,
986 .Va psn_len
987 will be set to the length of the buffer actually used.
988 .It Dv DIOCCLRSRCNODES
989 Clear the tree of source tracking nodes.
990 .It Dv DIOCIGETIFACES Fa "struct pfioc_iface *io"
991 Get the list of interfaces and interface drivers known to
992 .Nm .
993 All the ioctls that manipulate interfaces
994 use the same structure described below:
995 .Bd -literal
996 struct pfioc_iface {
997 char pfiio_name[IFNAMSIZ];
998 void *pfiio_buffer;
999 int pfiio_esize;
1000 int pfiio_size;
1001 int pfiio_nzero;
1002 int pfiio_flags;
1003 };
1004 .Ed
1005 .Pp
1006 If not empty,
1007 .Va pfiio_name
1008 can be used to restrict the search to a specific interface or driver.
1009 .Va pfiio_buffer[pfiio_size]
1010 is the user-supplied buffer for returning the data.
1011 On entry,
1012 .Va pfiio_size
1013 contains the number of
1014 .Vt pfi_kif
1015 entries that can fit into the buffer.
1016 The kernel will replace this value by the real number of entries it wants
1017 to return.
1018 .Va pfiio_esize
1019 should be set to
1020 .Li sizeof(struct pfi_kif) .
1021 .Pp
1022 The data is returned in the
1023 .Vt pfi_kif
1024 structure described below:
1025 .Bd -literal
1026 struct pfi_kif {
1027 RB_ENTRY(pfi_kif) pfik_tree;
1028 char pfik_name[IFNAMSIZ];
1029 u_int64_t pfik_packets[2][2][2];
1030 u_int64_t pfik_bytes[2][2][2];
1031 u_int32_t pfik_tzero;
1032 int pfik_flags;
1033 struct pf_state_tree_lan_ext pfik_lan_ext;
1034 struct pf_state_tree_ext_gwy pfik_ext_gwy;
1035 TAILQ_ENTRY(pfi_kif) pfik_w_states;
1036 void *pfik_ah_cookie;
1037 struct ifnet *pfik_ifp;
1038 struct ifg_group *pfik_group;
1039 int pfik_states;
1040 int pfik_rules;
1041 TAILQ_HEAD(, pfi_dynaddr) pfik_dynaddrs;
1042 };
1043 .Ed
1044 .It Dv DIOCSETIFFLAG Fa "struct pfioc_iface *io"
1045 Set the user setable flags (described above) of the
1046 .Nm
1047 internal interface description.
1048 The filtering process is the same as for
1049 .Dv DIOCIGETIFACES .
1050 .Bd -literal
1051 #define PFI_IFLAG_SKIP 0x0100 /* skip filtering on interface */
1052 .Ed
1053 .It Dv DIOCCLRIFFLAG Fa "struct pfioc_iface *io"
1054 Works as
1055 .Dv DIOCSETIFFLAG
1056 above but clears the flags.
1057 .El
1058 .Sh FILES
1059 .Bl -tag -width /dev/pf -compact
1060 .It Pa /dev/pf
1061 packet filtering device.
1062 .El
1063 .Sh EXAMPLES
1064 The following example demonstrates how to use the
1065 .Dv DIOCNATLOOK
1066 command to find the internal host/port of a NATed connection:
1067 .Bd -literal
1068 #include \*[Lt]sys/types.h\*[Gt]
1069 #include \*[Lt]sys/socket.h\*[Gt]
1070 #include \*[Lt]sys/ioctl.h\*[Gt]
1071 #include \*[Lt]sys/fcntl.h\*[Gt]
1072 #include \*[Lt]net/if.h\*[Gt]
1073 #include \*[Lt]netinet/in.h\*[Gt]
1074 #include \*[Lt]net/pfvar.h\*[Gt]
1075 #include \*[Lt]err.h\*[Gt]
1076 #include \*[Lt]stdio.h\*[Gt]
1077 #include \*[Lt]stdlib.h\*[Gt]
1079 u_int32_t
1080 read_address(const char *s)
1081 {
1082 int a, b, c, d;
1084 sscanf(s, "%i.%i.%i.%i", \*[Am]a, \*[Am]b, \*[Am]c, \*[Am]d);
1085 return htonl(a \*[Lt]\*[Lt] 24 | b \*[Lt]\*[Lt] 16 | c \*[Lt]\*[Lt] 8 | d);
1086 }
1088 void
1089 print_address(u_int32_t a)
1090 {
1091 a = ntohl(a);
1092 printf("%d.%d.%d.%d", a \*[Gt]\*[Gt] 24 \*[Am] 255, a \*[Gt]\*[Gt] 16 \*[Am] 255,
1093 a \*[Gt]\*[Gt] 8 \*[Am] 255, a \*[Am] 255);
1094 }
1096 int
1097 main(int argc, char *argv[])
1098 {
1099 struct pfioc_natlook nl;
1100 int dev;
1102 if (argc != 5) {
1103 printf("%s \*[Lt]gwy addr\*[Gt] \*[Lt]gwy port\*[Gt] \*[Lt]ext addr\*[Gt] \*[Lt]ext port\*[Gt]\\n",
1104 argv[0]);
1105 return 1;
1106 }
1108 dev = open("/dev/pf", O_RDWR);
1109 if (dev == -1)
1110 err(1, "open(\\"/dev/pf\\") failed");
1112 memset(\*[Am]nl, 0, sizeof(struct pfioc_natlook));
1113 nl.saddr.v4.s_addr = read_address(argv[1]);
1114 nl.sport = htons(atoi(argv[2]));
1115 nl.daddr.v4.s_addr = read_address(argv[3]);
1116 nl.dport = htons(atoi(argv[4]));
1117 nl.af = AF_INET;
1118 nl.proto = IPPROTO_TCP;
1119 nl.direction = PF_IN;
1121 if (ioctl(dev, DIOCNATLOOK, \*[Am]nl))
1122 err(1, "DIOCNATLOOK");
1124 printf("internal host ");
1125 print_address(nl.rsaddr.v4.s_addr);
1126 printf(":%u\\n", ntohs(nl.rsport));
1127 return 0;
1128 }
1129 .Ed
1130 .Sh SEE ALSO
1131 .Xr ioctl 2 ,
1132 .Xr bridge 4 ,
1133 .Xr pflog 4 ,
1134 .Xr pfsync 4 ,
1135 .Xr pfctl 8 ,
1136 .Xr altq 9
1137 .Sh HISTORY
1138 The
1139 .Nm
1140 packet filtering mechanism first appeared in
1141 .Ox 3.0 .
1142 .Sh CAVEATS
1143 The following functionality is missing from
1144 .Nm
1145 in this version of
1146 .Nx :
1147 .Bl -bullet -offset indent
1148 .It
1149 The
1150 .Em group
1151 keyword is not supported.
1152 .El