Document verbose mode with tables (statistics).

1 files changed, 114 insertions, 2 deletions

diff --git a/sbin/pfctl/pfctl.8 b/sbin/pfctl/pfctl.8
index ce165497eab..8486c28a72e 100644
--- a/sbin/pfctl/pfctl.8
+++ b/sbin/pfctl/pfctl.8
@@ -1,4 +1,4 @@
-.\" $OpenBSD: pfctl.8,v 1.75 2003/02/14 09:44:31 henning Exp $
+.\" $OpenBSD: pfctl.8,v 1.76 2003/02/14 11:04:22 cedric Exp $
 .\"
 .\" Copyright (c) 2001 Kjell Wooding.  All rights reserved.
 .\"
@@ -259,7 +259,9 @@ Test if the given addresses match a table.
 Clear all the statistics of a table.
 .It Fl T Ar load
 Load only the table definitions from pf.conf.
-Used in "pfctl -Tl -f pf.conf".
+Used in conjunction with the
+.Fl f
+flag, like in: "pfctl -Tl -f pf.conf".
 .El
 .Pp
 For the
@@ -294,12 +296,122 @@ The address match (test operation only).
 The address/network is duplicated and therefore ignored.
 .It Y
 The address/network cannot be added/deleted due to conflicting "!" attribute.
+.It Z
+The address/network has been cleared (statistics).
+.El
+.Pp
+Each table maintains a set of counters that can be retrieved using the
+.Fl v
+flag of
+.Nm pfctl .
+For example, the following command define a wide open firewall which will keep
+track of packets going to or coming from OpenBSD ftp server.
+The following commands configure the firewall and send 10 pings to the ftp
+server:
+.Pp
+.Bd -literal -offset indent
+.Ic # echo \&"table <test> { ftp.openbsd.org }\en\&"\e
+.Ic > \&"pass out to <test> keep state\&" Xo
+.Ic \&| pfctl -f-
+.Xc
+.Ic # ping -qc10 ftp.openbsd.org
+.Ed
+.Pp
+We can now use the table
+.Ar show
+command to output, for each address and packet direction, the number of packets
+and bytes that are being passed or blocked by rules referencing the table.
+The time at which the current accounting started is also shown with the
+.Ar Cleared
+line.
+.Pp
+.Bd -literal -offset indent
+.Ic # pfctl -t test -vTshow
+.Ic \ \ 129.128.5.191
+.Ic \ \ \ \ Cleared: \ \ \ \ Thu Feb 13 18:55:18 2003
+.Ic \ \ \ \ In/Block: \ \ \ [ Packets: 0 \ \ \ \ \ \ \ Bytes: 0 \ \ \ \ \ \ \ ]
+.Ic \ \ \ \ In/Pass: \ \ \ \ [ Packets: 10 \ \ \ \ \ \ Bytes: 840 \ \ \ \ \ ]
+.Ic \ \ \ \ Out/Block: \ \ [ Packets: 0 \ \ \ \ \ \ \ Bytes: 0 \ \ \ \ \ \ \ ]
+.Ic \ \ \ \ Out/Pass: \ \ \ [ Packets: 10 \ \ \ \ \ \ Bytes: 840 \ \ \ \ \ ]
+.Ed
+.Pp
+Similarly, It is possible to view global information about the tables
+by using two times the
+.Fl v
+modifier and the
+.Ar show Tables
+command. This will display the number of addresses on each table,
+the number of rules which reference the table, and the global
+packet statistics for the whole table:
+.Pp
+.Bd -literal -offset indent
+.Ic # pfctl -vvsTables
+.Ic --a-r   test
+.Ic \ \ \ \ Addresses: \ \ 1
+.Ic \ \ \ \ References: \ 1
+.Ic \ \ \ \ Cleared: \ \ \ \ Thu Feb 13 18:55:18 2003
+.Ic \ \ \ \ Evaluations: [\ NoMatch: 3496 \ \ \ \ Match: 1 \ \ \ \ \ \ \ ]
+.Ic \ \ \ \ In/Block: \ \ \ [ Packets: 0 \ \ \ \ \ \ \ Bytes: 0 \ \ \ \ \ \ \ ]
+.Ic \ \ \ \ In/Pass: \ \ \ \ [ Packets: 10 \ \ \ \ \ \ Bytes: 840 \ \ \ \ \ ]
+.Ic \ \ \ \ In/XPass: \ \ \ [ Packets: 0 \ \ \ \ \ \ \ Bytes: 0 \ \ \ \ \ \ \ ]
+.Ic \ \ \ \ Out/Block: \ \ [ Packets: 0 \ \ \ \ \ \ \ Bytes: 0 \ \ \ \ \ \ \ ]
+.Ic \ \ \ \ Out/Pass: \ \ \ [ Packets: 10 \ \ \ \ \ \ Bytes: 840 \ \ \ \ \ ]
+.Ic \ \ \ \ Out/XPass: \ \ [ Packets: 0 \ \ \ \ \ \ \ Bytes: 0 \ \ \ \ \ \ \ ]
+.Ed
+.Pp
+As we can see here, only one packet - the initial ping request - matched the
+table; but all packets passing at the result of the state are correctly
+accounted for.
+Reloading the table(s) will not affect packet accounting in any way; however,
+in this version, the state accounting will unfortunately stop if the rules
+are reloaded or flushed.
+The two
+.Ar XPass
+counters are incremented instead of the
+.Ar Pass
+counters when a \&"stateful\&" packet is passed but doesn't match the table
+anymore.
+This will happen in our example if someone flush the table while the ping
+command is
+running.
+.Pp
+When used with a single
+.Fl v ,
+.Nm pfctl
+will only display the first line containing the table flags and name.
+The flags are defined as follows:
+.Pp
+.Bl -tag -width XXX -compact
+.It c
+For constant tables, which cannot be altered outside
+.Nm pf.conf .
+.It p
+For persistant tables, which don't get automatically flushed when no rules
+refers to them.
+.It a
+For tables which are part of the
+.Ar active
+tableset. Tables without this flag do not really exist, cannot contain addresses, and are
+not listed if no
+.Fl v
+flag is given.
+.It i
+For tables which are part of the
+.Ar inactive
+tableset. This flag can only be witnessed briefly during the loading of
+.Nm pf.conf .
+If this flag appear for a long time, that mean
+.Nm pfctl
+failed badly.
+.It r
+For tables which are referenced (used) by rules.
 .El
 .It Fl v
 Produce more verbose output.
 A second use of
 .Fl v
 will produce an additional level of more verbose output.
+See previous section for its effect on table commands.
 .It Fl x Ar level
 Set the debug level to one of the following.
 Level names may be abbreviated: