Return to iftop.8 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / iftop

iftop

    1: .TH IFTOP 8
    2: .\"
    3: .\" iftop.8:
    4: .\" Manual page for iftop.
    5: .\"
    6: .\" $Id: iftop.8,v 1.1.1.1 2012/02/21 16:57:34 misho Exp $
    7: .\"
    8: 
    9: .SH NAME
   10: iftop - display bandwidth usage on an interface by host
   11: 
   12: .SH SYNOPSIS
   13: \fBiftop\fP \fB-h\fP |
   14: [\fB-nNpbBP\fP] [\fB-i\fP \fIinterface\fP] [\fB-f\fP \fIfilter code\fP] [\fB-F\fP \fInet\fP/\fImask\fP]
   15: 
   16: .SH DESCRIPTION
   17: \fBiftop\fP listens to network traffic on a named \fIinterface\fP, or on the
   18: first interface it can find which looks like an external interface if none is
   19: specified, and displays a table of current bandwidth usage by pairs of hosts.
   20: \fBiftop\fP must be run with sufficient permissions to monitor all network
   21: traffic on the \fIinterface\fP; see \fBpcap\fP(3) for more information, but on
   22: most systems this means that it must be run as root.
   23: 
   24: By default, \fBiftop\fP will look up the hostnames associated with addresses it
   25: finds in packets. This can cause substantial traffic of itself, and may result
   26: in a confusing display. You may wish to suppress display of DNS traffic by
   27: using filter code such as \fBnot port domain\fP, or switch it off entirely,
   28: by using the \fB-n\fP option or by pressing \fBR\fP when the program is running.
   29: 
   30: By default, \fBiftop\fP counts all IP packets that pass through the filter, and
   31: the direction of the packet is determined according to the direction the packet
   32: is moving across the interface.  Using the \fB-F\fP option it is possible to
   33: get \fBiftop\fP to show packets entering and leaving a given network.  For
   34: example, \fBiftop -F 10.0.0.0/255.0.0.0\fP will analyse packets flowing in and
   35: out of the 10.* network.
   36: 
   37: Some other filter ideas:
   38: .TP
   39: \fBnot ether host ff:ff:ff:ff:ff:ff\fP
   40: Ignore ethernet broadcast packets.
   41: .TP
   42: \fBport http and not host \fP\fIwebcache.example.com\fP
   43: Count web traffic only, unless it is being directed through a local web cache.
   44: .TP
   45: \fBicmp\fP
   46: How much bandwith are users wasting trying to figure out why the network is
   47: slow?
   48: 
   49: .SH OPTIONS
   50: 
   51: .TP
   52: \fB-h\fP
   53: Print a summary of usage.
   54: .TP
   55: \fB-n\fP
   56: Don't do hostname lookups. 
   57: .TP
   58: \fB-N\fP
   59: Do not resolve port number to service names
   60: .TP
   61: \fB-p\fP
   62: Run in promiscuous mode, so that traffic which does not pass directly through
   63: the specified interface is also counted.
   64: .TP
   65: \fB-P\fP
   66: Turn on port display.
   67: .TP
   68: \fB-b\fP
   69: Don't display bar graphs of traffic. 
   70: .TP
   71: \fB-B\fP
   72: Display bandwidth rates in bytes/sec rather than bits/sec.
   73: .TP
   74: \fB-i\fP \fIinterface\fP
   75: Listen to packets on \fIinterface\fP.
   76: .TP
   77: \fB-f\fP \fIfilter code\fP
   78: Use \fIfilter code\fP to select the packets to count. Only IP packets are ever
   79: counted, so the specified code is evaluated as \fB(\fP\fIfilter code\fP\fB) and ip\fP.
   80: .TP
   81: \fB-F\fP \fInet\fP/\fImask\fP
   82: Specifies a network for traffic analysis.  If specified, iftop will only
   83: include packets flowing in to or out of the given network, and packet direction
   84: is determined relative to the network boundary, rather than to the interface.
   85: You may specify \fImask\fP as a dotted quad, such as /255.255.255.0, or as a
   86: single number specifying the number of bits set in the netmask, such as /24.
   87: .TP
   88: \fB-c\fP \fIconfig file\fP
   89: Specifies an alternate config file.  If not specified, iftop will use
   90: \fB~/.iftoprc\fP if it exists.  See below for a description of config files
   91: 
   92: .SH DISPLAY
   93: 
   94: When running, \fBiftop\fP uses the whole screen to display network usage. At
   95: the top of the display is a logarithmic scale for the bar graph which gives a
   96: visual indication of traffic.
   97: 
   98: The main part of the display lists, for each pair of hosts, the rate at which
   99: data has been sent and received over the preceding 2, 10 and 40 second
  100: intervals. The direction of data flow is indicated by arrows, <= and =>. For
  101: instance,
  102: .nf
  103: 
  104: foo.example.com  =>  bar.example.com      1Kb  500b   100b
  105:                  <=                       2Mb    2Mb    2Mb
  106: 
  107: .Sp
  108: .fi
  109: shows, on the first line, traffic from \fBfoo.example.com\fP to
  110: \fBbar.example.com\fP; in the preceding 2 seconds, this averaged 1Kbit/s,
  111: around half that amount over the preceding 10s, and a fifth of that over the
  112: whole of the last 40s. During each of those intervals, the data sent in the
  113: other direction was about 2Mbit/s. On the actual display, part of each line
  114: is inverted to give a visual indication of the 10s average of traffic.
  115: You might expect to see something like this where host \fBfoo\fP is making
  116: repeated HTTP requests to \fBbar\fP, which is sending data back which saturates
  117: a 2Mbit/s link.
  118: 
  119: By default, the pairs of hosts responsible for the most traffic (10 second
  120: average) are displayed at the top of the list.
  121: 
  122: At the bottom of the display, various totals are shown, including peak traffic
  123: over the last 40s, total traffic transferred (after filtering), and total
  124: transfer rates averaged over 2s, 10s and 40s.
  125: 
  126: .SH SOURCE / DEST AGGREGATION
  127: 
  128: By pressing \fBs\fP or \fBd\fP while \fBiftop\fP is running, all traffic
  129: for each source or destination will be aggregated together.  This is most
  130: useful when \fBiftop\fP is run in promiscuous mode, or is run on a gateway
  131: machine.
  132: 
  133: .SH PORT DISPLAY
  134: 
  135: \fBS\fP or \fBD\fP toggle the display of source and destination ports
  136: respectively. \fBp\fP will toggle port display on/off.
  137: 
  138: .SH DISPLAY TYPE
  139: 
  140: \fBt\fP cycles through the four line display modes; the default 2-line display,
  141: with sent and received traffic on separate lines, and 3 1-line displays, with
  142: sent, received, or total traffic shown.
  143: 
  144: .SH DISPLAY ORDER
  145: 
  146: By default, the display is ordered according to the 10s average (2nd column).
  147: By pressing \fB1\fP, \fB2\fP or \fB3\fP it is possible to sort by the 1st, 2nd
  148: or 3rd column.   By pressing \fB<\fP or \fB>\fP the display will be sorted by
  149: source or destination hostname respectively.
  150: 
  151: .SH DISPLAY FILTERING
  152: 
  153: \fBl\fP allows you to enter a POSIX extended regular expression that will be
  154: used to filter hostnames shown in the display.  This is a good way to quickly
  155: limit what is shown on the display.  Note that this happens at a much later
  156: stage than filter code, and does not affect what is actually captured.  Display
  157: filters DO NOT affect the totals at the bottom of the screen.
  158: 
  159: .SH PAUSE DISPLAY / FREEZE ORDER
  160: 
  161: \fBP\fP will pause the current display.
  162: 
  163: \fBo\fP will freeze the current screen order.  This has the side effect that
  164: traffic between hosts not shown on the screen at the time will not be shown at
  165: all, although it will be included in the totals at the bottom of the screen.
  166: 
  167: .SH SCROLL DISPLAY
  168: 
  169: \fBj\fP and \fBk\fP will scroll the display of hosts.  This feature is most
  170: useful when the display order is frozen (see above).
  171: 
  172: .SH FILTER CODE
  173: 
  174: \fBf\fP allows you to edit the filter code whilst iftop running.  This
  175: can lead to some unexpected behaviour.
  176: 
  177: .SH CONFIG FILE
  178: 
  179: iftop can read its configuration from a config file.  If the \fB-c\fP option is
  180: not specified, iftop will attempt to read its configuration from
  181: \fB~/.iftoprc\fP, if it exists.  Any command line options specified will
  182: override settings in the config file.
  183: 
  184: The config file consists of one configuration directive per line.  Each
  185: directive is a name value pair, for example:
  186: .nf
  187: 
  188: interface: eth0
  189: 
  190: .Sp
  191: .fi
  192: sets the network interface.  The following config directives are supported:
  193: 
  194: .TP
  195: \fBinterface:\fP \fIif\fP
  196: Sets the network interface to \fIif\fP.
  197: .TP
  198: \fBdns-resolution:\fP \fI(yes|no)\fP
  199: Controls reverse lookup of IP addresses.
  200: .TP
  201: \fBport-resolution:\fP \fI(yes|no)\fP
  202: Controls conversion of port numbers to service names.
  203: .TP
  204: \fBfilter-code:\fP \fIbpf\fP
  205: Sets the filter code to \fIbpf\fP.
  206: .TP
  207: \fBshow-bars:\fP \fI(yes|no)\fP
  208: Controls display of bar graphs.
  209: .TP
  210: \fBpromiscuous:\fP \fI(yes|no)\fP
  211: Puts the interface into promiscuous mode.
  212: .TP
  213: \fBport-display:\fP \fI(off|source-only|destination-only|on)\fP
  214: Controls display of port numbers.
  215: .TP
  216: \fBhide-source:\fP \fI(yes|no)\fP
  217: Hides source host names.
  218: .TP
  219: \fBhide-destination:\fP \fI(yes|no)\fP
  220: Hides destination host names.
  221: .TP
  222: \fBuse-bytes:\fP \fI(yes|no)\fP
  223: Use bytes for bandwidth display, rather than bits.
  224: .TP
  225: \fBsort:\fP \fI(2s|10s|40s|source|destination)\fP
  226: Sets which column is used to sort the display.
  227: .TP
  228: \fBline-display:\fP \fI(two-line|one-line-both|one-line-sent|one-line-received)\fP
  229: Controls the appearance of each item in the display.
  230: .TP
  231: \fBshow-totals:\fP \fI(yes|no)\fP
  232: Shows cummulative total for each item.
  233: .TP
  234: \fBlog-scale:\fP \fI(yes|no)\fP
  235: Use a logarithmic scale for bar graphs.
  236: .TP
  237: \fBmax-bandwidth:\fP \fIbw\fP
  238: Fixes the maximum for the bar graph scale to \fIbw\fP, e.g. "10M"
  239: .TP
  240: \fBnet-filter:\fP \fInet/mask\fP
  241: Defines an IP network boundary for determining packet direction.
  242: .TP
  243: \fBscreen-filter:\fP \fIregexp\fP
  244: Sets a regular expression to filter screen output.
  245: 
  246: .SH QUIRKS (aka they're features, not bugs)
  247: 
  248: There are some circumstances in which iftop may not do what you expect.  In
  249: most cases what it is doing is logical, and we believe it is correct behaviour,
  250: although I'm happy to hear reasoned arguments for alternative behaviour.
  251: 
  252: \fBTotals don't add up\fP
  253: 
  254: There are several reasons why the totals may not appear to add up.  The
  255: most obvious is having a screen filter in effect, or screen ordering
  256: frozen.  In this case some captured information is not being shown to
  257: you, but is included in the totals.
  258: 
  259: A more subtle explanation comes about when running in promiscuous mode
  260: without specifying a \fB-F\fP option.  In this case there is no easy way
  261: to assign the direction of traffic between two third parties.  For the purposes
  262: of the main display this is done in an arbitrary fashion (by ordering of IP
  263: addresses), but for the sake of totals all traffic between other hosts is
  264: accounted as incoming, because that's what it is from the point of view of your
  265: interface.  The \fB-F\fP option allows you to specify an arbitrary network
  266: boundary, and to show traffic flowing across it.
  267: 
  268: \fBPeak totals don't add up\fP
  269: 
  270: Again, this is a feature.  The peak sent and peak received didn't necessarily
  271: happen at the same time.  The peak total is the maximum of sent plus received
  272: in each captured time division.
  273: 
  274: \fBChanging the filter code doesn't seem to work\fP
  275: 
  276: Give it time.  Changing the filter code affects what is captured from
  277: the time that you entered it, but most of what is on the display is
  278: based on some fraction of the last 40s window of capturing.  After
  279: changing the filter there may be entries on the display that are
  280: disallowed by the current filter for up to 40s.  DISPLAY FILTERING has
  281: immediate effect and does not affect what is captured.
  282: 
  283: .SH FILES
  284: 
  285: .TP
  286: \fB~/.iftoprc\fP
  287: Configuration file for iftop.
  288: 
  289: .SH SEE ALSO
  290: .BR tcpdump (8),
  291: .BR pcap (3),
  292: .BR driftnet (1).
  293: 
  294: .SH AUTHOR
  295: Paul Warren <pdw@ex-parrot.com>
  296: 
  297: .SH VERSION
  298: $Id: iftop.8,v 1.1.1.1 2012/02/21 16:57:34 misho Exp $
  299: 
  300: .SH COPYING
  301: This program is free software; you can redistribute it and/or modify
  302: it under the terms of the GNU General Public License as published by
  303: the Free Software Foundation; either version 2 of the License, or
  304: (at your option) any later version.
  305: 
  306: This program is distributed in the hope that it will be useful,
  307: but WITHOUT ANY WARRANTY; without even the implied warranty of
  308: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  309: GNU General Public License for more details.
  310: 
  311: You should have received a copy of the GNU General Public License
  312: along with this program; if not, write to the Free Software
  313: Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  314: