ConnMon - Connection Monitor
============================

Connection Monitor is a connection and bandwidth monitoring program
with console (ncurses) and X (gtk) based user interfaces. It displays
a list of open TCP and UDP connections with transfer rates in bytes
per second for each connection.

The transfer rates display requires a Linux 2.4 kernel with Netfilter
connection tracking facilities, with a small (included) patch applied.
ConnMon will still work with kernels (2.2 or 2.4) without this patch,
however no transfer rates will be displayed.

Communication with the kernel is done through /proc/net/ip_conntrack.
This file is read a few times a second. (The kernel patch extends this
file to contain packet- and byte-count information for each connection,
which makes monitoring of transfer rates possible.) Because of this,
ConnMon is well suited for systems with fewer (1000 or less) simultaneous
connections. Unlike similar programs such as IPTraf, ConnMon's use of
CPU-time does not increase when the total transfer rate increases.

As of version 0.9.0, ConnMon also supports connection monitoring on
2.2 (and possibly earlier) kernels. This is done through the
/proc/net/tcp and /proc/net/udp files. See below on how to use this.

ConnMon uses the GNU adns library to make asynchronous DNS lookups.

Features
========

For the impatient ones, here is a summary of ConnMon's features:

  NCurses and GTK user interface
  Interactive terminal-based user interface using ncurses
  Shows TCP, UDP and ICMP connections with Netfilter
  Shows TCP and UDP connections without Netfilter
  Shows transfer rates in bytes/KB/MB/GB per second for each connection and
  total transfer rate for all connections (only if statistics patch is applied)
  Built-in help screen
  Supports resizing of the terminal window
  Asynchronous and fast DNS lookups and lookup via /etc/hosts (or other file)
  Host name caching
  Port name lookup via /etc/services (or other file)
  Multiple instances can be run at the same time
  Does not require any root privilegies to run
  Written entirely in C
  Modular design to make connection monitors for X possible in the future
  Released under the GPL

Copyright and License
=====================

ConnMon is copyright (C) 2001 Oskar Liljeblad.

Some of the source code in the compat subdirectory may be
copyright (C) 1990, 1998, 2000 Free Software Foundation, Inc.
That source code was borrowed from GNU fileutils.

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Binary distribution
===================

Packages of ConnMon is available for the following linux distributions:

  Debian

    A debian package can be downloaded from ConnMon's home page.
    This package is not in the main Debian distribution at the
    momemt, but may be included in the future if someone is willing
    to do it.

  Red Hat, SuSE and other RPM-based distributions

    RPM packages can be downloaded from ConnMon's home page. (Note
    that the adns package is required.) Those packages were built
    on a non-RPM system, therefore the packages provided by Pascal
    Bleser <guru@linuxbe.org> may be safer and better overall.
    They are available at:
    
      http://guru.linuxbe.org/rpm/SuSE-7.3/Network/Monitoring/
      http://guru.linuxbe.org/rpm/SuSE-7.3/Network/DNS/ (adns)

Requirements
============

ConnMon does at this point only support Linux, and because of that
it has not been written with portability in mind. (However, it
would not be too hard porting it to another system, taken that
the necessary kernel facilities were provided.)

Build requirements:

  gcc 2.95 or later

    ConnMon builds properly with gcc 2.95.4 and 3.0. It is doubtful that
    it will build with earlier versions. On Debian the required packages
    are gcc and gcc-2.95.

  GNU adns 1.0 or later header files

    ConnMon builds properly with adns 1.0, but may build with earlier
    version as well. On Debian the required packages are libadns1 and
    libadns1-dev.
    
    NOTE: If you install GNU adns manually, you need to create a
    symbolic link "libadns.so" to "libadns.so.1.0" in the directory
    where you installed the latter:
    
      cd /usr/local/lib  [or corresponding directory]
      ln -s libadns.so.1.0 libadns.so

    For some reason GNU adns does not do this during install.

  ncurses 5.0 or later header files.

    ConnMon builds properly with ncurses 5.2, but may build with earlier
    version as well. On Debian the required packages are libncurses5 and
    libncurses5-dev.

  glib and gtk 1.2 or later header files.

    The GTK version of ConnMon, GConnMon, requires gtk and therefore also
    glib. On Debian the required packages are libgtk1.2, libgtk1.2-dev,
    libglib1.2 and libglib1.2-dev.

Use requirements:

  Linux 2.2 or
  Linux 2.4 with Netfilter and Connection tracking (recommended)
  and the conntrack statistics patch (optional but recommended)

    The statistics patch is not required but highly recommended. It can
    be found in the kernel subdirectory of the ConnMon sources. There
    are two types of patches - those for patch-o-matic and those against
    the kernel (full). The patch-o-matic patches should be applied
    with the "runme" command found in patch-o-matic directory of the
    iptables distribution. The full ones should be applied with the
    patch(1) command, e.g. like this:
    
      tar xvfz linux-2.4.17.tar.gz
      cd linux ; patch -p1 <~/connmon/kernel/statistics-2.4.17-full.patch

    The following kernel configuration directives must be enabled
    if you wish to use the Netfilter interface:

      CONFIG_NETFILTER
      CONFIG_IP_NF_CONNTRACK

    This directive enables the ip_conntrack statistics:

      CONFIG_IP_NF_STATS

    After this, the only module that needs to be loaded is ip_conntrack.
    You can verify that the ip_conntrack facilities are working and the
    statistics patch has been applied by looking in the contents of the
    /proc/net/ip_conntrack file. If each line in this file contains
    rx= and tx= strings then everything is fine. Otherwise the statistics
    patch has not been applied correctly.

  GNU libc 2.1 or later

    ConnMon uses some GNU libc-specific functions such as getline.

  GNU adns 1.0 or later

  ncurses 5.0 or later

  glib and gtk 1.2 or later

