gkrellm - The GNU Krell Monitors
SYNOPSIS
gkrellm [ --help ] [ -t | --theme dir ] [ -g | --geometry
+x+y ] [ -wm ] [ -w | --withdrawn ] [ -c | --config suffix
] [ -nc ] [ -f | --force-host-config ] [ -demo ] [ -p |
--plugin plugin.so ]
DESCRIPTION
With a single process, gkrellm manages multiple stacked
monitors and supports applying themes to match the moni
tors appearance to your window manager, Gtk, or any other
theme.
FEATURES
· SMP CPU, Disk, Proc, and active net interface monitors
with LEDs.
· Internet monitor that displays current and charts his
torical 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/voltage displays 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
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.
· 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 count button
permit, also stop animations and reset
remote message counts.
Btn 2,3
Toggle mail check mute mode which inhibits
the sound notify program, 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,3
Toggle minutes left and percentage display.
· Keyboard shortcuts
F1 popup the user config window.
p switch to previous theme or theme alterna
tive.
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 mon
itor, then left click on the monitor label to run the com
mand.
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 moni
tors.
OPTIONS
--help Displays this manual page.
-t, --theme dir
gkrellm will load all theme image files it finds in
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 configu
ration window. Theme changes are not saved when
gkrellm is run with this option.
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 posi
tions are not recognized (ie +-x--y ).
-wm Forces gkrellm to start up with window manager dec
orations. 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 configura
tion files (unless the --config option is speci
fied). This is a convenience for allowing remote
gkrellm 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 xdm(1)
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.so
For plugin development, load the command line spec
ified plugin so you can avoid repeated install
steps in the development cycle.
BUILTIN MONITORS
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
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 General->Info in
the config 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 (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. If your pppd setup does not
use /dev/modem, then you can configure an alterna
tive 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 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:
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 con
nection. This is useful if you have several net connec
tions or run multiple remote gkrellm programs. 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 avail
able. 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 com
mand output in the "-/+ buffers/cache" line where a calcu
lated 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 con
fig.
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 multi
plexed 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 manu
facturers 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
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 dis
plays. 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 ser
vice on port 8080. So it makes sense to have a http moni
tor which combines data from both ports. A possible com
mon 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 configu
ration 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 moni
tored. Clicking the small button on the Inet panels will
pop up a window listing the currently connected port num
bers 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:
If a mount point is in your /etc/fstab and you have mount
permission then mount(8) and umount(8) commands can be
enabled and executed for that mount point simply by check
ing 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
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
/dev/fd0 /mnt/floppy ext2 user,defaults 0 0
If gkrellm is run as root or if you have sudo(1) permis
sion to run the mount(8) commands, then a custom mount
command can be entered into the "mount command" entry box.
A umount(8) 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. Sec
ondary 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 pro
gram (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. The format for entering mailboxes to moni
tor in the Mailboxes config is (in the same order as
listed above):
filename
directory
mailserver username password
mailserver mailbox username password
POP3 and IMAP checking can use non-standard port numbers
if the mailserver part of a config entry includes a port
number in the format mailserver:portnumber.
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 func
tions 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 and if
the data is available, a time remaining decal shows bat
tery 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, volt
ages, and fan speeds. I do not link against the lm_sensor
library because I do not want to have that extra depen
dency for users that do not have or care about sensors.
FreeBSD provides 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 cor
rectly installed and finds the sensor chip on your mother
board), 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.
To get this to work, you must manually link temperature
and fan files to your cpu/motherboard in the "Sensor" con
figuration page. The linking is made by entering "cpu" or
"mb" in the "Sensor Label" entry next to the "Sensor
Files" name. For example, if you want readings from sen
sor 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 (the Proc panel is
used for motherboard readings to save the overhead of an
extra panel - and it does make some sense if you think
the labels must be "cpu0", "cpu1", etc and you must be
displaying real cpu charts.
There is a separate "Voltages" config page where voltages
may be enabled. See the Info page in the config.
If you set up to monitor both a temperature and a fan on a
panel, they can be displayed optionally as a an alternat
ing single display or as separate displays. If separate,
the fan display will replace the panel label. The config
uration 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 infor
mation you would have to set up in /etc/sensors.conf if
gkrellm were linked against the lm_sensor library. Eg. if
you have a line for the in3 voltage in sensors.conf like:
compute in3 ((6.8/10)+1)*@ , @/((6.8/10)+1)
then you would enter 1.68 as the factor and 0 as the off
set for in3. Voltages currently cannot be made a function
of other voltages, but I will see about adding that if I
can get some input from someone with a sensor chip needing
it.
CPU/Motherboard Temperatures
You can calibrate temperature readings by setting a cor
rection factor and offset for each temperature file.
You have to decide via your motherboard manual or inspec
tion which temperature file corresponds to which CPU or
motherboard and it may help to read the lm_sensor documen
tation. The way I would make the link by inspection is to
dump the contents of each temperature file reported under
the 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 cor
responding to the motherboard temperature will have a tem
perature over and hysteresis less than those in the tem
perature 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
tion numbers in the sensors config to correct the raw tem
perature 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 mother
board 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 pos
sible and safe). I would guess the motherboard tempera
ture 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 off
sets of 0 and is reporting temperatures in centigrade:
1 · Boot up the machine cold and read a real tempera
ture 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 configura
tion 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
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 rec
ommending that anyone try sticking temperature probes
inside their machines.
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 way to maximize utiliza
tion 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 moni
tors could be:
calendar:
gnomecal, evolution, or ical
CPU: xterm -e top or gps or gtop
inet: gftp or xterm -e ftpwho
net: mozilla, netscape, or xterm -e slrn -C-
And so on... Tooltips can be set up for these commands.
THEMES
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
http://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
page at http://www.gkrellm.net and there you will find a
Theme making reference.
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/plug
ins are also searched for plugins to install. For compat
ibility with pre 1.0.6 versions, plugins from the directo
ries /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 Plug
ins page at http://www.gkrellm.net and there you will find
a Plugin programmers reference.
FILES
~/.gkrellm
User gkrellm directory were are located configura
tion files, user's plugins and user's themes.
~/.gkrellm/plugins
User plugin directory.
/usr/lib/gkrellm/plugins
System wide plugin directory.
/usr/local/lib/gkrellm/plugins
Local plugin directory.
~/.gkrellm/themes
User theme directory.
/usr/share/gkrellm/themes
System wide theme directory.
/usr/local/share/gkrellm/themes
Local theme directory.
AUTHORS
Bill Wilson <bill@gkrellm.net>. http://www.gkrellm.net/
fstab(5), sudo(1), mount(8), pppd(8), umount(8)
Man(1) output converted with
man2html