File: manual.html

package info (click to toggle)
iptraf 2.1.1-4
links: PTS
area: main
in suites: potato
size: 1,112 kB
ctags: 950
sloc: ansic: 9,494; makefile: 111; sh: 50
file content (2394 lines) | stat: -rw-r--r-- 91,866 bytes
<HTML>
<HEAD>
<TITLE>IPTraf User's Manual</TITLE>
</HEAD>
<BODY BGCOLOR="#F8F8FF">
<H1>
IPTraf User's Manual
</H1>
<I>Written by Gerard Paul Java<BR>
Copyright &copy; Gerard Paul Java 1997-1999
<P>
<I>Version 2.1.1</I>
<P>
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.
</I>
<P>
<H1>Table of Contents</H1>
<UL>
<A HREF="#about"><B>About This Document</B></A><BR>
<UL>
<A HREF="#moreinfo">For More Information</A><BR>
<A HREF="#conventions">Document Conventions</A><BR>
</UL>
<A HREF="#intro"><B>Introduction</B></A><BR>
<A HREF="#installation"><B>Installation</B></A><BR>
<UL>
<A HREF="#requirements">System Requirements</A><BR>
<A HREF="#downloaded">Installing the Downloaded Package</A><BR>
<A HREF="#floppy">Installing the Floppy Distribution</A><BR>
<A HREF="#upgrading">Upgrading from Earlier Versions</A><BR>
</UL>
<A HREF="#starting"><B>Starting IPTraf</B></A><BR>
<UL>
<A HREF="#commandline">Command-line Options</A><BR>
<A HREF="#usingmenus">Using Menus</A><BR>
</UL>
<A HREF="#usingiptraf"><B>Using IPTraf</B></A><BR>
<UL>
<A HREF="#geninfo">General Information</A><BR>
<UL>
<A HREF="#numeric">Number Display Representations</A><BR>
<A HREF="#loginfo">Logging</A><BR>
<A HREF="#updinfo">Screen Update Delay</A><BR>
<A HREF="#ifaceinfo">Supported Network Interfaces</A><BR>
</UL>
<A HREF="#itrafmon">IP Traffic Monitor</A><BR>
<UL>
<A HREF="#upper">Upper Window</A><BR>
<A HREF="#lower">Lower Window</A><BR>
</UL>
<A HREF="#gstats">General Interface Statistics</A><BR>
<A HREF="#dstats">Detailed Interface Statistrics</A><BR>
<A HREF="#pktsize">Statistical Breakdowns</A><BR>
<UL>
<A HREF="#pktsize">Packet Size Breakdown</A><BR>
<A HREF="#serv">TCP and UDP Traffic Statistics</A><BR>
</UL>
<A HREF="#hostmon">LAN Station Statistics</A><BR>
<A HREF="#filters">Display Filters</A><BR>
<UL>
<A HREF="#tcpfilter">TCP Filters</A><BR>
<UL>
<A HREF="#tfilterdef">Defining a New Filter</A><BR>
<A HREF="#tfilterapp">Applying a Filter</A><BR>
<A HREF="#tfilteredit">Editing a Filter</A><BR>
<A HREF="#tfilterdel">Deleting a Defined Filter</A><BR>
<A HREF="#tfilterdet">Detaching an Applied Filter</A><BR>
</UL>
<A HREF="#othpfilter">Other Protocol Filters</A><BR>
</UL>
</UL>
<A HREF="#options"><B>Configuring IPTraf</B></A><BR>
<A HREF="#backop"><B>Background Operation</B></A><BR>
<A HREF="#messages"><B>Messages</B></A><BR>
<A HREF="#appendices"><B>Technical Appendices</B></A><BR>
<UL>
<A HREF="#recompiling">Recompiling</A><BR>
<A HREF="#technotes">Technical Notes</A><BR>
<UL>
<A HREF="#kernel">Kernel</A><BR>
<A HREF="#security">Security</A><BR>
<A HREF="#terminal">Terminal</A><BR>
<A HREF="#userinterface">User Interface</A><BR>
<A HREF="#netifaces">Network Interfaces</A><BR>
</UL>
</UL>
<A HREF="#GPL"><B>License and Copyright for IPTraf</B></A><BR>
</UL>

