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

Author:	Bill Wilson
Email:  billw@wt.net
Homepage: http://web.wt.net/~billw/gkrellm/gkrellm.html

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 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.
	* 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 fs monitors placed in drawer.


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.

In general, it is up to you to remember what scaling you set for the
various charts.  There is a toggle that displays info that aids in chart
reading.  The default theme includes a 5 division scale background for
the krells to move across and the krell full scale range is set to be
5 times the configurable grid line resolution.  I use a 5 factor because
10 divisions were too hard to read given the small size of the GKrellM
charts.

If you keep in mind that the krells are updated 10 times/sec and that
the charts are bumped once per second (not inet charts), you can read
transfer rates or actual numbers of events from GKrellM (if your eye
is quick enough). I can illustrate this with a couple of examples.

	1) If the PPP chart grid resolution is set at 2000 bytes/sec, then
	the krell full scale value is 10000 bytes/sec rate.  Now, say you
	get a burst of data read and the krell jumps to 40% of full scale
	and then drops back to 0.  What happened is that for the krell
	update period data was read at a rate of 4000 bytes/sec and since
	the update period is 0.1 second, you actually read 400 bytes during
	that period.  When the chart tick appears it will be a vertical bar
	slightly less than 1/4 of the way up to the first grid line which
	tells you that for the full second interval data was read at
	400 bytes/sec rate.  Good luck on reading that precisely.

	2) The process krell full scale value rate is fixed at 100 forks/sec
	which makes the chart show 20 forks per grid.  Again, since the
	krell update period is 0.1 seconds, you can multiply 100 by .1
	to get 10 fork events (not a rate) full scale per update interval.
	So try this.  Enter a command, say 'ls' while watching the proc
	krell.  It should tick up to 1/10 of full scale.  Now enter
	'ls | wc', and then 'ls | wc | wc'.  You can directly read on the
	proc krell that 1, then 2, and then 3 processes were created - if
	they all occured in just one update interval.

You can go through the same exercise with the CPU and Disk monitor.

The CPU monitor is measuring cpu usage in 1/100 second ticks, so the
grid resolution is 20/100 rate and the kell full scale is 100% cpu usage.

The Disk monitor is measuring the number of disk BLOCK_SIZE I/O
operations.  These are 1024 byte reads or writes, but because of disk
I/O buffering it is difficult to correlate chart readings with command
line activity.  Disk grid resolution is configurable.

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.
If you left click on the file system label the label will toggle to
an alternating display of file system capacity and blocks available.

Secondary file system monitors can be placed in a "drawer" which
allows their visibility to be toggled by middle mouse clicking on
any file system monitor panel.  This requires that at least one
non drawer fs monitor must exist for you to click on to make the
drawered monitors visible.  For example, you might make your main
file system monitors for root, home, user always visible but put
a monitor for your floppy, jazz, backup, mp3, etc mount points in
the drawer.  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.


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 life left in minutes or seconds.


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


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.
