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.