GKrellM - GNU (or Gtk) Krell Monitors (or Meters)
          (with an understood 'I' somewhere in appreciation for Imlib)
=======================================================================

Author:	Bill Wilson
Email:  bill@gkrellm.net
Homepage: http://gkrellm.net

Copyright (c) 1999 by Bill Wilson.  This program is free software
which I release under the GNU General Public License.
Read the COPYRIGHT file for more info.


Description
===========
With a single process, GKrellM manages multiple stacked monitors and supports
applying themes to match the monitors appearance to your window manager,
Gtk, or any other theme.


GKrellM Features
================
	* SMP CPU, Disk, Proc, and active net interface monitors with LEDs.
	* Internet monitor that displays current and charts historical port hits.
	* Memory and swap space usage meters and a system uptime monitor.
	* File system meters show capacity/free space and can mount/umount.
	* A mailbox monitor which can launch mail reader, remote mail fetch.
	* Clock/calendar and hostname display.
	* APM laptop battery monitor.
	* CPU/motherboard temperature display if lm_sensors modules installed.

	* Multiple monitors managed by a single process to reduce system load.
	* PPP on/off button that can execute your PPP scripts.
	* Charts are autoscaling with configurable grid line resolution.
	* Separate colors for "in" and "out" data.  The in color is used for
	  CPU user time, disk read, forks, and net receive data.  The out color
	  is used for CPU sys time, disk write, load, and net transmit data.
	* A different theme can be created with the GIMP.


User Interface
==============
	* Top frame:
		Btn 1,2 - press and drag to move gkrellm window
		Btn 3   - popup menu for user config window
	* Side frames:
		Btn 1,2 - slide gkrellm window shut
		Btn 3   - popup menu for user config window
	* Chart windows
		Btn 1   - toggle draw of extra detail info on the chart.
	* Inet charts
		Btn 2	- toggle between port hits per minute and hour.
	* File System meter panels:
		Btn 1	- Toggle display of label and fs capacity/free space.
		Btn 2	- Toggle visibility of secondary fs monitors.
	* Mailbox monitor panel:
		Btn 1	- Launch a mail reader program.
		Btn 2	- Toggle mail check mute mode.

Requirements
============
To use or compile GKrellM, you need:
	* GTK+ 1.2
	* Imlib


Notes
=====
	* GKrellM wants to report bytes of traffic for net interfaces.  However,
	  not all kernel 2.2.x nic drivers properly update their byte counters.
	  So, zero byte values are detected and packets then used.  This means
	  you can have mixed units for different network interfaces.  Keep this
	  in mind while setting resolutions for these cases. Kernel 2.0.x always
	  uses packets.


Installation
============

Debian packages
---------------
GKrellM is in the Debian distribution and you can upgrade to the
latest version with apt-get update, apt-get upgrade.  The .deb package
should appear near the same time or soon after new versions appear
on the website.

RedHat packages
---------------
If you download the .rpm package:

	rpm -i gkrellm-X.Y.Z.i386.rpm

From Source
-----------
	tar -xvcf gkrellm-X.Y.Z.tgz
	cd gkrellm-X.Y.Z
	make
	make install


Running GKrellM
===============

I run gkrellm at X startup by putting this in my .xsession (or .xclients or
whatever if you are not Debian).

	gkrellm &

GKrellM may also be run from the command line:

	gkrellm [options]
	options:
		--theme theme_dir
		-geometry +x+y
		-wm


Configuring GKrellM
===================

A right button mouse click on the side or top frames of the GKrellM
window will pop up a user preferences window where you can set grid
resolutions, ppp enable and on/off commands, etc.


Reading GKrellM - keeping an eye on your computers Id.
======================================================

Charts
------
You will notice if you try to change the grid scaling for any
chart that GKrellM likes to constrain you to values in a 1,2,5
sequence.  This is the best possible compromise between having
a scale that doubles at every step and that is also a clean decimal
value.  You can override this sequence, but always consider the
effect on reading rate values from the charts and krells.

See the online General->Info for basic chart reading and resolution
setting.

Net Monitors
------------
GKrellM is designed to display a chart for net interfaces which are
up, which means they are listed in the routing table, and data plotted
on the charts is read from /proc/net/dev.

