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-2000 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.
	* A timer button that can execute PPP or ISDN logon/logoff scripts.
	* Charts are autoscaling with configurable grid line resolution, or
	  can be set to a fixed scale mode.
	* 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.
	* Commands can be configured to run when monitor labels are clicked.
	* GKrellM is plugin capable so special interest monitors can be created.
	* A different theme can be created with the GIMP.


User Interface
==============
	* Top frame:
		Btn 1   - press and drag to move gkrellm window
		Btn 3   - popup menu for user config window
	* Side frames:
		Btn 2   - slide gkrellm window shut (Btn1 if -m2 option)
		Btn 3   - popup menu for user config window
	* All charts
		Btn 1   - toggle draw of extra info on the chart.
	* Inet charts
		Btn 2,3	- toggle between port hits per minute and hour.
	* File System meter panels:
		Btn 1	- On the label, Toggle visibility of secondary fs monitors.
	              On the mount button, run the mount/umount commands.
		Btn 2,3	- Toggle display of label and fs capacity scrolling display.
	* Mem and Swap meter panels:
		Btn 2,3	- Toggle display of label and memory or swap capacity
	              scrolling display.
	* Mailbox monitor message label:
		Btn 1	- Launch a mail reader program.
		Btn 2,3	- Toggle mail check mute mode.
	* Mailbox monitor envelope decal:
		Btn 1	- Force a mail check regardless of mute or timeout state.
	* APM monitor panel:
		Btn 2,3	- Toggle minutes left and percentage display.

	* F1  - keyboard shortcut to popup the user config window.

	If a command has been configured to be launched for a monitor, then
	left click on the monitor label to run the command.

Requirements
============
To use or compile GKrellM, you need:
	* GTK+ 1.2
	* Imlib
	* libgtop for systems other than Linux and FreeBSD.

Issues
======
	* For GTK versions prior to 1.2.7, if you change the system time GKrellM
	  will suspend because the Gtk library timeout compares to system time
	  for its timeout.  You can get GKrellM going again by clicking on the
	  top frame.

	* If you use GKrellM to NFS mount a file system and then loose the
	  physical network connection, GKrellM will be suspended by the kernel
	  when a stat() system call on the file system is made.


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, to get a list of options:

	gkrellm --help

Some of the options are:
	-t, --theme  theme_dir
	   GKrellM will load all theme image files it finds in theme_dir
	   and parse the gkrellmrc file if one exists.  This option overrides
	   the loading of the last theme you configured to be loaded in
	   the Themes configuration window.
	-g, --geometry +x+y
	   Or -g +x+y.  Makes GKrellM move to an x y postition on the screen
	   at startup.  Standard X window geometry position (not size) formats
	   are parsed, ie +x+y -x+y +x-y -x-y.
	-wm
	   Forces GKrellM to start up with window manager decorations.  The
	   default is no decorations because there are themed borders.
	-w, --withdrawn
		GKrellM starts up in withdrawn mode so it can go into the Blackbox
	    slit (and maybe WindowMaker dock)
	-f, --force-host-config
	   If GKrellM is run once with this option and then the configuration
	   or theme is changed, the config files that are written will have
	   a -hostname appended to them.  Subsequent runs will detect the
	   user_config-hostname and gkrellm_theme.cfg-hostname files and use
	   them instead of the normal configuration files.   This allows
	   remote GKrellMs independent config files in a shared home directory.
	   It might be desirable to run remote gkrellms using host specific
	   config files even if there is no shared home directory so that
	   the hostname will be appended to the X title.  This would allow
	   the window manager to distinguish between multiple GKrellMs.


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

A right button mouse click on the side or top frames of the GKrellM
window will pop up a user configuration window where you can configure
all the builtin and plugin monitors.


Using 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 or from a glibtop call.
One net interface may be linked to a timer button which can be used
to connect and disconnect from an ISP.

The timer button shows an off, standby, or on state by a distinctive
(color or shape) icon.
ppp: Standby state is while the modem phone line is locked while
    ppp is connecting, and the on state is the ppp link connected.
    The phone line lock is determined by the existence of the modem
    lock file /var/lock/LCK..modem.  If your pppd setup does not
    use /dev/modem, then you can configure an alternative with:
         ln  -s  /var/lock/LCK..ttySx   ~/.gkrellm/LCK..modem
    where ttySx is the tty device your modem uses.  The ppp on
    state is detected by the existence of /var/run/pppX.pid and
    the time stamp of this file is the base for the on line time.
ippp: glibtop is used to get the isdn on line or hangup status.
    The timer button standby state is not applicable to isdn
    interfaces that are always routed. The on state is isdn on line
    while the ippp interface is routed.  The on line timer is reset
    at isdn hangup to on line transitions.
For both ppp and ippp timer button links, the panel area of the
interface is always shown and the chart appears when the interface
is routed with the phone link connected or on line.
The timer button Start Command must run in the background and
this is automatically the default for most ppp logon scripts. One
exception, if you use wvdial it needs to be explicitly backgrounded:
      wvdail &
and the ppp logoff Stop Command in this case could be:
      skill -c wvdial
Otherwise do not append the "&" on more common ppp Start
Command entries.
If the timer button is not linked to a net interface, then it can
be used as a push on / push off timer

