IPTraf User's Manual

Written by Gerard Paul Java
Copyright (c) Gerard Paul Java 1997, 1998

Version 1.3.0

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.

Table of Contents

     About This Document
          For More Information
          Document Conventions
     Introduction
     Installation
          System Requirements
          Installing the Downloaded Package
          Installing the Floppy Distribution
          Upgrading from Earlier Versions
     Starting IPTraf
          Command-line Options
          Using Menus
     Using IPTraf
          General Information
               Number Display Representations
               Logging
          IP Traffic Monitor
               Upper Window
               Lower Window
          General Interface Statistics
          Detailed Interface Statistrics
          Ethernet Station Statistics
          TCP and UDP Traffic Statistics
          Display Filters
               TCP Filters
                    Defining a New Filter
                    Applying a Filter
                    Deleting a Defined Filter
                    Detaching an Applied Filter
               Other Protocol Filters
     Configuring IPTraf
     Messages
     Technical Appendices
          Recompiling
          Technical Notes
               Kernel
               Security
               Terminal
               User Interface
               Network Interfaces
     License and Copyright for IPTraf

About This Document

This document is the User's Manual for IPTraf 1.3. Documented here are the
features of the program and instructions on its use.


For Additional Information

See the included README file for summarized and late-breaking information.
The CHANGES file contains a record of the changes made to the software since
1.0.0. Planned features and fixes are in the TODO file. The file
README.rvnamed contains a description of the new rvnamed program and the
protocol used to communicate with IPTraf.

Document Conventions

[ ]  items in brackets are optional
{ }  curly braces enclose items you choose from
|    the vertical bar separates choices in curly braces

Introduction

IPTraf is a network monitoring utility for IP networks. It intercepts
packets on the network and gives out various pieces of information about the
current IP traffic over it. Information returned by IPTraf include:

   * Total, IP, TCP, UDP, ICMP, and non-IP byte counts
   * TCP source and destination addresses and ports
   * TCP packet and byte counts
   * TCP flag statuses
   * UDP source and destination information
   * ICMP type information
   * OSPF source and destination information
   * TCP and UDP service statistics
   * Interface packet counts
   * Interface IP checksum error counts
   * Interface activity indicators
   * LAN station statistics

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, supported FDDI adapters, supported ISDN adapters, and any
asynchronous SLIP/PPP interface. No special hardware is required.

Installation

IPTraf is most readily available on the Internet, but some may receive it on
a diskette. Here are the instructions for both types of distributions.

System Requirements

The supplied IPTraf precompiled program requires the following to run:

   * 80386 or later. i486DX2-75 MHz or later (or equivalents) will give
     better performance. Faster machines reduce the chances of missed
     packets.  Pentium-class machines are recommended.
   * Linux 2.0.0 or later. The latest kernel version (as of this writing
     2.0.35) is recommended for various security reasons.
   * 8MB of physical RAM or higher. More recommended. 16MB virtual memory
     recommended (physical memory + swap space)
   * Shared C library 5. The precompiled binary does not require the shared
     ncurses libraries (yet), as they are linked in. You can recompile if
     you'd like to use your shared ncurses and panels libraries.
   * Terminfo database in /usr/share/terminfo
   * Console or high-speed terminal
   * Ethernet, FDDI, ISDN, or asynchronous SLIP/PPP interfaces

The X Window system is not required. Here are the installation instructions.

Installing the Downloaded Package

IPTraf can be downloaded from the Internet. The downloadable package is in a
compressed (gzip) tar archive. To extract the files from the archive, you
need these utilities:

   * tar
   * GNU zip (gzip)

If you downloaded IPTraf from the Internet, follow these steps to install
the software:

  1. Decompress the .tar.gz file by entering

             tar zxvf iptraf-1.3.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.3.0.tar.gz
             tar xvf iptraf-1.3.0.tar

     This will decompress the sources into a directory called iptraf-1.3.0.
     Change to the src directory. It already contains ready-to-run
     distribution binaries for IPTraf and the accompanying rvnamed daemon.

  2. Enter

         make install

     This will install the distribution binary in the /usr/local/bin
     directory. The necessary working directory /var/local/iptraf will also
     be created.

Installing the Floppy Distribution

If you received IPTraf on a diskette, the sources are already decompressed.
The diskette is in Second Extended filesystem format. Perform the following
steps to install the software.

  1. Insert the floppy in the drive.

  2. Mount the floppy on an empty directory. For example, to mount the
     floppy in the first floppy drive under a directory called /mnt, enter

             mount -t ext2 /dev/fd0 /mnt

     This assumes your floppy is in /dev/fd0. You can use any empty
     directory in place of /mnt. With most Linux distributions, this will
     work.

  3. After mounting, change to the /mnt (or whatever) directory.

  4. Enter

             make install

  5. This will copy the binary to /usr/local/bin, and create the
     /var/local/iptraf directory.

  6. Unmount the diskette by typing

             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.

Be sure /usr/local/bin is included in your environment's PATH variable. You
can edit the appropriate command in your login customization file (.profile
for the Bourne-type shells, .cshrc for the C shells and its relatives).

