Provided by: avr-evtd_1.7.7-2_i386 bug

NAME

       avr-evtd - Linkstation AVR Event daemon

SYNOPSIS

       avr-evtd [ -d /dev/tty ] [i | c | v]

DESCRIPTION

       avr-evtd  is a simple and small user space interface to the Linkstation
       AVR micro-controller.  It doesn't have a lot of special  features,  but
       it's main task is to provide 'keep-alive' messages to the Linkstation's
       on-board AVR device.  This device controls/monitors  the  fan,  various
       LEDs,  timed  power  up  and  two  buttons.   This  daemon provides the
       necessary initialization to the device and  also  stimulates  the  LEDs
       depending on various fault conditions.  It also monitors a power button
       (located at the front) and a reset button (located at the rear).

       avr-evtd searches for a configuration file located within /etc/melco at
       start-up  time.  If  this file does not exist, then avr-evtd reverts to
       reading the file located at /etc/default/avr-evtd.  Additionally,  avr-
       evtd may, if requested, periodically check the root (Under user control
       and could be /dev/hda1) partition and the user working  partition  (For
       example, /dev/hda3) to ensure they are mounted.  Also, if requested, it
       will determine if sufficient space remains and if not then the  AVR  is
       requested  to  illuminate  the  DISK  LED.  This periodic checking also
       takes place on the configuration files.  If they  are  deemed  to  have
       been updated, then the daemon will respond accordingly.

       Any  failures  are  normally  routed through the log files.  With timed
       shutdown/power up, a warning will be broadcast to  all  users  (console
       message) when within 5 or less minutes of power off.  Also, fan failure
       alerts will be broadcast in this fashion.  Failure to determine mounted
       working  partition  will  result  in the DIAG LED flashing three times,
       repeatedly.

       A new feature of this daemon is the ability to code events  for  single
       or  groups  of  days.  This allows the user to add any number of power-
       on/off events as required.  This also has the added  benefit  of  being
       able  to  shut  down  the  device for longer periods.  The internal AVR
       timer has a 12-bit resolution timer which can power up the  Linkstation
       from  a  maximum  of a sixty eight hour sleep: from time of invocation.
       The AVR is updated again at time of power down/shutdown to  re-validate
       the  timer, in case of time updates (either by user or NTP).  This will
       also preserve the 68 hour sleep resolution.

OPTIONS

       -d   /dev/tty Specifies the UART device used to  communicate  with  the
            AVR.  This  is  normally  taken  care of by the scripts but can be
            specified in the configuration file.  See below for details.

       -c   Don't fork, i.e. run in the foreground (debug use only).

       -i   Returns the port memory location for the device  specified  by  -d
            /dev/tty

       -v   Display daemon version.

