serelc

# `serelc`

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

Example 1. 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

Example 2. 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