<A NAME="about">
<H1>
About This Document
</H1>
This document is the User's Manual for IPTraf 2.1.  Documented 
here are the features of the program and instructions on its 
use.
<p>
This manual is the HTML version and can be viewed with any Web browser
supporting HTML 3.2.
<P>
<A HREF="http://www.anybrowser.org"><IMG SRC="anybrowser3.gif" ALT="Viewable with Any Browser"
BORDER="0"></A>
<P>
<A NAME="moreinfo">
<H2>For Additional Information</H2>
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.  README.rvnamed contains information on the rvnamed reverse
resolution program.  See the other README files for support and
development information.
<P>
<H2>
<A NAME="conventions">
Document Conventions
</H2>
<DL COMPACT>
<DT><TT>[  ]</TT>
<DD>items in brackets are optional
<DT><TT>{ }</TT>
<DD>curly braces enclose items you choose from
<DT><TT>|</TT>
<DD>the vertical bar separates choices in curly braces
<DT><TT>normal monospace</TT>
<DD>normal monospace text in syntax specifications should be typed in
exactly as presented.  Because UNIX and variants are case-sensitive,
case must be preserved.  Monospace is also used in presenting items that
appear on the screen.
<DT><TT><I>monospace italics</I></TT>
<DD>italics in syntax specifications indicate items that are to be replaced
with an actual item (e.g. <TT><I>interface</I></TT> should be replaced
with an actual interface name, like eth0.
</DL>
<H1>
<A NAME="intro">
Introduction
</H1>
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:
<P>
<UL>
  <LI>Total, IP, TCP, UDP, ICMP, and non-IP byte counts</LI>
  <LI>TCP source and destination addresses and ports</LI>
  <LI>TCP packet and byte counts</LI>
  <LI>TCP flag statuses</LI>
  <LI>UDP source and destination information</LI>
  <LI>ICMP type information</LI>
  <LI>OSPF source and destination information</LI>
  <LI>TCP and UDP service statistics</LI>
  <LI>Interface packet counts</LI>
  <LI>Interface IP checksum error counts</LI>
  <LI>Interface activity indicators</LI>
  <LI>LAN station statistics</LI>
</UL>
<P>
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.
<P>
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.
<P>
Basic knowledge of the important TCP/IP protocols (IP, TCP, UDP, ICMP,
etc.) is necessary for you to best understand the information generated by
the program. 
<A NAME="installation">
<H1>
Installation
</H1>
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.
<A NAME="requirements">
<H2>
System Requirements
</H2>
The supplied IPTraf precompiled program requires the following to run:
<P>
<UL>
<LI>80386 or later. i486DX2-75 MHz or later (or equivalents) will give 
better performance.  Faster machines reduce the chances of missed packets.
Pentium-class (PPro or PII) or compatible (K6, 6x86, MII) machines are
recommended.
<P>
<HR>
<B>Note </B>Other architectures (SPARC, Alpha, M68K, PowerPC, etc) may
also be used but no tests have been performed on them. 
Distribution-specific packages may be available, check with the package
maintainer for details
<HR>
<P>
</LI>
<LI>
Linux 2.2.0 or later.  At the time of this writing, the 2.2.x kernel is new,
so the latest version is recommended.
<P>
<HR>
<B>Note </B>If you're running a custom-built kernel, make sure you compile
in or install as a module the <I>Packet Socket</I> kernel option, or IPTraf
(and others like it) will fail.
<HR>
<P>
<LI>
8MB of physical RAM or higher.  More recommended.  16MB virtual memory or
more recommended (physical memory + swap space)
</LI>
<LI>
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.
</LI>
<LI>
Terminfo database in <TT>/usr/share/terminfo</TT>
</LI>
<LI>
Console or high-speed terminal
</LI>
<LI>
Ethernet, FDDI, ISDN, PLIP, or asynchronous SLIP/PPP interfaces
</LI>
</UL>
<P>
The X Window system is not required.

Here are the installation instructions.

<A NAME="downloaded">
<H3>
Installing the Downloaded Package
</H3>
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:
<P>
<UL>
<LI>tar</LI>
<LI>GNU zip (gzip)</LI>
</UL>
<P>
If you downloaded IPTraf from the Internet, follow these 
steps to install the software:
<P><OL>
<LI>Decompress the .tar.gz file by entering
<P>
<PRE>        tar zxvf iptraf-2.1.0.tar.gz
</PRE><P>
   If your tar doesn't support the <TT>z</TT> option, you can 
   separately decompress the tar.gz then extract the resulting 
   .tar archive.
<P> 
<PRE>        gunzip iptraf-2.1.0.tar.gz
        tar xvf iptraf-2.1.0.tar
</PRE> 
   This will decompress the sources into a directory called 
   <TT>iptraf-2.1.0</TT>.
</LI>
</LI>
Change to the <TT>src</TT> directory.  It already contains ready-to-run
distribution binaries for IPTraf and the accompanying rvnamed daemon.
</LI>
<P>
<LI>
To install the software, enter
<P>
<PRE>    make install
</PRE>

while you are logged in as "root". This will install the distribution
binary in the  <TT>/usr/local/bin</TT> directory.  The necessary working 
directory <TT>/var/local/iptraf</TT> will also be created.
</LI>
</OL>
<A NAME="floppy">
<H3>
Installing the Floppy Distribution
</H3>
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.
<P><OL>
<LI>
Insert the floppy in the drive.
</LI>
<P>
<LI>
Mount the floppy on an empty directory.  For example, to 
mount the floppy in the first floppy drive under a 
directory called <TT>/mnt</TT>, enter
<P>
<PRE>        mount -t ext2 /dev/fd0 /mnt
</PRE>
 
This assumes your floppy is in <TT>/dev/fd0</TT>.  You can use any 
empty directory in place of <TT>/mnt</TT>.  With most Linux 
distributions, this will work.
</LI>
<P>
<LI>
After mounting, change to the <TT>/mnt</TT> (or whatever) 
directory.
</LI>
<P>
<LI>
Enter
<P>
<PRE>        make install
</PRE>
while logged in as root.
</LI>
<P>
This will copy the binaries to <TT>/usr/local/bin</TT>, and create 
the <TT>/var/local/iptraf</TT> working directory and the
<TT>/var/log/iptraf</TT> log directory.
<P>
<LI>
Unmount the diskette by typing
 
<P>
<PRE>        umount /mnt

    (That's umount, not unmount.)
</PRE>
   You can then eject the diskette.  Store it in a safe 
   place.
</LI>
</OL>
<P>
In both cases (downloaded and floppy), the installation will 
store the program in <TT>/usr/local/bin</TT> 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------).
<P>
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.
<P>
<HR>
<B>Note</B> You must be logged in as root to perform the "make install"
step to allow the proper directories to be written to or created.
<HR>
<P>
Be sure <TT>/usr/local/bin</TT> is included in your environment's
PATH variable.  You can edit the appropriate command in your login
customization file (<TT>.profile</TT> for the Bourne-type shells,
<TT>.cshrc</TT> for the C shells and its relatives).
<A NAME="upgrading">
<H2>Upgrading from Earlier Versions</H2>

If you're running IPTraf 2.0.x or earlier, and you're using TCP/UDP
filters, do a "make upgrade" procedure.  Versions 1.4.x and 2.0.x
erroneously placed the filter data files in a wrong directory due to a
filename parsing bug.
<P>
There have been no file format changes since version 1.4.  If you're
upgrading from a version prior to 1.4, do the "make upgrade" procedures
from each semi-major version in sequence (e.g. 1.2 -> 1.3 -> 1.4).
<P>
<A NAME="starting">
<H1>
Starting IPTraf
</H1>
After installation, you can start the program by simply 
entering
<UL>
<TT>iptraf</TT>
</UL>
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.
<P>
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.
<P>
IPTraf determines and makes use of the maximum number of lines and columns
on the terminal.
<P>
<HR>
<B>Note </B>IPTraf does not yet have a SIGWINCH handler, and does not adjust
itself when an xterm other X terminal is resized.
<HR>
<P>
<HR>
<B>Technical note </B>
IPTraf needs to refer to the terminfo database in
<TT>/usr/share/terminfo</TT>.  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 <TT>/usr/lib/terminfo</TT> (typical for
Slackware
distributions), you can use the commands:
<UL><TT>
	TERMINFO=/usr/lib/terminfo<BR>
	export TERMINFO</TT>
</UL>
You can place these commands in your <TT>~/.profile</TT> or the systemwide
<TT>/etc/profile</TT> startup files.
<P>
You can also create a symbolic link named
<TT>/usr/share/terminfo</TT> to let
it point to your existing terminfo (assuming again your terminfo is in
<TT>/usr/lib/terminfo</TT>):
<UL>
<TT>	ln -s /usr/lib/terminfo /usr/share/terminfo</TT>
</UL>
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.
<HR>
<P>
<A NAME="commandline">
<H2>
Command-line Options
</H2>
The following command-line parameters can also be passed to the IPTraf
command:
<P>
<DL>
<DT><TT>-i <I>iface</I></TT>
<DD>causes the IP traffic monitor to start immediately on the specified
interface.  If <TT>-i all</TT> is specified, all interfaces are monitored.
<DT><TT>-g</TT>
<DD>starts the general interface statistics
<DT><TT>-d <I>iface</I></TT>
<DD>shows detailed statistics for the specified interface
<DT><TT>-s <I>iface</I></TT>
<DD>starts the TCP/UDP traffic monitor for the specified interface
<DT><TT>-z <I>iface</I></TT>
<DD>starts the packet size breakdown for the specified interface
<DT><TT>-l <I>iface</I></TT>
<DD>starts the LAN station monitor on the specified interface.  If
<TT>-l all</TT> is specified, all LAN interfaces are monitored.
<DT><TT>-t <I>timeout</I></TT>
<DD>The <TT>-t</TT> parameter, when used with one of the other parameters that
specify a facility to start, tells IPTraf to run the indicated facility
for only <TT>timeout</TT> minutes, after which the facility exits.  The
<TT>-t</TT> parameter is ignored in menu mode.
<P>
If this parameter is not specified, the facility runs until the exit
keystroke is pressed.
<DT><TT>-B</TT>
<DD>Redirects all terminal output to the "bit bucket" <TT>/dev/null</TT>,
closes standard input, and places the program in the background.  This
parameter can be used only with one of the <TT>-i</TT>, <TT>-g</TT>,
<TT>-d</TT>, <TT>-s</TT>, <TT>-z</TT>, or <TT>-l</TT> parameters.  See the
section on <A HREF="#backop">Background Operation</A> below. <TT>-B</TT> is
ignored in menu mode.

<DT><TT>-q</TT>
<DD>overrides the startup warning if IPTraf is run on a machine with IP
Masquerading enabled.  Because IP Masquerading causes IPTraf to return
strange results, this warning is normally issued, but can be overridden
for more automated operation, provided you know how to interpret the
somewhat confusing output.
<DT><TT>-f</TT>
<DD>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.
<P>
The <TT>-f</TT> parameter overrides the existing locks imposed by the IPTraf
process and by 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 locks still lying
around.
<P>
The <TT>-f</TT> parameter may be used together with the others.
<DT><TT>iptraf -h</TT>
<DD>displays a short help screen
</DL>
<P>
While interactive commands in the IPTraf interface are not
case-sensitive, command-line options are.
<A NAME="usingmenus">
<H2>
Using the Menus
</H2>
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.
<P ALIGN=CENTER>
<IMG SRC="iptraf-mmenu.gif" ALT="Main Menu">
<P>
<A NAME="usingiptraf">
<H1>Using IPTraf</H1>
<A NAME="geninfo">
<H2>General Information</H2>
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.
<P>
<A NAME="numeric">
<H3>Number Display Notations</H3>
Initially IPTraf returns counts in bytes and packets.  However, as they
grow larger, IPTraf begins displaying them in higher denominations.
<P>
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
<P>
<PRE>
1024067		- exactly 1024067
1024K		- approximately 1024000
1024M		- approximately 1024000000
1024G		- approximately 1024000000000
1024T		- approximately 1024000000000000
</PRE>
<P>
These notations apply to both packet and byte counts.
<P>
<A NAME="loginfo">
<H3>Logging</H3>
The statistical facilities can log their counts and information to log files.
As of version 1.3, log files are by default stored in the directory 
<TT>/var/log/iptraf</TT>.  Each facility logs its information to its own log file.
See the <I>Logging</I> option under <A HREF="#options">Configuration</A>
below.
<P>
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.
<P>
<A NAME="updinfo">
<H3>Screen Update Delays</H3>
Older versions of IPTraf updated the screen as soon as a packet was received. 
However, screen updates are one of the slowest operations the program
performs.  Since version 1.3, a configuration option has been available to
control screen update speed.
<P>
See the <I>Screen update interval...</I> configuration option under the
<A HREF="#options">Configuration</A> section of this manual.
<P>
<A NAME="ifaceinfo">
<H3>Supported Network Interfaces</H3>
IPTraf currently supports the following network interface types and names.
<DL>
<DT><TT>lo</TT>
<DD>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 
<TT>dummy<I>n</I></TT> interface(s).
<DT><TT>eth<I>n</I></TT>
<DD>An Ethernet interface. <I>n</I> starts from 0. Therefore, eth0 refers
to the first Ethernet interface, eth1 to the second, and so on.  
Most machines only have one.

<DT><TT>fddi<I>n</I></TT>
<DD>An FDDI interface.  <I>n</I> starts from 0.

<DT><TT>ppp<I>n</I></TT>
<DD>A PPP interface. <I>n</I> starts from 0.  Therefore, ppp0
                is the first PPP interface, ppp1 is 
                the second, and so on.
<DT><TT>sli<I>n</I></TT>
<DD>A SLIP interface. <I>n</I> starts from 0. Same sequence
                as above
<DT><TT>ippp<I>n</I></TT>
<DD>A synchronous PPP interface using ISDN.  <I>n</I> starts from 0.
<DT><TT>isdn<I>n</I></TT>
<DD>ISDN interfaces can be given arbitrary names, but for them to work
with IPTraf, they must be named <TT>isdn<I>n</I></TT>.  IPTraf supports
synchronous PPP (the <TT>ippp<I>n</I></TT> interfaces above), raw IP, and
Cisco-HDLC encapsulation.
<DT><TT>plip<I>n</I></TT>
<DD>PLIP interfaces.  These are point-to-point IP connections using the PC
parallel port.
</DL>
<P>
Your system's network interfaces must be named according to the schemes
specified above.
<P>
<A NAME="itrafmon">
<H2>IP Traffic Monitor</H2>
Executing the first menu item or specifying <TT>-i</TT> to the <TT>iptraf</TT>
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.
<P>
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 <TT>Active</TT> indicator to the window you want 
to control.
<P ALIGN=CENTER>
<IMG SRC="iptraf-iptm1.gif" ALT="IP Traffic Monitor">
<P>
<A NAME="upper">
<H3>Upper Window</H3>
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:
<P>
<UL>
  <LI>Source address and port</LI>
  <LI>Packet count</LI>
  <LI>Byte count</LI>
  <LI>Packet Size</LI>
  <LI>Window Size</LI>
  <LI>TCP flag statuses</LI>
  <LI>Interface</LI>
</UL>
<P>
<HR>
<B>Note </B>Previous versions of IPTraf showed both the source and
destination addresses on each line.  IPTraf 2.0 shows only the source
host:port combination to save on screen real estate.  TCP connection
endpoints are still indicated with the green brackets along the left edge of
the screen.
<HR>
<P>
The TCP window is scrollable, and you can use the Up and Down arrow keys on
your keyboard to view more connections when the TCP window is marked Active.
<P>
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.
<P>
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.
<P>
Just because a host entry appears at the upper end of a connection bracket
doesn't mean it was  the initiator of the connection.
<P>
Each entry in the window contains these fields:
<P>
<B>Source address and port</B><BR>
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.
<P>
The destination is the host:port at the other end of the bracket.
<P>
<B>Packet count</B><BR>
The number of packets received for this direction of the
TCP connection
<P>
<B>Byte count</B><BR>
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.
<P>
<B>Packet Size</B><BR>
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.
<P>
<B>Window Size</B><BR>
The advertised window size of the most recently received packet.  This
item is visible if you press M for more TCP information.
<P>
<B>Flag statuses</B><BR>
The flags of the most recently received packet.

<DL COMPACT>
<DT><TT>S</TT>
<DD>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. 
<DT><TT>A</TT>
<DD>ACK.  This is an acknowledgment of a previously received packet
<DT><TT>P</TT>
<DD>PSH. A request to push all data to the top of the receiving queue
<DT><TT>U</TT>
<DD>URG. This packet contains urgent data
<DT><TT>RESET</TT>
<DD>RST. The source machine indicated in this direction reset the entire
connection.  The direction entries for reset connections become available
for new connections.
<DT><TT>DONE</TT>
<DD>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.
<DT><TT>CLOSED</TT>
<DD>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.
<DT><TT>-</TT>
<DD>The flag is not set
</DL>
<P>
Two more data items can also be viewed, the packet size and 
the advertised window size.  When the TCP window is marked Active, 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.
<P>
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 <I>Configure</I> menu.
<P>
<hr>
<h3>The rvnamed Process</h3>

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.
<P>
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.
<hr>
<hr>
<B>Tip </B>
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.
<HR>
<P>
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 <I>Configure</I> 
menu.
<P>
Some early entries may have a <TT>&gt;</TT> 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 <TT>&gt;</TT> entries will close (or 
time out) and disappear.  TCP entries without the <TT>&gt;</TT> were 
initiated after the traffic monitor started, and the counts 
indicate the totals of the connection itself.  Just consider 
entries with <TT>&gt;</TT> partial.
<P>
Some <TT>&gt;</TT> 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.)
<P>
Direction entries also become available for reuse if an ICMP 
Destination Unreachable message is received for the 
connection.
<P>
The lower part of the screen contains a summary line showing the
IP, TCP, UDP, ICMP, and non-IP byte counts since the start of the monitor. 
The IP, TCP, UDP, and ICMP counts include only the IP datagram header and
data, not the data-link headers.  The non-IP count includes the data-link
headers.
<P>
<HR>
<H3>Technical note: IP Forwarding and Masquerading</H3>
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.
<P>
On masquerading firewall machines, the behavior is even stranger.  A machine
performing IP masquerading translates between "real" IP addresses (i.e.
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.
<P>
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.
<HR>

<A NAME="lower">
<H3>Lower Window</H3>
The lower window displays information about the other types 
of traffic on your network.  The following protocols are 
detected:
<P>
<UL>
  <LI>UDP</LI>
  <LI>ICMP</LI>
  <LI>OSPF</LI>
  <LI>IGRP</LI>
  <LI>IGP</LI>
  <LI>IGMP</LI>
  <LI>ARP</LI>
  <LI>RARP</LI>
</UL>
<P>
Non-IP packets are simply indicated as Non-IP in the lower 
window.
<P>
<hr>
<B>Note </B>
The source and destination addresses for ARP and RARP entries
are MAC addresses. 
<P>
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.
<hr>

<P>
For all packets in the lower window, only the first IP fragment is
indicated (since that contains the header of the IP-encapsulated
protocol) but with no further information from the encapsulated protocol.
<p>
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).
<P>
<PRE>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		Bright white on Red
RARP		Bright white on Red
Other IP        Yellow on Red
Non-IP		Yellow on Red
</PRE>
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.
<P>
Some entries may be too long to completely fit in a screen line.  You can
use the Left and Right cursor keys to vertically scroll the lower window
when it is marked Active.
<P>
<B>Entry Details</B><BR>
In general, the entries in the lower window indicate the 
protocol, the IP datagram size (full frame size for non-IP, including ARP
and RARP), the source address, the destination address,
and the  network interface the packet was detected on.  However, some 
protocols have a little more information.
<P>
<B>ICMP:</B> ICMP entries are displayed in this format:

