1246 lines
37 KiB
Groff
1246 lines
37 KiB
Groff
.TH gkrellm 1 "Sep 15, 2010" "GNU/Linux" "User's Manual"
|
|
|
|
.SH "NAME"
|
|
gkrellm \- The GNU Krell Monitors
|
|
|
|
.SH "SYNOPSIS"
|
|
.B gkrellm
|
|
[
|
|
.B \-\-help
|
|
]
|
|
[
|
|
.B \-t
|
|
|
|
|
.B \-\-theme
|
|
dir
|
|
]
|
|
[
|
|
.B \-g
|
|
|
|
|
.B \-\-geometry
|
|
+x+y
|
|
]
|
|
[
|
|
.B \-wm
|
|
]
|
|
[
|
|
.B \-w
|
|
|
|
|
.B \-\-withdrawn
|
|
]
|
|
[
|
|
.B \-c
|
|
|
|
|
.B \-\-config
|
|
suffix
|
|
]
|
|
[
|
|
.B \-nc
|
|
]
|
|
[
|
|
.B \-f
|
|
|
|
|
.B \-\-force\-host\-config
|
|
]
|
|
[
|
|
.B \-demo
|
|
]
|
|
[
|
|
.B \-p
|
|
|
|
|
.B \-\-plugin
|
|
plugin.so
|
|
]
|
|
[
|
|
.B \-s
|
|
|
|
|
.B \-\-server
|
|
hostname
|
|
]
|
|
[
|
|
.B \-P
|
|
|
|
|
.B \-\-port
|
|
server_port
|
|
]
|
|
[
|
|
.B \-l
|
|
|
|
|
.B \-\-logfile
|
|
path
|
|
]
|
|
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
With a single process,
|
|
.B gkrellm
|
|
manages multiple stacked monitors and supports applying
|
|
themes to match the monitors appearance to your window manager, Gtk, or any
|
|
other theme.
|
|
|
|
.SS "FEATURES"
|
|
.IP \(bu 4
|
|
SMP CPU, Disk, Proc, and active net interface monitors with LEDs.
|
|
.IP \(bu 4
|
|
Internet monitor that displays current and charts historical port hits.
|
|
.IP \(bu 4
|
|
Memory and swap space usage meters and a system uptime monitor.
|
|
.IP \(bu 4
|
|
File system meters show capacity/free space and can mount/umount.
|
|
.IP \(bu 4
|
|
A mbox/maildir/MH/POP3/IMAP mail monitor which can launch a mail reader or
|
|
remote mail fetch program.
|
|
.IP \(bu 4
|
|
Clock/calendar and hostname display.
|
|
.IP \(bu 4
|
|
Laptop Battery monitor.
|
|
.IP \(bu 4
|
|
CPU/motherboard temperature/fan/voltages display with warnings and
|
|
alarms. Linux requires a sensor configured sysfs, lm_sensors modules or
|
|
a running mbmon daemon. FreeBSD can also read the mbmon daemon.
|
|
Windows requires MBM.
|
|
.IP \(bu 4
|
|
Disk temperatures if there's a running hddtemp daemon.
|
|
.IP \(bu 4
|
|
Multiple monitors managed by a single process to reduce system load.
|
|
.IP \(bu 4
|
|
A timer button that can execute PPP or ISDN logon/logoff scripts.
|
|
.IP \(bu 4
|
|
Charts are autoscaling with configurable grid line resolution, or
|
|
.IP \(bu 4
|
|
can be set to a fixed scale mode.
|
|
.IP \(bu 4
|
|
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.
|
|
.IP \(bu 4
|
|
Commands can be configured to run when monitor labels are clicked.
|
|
.IP \(bu 4
|
|
Data can be collected from a
|
|
.B gkrellmd
|
|
server running on a remote machine.
|
|
.IP \(bu 4
|
|
.B gkrellm
|
|
is plugin capable so special interest monitors can be created.
|
|
.IP \(bu 4
|
|
Many themes are available.
|
|
|
|
.SS "USER INTERFACE"
|
|
.B
|
|
.IP "\(bu Top frame"
|
|
.RS
|
|
.TP
|
|
.I "Btn 1"
|
|
Press and drag to move
|
|
.B gkrellm
|
|
window.
|
|
.TP
|
|
.I "Btn 3"
|
|
Popup main menu.
|
|
.RE
|
|
.B
|
|
.IP "\(bu Side frames"
|
|
.RS
|
|
.TP
|
|
.I "Btn 2"
|
|
Slide
|
|
.B gkrellm
|
|
window shut (Btn1 if -m2 option).
|
|
.TP
|
|
.I "Btn 3"
|
|
Popup main menu.
|
|
.RE
|
|
.B
|
|
.IP "\(bu All charts"
|
|
.RS
|
|
.TP
|
|
.I "Btn 1"
|
|
Toggle draw of extra info on the chart.
|
|
.TP
|
|
.I "Btn 3"
|
|
Brings up a chart configuration window.
|
|
.RE
|
|
.B
|
|
.B
|
|
.IP "\(bu Inet charts"
|
|
.RS
|
|
.TP
|
|
.I "Btn 2"
|
|
Toggle between port hits per minute and hour.
|
|
.RE
|
|
.B
|
|
.IP "\(bu Most panels"
|
|
.RS
|
|
.TP
|
|
.I "Btn 3"
|
|
Opens the configuration window directly to a monitor's configuration page.
|
|
.RE
|
|
.B
|
|
.IP "\(bu File System meter panels"
|
|
.RS
|
|
.TP
|
|
.I "Btn 1,2"
|
|
Toggle display of label and fs capacity scrolling display.
|
|
The mount button runs mount/umount commands.
|
|
If ejectable, left click the eject button to open tray, right click to close.
|
|
.RE
|
|
.B
|
|
.IP "\(bu Mem and Swap meter panels"
|
|
.RS
|
|
.TP
|
|
.I "Btn 1,2"
|
|
Toggle display of label and memory or swap capacity scrolling display.
|
|
.RE
|
|
.B
|
|
.IP "\(bu Mailbox monitor message count button"
|
|
.RS
|
|
.TP
|
|
.I "Btn 1"
|
|
Launch a mail reader program. If options permit, also
|
|
stop animations and reset remote message counts.
|
|
.TP
|
|
.I "Btn 2"
|
|
Toggle mail check mute mode which inhibits the sound
|
|
notify program, and optionally inhibits all mail checking.
|
|
.RE
|
|
.B
|
|
.IP "\(bu Mailbox monitor envelope decal"
|
|
.RS
|
|
.TP
|
|
.I "Btn 1"
|
|
Force a mail check regardless of mute or timeout state.
|
|
.RE
|
|
.B
|
|
.B
|
|
.IP "\(bu Battery monitor panel"
|
|
.RS
|
|
.TP
|
|
.I "Btn 1"
|
|
On the charging state decal toggles battery minutes left,
|
|
percent level, and charge rate display.
|
|
.TP
|
|
.I "Btn 2"
|
|
Anywhere on the panel also toggles the display.
|
|
.RE
|
|
.B
|
|
.IP "\(bu Keyboard shortcuts"
|
|
.RS
|
|
.TP
|
|
.I "F1"
|
|
popup the user config window.
|
|
.TP
|
|
.I "F2"
|
|
popup the main menu.
|
|
.TP
|
|
.I "Page_Up"
|
|
previous theme or theme alternative.
|
|
.TP
|
|
.I "Page_Down"
|
|
next theme or theme alternative.
|
|
.TP
|
|
.I "<Ctl>Page_Up"
|
|
previous theme, skipping any theme alternatives.
|
|
.TP
|
|
.I "<Ctl>Page_Down"
|
|
next theme, skipping any theme alternatives.
|
|
.RE
|
|
.PP
|
|
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.
|
|
.PP
|
|
A right button mouse click on the side or top frames of the
|
|
.B 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.
|
|
|
|
.SH "OPTIONS"
|
|
.TP
|
|
.B \-\-help
|
|
Displays this manual page.
|
|
.TP
|
|
.B \-t, \-\-theme dir
|
|
.B gkrellm
|
|
will load all theme image files it finds in
|
|
.I dir
|
|
and parse the
|
|
.IR 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
|
|
.B gkrellm
|
|
is run with this option.
|
|
.TP
|
|
.B \-g, \-\-geometry +x+y
|
|
Makes
|
|
.B gkrellm
|
|
move to an
|
|
.I (x,y)
|
|
position 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 ).
|
|
.TP
|
|
.B \-wm
|
|
Forces
|
|
.B gkrellm
|
|
to start up with window manager decorations. The
|
|
default is no decorations because there are themed borders.
|
|
.TP
|
|
.B \-w, \-\-withdrawn
|
|
.B gkrellm
|
|
starts up in withdrawn mode so it can go into the Blackbox
|
|
slit (and maybe WindowMaker dock).
|
|
.TP
|
|
.B \-c, \-\-config suffix
|
|
Use alternate config files generated by appending
|
|
.I suffix
|
|
to config file names. This overrides any previous host config which may have
|
|
been setup with the below option.
|
|
.TP
|
|
.B \-f, \-\-force\-host\-config
|
|
If
|
|
.B gkrellm
|
|
is run once with this option and then the configuration
|
|
or theme is changed, the config files that are written will have
|
|
a
|
|
.I -hostname
|
|
appended to them. Subsequent runs will detect the
|
|
.IR user-config-hostname
|
|
and
|
|
.I gkrellm_theme.cfg-hostname
|
|
files and use
|
|
them instead of the normal configuration files (unless the
|
|
.B \-\-config
|
|
option is specified). This is a convenience for allowing
|
|
remote
|
|
.B gkrellm
|
|
independent config files in a shared home directory,
|
|
and for the hostname to show up in the X title for window management.
|
|
This option has no effect in client mode.
|
|
.TP
|
|
.B \-s, \-\-server hostname
|
|
Run in client mode by connecting to and collecting data from a
|
|
.B gkrellmd
|
|
server on
|
|
.I hostname
|
|
.TP
|
|
.B \-P, \-\-port server_port
|
|
Use
|
|
.I server_port
|
|
for the
|
|
.B gkrellmd
|
|
server connection.
|
|
.TP
|
|
.B \-l, \-\-logfile path
|
|
Enable sending error and debugging messages to a log file.
|
|
.TP
|
|
.B \-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
|
|
.BR xdm (1)
|
|
login screen or during a screensaver mode?
|
|
.TP
|
|
.B \-demo
|
|
Force enabling of many monitors so themers can see everything. All
|
|
config saving is inhibited.
|
|
.TP
|
|
.B \-p, \-\-plugin plugin.so
|
|
For plugin development, load the command line specified plugin so you
|
|
can avoid repeated install steps in the development cycle.
|
|
|
|
.SH "BUILTIN MONITORS"
|
|
|
|
.SS "Charts"
|
|
.PP
|
|
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.
|
|
.PP
|
|
Auto grid resolution has the following behavior.
|
|
.PP
|
|
.B Auto mode sticks at peak value
|
|
is not set:
|
|
.TP
|
|
.B ""
|
|
1) If using auto number of grids, set the resolution per grid and the
|
|
number of grids to optimize the visibility of data drawn on the chart.
|
|
Try to keep the number of grids between 1 and 7.
|
|
.TP
|
|
.B ""
|
|
2) If using a fixed number of grids, set the resolution per grid to the
|
|
smallest value that draws data without clipping.
|
|
.PP
|
|
.B Auto mode sticks at peak value
|
|
is set:
|
|
.TP
|
|
.B ""
|
|
1) If using auto number of grids, set the resolution per grid such that
|
|
drawing the peak value encountered would require at least 5 grids.
|
|
.TP
|
|
.B ""
|
|
2) If using a fixed number of grids, set the resolution per grid such
|
|
that the peak value encountered could be drawn without clipping.
|
|
This means the resolution per grid never decreases.
|
|
.PP
|
|
All resolution per grid values are constrained to a set of values in
|
|
either a 1, 2, 5 sequence or a 1, 1.5, 2, 3, 5, 7 sequence. If you set
|
|
.B Auto mode sticks at peak value
|
|
a manual
|
|
.B Auto mode recalibrate
|
|
may occasionally be required if the chart data has a wide dynamic range.
|
|
|
|
|
|
.SS "CPU Monitor"
|
|
.PP
|
|
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.
|
|
|
|
.SS "Proc Monitor"
|
|
.PP
|
|
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.
|
|
|
|
.SS "Net Monitor"
|
|
.PP
|
|
.B 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.
|
|
.PP
|
|
The timer button shows an off, standby, or on state by a distinctive
|
|
(color or shape) icon.
|
|
.IP 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
|
|
.IR /var/lock/LCK..modem,
|
|
which assumes pppd is using
|
|
.IR /dev/modem.
|
|
However, if your pppd setup does not use
|
|
.IR /dev/modem,
|
|
then you can configure an alternative with:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
ln -s /var/lock/LCK..ttySx ~/.gkrellm2/LCK..modem
|
|
.fi
|
|
.RE
|
|
.IP
|
|
where ttySx is the tty device your modem does use. The ppp on
|
|
state is detected by the existence of
|
|
.IR /var/run/pppX.pid
|
|
and the time stamp of this file is the base for the on line time.
|
|
.IP 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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
If the timer button is not linked to a net interface, then it can
|
|
be used as a push on / push off timer
|
|
.PP
|
|
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
|
|
.B gkrellm
|
|
programs. It can be easier to keep track of who is connected
|
|
to who.
|
|
|
|
.SS "Mem and Swap Monitor"
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
|
|
.SS "Internet Monitor"
|
|
.PP
|
|
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.
|
|
.PP
|
|
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 one color and FTP hits in another.
|
|
To do this, setup in the Internet configuration tab:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
HTTP 80 8080 FTP 21
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Or you could create separate monitors for HTTP and FTP. Other
|
|
monitors might be SMTP on port 25 or NNTP on port 119.
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B gkrellm
|
|
samples TCP port activity once per second, so it is possible
|
|
for port hits lasting less than a second to be missed.
|
|
|
|
.SS "File System Monitor"
|
|
.PP
|
|
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:
|
|
.PP
|
|
If a mount point is in your
|
|
.IR /etc/fstab
|
|
and you have mount permission
|
|
then
|
|
.BR mount (8)
|
|
and
|
|
.BR umount (8)
|
|
commands can be enabled and executed for that
|
|
mount point simply by checking the "Enable /etc/fstab mounting" option.
|
|
Mount table entries in
|
|
.IR /etc/fstab
|
|
must have the "user" or "owner" option set
|
|
to grant this permission unless
|
|
.B gkrellm
|
|
is run as root.
|
|
For example, if you run
|
|
.B gkrellm
|
|
as a normal user and you want to be
|
|
able to mount your floppy, your
|
|
.IR /etc/fstab
|
|
could have either of:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
/dev/fd0 /mnt/floppy ext2 user,noauto,rw,exec 0 0
|
|
/dev/fd0 /mnt/floppy ext2 user,defaults 0 0
|
|
.fi
|
|
.RE
|
|
.PP
|
|
If
|
|
.B gkrellm
|
|
is run as root or if you have
|
|
.BR sudo (1)
|
|
permission to run the
|
|
.BR mount (8)
|
|
commands, then a custom mount command can be entered into the
|
|
"mount command" entry box. A
|
|
.BR umount (8)
|
|
command must also be entered if you
|
|
choose this method. Example mount and umount entries using sudo:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
sudo /bin/mount -t msdos /dev/fd0 /mnt/A
|
|
sudo /bin/umount /mnt/A
|
|
.fi
|
|
.RE
|
|
.PP
|
|
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
|
|
.IR /etc/sudoers
|
|
for this.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
|
|
.SS "Mail Monitor"
|
|
.PP
|
|
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 such as esdplay or artsplay 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.
|
|
.PP
|
|
.B gkrellm
|
|
is capable of checking mail from local mailbox types mbox, MH, and
|
|
maildir, and from remote mailbox types POP3 and IMAP.
|
|
.PP
|
|
POP3 and IMAP checking can use non-standard port numbers and password
|
|
authentication protocols APOP (for POP3 only) or CRAM-MD5. If supported
|
|
by the mail server, emote checking may be done over an SSL connection if
|
|
the "Use SSL" option is selected.
|
|
.PP
|
|
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
|
|
.B gkrellm
|
|
to be able to
|
|
download remote mail to local mailboxes because the builtin checking
|
|
functions cannot download.
|
|
|
|
.SS "Battery Monitor"
|
|
.PP
|
|
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, time remaining
|
|
may be displayed as well as the percentage battery level. If the time
|
|
remaining is not available or is inaccurate, the Estimate Time option
|
|
may be selected to display a battery time to run or time to charge which
|
|
is calculated based on the current battery percent level, user supplied
|
|
typical battery times, and a default linear extrapolation model.
|
|
For charging, an exponential charge model may be selected.
|
|
.PP
|
|
A battery low level warning and alarm alert may be set. If battery time
|
|
is not available from the OS and the estimate time mode is not set, the
|
|
alert units will be battery percent level. Otherwise the alert units will
|
|
be battery time left in minutes. If OS battery time is not available and the
|
|
estimate time mode is set when the alert is created, the alert will have
|
|
units of time left in minutes and the alert will automatically be destroyed
|
|
if the estimate time option is subsequently turned off.
|
|
.PP
|
|
If the OS reports multiple batteries, the alert will be a master alert
|
|
which is duplicated for each battery.
|
|
|
|
.SS "CPU/Motherboard Sensors - Temperature, Voltages, and Fan RPM"
|
|
.B Linux:
|
|
.br
|
|
Sensor monitoring on Linux requires that either lm_sensors modules are
|
|
installed in your running kernel, that you run a kernel >= 2.6 with sysfs
|
|
sensors configured, or, for i386 architectures, that you have the mbmon
|
|
daemon running when
|
|
.B gkrellm
|
|
is started (as long as mbmon supports reporting
|
|
sensor values for your motherboard).
|
|
.PP
|
|
For lm_sensors to be used,
|
|
.B gkrellm
|
|
must be compiled with libsensors support.
|
|
It will be if the libsensors development package is installed when
|
|
.B gkrellm
|
|
is compiled.
|
|
.PP
|
|
If the mbmon daemon is used, it
|
|
must be started before
|
|
.B gkrellm
|
|
like so:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
mbmon -r -P port-number
|
|
.fi
|
|
.RE
|
|
.PP
|
|
where the given "port-number" must be configured to match in the
|
|
.B gkrellm
|
|
Sensors->Options config.
|
|
If you have mbmon installed from a distribution
|
|
package, you can probably easily set up for mbmon to be started at boot.
|
|
With Debian, for example, you would edit the file /etc/default/mbmon
|
|
to set:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
START_MBMON=1
|
|
.fi
|
|
.RE
|
|
.PP
|
|
and you would need to set in the
|
|
.B gkrellm
|
|
Sensors->Option config the
|
|
mbmon port to be "411" to match the default in the /etc/default/mbmon
|
|
file.
|
|
.PP
|
|
Sensor temperatures can also be read from
|
|
/proc/acpi/thermal_zone, /proc/acpi/thermal, /proc/acpi/ibm, the
|
|
PowerMac Windfarm /sysfs interface, and PowerMac PMU /sysfs based
|
|
sensors.
|
|
.PP
|
|
When using lm_sensors, libsensors will be used if available, but if
|
|
libsensors is not linked into the program, the sensor data will be
|
|
read directly from the /sysfs or /proc file systems. If running a newer
|
|
Linux kernel sensor module not yet supported by libsensors and libsensors
|
|
is linked, there will also be an automatic fallback to using /sysfs as
|
|
long as libsensors doesn't detect any sensors. But if it does detect some
|
|
sensors which does not include the new sensors you need, you can force
|
|
getting /sysfs sensor data either by running:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
gkrellm --without-libsensors
|
|
.fi
|
|
.RE
|
|
.PP
|
|
or by rebuilding with:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
make without-libsensors=yes
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Disk temperatures may also be monitored if you have the hddtemp daemon
|
|
running when
|
|
.B gkrellm
|
|
is started.
|
|
.B gkrellm
|
|
uses the default hddtemp port of 7634. Like mbmon, hddtemp is best
|
|
started in a boot script to guarantee it will be running when
|
|
.B gkrellm
|
|
is started.
|
|
.PP
|
|
NVIDIA graphics card GPU temperatures may also be monitored if
|
|
the nvidia-settings command is installed and your Nvidia card supports
|
|
the temperature reporting. If nvidia-settings is not installed or does not
|
|
report temperatures for your card, an option for using the nvclock
|
|
program will appear in the Sensors config. Nvclock use is not
|
|
automatically enabled as is nvidia-settings because nvclock can
|
|
add seconds of
|
|
.B gkrellm
|
|
startup time
|
|
when used on a NVIDIA GPU chipset it does not support. GKrellM must be
|
|
restarted to recognize changes for the nvclock option.
|
|
.PP
|
|
.B Windows:
|
|
.br
|
|
Requires a MBM install:
|
|
.IR http://mbm.livewiredev.com/.
|
|
.PP
|
|
.B FreeBSD:
|
|
.br
|
|
Builtin sensor reporting is available for some sensor chips.
|
|
FreeBSD systems can also read sensor data from the mbmon daemon as described
|
|
in the Linux section above.
|
|
.PP
|
|
.B NetBSD:
|
|
.br
|
|
Builtin sensor reporting is available for some sensor chips.
|
|
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.
|
|
.PP
|
|
.B General Setup:
|
|
.br
|
|
Temperature and fan sensor displays may be optionally located on the CPU or
|
|
Proc panels to save some vertical space while voltages are always displayed
|
|
on their own panel. If you set up to monitor both a temperature and a fan
|
|
on a single 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.
|
|
.PP
|
|
If not using libsensors, in the Setup page for the Sensors config enter
|
|
any correction factors and offsets for each of the sensors you are monitoring
|
|
(see below and lm_sensor documentation). For Linux, default values are
|
|
automatically provided for many sensor chips.
|
|
.PP
|
|
But if using libsenors, it is not possible to enter correction factors and
|
|
offsets on the Sensors config page because libsensors configuration is
|
|
done in the /etc/sensors.conf file. To get sensor debug output and to find
|
|
out the sensor data source, run:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
gkrellm -d 0x80
|
|
.fi
|
|
.RE
|
|
.PP
|
|
.nf
|
|
Note for NetBSD users:
|
|
.fi
|
|
.RS
|
|
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.
|
|
.PP
|
|
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 simultaneously /dev/sysmon (see NetBSD PR#14368). A (quick and
|
|
dirty) workaround for this is to monopolize the driver :)
|
|
.RE
|
|
|
|
.SS "CPU/Motherboard Temperatures"
|
|
.PP
|
|
Most modern motherboards will not require setting temperature correction
|
|
factors and offsets other than the defaults. However, for lm_sensors it
|
|
is necessary to have a correct "set sensor" line in
|
|
.IR /etc/sensors.conf
|
|
if the temperature sensor type is other than the default thermistor.
|
|
If using Linux sysfs sensors, this sensor type would be set by writing to
|
|
a sysfs file. For example, you might at boot set a sysfs temperature sensor
|
|
type with:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
echo "2" > /sys/bus/i2c/devices/0-0290/sensor2
|
|
.fi
|
|
.RE
|
|
.PP
|
|
On the other hand, some older motherboards may need temperature calibration
|
|
by setting a correction factor and offset for each temperature sensor
|
|
because of factors such as variations in physical thermistor contact
|
|
with the CPU. Unfortunately, this calibration may not be practical or
|
|
physically possible because it requires that somehow you can get a real
|
|
CPU temperature reading. So, the calibration discussion which follows
|
|
should probably be considered an academic exercise that might give you
|
|
some good (or bad) ideas. If you have a recent motherboard, skip the
|
|
following.
|
|
.PP
|
|
Anyway, 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 (and this
|
|
is where things get impractical).
|
|
.PP
|
|
Here is a hypothetical CPU calibration procedure. Make sure
|
|
.B gkrellm
|
|
is configured with default factors of 1.0 and offsets of 0 and is reporting
|
|
temperatures in centigrade:
|
|
.PP
|
|
.IP "1 \(bu"
|
|
Power on the machine and read a real temperature T1 from the bios or
|
|
a temperature probe. If reading from the bios, proceed with booting
|
|
the OS. Now record a sensor temperature S1 as reported by
|
|
.B gkrellm.
|
|
.IP "2 \(bu"
|
|
Change the room temperature environment (turn off your AC or change
|
|
computer fan exhaust speed). Now repeat step 1, this time recording
|
|
a real temperature T2 and
|
|
.B gkrellm
|
|
reported sensor temperature S2.
|
|
.IP "3 \(bu"
|
|
Now you can calculate the correction factor and offset you need
|
|
to enter into the Sensor configuration tab:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
|
|
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
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SS "Voltage Sensor Corrections"
|
|
.PP
|
|
You need to read this section only if you think the default voltage correction
|
|
factors and offsets are incorrect. For Linux and lm_sensors and sysfs sensors
|
|
this would be if
|
|
.B gkrellm
|
|
does not know about your particular sensor chip.
|
|
For MBM with Windows, the default values should be correct.
|
|
.PP
|
|
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:
|
|
.PP
|
|
.IP "1 \(bu"
|
|
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.
|
|
.IP "2 \(bu"
|
|
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.
|
|
.IP "3 \(bu"
|
|
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.
|
|
.IP "4 \(bu"
|
|
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.
|
|
.PP
|
|
.RS
|
|
.nf
|
|
|
|
For cases 2 and 3, the sensor chip input network looks like:
|
|
|
|
Vs o----/\\/\\/---o-------------o Vin
|
|
R1 |
|
|
o--/\\/\\/--o Vref
|
|
R2
|
|
.fi
|
|
.RE
|
|
.PP
|
|
.IP "where,"
|
|
.RS
|
|
.TP
|
|
.I "Vs"
|
|
is the motherboard voltage under measurement
|
|
.TP
|
|
.I "Vin"
|
|
is the voltage at the input pin of the sensor chip and therefore is
|
|
the voltage reading that will need correction.
|
|
.TP
|
|
.I "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.
|
|
.RE
|
|
.PP
|
|
|
|
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.
|
|
.PP
|
|
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:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
(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).
|
|
|
|
.fi
|
|
.RE
|
|
.PP
|
|
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:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
compute in3 ((6.8/10)+1)*@ , @/((6.8/10)+1)
|
|
|
|
.fi
|
|
.RE
|
|
.PP
|
|
yields a correction factor of ((6.8/10)+1) = 1.68
|
|
and an offset of zero.
|
|
.PP
|
|
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.
|
|
.PP
|
|
A more complicated compute line for a case 3 voltage:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
|
|
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
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Here is a table of correction factors and offsets based on some typical
|
|
compute line entries from /etc/sensors.conf:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
|
|
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 -
|
|
|
|
.fi
|
|
.RE
|
|
|
|
.SS "Command launching"
|
|
.PP
|
|
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. If the command is a
|
|
console command (doesn't have a graphical user interface), then
|
|
the command must be run in a terminal window such as xterm, eterm,
|
|
or Gnome terminal. For example running the "top" command would take:
|
|
.TP
|
|
xterm -e top
|
|
.PP
|
|
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
|
|
.B 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:
|
|
.TP
|
|
.I calendar:
|
|
gnomecal, evolution, or ical
|
|
.TP
|
|
.I CPU:
|
|
xterm -e top or gps or gtop
|
|
.TP
|
|
.I inet:
|
|
gftp or xterm -e ftpwho
|
|
.TP
|
|
.I net:
|
|
mozilla, galeon, skipstone, or xterm -e slrn -C-
|
|
.PP
|
|
And so on... Tooltips can be set up for these commands.
|
|
|
|
.SS "Alerts"
|
|
.PP
|
|
Most monitors can have alerts configured to give warnings and alarms
|
|
for data readings which range outside of configurable limits. Where
|
|
useful, a delay of the alert trigger can be configured. A warning or
|
|
alarm consists of an attention grabbing decal appearing and an optional
|
|
command being executed.
|
|
For most monitors the command may contain the
|
|
same substitution variables which are available for display in the
|
|
chart or panel label format strings and are documented on configuration
|
|
Info pages. Additionally, the hostname may be embedded in the command
|
|
with the $H substitution variable.
|
|
.PP
|
|
If you have festival installed, either a warn or alarm command
|
|
could be configured to speak something. For example a CPU temperature
|
|
alert warn command could just speak the current temperature with:
|
|
.nf
|
|
|
|
sh -c "echo warning C P U is at $s degrees | esddsp festival --tts"
|
|
|
|
.fi
|
|
Assuming you have esd running.
|
|
|
|
.SH "THEMES"
|
|
.PP
|
|
A theme is a directory containing image files and a
|
|
.IR gkrellmrc
|
|
configuration file. The theme directory may be installed in
|
|
several locations:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
~/.gkrellm2/themes
|
|
/usr/local/share/gkrellm2/themes
|
|
/usr/share/gkrellm2/themes
|
|
.fi
|
|
.RE
|
|
.PP
|
|
For compatibility with Gtk themes, a
|
|
.B gkrellm
|
|
theme may also be installed as:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
~/.themes/THEME_NAME/gkrellm2
|
|
/usr/share/themes/THEME_NAME/gkrellm2
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Finally, a theme you simply want to check out can be untarred anywhere and
|
|
used by running:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
gkrellm -t path_to_theme
|
|
.fi
|
|
.RE
|
|
.PP
|
|
If you are interested in writing a theme, go to the Themes page
|
|
at
|
|
.IR http://www.gkrellm.net
|
|
and there you will find a Theme making reference.
|
|
|
|
|
|
.SH "PLUGINS"
|
|
.PP
|
|
.B gkrellm
|
|
tries to load all plugins (shared object files ending in .so)
|
|
it finds in your plugin directory
|
|
.IR ~/.gkrellm2/plugins.
|
|
The directories
|
|
.IR /usr/local/lib/gkrellm2/plugins
|
|
and
|
|
.IR /usr/lib/gkrellm2/plugins
|
|
are also searched for plugins to install.
|
|
.PP
|
|
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.
|
|
.PP
|
|
If you are interested in writing a plugin, go to the Plugins page
|
|
at
|
|
.IR http://www.gkrellm.net
|
|
and there you will find a Plugin programmers reference.
|
|
|
|
|
|
.SH "CLIENT/SERVER"
|
|
When a local
|
|
.B gkrellm
|
|
runs in client mode and connects to a remote
|
|
.B gkrellmd
|
|
server all builtin monitors collect
|
|
their data from the server. However, the client
|
|
.B gkrellm
|
|
process is running
|
|
on the local machine, so any enabled plugins will run in the local
|
|
context (Flynn is an exception to this since it derives its data from
|
|
the builtin CPU monitor). Also, any command launching will run commands
|
|
on the local machine.
|
|
|
|
.SH "FILES"
|
|
.TP
|
|
.I ~/.gkrellm2
|
|
User gkrellm directory where are located configuration files, user's plugins
|
|
and user's themes.
|
|
.TP
|
|
.I ~/.gkrellm2/plugins
|
|
User plugin directory.
|
|
.TP
|
|
.I /usr/lib/gkrellm2/plugins
|
|
System wide plugin directory.
|
|
.TP
|
|
.I /usr/local/lib/gkrellm2/plugins
|
|
Local plugin directory.
|
|
.TP
|
|
.I ~/.gkrellm2/themes
|
|
User theme directory.
|
|
.TP
|
|
.I ~/.themes/THEME_NAME/gkrellm2
|
|
User theme packaged as part of a user Gtk theme.
|
|
.TP
|
|
.I /usr/share/gkrellm2/themes
|
|
System wide theme directory.
|
|
.TP
|
|
.I /usr/local/share/gkrellm2/themes
|
|
Local theme directory.
|
|
.TP
|
|
.I /usr/share/themes/THEME_NAME/gkrellm2
|
|
System wide theme packaged as part of a system wide Gtk theme.
|
|
|
|
.SH "AUTHORS"
|
|
|
|
This manual page was written by Bill Wilson <billw@gkrellm.net>.
|
|
http://www.gkrellm.net/
|
|
|
|
.SH "SEE ALSO"
|
|
.BR fstab (5),
|
|
.BR sudo (1),
|
|
.BR mount (8),
|
|
.BR pppd (8),
|
|
.BR umount (8)
|