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 mbox/maildir/MH/POP3/IMAP mail monitor which can launch a mail reader
	  or remote mail fetch program.
	* Clock/calendar and hostname display.
	* APM laptop battery monitor.
	* CPU/motherboard temperature/fan/voltages 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.
	* Many themes are available.


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.
		Btn 3   - Brings up a chart configuration window.
	* Inet charts
		Btn 2	- toggle between port hits per minute and hour.
	* Most panels
		Btn 3   - Opens the configuration window directly to a monitor's
                  configuration page.
	* 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	- Toggle display of label and fs capacity scrolling display.
	* Mem and Swap meter panels:
		Btn 2	- Toggle display of label and memory or swap capacity
	              scrolling display.
	* Mailbox monitor message count button:
		Btn 1	- Launch a mail reader program.  If options permit, also
	              stop animations and reset remote message counts.
		Btn 2	- Toggle mail check mute mode which inhibits the sound
	              notify progra, and optionally inhibits all mail checking.
	* Mailbox monitor envelope decal:
		Btn 1	- Force a mail check regardless of mute or timeout state.
	* APM monitor panel:
		Btn 2	- Toggle minutes left and percentage display.

  Keyboard shortcuts:
	* F1  = popup the user config window.
	* p   = switch to previous theme or theme alternative.
	* n   = switch to next theme or theme alternative.
	* u   = switch to previous theme, skipping any theme alternatives.
	* d   = switch to next theme, skipping any theme alternatives.

    If a command has been configured to be launched for a monitor, then
    a button will appear when the mouse enters the panel of that monitor.
    Clicking the button will launch the command.


Requirements
============
To use or compile GKrellM, you need:
	* GTK+ 1.2
	* gdk-imlib1 (often distributed as part of the Imlib package).
To compile, you additionally need the development versions of these libs.


Installation
============
See the INSTALL file.  BSD systems will probably need to use GNU gmake
instead of BSD make.


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

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

	gkrellm &

Or if you run Gnome, you can install the GKrellM-Gnome plugin and get
session management.

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.  Theme changes are not saved
	   when GKrellM is run with this option.
	-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.  Except, negative geometry
	   positions are not recognized (ie +-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)
	-c, --config  suffix
	   Use alternate config files generated by appending "suffix" to config
	   file names.  This overrides any previous host config which may have
	   been setup with the below option.
	-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 (unless the --config
	   option is specified).   This is a convenience for allowing
	   remote GKrellMs independent config files in a shared home directory,
	   and for the hostname to show up in the X title for window management.
	-nc
	   No config mode.  The config menu is blocked so no config changes
	   can be made.  Useful in certain environments, or maybe for running
	   on a gdm login screen or during a screensaver mode?
	-demo
	   Force enabling of many monitors so themers can see everything. All
	   config saving is inhibited.
	-p, --plugin  plugin_under_test.so
	   For plugin development, load the command line specified plugin so you
	   can avoid repeated install steps in the development cycle.


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.  Chart appearance may be configured
by right clicking on a chart, and right clicking on many panels will open
the configuration window directly to the corresponding monitor's
configuration page.


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

Charts
======
The default for most charts is to automatically adjust the number of
grid lines drawn and the resolution per grid so drawn data will be
nicely visible.  You may change this to fixed grids of 1-5 and/or
fixed grid resolutions in the chart configuration windows.  However,
some combination of the auto scaling modes may give best results.

Auto number of grids:
    This means to scale the chart to draw as many grids as is necessary
    to show all the data on the chart without clipping.

Auto grid resolution has two meanings:
    1) If using a fixed number of grids, it means to set the
    resolution per grid to the smallest value in a base to peak range
    that draws data without clipping.  The peak is the maximum data
    value encountered and the base is 1/5 the peak.
    2) If using auto number of grids, it means to set the resolution
    per grid to a value such that drawing the peak value encountered
    requires at least 5 grids to be drawn.


CPU Monitor
-----------
Data is plotted as a percentage.  In auto number of grids
mode, resolution is a fixed 20% per grid.  In fixed number of grids
mode, grid resolution is 100% divided by the number of grids.


Proc Monitor
------------
The krell shows process forks with a full scale value
of 10 forks.  The chart has a resolution of 10 forks/sec per grid
in auto number of grids mode and 50 forks/second maximum on the
chart in fixed number of grids mode.
The process load resolution per grid is best left at 1.0 for auto
number of grids, but can be set as high as 5 if you configure the
chart to have only 1 or 2 fixed grids.