Upgrading from Earlier Versions

Version 1.2.0 added new configuration items and an additional field to the
TCP/UDP filters. The configuration and filter file formats have not changed
from 1.2.0 for version 1.3.0, but the port list data file (containing the
ports above 1023 you would like to monitor) was adjusted to allow for ranges
of ports in 1.3.0.

Therefore, if you're upgrading from 1.2.0, do a

        make upgrade

This will adjust the port data file for use with 1.3.0. The other data files
are untouched.

If you're upgrading from version 1.1.0, run the "cfconv" program from
version 1.2.0 as well. This will adjust the data records in the
configuration and filter data files to work properly with version 1.3.0. You
can do that by decompressing the 1.2.0 distribution and by performing its
"make upgrade" procedure.

Starting IPTraf

After installation, you can start the program by simply entering

        iptraf

at 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.

Since 1.2.0, IPTraf makes use of the maximum number of lines on the screen
(although only the first 80 characters on each line are utilized).

----------------------------------------------------------------------------

Technical note

IPTraf needs to refer to the terminfo database in /usr/share/terminfo. If
the supplied executable program fails with "Error opening terminal", your
terminfo database may be located somewhere else. You can control the
terminfo search path by using the TERMINFO environment variable. For
example, if you're using the sh or bash shell, and your terminfo database is
in /usr/lib/terminfo (typical for Slackware distributions), you can use the
commands:

        TERMINFO=/usr/lib/terminfo
        export TERMINFO

You can place these commands in your ~/.profile or the systemwide
/etc/profile startup files.

You can also create a symbolic link named /usr/local/share/terminfo to let
it point to your existing terminfo (assuming again your terminfo is in
/usr/lib/terminfo):

        ln -s /usr/lib/terminfo /usr/share/terminfo

Or you can recompile your program to use your existing ncurses library
installation. If you do this, make sure you have ncurses 1.9.9e or later.
----------------------------------------------------------------------------

Command-line Options

Since version 1.1.0, IPTraf accepts options on the command line which can be
used to start each individual facility.

-i
     causes the IP traffic monitor to start immediately
-g
     starts the general interface statistics
-d iface
     shows detailed statistics for the specified interface
-s iface
     starts the TCP/UDP traffic monitor for the specified interface
-l
     starts the LAN station monitor
-t timeout
     The -t parameter, when used with one of the other parameters that
     specifies a facility to start, tells IPTraf to run the indicated
     facility for only timeout minutes, after which the facility exits. The
     -t parameter is ignored in menu mode.
-f
     IPTraf's internal behavior does not allow its facilities to work well
     with other instances of themselves. To prevent conflicts involving
     internal resources (sockets) or files (logs), IPTraf will not allow
     more than one instance of a facility (traffic monitor, interface
     statistics, etc) to run at the same time. However, multiple copies of
     IPTraf can be started, each running a different facility. Configuration
     is only allowed for the first instance of IPTraf, subsequent instances
     cannot modify the configuration.

     The -f parameter overrides the existing tags attached to the IPTraf
     process and to the various facilities, causing this instance to think
     it is the first and that there are no other facilities running. Use
     this parameter with great caution. A common use for this parameter is
     to recover from abrupt or abnormal terminations which may leave stale
     tags still lying around.

     The -f parameter may be used together with the others.
iptraf -h
     displays a short help screen

While interactive commands in the IPTraf interface are not case-sensitive,
command-line options are.

Using the Menus

Use the Up and Down arrow keys on your keyboard to move the selection bar.
Press Enter to execute the selected item. Alternatively, you can also
directly press the highlighted letter of the item you want. This will
immediately execute the option.

Using IPTraf

General Information

The following sections document the various statistics facilities. The
default behavior is to return counts in as close to real time as possible,
although this may be adjusted at the Configuration menu.

Number Display Notations

Initially IPTraf returns counts in bytes and packets. However, as they grow
larger, IPTraf begins displaying them in higher denominations.

A number standing alone with no suffix represents an exact count. A number
with a K following is a kilo (thousand) figure. An M, G, and T suffix
represents mega (million), giga (billion), and tera (trillion) respectively.
For example

1024067         - exactly 1024067
1024K           - approximately 1024000
1024M           - approximately 1024000000
1024G           - approximately 1024000000000
1024T           - approximately 1024000000000000

These notations apply to both packet and byte counts.

Logging

The statistical facilities can log their counts and information to log
files. As of version 1.3, log files are stored in the directory
/var/log/iptraf. Each facility logs its information to its own log file. See
the Logging configuration option below.

See the descriptions of the individual facilities below for the names of the
log files. The logs are in plain text format and can be viewed with any text
pager or editor.

Screen Update Delays

Previous versions updated the screen as soon as a packet was received.
However, screen updates are one of the slowest operations the program
performs. Version 1.3.0 added a new configuration option to control the
screen update interval in seconds. Setting the interval to 0 results in
fastest updates.

See the Screen update interval... configuration option under the
Configuration section of this manual.