<P>
<TT>ICMP <I>type</I> (<I>subtype</I>) (<I>size</I> bytes) from <I>source</I>
to <I>destination</I> on <I>interface</I>
</TT>
<P>
where <TT><I>type</I></TT> could be any of the following:
<P>
<DL>
<DT><TT>echo request, echo reply</TT>
<DD>ICMP echo request and reply.  Usually used by the ping program and 
other network monitoring and diagnostic program.

<DT><TT>dest unreach</TT>
<DD>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.

<DT><TT>redirect</TT>
<DD>ICMP redirect.  Usually generated by a router to tell a host that a
better gateway is available.

<DT><TT>source quench</TT>
<DD>The ICMP source quench is used to stop a host from transmitting.  It's
some kind of flow control mechanism.

<DT><TT>time exceeded</TT>
<DD>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.

<DT><TT>router adv</TT>         <DD>ICMP router advertisement

<DT><TT>router sol</TT>         <DD>ICMP router solicitation

<DT><TT>timestamp req</TT>      <DD>ICMP timestamp request

<DT><TT>timestamp rep</TT>      <DD>ICMP timestamp reply

<DT><TT>info req</TT>           <DD>ICMP information request

<DT><TT>info rep</TT>           <DD>ICMP infromation reply

<DT><TT>addr mask req</TT>      <DD>ICMP address mask request

