﻿<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="scheduler_job_documentation.xsl"?>
<description xmlns="http://www.sos-berlin.com/schema/scheduler_job_documentation_v1.0" xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.sos-berlin.com/schema/scheduler_job_documentation_v1.0 http://www.sos-berlin.com/schema/scheduler_job_documentation_v1.0.xsd">

  <job name  = "JobSchedulerCheckSanity"
       title = "Check server sanity"
       order = "no"
       tasks = "1">
    <script language   = "java"
            java_class = "sos.scheduler.job.JobSchedulerCheckSanity"
            resource   = "1"/>
  </job>

  <releases>
    <release id="1.0" created="2006-03-30" modified="2006-03-30">
      <title>Version 1.0</title>
      <author name="Andreas Liebert" email="andreas.liebert@sos-berlin.com"/>
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">
        Initiale Auslieferung
        </div>
      </note>
      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">
        Initial Release
        </div>
      </note>
      <changes language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">
        Implementierung mit SOSConnection und hostWare.
        </div>
      </changes>
      <changes language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">
        Implementation with SOSConnection and hostWare.
        </div>
      </changes>
    </release>
  </releases>

  <resources>
    <file os="all" type="java" file="sos.scheduler.jar" id="1">
      <note language="de"><div xmlns="http://www.w3.org/1999/xhtml">Standard-Job der Auslieferung</div></note>
      <note language="en"><div xmlns="http://www.w3.org/1999/xhtml">Standard job in distribution</div></note>
    </file>
    <file os="all" type="java" file="sos.spooler.jar" id="2">
      <note language="de"><div xmlns="http://www.w3.org/1999/xhtml">Klasse Job_Impl</div></note>
      <note language="en"><div xmlns="http://www.w3.org/1999/xhtml">Class Job_Impl</div></note>
    </file>
    <file os="all" type="java" file="sos.util.jar" id="3">
      <note language="de"><div xmlns="http://www.w3.org/1999/xhtml">Klasse SOSLogger</div></note>
      <note language="en"><div xmlns="http://www.w3.org/1999/xhtml">Class SOSLogger</div></note>
    </file>
    <file os="all" type="java" file="sos.settings.jar" id="4">
      <note language="de"><div xmlns="http://www.w3.org/1999/xhtml">Klasse SOSProfileSettings</div></note>
      <note language="en"><div xmlns="http://www.w3.org/1999/xhtml">Class SOSProfileSettings</div></note>
    </file>
    <file os="win32"     type="binary" file="hostole.dll"    id="5"/>
    <file os="win32"     type="binary" file="hostjava.dll"   id="6"/>
    <file os="linux32"   type="binary" file="libhostole.so"  id="7"/>
    <file os="linux32"   type="binary" file="libhostjava.so" id="8"/>
    <file os="solaris32" type="binary" file="libhostole.so"  id="9"/>
    <file os="solaris32" type="binary" file="libhostjava.so" id="10"/>
    <file os="hpux64"    type="binary" file="libhostjava.sl" id="11"/>

    <database required="false">
      <resource name="SCHEDULER_SANITY_HISTORY" type="table">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
          Die Tabelle nimmt Historieneinträge auf: bei jedem Lauf werden
          die aktuellen Werte für Ressourcen eingefügt, die von diesem Job geprüft werden.
          </div>
        </note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
          This table contains the sanity check history: each time this job is executed
          the current values for the resources that have been checked are inserted into this table.
          </div>
        </note>
      </resource>
      <resource name="SCHEDULER_SANITY_REFERENCES" type="table">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
          Die Tabelle enthält Referenzwerte für die Prüfung von Ressourcen.
          </div>
        </note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
          This table contains the resource checking reference values.
          </div>
        </note>
      </resource>
    </database>
  </resources>

  <configuration>
    <note language="de">
      <div xmlns="http://www.w3.org/1999/xhtml">
        <p>
          Der Job kann über
        </p>
        <ul>
          <li>die Datenbank des Job Schedulers,</li>
          <li>über Einstellungen aus der Datei <code>factory.ini</code> und</li>
          <li>über Job-Parameter</li>
        </ul>
          konfiguriert werden.
        <p>
          Dabei gilt folgende Hierarchie: Job-Parameter haben Vorrang vor
          <code>factory.ini</code>, <code>factory.ini</code> vor Datenbank, Datenbank vor impliziten Job-Voreinstellungen.
        </p>
        <p>
          Der Job prüft die Ressourcen am Server für folgende Kategorien:
        </p>
        <ul>
          <li><strong>disk_space:</strong><br/>
            Überprüfung des Festplattenplatzes, der <em>subtype</em> gibt das Verzeichnis an, dessen Platz
            geprüft werden soll, <em>value</em> gibt den minimal erlaubten Wert an,
            bevor eine Warnung ausgegeben wird. Default sind 10 MB im Verzeichnis
            des Job Schedulers.
          </li>
          <li><strong>disk_space_user:</strong><br/>
            Wie <em>disk_space</em>, jedoch unter
            Einbeziehung von Quotas (verfügbarer Platz für den Job Scheduler account).
          </li>
          <li><strong>free_memory:</strong><br/>
            Überprüfung des Speichers.
            <em>value</em> gibt den minmal erlaubten Wert in Bytes an.
            <em>subtype</em> kann sein:
            <br/><br/>
            <ul>
              <li>jvm: Freier Speicher <strong>innerhalb</strong>
                der Java Virtual Machine. <strong>Außerhalb</strong>
                der Java Virtual Machine kann diese ihren Speicher nicht abbauen.
                Das heisst: hat eine JVM einmal Speicher vom Betriebssystem angefordert,
                dann gibt sie diesen während ihrer Laufzeit nicht mehr zurück.
              </li>
              <li>ram: Freier Hauptspeicher</li>
              <li>swap: Freier Swap-Speicher</li>
            </ul>
          </li>
        </ul>
      </div>
    </note>

    <note language="en">
      <div xmlns="http://www.w3.org/1999/xhtml">
        <p>
          This job may be configured using:
        </p>
        <ul>
          <li>the Job Scheduler database,</li>
          <li>settings in the <code>factory.ini</code> configuration file and</li>
          <li>job parameters</li>
        </ul>
          The following priority hierarchy applies:
          job parameters override <code>factory.ini</code> settings;
          <code>factory.ini</code> overrides database settings;
          database settings override implicit job defaults.
        <p>
          This job checks for the following resource categories:
        </p>
        <ul>
          <li><strong>disk_space:</strong><br/>
            Checks the available hard-disk space,
            <em>subtype</em> sets the directory for which the space is to be checked,
            <em>value</em> denotes the minimum value which is permitted before a warning is produced.
            The default is 10 MB in the Job Scheduler working directory.
          </li>
          <li><strong>disk_space_user:</strong><br/>
            As for disk_space, but including
            quotas (availale space for the Job Scheduler account).
          </li>
          <li><strong>free_memory:</strong><br/>
            Checks the memory.
            <em>value</em> denotes the minimum value in bytes. <em>subtype</em> is one of:
            <br/><br/>
            <ul>
              <li>jvm: free memory <strong>inside</strong> the Java Virtual Machine.
                this memory can not be released <strong>outside</strong> the Java Virtual Machine.
                This means that once the JVM has been allocated memory by the operating system,
                it will not release this memory during runtime.
              </li>
              <li>ram: free main memory</li>
              <li>swap: free swap memory</li>
            </ul>
          </li>
        </ul>
      </div>
    </note>

    <params id="job_parameter">
      <note language="de">
        <div xmlns="http://www.w3.org/1999/xhtml">
            Jeweils drei Einstellungen bilden eine Einheit. Diese tragen die Namen
            <strong>category_<em>n</em></strong>, <strong>subtype_<em>n</em></strong>, <strong>value_<em>n</em></strong> mit
            gleicher Zahl <em>n</em> für alle drei. Für weitere
            Einstellungen ist <em>n</em> zu inkrementieren. <em>n</em> muss mit 1
            beginnen, die Werte dürfen keine Lücken aufweisen.
          <p>
            Zusätzlich ist es über die Job-Parameter (nicht aber
            über den Profile oder die Datenbank) möglich, die
            Überprüfung des freien Speichers oder des freien
            Fesplattenplatzes abzuschalten. Dazu können die Parameter
            <em>check_disk_space</em>, <em>check_disk_space_user</em> bzw. <em>check_free_memory</em> mit dem Wert <em>false</em>
            belegt werden.
          </p>
          <p>
            Beispiel für Parameterangaben in der Job-Konfiguration:
            <br/><br/>
            &#160;&#160;&#160; &lt;params&gt;
            <br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="category_1" value="disk_space"/&gt;
            <br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="subtype_1" value="/"/&gt;
            <br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="value_1" value="2300000"/&gt;
            <br/><br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="category_2" value="disk_space/&gt;
            <br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="subtype_2" value="/tmp"/&gt;
            <br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="value_2" value="100000"/&gt;
            <br/>
            &#160;&#160;&#160; &lt;/params&gt;
          </p>
        </div>
      </note>

      <note language="en">
        <div xmlns="http://www.w3.org/1999/xhtml">
            Three settings are required to specify each resource to be checked.
            These are
            <strong>category_<em>n</em></strong>, <strong>subtype_<em>n</em></strong> and <strong>value_<em>n</em></strong>,
            where all three settings have the same number <em>n</em>.
            The settings <em>n</em> must be incremented when checking subsequent resources:
            <em>n</em> has to start with 1 and may not show any gaps.
          <p>
            Note that the job parameters (but not the profile or the database) can
            be used to turn off memory or hard-disk-space checking.
            This is done by setting the parameters
            <em>check_disk_space</em>, <em>check_disk_space_user</em> or <em>check_free_memory</em>
            to <em>false</em>.
          </p>
          <p>
            Example for settings in the job configuration:
            <br/><br/>
            &#160;&#160;&#160; &lt;params&gt;
            <br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="category_1" value="disk_space"/&gt;
            <br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="subtype_1" value="/"/&gt;
            <br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="value_1" value="2300000"/&gt;
            <br/><br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="category_2" value="disk_space/&gt;
            <br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="subtype_2" value="/tmp"/&gt;
            <br/>
            &#160;&#160;&#160; &#160;&#160;&#160; &lt;param name="value_2" value="100000"/&gt;
            <br/>
            &#160;&#160;&#160; &lt;/params&gt;
          </p>
        </div>
      </note>

      <param name="check_disk_space" default_value="true" required="false">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Parameter wird verwendet, um die Prüfung des Plattenplatzes abzuschalten, wenn der Wert <em>false</em>
            übergeben wird.
					</div>
				</note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter is used to exclude disk space checking from the sanity check if the value <em>false</em>
            is given.
					</div>
				</note>
			</param>

      <param name="check_disk_space_user" default_value="true" required="false">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Parameter wird verwendet, um die Prüfung des Plattenplatzes
            für die Benutzerkennung des Job Schedulers
            abzuschalten, wenn der Wert <em>false</em> übergeben wird.
					</div>
				</note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter is used to exclude disk space checking
            of the Job Scheduler account
            from the sanity check if the value <em>false</em> is given.
					</div>
				</note>
			</param>

      <param name="check_free_memory" default_value="true" required="false">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Parameter wird verwendet, um die Prüfung des Hauptspeicherverbrauchs
            abzuschalten, wenn der Wert <em>false</em> übergeben wird.
					</div>
				</note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter is used to exclude main memory checking
            from the sanity check if the value <em>false</em> is given.
					</div>
				</note>
			</param>

      <param name="category_1" default_value="" required="false">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Parameter gibt die Kategorie an, die geprüft wird. Mögliche Kategorien sind
            <em>disk_space</em>, <em>disk_space_user</em> oder <em>free_memory</em>.
            <br/><br/>
            Für die folgenden Parameter <em>subtype_1</em> und <em>value_1</em>
            wird der jeweils selbe iterierte Wert <em>1</em> im Namen verwendet.
            Dieser Wert muss mit 1 beginnen und fortlaufend zählen, z.B. <em>subtype_2</em>, <em>subtype_3</em>.
					</div>
				</note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter specifies the category used for sanity checking, possible values are
            <em>disk_space</em>, <em>disk_space_user</em> or <em>free_memory</em>.
            <br/><br/>
						For the following set of the parameters <em>subtype_1</em> and <em>value_1</em>
						the same iterated value <em>1</em> must be used.
						This iterator has to start with 1 and may not show any gaps, e.g. <em>subtype_2</em>, <em>subtype_3</em>.
					</div>
				</note>
			</param>

      <param name="subtype_1" default_value="" required="false">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Parameter gibt die Unterkategorie an, die geprüft wird. Mögliche Unterkategorien sind für die
            <ul>
              <li>Kategorien <em>disk_space</em> und <em>disk_space_user</em><br/>
              der Verzeichnisname, z.B. "." für das aktuelle Verzeichnis.</li>
            	<li>Kategorie <em>free_memory</em><br/> die Werte <em>ram</em>, <em>swap</em> und <em>jvm</em>.</li>
            </ul>
					</div>
				</note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter specifies the subcategory
            used for sanity checking, possible values are for
            <ul>
              <li>categories <em>disk_space</em> and <em>disk_space_user</em><br/>
              the directory name, e.g. "." for the working directory.</li>
            	<li>category <em>free_memory</em><br/> the values <em>ram</em>, <em>swap</em> und <em>jvm</em>.</li>
            </ul>
					</div>
				</note>
			</param>

      <param name="value_1" default_value="" required="false">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Der Parameter gibt den Schwellenwert an, der geprüft wird. Mögliche Werte hängen von der Kategorie ab:
            <ul>
              <li>Kategorie: disk_space<br/>der freie Plattenplatz in Byte</li>
              <li>Kategorie: disk_sapce_user<br/>der freie Plattenplatz der Benutzerkennung in Byte</li>
              <li>Kategorie: free_memory<br/>der freie Hauptspeicher in Abhängigkeit von der gewählten
              	Unterkategorie <em>ram</em>, <em>swap</em> oder <em>jvm</em>.</li>
             </ul>
					</div>
				</note>
        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            This parameter specifies the value of the threshold that is checked. Possible values
            depend on the category:
            <ul>
              <li>category: disk_space<br/>free disk space in byte</li>
              <li>category: disk_sapce_user<br/>free disk space of the user account (quota) in byte</li>
              <li>category: free_memory<br/>free memory in byte for one of the subcategories
              	<em>ram</em>, <em>swap</em> oder <em>jvm</em>.</li>
             </ul>
					</div>
				</note>
			</param>
    </params>

    <settings>
      <profile name="default">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Nur über die Konfigurationsdatei können mit dem Parameter <em>delay_after_error</em> Wiederholungsintervalle
            für den Fehlerfall gesetzt werden (siehe Beispiel).
            <p>
              Beispiel für Parameterangaben in der Konfigurationsdatei <code>factory.ini</code>:
              <br/><br/>
              <code>
                [job scheduler_check_sanity]
                <br/>
                category_1 &#160;&#160;&#160;&#160; = disk_space
                <br/>
                subtype_1 &#160; &#160;&#160;&#160; = /
                <br/>
                value_1 &#160;&#160;&#160;&#160;&#160;&#160;&#160; = 2300000
                <br/><br/>
                category_2 &#160;&#160;&#160;&#160; = disk_space
                <br/>
                subtype_2 &#160; &#160;&#160;&#160; = /tmp
                <br/>
                value_2 &#160;&#160;&#160;&#160;&#160;&#160;&#160; = 100000
                <br/>
                ;delay processing after error: &lt;number of errors&gt;:&lt;delay interval in seconds or stop&gt;;...
                <br/>
                delay_after_error = 1:60;5:600;10:1800;20:3600;60:stop
              </code>
            </p>
            <p>
              <em>delay_after_error</em> ist wie folgt zu interpretieren:
              nach dem ersten Fehler je 60s warten, ab dem fünften Fehler
              je 600s warten ... nach dem 60. Fehler den Job stoppen.
            </p>
          </div>
        </note>

        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            Note that the wait intervals in the event of an error can be
            configured only in the profile with the <em>delay_after_error</em> parameter (see example).
            <p>
              Example for parameters in the <code>factory.ini</code> configuration file:
              <br/><br/>
              <code>
                [job scheduler_check_sanity]
                <br/>
                category_1 &#160;&#160;&#160;&#160; = disk_space
                <br/>
                subtype_1 &#160; &#160;&#160;&#160; = /
                <br/>
                value_1 &#160;&#160;&#160;&#160;&#160;&#160;&#160; = 2300000
                <br/><br/>
                category_2 &#160;&#160;&#160;&#160; = disk_space
                <br/>
                subtype_2 &#160; &#160;&#160;&#160; = /tmp
                <br/>
                value_2 &#160;&#160;&#160;&#160;&#160;&#160;&#160; = 100000
                <br/>
                ;delay processing after error: &lt;number of errors&gt;:&lt;delay interval in seconds or stop&gt;;...
                <br/>
                delay_after_error = 1:60;5:600;10:1800;20:3600;60:stop
              </code>
            </p>
            <p>
              The <em>delay_after_error</em> parameter in the example above has the following meaning:
              wait 60s per retry after the first error,
              wait 600s per retry after the fifth error ... stop the job after 60 errors.
            </p>
          </div>
        </note>

        <section name="Job Section" reference="job_parameter"/>
      </profile>

      <connection name="default">
        <note language="de">
          <div xmlns="http://www.w3.org/1999/xhtml">
            In der Tabelle SCHEDULER_SANITY_REFERENCES existieren entsprechende
            Felder "CATEGORY", "SUBTYPE", "VALUE". Zusätzlich sollte die ID
            des entsprechenden Job Schedulers angegeben werden, ist sie leer, gelten
            die Einstellungen für alle Job Scheduler, die diese Datenbank
            verwenden.
            <br/><br/>
            Beispiel für entsprechende INSERT-Statements:
            <p>
            	<code>
              	INSERT INTO SCHEDULER_SANITY_REFERENCES ( "SPOOLER_ID", "CATEGORY",
              	"SUBTYPE", "VALUE" ) VALUES ( 'spooler', 'free_memory','jvm', '100000');
              	<br/>
              	INSERT INTO SCHEDULER_SANITY_REFERENCES ( "SPOOLER_ID", "CATEGORY",
              	"SUBTYPE", "VALUE" ) VALUES ( 'spooler', 'disk_space', '/', '2000000' );
            	</code>
            </p>
          </div>
        </note>

        <note language="en">
          <div xmlns="http://www.w3.org/1999/xhtml">
            The table SCHEDULER_SANITY_REFERENCES has fields named "CATEGORY", "SUBTYPE", "VALUE".
            There is also a field "ID" which defines the Job Scheduler that the setting applies to.
            If "ID" is empty, then the setting applies to all Job Schedulers that are using this database.
            <br/><br/>
            Example for corresponding INSERT-Statements:
            <p>
            	<code>
              	INSERT INTO SCHEDULER_SANITY_REFERENCES ( "SPOOLER_ID", "CATEGORY",
	              "SUBTYPE", "VALUE" ) VALUES ( 'spooler', 'free_memory','jvm', '100000');
  	            <br/>
    	          INSERT INTO SCHEDULER_SANITY_REFERENCES ( "SPOOLER_ID", "CATEGORY",
      	        "SUBTYPE", "VALUE" ) VALUES ( 'spooler', 'disk_space', '/', '2000000' );
        	    </code>
        	  </p>
          </div>
        </note>

        <application name="Table SCHEDULER_SANITY_REFERENCES">
        	<section name="SCHEDULER_SANITY_REFERENCES" reference="job_parameter"/>
        </application>
      </connection>
    </settings>
  </configuration>

  <documentation language="de">
    <div xmlns="http://www.w3.org/1999/xhtml">
      Der Job wird verwendet, um Ressourcen am Server System zu prüfen, auf dem der Job Scheduler
      betrieben wird, d.h. Plattenplatz und Hauptspeicher.
      <br/><br/>
      Die Einstellungen teilen sich auf in Kategorien mit Unterkategorien.
      Zu jedem Paar aus Kategorie und Unterkategorie wird ein Wert (<em>value</em>) angegeben.
      <br/><br/>
      Der Wert dient als Referenzwert, der nicht unterschritten werden
      darf. Wird der Referenzwert unterschritten, verschickt der Job eine eMail an den
      Empfänger, der in der Job Scheduler Konfiguration für
      <code>log_mail_to</code> eingetragen ist. Wird der Job Scheduler mit Datenbank betrieben,
      wird die Tabelle SCHEDULER_SANITY_HISTORY verwendet, um die Ergebnisse
      des Sanity Checks zu archivieren.
    </div>
  </documentation>

  <documentation language="en">
    <div xmlns="http://www.w3.org/1999/xhtml">
      This job is used to check resources of the server system that operates the Job Scheduler,
      i.e. disk space and memory.
      <br/><br/>
      The job settings are divided into categories and subcategories.
      Each category and subcategory settings pair is given a <em>value</em>.
      <br/><br/>
      This value is used as a reference below which metered values must not fall.
      If a metered value does fall below a given reference
      value, then an email is sent to the recipient(s) configured on the Job Scheduler
      (<code>log_mail_to</code>). If the Job Scheduler uses a database, then the results of the
      sanity check are archived in the SCHEDULER_SANITY_HISTORY table.
    </div>
  </documentation>

</description>