Debian Codegraph @

prog/sensord/sensord.8

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