<DT><TT>addr mask rep</TT>      <DD>ICMP address mask reply

<DT><TT>parameter problem</TT>  <DD>ICMP parameter problem

<DT><TT>bad/unknown</TT>        <DD>An unrecognized ICMP packet was 
                                received, or the packet is corrupted.  
</DL>
<P>
The destination unreachable message also includes information
on the type of error encountered.  Here are the destination
unreachable codes:
<P>
<DL>
<DT><TT>network</TT>            <DD>network unreachable

<DT><TT>host</TT>               <DD>host unreachable

<DT><TT>protocol</TT>           <DD>protocol unreachable

<DT><TT>port</TT>               <DD>port unreachable

<DT><TT>DF set</TT>             <DD>the packet has to be fragmented 
                                somewhere, but its don't fragment (DF) 
                                bit is set.

<DT><TT>src route failed</TT>   <DD>source route failed

<DT><TT>src isoltd</TT>         <DD>source isolated (obsolete)

<DT><TT>net comm denied</TT>    <DD>network communication denied

<DT><TT>host comm denied</TT>   <DD>host communication denied

<DT><TT>net unreach for TOS</TT>   <DD>network unreachable for specified IP 
                                type-of-service

<DT><TT>host unreach for TOS</TT>  <DD>host unreachable for specified IP 
                                type-of-service

<DT><TT>prec violtn</TT>        <DD>precedence violation

<DT><TT>prev cutoff</TT>        <DD>precedence cutoff
	
<DT><TT>dest net unkn</TT>      <DD>destination network unknown

<DT><TT>dest host unkn</TT>     <DD>destination network unknown
</DL>
<P>
For more information on ICMP, see RFC 792.
<P>
<B>OSPF:</B> OSPF messages also include a little more information.
The format of an OSPF message in the window is:

<P>
<TT>OSPF <I>type</I> (a=<I>area</I> r=<I>router</I>) (<I>size</I> bytes)
from <I>source</I> to <I>destination</I> on <I>interface</I>
</TT>
<P>
The <TT><I>type</I></TT> can be one of the following:
<P>
<DL>
<DT><TT>hlo</TT>        <DD>OSPF hello.  Hello messages establish
                        OSPF communications and keep routers 
                        informed of each other's presence.

<DT><TT>DB desc</TT>    <DD>OSPF Database Description

<DT><TT>LSR</TT>        <DD>OSPF Link State Request

<DT><TT>LSU</TT>        <DD>OSPF Link State Update.  Messages 
                        indicating the states of the OSPF 
                        network links

<DT><TT>LSA</TT>        <DD>OSPF Link State Acknowledgment

</DL>
<P>
The entries in parentheses:
<P>
<DL>
<DT><TT>a=<I>area</I></TT>          <DD>The area number of the OSPF message
<DT><TT>r=<I>router</I></TT>        <DD>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.
</DL>
<P>
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:
<P>
<DL>
<DT><TT>224.0.0.5 (OSPF-ALL.MCAST.NET)</TT>       <DD>OSPF all routers
<DT><TT>224.0.0.6 (OSPF-DSIG.MCAST.NET)</TT>       <DD>OSPF all designated routers
</DL>
<P>
See RFC 1247 for details on the OSPF protocol.
<P>
With logging enabled, IP traffic monitor information is written to the file
<TT>ip_traffic.log</TT>.
<P>
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
<TT>iptraf&nbsp;-i</TT>).
<P>
<A NAME="gstats">
<H2>General Interface Statistics
</H2>
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 <I>Detailed interface
statistics</I> option is also available.
<P>
The activity indicators can be toggled between kbits/s and kbytes/s with the
<I>Activity mode</I> configuration option.
<P>
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.
<P>
Copies of the statistics are written to the log file
<TT>iface_stats_general.log</TT> at
regular intervals if logging is enabled.  See the <I>Logging</I>
option below.
<P>
This facility can be started directly from the command line
with the <TT>-g</TT> option to the <TT>iptraf</TT> command.
<P ALIGN=CENTER>
<IMG SRC="iptraf-gstat1.gif" ALT="General Interface Statistics">
<P>
You can press X or Q to return to the main menu.

<A NAME="dstats">
<H2>Detailed Interface Statistics</H2>

The third menu option displays packet statistics for any 
selected interface.  It provides basically the same 
information as the <I>General interface statistics</I> option, with 
additional information.  This option provides the following 
information:
<P>
<UL>
  <LI>IP packet and byte counts</LI>
  <LI>TCP packet and byte counts</LI>
  <LI>UDP packet and byte count</LI>
  <LI>ICMP packet and byte counts</LI>
  <LI>Other IP-type packet and byte counts</LI>
  <LI>Non-IP packet and byte counts</LI>
  <LI>Checksum error count</LI>
  <LI>Interface activity</LI>
