<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
<!ENTITY general-cmdline-options-sect SYSTEM "general-cmdline-options-sect.xml">
<!ENTITY author-sect                  SYSTEM "author-sect.xml">
<!ENTITY bugs-sect                    SYSTEM "bugs-sect.xml">
<!ENTITY caveats-sect                 SYSTEM "caveats-sect.xml">
<!ENTITY exit-status-sect             SYSTEM "exit-status-sect.xml">
]>
<refentry status="draft" id="serelc">

<refentryinfo>
<!--  <date>2002-05-23</date> -->
<author>
<firstname>Leni</firstname>
<surname>Mayo</surname>
</author>
</refentryinfo>

<refmeta>
<refentrytitle><application>serelc</application></refentrytitle>
<manvolnum>8</manvolnum>
<refmiscinfo>serelc 0.3.2</refmiscinfo>
</refmeta>

<refnamediv>
<refname><application>serelc</application></refname>

<refpurpose>serel synchronisation primitives and daemon management</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>

<command>serelc</command>
<arg><option>general options</option></arg>
<arg choice="plain">--provide <replaceable>service</replaceable></arg>
<!-- <sbr/> created a dangling '>', <sbr></sbr> didn't work either -->
<sbr>
<command>serelc</command>
<arg><option>general options</option></arg>
<arg choice="plain">--unprovide <replaceable>service</replaceable></arg>
<sbr>
<command>serelc</command>
<arg><option>general options</option></arg>
<arg choice="plain">--need <replaceable>service</replaceable></arg>
<sbr>
<command>serelc</command>
<arg><option>general options</option></arg>
<arg choice="plain">--statuschange <replaceable>pid </replaceable><replaceable>exitstatus</replaceable></arg>
<sbr>
<command>serelc</command>
<arg><option>general options</option></arg>
<arg choice="plain">--control stop</arg>
<sbr>
<command>serelc</command>
<arg><option>general options</option></arg>
<arg choice="plain">--query <replaceable>args</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsect1>
<title>DESCRIPTION</title>

<para>
Boot scripts use <command>serelc</command> to register or deregister services with the serel daemon.
<command>serelc</command> tells the daemon that a boot script:
<itemizedlist spacing="compact">
<listitem><simpara>starts a service</simpara></listitem>
<listitem><simpara>stops a service</simpara></listitem>
<listitem><simpara>needs certain services in order for it to continue, or</simpara></listitem>
<listitem><simpara>exited</simpara></listitem>
</itemizedlist>
</para>
<para>
<command>serelc</command> also queries and stops the deamon.
</para>
</refsect1>

&general-cmdline-options-sect;

<refsect1>
<title>STARTING AND STOPPING SERVICES</title>
<para>
<!-- (De)registering a service and it's dependencies: -->
Boot scripts use the the following commands to register, deregister and synchronise:
<itemizedlist spacing="compact">
<listitem><simpara>
<cmdsynopsis>
<command>serelc</command>
<arg><option>general options</option></arg>
<arg choice="plain">--provide <replaceable>service</replaceable></arg>
</cmdsynopsis>
</simpara></listitem>
<listitem><simpara>
<cmdsynopsis>
<command>serelc</command>
<arg><option>general options</option></arg>
<arg choice="plain">--unprovide <replaceable>service</replaceable></arg>
</cmdsynopsis>
</simpara></listitem>
<listitem><simpara>
<cmdsynopsis>
<command>serelc</command>
<arg><option>general options</option></arg>
<arg choice="plain">--need <replaceable>service</replaceable></arg>
</cmdsynopsis>
</simpara></listitem>
</itemizedlist>
</para>

<para>
<variablelist>