IP Traffic Monitor

Executing the first menu item or specifying -i to the iptraf command takes
you to the IP Traffic Monitor. The Traffic Monitor is a real-time monitoring
system that intercepts all packets on all detected network interfaces. The
monitor decodes the IP information on all IP packets and displays the
appropriate information about it, most notably the source and destination
addresses. In addition to that, it also determines the encapsulated protocol
within the IP packet, and displays some important information about that as
well.

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.

Upper Window

The upper window of the Traffic Monitor displays the currently detected TCP
connections. Information about TCP packets are displayed here. The window
contains these pieces of information:

   * Source address and port
   * Destination address and port
   * Packet count
   * Byte count
   * Packet Size
   * Window Size
   * TCP flag statuses
   * Interface

The TCP window is scrollable, and you can use the Up and Down arrow keys on
your keyboard to view more connections.

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. These
bytes include total IP and TCP header information, in addition to the actual
data. Data link header (e.g. Ethernet and FDDI) data are not included.

Packet Size
The size of the most recently received packet. This item is visible if you
press M for more TCP information. This is the size of the IP datagram only,
not including the data link header.

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.

S    SYN. A synchronization is taking place in preparation for connection
     establishment. If only an S is present (S---) the source is trying to
     initiate a connection. If an A is also present (S-A-), this is an
     acknowledgment of a previous connection request, and is responding.
A    ACK. This is an acknowledgment of a previously received packet
P    PSH. A request to push all data to the top of the receiving queue
U    URG. This packet contains urgent data
RESET
     RST. The source machine indicated in this direction reset the entire
     connection. The direction entries for reset connections become
     available for new connections.
DONE
     The connection is done sending data in this direction, and has sent a
     FIN (finished) packet, but has not yet been acknowledged by the other
     host.
CLOSED
     The FIN has been acknowledged by the other host. When both directions
     of a connection are marked CLOSED, the entries they occupy become
     available for new connection entries.
-    The flag is not set

Interface
The network interface this packet was received from. The following types of
interfaces are currently supported:

lo
     The loopback interface. Every machine has one, and has an IP address of
     127.0.0.1. lo is also indicated if data is detected on the dummyn
     interface(s).
ethn
     An Ethernet interface. n starts from 0. Therefore, eth0 refers to the
     first Ethernet interface, eth1 to the second, and so on. Most machines
     only have one.
fddin
     An FDDI interface. n starts from 0.
pppn
     A PPP interface. n starts from 0. Therefore, ppp0 is the first PPP
     interface, ppp1 is the second, and so on.
slin
     A SLIP interface. n starts from 0. Same sequence as above

Two more data items can also be viewed, the packet size and the advertised
window size. Pressing M will replace the packet and byte counts with the
packet size and window size. Press M again to view the packet counts and
byte counts.

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 Configure menu.

----------------------------------------------------------------------------

The rvnamed Process

The IP Traffic Monitor starts a daemon called rvnamed to help speed up
reverse lookups without sacrificing too much keyboard control and accuracy
of the counts. While reverse lookup is being conducted in the background, IP
addresses will be used until the resolution is complete.

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 standard lookup functions do not return until they have completed their
tasks, and it can take several seconds for a name resolution in the
foreground to complete.
----------------------------------------------------------------------------
----------------------------------------------------------------------------

Tip

If you notice unusual SYN activity (too many initial (S---) but frozen SYN
entries, or rapidly increasing initial SYN packets for a single connection),
you may be under a SYN flooding attack. Apply appropriate measures, or the
targeted machine may begin denying network services.
----------------------------------------------------------------------------

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 Configure 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.

----------------------------------------------------------------------------

Technical note: IP Forwarding and Masquerading

The traffic monitor behaves somewhat unusually for machines which forward
packets between interfaces. On a machine functioning as a regular router,
IPTraf will see two copies of the same packets, one for the interface it
arrives on, and one for each interface it exits. The TCP window will display
two entries for such packets, one for each interface, while two entries for
each forwarded non-TCP packet will be displayed in the lower window.

