.\" Made by Sampo Niskanen
.TH ledcontrol.conf 5 "January, 2001" "ledcontrol @VERSION@"
.SH NAME
ledcontrol.conf \- configuration file for \fBledd\fR's default startup
script 
.SH DESCRIPTION
The file
.B ledcontrol.conf
is the configuration file for
.BR startup.sh (8),
the default startup script for
.BR ledd (8),
part of the ledcontrol package.
.B ledcontrol.conf
configures under what circumstances what LEDs are lighted. It is
parsed by \fIstartup.sh\fR 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 \fBledd\fR as commands and everything
written to standard error is logged via the chosen logging mechanism
on a warning level.
.PP
The default file is pretty well commented, so you should be able to
configure it just by looking at it.
.PP
The configuration itself is done by setting environment variables. The
format is ``VARIABLE="option"''. All options should be set.
.SH "GENERAL CONFIGURATION PARAMETERS"
.TP
\fBSTARTUP_ANIM=\fR[YES|NO]
If set to YES, a short animation (about 1 second) is flashed when
starting \fBledd\fR. 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.
.TP
\fBUSE_BACKGROUNDING=\fR[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.
.TP
\fBMINIMUM_DELAY=\fR\fIVALUE\fR
Sleep \fIVALUE\fR seconds at minimum between the checks. This gives
the resolution of the check timings (a scheduled check can be delayed
at most \fIVALUE\fR seconds). 5 is a reasonable value.

Note that you will probably get a disk-access every \fIVALUE\fR
seconds (see
.BR startup.sh (8)
section
.B SILENCING
for details).
.TP
\fBDEFAULT_SETTINGS=\fR"command"
These settings are set at the beginning. (See
.BR ledd (8)
section \fBCOMMANDS\fR)
.SH "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:
.TP
\fBCOMMAND_\fInn\fR
Command to test the condition. This can be any command available on
the system or a build-it check (see
.B BUILT-IN CHECKS
below). It should not print anything to stdout (except in special
conditions, see
.B WRITING SCRIPTS
below). Errors may be printed to stderr.
.TP
\fBSUCCESS_\fInn\fR
Command to give \fBledd\fR if \fBCOMMAND_\fInn\fR returns successfully
(exit code 0). If an arbitrary number is to be indicated (using
commands "frequency" or "dutycycle", see
.BR ledd (8)),
the last argument (the value) should be
omitted.
.TP
\fBFAILURE_\fInn\fR
Command to give \fBledd\fR if \fBCOMMAND_\fInn\fR 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").
.TP
\fBDELAY_\fInn\fR
Minimum time between tests. The resolution of this is determined by
\fBMINIMUM_DELAY\fR.
.SH "BUILT-IN CHECKS"
Ledcontrol offers certain common checks built-in. The command names
are prefixed with \fBled_\fR. They can be used in the checks as any
other commands. The following checks are boolean checks.
.TP
\fBled_ppp\fR
Check for a PPP-link. Returns true if a network interface with the
name ppp0 to ppp9 is found.
.TP
\fBled_ping\fR \fIhost\fR
Returns true if \fIhost\fR replies to a ping packet.
.BR ping (8)
must be available on the machine. This function uses backgrounding, if
available.
.TP
\fBled_file\fR \fIfile(s)\fR ...
Returns true if every one of \fIfile(s)\fR exist. \fIfile(s)\fR may
contain wildcards (in that case at least one file has to match each
pattern).
.TP
\fBled_size\fR \fIfile\fR \fImin\fR [\fImax\fR]
Returns true if \fIfile\fR exists and its size is greater or equal to
\fImin\fR and (optionally) less than \fImax\fR. This can be used to
detect mail in someone's mailbox.
.PP
The following checks set the LED to indicate a number. The
\fBSUCCESS_\fInn\fR command should be either type "set xxx frequency"
or "set xxx dutycycle", where the last argument (the value) is
omitted.
.TP
\fBled_load\fR
Indicate the current system load (1 minute
average). \fBFAILURE_\fInn\fR is ignored, but must be
present.
.TP
\fBled_netload\fR \fIiface\fR \fItype\fR
Indicate current network load on interface \fIiface\fR. \fItype\fR 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 \fBDELAY_\fInn\fR is, the more accurate the value. Returns
false if no such interface exists.
.SH "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 @datadir_int@ in a file ending in \fB.sh\fR (it doesn't
have to be executable) or by writing it in \fBledcontrol.conf\fR. In
both cases it is sourced by \fIstartup.sh\fR at startup. Read the
existing scripts for examples.
.SH "Environment variables in functions"
The following environment variables are available to the function:
.TP
\fBLEDDSCRIPTS\fR
Directory in which all the scripts should be located, including
\fIstartup.sh\fR.
.TP
\fBSUCCESS\fR
The command to be given on successful exit value. The function may
change this to give another command (it is restored between calls).
.TP
\fBFAILURE\fR
The command to be given on unsuccessful exit values. The function may
change this to give another command.
.TP
\fBCOMMAND\fR
The whole command that was executed to start the function. Note that
command line arguments are also available in $1, $2, etc.
.TP
\fBCOUNT\fR
Number part of \fBCOMMAND_\fInn\fR. Can be used to store variables
between calls (see
.B Storing variables between calls
below). This must not be changed!
.TP
\fBUSE_BACKGROUNDING\fR
Set to YES if slow checks should be backgrounded (see
.B Backgrounding
below).
.SH "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).
.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 \fBbash\fR):
.nf

# 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'
.fi
.SH Backgrounding
Tests which may take many seconds to complete (eg. ping when remote
host is not responding) should check whether the variable
\fBUSE_BACKGROUNDING\fR is set to "YES" and in that case make the test
in a background process. The function itself should set \fBSUCCESS\fR 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 \fBalways\fR check whether
the old process is still running.
.PP
The background process can be made by
.nf

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

.fi
.SH "Examples of scripts"
Look at the existing scripts. For basic boolean checks, see
eg. \fIfile.sh\fR, \fIsize.sh\fR and \fIppp.sh\fR. For examples of
arbitrary number indication, see \fIload.sh\fR, or a more complex
example with variable storing in \fInetload.sh\fR. For an example of
backgrounding, see \fIping.sh\fR.
.SH EXAMPLE
Example configuration file:
.nf

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

.fi
.SH FILES
.TP
\fI@sysconfdir_int@/ledcontrol.conf\fR
default configuration file location
.TP
\fI@datadir_int@/\fR
location of the default startup script \fIstartup.sh\fR and other
scripts
.SH "SEE ALSO"
.BR startup.sh (8),
.BR ledd (8),
.BR ledd.conf (5),
.BR ledcontrol (1),
.BR bash (1),
.BR ping (8)
.SH AUTHOR
Ledcontrol was written by Sampo Niskanen <sampo.niskanen@iki.fi>. You
can get the latest version of ledcontrol from
.I http://www.iki.fi/sampo.niskanen/ledcontrol/
.SH BUGS
.B bash
version 2.xx.xx has a bug in it that causes \fIstartup.sh\fR to lock
up if backgrounding is used. From version 0.5.0 up this has been
checked by \fIstartup.sh\fR and if a bad version of
.B bash
is being used the variable \fBUSE_BACKGROUNDING\fR is automatically
set to "NO".
.PP
The default startup script may cause a disk-access every
\fBMINIMUN_DELAY\fR seconds. See
.BR startup.sh (8)
for more info.