contrib/ipfilter/man/ipfstat.8

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