On masquerading firewall machines, the behavior is even stranger. A machine
performing IP masquerading translates between "real" IP addresses (e.g.
properly registered addresses on the Internet) and "fake" IP addresses
(non-registered addresses not reachable or valid on the Internet). The
kernel performs the IP address translation before the packet is pushed up to
the raw packet capture facility. As a result, the TCP traffic monitor
displays entries with data flowing in one direction, but with none in the
other, instead, the other direction is in another TCP entry (which also has
0 bytes flowing in the opposite direction. This is because the destination
IP addresses of packets coming from the outside ("real") network are
translated, then IPTraf sees the "dummy" destination address. But packets
coming from the inside ("fake") network have their source addresses
translated, and IPTraf sees the translated address (the "real" address of
the masquerading machine), which does not match the opposite direction.

If you're confused with the outputs, and even more so reading this sidebar,
it may be better to run multiple copies of IPTraf, one on a computer on each
segment connected to masquerading machine, rather than on the masquerading
machine itself.
----------------------------------------------------------------------------

Lower Window

The lower window displays information about the other types of traffic on
your network. The following protocols are detected:

   * UDP
   * ICMP
   * OSPF
   * IGRP
   * IGP
   * IGMP
   * ARP
   * RARP

Non-IP packets are simply indicated as Non-IP in the lower window.

----------------------------------------------------------------------------

Note

The source and destination addresses for ARP and RARP entries are MAC
addresses.

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 LANs.
----------------------------------------------------------------------------

For all packets in the lower window, only the first IP fragment is indicated
(since that contains the header of the IP-encapsulated protocol).

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 Red

The 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 interface

where type could be any of the following:

echo request, echo reply
     ICMP echo request and reply. Usually used by the ping program and other
     network monitoring and diagnostic program.
dest unreach
     ICMP destination unreachable. Something failed to reach its target. The
     dest unreach type is supplemented with a further indicator of the
     problem. Destination unreachable messages for TCP traffic causes the
     corresponsing TCP entry in the upper window to be made available for
     reuse by new connections.
redirect
     ICMP redirect. Usually generated by a router to tell a host that a
     better gateway is available.
source quench
     The ICMP source quench is used to stop a host from transmitting. It's
     some kind of flow control mechanism.
time exceeded
     Indicates a packet's time-to-live value expired before it got to its
     destination. Mostly happens if a destination is too far away. Also used
     by the traceroute program.
router adv
     ICMP router advertisement
router sol
     ICMP router solicitation
timestamp req
     ICMP timestamp request
timestamp rep
     ICMP timestamp reply
info req
     ICMP information request
info rep
     ICMP infromation reply
addr mask req
     ICMP address mask request
addr mask rep
     ICMP address mask reply
parameter problem
     ICMP parameter problem
bad/unknown
     An unrecognized ICMP packet was received, or the packet is corrupted.

The destination unreachable message also includes information on the type of
error encountered. Here are the destination unreachable codes:

network
     network unreachable
host
     host unreachable
protocol
     protocol unreachable
port
     port unreachable
DF set
     the packet has to be fragmented somewhere, but its don't fragment (DF)
     bit is set.
src route failed
     source route failed
src isoltd
     source isolated (obsolete)
net comm denied
     network communication denied
host comm denied
     host communication denied
net unreach for TOS
     network unreachable for specified IP type-of-service
host unreach for TOS
     host unreachable for specified IP type-of-service
prec violtn
     precedence violation
prev cutoff
     precedence cutoff
dest net unkn
     destination network unknown
dest host unkn
     destination network unknown

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 interface

The type can be one of the following:

hlo
     OSPF hello. Hello messages establish OSPF communications and keep
     routers informed of each other's presence.
DB desc
     OSPF Database Description
LSR
     OSPF Link State Request
LSU
     OSPF Link State Update. Messages indicating the states of the OSPF
     network links
LSA
     OSPF Link State Acknowledgment

The entries in parentheses:

a=area
     The area number the of the OSPF message
r=router
     The IP address of the router that generated the message. It is not
     necessarily the same as the source address of the encapsulating IP
     packet.

Many times, the destination addresses for OSPF packets are class D multicast
addresses in standard dotted decimal notation or (if reverse lookup is
enabled), hosts under the MCAST.NET domain. Such multicast addresses are
defined as follows:

224.0.0.5 (OSPF-ALL.MCAST.NET)
     OSPF all routers
224.0.0.6 (OSPF-DSIG.MCAST.NET)
     OSPF all designated routers

See RFC 1247 for details on the OSPF protocol.

With logging enabled, IP traffic monitor information is written to the file
ip_traffic.log.

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).

General Interface Statistics

The second menu option displays a list of attached network interfaces, and
some general packet counts. Specifically, it displays counts of IP, non-IP,
and bad IP packets (packets with IP checksum errors). It also includes an
activity indicator, which shows the number of kilobits and packets the
interface sees per second. All figures are for incoming and outgoing
packets. (Again, considering promiscuous mode for LAN interfaces, which
simply causes the machine to intercept all packets). This is useful for
general monitoring of all attached interfaces. If byte counts and additional
information are needed for a specific interface, the Detailed interface
statistics option is also available.

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 iface_stats_general.log
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.

Detailed Interface Statistics

The third menu option displays packet statistics for any selected interface.
It provides basically the same information as the General interface
statistics option, with additional information. This option provides the
following information:

   * IP packet and byte counts
   * TCP packet and byte counts
   * UDP packet and byte count
   * ICMP packet and byte counts
   * Other IP-type packet and byte counts
   * Non-IP packet and byte counts
   * Checksum error count
   * Interface activity in kilobits per second
   * Packet size counts

All IP byte counts (IP, TCP, UDP, ICMP, other IP) include IP header data and
payload. The data link header is not included. The full frame length
(including data-link header) is included in the non-IP byte count.

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 eth0

starts the statistics for eth0. The interface must be specified, or IPTraf
will not start the facility.

----------------------------------------------------------------------------

Note

