Permission is granted to reproduce and distribute this document with the included software under the terms of the GNU General Public License. This manual and the software that accompanies it come with absolutely no warranty, not even the implied warranties of merchantability or fitness for any particular purpose. See the included COPYING file for details.
This manual is the HTML version and can be viewed with any Web browser supporting HTML 3.0.
IPTraf can be used to monitor the load on an IP network, the most used types of network services, the proceedings of TCP connections, and others.
IPTraf is software-only, and utilizes the built-in raw packet capture interface of the Linux kernel, allowing it to be used with a wide range of Ethernet cards and any SLIP/PPP interface. No special hardware is required.
The X Window system is not required. Here are the installation instructions.
If you downloaded IPTraf from the Internet, follow these steps to install the software:
tar zxvf iptraf-1.1.0.tar.gz
If your tar doesn't support the z option, you can separately decompress the tar.gz then extract the resulting .tar archive.
gunzip iptraf-1.1.0.tar.gz
tar xvf iptraf-1.1.0.tar
This will decompress the sources into a directory called
iptraf-1.1.0.
make installThis will install the distribution binary in the /usr/local/bin directory. The necessary working directory /var/local/iptraf will also be created.
mount -t ext2 /dev/fd0 /mntThis assumes your floppy is in /dev/fd0. You can use any empty directory in place of /mnt. With most Linux distributions, this will work.
make install
umount /mnt
(That's umount, not unmount.)
You can then eject the diskette. Store it in a safe
place.
In both cases (downloaded and floppy), the installation will store the program in /usr/local/bin with the binaries owned by user root, readable, writable, and executable by the owner, no permissions for the group, no permissions for all others. (700 octal, or -rwx------). In either case, perform the "make install" step. This not only transfers the executable programs, but creates the necessary directories if they do not yet exist. IPTraf will not function properly without them.
iptrafat the shell prompt. You will see a copyright notice, with an instruction to press any key to get started. Just press any character key, and you will be immediately taken to the main menu. All major functions of the program are found here.
Entering the IPTraf command without any command-line parameters brings up the program's main menu. From there, you can select the facilities you want.
While interactive commands in the IPTraf interface are not case-sensitive, command-line options are.
There are two windows in the Traffic Monitor. Both of them can be scrolled with the Up and Down cursor keys. Just press W to move the Active indicator to the window you want to control.
The TCP window is scrollable, and you can view more connections by using the Up and Down arrow keys on your keyboard.
Because this monitoring system relies solely on packet information, it does not determine which endpoint initiated the connection. In other words, it does not determine which endpoint is the client, and which is the server. This is necessary because it can operate in promiscuous mode, and as such cannot determine the socket statuses for other machines on the LAN.
That being the case, the system displays two entries for each connection, one for each direction of the TCP connection. To make it easier to determine the direction pairs of each connection, a bracket is used to "join" both together. This bracket appears at the leftmost part of each entry.
The directions of data flow do not determine which entries appear at the top and at the bottom of the bracket. That is, just because the direction appears at the upper part of the bracket doesn't mean its source machine initiated the connection.
Each entry in the window contains these fields:
Source address and port
The source address and port indicator is in address:port format.
This indicates the source machine and TCP port on that machine
from which this data is coming.
Destination address and port
The destination address and port field indicates to which
machine and port on that machine packets are being sent to.
Packet count
The number of packets received for this direction of the
TCP connection
Byte count
The number of bytes received for this direction of the TCP
connection
Packet Size
The size of the most recently received packet. This item is visible
if you press M for more TCP information.
Window Size
The advertised window size of the most recently received packet. This
item is visible if you press M for more TCP information.
Flag statuses
The flags of the most recently received packet.
Interface
The network interface this packet was received
from. The following types of interfaces are currently
supported:
By default, only IP addresses are displayed, but if you have access to a name server or host table, you may enable reverse lookup for the IP addresses. Just enable reverse lookup in the Options menu.
If for some reason rvnamed cannot start (probably due to improper installation or lack of memory), and you are on the Internet, and you enable reverse lookup, your keyboard control can become very slow. This is because the lookup functions will not return until they have completed their tasks, and it can take several seconds for a name resolution in the foreground to complete.
Entries not updated within a user-configurable amount of time may get replaced with new connections. The default time is 15 minutes. This is regardless of whether the connection is closed or not. (Some unclosed connections may be due to extremely slow links or crashes at either end of the connection.) This figure can be changed at the Options menu.
Some early entries may have a > symbol in front of its packet count. This means the connection was already established when the monitor started. In other words, the figures indicated do not reflect the counts since the start of the TCP connection, but rather, since the start of the traffic monitor. Eventually, these > entries will close (or time out) and disappear. TCP entries without the > were initiated after the traffic monitor started, and the counts indicate the totals of the connection itself. Just consider entries with > partial.
Some > entries may go idle if the traffic monitor was started when these connections were already half-closed (FIN sent by one host, but data still being sent by the other). This is because the traffic monitor cannot determine if a connection was already half-closed when it started. These entries will eventually time out. (To minimize these entries, an entry is not added by the monitor until a packet with data or a SYN packet is received.)
Direction entries also become available for reuse if an ICMP Destination Unreachable message is received for the connection.
Non-IP packets are simply indicated as Non-IP in the lower window.
Well, strictly speaking, ARP and RARP packets aren't IP packets, since they are not encapsulated in an IP datagram. They're just indicated because they are integral to proper IP operation on Ethernet LANs.
UDP packets are also displayed in address:port format. ICMP entries also contain the ICMP message type. For easier location, each type of protocol is color-coded (text console only).
UDP Red on White ICMP Yellow on Blue OSPF Black on Cyan IGRP Bright white on Cyan IGP Red on Cyan IGMP Bright green on Blue ARP Yellow on Red RARP Yellow on Red Other IP Yellow on Red Non-IP Yellow on RedThe lower window can hold up to 512 entries. You can scroll the lower window by using the W key to move the Active indicator to it, and by using the Up and Down cursor keys. The lower window automatically scrolls every time a new entry is added, and either the first entry or last entry is visible. Upon reaching 512 entries, old entries are thrown out as new entries are added.
Entry Details
In general, the entries in the lower window indicate the
protocol, the source address, the destination address, the
network interface the packet was detected on. However, some
protocols have a little more information.
ICMP: ICMP entries are displayed in this format:
ICMP type (subtype) from source to destination on interfacewhere type could be any of the following:
The destination unreachable message also includes information on the type of error encountered. Here are the destination unreachable codes:
For more information on ICMP, see RFC 792.
OSPF: OSPF messages also include a little more information. The format of an OSPF message in the window is:
OSPF type (a=area r=router) from source to destination on interfaceThe type can be one of the following:
The entries in parentheses:
Many times, the destination addresses for OSPF packets are class D multicast addresses in standard dotted decimal notation. Such multicast addresses are defined as follows:
See RFC 1247 for details on the OSPF protocol.
At any time, you can press X or Q to return to the main menu (or back to the shell if the monitor was started with iptraf -i).
The general statistics window will dynamically add new entries as packets from newly-created interfaces (e.g. new PPP interfaces) are intercepted. Long lists can be scrolled with the Up, Down, PgUp, and PgDn keys.
Copies of the statistics are written to the log file at regular intervals if logging is enabled. See the Logging option below.
This facility can be started directly from the command line with the -g option to the iptraf command.
You can press X or Q to return to the main menu.
The upper portion of the screen contains the packet and byte counts for all IP and non-IP packets intercepted on the interface. The lower portion contains the counts of packets whose sizes fall within the indicated brackets. This can be useful when monitoring the sizes of packets passing over the network.
If you wish to start this facility directly from the command line, you can specify the -d parameter and an interface to monitor. For example,
iptraf -d eth0starts the statistics for eth0. The interface must be specified, or IPTraf will not start the facility.
Pressing X or Q takes you back to the main menu (if this facility was started with the command-line option, X or Q drops you back to the shell).
The entry above each line of statistics is the Ethernet hardware address. Each statistics line follows this format:
ITP IIP ITB IA OTP OIP OIB OA
Legend:
ITP - total incoming packets
IIP - incoming IP packets
ITB - incoming bytes
IA - incoming activity in kbits/sec
OTP - total outgoing packets
OIP - outgoing IP packets
OIB - outgoing bytes
OA - outgoing activity in kbits/sec
This facility works only for Ethernet frames. Loopback and
SLIP/PPP networks are not monitored here.
Copies of the statistics are written to the log at regular intervals if logging is enabled.
The window can be scrolled with the Up and Down cursor keys. Press X or Q to return to the main menu (or the shell if this facility was started with the -e command-line option).
The statistics window indicates the protocol (TCP or UDP), the port number, the total packets and bytes counted for this particular protocol/port combination, the packets and bytes destined for that protocol and port, and the packets and bytes coming from that protocol and port.
Some network applications or protocols may use port numbers higher than 1023. Examples of these include application proxy servers (HTTP proxy servers typically use values like 8000, 8080, 8888, and the like), and IRC (IRC servers commonly accept connections on ports 6660 to 6669). These ports are by default not included in the counts. If you do want to include a higher-numbered port in the statistics, you can add them yourself from the Options/Additional port... menu item. See the section below.
The statistics are also written to the log file if logging is enabled.
If you wish to start this facility from the command line, you can use the -s option followed by an interface to monitor. For example,
iptraf -s eth0brings up this module for traffic on eth0. The interface must be specified, or IPTraf will drop back to the shell.
The Up and Down cursor keys scroll the window. Pressing X or Ctrl+X exits and returns to the main menu (or the shell if it was started from the command line).
A freshly installed program will have no filters defined, so before anything else, you will have to define a filter. You can do this by selecting the Define new filter... option.
Selecting this option displays a box asking you to enter a short description of the filter you are going to define. Just enter any text that clearly identifies the nature of the filter.
Press Enter when you're done with that box. As an alternative, you can also press Ctrl+X to cancel the operation. Following that will be another dialog box asking you for the source and target IP addresses, wildcard masks, and service ports.
You can enter addresses of individual hosts, networks, or a catch-all address. The nature of the address will be determined by the wildcard mask.
You'll notice two sets of fields. You fill these out with the information about your source and targets. Strictly speaking, because packets alone don't provide information about which side initiated the connection (except for SYN packets), you may think of these as "endpoint" fields rather than strict source/target fields. That means, you can enter information about the "from" side in the first set of fields, and the "to" side in the second set, or vice versa. It doesn't matter, since TCP is full duplex. (Also important, since the Traffic Monitor displays information about both sides of the connection).
Fill out the IP address of the hosts or networks in the first field marked Host name/IP Address. Enter it in standard dotted- decimal notation. When done, press Tab to move to the Wildcard mask field. The wildcard mask is similar but not exactly identical to the standard IP subnet masks. The wildcard mask is used to determine which bits to ignore when processing the filter. In most cases, it will work very closely like a subnet mask. Place ones (1) under the bits you want the filter to recognize, and keep zeros (0) under the bits you want the filter to ignore. For example:
To recognize the host 207.0.115.44
Enter IP address: 207.0.115.44
Wildcard mask: 255.255.255.255
To recognize all hosts belonging to network 202.47.132.x
Enter IP address: 202.47.132.0
Wildcard mask: 255.255.255.0
To recognize all hosts with any address:
Enter IP address: 0.0.0.0
Wildcard mask 0.0.0.0
The IP address/wildcard mask mechanism of the display filter
doesn't recognize IP address class. It uses a simple bit-
pattern matching algorithm.
The wildcard mask also does not have to end on a byte boundary; you may mask right into a byte itself. For example, 255.255.255.224 masks 27 bits (224 is 11100000 in binary).
Leaving the wildcard mask fields blank or storing invalid data in them causes the filter to recognize the entries as 255.255.255.255.
Starting with version 1.1.0, IPTraf accepts host names in place of the IP address. IPTraf will resolve the host name when the filter is loaded. When the filter is interpreted, the wildcard mask will also be applied. This can be useful in cases where a single host name may resolve to several IP addresses.
The Port field should contain a port number of the service you may be interested in. Leave it at 0 to let the filter ignore it. You will most likely be interested in target ports rather than source ports (which are usually unpredictable anyway, perhaps with the exception of FTP data).
Fill out the second set of fields with the parameters of the opposite end of the connection. As previously mentioned, you may place either set of parameters in either set. By default, the second set of parameters are defaulted to 0.0.0.0, 0.0.0.0, 0. Just Backspace or Delete over them and replace them if needed.
Press Enter to accept all parameters when done. The parameters will be accepted and you'll be presented with another blank form. You can enter another set of parameters, or you can end with Ctrl+X.
Examples
To see all traffic to/from host 202.47.132.1 from/to
207.0.115.44, regardless of TCP port
Host name/IP Address 202.47.132.2 207.0.115.44 Wildcard mask 255.255.255.255 255.255.255.255 Port 0 0To see all traffic from/to 207.0.115.44 to/from network 202.47.32.0
Host name/IP Address 207.0.115.44 202.47.132.0 Wildcard mask 255.255.255.255 255.255.255.0 Port 0 0To see all Web traffic, regardless of source or destination
Host name/IP Address 0.0.0.0 0.0.0.0 Wildcard mask 0.0.0.0 0.0.0.0 Port 80 0To see all mail (SMTP) traffic to/from a single host (202.47.132.2) from/to anywhere
Host name/IP Address 202.47.132.2 0.0.0.0 Wildcard mask 255.255.255.255 0.0.0.0 Port 25 0To see traffic to/from host sunsite.unc.edu from/to cebu.mozcom.com
Host name/IP Address sunsite.unc.edu cebu.mozcom.com Wildcard mask 255.255.255.255 255.255.255.255 Port 0 0In all cases, you could have interchanged the first and second sets of IP addresses, wildcard masks, and port values; they wouldn't have made any difference. That's why they're better referred to as "first" and "second" rather than "source" and "target".
You can enter as many parameters as you wish. All of them will be interpreted when the filter is processed.
Applying a Filter
The above steps only add the filter to a defined list. To
actually apply the filter, you must select Apply filter.
from the menu. You will be presented with a list of filters
you already defined. Select the one you want to apply, and
press Enter.
Deleting a Defined Filter
Select Delete Filter. from the menu to remove a filter from
the list. Just move the pointer to the filter you want to
delete, and press Enter.
Detaching a Filter
The Detach filter option deactivates the filter currently in
use. Selecting this option causes all TCP information to be
displayed by the traffic monitor.
When you're done with the menu, just select the Exit menu option.
Because UDP packets are also significantly high in volume, you can also define a UDP filter the same way you do a TCP filter. To work with UDP filters, select the UDP... option. You can opt to display all UDP packets, no UDP packets, and define a custom UDP filter. Other than the first two options, the others are almost identical to the custom TCP filter options.
If you applied a custom UDP filter, or set IPTraf to display all UDP packets, UDP will be included in the list of visible protocols.
Reverse Lookup
Activating reverse lookup causes IPTraf to find out the name
of the hosts with the addresses in the IP packets. As
pointed out earlier, if you're on the Internet, your
keyboard control can become very clumsy with this option
enabled, and you can lose packet counts. You may want to
keep this off if you're monitoring a machine on the
Internet, or if you have no accessible name server or host
table. A local DNS server on an isolated LAN though won't
give much trouble.
This option is off by default.
Promiscuous Operation
If this option is enabled, your Ethernet interface will
capture all packets on your LAN. Using this option enables
you to see all TCP connections and packets passing your LAN
segment, even if they're not from or for your machine. When
this option is active in the statistics windows, the Activity
indicators will show a good estimate of the load on your
Ethernet segment.
When this option is disabled, you'll only receive information about packets coming from and entering your machine.
The setting of this option affects all Ethernet interfaces on your machine, if you have more than one.
Regardless of the initial setting of the interfaces' promiscuous flags, IPTraf turns them off when it exits. Promiscuous mode is off by default.
Color
Turn it on with color monitors. Turn it off with black-and-
white monitors or non-color terminals (like xterms).
Changes to this setting will take effect only upon
restarting the program.
Color is on by default on consoles, off on non-color terminal types like xterms and VT100s.
Logging
When this option is active, IPTraf will log information to a
disk file, which can be examined later. The log file is
/var/local/iptraf/iptraf.log.
The traffic monitor will write the following pieces of information to the log file:
Each log entry includes the date and time the entry was written. Logging is also affected by the defined filters.
Log files can grow very fast, so be prepared with plenty of free space and delete unneeded logs. Log write errors are not indicated.
Copies of the interface statistics, TCP/UDP statistics, and Ethernet host statistics are also written to the log files at regular intervals. See "Log Interval" below.
Logging comes disabled by default.
TCP Timeout This figure determines the amount of time (in minutes) a connection entry may remain idle before it becomes eligible for replacement by a new connection. The default is 15 minutes. You may want to reduce this on an isolated (not connected to the Internet) LAN or a LAN connected to the Internet with high-speed links. Just enter the new value and press Enter. You can press Ctrl+X to leave the current value unchanged.
Log Interval
This figure determines the number of minutes between logging
of interface statistics, TCP/UDP figures, and Ethernet host
statistics. The default is 60 minutes. This figure is
meaningless if logging is disabled.
Additional port
Select this item to enter a port number to be included in
the TCP/UDP counts in the TCP/UDP service statistics main
menu item described above. By default, port numbers above
1023 are not monitored. If you do have a higher-numbered
port to monitor, enter it here. You can select this option
multiple times to add more values.
Delete port
Select this item to remove a higher-numbered port number you
entered earlier with the Additional port... option. You
cannot delete ports less than 1024.
Unable to read config file
The configuration record cannot be read. You most likely
have a disk problem.
Unable to write config file
The configuration file cannot be written. You either have a
disk problem, or (more likely), your disk is full.
Unable to read filter record file
IPTraf cannot access the list of defined TCP or UDP filters.
Can also be an indicator of a bad disk.
Unable to read filter file
IPTraf cannot read the filter data off the file. Could be
caused by a bad disk.
Unable to write filter record file
IPTraf cannot add the newly defined filter to the filter
list.
Unable to write filter file
IPTraf cannot write the data of the newly defined filter.
Cannot open log file
There is a problem opening the log file. There is most
likely a problem with the disk, or there are too many open
files.
Critical error: unable to allocate memory for a critical function
May occur if you have too little memory to allocate for windows, the
menu system, or dialog boxes. IPTraf tries to prevent further
allocations if memory runs out during a monitor.
This program can be run only by the system administrator
IPTraf normally does not allow anybody but uid 0 (root) to run it. This
measure is included for safety reasons. See the section on recompiling
the program below if you want to override this. This feature is built
in, and not part of the configuration
Your TERM variable is not set
The TERM (terminal type) environment variable must be set to a valid
terminal type so that the screen management routines can function
properly. Set it to the appropriate terminal type. Linux consoles
typically use a value called "linux".
Received TERM signal
Not related to the previous message. The TERM signal is normally used to
gracefully shut down a program. This message simply indicates that the
TERM signal was caught and IPTraf is attempting to shut down as gracefully
as possible.
Invalid option or missing parameter
The -d or -s options were specified but no interface was specified on the
command line. The -d and -s parameters require a valid interface name.
This message can also appear if an unknown option is passed to the iptraf command.
Duplicate port entered
You entered a port number that was added to the list of additional ports
to be monitored by the TCP/UDP service monitor
Unknown port value
You tried to delete a port number that wasn't previously entered.
Can't start rvnamed; lookups will block
IPTraf cannot start the rvnamed daemon; probably due to a bad installation.
IPTraf will fall back to blocking lookups.
Can't start new process; lookups will block
IPTraf cannot start a new process. This may be due to memory shortage.
IPTraf will fall back to blocking lookups.
make clean
makeat the prompt. You may want to recompile force the program to use your libraries and/or kernel sources, or to simply generate smaller executable files.
The distribution executable file is dynamically-linked ELF. It uses the shared C library, but the ncurses and panels libraries are linked in. With most systems, this program should work immediately after installation.
If you have the appropriate libraries and facilities, you can recompile the program to use the shared versions of the ncurses and panels libraries.
Recompiling requires:
CC specifies the C compiler to use. On Linux
systems, you will not need to change this
LIBS specifies additional libraries to use. IPTraf
uses the panels extensions to ncurses, and
therefore must specify -lpanels -lncurses in that
order. Again, most people have no need to change
this.
DEBUG the -g option to GCC. Specifying this option
causes GCC to generate debug information for use
with gdb. Also bloats the executable. Leave it
commented unless you intend to trace or debug the
executable program.
OPTIONS standard options to the GCC compiler. -O2 for
optimization, -m486 for 486-specific optimizations,
-Wall for generation of all warnings. No need to
change this
LDOPTS set this to -static to force a statically-linked
binary. Comment out to have it use the shared C
library.
INCLUDEDIR by default contains a -I/usr/include/ncurses
tag to tell GCC the location of the ncurses header
files. If your ncurses header files are located
somewhere else, change this path appropriately.
BSSETTING if set to -DDISABLEBS will disable the Backspace
key in text entry fields. If commented out,
IPTraf will recognize the Backspace key. You may
want to disable this on earlier ncurses versions,
as the Backspace key was unpredictable then.
EXECPERM If set to -DALLOWUSERS, the resulting program will
work for non-root users if its setuid bit is on.
Use with extreme caution, since this program was
not written with non-administrators in mind, and no
guarantees are given regarding security holes.
Leave commented out if not necessary.
TARGET The destination directory. Just let this point to
anywhere you want to place the resulting binary
during the make install.
The dirs.h header file also contains the default locations
for the working directory and the names and locations of the
configuration and log files. You do not need to change
these, but you may do so if you'd rather place these files
somewhere else.
When compilation is complete, enter
make installto install the resulting executable module in the proper directory.
Kernels prior to 2.0.24 had a serious bug that allowed oversized IP datagrams to crash the system (Ping o' Death), while kernels prior to 2.0.32 crashed whenever certain badly fragmented IP packets were received (the so-called "teardrop" attack). It is recommended that you upgrade to at least version 2.0.32 or apply kernel patches to fix these problems.
The new rvnamed daemon communicates with IPTraf with the UNIX domain socket mechanism. Being a background daemon, it may present a possible security issue if it turns out to be broken. Please report any discovered problems immediately.
There is also a little concern regarding the Backspace key. Apparently the backspace key mapping (KEY_BACKSPACE) is considered unreliable, and is marked as such in ncurses versions as late as 1.9.9e, although tests on this version already worked. Tests for 1.9.4 failed; pressing the Backspace key yielded ^?. The Delete key works with no problem though. If you want the program to not recognize the Backspace key, you can enable the -DDISABLEBS directive in the Makefile.
Earlier versions of ncurses also did not properly define the behavior of overlapping windows. This has been fixed in 1.9.9e.
For Ethernet, IPTraf can receive packets in promiscuous mode (i.e. all packets on the LAN, regardless of their destination). Promiscuous mode is pointless on SLIP/PPP interfaces, since these things are point-to-point links.
IPTraf imposes no additional load on the network (except for DNS traffic if reverse name lookup is enabled).
The software and accompanying documentation are distributed under the terms of the GNU General Public License, Version 2 or any later version, as published by the Free Software Foundation, Inc. Permission is granted to distribute and/or modify the software and the documentation under the terms of the license.
The software and accompanying documentation are distributed in the hope that they will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR ANY PARTICULAR PURPOSE. For more details, see the GNU General Public License, in the COPYING file included in the distribution. IPTraf uses header files that are part of the GNU C library and the Linux kernel distribution.
Additional structures were extracted from software copyrighted by the Regents of the University of California.