Annotation of embedaddon/iftop/iftop.8, revision 1.1.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