1gkrellm(1)                       User's Manual                      gkrellm(1)
2
3
4

NAME

6       gkrellm - The GNU Krell Monitors
7
8

SYNOPSIS

10       gkrellm  [ --help ] [ -t | --theme dir ] [ -g | --geometry +x+y ] [ -wm
11       ] [ -w | --withdrawn ] [ -c |  --config  suffix  ]  [  -nc  ]  [  -f  |
12       --force-host-config  ]  [  -demo  ]  [ -p | --plugin plugin.so ] [ -s |
13       --server hostname ] [ -P | --port server_port ] [ -l | --logfile path ]
14
15

DESCRIPTION

17       With a single process, gkrellm manages multiple  stacked  monitors  and
18       supports  applying themes to match the monitors appearance to your win‐
19       dow manager, Gtk, or any other theme.
20
21
22   FEATURES
23       ·   SMP CPU, Disk, Proc, and active net interface monitors with LEDs.
24
25       ·   Internet monitor that displays current and charts  historical  port
26           hits.
27
28       ·   Memory and swap space usage meters and a system uptime monitor.
29
30       ·   File system meters show capacity/free space and can mount/umount.
31
32       ·   A  mbox/maildir/MH/POP3/IMAP  mail  monitor which can launch a mail
33           reader or remote mail fetch program.
34
35       ·   Clock/calendar and hostname display.
36
37       ·   Laptop Battery monitor.
38
39       ·   CPU/motherboard temperature/fan/voltages display with warnings  and
40           alarms.   Linux requires a sensor configured sysfs, lm_sensors mod‐
41           ules or a running mbmon daemon.  FreeBSD can also  read  the  mbmon
42           daemon.  Windows requires MBM.
43
44       ·   Disk temperatures if there's a running hddtemp daemon.
45
46       ·   Multiple  monitors  managed  by  a  single process to reduce system
47           load.
48
49       ·   A timer button that can execute PPP or ISDN logon/logoff scripts.
50
51       ·   Charts are autoscaling with configurable grid line resolution, or
52
53       ·   can be set to a fixed scale mode.
54
55       ·   Separate colors for "in" and "out" data.  The in color is used  for
56           CPU  user  time,  disk  read, forks, and net receive data.  The out
57           color is used for CPU sys time, disk write, load, and net  transmit
58           data.
59
60       ·   Commands can be configured to run when monitor labels are clicked.
61
62       ·   Data  can  be  collected from a gkrellmd server running on a remote
63           machine.
64
65       ·   gkrellm is plugin capable so special interest monitors can be  cre‐
66           ated.
67
68       ·   Many themes are available.
69
70
71   USER INTERFACE
72       · Top frame
73
74              Btn 1  Press and drag to move gkrellm window.
75
76              Btn 3  Popup main menu.
77
78       · Side frames
79
80              Btn 2  Slide gkrellm window shut (Btn1 if -m2 option).
81
82              Btn 3  Popup main menu.
83
84       · All charts
85
86              Btn 1  Toggle draw of extra info on the chart.
87
88              Btn 3  Brings up a chart configuration window.
89
90       · Inet charts
91
92              Btn 2  Toggle between port hits per minute and hour.
93
94       · Most panels
95
96              Btn 3  Opens  the  configuration  window directly to a monitor's
97                     configuration page.
98
99       · File System meter panels
100
101              Btn 1,2
102                     Toggle display of label and fs  capacity  scrolling  dis‐
103                     play.   The  mount button runs mount/umount commands.  If
104                     ejectable, left click the  eject  button  to  open  tray,
105                     right click to close.
106
107       · Mem and Swap meter panels
108
109              Btn 1,2
110                     Toggle  display  of  label  and  memory  or swap capacity
111                     scrolling display.
112
113       · Mailbox monitor message count button
114
115              Btn 1  Launch a mail reader program.  If  options  permit,  also
116                     stop animations and reset remote message counts.
117
118              Btn 2  Toggle  mail  check  mute  mode  which inhibits the sound
119                     notify program, and optionally inhibits all  mail  check‐
120                     ing.
121
122       · Mailbox monitor envelope decal
123
124              Btn 1  Force a mail check regardless of mute or timeout state.
125
126       · Battery monitor panel
127
128              Btn 1  On the charging state decal toggles battery minutes left,
129                     percent level, and charge rate display.
130
131              Btn 2  Anywhere on the panel also toggles the display.
132
133       · Keyboard shortcuts
134
135              F1     popup the user config window.
136
137              F2     popup the main menu.
138
139              Page_Up
140                     previous theme or theme alternative.
141
142              Page_Down
143                     next theme or theme alternative.
144
145              <Ctl>Page_Up
146                     previous theme, skipping any theme alternatives.
147
148              <Ctl>Page_Down
149                     next theme, skipping any theme alternatives.
150
151       If a command has been configured to be launched for a monitor,  then  a
152       button  will  appear  when  the mouse enters the panel of that monitor.
153       Clicking the button will launch the command.
154
155       A right button mouse click on the side or top  frames  of  the  gkrellm
156       window  will pop up a user configuration window where you can configure
157       all the builtin and plugin monitors.  Chart appearance may  be  config‐
158       ured  by  right  clicking on a chart, and right clicking on many panels
159       will open the configuration window directly to the corresponding  moni‐
160       tor's configuration page.
161
162

