Add the DragonFly cvs id and perform general cleanups on cvs/rcs/sccs ids. Most
[dragonfly.git] / contrib / ipfilter / man / ipfstat.8
CommitLineData
984263bc 1.\" $FreeBSD: src/contrib/ipfilter/man/ipfstat.8,v 1.3.2.4 2003/03/01 03:55:53 darrenr Exp $
1de703da 2.\" $DragonFly: src/contrib/ipfilter/man/ipfstat.8,v 1.2 2003/06/17 04:24:02 dillon Exp $
984263bc
MD
3.TH ipfstat 8
4.SH NAME
5ipfstat \- reports on packet filter statistics and filter list
6.SH SYNOPSIS
7.B ipfstat
8[
9.B \-6aAfghIinosv
10] [
11.B \-d
12<device>
13]
14
15.B ipfstat -t
16[
17.B \-C
18] [
19.B \-D
20<addrport>
21] [
22.B \-P
23<protocol>
24] [
25.B \-S
26<addrport>
27] [
28.B \-T
29<refresh time>
30] [
31.B \-d
32<device>
33]
34.SH DESCRIPTION
35.PP
36\fBipfstat\fP examines /dev/kmem using the symbols \fB_fr_flags\fP,
37\fB_frstats\fP, \fB_filterin\fP, and \fB_filterout\fP.
38To run and work, it needs to be able to read both /dev/kmem and the
39kernel itself. The kernel name defaults to \fB/kernel\fP.
40.PP
41The default behaviour of \fBipfstat\fP
42is to retrieve and display the accumulated statistics which have been
43accumulated over time as the kernel has put packets through the filter.
44.SH OPTIONS
45.TP
46.B \-6
47Display filter lists for IPv6, if available.
48.TP
49.B \-a
50Display the accounting filter list and show bytes counted against each rule.
51.TP
52.B \-A
53Display packet authentication statistics.
54.TP
55.B \-C
56This option is only valid in combination with \fB\-t\fP.
57Display "closed" states as well in the top. Normally, a TCP connection is
58not displayed when it reaches the CLOSE_WAIT protocol state. With this
59option enabled, all state entries are displayed.
60.TP
61.BR \-d \0<device>
62Use a device other than \fB/dev/ipl\fP for interfacing with the kernel.
63.TP
64.BR \-D \0<addrport>
65This option is only valid in combination with \fB\-t\fP. Limit the state top
66display to show only state entries whose destination IP address and port
67match the addport argument. The addrport specification is of the form
68ipaddress[,port]. The ipaddress and port should be either numerical or the
69string "any" (specifying any ip address resp. any port). If the \fB\-D\fP
70option is not specified, it defaults to "\fB\-D\fP any,any".
71.TP
72.B \-f
73Show fragment state information (statistics) and held state information (in
74the kernel) if any is present.
75.TP
76.B \-g
77Show groups currently configured (both active and inactive).
78.TP
79.B \-h
80Show per-rule the number of times each one scores a "hit". For use in
81combination with \fB\-i\fP.
82.TP
83.B \-i
84Display the filter list used for the input side of the kernel IP processing.
85.TP
86.B \-I
87Swap between retrieving "inactive"/"active" filter list details. For use
88in combination with \fB\-i\fP.
89.TP
90.B \-n
91Show the "rule number" for each rule as it is printed.
92.TP
93.B \-o
94Display the filter list used for the output side of the kernel IP processing.
95.TP
96.BR \-P \0<protocol>
97This option is only valid in combination with \fB\-t\fP. Limit the state top
98display to show only state entries that match a specific protocol. The
99argument can be a protocol name (as defined in \fB/etc/protocols\fP) or a
100protocol number. If this option is not specified, state entries for any
101protocol are specified.
102.TP
103.B \-s
104Show packet/flow state information (statistics only).
105.TP
106.B \-sl
107Show held state information (in the kernel) if any is present (no statistics).
108.TP
109.BR \-S \0<addrport>
110This option is only valid in combination with \fB\-t\fP. Limit the state top
111display to show only state entries whose source IP address and port match
112the addport argument. The addrport specification is of the form
113ipaddress[,port]. The ipaddress and port should be either numerical or the
114string "any" (specifying any ip address resp. any port). If the \fB\-S\fP
115option is not specified, it defaults to "\fB\-S\fP any,any".
116.TP
117.B \-t
118Show the state table in a way similar to they way \fBtop(1)\fP shows the process
119table. States can be sorted using a number of different ways. This options
120requires \fBncurses(3)\fP and needs to be compiled in. It may not be available on
121all operating systems. See below, for more information on the keys that can
122be used while ipfstat is in top mode.
123.TP
124.BR \-T \0<refreshtime>
125This option is only valid in combination with \fB\-t\fP. Specifies how often
126the state top display should be updated. The refresh time is the number of
127seconds between an update. Any positive integer can be used. The default (and
128minimal update time) is 1.
129.TP
130.B \-v
131Turn verbose mode on. Displays more debugging information.
132.SH SYNOPSIS
133The role of \fBipfstat\fP is to display current kernel statistics gathered
134as a result of applying the filters in place (if any) to packets going in and
135out of the kernel. This is the default operation when no command line
136parameters are present.
137.PP
138When supplied with either \fB\-i\fP or \fB\-o\fP, it will retrieve and display
139the appropriate list of filter rules currently installed and in use by the
140kernel.
141.SH STATE TOP
142Using the \fB\-t\fP option \fBipfstat\fP will enter the state top mode. In
143this mode the state table is displayed similar to the way \fBtop\fP displays
144the process table. The \fB\-C\fP, \fB\-D\fP, \fB\-P\fP, \fB\-S\fP and \fB\-T\fP
145commandline options can be used to restrict the state entries that will be
146shown and to specify the frequency of display updates.
147.PP
148In state top mode, the following keys can be used to influence the displayed
149information:
150.TP
151\fBd\fP select information to display.
152.TP
153\fBl\fP redraw the screen.
154.TP
155\fBq\fP quit the program.
156.TP
157\fBs\fP switch between different sorting criterion.
158.TP
159\fBr\fP reverse the sorting criterion.
160.PP
161States can be sorted by protocol number, by number of IP packets, by number
162of bytes and by time-to-live of the state entry. The default is to sort by
163the number of bytes. States are sorted in descending order, but you can use
164the \fBr\fP key to sort them in ascending order.
165.SH STATE TOP LIMITATIONS
166It is currently not possible to interactively change the source, destination
167and protocol filters or the refresh frequency. This must be done from the
168command line.
169.PP
170The screen must have at least 80 columns. This is however not checked.
171.PP
172Only the first X-5 entries that match the sort and filter criteria are
173displayed (where X is the number of rows on the display. There is no way to
174see more entries.
175.PP
176No support for IPv6
177.PP
178.SH FILES
179/dev/kmem
180.br
181/dev/ipl
182.br
183/dev/ipstate
184.br
185/kernel
186.SH SEE ALSO
187ipf(8)
188.SH BUGS
189none known.