If you have a ppp interface and link ppp0 to the timer button, then
GKrellM will set the on line timer based on the time stamp on the
modem lock file /var/lock/LCK..modem.  This works for systems which
have /dev/modem linked to the modem device /dev/ttySx (where x is 0-3)
and which have their pppd setup to access /dev/modem.  If you choose
not to set your system up with /dev/modem, the ppp timer can still be
made to work correctly by making the following link:
  ln -s /var/lock/LCK..ttySx ~/.gkrellm/LCK..modem
where ttySx is ttyS0 - ttyS3 (your modem device).  Gkrellm versions 0.7.3
and later will check ~/.gkrellm/LCK..modem if /var/lock/LCK..modem fails.


Mem and Swap Meters
-------------------
Here you are reading a ratio of total used to total available.
The kernel actually uses some of the available memory for buffers and
cache, but that memory is not included in the total used value
because the kernel can free it as process demand for memory goes up.


Internet Monitor
---------------
Displays TCP port connections and records historical port hits on a
minute or hourly chart.  Middle button click on an inet chart to
toggle between the minute and hourly displays.  There is a strip
below the minute or hour charts where marks are drawn for port
hits in second intervals.  Each inet krell also shows port hits
with a full scale range of 5 hits.  The left button toggle of extra
info displays current port connections.

For each internet monitor you can specify two labeled datasets with
one or two ports for each dataset.  I allow two ports because some
internet ports are related and you might want to group them - for
example, the standard http port is 80, but there is also a www web
caching service on port 8080.  So it makes sense to have a http
monitor which combines data from both ports.  A possible common
configuration would be to create one inet monitor that monitors
http hits plotted in the in_color and ftp hits in the out_color.
To do this, setup in the Internet configuration tab:

    http  80 8080    ftp  21

Or you could create separate monitors for http and ftp.  Other
monitors might be smtp on port 25 or nntp on port 119.

GKrellM samples TCP port activity once per second, so it is possible
for port hits lasting less than a second to be missed.


File System Monitor
-------------------
File system mount points can be selected to be monitored with a meter
that shows the ratio of blocks used to total blocks available.  If
you select a mount point that is in your /etc/fstab, then mount and
umount commands can be enabled and executed for that mount point by
clicking on the disk mount decal. You of course must have permission
for the mounting to succeed, so check that the user option is set in
/etc/fstab for the filesystems you will want to mount.  For example,
to be able to mount your floppy your /etc/fstab  could have either of:

   /dev/fd0  /mnt/floppy  ext2   user,noauto,rw,exec  0  0
or
   /dev/fd0  /mnt/floppy  ext2   user,defaults  0  0

If you run GKrellM as root, then the user option is not necessary.

If you left click on the file system label the label will toggle to
an alternating display of file system capacity and blocks available.

File system monitors can be created as primary (always visible), or
secondary which can be hidden and then shown when they are of interest
by middle mouse clicking on any file system monitor panel.  This
requires that at least one primary fs monitor must exist to click on
to make the secondary monitors visible.  For example, you might make
your main file system monitors for root, home, user always visible but
make monitors for your floppy, jazz, backup, mp3, etc mount points in
the secondary group.  A standard cdrom mount will show as 100% full
but you could still create a monitor for it with mounting enabled just to
have the mount/umount convenience.


Mailbox Monitor
---------------
Checks your mailboxes for unread mail. A mail reading program can be
executed with a left mouse click on the mail monitor panel, and a
mail notify (play a sound) program can be executed whenever the new
mail count increases.  Additionally, a mail fetch program can
be executed periodically to download or check for new mail from a
remote (pop3, ...) server.  If your local mail reader can do remote
downloads, you can use "fetchmail -c" to check and leave the mail on
the remote server.  For this case, check the "Fetch program will check
but not download messages" box in the Mail->Setup configuration tab
and GKrellM will try to read the Fetchmail output so it can report new
mail on the remote server.
Here are a couple of setup examples for remote mail fetching:

    Mail reading program:    xterm -e mutt
	Notify (sound) program:  cat /usr/local/sounds/newmail.wav > /dev/dsp
	Remote fetch program:    fetchmail

With this configuration, fetchmail will download remote mail and deliver
to local mailboxes which GKrellM can be set up to watch in the Mailboxes
tab.  The mail reader need only be able to process local mbox or maildir
style mailboxes.

    Mail reading program:    xfmail
	Notify (sound) program:  bplay /usr/local/sounds/newmail.wav
	Remote fetch program:    fetchmail -c

In this second example, fetchmail checks a remote server for mail
and reports any new messages found to GKrellM. The xfmail mail reader
can then do its own downloading when it is launched.  GKrellM can
currently recognize these two styles of output from fetchmail -c:
   1 message for billw at mail.wt.net (32743 octets).
