wmnetload - A dockapp to monitor network interface usage.

Copyright (c) 2002 Peter Memishian <[email protected]>

Overview
========

The wmnetload dockapp is a simple network interface monitoring tool.  It was
written for use under Window Maker, but will likely work under other window
managers such as AfterStep, BlackBox and Enlightenment.

The dockapp has been designed with the following goals:

	1. Look-and-feel like Seiichi SATO's kick-ass wmcpuload (see
	   "Configuring the Look", below, for details).

	2. Provide useful information.  When monitoring an interface,
	   the information I frequently want to know is:

		(a) Is the interface functioning?

		(b) How loaded is the interface?

		(c) What are the recent traffic patterns on the interface,
		    for both incoming and outgoing traffic?

	3. Provide information clearly.  To that end, wmnetload:

		(a) Turns the entire digital display area red when an
		    interface is malfunctioning, so that you're quickly
		    alerted to the problem.

		(b) Uses a large font for the total network throughput.
		    It's important; it should be easy to read.  See
		    "Understanding wmnetload Statistics", below, for
		    help on interpreting throughput.

		(c) Separates incoming and outgoing traffic in the network
		    traffic graph in a intuitive, simple manner: incoming
		    traffic is considered to be "pulled down" from the
		    network and thus is shown descending from the top of the
		    graph, whereas outgoing traffic is considered to be
		    "pushed up" into the network and thus is shown growing
		    up from the bottom of the graph.

		    This approach may take some getting used to, but once
		    you do, I hope you'll agree that it's much easier to
		    read than the traditional multi-color approach, not to
		    mention easier to remember.

A number of other features you may find useful described below.

If you have additional suggestions for how to improve wmnetload and still
meet the aforementioned goals, don't hesitate to email.

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

This program uses standard GNU configure; please see the file `INSTALL' for
generic instructions.  

Unfortunately, wmnetload makes use of a couple of libraries that aren't
installed by default on some versions of Unix.  In particular, you'll need
both libXpm and libdockapp to compile wmnetload.  If you do not have these
libraries one your system, you can grab them from:

	libXpm		http://freshmeat.net/projects/libxpm
	libdockapp	ftp://truffula.com/pub/libdockapp-0.4.tgz

Please note that if you install these libraries in a location other than
/usr/lib or /usr/local/lib, you'll need pass the --with-libs-from and
--with-incs-from options to `configure'.  For instance, if you install these
libraries in /usr/shared/i686/lib and the headers in /usr/shared/include,
then you'll need to pass `--with-libs-from=/usr/shared/i686/lib
--with-incs-from=/usr/shared/include' to `configure'.

Configuring the Look
====================

Since one of the main goals of wmnetload is to match the look-and-feel of
wmcpuload, and since the look of wmcpuload was changed as of version 0.9, the
look of wmnetload has also been revised.  However, those who prefer the
"classic" wmnetload look (or who are still using older versions of wmcpuload)
can compile wmnetload to present the original look by passing
--with-classic-look to `configure'. 

Interface Cycling
=================

Although wmnetload can monitor only a single interface at a time, the
interface being monitored can be selected by using mouse buton 3 to cycle
through each of the available interfaces.  Note that with the classic look,
wmnetload does not display the name of the interface, which makes interface
cycling hard to use without getting confused.

Alarm Mode
==========

Like wmcpuload, wmnetload allows you to set an alarm value (in kbits/sec)
that causes the display backlight to be turned on whenever it is exceeded.
This is chiefly useful for alerting you to unusual or aberrant network
behavior.

NetBSD Limitations
==================

Please note that wmnetload must execute as a kmem reader on NetBSD in order
to retrieve interface statistics, which means that it must be run with a real
or effective gid of `kmem'.  If you attempt to run wmnetload with a gid other
than `kmem', it will fail with:

  wmnetload: cannot access raw kernel memory: /dev/mem: Permission denied
  wmnetload: fatal: cannot initialize interface statistics: Permission denied

Note that wmnetload immediately drops `kmem' privileges at startup and only
re-acquires them for the duration of the call to kvm_open(), so this should
not pose a security risk.  However, since there's an inherent danger
associated with setgid applications, wmnetload is never installed as setgid
by default; you must do this yourself by executing:

	# chgrp kmem wmnetload
	# chmod 2755 wmnetload

Solaris Limitations
===================

Solaris does not export the kstats wmnetload needs in order to track network
activity on the loopback interface.  As a result, attempts to monitor
the loopback interface will display "Err" on Solaris.

AfterStep Limitations
=====================

Several users have reported issues trying to get wmnetload to be correctly
swallowed when used under AfterStep.  Investigation has revealed that this
problem is due to bugs in libdockapp, not wmnetload.  Unfortunately,
libdockapp is currently unmaintained, so it's not really possible to roll
fixes into it (without taking over as maintainer, a task which I simply do
not have time for).  If you feel strongly about this issue, I encourage you
to work on the core issue, which is getting libdockapp back in active
development.

Understanding wmnetload Statistics
==================================

First, this probably seems obvious, but wmnetload only provides statistics
on packets *received* by the network card.  This means that if you're on a
traditional non-switched Ethernet, and your network interface is not in
promiscuous mode, wmnetload will be unaware of unicast traffic between other
nodes on your network. 

Second, depending on your operating system and whether it does accounting
before or after firewalling rules, wmnetload statistics may or may not
include traffic filtered by the firewall.

By default, all throughput is displayed in either kilobits, megabits, or
gigabits per second, as appropriate (the corresponding letter will light up
to indicate the scale).  If you'd prefer your throughput displayed in bytes,
then pass the `-b' option to wmnetload.

Contributions
=============

Please send all bug reports, bug fixes, and enhancements to <[email protected]>.
I'm particularly interested in contributions that would lead to additional
interface statistics "backends" for other POSIX-compliant systems.  Please
let me know if you wish to contribute one or provide access to a machine I
could use to write one myself.

Copyright
=========

All code is under GPL.

Fresh Bits
==========

The latest version of wmnetload is available from:

	http://freshmeat.net/projects/wmnetload