Changeset 3363

Timestamp:

May 22, 2007, 10:48:49 PM (16 years ago)

Author:

Nicklas Nordborg

Message:

References #598

Location:

trunk/doc/src/docbook/appendix

Files:

• base.config.xml (modified) (1 diff)
• jobagent.properties.xml (modified) (1 diff)

trunk/doc/src/docbook/appendix/base.config.xml

@@ -349 +349 @@
       The internal job queue is a simple queue that executes jobs more or
       less in the order they were added to the queue. To make sure long-running
-      jobs don't block the queue, there are four slots that uses to the
+      jobs don't block the queue, there are four slots that uses the
       expected execution time to decide if a job should be allowed to execute 
       or not.

trunk/doc/src/docbook/appendix/jobagent.properties.xml

@@ -31 +31 @@
   
   <para>
-    This document is only available in the old format.
-    See <ulink url="http://base.thep.lu.se/chrome/site/doc/admin/jobagent.properties.html"
-      >http://base.thep.lu.se/chrome/site/doc/admin/jobagent.properties.html</ulink>.
+    The <filename>jobagent.properties</filename> file is the main configuration file
+    for job agents. It is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename>
+    directory.
   </para>
 
+  <simplesect id="appendix.jobagent.properties.base">
+    <title>BASE settings</title>
+    
+    <para>
+      This section describes the configuration parameters that 
+      are used by the job agent to get access to the BASE server.
+    </para>
+    
+    <variablelist>
+    <varlistentry>
+      <term><property>agent.user</property></term>
+      <listitem>
+        <para>
+          Required. The BASE user account the job agent should use to login 
+          to the BASE server. The user account must have sufficient privileges 
+          to access jobs and job agents. The <emphasis>Job agent</emphasis>
+          role is a predefined role with all permissions a job agent needs.
+          There is also a predefined user account with the login 
+          <emphasis>jobagent</emphasis>. This account is disabled by default and
+          has to be enabled and given a password before it can be used.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><property>agent.password</property></term>
+      <listitem>
+        <para>
+          Required. The password for the user account.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><property>agent.id</property></term>
+      <listitem>
+        <para>
+          Required. A unique ID that identifies this job agent among other 
+          job agent. If multiple job agents are installed each job agent 
+          should have it's own unique ID.
+        </para>
+      </listitem>
+    </varlistentry>
+    
+    <varlistentry>
+      <term><property>agent.name</property></term>
+      <listitem>
+        <para>
+          Optional. The name of the job agent. If not specified the ID is used. 
+          The name is only used when registering the job agent with the BASE 
+          server.
+        </para>
+      </listitem>
+    </varlistentry>
+    
+    <varlistentry>
+      <term><property>agent.description</property></term>
+      <listitem>
+        <para>
+          Optional. A description of the job agent. This is only used when 
+          registering the job agent.
+        </para>
+      </listitem>
+    </varlistentry>
+    </variablelist>
+    
+  </simplesect>
+
+  <simplesect id="appendix.jobagent.properties.jobagent">
+    <title>Job agent server settings</title>
+    
+    <para>
+      This section describes the configuration parameters that 
+      affect the job agent server itself.
+    </para>
+    
+    <variablelist>
+    <varlistentry>
+      <term><property>agent.port</property></term>
+      <listitem>
+        <para>
+          Optional. The port the job agent listens to for control requests. 
+          Control requests are used for starting, stopping, pausing and getting 
+          status information from the job agent. It is also used by the 
+          <command>jobagent.sh</command> script to control 
+          the local job agent. The default value is 47822.
+        </para>
+      </listitem>
+    </varlistentry>
+    
+    <varlistentry>
+      <term><property>agent.remotecontrol</property></term>
+      <listitem>
+        <para>
+          Optional. A comma-separated list of ip addresses or names of 
+          computers that are allowed to send control requests to the job 
+          agent. If no value is specified, only the local host is allowed 
+          to connect. It is recommended that the web server is added to 
+          the list if the job agent is not running on the same server as
+          the web server.
+        </para>
+      </listitem>
+    </varlistentry>
+    
+    <varlistentry>
+      <term><property>agent.allowremote.stop</property></term>
+      <listitem>
+        <para>
+          Optional. If the <command>stop</command> command should be 
+          accepted from remote hosts specified in the <property>agent.remotecontrol</property> setting. 
+          If <constant>false</constant>, which is the default value,
+          only the local host is allowed to stop the job agent.
+        </para>
+        
+        <note>
+          <para>
+          Once the job agent has been stopped it can't be started
+          by remote control. You must use the <command>jobagent.sh</command>
+          script for this.
+          </para>
+        </note>
+        
+      </listitem>
+    </varlistentry>
+    
+    <varlistentry>
+      <term><property>agent.allowremote.start</property></term>
+      <listitem>
+        <para>
+          Optional. If the <command>start</command> command should be 
+          accepted from remote hosts specified in the <property>agent.remotecontrol</property> setting. 
+          If <constant>false</constant>, only the local host is allowed to 
+          start the job agent. The default value is <constant>true</constant>.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><property>agent.allowremote.pause</property></term>
+      <listitem>
+        <para>
+          Optional. If the <command>pause</command> command should be 
+          accepted from remote hosts specified in the <property>agent.remotecontrol</property> setting. 
+          If <constant>false</constant>, only the local host is allowed to 
+          pause the job agent. The default value is <constant>true</constant>.
+        </para>
+      </listitem>
+    </varlistentry>
+    </variablelist>
+
+  </simplesect>
+
+  <simplesect id="appendix.jobagent.properties.execution">
+    <title>Job execution settings</title>
+    
+    <para>
+      This section describes the configuration parameters that 
+      affect the execution of jobs.
+    </para>
+    
+    <variablelist>
+    <varlistentry>
+      <term><property>agent.executor.class</property></term>
+      <listitem>
+        <para>
+          The name of the Java class that handles the actual execution of jobs. 
+          The default implementation for a job agent ships three 
+          implementations:
+          
+          <itemizedlist>
+          <listitem>
+            <para>
+            <classname>net.sf.basedb.clients.jobagent.executors.ProcessJobExecutor</classname>: 
+            Executes the job in an 
+            external process. This is the recommended executor and is the default
+            choice if no value has been specified. With this executor a 
+            misbehaving plugin doesn't affect the job agent or other jobs.
+            The drawback is that since a new virtual machine has to be started,
+            more memory is required and the startup time can be long.
+            </para>
+          </listitem>
+          
+          <listitem>
+            <para>
+            <classname>net.sf.basedb.clients.jobagent.executors.ThreadJobExecutor</classname>:      
+            Executes the job in a separate thread. This is only recommended 
+            for plugins that are  trusted and safe. A misbehaving plugin can affect the job agent 
+            and other jobs, but the statup time is short and less memory 
+            is used.
+            </para>
+          </listitem>
+          
+          <listitem>
+            <para>
+            <classname>net.sf.basedb.clients.jobagent.executors.DummyJobExecutor</classname>:     
+            Doesn't execute the job. It only marks the job as beeing executed, 
+            and after waiting some time, as finished successfully. 
+            Use it for debugging the job agent. 
+            </para>
+          </listitem>
+          </itemizedlist>
+
+          It is possible to create your own implemetnation of a job executor. 
+          Create a class that implements the 
+          <interfacename>net.sf.basedb.clients.jobagent.JobExecutor</interfacename>
+          interface.          
+        </para>
+      </listitem>
+    </varlistentry>
+    
+    <varlistentry>
+      <term><property>agent.executor.process.java</property></term>
+      <listitem>
+        <para>
+          Optional. The path to the Java executable used by the 
+          <classname>ProcessJobExecutor</classname>. If not specified the 
+          <envar>JAVA_HOME</envar> environment variable will be checked. 
+          As a last resort <command>java</command> is used without path 
+          information to let the operating system find the default 
+          installation.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><property>agent.executor.process.options</property></term>
+      <listitem>
+        <para>
+          Optional. Additional command line options to the Java executable. 
+          Do not add memory options (<option>-Mx</option> or 
+          <option>-Ms</option>), it will be added automatically by the 
+          executor. This setting is used by the 
+          <classname>ProcessJobExecutor</classname> only.
+        </para>
+      </listitem>
+    </varlistentry>
+    
+    <varlistentry>
+      <term><property>agent.executor.dummy.wait</property></term>
+      <listitem>
+        <para>
+          Optional. Number of seconds the <classname>DummyJobExecutor</classname> should 
+          wait before returning from the "job execution". The executor first sets 
+          the progress to 50% then waits the specified number of seconds before 
+          setting the job to completed. If no value is specified it returns immediately.
+        </para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term><property>agent.checkinterval</property></term>
+      <listitem>
+        <para>
+          Optional. Number of seconds between checks to the database 
+          for jobs that are waiting for execution. The default value
+          is 30 seconds.
+        </para>
+      </listitem>
+    </varlistentry>
+    
+    </variablelist>
+  </simplesect>
+  
+  <simplesect id="appendix.jobagent.properties.slots">
+    <title>Slots and priorities</title>
+    
+    <para>
+      The job agent doesn't execute any number of jobs at the same time.
+      This would sooner or later break the server. Instead, it uses a
+      simple system with four different slots. Each slot is reserved for
+      jobs that are estimated to be finished in a certain amount of time.
+      The exception is that a quick job may use a slot with longer expected time
+      since that will not block the slot very long. 
+    </para>
+    
+    <para>
+      With each slot is also associated a thread priority. The priority
+      is a value between 1 and 10 as defined by the 
+      <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Thread.html"
+        ><classname>java.lang.Thread</classname></ulink> class.
+    </para>
+    
+    <informaltable frame="all" align="center">
+    <tgroup cols="3">
+      <colspec colname="property" />
+      <colspec colname="default" align="center"/>
+      <colspec colname="time" />
+      <thead>
+        <row>
+          <entry>Property</entry>
+          <entry>Default value</entry>
+          <entry>Estimated execution time</entry>
+        </row>
+      </thead>
+      
+      <tbody>
+        <row>
+          <entry>agent.shortest.slots</entry>
+          <entry>1</entry>
+          <entry morerows="1">&lt; 1 minute</entry>
+        </row>
+        <row>
+          <entry>agent.shortest.priority</entry>
+          <entry>4</entry>
+        </row>
+        <row>
+          <entry>agent.short.slots</entry>
+          <entry>1</entry>
+          <entry morerows="1">&lt; 10 minutes</entry>
+        </row>
+        <row>
+          <entry>agent.short.priority</entry>
+          <entry>4</entry>
+        </row>
+        <row>
+          <entry>agent.medium.slots</entry>
+          <entry>2</entry>
+          <entry morerows="1">&lt; 1 hour</entry>
+        </row>
+        <row>
+          <entry>agent.medium.priority</entry>
+          <entry>3</entry>
+        </row>
+        <row>
+          <entry>agent.long.slots</entry>
+          <entry>2</entry>
+          <entry morerows="1">&gt; 1 hour</entry>
+        </row>
+        <row>
+          <entry>agent.long.priority</entry>
+          <entry>3</entry>
+        </row>
+      </tbody>
+    </tgroup>
+    </informaltable>
+    
+
+  </simplesect>
+
+
 </appendix>