Net Monitor
------------
GKrellM is designed to display a chart for net interfaces which are
up, which means they are listed in the routing table (however, it is
possible in some cases to monitor unrouted interfaces).
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 which assumes pppd is using
    /dev/modem.  However, 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 does use.  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: 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 transitions from isdn hangup state to on line state.
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 many ppp logon scripts. A couple
of exceptions are wvdial and kppp which need to be explicitly
backgrounded:

      wvdail &
or
      kppp -c Foo &

and the timer button Stop Command in these cases could be:

      skill -c wvdial
or
      kppp -k

Otherwise do not append the "&" on ppp Start Command entries that
background themselves.

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 Monitor
--------------------
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.

While the memory meter always shows the calculated "used" memory,
the raw memory values total, shared, buffered, and cached may be
optionally displayed in the memory panel by entering an appropriate
format display string in the config.

Units:  All memory values have units of binary megabytes (MiB).
Memory sizes have historically been reported in these units because
memory arrays on silicon have always increased in size by multiples
of 2.  Add an address line to a memory chip and you double or quadruple
(a multiplexed address) the memory size.  A binary megabyte is
2^20 or 1048576.  Contrast this with units for other stats such
as disk capacities or net transfer rates where the proper units
are decimal megabytes or kilobytes.  Disk drive capacities do not
increase by powers of 2 and manufacturers do not use binary
units when reporting their sizes.  However, some of you may prefer
to see a binary disk drive capacity reported, so it is available
as an option - but I don't recommended it.


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 one color and ftp hits in another.
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.

If you check the "Port0 - Port1 is a range" button, then all of the
ports between the two entries will be monitored.  Clicking the
small button on the Inet panels will pop up a window listing the
currently connected port numbers and the host that is connected
to it.

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" or "owner" 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.

When the "Ejectable" option is selected for a file system, an eject
button will appear when the mouse enters the file system panel.  If you
are not using /etc/fstab mounting, a device file to eject will also need
to be entered.  Systems may have varying levels of support for this feature
ranging from none or basic using an ioctl() to full support using an eject
command to eject all its supported devices.   Linux and NetBSD use the
"eject" command while FreeBSD uses the "cdcontrol" command, so be sure
these commands are installed.
Most eject commands will also support closing a CDROM tray.  If they do,
you will be able to access this function by right clicking the eject button.

See what I have to say about units under the Memory and Swap Monitors.


Mail Monitor
------------
Checks your mailboxes for unread mail. A mail reading program (MUA) can be
executed with a left mouse click on the mail monitor panel button, and
a mail notify (play a sound) program can be executed whenever the new
mail count increases.  The mail panel envelope decal may also be
clicked to force an immediate mail check at any time.

GKrellM is capable of checking mail from local mailbox types mbox, MH, and
maildir, and from remote mailbox types POP3 and IMAP.

POP3 and IMAP checking can use non-standard port numbers and password
authentication protocols APOP (for POP3 only) and CRAM-MD5 may be selected
as long as your mail server supports them.

Before internal POP3 and IMAP checking was added, an external mail
fetch/check program could be set up to be executed periodically to
download or check remote POP3 or IMAP mail.  This method is still
available and must be used if you want GKrellM to be able to
download remote mail to local mailboxes because the builtin checking
functions cannot download.


APM Laptop Battery Monitor
--------------------------
This meter will be available if a battery exists and will show battery
percentage life remaining.  A decal indicates if AC line is connected
or if the battery is in use.  If the data is available, a time remaining
decal shows battery time left in minutes or seconds.


CPU/Motherboard Sensors - Temperature, Voltages, and Fan RPM
------------------------------------------------------------
For Linux, if you have lm_sensor kernel modules installed which reports
sensor readings in /proc/sys/dev/sensors as a chip/tempX, chip/inX,
or chip/fanX file, then GKrellM can display your CPU and motherboard
temperatures, voltages, and fan speeds.  FreeBSD and NetBSD provide
sensor reporting for some sensor chips.

If the /proc/sys/dev/sensors directory exists and has chip subdirectories
(which it will if lm_sensors has been correctly installed and finds
the sensor chip on your motherboard), then GKrellM automatically detects
this and there will be a "Sensors" configuration option in the config
window.  Likewise there will be the Sensors config if FreeBSD detects
a sensor chip. NetBSD uses the envsys(4) interface and sensors reading is
automatically enabled if you have either a lm(4) or viaenv(4) chip
configured in your kernel.

Temperature and fan sensor data may be displayed on a panel below the
Proc panel, or may be displayed on the CPU and Proc panels.  Voltage data
is always displayed on a panel below the Proc panel.