Net monitors can have a label so that the interface can be
associated with the identity of the other end of the connection.
This is useful if you have several net connections or run multiple
remote gkrellms.  It can be easier to keep track of who is connected
to who.

Mem and Swap Meters
-------------------
Here you are reading a ratio of total used to total available.
The amount of memory used indicated by the memory monitor is
actually a calculated "used" memory.  If you enter the
"free" command, you will see that most of your memory is almost
always used because the kernel uses large amounts for buffers
and cache.  Since the kernel can free a lot of this memory
as user process demand for memory goes up, a more realistic reading
of memory in use is obtained by subtracting the buffers and cached
memory from the kernel reported used.  This is shown in the free
command output in the "-/+ buffers/cache" line where a calculated
used amount has buffers and cached memory subtracted from the kernel
reported used memory, and a calculated free amount has the buffers
and cached memory added in.


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.  There are 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.  Mounting
commands can be enabled for mount points in one of two ways:

1) If a mount point is in your /etc/fstab and you have mount permission
then mount and umount commands can be enabled and executed for that
mount point simply by checking the \"Enable /etc/fstab mounting\" option.
Mount table entries in /etc/fstab must have the \"user\" option set
to grant this permission unless GKrellM is run as root.
For example, if you run GKrellM as a normal user and you want 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

2) If GKrellM is run as root or if you have sudo permission to run the
mount commands, then a custom mount command can be entered into the
\"mount command\" entry box.  A umount command must also be entered if you
choose this method.  Example mount and umount entries using sudo:
      sudo /bin/mount -t msdos /dev/fd0 /mnt/A
      sudo /bin/umount /mnt/A
Notes: the mount point specified in a custom mount command (/mnt/A in
this example) must be the same as entered in the \"Mount Point\" entry.
Also, you should have the NOPASSWD option set in /etc/sudoers for this.

File system monitors can be created as primary (always visible)
or secondary which can be hidden and then shown when they are of
interest.  For example, you might make primary file system monitors
for root, home, or user so they will be always visible, but make
secondary monitors for less frequently used mount points such as
floppy, zip, backup partitions, foreign file system types, etc.
Secondary FS monitors can also be configured to always be visible if they
are mounted by checking the \"Show if mounted\" option.   Using this
feature you can show the secondary group, mount a file system, and have
that FS monitor remain visible even when the secondary group is hidden.
A standard cdrom mount will show as 100% full but a monitor for it
could be created 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/check 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/check program checks
messages only" box in the Mail->Options configuration tab
and GKrellM will try to read the Fetchmail output so it can report new
mail on the remote server.  This same option should be checked if you
use MH mail messaging and you enter "flist -all" as your Mail fetch/check
program.  In this case flist will list the messages you have in your
local MH directories and GKrellM will try to read that output.

Here are some examples for remote mail fetching:

    Mail reading program:    xterm -e mutt
	Notify (sound) program:  cat /usr/local/sounds/newmail.wav > /dev/dsp
	Mail fetch/check 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:  esdplay /usr/local/sounds/newmail.wav
	Mail fetch/check 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 styles of output from fetchmail -c:
     1 message for billw at gkrellm.net (32743 octets).
     Fetchmail: 2 messages for billw at gkrellm.net (20300 octets)
     26 messages (25 seen) for billw at gkrellm.net
  As you might guess, fetchmail has had difficulty making its mind up
  on an output format.

If you use MH mail and have this setup:

    Mail fetch/check program: flist -all

  then GKrellM reads the output from flist and can recognize this format:
    /work/Mail  has  5 in sequence unseen (private); out of  46
    inbox+      has 10 in sequence unseen          ; out of 153
 

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.


Command launching
-----------------
Most monitors can be set up to launch a command when you click on
the monitor label.  When a command is configured for a monitor, its
label is converted into a button which may become visible when the mouse
enters the panel or meter area of the label.  If you are using a theme
which does not provide the button images necessary for this, then
the button will not become visible, but the button action of the label
will still occur.  You can use the command launching feature to
run commands related to monitoring functions, or you may use it to
have a convenient launch for any command.  Some launch examples for
some monitors could be:

   Calendar: gnomecal  or  ical
        CPU: xterm -e top  or  gps
       inet: gftp  or  xterm -e ftpwho
        net: netscape  or  xterm -e slrn -C-
and so on...

Tooltips can be enabled so that when the mouse is in the meter or panel
area where a command has been configured, the text of the command will
appear in a tooltip.

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/themes directory.  Themes for GKrellM
can be downloaded from www.muhri.net and once untarred can be
selected from the Themes configuration tab.

GKrellM also searches /usr/share/gkrellm/themes for any system wide
installed themes.   If there are duplicate entries in your user theme
directory and the system wide theme directory, both will appear under
the Themes configuration tab.

Read the Themes file if you want more information or are interested in
making a new theme for GKrellM.


Plugins
=======

GKrellM tries to load all plugins (shared object files ending in .so)
it finds in your plugin directory ~/.gkrellm/plugins.
If you download a plugin it is installed by simply moving it to
that directory.  Some plugins may be available only as source
files and they will have to be compiled before installation.  There
should be instructions for doing this with each plugin that comes
in source form.
