README.html

<h1 id="syswatcher">sysWatcher</h1>
<p>The sysWatcher project is a fully scriptable, generic event system. It uses custom triggers to invoke a script or to send an email with predetermined content. Event triggering is entirely handled by the plugin scripts, hence the term &quot;generic&quot;.</p>
<h2 id="installation">Installation</h2>
<p>The installation process is necessary because sysWatcher depends on in-house scripts, which provide functions useful to plugins and the main script alike. Functions for date and time malipulation are provided, among others.</p>
<p>In your terminal, clone the sysWatcher repository using <code>git clone git://xroutine.net/sysWatcher.git</code>.</p>
<p>Install the configuration and plugin files by typing <code>make install</code>. This creates and populates the directory <strong>/usr/share/sysWatcher</strong>.</p>
<p>Finally, copy sysWatcher.sh to the installation path of your choice.</p>
<p><em>Note: sysWatcher consists entirely of shell script and configuration files, so no compiler commands are required.</em></p>
<h2 id="configuration">Configuration</h2>
<p>The main script, <strong>sysWatcher.sh</strong>, looks for <strong>sysWatcher.conf</strong>, first in the current directory (which may not be the installation directory), then in /etc, and finally in /usr/local/etc. It will stop looking for sysWatcher.conf at the first match.</p>
<p><strong>sysWatcher.conf</strong> must contain at least three variables: <strong>email</strong>, <strong>eventDir</strong> and <strong>varDir</strong>:</p>
<ul>
<li><strong>eventDir</strong> tells sysWatcher which directory contains the plugin scripts.</li>
<li><strong>varDir</strong> specifies a directory including items such as temporary timeout files.</li>
<li><strong>email</strong> is the default recipient email.</li>
</ul>
<p>More detailed configuration options are given in <strong>sysWatcher.sh</strong>.</p>
<h2 id="requirements">Requirements</h2>
<p>A plugin script needs to include certain mandatory functions to work properly. More details are given within <strong>sysWatcher.sh</strong>.</p>
<p>For reasons of compatibility, only <strong>bash</strong> and <strong>zsh</strong> are supported. Some other shells such as <strong>dash</strong> lack some necessary features. It may be possible to use <strong>ksh</strong>, but this has not been tested.</p>
<p>sysWatcher.sh uses the <strong>mail</strong> command to send emails. For this to work you should have a mailing system (such as postfix) installed and configured.</p>
<h2 id="running-syswatcher">Running sysWatcher</h2>
<p>You should schedule sysWatcher.sh as a regular job using cron or similar. This allows sysWatcher to run as often or as rarely as you wish.</p>
<h3 id="adding-a-cron-job">Adding a cron job</h3>
<p>Open a terminal and type:</p>
<p><code>sudo crontab -e</code></p>
<p>This will open the cron table in your default text editor. Enter the following after the comments:</p>
<p><code>*/1 * * * * /bin/bash /usr/sbin/sysWatcher.sh</code></p>
<p>The above example assumes you want to run sysWatcher.sh every minute. Please note that the path may vary depending on where you choose to install sysWatcher (see the Installation section for more details). Read the man pages for <strong>crontab(5)</strong> and <strong>cron(8)</strong> for more details on scheduling with cron.</p>
<p>It should be quite easy to run sysWatcher as a standalone daemon, but this might be less useful than scheduling it as a cron job.</p>