In both the general and detailed statistics screens, as well as in the IP
Traffic Monitor, the packet counts are for actual network packets (layer 2),
not the logical IP packets (layer 3) that may be reconstructed after
fragmentation. That means, if a packet was fragmented into four pieces, and
these four fragments pass over your interface, the packet counts will
indicate four separate packets. The figure for the IP checksum error is a
packet count only, because the corrupted IP header cannot be relied upon to
give a correct IP packet length value.
----------------------------------------------------------------------------
The figures are logged at regular intervals if logging is enabled.

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).

LAN Station Statistics

The LAN Station Monitor (Ethernet Station Monitor on versions prior to
1.3.0) discovers MAC addresses and displays statistics on the number of
incoming, and outgoing packets. It also includes figures for incoming and
outgoing kilobits per second for each discovered station.

The entry above each line of statistics is the station's LAN type (Ethernet
or FDDI) and the hardware MAC 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

The byte counts include the data link header.

This facility works only for Ethernet and FDDI frames. Loopback and SLIP/PPP
networks are not monitored here.

Copies of the statistics are written to the log file lan_statistics.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).

TCP and UDP Traffic Statistics

IPTraf also includes a facility that generates statistics on TCP and UDP
traffic. This facility displays counts of all TCP and UDP packets with
source or destination ports numbered less than 1024. Ports 1 to 1023 are
reserved for the TCP/IP application protocols (well-known ports).

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.

Byte counts include the IP header and payload only. The data link header is
not included.

The protocol/port indicators are color-coded for easier identification. TCP
indicators are in yellow, UDP in bright green (TCP is normal, UDP is bold
white in non-color mode).

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
Configure/Additional port... menu item. See the section below.

The statistics are also written to the log file tcp_udp_services.log 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 eth0

brings 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).

Display Filters

The Display Filters are used to control the information displayed by the IP
Traffic Monitor. In many cases, the Traffic Monitor fills up very rapidly
with information, most of which you may not need. You may want to use such a
display just to get a general idea of the network traffic, but if you're
interested only in particular traffic, you must restrict the information
displayed. The filters also apply to logging activity.

TCP Filters

The TCP display filters option allows you to define a set of parameters that
determine which connections the Traffic Monitor displays about. Selecting
this option pops up another menu with the tasks used to define and apply
custom TCP display filters.

Defining a New Filter
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 as
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.

IPTraf also accepts host names in place of the IP addresses. 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.

----------------------------------------------------------------------------

Tip

See the Linux Network Administrator's Guide if you need more information on
IP addresses and subnet masking.
----------------------------------------------------------------------------

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
preset to 0.0.0.0, 0.0.0.0, 0. Just Backspace or Delete over them and
replace them if needed.

The last field is marked Include/Exclude. This field allows you to decide
whether to include or exclude this entry from the display. Setting this
field to I causes the filter to display matching entries, while setting it
to E causes the filter to supress the display of matching entries. This
field is set to I by default.

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 as
many sets of paramters as you wish. Press Ctrl+X at a blank form when done.

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                       0
Include/Exclude         I

To 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                       0
Include/Exclude         I

To 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                      0
Include/Exclude         I

To 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                      0
Include/Exclude         I

To 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                       0
Include/Exclude         I

To omit display of traffic to/from 140.66.5.x from/to anywhere

Host name/IP Address    140.66.5.x              0.0.0.0
Wildcard mask           255.255.255.0           0.0.0.0
Port                    0                       0
Include/Exclude         E

In 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.

Excepting Certain Sites from the Display
Filters follow an "implicit no-display" policy, that is, only explicitly
defined sites will be displayed, everything else is not. This is similar to
the access-list policy "whatever is not explicitly permitted is denied". If
you want to show all traffic to/from everywhere, except certain places, you
can specify the sites you wish to exclude, mark them with E in the
Include/Exclude field, and define a general catch-all entry with source
address 0.0.0.0, mask 0.0.0.0, port 0, and destination 0.0.0.0, mask
0.0.0.0, port 0. as the last entry.

For example:

To see all traffic except all SMTP, Web, and traffic from/to 207.0.115.44:

Host name/IP address            0.0.0.0                 0.0.0.0
Wildcard mask                   0.0.0.0                 0.0.0.0
Port                            25                      0
Include/Exclude                 E

Host name/IP address            0.0.0.0                 0.0.0.0
Wildcard mask                   0.0.0.0                 0.0.0.0
Port                            80                      0
Include/Exclude                 E

Host name/IP address            207.0.115.44            0.0.0.0
Wildcard mask                   255.255.255.255         0.0.0.0
Port                            0                       0
Include/Exclude                 E

Host name/IP address            0.0.0.0                 0.0.0.0
Wildcard mask                   0.0.0.0                 0.0.0.0
Port                            0                       0
Include/Exclude                 I

----------------------------------------------------------------------------

Tip

To omit all TCP from the display, define a filter with a single entry, with
a source of 0.0.0.0 mask 0.0.0.0 port 0, and a destination of 0.0.0.0 mask
0.0.0.0 port 0, with the Include/Exclude field marked E (exclude). Then
apply this filter.
----------------------------------------------------------------------------

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.