THE CONFIGURATION FILE

       The  avr-evtd configuration file is the fallback file in the event that
       the stock melco files do not exist.  The file is read at initial start-
       up  in order to determine if timed shutdown is required and if the disk
       usage is to be monitored.  The file should be always located within the
       /etc/default  directory and a sample file is provided.  The file format
       is similar to other Unix configuration files - comments begin with a  #
       character  and  extend to the end of the line; blank lines are ignored.
       Configuration commands consist of an initial  keyword  followed  by  an
       argument.   Arguments  may  be  strings or times written in HH:MM (UTC)
       format.  Optional arguments are delimited  by  [  ]  in  the  following
       descriptions, while alternatives are separated by |.

       DEBUG
            [ON | OFF]

            This  is  reserved  for  admin  only.   Allows  logging of certain
            information.  A log  file  will  be  maintained  in  /etc/avr-evtd
            logging  events  and  when run from command line, the process will
            log data to the console.

       TIMER
            [YES | NO]

            The timer command informs the daemon if it  has  to  provide  time
            controlled shutdown and power up.  If TIMER is set to NO then this
            function is not available and the commands  SHUTDOWN  and  POWERON
            are  ignored  and  have  no  effect.   The same applies if any day
            events are specified and the TIMER is set to NO then these  events
            will also be ignored.

       DEVICE
            [/dev/tty]

            This informs the AVR which UART to use when communicating with the
            AVR.  The communication path between the micro-controller and this
            daemon  is via a serial link.  This keyword is not for general use
            and is provided to allow advanced users the option  of  overriding
            automatic configuration.  This would normally be set to /dev/ttyS1
            but on some systems  it  is  /dev/ttyS0.   The  selection  of  the
            correct  port  is  performed by the daemon start script and is not
            normally required to be altered.

       [<day>|<day>-<day>]
            [ON=HH:MM | ON= | OFF=HH:MM | OFF=]

            This defines events for either a single day or group of days,  '-'
            separator.   Any  number of ON and OFF events can be specified and
            can be extended over additional lines. <day> can be any number  of
            days of the week specified as either SUN, MON, TUE, WED, THR, FRI,
            and SAT.  For example:

                      MON-WED=ON=09:00,OFF=23:00
                      THR=ON=09:00
                      FRI=OFF=01:00

            In this example, the first power on event is Monday at 09:00.   At
            23:00  the  Linkstation  will  power  down.   This is repeated for
            Tuesday and Wednesday.  On Thursday, the Linkstation will power on
            at  09:00  and  will  power off on Friday at 01:00.  The unit will
            then remain off for Saturday and Sunday and  not  power  up  again
            till 09:00 on Monday.  The unit is capable of sleeping for no more
            than 68 hours (due to  the  resolution  of  the  internal  timer).
            Again, this time MUST be specified in UTC format and follow HH:MM.

            Five  minutes before power off is required, a message is broadcast
            to all console users.  At shutdown, an event message  is  sent  to
            the event script.  See below for more details.

       SHUTDOWN
            [HH:MM]

            This specifies the time that the Linkstation will be powered down.
            This time MUST be specified in UTC  and  must  follow  the  format
            HH:MM.   If  the  user  alters  this configuration file whilst the
            daemon is running, then the  change  will  be  seen  and  the  new
            settings  will  be implemented.  If the new time entered is passed
            the current time, then the shutdown time will be for the following
            day.   If  single  or multiple day events are specified, then this
            becomes the default power down time for any undefined days.

       POWERON
            [HH:MM]

            This specifies the time that the Linkstation will be automatically
            powered up; as long as now unexpected power outage occurs.  Again,
            if this time is less than the SHUTDOWN time then  it  is  for  the
            following  day.  Both the TIMER set to ON and the SHUTDOWN and the
            POWERON times are valid will timed shutdown/power up  be  enabled.
            This  will be reported in the message log along with any errors in
            the configuration file.

            If single or multiple day events are specified, then this  becomes
            the default power on time for any undefined days.

       DISKCHECK
            [OFF | 0..100]

            If  this  is  set to OFF or 0 (zero) then disk usage/monitoring is
            disabled.  Set to a value between  0  and  100%  to  monitor  disk
            usage.  If disk usage is above this specified value, then the DISK
            LED will be illuminated.  At the same  time,  a  disk  full  event
            message will be sent to the event script.

       ROOT [hda1..9]

            No  default.   This allows the root partition to be defined by the
            user.  No syntax checking is performed on this entry or validation
            of the partition ID.

       WORK [hda1..9]

            No  default.   This  allows the working partition to be defined by
            the user.  Again, no syntax checking is performed on this entry or
            validation of the partition ID.

       REFRESH
            [1..300]

            This  defaults  to  40.   This  provides control over the rate (in
            seconds) that  the  daemon  checks  the  system  for  changes  and
            refreshes  the  AVR.  Any number between 1 and 300 can be entered.
            Anything less than the default will result in higher impact on the
            system:  more  CPU  usage.   Higher  times will result with slower
            response to configuration file changes but  this  may  not  be  an
            issue with most users.

       HOLD [1..9]

            This  defaults  to  3.   This  provides  control over the time (in
            seconds) that the user needs to hold either the reset of the power
            button  in  for  a  reset  event (reset button) or power off event
            (power button).

       DISKNAG
            [ON | OFF]

            Default if off.  This provides the user control over the disk full
            event.   The default is that once detected, just a single event is
            triggered.  If required, setting this to on will generate repeated
            events,  at  the  frequency of REFRESH until the disk is no longer
            deemed full.

       FANSTOP
            [OFF | 0..60]

            Default is 30 seconds. This  is  the  time,  from  report  of  fan
            failure in which the daemon will generate a fan failure event call
            to the event script.  This allows the user to act accordingly.  At
            present,  the  script is setup to power down.  This can be changed
            to an e-mail event prior to shutdown if required.

            Otherwise, if a user has decided to remove the fan then  this  can
            be  set  to  OFF  to  prevent  shutdown from occuring.  It must be
            stressed that alternative cooling must be sourced if  this  option
            is selected.