OPTIONS

164       --help Displays this manual page.
165
166       -t, --theme dir
167              gkrellm  will  load  all  theme  image files it finds in dir and
168              parse the gkrellmrc file if one exists.  This  option  overrides
169              the loading of the last theme you configured to be loaded in the
170              Themes configuration window.  Theme changes are not  saved  when
171              gkrellm is run with this option.
172
173       -g, --geometry +x+y
174              Makes  gkrellm  move  to  an  (x,y)  position  on  the screen at
175              startup.  Standard X window geometry position (not size) formats
176              are  parsed,  ie +x+y -x+y +x-y -x-y.  Except, negative geometry
177              positions are not recognized (ie +-x--y ).
178
179       -wm    Forces gkrellm to start up with window manager decorations.  The
180              default is no decorations because there are themed borders.
181
182       -w, --withdrawn
183              gkrellm starts up in withdrawn mode so it can go into the Black‐
184              box slit (and maybe WindowMaker dock).
185
186       -c, --config suffix
187              Use alternate config files generated by appending suffix to con‐
188              fig  file  names.  This overrides any previous host config which
189              may have been setup with the below option.
190
191       -f, --force-host-config
192              If gkrellm is run once with this option and then the  configura‐
193              tion or theme is changed, the config files that are written will
194              have a -hostname appended to them.  Subsequent runs will  detect
195              the  user-config-hostname  and  gkrellm_theme.cfg-hostname files
196              and use them instead of the normal configuration  files  (unless
197              the  --config  option is specified).   This is a convenience for
198              allowing remote gkrellm independent config  files  in  a  shared
199              home  directory,  and for the hostname to show up in the X title
200              for window management.  This option  has  no  effect  in  client
201              mode.
202
203       -s, --server hostname
204              Run  in  client mode by connecting to and collecting data from a
205              gkrellmd server on hostname
206
207       -P, --port server_port
208              Use server_port for the gkrellmd server connection.
209
210       -l, --logfile path
211              Enable sending error and debugging messages to a log file.
212
213       -nc    No config mode.  The config menu is blocked so no config changes
214              can  be made.  Useful in certain environments, or maybe for run‐
215              ning on a xdm(1) login screen or during a screensaver mode?
216
217       -demo  Force enabling of many monitors so themers can  see  everything.
218              All config saving is inhibited.
219
220       -p, --plugin plugin.so
221              For  plugin  development, load the command line specified plugin
222              so you can avoid  repeated  install  steps  in  the  development
223              cycle.
224
225

BUILTIN MONITORS