The applied filter stays in effect over exits and restarts of the IPTraf
program until it is detached.

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.

Other Protocol Filters

You can select the other IP-type protocols you want to display or omit with
the Other protocol filters... option. With the exception of UDP, the filters
for other protocols are simply toggled. To toggle a protocol's display, just
select the protocol and press Enter. Visible protocols are listed in the box
next to the menu.

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.

The filters for non-TCP protocols are saved and automatically reapplied
whenever IPTraf is restarted after an exit.

Configuring IPTraf

IPTraf can be easily configured with the Configure item in the main menu.
The configuration is stored in the /var/local/iptraf/iptraf.cfg file. If the
file is not found, IPTraf uses the default settings. Any changes to the
configuration immediately get stored in the configuration file.

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.

TCP/UDP Service Names
This option, when on, causes IPTraf to display the TCP/UDP service names
(smtp, www, pop3, etc.) instead of their numeric ports (25, 80, 110, etc).
The number-to-name mappings will depend on the systems services database
file (usually /etc/services). Should there be no corresponding service name
for the port number, the numeric form will still be displayed.

This setting is off by default.
----------------------------------------------------------------------------

Note

Reverse lookup and service name lookup take some time and may impact
performance and increase the chances of dropped packets. Performance and
results are best (albeit more cryptic) with both these settings off.
----------------------------------------------------------------------------

Promiscuous Operation
If this option is enabled, your LAN 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 LAN 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 LAN (both Ethernet and FDDI)
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.

----------------------------------------------------------------------------

Note

Do not use other programs that change the interface's promiscuous flag at
the same time you're using IPTraf. The programs can interfere with each
other's expected operations.
----------------------------------------------------------------------------

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. Starting with version 1.3.0, each facility has
its own log file as follows:

        IP Traffic Monitor              - ip_traffic.log
        General Interface Stats         - iface_stats_general.log
        Detailed Interface Stats        - iface_stats_detailed.log
        TCP/UDP Service Monitor         - tcp_udp_services.log
        LAN Station Monitor             - lan_statistics.log

The traffic monitor will write the following pieces of information to its
log file:

   * Start of the traffic monitor
   * Receipt of the first TCP packet for a connection. If that packet is a
     SYN, (SYN) will be indicated in the log entry. (Of course, the traffic
     monitor may start in the middle of established connections. It will
     still count those packets. This also explains why some connection
     entries may become idle if the traffic monitor is started in the middle
     of a half-closed connection, and miss the first FIN. Such entries time
     out in a while.)
   * Receipt of a FIN
   * ACK of a FIN
   * Timeouts of TCP entries
   * Everything that appears in the bottom window of the traffic monitor
   * Stopping of the traffic monitor

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 LAN 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 LAN host statistics. The default is 60
minutes. This figure is meaningless if logging is disabled.

Screen Update Interval
This value determines the rate in seconds at which the screen is updated.
The default is 0, which means the screen is updated as fast as possible,
giving close-to-realtime reflection of network activity. However, this
high-speed update can cause incredible amounts of traffic if IPTraf is run
on a remote termnial (e.g. a Telnet or Secure Shell session). You can set
this to a higher value, such as 1 or 2 seconds to slow down the updates.

This figure does not affect the rate of data capture. Only the screen
refresh is affected. The figures are still updated as fast as possible,
although the figure display will no longer be as close to realtime.

The default setting is 0, which shouldn't be a problem on the console. Set
it to a slightly higher value on remote terminals or slow links. The setting
affects all monitoring facilities.

----------------------------------------------------------------------------

Note

Screen updating is one of the slowest operations in a program. Previous
versions of IPTraf had a problem once network activity became very high.
Because each packet caused a screen update, IPTraf began spending more time
with the screen updates, causing a loss of packets once network activity
reached a certain point.

However, since many users like rapid counts on their screen, a compromise
was incorporated. When the screen update interval is set to 0, there is
still a 50ms delay between screen updates (except the LAN station monitor,
which has a 100 ms delay). This is still visually fast, but provides more
time to the packet capture routine. Higher delays may result in better
accuracy of counts and activity.

In any case, this setting only affects screen updates. Capture still
proceeds as fast as possible.

----------------------------------------------------------------------------

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 will see two fields. If you have only one port to enter, just fill up
the first field. To specify a range, fill both fields, the first port in the
first field, the last port in the second field.

You can select this option multiple times to add more values or ranges.

Delete port/range
Select this item to remove a higher-numbered port number or port range you
entered earlier with the Additional port... option. A window will come up
containing the entered ports and ranges. Select the entry you want delete
and press Enter.

LAN Station Identifiers

Version 1.2.0 had a new feature: an option to provide descriptions to the
cryptic and hard-to-remember 6-byte Ethernet MAC addresses. An identical
facility was added in version 1.3.0 for FDDI addresses as well. This section
applies to both Ethernet and FDDI address descriptions.

The LAN station statistics facility monitors stations based on their
respective MAC addresses. The hexadecimal notation of these addresses make
them even more difficult to remember than the dotted-decimal IP addresses,
so these facilities was added to help you better find which station is
which.

