Provided by: ledcontrol_0.5.2-11.1_i386 bug


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


       The  file  ledcontrol.conf is the configuration file for,
       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 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.


              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.

              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.

              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 section SILENCING for details).

              These  settings  are  set at the beginning. (See ledd(8) section


       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 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

              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.

              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").

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


       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.

              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

       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

       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.

              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.


       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  at  startup.  Read  the  existing  scripts  for

Environment variables in functions

       The following environment variables are available to the function:

              Directory  in which all the scripts should be located, including

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

              The command  to  be  given  on  unsuccessful  exit  values.  The
              function may change this to give another 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!

              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,

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

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


       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 ) &
       # Store PID

Examples of scripts

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


       Example configuration file:

       # Give startup animation

       # Use backgrounding (automatically disabled if dangerous)

       # Minimum delay of 5 seconds is reasonable

       # 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.
       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.

       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.


              default configuration file location

              location  of  the  default  startup  script and other

SEE ALSO, ledd(8), ledd.conf(5), ledcontrol(1), bash(1), ping(8)


       Ledcontrol was written by Sampo Niskanen  <>.  You
       can     get     the     latest     version     of    ledcontrol    from


       bash version 2.xx.xx has a bug in it that causes to lock  up
       if  backgrounding  is used. From version 0.5.0 up this has been checked
       by 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 for more info.