On the Setup page enter a Label next to a temperature or fan Sensor File
to make GKrellM display the data from that sensor.  If the label is one of
the reserved name labels, then the data display will appear on a CPU or
Proc panel.  The lower case reserved name labels are "cpu" and "mb" where
the "mb" label is for displaying on the Proc panel.  If you have a SMP
machine, then the labels must be "cpu0", "cpu1", etc and you must be
displaying real cpu charts.

For example, if you want readings from sensor file temp1 and/or sensor file
fan1 to show up on the CPU panel, then enter "cpu" as the label for both
temp1 and fan1.  If you want the readings to show up on the Proc panel,
then enter "mb" as the labels.

Displaying temperature and fan sensors on the CPU and Proc panels can save
some vertical space in GKrellM.  However, if labels other than the reserved
labels are entered then the temperature or fan data will be displayed on
a separate panel.  If you wish to have a reserved label appear on the
separate panel, prepend an underscore.  For example, use "_cpu".

There is a separate Voltages config page where voltages may be enabled.
Voltages always have a label assigned.  The default voltage labels may
be overridden on the Setup page.

If you set up to monitor both a temperature and a fan on the CPU or PROC
panel, they can be displayed optionally as an alternating single display
or as separate displays.  If separate, the fan display will replace
the panel label.  The configuration for this is under the CPU and Proc
config pages.

In the Setup page for the Sensors config you also enter any correction
factors and offsets for each of the sensors you are monitoring.  This
is the same configuration information you would have to set up in
/etc/sensors.conf if GKrellM were linked against the lm_sensor library.
See below for an explanation of converting lm_sensor compute lines to
GKrellM correction factors and offsets.

Note for NetBSD users: 
The current implementation of the sensor reading under NetBSD opens
/dev/sysmon and never closes it. Since that device does not support
concurrent accesses, you won't be able to run other apps such as
envstat(8) while GKrellM is running.  This might change if this happens
to be an issue.
The reasons for this choice are a) efficiency (though it might be possible
to open/close /dev/sysmon each time a reading is needed without major
performance issue) and b) as of october 2001, there's a bug in the
envsys(4) driver which sometimes causes deadlocks when processes try to
access simultaneoulsy /dev/sysmon  (see NetBSD PR#14368). A (quick and
dirty) workaround for this is to monopolize the driver :)


CPU/Motherboard Temperatures
----------------------------
You can calibrate temperature readings by setting a correction factor
and offset for each temperature file.  

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 (for Linux) 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.

Some motherboards may not provide accurate temperature readings because
of various factors, such as variations in sensor contact with the CPU.
For these cases, if you care about precise temperature readings, you can
enter calibration numbers in the sensors config to correct the raw
temperature readings.

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 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.
Anyway, these are just some ideas.  I'm not actually recommending
that anyone try sticking temperature probes inside their machines.


Voltage Sensor Corrections
--------------------------
Motherboard voltage measurements are made by a variety of sensor
chips which are capable of measuring a small positive voltage.
GKrellM can display these voltage values and can apply a correction
factor, offset, and for the negative voltages of some chips (lm80), a
level shifting reference voltage to the displayed voltage.  There are
four cases to consider:

  1) Low valued positive voltages may be directly connected to the input
  pins of the sensor chip and therefore need no correction.  For these,
  the correction factor should be 1.0 and the offset should be 0.

  2) Higher valued positive voltages will be connected to the input pins
  of the sensor chip through a 2 resistor attenuation circuit.  For these,
  the correction factor will be a ratio of the resistor values and the
  offset will be 0.

  3) Negative voltages will be connected to the input pins of the sensor
  through a 2 resistor attenuation circuit with one of the resistors
  connected to a positive voltage to effect a voltage level shift.
  For these (lm80), the correction factor and offset will be ratios of the
  resistor values, and a reference voltage must be used.

  4) Some sensor chips (w83782, lm78) are designed to handle negative inputs
  without requiring an input resistor connected to a voltage reference.
  For these, there will be a correction factor and a possible offset.

For cases 2 and 3, the sensor chip input network looks like:

    Vs o----/\/\/---o-------------o Vin
             R1     |
                    o--/\/\--o Vref
                        R2
where,
    Vs   is the motherboard voltage under measurment
    Vin  is the voltage at the input pin of the sensor chip and therefore is
         the voltage reading that will need correction.
    Vref is a level shifting voltage reference.  For case 2, Vref is ground
         or zero.  For case 3, Vref will be one of the positive motherboard
         voltages.

