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