SERELC(8)

NAME
serelc - serel synchronisation primitives and daemon management

SYNOPSIS
serelc [ general options] --provide service serelc [ general options] --unprovide service serelc [ general options] --need service serelc [ general options] --statuschange pid exitstatus serelc [ general options] --control stop serelc [ general options] --query args

DESCRIPTION

Boot scripts use serelc to register or deregister services with the serel daemon. serelc tells the daemon that a boot script:

•   starts a service

•   stops a service

•   needs certain services in order for it to continue, or

•   exited

serelc also queries and stops the deamon.

GENERAL OPTIONS

-d --debuglevel num
    num controls the verbosity of the log output: 0 - none 1 - default 2 - and above generate increased verbosity

-l --log log
    Output logging to log, which is either a filename or syslog facility (LOG_XXXX)

-a --log-append
    (default) Append log messages to the log file

-t --log-truncate
    Truncate the log file before writing log messages

-v --version
    Report the version number and exit

STARTING AND STOPPING SERVICES

Boot scripts use the the following commands to register, deregister and synchronise:

•   serelc [ general options] --provide service

•   serelc [ general options] --unprovide service

•   serelc [ general options] --need service

--provide service
    Tell the daemon that the parent process is starting service

--unprovide service
    Tell the daemon that the parent process is stopping service

--need service
    Block until the daemon reports that service's providing process has exited. The exit status of the providing process may also be relevant, see --statuschange.

--statuschange pid exitstatus
    Tell the daemon that process pid exited with status exitstatus. While --statuschange can be called from within a boot script, generally a shell "trap" must be employed to guarantee that it is called. This usage is cumbersome, and so --statuschange is generally called by the boot scripts's parent process, commonly serel-wrap.

General Limitations:

•   a script should only call --provide or --unprovide once, subsequent calls to either command will fail

•   a script should call --provide before calling --need, otherwise --need fails

STOPPING THE DAEMON

The daemon is stopped via: serelc [ general options] --control stop

QUERYING THE DAEMON

The daemon is queried via: serelc [ general options] --query args where args is one of:

state service
    output the finite state machine value for service Explanation: the daemon maintains a finite state machine for each service, representing the service life cycle: non-existent, on-the-way-in, in, failed, on-the-way-out. Finite state machine values are likely to only be of interest to developers.

graph   [ id graph_id ]  [  add file ]
    output the daemon's dependency graph as an xml/rdf document. Optionally set the rdf:ID of the graph to graph_id, and optionally add the contents of file to the xml/rdf document. Explanation: When boot scripts use serelc --provide, --need and --unprovide to synchronise with one another, the daemon builds a dependency graph. This command outputs the dependency graph as an xml/rdf document, suitable for further processing purposes such as visualisation. The graph may include weights representing the nett time taken by services to start.

EXIT STATUS

To be written.

EXAMPLES

  SAMPLE SCRIPT TO START AND STOP A SERVICE
# This script starts sendmail
#
# sendmail depends on network and syslog
#
service ="sendmail"
case "$1" in
  start)
    serelc --provide $service || exit 1
    serelc --need network || exit 1
    serelc --need syslog || exit 1
    # ... start sendmail
    ;;
  stop)
    serelc --unprovide $service || exit 1
    # ... stop sendmail
    ;;
esac

  SCRIPT TO DUMP THE DAEMON'S DEPENDENCY GRAPH
# This script dumps the serel daemon dependency graph as
# an xml/rdf document and adds host-specific metadata
#
tmpfile=`mktemp -q /tmp/XXXXXX`
$CAT <<EOF > $tmpfile
<rdf:Description about="mygraph"
myspace:hostname=`/bin/hostname`
myspace:date=`/bin/date`
/>
EOF
serelc --query graph id mygraph add $tmpfile
/bin/rm $tmpfile

CAVEATS

This software is relatively immature, some options may be renamed or may disappear altogether.

REPORTING BUGS

Email bug reports to <serel@fastboot.org>.

SEE ALSO

sereld (8), serelhistory (8)

AUTHOR

Leni Mayo