</UL>
<P>
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 and Total byte
count.
<P ALIGN=CENTER>
<IMG SRC="iptraf-dstat1.gif" ALT="Detailed Interface Statistics">
<P>
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 total, incoming, and outgoing
interface data rates. 
<P>
This facility also displays incoming and outgoing counts
and data rates.  The packet size breakdown in versions prior to 2.0.0 has
been moved to its own facility under <I>Statistical breakdowns/By
packet size</I>.
<P>
An outgoing packet is one that exits your interface, regardless of whether
it originated from your machine or came from another machine and was 
routed through yours.  An incoming packet is one that enters your
interface, either addressed to you directly, broadcast, multicast, or
captured promiscuously.
<P>
The rate indicators can be set to display kbits/s or kbytes/s with the
<I>Activity mode</I> configuration option.
<P>
<HR>
<B>Note </B>
Buffering and some other factors may affect the data rates, notably
the outgoing rate, causing it to reflect a higher figure than the actual
rate at which the interface is sending.
<HR>
<P>
If you wish to start this facility directly from the command
line, you can specify the <TT>-d</TT> parameter and an interface to
monitor.  For example,

<P>
<PRE>        iptraf -d eth0
</PRE>

starts the statistics for eth0.  The interface must be
specified, or IPTraf will not start the facility.
<P>
<HR>
<B>Note </B>
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.
<P>
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.
<HR>
<P>
The figures are logged at regular intervals if logging is
enabled.
<P>
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).
<P>
<A NAME="pktsize">
<H2>Statistical Breakdowns</H2>
Statistical breakdowns contain two facilities that break down traffic counts
by either packet size or TCP/UDP port.
<P>
<H3>Statistical Breakdown: Packet Sizes</H3>
The packet size breakdown facility used to be incorporated into the
detailed interface statistics.  It has since been moved to its own
facility.  It is entered by selecting <I>Statistical Breakdowns/By packet
size</I>.
<P>
The packet size breakdown takes the interface's Maximum Transmission Unit
(MTU) size and divides it into 20 brackets, each bracket containing a
range of sizes.  As a packet is captured, its size is determined and the
appropriate bracket is incremented.
<P>
This facility provides an idea as to the packet sizes passing over your
network, and can aid in network (re)design decisions.
<P ALIGN=CENTER>
<IMG SRC="iptraf-pktsize.gif" ALT="Packet Size Breakdown">
<P>
If logging is enabled, copies of the statistics are written at regular
intervals to <TT>packet_size.log</TT> in the log directory.
<P>
The packet size breakdown can also be invoked straight from the command
line by specifying the <TT>-z <I>iface</I></TT> parameter.  The interface
parameter is required.  For example, this command runs the facility on
interface <TT>eth0</TT>.
<P>
<PRE>	iptraf -z eth0
</PRE>
<P>
To exit, press X or Ctrl+X.
<P>
<A NAME="serv">
<H3>Statistical Breakdown: TCP and UDP Traffic Statistics</H3>
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).
<P ALIGN=CENTER>
<IMG SRC="iptraf-tcpudp.gif" ALT="TCP/UDP Statistics">
<P>
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.
<P>
Byte counts include the IP header and payload only.  The data link
header is not included.
<P>
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).
<P>
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 <I>Configure/Additional port...</I> 
menu item.  See the section below.
<P>
The statistics are also written to the log file <TT>tcp_udp_services.log</TT>
if logging is enabled.
<P>

If you wish to start this facility from the command line,
you can use the <TT>-s</TT> option followed by an interface to
monitor.  For example,

<P>
<PRE>        iptraf -s eth0
</PRE>

brings up this module for traffic on eth0.  The interface must
be specified, or IPTraf will drop back to the shell.
<P>
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 NAME="hostmon">
<H2>LAN Station Statistics</H2>
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.
<P>
The entry above each line of statistics is the station's
LAN type (Ethernet, PLIP,  or FDDI) and the hardware MAC address. 
Each statistics line consists of the following information:
<P>
<UL>
<LI>Total packets incoming</LI>
<LI>IP packets incoming</LI>
<LI>Total bytes incoming</LI>
<LI>Incoming rate</LI>
<LI>Total packets outgoing</LI>
<LI>IP packets outgoing</LI>
<LI>Total bytes outgoing</LI>
<LI>Outgoing rate</LI>
</UL>
<P>
The byte counts include the data link header.  The activity indicators can
be set to display kbits/s or kbytes/s with the <I>Activity mode</I>
configuration option.
<P>
This facility works only for Ethernet, PLIP, and FDDI frames.  Loopback.
ISDN, and  SLIP/PPP networks are not monitored here.
<P ALIGN=CENTER>
<IMG SRC="iptraf-hw.gif" ALT="LAN Station Statistics">
<P>
Copies of the statistics are written to the log file
<TT>lan_statistics.log</TT> at regular
intervals if logging is enabled.
<P>
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 <TT>-e</TT> command-line option).

<A NAME="filters"> 
<H2>Display Filters</H2>
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.
<P>
<A NAME="tcpfilter">
<H3>TCP Filters</H3>
The <I>TCP display filters</I> 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.
<P ALIGN=CENTER>
<IMG SRC="iptraf-tcpfltmenu.gif" ALT="TCP Filter Menu">
<P>
<A NAME="tfilterdef">
<B>Defining a New Filter</B><BR>
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 <I>Define new filter...</I> option. 
<P>
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.
<P ALIGN=CENTER>
<IMG SRC="iptraf-tcpflt-dlg1.gif" ALT="TCP Filter Description Dialog">
<P>
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.
<P>
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.
<P>
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).
<P>
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:

<PRE>
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
</PRE>

The IP address/wildcard mask mechanism of the display filter 
doesn't recognize IP address class.  It uses a simple bit-
pattern matching algorithm.
<P>
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).
<P>
Leaving the wildcard mask fields blank or storing invalid data in them
causes the filter to recognize the entries as 255.255.255.255.
<P>
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.
<P>
<hr>
<B>Tip </B>
See the Linux Network Administrator's Guide if you need more 
information on IP addresses and subnet masking.
<hr>
<P>
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).
<P>
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.
<P>
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.
<P>
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.
<P ALIGN=CENTER>
<IMG SRC="iptraf-tcpflt-dlg2.gif" ALT="TCP Filter Parameter Dialog">
<P>
<B>Examples</B><BR>
To see all traffic to/from host 202.47.132.1 from/to 
207.0.115.44, regardless of TCP port

<P>
<PRE>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
</PRE>

To see all traffic from/to 207.0.115.44 to/from network 
202.47.32.0
<P>
<PRE>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
</PRE>

To see all Web traffic, regardless of source or destination
<P>
<PRE>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
</PRE>

To see all mail (SMTP) traffic to a single host 
(202.47.132.2) from anywhere

<P>
<PRE>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
</PRE>

To see traffic to/from host sunsite.unc.edu from/to cebu.mozcom.com
<P>
<PRE>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
</PRE>