BUTTON OPERATION

       All   events,   whether   mechanical   button  operation,  or  software
       reset/shutdown actions are routed through an event  script  located  at
       /etc/avr-evtd/EventSCript

       POWER
            On  press,  a  button  event message is sent.  On release, another
            event message is sent.  If the button is held  in  for  more  than
            HOLD  seconds,  then  a  shutdown  event  request is sent.  If the
            button is pressed twice within a period  of  one  second,  then  a
            reset request event is sent.

            If  the  power  button  is  pressed  during  the five minute timed
            shutdown warning, then the shutdown  time  is  increased  by  five
            minutes.   Multiple  presses will keep increasing the time by five
            minutes (to a maximum pause of fifty minutes).  This provides  the
            user with the ability to carry on working before timed shutdown is
            finally activated; careful here as repeated presses maybe seen  as
            a reboot request.

       RESET
            On  press,  a  button  event message is sent.  On release, another
            event message is sent.  If the button is held  in  for  more  than
            twenty  seconds,  then  a  EM-Mode  event request is sent.  If the
            button is pressed twice within a period  of  one  second,  then  a
            special  event  is sent which in the default state will launch the
            telnet daemon.

MESSAGE EVENTS

       The event system has been modified such that 99% of  the  daemon  event
       system  is  pushed  through  the  event  script.   A third parameter is
       supplied by the daemon out to the script detailing information relevant
       to  the  generated  message.  For example, for a disk full message, the
       third parameter would detail the percentage disk space used  (worst  of
       the  two  monitored  partitions)  and  when  this is cleared, then this
       parameter would be cleared to zero.

       0    User has requested (by double press of reset button) to, with  the
            first  press,  launch  the  telnet  daemon,  or  other  client  as
            specified in the  EventScript.   The  script  also  establishes  a
            static  IP  to an alias Ethernet device :EM at 192.168.11.150.  If
            this IP is already in-use, then it will not be  created.   If  the
            Ethernet   is   not   running,   then   an   alternative  Ethernet
            configuration  file  is  loaded   providing   a   static   IP   at
            192.168.11.150.  and also a DHCP provided IP.  On the THIRD double
            press, then a known set of  group  and  user  password  files  are
            copied  to  /etc.   Prior  to  the transfer, the relevant original
            files are copied to .em.  A file, recovery.tar, is  extracted  and
            the  LEDs  are  flashed to indicate this new mode.  A user can now
            gain root access using the password emergency and gain access  via
            the telnet port 1234 to their box.

       1    AVR micro-controller has requested a reset.

       2    Shutdown request from the shutdown timer event.

       3    Power button has been released event.

       4    Power button has been pressed event.

       5    Reset button (rear of unit) has been released.

       6    Reset button has been pressed.

       7    User  has  requested  (by  holding power button for more than HOLD
            seconds) to shutdown the unit.

       8    User has requested (by double press of the power button) to  reset
            the unit.

       9    Disk  usage greater than DISKCHECK.  Parameter 3 set to percentage
            used or zero.

       F    Fan has been stationary for FANSTOP seconds.  Parameter 3  is  set
            to 4 when cleared.

       E    EM-Mode has been selected.  The EM-Mode sequence is written to the
            desired flash location and the system is issued a reboot  request.
            EM-Mode  is  an  emergency  boot  mode that for the Linkstation it
            boots from an image in flash and rebuilds files on the disk.  This
            should  only  be  used by those who know what will happen to their
            disks when this Mode is selected

       S    The system will  shutdown  in  less  than  five  minutes  warning.
            Parameter 3 indicates shutdown delay on power press.

       D    Error message handler.  Parameter 3 indicates error number.

ERROR CODES

       The  following  error  messages maybe displayed in the log files during
       operation:

       1    No stock or avr-evtd configuration files were located.

       2    Power off time greater than that supported by the AVR.  As this is
            calculated  at  the  time the timer is established, this fault may
            clear at shutdown as timers are re-validated.

       3    Timer declaration  error  in  /etc/default/avr-evtd  configuration
            file

       4    Error in stock configuration file

FILES

       /etc/default/avr-evtd
       /etc/avr-evtd/EventScript
       /etc/avr-evtd/emergency-eth0
       /etc/default/events.log
       /etc/avr-evtd/recovery.tar

AUTHORS

       Bob   Perry   <lb-source@users.sourceforge.net>   (2006),   with   some
       modifications by Rogério  Brito  <rbrito@users.sourceforge.net>  (2008,
       2009).

COPYRIGHT

       This program is free software; you can redistribute it and/or modify it
       under the terms of the GNU General Public License as published  by  the
       Free  Software Foundation; either version 2 of the License, or (at your
       option) any later version.

       This program is distributed in the hope that it  will  be  useful,  but
       WITHOUT   ANY   WARRANTY;   without   even   the  implied  warranty  of
       MERCHANTABILITY or FITNESS  FOR  A  PARTICULAR  PURPOSE.  See  the  GNU
       General Public License for more details.

       You should have received a copy of the GNU General Public License along
       with this program; if not, write to the Free Software Foundation, Inc.,
       675 Mass Ave, Cambridge, MA 02139, USA.

                                  28 Aug 2009                      AVR-EVTD(8)