root/lm-sensors/trunk/prog/sensord/sensord.8 @ 5737

Revision 5737, 12.6 KB (checked in by khali, 6 years ago)

Use the "daemon" logging facility instead of "local4" by default.
Local facilities are meant for local uses, no daemon should use it by
default.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1.\" Copyright 1999-2002 Merlin Hughes <merlin@merlin.org>
2.\" sensord is distributed under the GPL
3.\"
4.\" Permission is granted to make and distribute verbatim copies of this
5.\" manual provided the copyright notice and this permission notice are
6.\" preserved on all copies.
7.\"
8.\" Permission is granted to copy and distribute modified versions of this
9.\" manual under the conditions for verbatim copying, provided that the
10.\" entire resulting derived work is distributed under the terms of a
11.\" permission notice identical to this one
12.\"
13.\" Since the Linux kernel and libraries are constantly changing, this
14.\" manual page may be incorrect or out-of-date.  The author(s) assume no
15.\" responsibility for errors or omissions, or for damages resulting from
16.\" the use of the information contained herein.  The author(s) may not
17.\" have taken the same level of care in the production of this manual,
18.\" which is licensed free of charge, as they might when working
19.\" professionally.
20.\"
21.\" Formatted or processed versions of this manual, if unaccompanied by
22.\" the source, must acknowledge the copyright and authors of this work.
23.\"
24.TH sensord 8  "October 2007" "lm-sensors 3" "Linux System Administration"
25.SH NAME
26sensord \- Sensor information logging daemon.
27.SH SYNOPSIS
28.B sensord [
29.I options
30.B ] [
31.I chips
32.B ]
33
34.SH DESCRIPTION
35.B Sensord
36is a daemon that can be used to periodically log sensor readings from
37hardware health-monitoring chips to
38.BR syslog (3)
39or a round-robin database (RRD)
40and to alert when a sensor alarm is signalled; for example, if a
41fan fails, a temperature limit is exceeded, etc.
42
43.SH OPTIONS
44.IP "-i, --interval time"
45Specify the interval between scanning for sensor alarms; the default is to
46scan every minute.
47
48The time should be specified as a raw integer (seconds) or with a suffix
49`s' for seconds, `m' for minutes or `h' for hours; for example, the
50default interval is `60' or `1m'.
51
52Specify an interval of zero to suppress scanning explicitly for alarms.
53.IP "-l, --log-interval time"
54Specify the interval between logging all sensor readings; the default is
55to log all readings every half hour.
56
57The time is specified as before; e.g., `30m'.
58
59Specify an interval of zero to suppress logging of regular sensor
60readings.
61.IP "-t, --rrd-interval time"
62Specify the interval between logging all sensor readings to a round-robin
63database; the default is to log all readings every five minutes
64.B if
65a round-robin database is configured.
66
67The time is specified as before; e.g., `5m'.
68.IP "-T, --rrd-no-average"
69Specify that the round-robin database should not be averaged.
70
71.IP "-r, --rrd-file file"
72Specify a round-robin database into which to log all sensor readings;
73e.g., `/var/log/sensord.rrd'. This database will be created if it does
74not exist. By default, no round-robin database is used.
75
76See the section
77.B ROUND ROBIN DATABASES
78below for more details.
79.IP "-c, --config-file file"
80Specify a
81.BR libsensors (3)
82configuration file. If no file is specified, the libsensors default
83configuration file is used.
84
85.IP "-p, --pid-file file"
86Specify what PID file to write; the default is to write the file
87`/var/run/sensord.pid'. You should always specify an absolute path
88here. The file is removed when the daemon exits.
89.IP "-f, --syslog-facility facility"
90Specify the
91.BR syslog (3)
92facility to use when logging sensor readings and alarms; the default is
93to use
94.IR daemon .
95
96Other possible facilities include
97.IR local0
98through
99.IR local7 ,
100and
101.IR user .
102.IP "-g, --rrd-cgi directory"
103Prints out a sample
104.BR rrdcgi (1)
105CGI script that can be used to display graphs of recent sensor information
106in a Web page, and exits. You must specify the world-writable, Web-accessible
107directory where the graphs should be stored; the CGI script assumes that
108this will be accessed under the `/sensord/' directory on the Webserver. See
109the section
110.B ROUND ROBIN DATABASES
111below for more details.
112.IP "-a, --load-average"
113Include the load average in the RRD database. You should
114also specify this flag when you create the CGI script.
115.IP "-d, --debug"
116Prints a small amount of additional debugging information.
117.IP "-h, --help"
118Prints a help message and exits.
119.IP "-v, --version"
120Displays the program version and exits.
121.SH CHIPS
122To restrict the devices that are scanned by this daemon, you may
123optionally specify a list of chip names. By default, all available
124chips are scanned.
125
126A typical chip name would be `w83782d-*' (you may want to escape the
127`*' for your shell) which would scan any W83782D chips on any bus. See
128.BR sensors.conf (5)
129for more details. Another option is to simply not load the sensor
130modules for chips in which you have no interest.
131.SH SIGNALS
132Upon receipt of a SIGTERM (see
133.BR signal (7)
134for details) this daemon should gracefully shut down.
135
136Upon receipt of a SIGHUP, this daemon will rescan the kernel interface
137for chips and features, and reload the libsensors configuration file.
138.SH LOGGING
139All messages from this daemon are logged to
140.BR syslog (3)
141under the program name `sensord' and facility
142.IR daemon ,
143or whatever is specified on the command line.
144
145Regular sensor readings are logged at the level
146.IR info .
147Alarms are logged at the level
148.IR alert .
149Inconsequential status messages are logged at
150the minimum level,
151.IR debug ,
152when debugging is enabled.
153
154You can use an appropriate `/etc/syslog.conf'
155file to direct these messages in a useful manner. See
156.BR syslog.conf (5)
157for full details. Assuming you set the logging facility to local4,
158the following is a sample configuration:
159.IP
160.nf
161# Sample syslog.conf entries
162*.info;...;local4.none;local4.warn  /var/log/messages
163local4.info                        -/var/log/sensors
164local4.alert                        /dev/console
165local4.alert                        *
166.fi
167.PP
168The first line ensures that regular sensor readings do not clutter
169`/var/log/messages'; we first say `local4.none' to eliminate
170informational messages; then `local4.warn' to enable warnings and
171above. The second line says to log all regular sensor readings to
172`/var/log/sensors'; the leading hyphen `-' means that this file
173is not flushed after every message. The final two lines ensure
174that alarms are printed to the system console as well as
175to all connected users (in addition to `/var/log/messages' and
176`/var/log/sensors').
177.SH LOG ROTATION
178On a typical system with a good sensor chip, expect about 2KB per sensor
179reading in the log file. This works out at about 3MB per month. You
180should be rotating your syslog files anyway, but just to be sure you'll
181want to use something like
182.BR logrotate (8)
183or equivalent. You might, for example, want an entry in
184`/etc/logrotate.d/syslog' containing:
185.IP
186.nf
187# Sample logrotate.d entry
188/var/log/sensors {
189    postrotate
190        /usr/sbin/killall -HUP syslogd
191    endscript
192}
193.fi
194.PP
195Note, of course, that you want to restart
196.BR syslogd (8)
197and not
198.BR sensord (8)
199.
200.SH ALARMS
201Alarms generally indicate a critical condition; for example, a fan
202failure or an unacceptable temperature or voltage. However, some
203sensor chips do not support alarms, while others are incorrectly
204configured and may signal alarms incorrectly.
205
206Note that some drivers may lack support for alarm reporting
207even though the chips they support do have alarms. As of Linux 2.6.23,
208many drivers still don't report alarms in a format suitable for
209libsensors 3.
210
211.SH BEEPS
212If you see `(beep)' beside any sensor reading, that just means that
213your system is configured to issue an audio warning from the
214motherboard if an alarm is signalled on that sensor.
215.SH ROUND ROBIN DATABASES
216.BR Sensord (8)
217provides support for storing sensor readings in a round-robin
218database. This may be a useful alternative to the use of
219.BR syslog (3).
220
221Round-robin databases are
222constant-size databases that can be used to store, for example,
223a week's worth of sensor readings. Subsequent readings stored
224in the database will overwrite readings that are over a week
225old. This capability is extremely useful because it allows
226useful information to be stored in an easily-accessible
227manner for a useful length of time, without the burden of
228ever-growing log files.
229
230The
231.BR rrdtool (1)
232utility and its associated library provide the basic framework for
233the round-robin database beneath
234.BR sensord (8).
235In addition, the
236.BR rrdcgi (1)
237and
238.BR rrdgraph (1)
239utilities provide support for generating graphs of these data for
240display in a Web page.
241
242If you wish to use the default configuration of round-robin
243database, which holds one week of sensor readings at five-minute
244intervals, then simply start
245.BR sensord (8)
246and specify where you want the database stored. It will automatically
247be created and configured using these default parameters.
248
249If you wish readings to be stored for a longer period, or want multiple
250readings to be averaged into each database entry, then you must
251manually create and configure the database before starting
252.BR sensord (8).
253Consult the
254.BR rrdcreate (1)
255manual for details. Note that the database must match exactly the
256names and order of sensors read by
257.BR sensord (8).
258It is recommended that you create the default database and then use
259.BR rrdinfo (1)
260to obtain this information, and/or
261.BR rrdtune (1)
262to change it.
263
264After creating the round-robin database, you must then configure
265your Web server to display the sensor information. This assumes that
266you have a Web server preconfigured and functioning on your machine.
267.BR Sensord (8)
268provides a command-line option
269.BR --rrd-cgi
270to generate a basic CGI script to
271display these graphs; you can then customize this script as desired.
272Consult the
273.BR rrdcgi (1)
274manual for details. This CGI script requires a world-writable, Web-accessible
275directory into which to write the graphs that it generates.
276
277An example of how to set up Web-accessible graphs of recent sensor readings
278follows:
279.IP
280.nf
281sensord --log-interval 0 \\
282  --load-average \\
283  --rrd-file /var/log/sensord.rrd
284.fi
285.PP
286Here, we start
287.BR sensord (8)
288and configure it to store readings in a round-robin database; note
289that we disable logging of sensor readings to
290.BR syslog (3),
291and enable logging of the load average.
292.IP
293.nf
294mkdir /var/www/sensord
295chown www-data:staff /var/www/sensord
296chmod a=rwxs /var/www/sensord
297.fi
298.PP
299Here, we create a world-writable, Web-accessible directory in which
300graphs will be stored; we set the ownership and permissions on this
301directory appropriately. You will have to determine the location and
302ownership that is appropriate for your machine.
303.IP
304.nf
305sensord --load-average \\
306  --rrd-file /var/log/sensord.rrd \\
307  --rrd-cgi /var/www/sensord \\
308  > /usr/lib/cgi-bin/sensord.cgi
309chmod a+rx /usr/lib/cgi-bin/sensord.cgi
310.fi
311.PP
312Here, we create
313a CGI script that will display sensor readings from the database.
314You must specify the location of the round-robin database, the
315location of the directory where the images should be stored,
316and whether you want the load average displayed. The
317.BR --rrd-cgi
318command-line parameter causes
319.BR sensord (8)
320to display a suitable CGI script on
321.BR stdout
322and then to exit. You will need to write this script to the CGI
323bin directory of your Web server,
324and edit the script if the image directory you chose is not the
325`/sensord/' directory of your Web server.
326
327Finally, you should be able to view your sensor readings from
328the URL `http://localhost/cgi-bin/sensord.cgi'.
329.SH MODULES
330It is expected that all required sensor modules are loaded prior to
331this daemon being started. This can either be achieved with a system
332specific module loading scheme (e.g., listing the required modules
333in the file `/etc/modules' under Debian) or with explicit
334.BR modprobe (1)
335commands in an init script before loading the daemon.
336
337For example, a `sensord' initialization script might
338contain (among others) the following commands:
339.IP
340.nf
341# Sample init.d scriptlet
342echo -n "Loading AMD756 module: "
343modprobe i2c-amd756 || { echo Fail. ; exit 1 ; }
344echo OK.
345echo -n "Loading W83781D module: "
346modprobe w83781d || { echo Fail. ; exit 1 ; }
347echo OK.
348echo -n "Starting sensord: "
349daemon sensord
350...
351.fi
352.PP
353Ignore the platform-specific shell functions; the general idea
354should be fairly clear.
355.SH ERRORS
356Errors encountered by this daemon are logged to
357.BR syslogd (8)
358after which the daemon will exit.
359.SH BUGS
360Round-robin database support doesn't cope with
361multiple sensor chips having duplicate sensor labels.
362.SH FILES
363.I /etc/sensors3.conf
364.br
365.I /etc/sensors.conf
366.RS
367The system-wide
368.BR libsensors (3)
369configuration file. See
370.BR sensors.conf (5)
371for further details.
372.RE
373.I /etc/syslog.conf
374.RS
375The system-wide
376.BR syslog (3)
377/
378.BR syslogd (8)
379configuration file. See
380.BR syslog.conf (5)
381for further details.
382.RE
383
384.SH SEE ALSO
385sensors.conf(5)
386.SH AUTHORS
387.B Sensord
388was written by Merlin Hughes <merlin@merlin.org>. Basics of round-robin
389databases were misappropriated from Mark D. Studebaker.
Note: See TracBrowser for help on using the browser.