File: gkrellm.1

package info (click to toggle)
gkrellm 2.3.10-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 4,828 kB
  • sloc: ansic: 58,390; makefile: 665; sh: 270
file content (1247 lines) | stat: -rw-r--r-- 38,383 bytes parent folder | download | duplicates (3)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
.TH gkrellm 1 "Oct 14, 2014" "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.  Using libsensors is the preferred interface on Linux since it is
the only interface that will be up to date on supporting correct voltage
scaling factors and offsets for recent sensor chips.
.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)