| blob | ba47f787255aeece0b885d3438d4a6a20503910d |
1 '\" te
2 .\" To view license terms, attribution, and copyright for IP Filter, the default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Solaris operating environment has been installed anywhere other than the default, modify the given path to access the file at the installed
3 .\" location.
4 .\" Portions Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved.
5 .\" Portions Copyright (c) 2013, Joyent, Inc. All Rights Reserved.
6 .TH IPFSTAT 1M "Oct 30, 2013"
7 .SH NAME
8 ipfstat \- reports on packet filter statistics and filter list
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBipfstat\fR [\fB-6aACdfghIilnoRstv\fR]
13 .fi
15 .LP
16 .nf
17 \fBipfstat\fR [\fB-C\fR] [\fB-D\fR \fIaddrport\fR] [\fB-P\fR \fIprotocol\fR] [\fB-S\fR \fIaddrport\fR]
18 [\fB-T\fR \fIrefreshtime\fR] [\fB-G\fR | \fB-z\fR \fIzonename\fR]
19 .fi
21 .SH DESCRIPTION
22 .LP
23 The \fBipfstat\fR command is part of a suite of commands associated with the
24 Solaris IP Filter feature. See \fBipfilter\fR(5).
25 .sp
26 .LP
27 The \fBipfstat\fR command examines \fB/dev/kmem\fR using the symbols
28 \fB_fr_flags\fR, \fB_frstats\fR, \fB_filterin\fR, and \fB_filterout\fR. To run
29 and work, it needs to be able to read both \fB/dev/kmem\fR and the kernel
30 itself.
31 .sp
32 .LP
33 The default behavior of \fBipfstat\fR is to retrieve and display the statistics
34 which have been accumulated over time as the kernel has put packets through the
35 filter.
36 .sp
37 .LP
38 The role of \fBipfstat\fR is to display current kernel statistics gathered as a
39 result of applying the filters in place (if any) to packets going in and out of
40 the kernel. This is the default operation when no command line parameters are
41 present. When supplied with either \fB-i\fR or \fB-o\fR, \fBipfstat\fR will
42 retrieve and display the appropriate list of filter rules currently installed
43 and in use by the kernel.
44 .sp
45 .LP
46 \fBipfstat\fR uses kernel device files to obtain information. The default
47 permissions of these files require \fBipfstat\fR to be run as root for all
48 operations.
49 .sp
50 .LP
51 The \fBipfstat\fR command supports the \fBkstat\fR(3KSTAT) kernel facility.
52 Because of this support, as an alternative to \fBipfstat\fR, you can use
53 \fBkstat\fR(1M). For example:
54 .sp
55 .LP
56 # kstat \(hym ipf
57 .sp
58 .LP
59 Using the \fBipfstat\fR \fB-t\fR option causes \fBipfstat\fR to enter the state
60 top mode. In this mode the state table is displayed similarly to the way the
61 Unix \fBtop\fR utility displays the process table. The \fB-C\fR, \fB-D\fR,
62 \fB-P\fR, \fB-S\fR and \fB-T\fR command line options can be used to restrict
63 the state entries that will be shown and to specify the frequency of display
64 updates.
65 .sp
66 .LP
67 In state top mode, use the following keys to influence the displayed
68 information:
69 .sp
70 .ne 2
71 .na
72 \fB\fBd\fR\fR
73 .ad
74 .RS 5n
75 Select information to display.
76 .RE
78 .sp
79 .ne 2
80 .na
81 \fB\fBl\fR\fR
82 .ad
83 .RS 5n
84 Redraw the screen.
85 .RE
87 .sp
88 .ne 2
89 .na
90 \fB\fBq\fR\fR
91 .ad
92 .RS 5n
93 Quit the program.
94 .RE
96 .sp
97 .ne 2
98 .na
99 \fB\fBs\fR\fR
100 .ad
101 .RS 5n
102 Switch between different sorting criteria.
103 .RE
105 .sp
106 .ne 2
107 .na
108 \fB\fBr\fR\fR
109 .ad
110 .RS 5n
111 Reverse the sorting criteria.
112 .RE
114 .sp
115 .LP
116 States can be sorted by protocol number, by number of IP packets, by number of
117 bytes, and by time-to-live of the state entry. The default is to sort by the
118 number of bytes. States are sorted in descending order, but you can use the
119 \fBr\fR key to sort them in ascending order.
120 .sp
121 .LP
122 It is not possible to interactively change the source, destination, and
123 protocol filters or the refresh frequency. This must be done from the command
124 line.
125 .sp
126 .LP
127 The screen must have at least 80 columns for correct display. However,
128 \fBipfstat\fR does not check the screen width.
129 .sp
130 .LP
131 Only the first \fIX\fR-5 entries that match the sort and filter criteria are
132 displayed (where \fIX\fR is the number of rows on the display). There is no way
133 to see additional entries.
134 .SH OPTIONS
135 .LP
136 The following options are supported:
137 .sp
138 .ne 2
139 .na
140 \fB\fB-6\fR\fR
141 .ad
142 .RS 18n
143 Display filter lists and states for IPv6, if available. This option might
144 change in the future.
145 .RE
147 .sp
148 .ne 2
149 .na
150 \fB\fB-a\fR\fR
151 .ad
152 .RS 18n
153 Display the accounting filter list and show bytes counted against each rule.
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fB-A\fR\fR
160 .ad
161 .RS 18n
162 Display packet authentication statistics.
163 .RE
165 .sp
166 .ne 2
167 .na
168 \fB\fB-C\fR\fR
169 .ad
170 .RS 18n
171 Valid only in combination with \fB-t\fR. Display "closed" states as well in the
172 top. Normally, a TCP connection is not displayed when it reaches the
173 \fBCLOSE_WAIT\fR protocol state. With this option enabled, all state entries
174 are displayed.
175 .RE
177 .sp
178 .ne 2
179 .na
180 \fB\fB-d\fR\fR
181 .ad
182 .RS 18n
183 Produce debugging output when displaying data.
184 .RE
186 .sp
187 .ne 2
188 .na
189 \fB\fB-D\fR \fIaddrport\fR\fR
190 .ad
191 .RS 18n
192 Valid only in combination with \fB-t\fR. Limit the state top display to show
193 only state entries whose destination IP address and port match the
194 \fIaddrport\fR argument. The \fIaddrport\fR specification is of the form
195 \fIipaddress\fR[,\fIport\fR]. The \fIipaddress\fR and \fIport\fR should be
196 either numerical or the string \fBany\fR (specifying any IP address and any
197 port, in that order). If the \fB-D\fR option is not specified, it defaults to
198 \fB-D\fR \fBany,any\fR.
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fB\fB-f\fR\fR
205 .ad
206 .RS 18n
207 Show fragment state information (statistics) and held state information (in the
208 kernel) if any is present.
209 .RE
211 .sp
212 .ne 2
213 .na
214 \fB\fB-g\fR\fR
215 .ad
216 .RS 18n
217 Show groups currently configured (both active and inactive).
218 .RE
220 .sp
221 .ne 2
222 .na
223 \fB\fB-h\fR\fR
224 .ad
225 .RS 18n
226 Show per-rule the number of times each one scores a "hit". For use in
227 combination with \fB-i\fR.
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fB-i\fR\fR
234 .ad
235 .RS 18n
236 Display the filter list used for the input side of the kernel IP processing.
237 .RE
239 .sp
240 .ne 2
241 .na
242 \fB\fB-I\fR\fR
243 .ad
244 .RS 18n
245 Swap between retrieving \fBinactive\fR/\fBactive\fR filter list details. For
246 use in combination with \fB-i\fR.
247 .RE
249 .sp
250 .ne 2
251 .na
252 \fB\fB-l\fR\fR
253 .ad
254 .RS 18n
255 When used with \fB-s\fR, show a list of active state entries (no statistics).
256 .RE
258 .sp
259 .ne 2
260 .na
261 \fB\fB-n\fR\fR
262 .ad
263 .RS 18n
264 Show the rule number for each rule as it is printed.
265 .RE
267 .sp
268 .ne 2
269 .na
270 \fB\fB-o\fR\fR
271 .ad
272 .RS 18n
273 Display the filter list used for the output side of the kernel IP processing.
274 .RE
276 .sp
277 .ne 2
278 .na
279 \fB\fB-P\fR \fIprotocol\fR\fR
280 .ad
281 .RS 18n
282 Valid only in combination with \fB-t\fR. Limit the state top display to show
283 only state entries that match a specific protocol. The argument can be a
284 protocol name (as defined in \fB/etc/protocols\fR) or a protocol number. If
285 this option is not specified, state entries for any protocol are specified.
286 .RE
288 .sp
289 .ne 2
290 .na
291 \fB\fB-R\fR\fR
292 .ad
293 .RS 18n
294 Disable both IP address-to-hostname resolution and port number-to-service name
295 resolution.
296 .RE
298 .sp
299 .ne 2
300 .na
301 \fB\fB-S\fR \fIaddrport\fR\fR
302 .ad
303 .RS 18n
304 Valid only in combination with \fB-t\fR. Limit the state top display to show
305 only state entries whose source IP address and port match the \fIaddrport\fR
306 argument. The \fIaddrport\fR specification is of the form
307 \fIipaddress\fR[,\fIport\fR]. The \fIipaddress\fR and \fIport\fR should be
308 either numerical or the string \fBany\fR (specifying any IP address and any
309 port, in that order). If the \fB-S\fR option is not specified, it defaults to
310 \fB-S\fR \fBany,any\fR.
311 .RE
313 .sp
314 .ne 2
315 .na
316 \fB\fB-s\fR\fR
317 .ad
318 .RS 18n
319 Show packet/flow state information (statistics only).
320 .RE
322 .sp
323 .ne 2
324 .na
325 \fB\fB-T\fR \fIrefreshtime\fR\fR
326 .ad
327 .RS 18n
328 Valid only in combination with \fB-t\fR. Specifies how often the state
329 \fBtop\fR display should be updated. The refresh time is the number of seconds
330 between an update. Any positive integer can be used. The default (and minimal
331 update time) is 1.
332 .RE
334 .sp
335 .ne 2
336 .na
337 \fB\fB-t\fR\fR
338 .ad
339 .RS 18n
340 Show the state table in a way similar to the way the Unix utility, \fBtop\fR,
341 shows the process table. States can be sorted in a number of different ways.
342 .RE
344 .sp
345 .ne 2
346 .na
347 \fB\fB-v\fR\fR
348 .ad
349 .RS 18n
350 Turn verbose mode on. Displays additional debugging information.
351 .RE
353 .sp
354 .ne 2
355 .na
356 \fB\fB-z\fR \fIzonename\fR\fR
357 .ad
358 .RS 18n
359 Report the in-zone statistics for the specified zone. If neither this option
360 nor \fB-G\fR is specified, the current zone is used. This command is only
361 available in the Global Zone. See \fBZONES\fR in \fBipf\fR(1m) for more
362 information.
363 .RE
365 .sp
366 .ne 2
367 .na
368 \fB\fB-G\fR \fIzonename\fR\fR
369 .ad
370 .RS 18n
371 Report the global zone controlled statistics for the specified zone. If
372 neither this option nor \fB-z\fR is specified, the current zone is used. This
373 command is only available in the Global Zone. See \fBZONES\fR in \fBipf\fR(1m)
374 for more information.
375 .RE
377 .SH FILES
378 .RS +4
379 .TP
380 .ie t \(bu
381 .el o
382 \fB/dev/kmem\fR
383 .RE
384 .RS +4
385 .TP
386 .ie t \(bu
387 .el o
388 \fB/dev/ksyms\fR
389 .RE
390 .RS +4
391 .TP
392 .ie t \(bu
393 .el o
394 \fB/dev/ipl\fR
395 .RE
396 .RS +4
397 .TP
398 .ie t \(bu
399 .el o
400 \fB/dev/ipstate\fR
401 .RE
402 .SH ATTRIBUTES
403 .LP
404 See \fBattributes\fR(5) for descriptions of the following attributes:
405 .sp
407 .sp
408 .TS
409 box;
410 c | c
411 l | l .
412 ATTRIBUTE TYPE ATTRIBUTE VALUE
413 _
414 Interface Stability Committed
415 .TE
417 .SH SEE ALSO
418 .LP
419 \fBipf\fR(1M), \fBkstat\fR(1M), \fBkstat\fR(3KSTAT), \fBattributes\fR(5),
420 \fBipfilter\fR(5), \fBzones(5)\fR
421 .sp
422 .LP
423 \fI\fR