<varlistentry>
<term>--provide <replaceable>service</replaceable></term>
<listitem>
<para>
Tell the daemon that the parent process is starting <replaceable>service</replaceable>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>--unprovide <replaceable>service</replaceable></term>
<listitem>
<para>
Tell the daemon that the parent process is stopping <replaceable>service</replaceable>
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>--need <replaceable>service</replaceable></term>
<listitem>
<para>
Block until the daemon reports that <replaceable>service</replaceable>'s providing process has exited.  The exit status of the providing process may also be relevant, see <command>--statuschange</command>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>--statuschange <replaceable>pid </replaceable><replaceable>exitstatus</replaceable></term>
<listitem>
<para>
Tell the daemon that process <replaceable>pid</replaceable> exited with
status <replaceable>exitstatus</replaceable>.
</para>
<para>
While <command>--statuschange</command> 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 <command>--statuschange</command> is generally
called by the boot scripts's parent process, commonly <command>serel-wrap</command>.
</para>
</listitem>
</varlistentry>

</variablelist>
</para>

<para>
General Limitations:
<itemizedlist spacing="compact">
<listitem><simpara>a script should only call <command>--provide</command> or <command>--unprovide</command> once, subsequent calls to either command will fail</simpara></listitem>
<listitem><simpara>a script should call <command>--provide</command> before calling <command>--need</command>, otherwise  <command>--need</command> fails</simpara></listitem>
</itemizedlist>
</para>
</refsect1>

<refsect1>
<title>STOPPING THE DAEMON</title>
<para>
The daemon is stopped via:
<cmdsynopsis>
<command>serelc</command>
<arg><option>general options</option></arg>
<arg choice="plain">--control stop</arg>
</cmdsynopsis>
</para>
</refsect1>

<refsect1>
<title>QUERYING THE DAEMON</title>
<para>
The daemon is queried via:
<cmdsynopsis>
<command>serelc</command>
<arg><option>general options</option></arg>
<arg choice="plain">--query <replaceable>args</replaceable></arg>
</cmdsynopsis>
where <replaceable>args</replaceable> is one of:
<variablelist>

<varlistentry>
<term>state <replaceable>service</replaceable></term>
<listitem>
<para>
output the finite state machine value for <replaceable>service</replaceable>
</para>
<para>
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.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
graph
<cmdsynopsis>
<arg choice="opt"> id <replaceable class="parameter">graph_id</replaceable> </arg>
<arg choice="opt"> add <replaceable class="parameter">file</replaceable> </arg>
</cmdsynopsis>
</term>
<listitem>
<para>
output the daemon's dependency graph as an xml/rdf document.
Optionally set the rdf:ID of the graph to <replaceable class="parameter">graph_id</replaceable>, and
optionally add the contents of <replaceable class="parameter">file</replaceable> to the xml/rdf document.
</para>
<para>
Explanation: When boot scripts use <command>serelc</command>
<command>--provide</command>, <command>--need</command> and <command>--unprovide</command> 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.
</para>
</listitem>
</varlistentry>

</variablelist>
</para>
</refsect1>

&exit-status-sect;

<refsect1>
<title>EXAMPLES</title>
<example>
<title>sample script to start and stop a service</title>
<programlisting>
# 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
</programlisting>
</example>

<example>
<title>script to dump the daemon's dependency graph</title>
<programlisting>
# This script dumps the serel daemon dependency graph as
# an xml/rdf document and adds host-specific metadata
#
tmpfile=`mktemp -q /tmp/XXXXXX`

$CAT &lt;&lt;EOF &gt; $tmpfile
&lt;rdf:Description about="mygraph"
myspace:hostname=`/bin/hostname`
myspace:date=`/bin/date`
/&gt;
EOF

serelc --query graph id mygraph add $tmpfile
/bin/rm $tmpfile
</programlisting>
</example>
</refsect1>

&caveats-sect;

&bugs-sect;

<refsect1>
<title>SEE ALSO</title>
<para>
<command>sereld (8)</command>, <command>serelhistory (8)</command>
</para>
</refsect1>

&author-sect;

</refentry>
