MAN page from OpenSuSE iftop-0.17-5.1.i586.rpm


Section: Maintenance Commands (8)



iftop - display bandwidth usage on an interface by host



iftop -h |[-nNpbBP] [-i interface] [-f filter code] [-F net/mask]



iftop listens to network traffic on a named interface, or on thefirst interface it can find which looks like an external interface if none isspecified, and displays a table of current bandwidth usage by pairs of hosts.iftop must be run with sufficient permissions to monitor all networktraffic on the interface; see pcap(3) for more information, but onmost systems this means that it must be run as root.

By default, iftop will look up the hostnames associated with addresses itfinds in packets. This can cause substantial traffic of itself, and may resultin a confusing display. You may wish to suppress display of DNS traffic byusing filter code such as not port domain, or switch it off entirely,by using the -n option or by pressing R when the program is running.

By default, iftop counts all IP packets that pass through the filter, andthe direction of the packet is determined according to the direction the packetis moving across the interface. Using the -F option it is possible toget iftop to show packets entering and leaving a given network. Forexample, iftop -F will analyse packets flowing in andout of the 10.* network.

Some other filter ideas:

not ether host ff:ff:ff:ff:ff:ff
Ignore ethernet broadcast packets.
port http and not host
Count web traffic only, unless it is being directed through a local web cache.
How much bandwith are users wasting trying to figure out why the network isslow?



Print a summary of usage.
Don't do hostname lookups.
Do not resolve port number to service names
Run in promiscuous mode, so that traffic which does not pass directly throughthe specified interface is also counted.
Turn on port display.
Don't display bar graphs of traffic.
Display bandwidth rates in bytes/sec rather than bits/sec.
-i interface
Listen to packets on interface.
-f filter code
Use filter code to select the packets to count. Only IP packets are evercounted, so the specified code is evaluated as (filter code) and ip.
-F net/mask
Specifies a network for traffic analysis. If specified, iftop will onlyinclude packets flowing in to or out of the given network, and packet directionis determined relative to the network boundary, rather than to the interface.You may specify mask as a dotted quad, such as /, or as asingle number specifying the number of bits set in the netmask, such as /24.
-c config file
Specifies an alternate config file. If not specified, iftop will use~/.iftoprc if it exists. See below for a description of config files



When running, iftop uses the whole screen to display network usage. Atthe top of the display is a logarithmic scale for the bar graph which gives avisual indication of traffic.

The main part of the display lists, for each pair of hosts, the rate at whichdata has been sent and received over the preceding 2, 10 and 40 secondintervals. The direction of data flow is indicated by arrows, <= and =>. Forinstance,  =>      1Kb  500b   100b                 <=                       2Mb    2Mb    2Mb
shows, on the first line, traffic from; in the preceding 2 seconds, this averaged 1Kbit/s,around half that amount over the preceding 10s, and a fifth of that over thewhole of the last 40s. During each of those intervals, the data sent in theother direction was about 2Mbit/s. On the actual display, part of each lineis inverted to give a visual indication of the 10s average of traffic.You might expect to see something like this where host foo is makingrepeated HTTP requests to bar, which is sending data back which saturatesa 2Mbit/s link.

By default, the pairs of hosts responsible for the most traffic (10 secondaverage) are displayed at the top of the list.

At the bottom of the display, various totals are shown, including peak trafficover the last 40s, total traffic transferred (after filtering), and totaltransfer rates averaged over 2s, 10s and 40s.



By pressing s or d while iftop is running, all trafficfor each source or destination will be aggregated together. This is mostuseful when iftop is run in promiscuous mode, or is run on a gatewaymachine.



S or D toggle the display of source and destination portsrespectively. p will toggle port display on/off.



t cycles through the four line display modes; the default 2-line display,with sent and received traffic on separate lines, and 3 1-line displays, withsent, received, or total traffic shown.



By default, the display is ordered according to the 10s average (2nd column).By pressing 1, 2 or 3 it is possible to sort by the 1st, 2ndor 3rd column. By pressing < or > the display will be sorted bysource or destination hostname respectively.