To omit display of traffic to/from 140.66.5.x from/to anywhere
<P>
<PRE>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
</PRE>
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".
<P>
You can enter as many parameters as you wish.  All of them 
will be interpreted when the filter is processed.
<P>
<B>Excepting Certain Sites from the Display</B><BR>
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, <I>except</I> 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, tagged
with an I in the Include/Exclude field as the <I>last</I> entry.
<P>
For example:
<P>
To see all traffic except all SMTP, Web, and traffic from/to 207.0.115.44:
<P>
<PRE>
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
</PRE>
<P>
<HR>
<B>Tip </B>
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.
<HR>
<P>
<A NAME="tfilterapp">
<B>Applying a Filter</B><BR>
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.
<P>
The applied filter stays in effect over exits and restarts of the
IPTraf program until it is detached.
<P>
<A NAME="tfilteredit">
<B>Editing a Defined Filter</B><BR>
Select <I>Edit filter...</I> to modify an existing filter.  Once you select
this option, you will be presented with the list of defined filters.  Select
the filter you want to edit by moving the pointer and press Enter.
<P>
Edit the description if you wish.  Pressing Ctrl+X at this point will abort
the operation, and the filter will remain unmodified.  Press Enter to accept
any changes to the filter description.
<P ALIGN=CENTER>
<IMG SRC="iptraf-editfilter.gif">
<P>
After pressing Enter, you will see the filter's rules.  To edit an existing
filter rule, move the pointer to the desired entry and press Enter.  A
prefilled dialog box will appear.  Edit its contents as desired.  Press
Enter to accept the changes or Ctrl+X to discard.
<P>
You can add a new filter rule by pressing I to insert at the current pointer
position.  When you press I, you will be presented with a dialog box asking
you to enter the new rule data. Pressing A results in a similar operation,
except the rule will be appended as the last entry in the rule list.
<P>
Pressing D deletes the currently pointed entry.
<P>
Press X or Ctrl+X to end the edit and save the changes.
<P>
<HR>
<B>Note </B>Be aware that the filter process the rules in order.  In other
words, if a packet matches more than one rule, only the first matching rule
is followed.
<HR>
<P>
<A NAME="tfilterdel">
<B>Deleting a Defined Filter</B><BR>
Select <I>Delete filter...</I> from the menu to remove a filter from 
the list.  Just move the pointer to the filter you want to 
delete, and press Enter.
<P>
<A NAME="tfilterdet">
<B>Detaching a Filter</B><BR>
The <I>Detach filter</I> option deactivates the filter currently in 
use.  Selecting this option causes all TCP information to be 
displayed by the traffic monitor.
<P>
When you're done with the menu, just select the <I>Exit menu</I> 
option.
<A NAME="othpfilter">
<H3>Other Protocol Filters</H3>
You can select the other IP-type protocols you want to 
display or omit with the <I>Other protocol filters...</I> 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.
<P ALIGN=CENTER>
<IMG SRC="iptraf-othfltmenu.gif" ALT="Non-TCP Filters">
<P>
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 <I>UDP...</I> 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.  Custom UDP filters can be defined, edited, and deleted as
TCP filters.  See the section on <I><A HREF="#tcpfilter">TCP Filters</A></I>
above.
<P>
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.
<P>
The <I>Non-IP</I> filter option toggles the display and logging of all
non-IP packets, excepting ARP and RARP, which are toggled separately.
<P>
The filters for non-TCP protocols are saved and automatically
reapplied whenever IPTraf is restarted after an exit.
<P>
<A NAME="options">
<H2>Configuring IPTraf</H2>
IPTraf can be easily configured with the <I>Configure</I> item in the 
main menu.  The configuration is stored in the 
<TT>/var/local/iptraf/iptraf.cfg</TT> file. If the file is not found, 
IPTraf uses the default settings.  Any changes to the 
configuration immediately get stored in the configuration 
file.
<P ALIGN=CENTER>
<IMG SRC="iptraf-configmenu.gif" ALT="Configuration Menu">
<P>
<B>Reverse Lookup</B><BR>
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.
<P>
This option is off by default.
<P>
<B>TCP/UDP Service Names</B>
<BR>
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.
<P>
This setting is off by default.
<hr>
<B>Note </B>
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.
<HR>
<P>
<B>Promiscuous Operation</B><BR>
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.
<P>
When this option is disabled, you'll only receive 
information about packets coming from and entering your 
machine.
<P>
The setting of this option affects all LAN (both Ethernet and FDDI)
interfaces on your machine, if you have more than one.
<P>
Regardless of the initial setting of the interfaces' 
promiscuous flags, IPTraf turns them off when it exits. 
Promiscuous mode is off by default.
<P>
<HR>
<B>Note </B>
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.
<HR>
<P>
<B>Color</B><BR>
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.
<P>
Color is on by default on consoles, off on non-color terminal
types like xterms and VT100s.
<P>
<B>Logging</B><BR>
When this option is active, IPTraf will log information to a 
disk file, which can be examined later.  Each facility has its own log
file in (by default) the <TT>/var/log/iptraf</TT> directory as follows:
<P>
<PRE>
	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
	Packet Size Breakdown		- packet_size.log
	LAN Station Monitor             - lan_statistics.log
</PRE>
<P>
The traffic monitor will write the following pieces of 
information to its log file:
<P>
<UL>
  <LI>Start of the traffic monitor</LI>
  <LI>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.)</LI>
  <LI>Receipt of a FIN</LI>
  <LI>ACK of a FIN</LI>
  <LI>Timeouts of TCP entries</LI>
  <LI>Everything that appears in the bottom window of the traffic monitor</LI>
  <LI>Stopping of the traffic monitor</LI>
