Annotation of embedaddon/iftop/iftop.8, revision 1.1
1.1 ! misho 1: .TH IFTOP 8
! 2: .\"
! 3: .\" iftop.8:
! 4: .\" Manual page for iftop.
! 5: .\"
! 6: .\" $Id: iftop.8,v 1.25 2005/12/25 11:50:21 pdw 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.25 2005/12/25 11:50:21 pdw 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:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to iftop.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / iftop