path: root/usr/src/man/man1m/ipfstat.1m

'\" te
.\" 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
.\" location.
.\" Portions Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved.
.\" Portions Copyright (c) 2012, Joyent, Inc. All Rights Reserved.
.TH IPFSTAT 1M "Nov 26, 2012"
.SH NAME
ipfstat \- reports on packet filter statistics and filter list
.SH SYNOPSIS
.LP
.nf
\fBipfstat\fR [\fB-6aACdfghIilnoRstv\fR]
.fi

.LP
.nf
\fBipfstat\fR [\fB-C\fR] [\fB-D\fR \fIaddrport\fR] [\fB-P\fR \fIprotocol\fR] [\fB-S\fR \fIaddrport\fR]
     [\fB-T\fR \fIrefreshtime\fR] [\fB-z\fR \fIzonename\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBipfstat\fR command is part of a suite of commands associated with the
Solaris IP Filter feature. See \fBipfilter\fR(5).
.sp
.LP
The \fBipfstat\fR command examines \fB/dev/kmem\fR using the symbols
\fB_fr_flags\fR, \fB_frstats\fR, \fB_filterin\fR, and \fB_filterout\fR. To run
and work, it needs to be able to read both \fB/dev/kmem\fR and the kernel
itself.
.sp
.LP
The default behavior of \fBipfstat\fR is to retrieve and display the statistics
which have been accumulated over time as the kernel has put packets through the
filter.
.sp
.LP
The role of \fBipfstat\fR is to display current kernel statistics gathered as a
result of applying the filters in place (if any) to packets going in and out of
the kernel. This is the default operation when no command line parameters are
present. When supplied with either \fB-i\fR or \fB-o\fR, \fBipfstat\fR will
retrieve and display the appropriate list of filter rules currently installed
and in use by the kernel.
.sp
.LP
\fBipfstat\fR uses kernel device files to obtain information. The default
permissions of these files require \fBipfstat\fR to be run as root for all
operations.
.sp
.LP
The \fBipfstat\fR command supports the \fBkstat\fR(3KSTAT) kernel facility.
Because of this support, as an alternative to \fBipfstat\fR, you can use
\fBkstat\fR(1M). For example:
.sp
.LP
# kstat \(hym ipf
.sp
.LP
Using the \fBipfstat\fR \fB-t\fR option causes \fBipfstat\fR to enter the state
top mode. In this mode the state table is displayed similarly to the way the
Unix \fBtop\fR utility displays the process table. The \fB-C\fR, \fB-D\fR,
\fB-P\fR, \fB-S\fR and \fB-T\fR command line options can be used to restrict
the state entries that will be shown and to specify the frequency of display
updates.
.sp
.LP
In state top mode, use the following keys to influence the displayed
information:
.sp
.ne 2
.na
\fB\fBd\fR\fR
.ad
.RS 5n
Select information to display.
.RE

.sp
.ne 2
.na
\fB\fBl\fR\fR
.ad
.RS 5n
Redraw the screen.
.RE

.sp
.ne 2
.na
\fB\fBq\fR\fR
.ad
.RS 5n
Quit the program.
.RE

.sp
.ne 2
.na
\fB\fBs\fR\fR
.ad
.RS 5n
Switch between different sorting criteria.
.RE

.sp
.ne 2
.na
\fB\fBr\fR\fR
.ad
.RS 5n
Reverse the sorting criteria.
.RE

.sp
.LP
States can be sorted by protocol number, by number of IP packets, by number of
bytes, and by time-to-live of the state entry. The default is to sort by the
number of bytes. States are sorted in descending order, but you can use the
\fBr\fR key to sort them in ascending order.
.sp
.LP
It is not possible to interactively change the source, destination, and
protocol filters or the refresh frequency. This must be done from the command
line.
.sp
.LP
The screen must have at least 80 columns for correct display. However,
\fBipfstat\fR does not check the screen width.
.sp
.LP
Only the first \fIX\fR-5 entries that match the sort and filter criteria are
displayed (where \fIX\fR is the number of rows on the display). There is no way
to see additional entries.
.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-6\fR\fR
.ad
.RS 18n
Display filter lists and states for IPv6, if available. This option might
change in the future.
.RE

.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 18n
Display the accounting filter list and show bytes counted against each rule.
.RE

.sp
.ne 2
.na
\fB\fB-A\fR\fR
.ad
.RS 18n
Display packet authentication statistics.
.RE

.sp
.ne 2
.na
\fB\fB-C\fR\fR
.ad
.RS 18n
Valid only in combination with \fB-t\fR. Display "closed" states as well in the
top. Normally, a TCP connection is not displayed when it reaches the
\fBCLOSE_WAIT\fR protocol state. With this option enabled, all state entries
are displayed.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 18n
Produce debugging output when displaying data.
.RE

.sp
.ne 2
.na
\fB\fB-D\fR \fIaddrport\fR\fR
.ad
.RS 18n
Valid only in combination with \fB-t\fR. Limit the state top display to show
only state entries whose destination IP address and port match the
\fIaddrport\fR argument. The \fIaddrport\fR specification is of the form
\fIipaddress\fR[,\fIport\fR]. The \fIipaddress\fR and \fIport\fR should be
either numerical or the string \fBany\fR (specifying any IP address and any
port, in that order). If the \fB-D\fR option is not specified, it defaults to
\fB-D\fR \fBany,any\fR.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 18n
Show fragment state information (statistics) and held state information (in the
kernel) if any is present.
.RE

.sp
.ne 2
.na
\fB\fB-g\fR\fR
.ad
.RS 18n
Show groups currently configured (both active and inactive).
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.RS 18n
Show per-rule the number of times each one scores a "hit". For use in
combination with \fB-i\fR.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.RS 18n
Display the filter list used for the input side of the kernel IP processing.
.RE

.sp
.ne 2
.na
\fB\fB-I\fR\fR
.ad
.RS 18n
Swap between retrieving \fBinactive\fR/\fBactive\fR filter list details. For
use in combination with \fB-i\fR.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 18n
When used with \fB-s\fR, show a list of active state entries (no statistics).
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 18n
Show the rule number for each rule as it is printed.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fR
.ad
.RS 18n
Display the filter list used for the output side of the kernel IP processing.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR \fIprotocol\fR\fR
.ad
.RS 18n
Valid only in combination with \fB-t\fR. Limit the state top display to show
only state entries that match a specific protocol. The argument can be a
protocol name (as defined in \fB/etc/protocols\fR) or a protocol number. If
this option is not specified, state entries for any protocol are specified.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR\fR
.ad
.RS 18n
Disable both IP address-to-hostname resolution and port number-to-service name
resolution.
.RE

.sp
.ne 2
.na
\fB\fB-S\fR \fIaddrport\fR\fR
.ad
.RS 18n
Valid only in combination with \fB-t\fR. Limit the state top display to show
only state entries whose source IP address and port match the \fIaddrport\fR
argument. The \fIaddrport\fR specification is of the form
\fIipaddress\fR[,\fIport\fR]. The \fIipaddress\fR and \fIport\fR should be
either numerical or the string \fBany\fR (specifying any IP address and any
port, in that order). If the \fB-S\fR option is not specified, it defaults to
\fB-S\fR \fBany,any\fR.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 18n
Show packet/flow state information (statistics only).
.RE

.sp
.ne 2
.na
\fB\fB-T\fR \fIrefreshtime\fR\fR
.ad
.RS 18n
Valid only in combination with \fB-t\fR. Specifies how often the state
\fBtop\fR display should be updated. The refresh time is the number of seconds
between an update. Any positive integer can be used. The default (and minimal
update time) is 1.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 18n
Show the state table in a way similar to the way the Unix utility, \fBtop\fR,
shows the process table. States can be sorted in a number of different ways.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 18n
Turn verbose mode on. Displays additional debugging information.
.RE

.sp
.ne 2
.na
\fB\fB-z\fR\fR
.ad
.RS 18n
Report statistics for the specified zone. If this option is not specified,
the current zone is used. This command is only available in the Global Zone.
.RE

.SH FILES
.RS +4
.TP
.ie t \(bu
.el o
\fB/dev/kmem\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB/dev/ksyms\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB/dev/ipl\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB/dev/ipstate\fR
.RE
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBipf\fR(1M), \fBkstat\fR(1M), \fBkstat\fR(3KSTAT), \fBattributes\fR(5),
\fBipfilter\fR(5), \fBzones(5)\fR
.sp
.LP
\fI\fR