</UL>
<P>
Each log entry includes the date and time the entry was 
written.  Logging is also affected by the defined filters.
<P>
Log files can grow very fast, so be prepared with plenty of 
free space and delete unneeded logs.  Log write errors are 
not indicated.
<P>
Copies of the interface statistics, TCP/UDP statistics, packet size
statistics, and LAN host statistics are also written to the log
files at regular intervals.  See <I>Log Interval...</I> below.
<P>
IPTraf closes and reopens the active log file when it receives a USR1
signal.  This is useful in cases where a facility is run for long periods
of time but the log files have to be cleared or moved.
<P>
To clear or move an active log file, rename it first.  IPTraf will
continue to write to the file despite the new name.  Then use the UNIX
<TT>kill</TT> command to send the running IPTraf process a USR1 signal.
IPTraf will then close the log file and open another with the original
name.  You can then safely remove or delete the renamed file.
<P>
Do not delete an open log file.  Doing so will only result in a file just
as large but filled with null characters (ASCII code 0).
<P>
Logging comes disabled by default.  The USR1 signal is caught only if
logging is enabled, it is ignored otherwise.
<P>
<B>Activity mode</B><BR>
Toggles activity indicators in the interface and LAN statistics facilities
between kilobits per second (kbits/s) or kilobytes per second (kbytes/s).
<P>
The default setting is kilobits per second.
<P>
<B>TCP Timeout</B></BR>
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.
<P>
<B>Log Interval</B><BR>
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.
<P>
<B>Screen Update Interval</B><BR>
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.
<P>
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.
<P>
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. <P>
<HR>
<B>Note </B>
Screen updating is one of the slowest operations in a program.  Older
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.
<P>
However, since many users like rapid counts on their screen, a compromise was
incorporated.  Even 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.
<P>
In any case, this setting only affects screen updates.  Capture still 
proceeds as fast as possible.
<P>
<HR>
<P>
<B>Additional port</B><BR>
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.
<P>
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.
<P>
You can select this option multiple times to add more values or ranges.
<P>
<B>Delete port/range</B><BR>
Select this item to remove a higher-numbered port number or port range you 
entered earlier with the <I>Additional port...</I> option.  A window will
come up containing the entered ports and ranges.  Select the entry you
want delete and press Enter.
<P>
<A NAME="ethdesc">
<H2>LAN Station Identifiers</H2>
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.
<P>
Selecting the
<I>Ethernet/PLIP host descriptions</I> or <I>FDDI host descriptions</I> options
brings up a submenu asking you to add, edit, or delete descriptions.
<P>
To add a new description, select the <I>Add description...</I> 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.
<P>
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.
<P>
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.
<P>
Enter as many descriptions as you need.  Press Ctrl+X at a blank dialog
after you have entered the last entry
<P>
These descriptions will be displayed alongside the MAC addresses in
the LAN station monitor, together with the type of frame (Ethernet, PLIP,
or FDDI).
<P>
An existing address or description may be edited by selecting the
<I>Edit description...</I> 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.
<P>
Selecting the <I>Delete description...</I> 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.
<P>
<HR>
<B>Note </B>
The description file for Ethernet and PLIP is <TT>ethernet.desc</TT>,
while the FDDI descriptions are stored in <TT>fddi.desc</TT> in the IPTraf
working directory.  These files are in colon-delimited text format.
Database engines or custom scripts can be told to
append data lines to those files.  Each line follows this simple format:
<P>
<UL>
<TT><I>address</I>:<I>description</I></TT>
</UL>
For example
<UL>
<P>
<TT>00201e457e:Cisco 3640 gateway</TT>
</UL>
<P>
Do not put colons, periods, or any invalid characters in the MAC address.
<HR>
<P>
<A NAME="backop">
<H1>Background Operation</H1>
IPTraf's facilities can be placed in the background solely for logging.
When running in the background, it doesn't display any output on the
screen, and doesn't receive input from the keyboard, and drops you back to
the shell.
<P>
Before starting a statistical facility in the background, configure IPTraf
in the usual way (set filters, add TCP/UDP ports, etc).
<P>
Once that's done, exit all instances of IPTraf on the system, then invoke
IPTraf from the command line with the parameter to start the facility you
want, the timeout (<TT>-t</TT>) parameter if you wish, and the
<TT>-B</TT> parameter to actually daemonize the program.  For example, to
run the IP Traffic Monitor in the background for all interfaces, issue the
command
<P>
<UL>
<TT>iptraf -i all -B</TT>
</UL>
<P>
To run the Detailed Interface Statistics on interface <TT>eth0</TT> for 5
minutes in the background:
<UL>
<TT>iptraf -d eth0 -t 5 -B</TT>
</UL>
<P>
If the timeout parameter is not specified, the facility will run until the
process recieves a USR2 signal.  To stop a facility in the background, do
a
<UL>
<TT>ps x</TT>
</UL>
at the command line, and find the process id (pid) of the iptraf process
you're looking for.  Then send that process a USR2 signal with the
<TT>kill</TT> command:
<UL>
<TT>kill -USR2 <I>pid</I></TT>
</UL>
<P>
Since IPTraf cannot send error messages to the terminal, all messages are
written to the file <TT>daemon.log</TT> in the IPTraf logging directory.
<P>
The <TT>-B</TT> automatically enables logging regardless of its
configured setting.  The parameter is ignored if not used with one of the
parameters to start a facility from the command line.
<P>
<A NAME="messages">
<H1>Messages</H1>

<B>Unable to create config file</B><BR>
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 <TT>/var/local/iptraf</TT> does 
not exist.  Can also be generated if you have a disk problem 
or if you have too many files open.
<P>
<B>Unable to read config file</B><BR>
The configuration record cannot be read.  You most likely 
have a disk problem.
<P>
<B>Unable to write config file</B><BR>
The configuration file cannot be written.  You either have a 
disk problem, or (more likely), your disk is full.
<P>
<B>Error loading filter list file</B><BR>
IPTraf cannot access the list of defined TCP or UDP filters.  
Can also be an indicator of a bad disk.
<P>
<B>Error writing filter list file</B><BR>
The filter list file cannot be written to.  You may have trouble accessing
your filters.
<P>
<B>Unable to read filter file</B><BR>
IPTraf cannot read the filter data off the file.  Could be 
caused by a bad disk.
<P>
<B>Error opening filter file</B><BR>
IPTraf cannot open the filter file.  Could be caused by a shortage of file
descriptors or a bad disk.
<P>
<B>Unable to write TCP/UDP filter record</B><BR>
IPTraf cannot add the newly defined filter to the filter 
list.
<P>
<B>Cannot create TCP/UDP filter record file</B><BR>
IPTraf cannot create the filter record file.  The defined filter is lost.
<P>
<B>Unable to create TCP/UDP filter file</B><BR>
IPTraf cannot create the filter data file.
<P>
<B>Unable to save TCP/UDP filter name</B><BR>
IPTraf cannot save the name of the current TCP filter.  IPTraf will start
with no filters active the next time it is invoked.
<P>
<B>Unable to save filter changes</B>
IPTraf cannot save the changes you made to the filter.  You probably have a
disk error.
<P>
<B>Unable to retrieve saved TCP/UDP filter</B><BR>
The saved filter cannot be retrieved.  IPTraf will start with no TCP filters
active.
<P>
<B>Unable to write non-TCP filters</B><BR>
IPTraf was not able to write the filters for the other protocols.  Probably
due to a bad disk or full filesystem.
<P>
<I>protocol</I> <B>data file in use; try again later</B><BR>
Another IPTraf process is modifying the TCP or UDP filter data, and has
locked the files.  Try again once the other IPTraf process has terminated
or completed its modifications and unlocked the files.
<P>
<B>Unable to resolve </B><I>hostname</I><BR>
The indicated host name in the filter cannot be resolved into an IP address.
Check the local hosts database <TT>/etc/hosts</TT> or your machine's DNS
configuration or DNS server.
<P>
The filter parameters will not be used.
<P>
<B>Unable to open host description file</B><BR>
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.
<P>
<B>Unable to write host description</B><BR>
IPTraf was unable to write the description record for this Ethernet or FDDI
address.  Could be due to a bad disk or corrupted filesystem.
<P>
<B>No descriptions</B><BR>
You tried to edit or delete a description with no previous descriptions
defined.
<P>
<B>Cannot open log file</B><BR>
There is a problem opening the log file.  There is most 
likely a problem with the disk, or there are too many open 
files.
<P>
<B>Unable to obtain interface list</B><BR>
IPTraf was unable to retrieve the list of network interfaces from the
<TT>/proc</TT> filesystem.  This may be due to a badly configured kernel.
IPTraf needs <TT>/proc</TT> filesystem support.
<P>
<B>Unable to obtain interface parameters</B><BR>
The system call to retrieve the interface's flags failed.  Check your
interface or kernel driver.
<P>
<B>Promisc change failed for</B> <I>interface</I><BR>
The system call to change the promiscuous flag failed.  Check your interface
or its kernel driver.
<P>
<B>Unable to open raw socket for flag change</B><BR>
IPTraf was unable to open the necessary socket for the promiscuous change
operation.  May be due to a shortage of file descriptors.
<P>
<B>Unable to open socket for MTU determination</B><BR>
Returned by the facility for detailed interface statistics if the raw
socket's opening sequence failed.  The facility will abort.
<P>
<B>Unable to open raw socket</B><BR>
IPTraf was unable to open the raw socket for packet capture.  May be due
to a shortage of file descriptors.
<P>
<HR>
<B>Reminder </B>IPTraf 2.x.x requires Linux kernel 2.2.x, with the <I>Packet
Socket</I> option compiled in or installed as a module.  IPTraf 2.x will
return this error on a pre-2.2 kernel or on a 2.2 kernel without <I>Packet
Socket</I>.
<HR>
<P>
<B>Unable to obtain interface MTU</B><BR>
The detailed statistics facility was unable to obtain the maximum
transmission unit (MTU) for the selected interface.  The facility will
abort.
<P>
<B>Specified interface not supported</B><BR>
The interface specified with the <TT>-i</TT>, <TT>-d</TT>, <TT>-s</TT>,
<TT>-l</TT> or <TT>-z</TT>
command-line parameters is not supported by IPTraf.
<P>
<B>Specified interface not active</B><BR>
The interface specified with the <TT>-i</TT>, <TT>-d</TT>, <TT>-s</TT>,
<TT>-l</TT> or <TT>-z</TT>
command-line parameters is supported, but not currently activated.
<P>
<B>Critical error: unable to allocate memory for a critical function</B><BR>
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.
<P>
<HR>
<B>Technical note:</B> This is actually a response to the segmentation fault
error (SIGSEGV).
<HR>
<P>
<B>This program can be run only by the system administrator</B><BR>
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
<P>
<B>Your TERM variable is not set</B><BR>
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".
<P>
<B>Received TERM signal</B><BR>
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.
<P>
<B>Invalid option or missing parameter, use iptraf -h for help</B><BR>
The <TT>-i</TT>, <TT>-d</TT>, <TT>-s</TT>, <TT>-z</TT> or <TT>-l</TT>
options were specified but no interface was specified on the command line.
These parameters require a valid interface name (or <TT>all</TT> for
<TT>-i</TT> or <TT>-l</TT>).
<P>
This message also appears if an unknown option is passed to the <TT>iptraf</TT>
command.
<P>
<B>Warning: unable to tag this process</B><BR>
IPTraf normally tags itself when it runs to prevent multiple instances of
the statistical facilities from running.  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.
<P>
<B>Warning: unable to tag </B><I>facility</I><BR>
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.
<P>
<I>facility</I><B> already active in another process</B><BR>
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.
<P>
<B>Duplicate port/range entry</B><BR>
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
<P>
<B>No custom ports</B><BR>
There are no ports or port ranges earlier added.  There's nothing to
delete.
<P>
<B>Can't start rvnamed; lookups will block</B><BR>
IPTraf cannot start the rvnamed daemon; probably due to a bad installation.
IPTraf will fall back to blocking lookups.
<P>
<B>Can't start new process; lookups will block</B><BR>
IPTraf cannot start a new process.  This may be due to memory shortage.
IPTraf will fall back to blocking lookups.
<P>
<B>Fork error, IPTraf cannot run in background</B><BR>
IPTraf cannot start a new process, and can go into the background.  This
may be due to memory shortage.  IPTraf aborts.
<P>
<B>Memory Low</B>
<BR>
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.
<P>
<B>IPC Error</B>
<BR>
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 <TT>rvnamed.log</TT> file.
<P>
<B>Error opening terminal:</B> <I>terminal</I><BR>
The screen management routines cannot find the terminfo entry for your
terminal.  IPTraf expects the terminfo database located in
<TT>/usr/share/terminfo</TT>.  This error could occur when your terminfo
database is located somewhere else.
<P>
See the section above on controlling the terminfo search path.
<P>
<H2>rvnamed Messages</H2>
<P>
Being a daemon, rvnamed does not send messages to the screen.  It writes
its messages to the file <TT>rvnamed.log</TT> in the IPTraf working directory.
<P>
<B>Unable to open child communication socket</B><BR>
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.
<P>
<B>Unable to open client communication socket</B><BR>
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.
<P>
<B>Error binding client communication socket<BR>
Error binding child communication socket</B><BR>
rvnamed was unable to assign a name to the indicated communication socket.
This may be due to a bad, full, or corrupted filesystem.
<P>
<B>Fatal error: no memory for descriptor monitoring</B><BR>
rvnamed ran out of memory.  IPTraf will resort to blocking, and may freeze.
<P>
<B>Error on fork, returning IP address</B><BR>
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.
<P>
<A NAME="appendices">
<H1>Technical Appendices</H1>
<A NAME="recompiling">
<H2>Recompiling the Program</H2>
With both the downloaded and floppy distributions, you can 
recompile the program immediately before you do the <TT>make 
install</TT>.  Perform the following steps to recompile:
<P><OL>
<LI>Change to the src directory and clear out the supplied 
binaries by entering
 
