Debian Codegraph @

Install/avr-evtd.8

raw ◀ ▶
Source reconstructed at patch state 1 of 2 — not the installed (fully patched) source.
2 Debian patches touch this file
1 .TH AVR-EVTD 8 "28 Aug 2009"
2
3 .SH NAME
4
5 avr-evtd - Linkstation AVR Event daemon
6
7 .SH SYNOPSIS
8
9 avr-evtd [
10 .B -d
11 .IR /dev/tty
12 ] [i | c | v]
13
14 .SH DESCRIPTION
15
16 .IR avr-evtd
17 is a simple and small user space interface to the Linkstation AVR
18 micro-controller. It doesn't have a lot of special features, but it's
19 main task is to provide 'keep-alive' messages to the Linkstation's
20 on-board AVR device. This device controls/monitors the fan, various
21 LEDs, timed power up and two buttons. This daemon provides the
22 necessary initialization to the device and also stimulates the LEDs
23 depending on various fault conditions. It also monitors a power button
24 (located at the front) and a reset button (located at the rear).
25
26 .IR avr-evtd
27 searches for a configuration file located within
28 .B /etc/melco
29 at start-up time. If this file does not exist, then
30 .IR avr-evtd
31 reverts to reading the file located at
32 .B /etc/default/avr-evtd.
33 Additionally,
34 .IR avr-evtd
35 may, if requested, periodically check the root (\fBUnder user control
36 and could be /dev/hda1\fP) partition and the user working partition
37 (\fBFor example, /dev/hda3\fP) to ensure they are mounted. Also, if
38 requested, it will determine if sufficient space remains and if not then
39 the AVR is requested to illuminate the DISK LED. This periodic checking
40 also takes place on the configuration files. If they are deemed to have
41 been updated, then the daemon will respond accordingly.
42 .LP
43 Any failures are normally routed through the log files. With timed
44 shutdown/power up, a warning will be broadcast to all users (console
45 message) when within 5 or less minutes of power off. Also, fan failure
46 alerts will be broadcast in this fashion. Failure to determine mounted
47 .B working
48 partition will result in the DIAG LED flashing three times, repeatedly.
49 .LP
50 A new feature of this daemon is the ability to code events for single or
51 groups of days. This allows the user to add any number of power-on/off
52 events as required. This also has the added benefit of being able to
53 shut down the device for longer periods. The internal AVR timer has a
54 12-bit resolution timer which can power up the Linkstation from a
55 maximum of a sixty eight hour sleep: from time of invocation. The AVR
56 is updated again at time of power down/shutdown to re-validate the
57 timer, in case of time updates (either by user or NTP). This will also
58 preserve the 68 hour sleep resolution.
59
60 .SH OPTIONS
61
62 .TP 5
63 .B -d
64 .IR /dev/tty
65 Specifies the UART device used to communicate with the AVR. This is
66 normally taken care of by the scripts but can be specified in the
67 configuration file.
68 .B See below for details.
69
70 .TP 5
71 .B -c
72 Don't fork, i.e. run in the foreground (debug use only).
73
74 .TP
75 .B -i
76 Returns the port memory location for the device specified by
77 .B -d
78 .IR /dev/tty
79
80 .TP 5
81 .B -v
82 Display daemon version.
83
84 .SH THE CONFIGURATION FILE
85
86 The
87 .IR avr-evtd
88 configuration file is the fallback file in the event that the stock
89 melco files do not exist. The file is read at initial start-up in order
90 to determine if timed shutdown is required and if the disk usage is to
91 be monitored. The file should be always located within the /etc/default
92 directory and a sample file is provided. The file format is similar to
93 other Unix configuration files - comments begin with a # character and
94 extend to the end of the line; blank lines are ignored. Configuration
95 commands consist of an initial keyword followed by an argument.
96 Arguments may be strings or times written in HH:MM (UTC) format.
97 Optional arguments are delimited by [ ] in the following descriptions,
98 while alternatives are separated by |.
99
100 .TP 5
101
102 .IR DEBUG
103 [ON | OFF]
104
105 This is reserved for admin only. Allows logging of certain information.
106 A log file will be maintained in /etc/avr-evtd logging events and when
107 run from command line, the process will log data to the console.
108
109 .TP 5
110
111 .IR TIMER
112 [YES | NO]
113
114 The timer command informs the daemon if it has to provide time
115 controlled shutdown and power up. If
116 .IR TIMER
117 is set to
118 .B NO
119 then this function is not available and the commands
120 .IR SHUTDOWN
121 and
122 .IR POWERON
123 are ignored and have no effect. The same applies if any day events are
124 specified and the
125 .IR TIMER
126 is set to
127 .B NO
128 then these events will also be ignored.
129
130 .TP 5
131
132 .IR DEVICE
133 [/dev/tty]
134
135 This informs the AVR which UART to use when communicating with the AVR.
136 The communication path between the micro-controller and this daemon is
137 via a serial link. This keyword is not for general use and is provided
138 to allow advanced users the option of overriding automatic
139 configuration. This would normally be set to /dev/ttyS1 but on some
140 systems it is /dev/ttyS0. The selection of the correct port is
141 performed by the daemon start script and is not normally required to be
142 altered.
143
144 .TP 5
145
146 .IR [<day> | <day>-<day>]
147 [ON=HH:MM | ON= | OFF=HH:MM | OFF=]
148
149 This defines events for either a single day or group of days, '-'
150 separator. Any number of
151 .B ON
152 and
153 .B OFF
154 events can be specified and can be extended over additional lines. <day>
155 can be any number of days of the week specified as either SUN, MON, TUE,
156 WED, THR, FRI, and SAT. For example:
157
158 .RS 15
159 .B MON-WED=ON=09:00,OFF=23:00
160 .RE
161 .RS 15
162 .B THR=ON=09:00
163 .RE
164 .RS 15
165 .B FRI=OFF=01:00
166 .RE
167
168 .RS 5
169 In this example, the first power on event is Monday at 09:00. At 23:00
170 the Linkstation will power down. This is repeated for Tuesday and
171 Wednesday. On Thursday, the Linkstation will power on at 09:00 and will
172 power off on Friday at 01:00. The unit will then remain off for
173 Saturday and Sunday and not power up again till 09:00 on Monday. The
174 unit is capable of sleeping for no more than 68 hours (due to the
175 resolution of the internal timer). Again, this time MUST be specified
176 in UTC format and follow HH:MM.
177 .LP
178 Five minutes before power off is required, a message is broadcast to all
179 console users. At shutdown, an event message is sent to the event
180 script.
181 .B See below for more details.
182
183 .RE
184
185 .TP 5
186
187 .IR SHUTDOWN
188 [HH:MM]
189
190 This specifies the time that the Linkstation will be powered down. This
191 time MUST be specified in UTC and must follow the format HH:MM. If the
192 user alters this configuration file whilst the daemon is running, then
193 the change will be seen and the new settings will be implemented. If
194 the new time entered is passed the current time, then the shutdown time
195 will be for the following day. If single or multiple day events are
196 specified, then this becomes the default power down time for any
197 undefined days.
198
199 .TP 5
200
201 .IR POWERON
202 [HH:MM]
203
204 This specifies the time that the Linkstation will be automatically
205 powered up; as long as now unexpected power outage occurs. Again, if
206 this time is less than the
207 .IR SHUTDOWN
208 time then it is for the following day. Both the
209 .IR TIMER
210 set to ON and the
211 .IR SHUTDOWN
212 and the
213 .IR POWERON
214 times are valid will timed shutdown/power up be enabled. This will be
215 reported in the message log along with any errors in the configuration
216 file.
217
218 .RS 5
219 If single or multiple day events are specified, then this becomes the
220 default power on time for any undefined days.
221 .RE
222
223 .TP 5
224
225 .IR DISKCHECK
226 [OFF | 0..100]
227
228 If this is set to OFF or 0 (zero) then disk usage/monitoring is
229 disabled. Set to a value between 0 and 100% to monitor disk usage. If
230 disk usage is above this specified value, then the DISK LED will be
231 illuminated. At the same time, a disk full event message will be sent
232 to the event script.
233
234 .TP 5
235
236 .IR ROOT
237 [hda1..9]
238
239 No default. This allows the root partition to be defined by the user.
240 No syntax checking is performed on this entry or validation of the
241 partition ID.
242
243 .TP 5
244
245 .IR WORK
246 [hda1..9]
247
248 No default. This allows the working partition to be defined by the
249 user. Again, no syntax checking is performed on this entry or
250 validation of the partition ID.
251
252 .TP 5
253
254 .IR REFRESH
255 [1..300]
256
257 This defaults to 40. This provides control over the rate (in seconds)
258 that the daemon checks the system for changes and refreshes the AVR.
259 Any number between 1 and 300 can be entered. Anything less than the
260 default will result in higher impact on the system: more CPU usage.
261 Higher times will result with slower response to configuration file
262 changes but this may not be an issue with most users.
263
264 .TP 5
265
266 .IR HOLD
267 [1..9]
268
269 This defaults to 3. This provides control over the time (in seconds)
270 that the user needs to hold either the reset of the power button in for
271 a reset event (reset button) or power off event (power button).
272
273 .TP 5
274
275 .IR DISKNAG
276 [ON | OFF]
277
278 Default if off. This provides the user control over the disk full
279 event. The default is that once detected, just a single event is
280 triggered. If required, setting this to on will generate repeated
281 events, at the frequency of
282 .B REFRESH
283 until the disk is no longer deemed full.
284
285 .TP 5
286 .IR FANSTOP
287 [OFF | 0..60]
288
289 Default is 30 seconds. This is the time, from report of fan failure in
290 which the daemon will generate a fan failure event call to the event
291 script. This allows the user to act accordingly. At present, the
292 script is setup to power down. This can be changed to an e-mail event
293 prior to shutdown if required.
294
295 Otherwise, if a user has decided to remove the fan then this can be set
296 to OFF to prevent shutdown from occuring. It must be stressed that
297 alternative cooling must be sourced if this option is selected.
298
299 .SH BUTTON OPERATION
300
301 All events, whether mechanical button operation, or software
302 reset/shutdown actions are routed through an event script located at
303 .B /etc/avr-evtd/EventSCript
304
305 .TP 5
306
307 .IR POWER
308 On press, a button event message is sent. On release, another event
309 message is sent. If the button is held in for more than
310 .B HOLD
311 seconds, then a shutdown event request is sent. If the button is
312 pressed twice within a period of one second, then a reset request event
313 is sent.
314 .RS 5
315
316 If the power button is pressed during the five minute timed shutdown
317 warning, then the shutdown time is increased by five minutes. Multiple
318 presses will keep increasing the time by five minutes (to a maximum
319 pause of fifty minutes). This provides the user with the ability to
320 carry on working before timed shutdown is finally activated; careful
321 here as repeated presses maybe seen as a reboot request.
322 .RE
323 .TP 5
324
325 .IR RESET
326 On press, a button event message is sent. On release, another event
327 message is sent. If the button is held in for more than twenty seconds,
328 then a EM-Mode event request is sent. If the button is pressed twice
329 within a period of one second, then a
330 .I special
331 event is sent which in the default state will launch the telnet daemon.
332
333 .SH MESSAGE EVENTS
334
335 The event system has been modified such that 99% of the daemon event
336 system is pushed through the event script. A third parameter is
337 supplied by the daemon out to the script detailing information relevant
338 to the generated message. For example, for a disk full message, the
339 third parameter would detail the percentage disk space used (worst of
340 the two monitored partitions) and when this is cleared, then this
341 parameter would be cleared to zero.
342
343 .TP 5
344
345 .IR 0
346 User has requested (by double press of reset button) to, with the first
347 press, launch the telnet daemon, or other client as specified in the
348 .IR EventScript.
349 The script also establishes a static IP to an alias Ethernet device :EM
350 at 192.168.11.150. If this IP is already in-use, then it will not be
351 created. If the Ethernet is not running, then an alternative Ethernet
352 configuration file is loaded providing a static IP at 192.168.11.150.
353 and also a DHCP provided IP. On the
354 .IR THIRD
355 double press, then a known set of group and user password files are
356 copied to /etc. Prior to the transfer, the relevant original files are
357 copied to
358 .IR .em.
359 A file, recovery.tar, is extracted and the LEDs are flashed to indicate
360 this new mode. A user can now gain root access using the password
361 .I emergency
362 and gain access via the telnet port 1234 to their box.
363
364 .TP 5
365
366 .IR 1
367 AVR micro-controller has requested a reset.
368
369 .TP 5
370
371 .IR 2
372 Shutdown request from the shutdown timer event.
373
374 .TP 5
375
376 .IR 3
377 Power button has been released event.
378
379 .TP 5
380
381 .IR 4
382 Power button has been pressed event.
383
384 .TP 5
385
386 .IR 5
387 Reset button (rear of unit) has been released.
388
389 .TP 5
390
391 .IR 6
392 Reset button has been pressed.
393
394 .TP 5
395
396 .IR 7
397 User has requested (by holding power button for more than
398 .B HOLD
399 seconds) to shutdown the unit.
400
401 .TP 5
402
403 .IR 8
404 User has requested (by double press of the power button) to reset the
405 unit.
406
407 .TP 5
408
409 .IR 9
410 Disk usage greater than DISKCHECK. Parameter 3 set to percentage used
411 or zero.
412
413 .TP 5
414
415 .IR F
416 Fan has been stationary for FANSTOP seconds. Parameter 3 is set to 4
417 when cleared.
418
419 .TP 5
420
421 .IR E
422 EM-Mode has been selected. The EM-Mode sequence is written to the
423 desired flash location and the system is issued a reboot request.
424 EM-Mode is an emergency boot mode that for the Linkstation it boots from
425 an image in flash and rebuilds files on the disk.
426 .B This should only be used by those who know what will happen to their
427 disks when this Mode is selected
428
429 .TP 5
430
431 .IR S
432 The system will shutdown in less than five minutes warning. Parameter 3
433 indicates shutdown delay on power press.
434
435 .TP 5
436
437 .IR D
438 Error message handler. Parameter 3 indicates error number.
439
440 .SH ERROR CODES
441
442 The following error messages maybe displayed in the log files during
443 operation:
444
445 .TP 5
446
447 .IR 1
448 No stock or avr-evtd configuration files were located.
449
450 .TP 5
451
452 .IR 2
453 Power off time greater than that supported by the AVR. As this is
454 calculated at the time the timer is established, this fault may clear at
455 shutdown as timers are re-validated.
456
457 .TP 5
458
459 .IR 3
460 Timer declaration error in /etc/default/avr-evtd configuration file
461
462 .TP 5
463
464 .IR 4
465 Error in stock configuration file
466
467 .SH FILES
468
469 .RS 0
470 .IR /etc/default/avr-evtd
471 .RE
472 .RS 0
473 .IR /etc/avr-evtd/EventScript
474 .RE
475 .RS 0
476 .IR /etc/avr-evtd/emergency-eth0
477 .RE
478 .RS 0
479 .IR /etc/default/events.log
480 .RE
481 .RS 0
482 .IR /etc/avr-evtd/recovery.tar
483 .RE
484
485 .SH AUTHORS
486
487 Bob Perry <[email protected]> (2006), with some modifications
488 by Rog\['e]rio Theodoro de Brito <[email protected]> (2008,
489 2009).
490
491 .SH COPYRIGHT
492
493 This program is free software; you can redistribute it and/or modify it
494 under the terms of the GNU General Public License as published by the
495 Free Software Foundation; either version 2 of the License, or (at your
496 option) any later version.
497 .LP
498 This program is distributed in the hope that it will be useful, but
499 WITHOUT ANY WARRANTY; without even the implied warranty of
500 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
501 Public License for more details.
502 .LP
503 You should have received a copy of the GNU General Public License along with
504 this program; if not, write to the Free Software Foundation, Inc., 51
505 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.