Provided by: ledcontrol_0.5.2-12_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.