227   Charts
228       The  default  for  most charts is to automatically adjust the number of
229       grid lines drawn and the resolution per grid  so  drawn  data  will  be
230       nicely visible.  You may change this to fixed grids of 1-5 and/or fixed
231       grid resolutions in the chart  configuration  windows.   However,  some
232       combination of the auto scaling modes may give best results.
233
234       Auto grid resolution has the following behavior.
235
236       Auto mode sticks at peak value is not set:
237
238              1)  If  using  auto number of grids, set the resolution per grid
239              and the number of grids to optimize the visibility of data drawn
240              on the chart.  Try to keep the number of grids between 1 and 7.
241
242              2) If using a fixed number of grids, set the resolution per grid
243              to the smallest value that draws data without clipping.
244
245       Auto mode sticks at peak value is set:
246
247              1) If using auto number of grids, set the  resolution  per  grid
248              such  that  drawing  the peak value encountered would require at
249              least 5 grids.
250
251              2) If using a fixed number of grids, set the resolution per grid
252              such  that  the  peak  value  encountered could be drawn without
253              clipping.  This means the resolution per grid never decreases.
254
255       All resolution per grid values are constrained to a set  of  values  in
256       either a 1, 2, 5 sequence or a 1, 1.5, 2, 3, 5, 7 sequence.  If you set
257       Auto mode sticks at peak value a manual Auto mode recalibrate may occa‐
258       sionally be required if the chart data has a wide dynamic range.
259
260
261
262   CPU Monitor
263       Data is plotted as a percentage.  In auto number of grids mode, resolu‐
264       tion is a fixed 20% per grid.  In fixed number of grids mode, grid res‐
265       olution is 100% divided by the number of grids.
266
267
268   Proc Monitor
269       The krell shows process forks with a full scale value of 10 forks.  The
270       chart has a resolution of 10 forks/sec per grid in auto number of grids
271       mode  and 50 forks/second maximum on the chart in fixed number of grids
272       mode.  The process load resolution per grid is best  left  at  1.0  for
273       auto  number of grids, but can be set as high as 5 if you configure the
274       chart to have only 1 or 2 fixed grids.
275
276
277   Net Monitor
278       gkrellm is designed to display a chart for net interfaces which are up,
279       which means they are listed in the routing table (however, it is possi‐
280       ble in some cases to monitor unrouted interfaces).  One  net  interface
281       may  be  linked to a timer button which can be used to connect and dis‐
282       connect from an ISP.
283
284       The timer button shows an off, standby, or on state  by  a  distinctive
285       (color or shape) icon.
286
287       ppp    Standby  state is while the modem phone line is locked while ppp
288              is connecting, and the on state is the ppp link connected.   The
289              phone line lock is determined by the existence of the modem lock
290              file  /var/lock/LCK..modem,  which   assumes   pppd   is   using
291              /dev/modem.    However,   if   your  pppd  setup  does  not  use
292              /dev/modem, then you can configure an alternative with:
293
294              ln  -s  /var/lock/LCK..ttySx   ~/.gkrellm2/LCK..modem
295
296              where ttySx is the tty device your modem does use.  The  ppp  on
297              state  is detected by the existence of /var/run/pppX.pid and the
298              time stamp of this file is the base for the on line time.
299
300       ippp   The timer button standby state is not applicable to ISDN  inter‐
301              faces that are always routed. The on state is ISDN on line while
302              the ippp interface is routed.  The on line  timer  is  reset  at
303              transitions from ISDN hangup state to on line state.
304
305       For  both ppp and ippp timer button links, the panel area of the inter‐
306       face is always shown and the chart appears when the interface is routed
307       with the phone link connected or on line.
308
309       If  the  timer  button is not linked to a net interface, then it can be
310       used as a push on / push off timer
311
312       Net monitors can have a label so that the interface can  be  associated
313       with  the  identity of the other end of the connection.  This is useful
314       if you have several net connections or run multiple remote gkrellm pro‐
315       grams.  It can be easier to keep track of who is connected to who.
316
317
318   Mem and Swap Monitor
319       Here  you  are  reading  a ratio of total used to total available.  The
320       amount of memory used indicated by the memory  monitor  is  actually  a
321       calculated  "used"  memory.   If you enter the "free" command, you will
322       see that most of your memory is almost always used because  the  kernel
323       uses  large amounts for buffers and cache.  Since the kernel can free a
324       lot of this memory as user process demand for memory goes  up,  a  more
325       realistic  reading of memory in use is obtained by subtracting the buf‐
326       fers and cached memory from the kernel reported used.  This is shown in
327       the  free command output in the "-/+ buffers/cache" line where a calcu‐
328       lated used amount has buffers and cached  memory  subtracted  from  the
329       kernel  reported used memory, and a calculated free amount has the buf‐
330       fers and cached memory added in.
331
332       While the memory meter always shows the calculated "used"  memory,  the
333       raw memory values total, shared, buffered, and cached may be optionally
334       displayed in the memory panel by entering an appropriate format display
335       string in the config.
336
337       Units:  All memory values have units of binary megabytes (MiB).  Memory
338       sizes have historically been reported in  these  units  because  memory
339       arrays on silicon have always increased in size by multiples of 2.  Add
340       an address line to a memory chip and you double or quadruple (a  multi‐
341       plexed address) the memory size.  A binary megabyte is 2^20 or 1048576.
342       Contrast this with units for other stats such as disk capacities or net
343       transfer  rates  where  the proper units are decimal megabytes or kilo‐
344       bytes.  Disk drive capacities do not increase by powers of 2 and  manu‐
345       facturers do not use binary units when reporting their sizes.  However,
346       some of you may prefer to see a binary disk drive capacity reported, so
347       it is available as an option.
348
349
350   Internet Monitor
351       Displays  TCP  port  connections  and records historical port hits on a
352       minute or hourly chart.  Middle button click on an inet chart to toggle
353       between  the  minute  and  hourly displays.  There is a strip below the
354       minute or hour charts where marks are drawn for  port  hits  in  second
355       intervals.   Each  inet  krell  also  shows port hits with a full scale
356       range of 5 hits.  The left button toggle of extra info displays current
357       port connections.
358
359       For each internet monitor you can specify two labeled datasets with one
360       or two ports for each dataset.  There are two ports because some inter‐
361       net  ports  are related and you might want to group them - for example,
362       the standard HTTP port is 80, but there is also a www web caching  ser‐
363       vice on port 8080.  So it makes sense to have a HTTP monitor which com‐
364       bines data from both ports.  A possible common configuration  would  be
365       to create one inet monitor that monitors HTTP hits plotted in one color
366       and FTP hits in another.  To do this, setup in the Internet  configura‐
367       tion tab:
368
369              HTTP  80 8080    FTP  21
370
371       Or you could create separate monitors for HTTP and FTP.  Other monitors
372       might be SMTP on port 25 or NNTP on port 119.
373
374       If you check the "Port0 - Port1 is a range" button,  then  all  of  the
375       ports  between  the  two entries will be monitored.  Clicking the small
376       button on the Inet panels will pop up a window  listing  the  currently
377       connected port numbers and the host that is connected to it.
378
379       gkrellm  samples  TCP  port activity once per second, so it is possible
380       for port hits lasting less than a second to be missed.
381
382
383   File System Monitor
384       File system mount points can be selected to be monitored with  a  meter
385       that  shows the ratio of blocks used to total blocks available.  Mount‐
386       ing commands can be enabled for mount points in one of two ways:
387
388       If a mount point is in your /etc/fstab and you  have  mount  permission
389       then  mount(8)  and  umount(8) commands can be enabled and executed for
390       that mount point simply by checking the  "Enable  /etc/fstab  mounting"
391       option.   Mount  table  entries  in  /etc/fstab must have the "user" or
392       "owner" option set to grant this permission unless gkrellm  is  run  as
393       root.  For example, if you run gkrellm as a normal user and you want to
394       be able to mount your floppy, your /etc/fstab could have either of:
395
396              /dev/fd0 /mnt/floppy  ext2 user,noauto,rw,exec  0  0
397              /dev/fd0 /mnt/floppy  ext2 user,defaults  0  0
398
399       If gkrellm is run as root or if you have sudo(1) permission to run  the
400       mount(8)  commands, then a custom mount command can be entered into the
401       "mount command" entry box.  A umount(8) command must also be entered if
402       you choose this method.  Example mount and umount entries using sudo:
403
404              sudo /bin/mount -t msdos /dev/fd0 /mnt/A
405              sudo /bin/umount /mnt/A
406
407       Notes:  the  mount point specified in a custom mount command (/mnt/A in
408       this example) must be the same as entered in the "Mount  Point"  entry.
409       Also, you should have the NOPASSWD option set in /etc/sudoers for this.
410
411       File system monitors can be created as primary (always visible) or sec‐
412       ondary which can be hidden and then shown when they  are  of  interest.
413       For  example,  you  might  make  primary file system monitors for root,
414       home, or user so they will be always visible, but make secondary  moni‐
415       tors  for less frequently used mount points such as floppy, zip, backup
416       partitions, foreign file system types, etc.  Secondary FS monitors  can
417       also be configured to always be visible if they are mounted by checking
418       the "Show if mounted" option.   Using this feature  you  can  show  the
419       secondary  group,  mount a file system, and have that FS monitor remain
420       visible even when the secondary group  is  hidden.   A  standard  cdrom
421       mount will show as 100% full but a monitor for it could be created with
422       mounting enabled just to have the mount/umount convenience.
423
424       When the "Ejectable" option is selected for a  file  system,  an  eject
425       button will appear when the mouse enters the file system panel.  If you
426       are not using /etc/fstab mounting, a device file  to  eject  will  also
427       need  to  be  entered.   Systems may have varying levels of support for
428       this feature ranging from none or basic using an ioctl() to  full  sup‐
429       port using an eject command to eject all its supported devices.   Linux
430       and NetBSD use the "eject" command while FreeBSD uses  the  "cdcontrol"
431       command,  so be sure these commands are installed.  Most eject commands
432       will also support closing a CDROM tray.  If they do, you will  be  able
433       to access this function by right clicking the eject button.
434
435
436   Mail Monitor
437       Checks your mailboxes for unread mail. A mail reading program (MUA) can
438       be executed with a left mouse click on the mail monitor  panel  button,
439       and  a  mail  notify (play a sound) program such as esdplay or artsplay
440       can be executed whenever the new mail count increases.  The mail  panel
441       envelope  decal may also be clicked to force an immediate mail check at
442       any time.
443
444       gkrellm is capable of checking mail from local mailbox types mbox,  MH,
445       and maildir,  and from remote mailbox types POP3 and IMAP.
446
447       POP3  and  IMAP checking can use non-standard port numbers and password
448       authentication protocols APOP (for POP3 only)  or  CRAM-MD5.   If  sup‐
449       ported  by the mail server, emote checking may be done over an SSL con‐
450       nection if the "Use SSL" option is selected.
451
452       Before internal POP3 and IMAP checking  was  added,  an  external  mail
453       fetch/check  program  could  be  set  up to be executed periodically to
454       download or check remote POP3 or  IMAP  mail.   This  method  is  still
455       available  and  must be used if you want gkrellm to be able to download
456       remote mail to local mailboxes because the builtin  checking  functions
457       cannot download.
458
459
460   Battery Monitor
461       This  meter will be available if a battery exists and will show battery
462       percentage life remaining.  A decal indicates if AC line  is  connected
463       or  if the battery is in use.  If the data is available, time remaining
464       may be displayed as well as the percentage battery level. If  the  time
465       remaining  is  not available or is inaccurate, the Estimate Time option
466       may be selected to display a battery time to  run  or  time  to  charge
467       which  is  calculated  based on the current battery percent level, user
468       supplied typical battery times,  and  a  default  linear  extrapolation
469       model.  For charging, an exponential charge model may be selected.
470
471       A  battery  low  level  warning and alarm alert may be set.  If battery
472       time is not available from the OS and the estimate  time  mode  is  not
473       set,  the  alert  units  will  be battery percent level.  Otherwise the
474       alert units will be battery time left in minutes.  If OS  battery  time
475       is  not  available  and the estimate time mode is set when the alert is
476       created, the alert will have units of time  left  in  minutes  and  the
477       alert  will  automatically  be destroyed if the estimate time option is
478       subsequently turned off.
479
480       If the OS reports multiple batteries, the alert will be a master  alert
481       which is duplicated for each battery.
482
483
484   CPU/Motherboard Sensors - Temperature, Voltages, and Fan RPM
485       Linux:
486       Sensor  monitoring on Linux requires that either lm_sensors modules are
487       installed in your running kernel, that you run a  kernel  >=  2.6  with
488       sysfs sensors configured, or, for i386 architectures, that you have the
489       mbmon daemon running when gkrellm is started (as long as mbmon supports
490       reporting sensor values for your motherboard).
491
492       For  lm_sensors  to  be  used, gkrellm must be compiled with libsensors
493       support.  It will be if the libsensors development package is installed
494       when  gkrellm is compiled.  Using libsensors is the preferred interface
495       on Linux since it is the only interface that will be up to date on sup‐
496       porting  correct  voltage scaling factors and offsets for recent sensor
497       chips.
498
499       If the mbmon daemon is used, it must be started before gkrellm like so:
500
501              mbmon -r -P port-number
502
503       where the given "port-number"  must  be  configured  to  match  in  the
504       gkrellm  Sensors->Options  config.   If you have mbmon installed from a
505       distribution package, you can probably easily set up for  mbmon  to  be
506       started  at  boot.   With  Debian, for example, you would edit the file
507       /etc/default/mbmon to set:
508
509              START_MBMON=1
510
511       and you would need to set in the  gkrellm  Sensors->Option  config  the
512       mbmon  port  to be "411" to match the default in the /etc/default/mbmon
513       file.
514
515       Sensor temperatures can  also  be  read  from  /proc/acpi/thermal_zone,
516       /proc/acpi/thermal, /proc/acpi/ibm, the PowerMac Windfarm /sysfs inter‐
517       face, and PowerMac PMU /sysfs based sensors.
518
519       When using lm_sensors, libsensors will be used  if  available,  but  if
520       libsensors is not linked into the program, the sensor data will be read
521       directly from the /sysfs or /proc file systems.   If  running  a  newer
522       Linux  kernel sensor module not yet supported by libsensors and libsen‐
523       sors is linked, there will also be  an  automatic   fallback  to  using
524       /sysfs  as  long  as  libsensors doesn't detect any sensors.  But if it
525       does detect some sensors which does not include  the  new  sensors  you
526       need, you can force getting /sysfs sensor data either by running:
527
528              gkrellm --without-libsensors
529
530       or by rebuilding with:
531
532              make without-libsensors=yes
533
534       Disk  temperatures may also be monitored if you have the hddtemp daemon
535       running when gkrellm is started.  gkrellm uses the default hddtemp port
536       of 7634.  Like mbmon, hddtemp is best started in a boot script to guar‐
537       antee it will be running when gkrellm is started.
538
539       NVIDIA graphics card GPU temperatures may  also  be  monitored  if  the
540       nvidia-settings  command is installed and your Nvidia card supports the
541       temperature reporting.  If nvidia-settings is not installed or does not
542       report temperatures for your card, an option for using the nvclock pro‐
543       gram will appear in the Sensors config.  Nvclock use is  not  automati‐
544       cally  enabled as is nvidia-settings because nvclock can add seconds of
545       gkrellm startup time when used on a NVIDIA GPU chipset it does not sup‐
546       port.   GKrellM  must be restarted to recognize changes for the nvclock
547       option.
548
549       Windows:
550       Requires a MBM install: http://mbm.livewiredev.com/.
551
552       FreeBSD:
553       Builtin sensor reporting is available for some sensor  chips.   FreeBSD
554       systems can also read sensor data from the mbmon daemon as described in
555       the Linux section above.
556
557       NetBSD:
558       Builtin sensor reporting is available for some  sensor  chips.   NetBSD
559       uses  the  envsys(4)  interface  and  sensors  reading is automatically
560       enabled if you have either a lm(4) or viaenv(4) chip configured in your
561       kernel.
562
563       General Setup:
564       Temperature  and  fan  sensor displays may be optionally located on the
565       CPU or Proc panels to save  some  vertical  space  while  voltages  are
566       always  displayed  on their own panel.  If you set up to monitor both a
567       temperature and a fan on a single CPU or Proc panel, they can  be  dis‐
568       played  optionally as an alternating single display or as separate dis‐
569       plays.  If separate, the fan display will replace the panel label.  The
570       configuration for this is under the CPU and Proc config pages.
571
572       If not using libsensors, in the Setup page for the Sensors config enter
573       any correction factors and offsets for each of the sensors you are mon‐
574       itoring  (see  below  and lm_sensor documentation).  For Linux, default
575       values are automatically provided for many sensor chips.
576
577       But if using libsenors, it is not possible to enter correction  factors
578       and offsets on the Sensors config page because libsensors configuration
579       is done in the /etc/sensors.conf file.  To get sensor debug output  and
580       to find out the sensor data source, run:
581
582              gkrellm -d 0x80
583
584       Note for NetBSD users:
585              The  current  implementation  of the sensor reading under NetBSD
586              opens /dev/sysmon and never closes it. Since  that  device  does
587              not  support concurrent accesses, you won't be able to run other
588              apps such as envstat(8) while GKrellM is  running.   This  might
589              change if this happens to be an issue.
590
591              The  reasons  for this choice are a) efficiency (though it might
592              be possible to open/close /dev/sysmon each  time  a  reading  is
593              needed  without  major  performance  issue) and b) as of October
594              2001, there's a bug in  the  envsys(4)  driver  which  sometimes
595              causes  deadlocks  when  processes  try to access simultaneously
596              /dev/sysmon  (see NetBSD PR#14368). A (quick  and  dirty)  work‐
597              around for this is to monopolize the driver :)
598
599
600   CPU/Motherboard Temperatures
601       Most  modern  motherboards will not require setting temperature correc‐
602       tion factors and offsets other than the defaults.  However, for lm_sen‐
603       sors  it  is necessary to have a correct "set sensor" line in /etc/sen‐
604       sors.conf if the temperature sensor type  is  other  than  the  default
605       thermistor.   If  using  Linux sysfs sensors, this sensor type would be
606       set by writing to a sysfs file.  For example, you might at boot  set  a
607       sysfs temperature sensor type with:
608
609              echo "2" > /sys/bus/i2c/devices/0-0290/sensor2
610
611       On  the  other hand, some older motherboards may need temperature cali‐
612       bration by setting a correction factor and offset for each  temperature
613       sensor  because  of  factors  such as variations in physical thermistor
614       contact with the CPU.  Unfortunately, this calibration may not be prac‐
615       tical  or  physically possible because it requires that somehow you can
616       get a real CPU temperature reading.   So,  the  calibration  discussion
617       which  follows  should probably be considered an academic exercise that
618       might give you some good (or bad) ideas. If you have a  recent  mother‐
619       board, skip the following.
620
621       Anyway,  to do this calibration, take two real CPU temperature readings
622       corresponding to two sensor reported readings.   To get the real  read‐
623       ings,  you  can  trust that your motherboard manufacturer has done this
624       calibration and is reporting accurate temperatures in the bios, or  you
625       can  put  a  temperature  probe  directly on your CPU case (and this is
626       where things get impractical).
627
628       Here is a hypothetical CPU calibration procedure.  Make sure gkrellm is
629       configured  with default factors of 1.0 and offsets of 0 and is report‐
630       ing temperatures in centigrade:
631
632       1 ·    Power on the machine and read a real  temperature  T1  from  the
633              bios  or a temperature probe.  If reading from the bios, proceed
634              with booting the OS.  Now record  a  sensor  temperature  S1  as
635              reported by gkrellm.
636
637       2 ·    Change  the  room  temperature  environment (turn off your AC or
638              change computer fan exhaust speed).  Now  repeat  step  1,  this
639              time recording a real temperature T2 and gkrellm reported sensor
640              temperature S2.
641
642       3 ·    Now you can calculate the correction factor and offset you  need
643              to enter into the Sensor configuration tab:
644
645              From:
646
647              s - S1     t - T1
648              ------  =  ------
649              S2 - S1    T2 - T1
650
651                       T2 - T1     S2*T1 - S1*T2
652              t  = s * -------  +  -------------
653                       S2 - S1         S2 - S1
654
655              So:
656
657                        T2 - T1                S2*T1 - S1*T2
658              factor =  -------      offset =  -------------
659                        S2 - S1                   S2 - S1
660
661
662
663   Voltage Sensor Corrections
664       You  need  to  read  this section only if you think the default voltage
665       correction factors and offsets are incorrect.  For Linux and lm_sensors
666       and sysfs sensors
667        this  would  be  if gkrellm does not know about your particular sensor
668       chip.  For MBM with Windows, the default values should be correct.
669
670       Motherboard voltage measurements are made by a variety of sensor  chips
671       which  are  capable of measuring a small positive voltage.  GKrellM can
672       display these voltage values and can apply a correction factor, offset,
673       and  for  the  negative voltages of some chips (lm80), a level shifting
674       reference voltage to the displayed voltage.  There are  four  cases  to
675       consider:
676
677       1 ·    Low  valued  positive  voltages may be directly connected to the
678              input pins of the sensor chip and therefore need no  correction.
679              For  these,  the  correction factor should be 1.0 and the offset
680              should be 0.
681
682       2 ·    Higher valued positive voltages will be connected to  the  input
683              pins  of  the  sensor chip through a 2 resistor attenuation cir‐
684              cuit.  For these, the correction factor will be a ratio  of  the
685              resistor values and the offset will be 0.
686
687       3 ·    Negative  voltages  will  be  connected to the input pins of the
688              sensor through a 2 resistor attenuation circuit with one of  the
689              resistors  connected  to  a positive voltage to effect a voltage
690              level shift.  For these (lm80), the correction factor and offset
691              will  be  ratios of the resistor values, and a reference voltage
692              must be used.
693
694       4 ·    Some sensor chips (w83782, lm78) are designed to handle negative
695              inputs  without requiring an input resistor connected to a volt‐
696              age reference.  For these, there will be a correction factor and
697              a possible offset.
698
699              For cases 2 and 3, the sensor chip input network looks like:
700
701                  Vs o----/\/\/---o-------------o Vin
702                           R1     |
703                                  o--/\/\/--o Vref
704                                      R2
705
706       where,
707
708              Vs     is the motherboard voltage under measurement
709
710              Vin    is  the  voltage  at the input pin of the sensor chip and
711                     therefore is the voltage reading that will  need  correc‐
712                     tion.
713
714              Vref   is  a level shifting voltage reference.  For case 2, Vref
715                     is ground or zero.  For case 3, Vref will be one  of  the
716                     positive motherboard voltages.
717
718       The  problem  then  is  to  compute correction factors and offsets as a
719       function of R1 and R2 so that GKrellM can display  a  computed  mother‐
720       board voltage Vs as a function of a measured voltage Vin.
721
722       Since  sensor chip input pins are high impedance, current into the pins
723       may be assumed to be zero.  In that case, the current through R1 equals
724       current through R2, and we have:
725
726                  (Vs - Vin)/R1 = (Vin - Vref)/R2
727
728              Solving for Vs as a function of Vin:
729
730                  Vs = Vin * (1 + R1/R2)  -  (R1/R2) * Vref
731
732              So, the correction factor is:  1 + R1/R2
733                  the correction offset is:  - (R1/R2)
734                  Vref is specified in the config separately from
735                  the offset (for chips that need it).
736
737
738       Fortunately  there  seems  to be a standard set of resistor values used
739       for the various sensor chips which are documented in the lm_sensor doc‐
740       umentation.   The GKrellM sensor corrections are similar to the compute
741       lines you find with lm_sensors, with the difference that lm_sensors has
742       an  expression  evaluator  which does not require that compute lines be
743       simplified to the single factor and offset required  by  GKrellM.   But
744       you  can  easily  calculate  the  factor and offset.  For example, this
745       lm_sensor compute line for a case 2 voltage:
746
747                  compute in3 ((6.8/10)+1)*@ ,  @/((6.8/10)+1)
748
749
750       yields a correction factor of ((6.8/10)+1) =  1.68  and  an  offset  of
751       zero.
752
753       Note that the second compute line expression is not relevant in GKrellM
754       because there is never any need to invert the voltage reading  calcula‐
755       tion.  Also, the compute line '@' symbol represents the Vin voltage.
756
757       A more complicated compute line for a case 3 voltage:
758
759                  compute in5 (160/35.7)*(@ - in0) + @, ...
760
761              can be rewritten:
762
763                  compute in5 (1 + 160/35.7)*@ - (160/35.7)*in0, ...
764
765              so the correction factor is  (1 + 160/35.7) = 5.48
766              and the correction offset is -(160/35.7) = -4.48
767              and the voltage reference Vref is in0
768
769       Here is a table of correction factors and offsets based on some typical
770       compute line entries from /etc/sensors.conf:
771
772                     Compute line                 Factor  Offset  Vref
773                     -------------------------------------------------
774              lm80   in0 (24/14.7 + 1) * @        2.633     0       -
775                     in2 (22.1/30 + 1) * @        1.737     0       -
776                     in3 (2.8/1.9) * @            1.474     0       -
777                     in4 (160/30.1 + 1) * @       6.316     0       -
778                     in5 (160/35.7)*(@-in0) + @   5.482    -4.482  in0
779                     in6 (36/16.2)*(@-in0) + @    3.222    -2.222  in0
780
781              LM78   in3 ((6.8/10)+1)*@           1.68      0       -
782                     in4 ((28/10)+1)*@            3.8       0       -
783                     in5 -(210/60.4)*@           -3.477     0       -
784                     in6 -(90.9/60.4)*@          -1.505     0       -
785
786              w83782 in5 (5.14 * @) - 14.91       5.14    -14.91    -
787                     in6 (3.14 * @) -  7.71       3.14     -7.71    -
788
789
790
791   Command launching
792       Many monitors can be set up to launch a command when you click  on  the
793       monitor  label.   When a command is configured for a monitor, its label
794       is converted into a button which becomes visible when the mouse  enters
795       the panel or meter area of the label.  If the command is a console com‐
796       mand (doesn't have a graphical user interface), then the  command  must
797       be  run  in  a terminal window such as xterm, eterm, or Gnome terminal.
798       For example running the "top" command would take:
799
800       xterm -e top
801
802       You can use the command launching feature to run  commands  related  to
803       monitoring functions, or you may use it to have a convenient launch for
804       any command.  Since gkrellm is usually made sticky, you can  have  easy
805       access  to  several frequently used commands from any desktop.  This is
806       intended to be a convenience and  a  way  to  maximize  utilization  of
807       screen real estate and not a replacement for more full featured command
808       launching from desktops such as Gnome or KDE or  others.   Some  launch
809       ideas for some monitors could be:
810
811       calendar:
812              gnomecal, evolution, or ical
813
814       CPU:   xterm -e top or gps or gtop
815
816       inet:  gftp or xterm -e ftpwho
817
818       net:   mozilla, galeon, skipstone, or xterm -e slrn -C-
819
820       And so on... Tooltips can be set up for these commands.
821
822
823   Alerts
824       Most  monitors  can  have alerts configured to give warnings and alarms
825       for data readings which range outside of  configurable  limits.   Where
826       useful,  a  delay of the alert trigger can be configured.  A warning or
827       alarm consists of an attention grabbing decal appearing and an optional
828       command  being executed.  For most monitors the command may contain the
829       same substitution variables which are  available  for  display  in  the
830       chart or panel label format strings and are documented on configuration
831       Info pages.  Additionally, the hostname may be embedded in the  command
832       with the $H substitution variable.
833
834       If you have festival installed, either a warn or alarm command could be
835       configured to speak something.  For example  a  CPU  temperature  alert
836       warn command could just speak the current temperature with:
837
838           sh -c "echo warning C P U is at $s degrees | esddsp festival --tts"
839
840       Assuming you have esd running.
841
842

THEMES

844       A  theme is a directory containing image files and a gkrellmrc configu‐
845       ration file.  The theme directory may be  installed  in  several  loca‐
846       tions:
847
848              ~/.gkrellm2/themes
849              /usr/local/share/gkrellm2/themes
850              /usr/share/gkrellm2/themes
851
852       For  compatibility  with  Gtk  themes,  a  gkrellm  theme  may  also be
853       installed as:
854
855              ~/.themes/THEME_NAME/gkrellm2
856              /usr/share/themes/THEME_NAME/gkrellm2
857
858       Finally, a theme you simply want to check out can be untarred  anywhere
859       and used by running:
860
861              gkrellm -t path_to_theme
862
863       If  you  are  interested  in  writing a theme, go to the Themes page at
864       http://www.gkrellm.net and there you will find a  Theme  making  refer‐
865       ence.
866
867
868

PLUGINS

870       gkrellm  tries  to load all plugins (shared object files ending in .so)
871       it finds in your plugin directory ~/.gkrellm2/plugins.  The directories
872       /usr/local/lib64/gkrellm2/plugins  and  /usr/lib64/gkrellm2/plugins are
873       also searched for plugins to install.
874
875       Some plugins may be available only as source files and they  will  have
876       to  be  compiled before installation.  There should be instructions for
877       doing this with each plugin that comes in source form.
878
879       If you are interested in writing a plugin, go to the  Plugins  page  at
880       http://www.gkrellm.net  and  there  you  will find a Plugin programmers
881       reference.
882
883
884

CLIENT/SERVER

886       When a local gkrellm runs in client  mode  and  connects  to  a  remote
887       gkrellmd  server  all  builtin  monitors  collect  their  data from the
888       server.  However, the client gkrellm process is running  on  the  local
889       machine, so any enabled plugins will run in the local context (Flynn is
890       an exception to this since it derives its data  from  the  builtin  CPU
891       monitor).   Also,  any command launching will run commands on the local
892       machine.
893
894

FILES

896       ~/.gkrellm2
897              User gkrellm directory where are  located  configuration  files,
898              user's plugins and user's themes.
899
900       ~/.gkrellm2/plugins
901              User plugin directory.
902
903       /usr/lib64/gkrellm2/plugins
904              System wide plugin directory.
905
906       /usr/local/lib64/gkrellm2/plugins
907              Local plugin directory.
908
909       ~/.gkrellm2/themes
910              User theme directory.
911
912       ~/.themes/THEME_NAME/gkrellm2
913              User theme packaged as part of a user Gtk theme.
914
915       /usr/share/gkrellm2/themes
916              System wide theme directory.
917
918       /usr/local/share/gkrellm2/themes
919              Local theme directory.
920
921       /usr/share/themes/THEME_NAME/gkrellm2
922              System wide theme packaged as part of a system wide Gtk theme.
923
924

AUTHORS

926       This  manual  page  was  written  by  Bill  Wilson <billw@gkrellm.net>.
927       http://www.gkrellm.net/
928
929

SEE ALSO

931       fstab(5), sudo(1), mount(8), pppd(8), umount(8)
932
933
934
935GNU/Linux                        Jul 25, 2019                       gkrellm(1)
Impressum