<P>
<PRE>        make clean
</PRE>
</LI> 
<LI>Recompile by entering
 
<P>
<PRE>        make
</PRE>

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.
</OL>
<P>
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.
<P>
If you have the appropriate libraries and facilities, you 
can recompile the program to use the shared versions of the 
ncurses and panels libraries.
<P>
Recompiling requires:
<P>
<UL>
  <LI>Linux 2.2.0 or later</LI>
  <LI>gcc-2.7.0 or later (2.7.2.3 or later for glibc2)</LI>
  <LI>ncurses-1.9.9e or later (earlier versions have problems 
        with the Backspace key and updates of overlapping windows)</LI>
  <LI>GNU make</LI>
</UL>
<P>
<H3>Makefile Options</H3>
The Makefile has several options you can change.  You 
probably don't need to change most of them, probably with 
the exception of LDOPTS
<P>
The <TT>dirs.h</TT> 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.
<P>
Read the comments in the Makefile and dirs.h files for information on the
various directives.
<P>
When compilation is complete, enter

<P><PRE>        make install
</PRE>

to install the resulting executable modules in the proper directory.
<A NAME="technotes">
<H2>Technical Notes</H2>
<I>(also in the README file)</I>
<A NAME="kernel">
<H3>Kernel</H3>
IPTraf 2 requires the 2.2.x series of the Linux kernel.  If you still have
Linux 2.0, continue using IPTraf 1.4.  You must make sure your 2.2 kernel
has the Packet Socket functionality compiled in or installed as a module, or
IPTraf will fail.
<P>
The new kernel's raw packet capture facility has been extended since the
last stable kernel release, and IPTraf now takes advantage of the new
functionality, enabling it to count packets on a directional
(incoming/outgoing) basis.
<P>
<A NAME="security">
<H3>Security</H3>
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 <TT>-DALLOWUSERS</TT> 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.
<P>
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.
<A NAME="terminal">
<H3>Terminal</H3>
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.
<P>
IPTraf will use the maximum number of available lines and columns in the
terminal.

<A NAME="userinterface">
<h3>User Interface</H3>
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.
<P>
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 <TT>-DDISABLEBS</TT> directive in 
the Makefile.
<P>
Earlier versions of ncurses also did not properly define the behavior
of overlapping windows.  This has been fixed in 1.9.9e.

<A NAME="netifaces">
<H3>Network Interfaces</H3>
IPTraf currently includes support for Ethernet, FDDI, loopback, 
asynchronous SLIP/PPP, PLIP, and ISDN (synchronous PPP, Cisco-HDLC, and
raw IP encapsulations).
<P>
With 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.
<P>
IPTraf imposes no additional load on the network, except for 
DNS traffic if reverse name lookup is enabled.  (Some setups use RPC calls
to obtain service name information.  This could also add UDP traffic to
the network.)
<P>
<HR>
<A NAME="GPL">
<H1>License and Copyright for IPTraf</H1>

IPTraf 2.1 Copyright &copy; Gerard Paul Java, 1997-1999
<P>
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. 
<P>
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.
<P>
IPTraf uses header files that are part of the GNU C library and the Linux 
kernel distribution.
<P>
Additional structures were extracted from software 
copyrighted by the Regents of the University of California.
<P>
Linux is a registered trademark of Linus Torvalds
<P>
Pentium is a registered trademark of Intel Corporation.
<P>
<HR>
<I>IPTraf User's Manual, HTML Version 2.1.1<BR>
Copyright &copy; Gerard Paul Java 1997-1999</I>
</BODY>
</HTML>