l allows you to enter a POSIX extended regular expression that will beused to filter hostnames shown in the display. This is a good way to quicklylimit what is shown on the display. Note that this happens at a much laterstage than filter code, and does not affect what is actually captured. Displayfilters DO NOT affect the totals at the bottom of the screen.



P will pause the current display.

o will freeze the current screen order. This has the side effect thattraffic between hosts not shown on the screen at the time will not be shown atall, although it will be included in the totals at the bottom of the screen.



j and k will scroll the display of hosts. This feature is mostuseful when the display order is frozen (see above).



f allows you to edit the filter code whilst iftop running. Thiscan lead to some unexpected behaviour.



iftop can read its configuration from a config file. If the -c option isnot specified, iftop will attempt to read its configuration from~/.iftoprc, if it exists. Any command line options specified willoverride settings in the config file.

The config file consists of one configuration directive per line. Eachdirective is a name value pair, for example:

interface: eth0
sets the network interface. The following config directives are supported:

interface: if
Sets the network interface to if.
dns-resolution: (yes|no)
Controls reverse lookup of IP addresses.
port-resolution: (yes|no)
Controls conversion of port numbers to service names.
filter-code: bpf
Sets the filter code to bpf.
show-bars: (yes|no)
Controls display of bar graphs.
promiscuous: (yes|no)
Puts the interface into promiscuous mode.
port-display: (off|source-only|destination-only|on)
Controls display of port numbers.
hide-source: (yes|no)
Hides source host names.
hide-destination: (yes|no)
Hides destination host names.
use-bytes: (yes|no)
Use bytes for bandwidth display, rather than bits.
sort: (2s|10s|40s|source|destination)
Sets which column is used to sort the display.
line-display: (two-line|one-line-both|one-line-sent|one-line-received)
Controls the appearance of each item in the display.
show-totals: (yes|no)
Shows cummulative total for each item.
log-scale: (yes|no)
Use a logarithmic scale for bar graphs.
max-bandwidth: bw
Fixes the maximum for the bar graph scale to bw, e.g. "10M"
net-filter: net/mask
Defines an IP network boundary for determining packet direction.
screen-filter: regexp
Sets a regular expression to filter screen output.


QUIRKS (aka they're features, not bugs)

There are some circumstances in which iftop may not do what you expect. Inmost cases what it is doing is logical, and we believe it is correct behaviour,although I'm happy to hear reasoned arguments for alternative behaviour.

Totals don't add up

There are several reasons why the totals may not appear to add up. Themost obvious is having a screen filter in effect, or screen orderingfrozen. In this case some captured information is not being shown toyou, but is included in the totals.

A more subtle explanation comes about when running in promiscuous modewithout specifying a -F option. In this case there is no easy wayto assign the direction of traffic between two third parties. For the purposesof the main display this is done in an arbitrary fashion (by ordering of IPaddresses), but for the sake of totals all traffic between other hosts isaccounted as incoming, because that's what it is from the point of view of yourinterface. The -F option allows you to specify an arbitrary networkboundary, and to show traffic flowing across it.

Peak totals don't add up

Again, this is a feature. The peak sent and peak received didn't necessarilyhappen at the same time. The peak total is the maximum of sent plus receivedin each captured time division.

Changing the filter code doesn't seem to work

Give it time. Changing the filter code affects what is captured fromthe time that you entered it, but most of what is on the display isbased on some fraction of the last 40s window of capturing. Afterchanging the filter there may be entries on the display that aredisallowed by the current filter for up to 40s. DISPLAY FILTERING hasimmediate effect and does not affect what is captured.



Configuration file for iftop.






Paul Warren <>



$Id: iftop.8,v 1.25 2005/12/25 11:50:21 pdw Exp $



This program is free software; you can redistribute it and/or modifyit under the terms of the GNU General Public License as published bythe Free Software Foundation; either version 2 of the License, or(at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty ofMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See theGNU General Public License for more details.

You should have received a copy of the GNU General Public Licensealong with this program; if not, write to the Free SoftwareFoundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.



QUIRKS (aka they're features, not bugs)

This document was created byman2html,using the manual pages.