Provided by: ledcontrol_0.5.2-10_i386 bug

NAME

       ledcontrol.conf - configuration file for ledd’s default startup script

DESCRIPTION

       The  file  ledcontrol.conf is the configuration file for startup.sh(8),
       the default startup script for ledd(8), part of the ledcontrol package.
       ledcontrol.conf  configures  under  what  circumstances  what  LEDs are
       lighted. It is parsed by startup.sh as a shell script, so  blank  lines
       and lines with a number sign (‘‘#’’) are ignored. It can therefore also
       include normal shell commands  for  more  complex  actions.  Everything
       written to standard output is parsed by ledd as commands and everything
       written to standard error is logged via the chosen logging mechanism on
       a warning level.

       The  default  file  is  pretty well commented, so you should be able to
       configure it just by looking at it.

       The configuration itself is done by setting environment variables.  The
       format is ‘‘VARIABLE="option"’’. All options should be set.

GENERAL CONFIGURATION PARAMETERS

       STARTUP_ANIM=[YES|NO]
              If  set  to  YES,  a short animation (about 1 second) is flashed
              when starting ledd. It is ignored if started in X, as this might
              leave  the  LEDs  in  an  incorrect  state.  It  is  done in the
              background, so it doesn’t slow the booting.

       USE_BACKGROUNDING=[YES|NO]
              If set to YES, then some slow tests (eg. pinging a  remote  host
              that  isn’t  responding) are done in the background so as not to
              delay other checks. This is automatically disabled if using bash
              2.x.x  as it has a bug that makes it freeze. It is safe to leave
              this on.

       MINIMUM_DELAY=VALUE
              Sleep VALUE seconds at minimum between the  checks.  This  gives
              the  resolution  of  the check timings (a scheduled check can be
              delayed at most VALUE seconds). 5 is a reasonable value.

              Note that you  will  probably  get  a  disk-access  every  VALUE
              seconds (see startup.sh(8) section SILENCING for details).

       DEFAULT_SETTINGS="command"
              These  settings  are  set at the beginning. (See ledd(8) section
              COMMANDS)

TEST CONFIGURATION PARAMETERS

       The different tests are defined by four variables per test. Each one is
       suffixed with an underscore and a number. The numbers have to rise from
       1 up (you’re not allowed to skip numbers). The variables are as follow:

       COMMAND_nn
              Command to test the condition. This can be any command available
              on the system or a build-it check (see BUILT-IN  CHECKS  below).
              It  should  not  print  anything  to  stdout  (except in special
              conditions, see WRITING SCRIPTS below). Errors may be printed to
              stderr.

       SUCCESS_nn
              Command  to  give  ledd if COMMAND_nn returns successfully (exit
              code 0). If an  arbitrary  number  is  to  be  indicated  (using
              commands  "frequency"  or  "dutycycle",  see  ledd(8)), the last
              argument (the value) should be omitted.

       FAILURE_nn
              Command to give ledd if COMMAND_nn returns unsuccessfully  (exit
              code  non-zero).  If  an arbitrary value is to be indicated this
              variable may be ignored, but must be present (eg. "nop").

       DELAY_nn
              Minimum time between tests. The resolution of this is determined
              by MINIMUM_DELAY.

BUILT-IN CHECKS

       Ledcontrol offers certain common checks built-in. The command names are
       prefixed with led_. They can  be  used  in  the  checks  as  any  other
       commands. The following checks are boolean checks.

       led_ppp
              Check  for  a PPP-link. Returns true if a network interface with
              the name ppp0 to ppp9 is found.

       led_ping host
              Returns true if host replies to a ping packet.  ping(8) must  be
              available  on  the machine. This function uses backgrounding, if
              available.

       led_file file(s) ...
              Returns true if every one of file(s) exist. file(s) may  contain
              wildcards  (in  that  case  at  least one file has to match each
              pattern).

       led_size file min [max]
              Returns true if file exists and its size is greater or equal  to
              min  and  (optionally) less than max. This can be used to detect
              mail in someone’s mailbox.

       The following checks set the LED to indicate a number.  The  SUCCESS_nn
       command  should  be  either  type  "set  xxx  frequency"  or  "set  xxx
       dutycycle", where the last argument (the value) is omitted.

       led_load
              Indicate the current system load (1 minute average).  FAILURE_nn
              is ignored, but must be present.

       led_netload iface type
              Indicate  current  network  load on interface iface. type may be
              "IN", "OUT", or "BOTH" for inbound traffic, outbound traffic  or
              both  together.  The  value  is  given  as  kB/s  (kilobytes per
              second). The longer DELAY_nn is, the more  accurate  the  value.
              Returns false if no such interface exists.

WRITING SCRIPTS

       If  you want to use the scriptability to the full extent, I suggest you
       write custom "built-in" functions. This can be done either by adding it
       to /usr/share/ledcontrol in a file ending in .sh (it doesn’t have to be
       executable) or by writing it in ledcontrol.conf. In both  cases  it  is
       sourced  by  startup.sh  at  startup.  Read  the  existing  scripts for
       examples.

Environment variables in functions

       The following environment variables are available to the function:

       LEDDSCRIPTS
              Directory in which all the scripts should be located,  including
              startup.sh.

       SUCCESS
              The  command  to be given on successful exit value. The function
              may change this to give another command (it is restored  between
              calls).

       FAILURE
              The  command  to  be  given  on  unsuccessful  exit  values. The
              function may change this to give another command.

       COMMAND
              The whole command that was executed to start the function.  Note
              that command line arguments are also available in $1, $2, etc.

       COUNT  Number  part  of  COMMAND_nn.  Can  be  used  to store variables
              between calls (see Storing variables between calls below).  This
              must not be changed!

       USE_BACKGROUNDING
              Set   to   YES  if  slow  checks  should  be  backgrounded  (see
              Backgrounding below).

Arbitrary number indication

       If you want to make a script that  outputs  an  arbitrary  number,  you
       should append the number to the environment variable SUCCESS and return
       0 (for example load.sh, netload.sh).

Storing variables between calls

       The function may use almost any  variables  internally,  but  must  not
       depend  on  them  staying same between calls, as there might be several
       tests using the function. Instead you can use variables beginning  with
       the  function  name and with $COUNT appended to it. This can be done as
       follows (other means exist in new versions of bash):

       # Read previously saved value to $LOCAL
       eval ’LOCAL=LED_NAME_DESC_’$COUNT

       # Store value from $LOCAL for future use
       eval ’LED_NAME_DESC_’$COUNT’=$LOCAL’

Backgrounding

       Tests which may take many seconds to complete  (eg.  ping  when  remote
       host   is   not   responding)   should   check   whether  the  variable
       USE_BACKGROUNDING is set to "YES" and in that case make the test  in  a
       background process. The function itself should set SUCCESS to "nop" and
       return successfully and the subprocess check  the  condition  and  echo
       $SUCCESS or $FAILURE depending on the result. Note that when making the
       background process, you should always check whether the old process  is
       still running.

       The background process can be made by

       # Retrieve old PID
       if test -z "$PID" -o ! -e "/proc/$PID" ; then
           ( commands ) &
           PID=$!
       fi
       # Store PID

Examples of scripts

       Look  at  the  existing  scripts.  For  basic  boolean  checks, see eg.
       file.sh,  size.sh  and  ppp.sh.  For  examples  of   arbitrary   number
       indication,  see  load.sh,  or  a  more  complex  example with variable
       storing in netload.sh. For an example of backgrounding, see ping.sh.

EXAMPLE

       Example configuration file:

       # Give startup animation
       STARTUP_ANIM=YES

       # Use backgrounding (automatically disabled if dangerous)
       USE_BACKGROUNDING=YES

       # Minimum delay of 5 seconds is reasonable
       MINIMUM_DELAY=5

       # We use Caps Lock and Scroll Lock, so set them off.
       DEFAULT_SETTINGS="set c1s1 off"

       # Two tests:
       # Scroll Lock indicates the current system load
       # Caps Lock is lighted when a ppp-link is up and blinks when
       # "somehost.example" responds.
       COMMAND_1="led_load"
       SUCCESS_1="set s5 frequency 0.8 1000 1.9 100"
       FAILURE_1="nop"   # Ignored, but must be present.
       DELAY_1=10     # Not so critical check.

       COMMAND_2="led_ppp"
       SUCCESS_2="set c4 on"
       FAILURE_2="set c4c6 normal"   # We assume that if this fails,
                                     # ping will also fail.
       DELAY_2=5      # For immediate response

       COMMAND_3="led_ping somehost.example"
       SUCCESS_3="set c6 blink 500"
       FAILURE_3="set c6 normal"
       DELAY_3=20     # Not so critical check.

FILES

       /etc/ledcontrol.conf
              default configuration file location

       /usr/share/ledcontrol/
              location of the default  startup  script  startup.sh  and  other
              scripts

SEE ALSO

       startup.sh(8), ledd(8), ledd.conf(5), ledcontrol(1), bash(1), ping(8)

AUTHOR

       Ledcontrol  was  written by Sampo Niskanen <sampo.niskanen@iki.fi>. You
       can    get    the     latest     version     of     ledcontrol     from
       http://www.iki.fi/sampo.niskanen/ledcontrol/

BUGS

       bash  version 2.xx.xx has a bug in it that causes startup.sh to lock up
       if backgrounding is used. From version 0.5.0 up this has  been  checked
       by  startup.sh  and if a bad version of bash is being used the variable
       USE_BACKGROUNDING is automatically set to "NO".

       The default startup script may cause a disk-access every  MINIMUN_DELAY
       seconds. See startup.sh(8) for more info.