contrib/ipfilter/man/ipfstat.8

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