ConnMon does not need root privilegies to run since the
/proc/net/ip_conntrack file is world readable by default.

Building and Installation
=========================

NOTE: The default kernel interface (hereafter referred to as
the driver) is "netfilter". It will only work with 2.4 kernels
with the Netfilter facilities installed. If you wish to use
ConnMon with earlier kernels or kernels without the Netfilter
facilities, you will need to either start connmon with the
`-elinux' option, or edit config.h and change the
DEFAULT_CONNMON_DRIVER define to "linux".

Simply run `make'. ConnMon is best installed by copying the
connmon executable in some appropriate directory (usually
/usr/local/bin or /usr/bin).

Build errors and runtime problems
=================================

This section describes some errors which may occur when building
ConnMon:

../libhpnl/lib_hpnl.a(hnl_adns.o): In function `adns_hnl_free':
[..]: undefined reference to `adns_submit'
[..]: undefined reference to `adns_submit'
[..]
collect2: ld returned 1 exit status

  This is caused by a missing libadns.so file in the directory where
  adns libraries were installed. If you installed adns manually this
  file must be created:
    
    cd /usr/local/lib  [or corresponding directory]
    ln -s libadns.so.1.0 libadns.so

These errors may occur when starting connmon:

connmon: error while loading shared libraries: libadns.so.1: cannot
load shared object file: No such file or directory

  This may be caused on Red Hat (and possibly other systems) where
  /usr/local/lib is not searched for libraries. To see if that is
  the case, start connmon like this:

    LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH connmon

  If that works you should add /usr/local/bin to your /etc/ld.so.conf.

strbuf.h:37: badly punctuated parameter list in `#define'
make[2]: *** [io-utils.o] Error 1
[..]

  This happens because the C compiler does not support macros with
  variable number of arguments (which is used in strbuf.h). If you
  are using gcc 2.95 or later, please email me. Otherwise, try
  upgrading your compiler.

Some very old TCP connects show up in the connection list of connmon.

  This appears to be a bug (or feature) in netfilter in the kernel.
  For some reason, there's a timeout of 5 days defined in
  net/ipv4/netfilter/ip_conntrack_proto_tcp.c in the kernel sources.

Usage
=====

Just run `connmon'. A few command line options are accepted -
they can be listed with `connmon --help'.

Note that if the statistics patch is not applied, you will not
see any transfer rates. Instead, `--' will be displayed for
transfer rate.

Color schemes
=============

For the impatient ones, just check out the schemes in the `examples'
directory.

Color schemes control how to color and highlight certain parts of the
display. The display is divided into certain areas such as
`main_header_top' (the top line with "Connmon X.Y.Z") or `conn_host_ip'
(the IP number of displayed connections). (For a list of all these
areas, see the example files.) Each such area can be given certain
curses attributes. The possible attributes are:

  normal    	Normal display (no highlight)
  standout  	Best highlighting mode of the terminal.
  underline 	Underlining
  reverse   	Reverse video
  blink     	Blinking
  dim	    	Half bright
  bold      	Extra bright or bold
  protect   	Protected mode
  invis     	Invisible or blank mode
  altcharset	Alternate character set
  chartext  	Bit-mask to extract a character

Example:

  conn_host_ip		bold

It is also possible to specify color by naming two colors,
foreground and background:

  conn_host_ip		white black

Note that both foreground and background must be specified.
Attributes and colors can be combined:

  conn_host_ip		bold white black blink

Some terminals support custom colors, i.e. creating colors
with any RGB values. In the color scheme files this is done
with the color keyword, for example:

  color pink 255 105 180

(Custom colors need to be defined before they are used.)
The following colors are built in:

  black
  red
  green
  yellow
  blue
  magenta
  cyan
  white

One last thing: Comments introduced by `#' can appear anywhere
in the file.

Homepage
========

The latest version of ConnMon can be downloaded from

  http://www.student.lu.se/~nbi98oli/

Feedback
========

The author of ConnMon and this document, Oskar Liljeblad, can be
reached via email:

  oskar@osk.mine.nu

I would like to hear from you about:

  * Bug reports. You don't need to write a precise bug report, just
    send me the error message (if there is one).

  * Patches. All patches are of course warmly welcome.

  * Suggestions for improvements, and ideas in general. Anything that
    you would like to see in this program.

  * Notes that you are or are not using this program (for whatever
    reasons). Feel free to send me long detailed emails, or just
    "I'm [not] using connmon. Bye." :).

In other words, just email me anything. Thanks. :)

Known bugs
==========

None at the moment.

Possible things to do
=====================

Please see the TODO document.

-