Selecting the Ethernet host descriptions or FDDI host descriptions options
brings up a submenu asking you to add, edit, or delete descriptions.

To add a new description, select the Add description... option. A dialog box
will appear, asking you for the MAC address and an appropriate description.
Type in the address in hexadecimal notation with no punctuation of any kind.
The dialog box is case-insensitive for the address; the alphabetical digits
A to F will be stored in lowercase.

Use the Tab key to move between fields and Enter to accept. Press Ctrl+X to
discard this dialog and return to the main menu.

The description may be anything: the IP address, a fully-qualified domain
name, or a description of your liking as long as the field can hold.

Enter as many descriptions as you need. Press Ctrl+X at a blank dialog after
you have entered the last entry

These descriptions will be displayed alongside the MAC addresses in the LAN
station monitor, together with the type of frame (Ethernet or FDDI).

An existing address or description may be edited by selecting the Edit
description... option from the submenu. A panel will appear with a list of
existing address descriptions. Select the one you wish to edit and press
Enter. A dialog box identical to that when you add a description will appear
with prefilled fields. Just backspace over and edit the fields. Press Enter
to accept or Ctrl+X to cancel.

Selecting the Delete description... submenu item brings up the selection
panel. Select the description you want to delete and press Enter. You can
also press Ctrl+X to cancel the operation.

Messages

Unable to create config file
IPTraf cannot create the configuration file. The most likely cause of this
is that you didn't properly install the program, and the necessary directory
/var/local/iptraf does not exist. Can also be generated if you have a disk
problem or if you have too many files open.

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.

Error loading filter list file
IPTraf cannot access the list of defined TCP or UDP filters. Can also be an
indicator of a bad disk.

Error writing filter list file
The filter list file cannot be written to. You may have trouble accessing
your filters.

Unable to read filter file
IPTraf cannot read the filter data off the file. Could be caused by a bad
disk.

Error opening filter file
IPTraf cannot open the filter file. Could be caused by a shortage of file
descriptors or a bad disk.

Unable to write TCP/UDP filter record
IPTraf cannot add the newly defined filter to the filter list.

Cannot create TCP/UDP filter record file
IPTraf cannot create the filter record file. The defined filter is lost.

Unable to create TCP/UDP filter file
IPTraf cannot create the filter data file.

Unable to save TCP/UDP filter name
IPTraf cannot save the name of the current TCP filter. IPTraf will start
with no filters active the next time it is invoked.

Unable to retrieve saved TCP/UDP filter
The saved filter cannot be retrieved. IPTraf will start with no TCP filters
active.

Unable to write non-TCP filters
IPTraf was not able to write the filters for the other protocols. Probably
due to a bad disk or full filesystem.

Unable to resolve hostname
The indicated host name in the filter cannot be resolved into an IP address.
Check the local hosts database /etc/hosts or your machine's DNS
configuration or DNS server.

The filter parameters will not be used.

Unable to open host description file
IPTraf cannot open the file containing the descriptions for Ethernet or FDDI
addresses. Could be due to a bad disk or a hit on the file descriptor limit.

Unable to write host description
IPTraf was unable to write the description record for this Ethernet or FDDI
address. Could be due to a bad disk or corrupted filesystem.

No descriptions
You tried to edit or delete a description with no previous descriptions
defined.

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.

Unable to obtain interface list
IPTraf was unable to retrieve the list of network interfaces from the /proc
filesystem. This may be due to a badly configured kernel. IPTraf needs /proc
filesystem support.

Unable to obtain interface parameters
The system call to retrieve the interface's flags failed. Check your
interface or kernel driver.

Promisc change failed for interface
The system call to change the promiscuous flag failed. Check your interface
or kernel driver.

Unable to open raw socket for flag change
IPTraf was unable to open the necessary socket for the promiscuous change
operation. May be due to a shortage of file descriptors.

Unable to open socket for MTU determination
Returned by the facility for detailed interface statistics if the raw
socket's opening sequence failed. The facility will abort.

Unable to open raw socket
IPTraf was unable to open the raw socket for packet capture. May be due to a
shortage of file descriptors.

Unable to obtain interface MTU
The detailed statistics facility was unable to obtain the maximum
transmission unit (MTU) for the selected interface. The facility will abort.

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.

----------------------------------------------------------------------------
Technical note: This is actually a response to the segmentation fault error
(SIGSEGV).
----------------------------------------------------------------------------

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 (terminate) 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.

Warning: unable to tag this process
IPTraf normally tags itself when it runs to prevent other instances of it
from running while this copy is active. This message means the program was
unable to create the necessary tag file. This may be due to a bad or
improper installation. Try running the "make install" procedure.

Warning: unable to tag facility
IPTraf was unable to create the tag file for the facility you started. The
facility will still run, but other instances of IPTraf that may be running
simultaneously will allow the same facility to run. This may cause both
instances of the facility to malfunction. This could be due to a bad disk or
bad installation.