The problem then is to compute correction factors and offsets as a function
of R1 and R2 so that GKrellM can display a computed motherboard voltage Vs
as a function of a measured voltage Vin.

Since sensor chip input pins are high impedance, current into the pins may
be assumed to be zero.  In that case, the current through R1 equals current
through R2, and we have:

    (Vs - Vin)/R1 = (Vin - Vref)/R2

Solving for Vs as a function of Vin:

    Vs = Vin * (1 + R1/R2)  -  (R1/R2) * Vref

So, the correction factor is:  1 + R1/R2
    the correction offset is:  - (R1/R2)
    Vref is specified in the config separately from the offset (for
    chips that need it).

Fortunately there seems to be a standard set of resistor values used
for the various sensor chips which are documented in the lm_sensor
documentation.  The GKrellM sensor corrections are similar to the compute
lines you find with lm_sensors, with the difference that lm_sensors has an
expression evaluator which does not require that compute lines be simplified
to the single factor and offset required by GKrellM.  But you can easily
calculate the factor and offset.  For example, this lm_sensor compute line
for a case 2 voltage:

    compute in3 ((6.8/10)+1)*@ ,  @/((6.8/10)+1)

yields a correction factor of ((6.8/10)+1) = 1.68
and an offset of zero.

Note that the second compute line expression is not relevant in GKrellM
because there is never any need to invert the voltage reading calculation.
Also, the compute line '@' symbol represents the Vin voltage.

A more complicated compute line for a case 3 voltage:

    compute in5 (160/35.7)*(@ - in0) + @, ...

can be rewritten:

    compute in5 (1 + 160/35.7)*@ - (160/35.7)*in0, ...

so the correction factor is  (1 + 160/35.7) = 5.48
and the correction offset is -(160/35.7) = -4.48
and the voltage reference Vref is in0

Here is a table of correction factors and offsets based on some typical
compute line entries from /etc/sensors.conf:

       Compute line                     Factor  Offset  Vref
       -----------------------------------------------------
lm80   in0 (24/14.7 + 1) * @            2.633     0       -
       in2 (22.1/30 + 1) * @            1.737     0       -
       in3 (2.8/1.9) * @                1.474     0       -
       in4 (160/30.1 + 1) * @           6.316     0       -
       in5 (160/35.7)*(@ - in0) + @     5.482    -4.482  in0
       in6 (36/16.2)*(@ - in0) + @      3.222    -2.222  in0

LM78   in3 ((6.8/10)+1)*@               1.68      0       -
       in4 ((28/10)+1)*@                3.8       0       -
       in5 -(210/60.4)*@               -3.477     0       -
       in6 -(90.9/60.4)*@              -1.505     0       -

w83782 in5 (5.14 * @) - 14.91           5.14    -14.91    -
       in6 (3.14 * @) -  7.71           3.14     -7.71    -



Command launching
=================
Many 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 becomes visible when the mouse
enters the panel or meter area of the label.

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.  Since GKrellM is usually made sticky, you can have
easy access to several frequently used commands from any desktop.
This is intended to be a convenience and a way to maximize utilization
of screen real estate and not a replacement for more full featured
command launching from desktops such as Gnome or KDE or others.
Some launch ideas for some monitors could be:

   calendar: gnomecal, evolution, or ical
        CPU: xterm -e top  or  gps  or  gtop
       inet: gftp  or  xterm -e ftpwho
        net: mozilla, galeon, skipstone,  or  xterm -e slrn -C-
and so on...

Tooltips can be set up for these commands.


Alerts
======
The sensor and APM monitors can have alerts configured to give
warnings and alarms for data readings which range outside of
configurable limits.  A warning or alarm consists of an attention
grabbing decal appearing and an optional command being executed.

Additionally, if you have the gvoice plugin and the ViaVoice
libraries from IBM installed, a voice alert may be configured
to get your attention.


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 or under
/usr/local/share/gkrellm/themes.  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
themes installed as part of a distribution.  Finally, a theme you
simply want to check out can be untarred anywhere and used by
running:  gkrellm -t path_to_theme

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.  The directories
/usr/local/lib/gkrellm/plugins and /usr/lib/gkrellm/plugins are
also searched for plugins to install.
For compatibility with pre 1.0.6 versions, plugins from the directories
/usr/local/share/gkrellm/plugins and /usr/share/gkrellm/plugins are
still installed, but this is not compatible with the FHS.

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.

If you are interested in writing a plugin, go to the Plugins page
at http://gkrellm.net and there you will find a Plugin programmers
reference and Plugins-changelog.