or
   26 messages (25 seen) for billw at mail.wt.net

Large numbers of mailboxes can be expensive to read for mail counts when
mail is checked.  For such systems, you can set a message no count
mode which checks for new mail on the basis of file modification times and
size changes.  You will get an animation when new mail is available but
will not get a new mail count.

Mailboxes can be mbox or maildir types.


APM Laptop Battery Monitor
--------------------------
This meter will appear if /proc/apm indicates that a battery exists
and shows battery percentage life remaining.  A decal indicates
if AC line is connected or if the battery is in use and a time
remaining decal shows battery time left in minutes or seconds (if
your bios reports the battery time left).


CPU/Motherboard Temperatures
----------------------------
If you have lm_sensor kernel modules installed which report temperatures
in /proc/sys/dev/sensors as a chip/tempX file, then GKrellM can display
your CPU and motherboard temperatures.  I do not monitor fan speeds or
voltages.   I also do not link against the lm_sensor library because
I do not want to have that extra dependency for users that do not have
or care about temperatures.

This means that you must manually link temperature files to your
cpu/motherboard in the "Sensor" configuration tab (this tab will exist
only if temperature files are found).   You can also calibrate
temperature readings by setting a correction factor and offset for
each tempX file.   This is the same configuration information you
would have to set up in /etc/sensors.cfg if GKrellM were linked
against the lm_sensor library.

You have to decide via your motherboard manual or inspection which
temperature file corresponds to which CPU or motherboard and it may
help to read the lm_sensor documentation.  The way I would make the
link by inspection is to dump the contents of each temperature file
reported under GKrellM's Sensor configuration tab.  Each temperature
file should have a single line with three numbers which report
temperature over, temperature hysteresis, and measured temperature.
It is likely that the temperature file corresponding to the motherboard
temperature will have a temperature over and hysteresis less than
those in the temperature files for CPU's.   You could also try
modulating CPU temperatures to see which sensor reading tracks the
modulation.  For example, with your computer cover off and after
warming up to equilibrium, try augmenting cooling on a CPU by blowing
additional air on the heatsink.  Or maybe try some circuit cooler.

The raw temperature reading may need to be corrected to give accurate
CPU temperatures because the sensors may not be in physical  contact
with the CPU's.  To do this calibration, take two real CPU temperature
readings corresponding to two sensor reported readings.   To get
the real readings, you can trust that your motherboard manufacturer
has done this calibration and is reporting accurate temperatures in
the bios, or you can put a temperature probe directly on your CPU
case (if possible and safe).  I would guess the motherboard temperature
will not need calibration, but you could check with a temperature probe.

Here is a sample CPU calibration procedure.  Make sure GKrellM is
configured with default factors of 1.0 and offsets of 0 and is
reporting temperatures in centigrade:

    1) Boot up the machine cold and read a real temperature T1
       from the bios or a temperature probe.  If reading from the
       bios, boot as quickly as possible into Linux and record
       a sensor temperature S1 as reported by GKrellM.
    2) Allow the CPU to run and heat up to equilibrium.
       Record sensor temperature S2 and real temperature T2.
       If reading real temps from the bios, you have to shutdown
       and reboot into the bios quickly before temperatures drift.
    3) Now you can calculate the correction factor and offset you need
       to enter into the Sensor configuration tab:
           From:
                   s - S1     t - T1
                   ------  =  ------
                  S2 - S1    T2 - T1

                                 T2 - T1     S2*T1 - S1*T2
                        t  = s * -------  +  -------------
                                 S2 - S1         S2 - S1

            So:
                          T2 - T1                S2*T1 - S1*T2
                factor =  -------      offset =  -------------
                          S2 - S1                   S2 - S1


Note: ideally, the temperature measurements should each be made at
equilibrium and in the above example, the T1 S1 reading will probably
not be an equilibrium reading.  Maybe a pair of readings with the
cpu idling as much as possible and then running something like cpuburn
could be made.  See Freshmeat for cpuburn, and read the cautions.


Installing a Theme for GKrellM
==============================

A theme is a directory containing image files and a gkrellmrc
configuration file.  The directory should be installed as a
subdirectory under your ~/.gkrellm directory.  Themes for GKrellM
can be downloaded from www.muhri.net and once untarred can be
selected from the Themes configuration tab.

Read the Themes file if you are interested in making a new skin
for GKrellM.