facility already active in another process
The facility you tried to start is currently running in another IPTraf
process on the machine. This restriction is placed to prevent conflicts
involving internal sockets or the log file.

Duplicate port/range entry
You entered a port number or range that was already added to the list of
additional ports to be monitored by the TCP/UDP service monitor

No custom ports
There are no ports or port ranges earlier added. There's nothing to delete.

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.

Memory Low
This indicator appears if memory runs low due to a lot of entries in a
facility. Should critical functions fail (window creation, internal
allocation), the program could terminate with a segmentation violation.

IPC Error
This indicator appears if an error occurs receiving data from the rvnamed
program (IPC stands for Interprocess Communication). This indication should
not occur under normal circumstances. Report instances of this condition and
the circumstances under which it happens. You may also include data from the
rvnamed.log file.

Error opening terminal: terminal
The screen management routines cannot find the terminfo entry for your
terminal. IPTraf expects the terminfo database located in
/usr/share/terminfo. This error could occur when your terminfo database is
located somewhere else.

See the section above on controlling the terminfo search path.

rvnamed Messages

Being a daemon, rvnamed does not send messages to the screen. It writes its
messages to the file rvnamed.log in the IPTraf working directory.

Unable to open child communication socket
rvnamed was unable to open the communication endpoint for data reception
from the children it creates. This is highly unusual, and should it occur,
report the circumstances.

Unable to open client communication socket
rvnamed was unable to open the communication endpoint for data exchange with
the IPTraf program. This is highly unusual, and should it occur, report the
circumstances.

Error binding client communication socket
Error binding child communication socket
rvnamed was unable to assign a name to the indicated communication socket.
This may be due to a bad, full, or corrupted filesystem.

Fatal error: no memory for descriptor monitoring
rvnamed ran out of memory. IPTraf will resort to blocking, and may freeze.

Error on fork, returning IP address
rvnamed had a problem spawning a copy of itself to resolve the IP address.
rvnamed will simply return the IP address in its literal, dotted-decimal
notation. IPTraf will still function normally. This may be due to lack of
memory or a process limit hit.

Technical Appendices

Recompiling the Program

With both the downloaded and floppy distributions, you can recompile the
program immediately before you do the make install. Perform the following
steps to recompile:

  1. Change to the src directory and clear out the supplied binaries by
     entering

             make clean

  2. Recompile by entering

             make

     at 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:

   * Linux 2.0.0 or later
   * gcc-2.7.0 or later (2.7.2.3 or later for glibc2)
   * ncurses-1.9.9e or later (earlier versions have problems with the
     Backspace key and updates of overlapping windows)
   * GNU make

Makefile Options

The Makefile has several options you can change. You probably don't need to
change most of them, probably with the exception of LDOPTS

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.
PROF            the -pg option.  Uncomment this to generate profile code
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 (although you should change the -m486
                parameter if compiling for a different processor)
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
                (many distributions have the ncurses headers in
                /usr/include/ncurses)
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 install

to install the resulting executable module in the proper directory.

Technical Notes

(also in the README file)

Kernel

IPTraf is untested on Linux kernels prior to the 2.0.x series. The raw
socket interface in the 2.0 series kernels is known to be stable. IPTraf may
still work on earlier kernels, but no guarantee is actually given. As is
always the case, development series kernels may or may not work.

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
"teardrop" attack). A newer bug was discovered in kernels 2.0.33 and
earlier, still in the IP fragment code (the "nestea" vulnerability). It is
recommended that you upgrade to at least version 2.0.35 or apply kernel
patches to fix these problems.

Security

The raw socket interface requires the program to run with root permission.
This program is intended for system and network administrators. However,
should you want to allow non-root users to use the program you can edit the
Makefile and enable the -DALLOWUSERS option, then install the program setuid
root. This is not recommended though. While effort has been exerted to avoid
things like buffer overruns, this program is not declared to be secure for
non- root users to use.

The 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.

Terminal

This program was designed to run on the Linux console. It should work on
80x25 xterms and rxvt windows. Run this program from the console (text or
xterm) or a high-speed terminal for best results. Resize xterms to the
appropriate size before you run the program.

IPTraf will use the maximum number of available lines in the terminal, but
only the first 80 characters on each line will be recognized.

User Interface

Reverse DNS lookups will block if the rvnamed daemon is not running when the
traffic monitor is active. This will cause severe packet loss and keyboard
control close to impossible. Normally rvnamed should start with no problems
whenever the traffic monitor is started with reverse lookups enabled.

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.

Network Interfaces

IPTraf currently includes support for Ethernet, FDDI, loopback, and
asynchronous SLIP/PPP interfaces.

For Ethernet and FDDI, 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).

----------------------------------------------------------------------------

License and Copyright for IPTraf

IPTraf 1.3 Copyright  Gerard Paul Java, 1997, 1998

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 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.

Linux is a registered trademark of Linus Torvalds.

Pentium is a registered trademark of Intel Corporation.

----------------------------------------------------------------------------
IPTraf User's Manual, Plain Text Version 1.3.0
Copyright (c) Gerard Paul Java 1997, 1998
