Changeset 3363


Ignore:
Timestamp:
May 22, 2007, 10:48:49 PM (15 years ago)
Author:
Nicklas Nordborg
Message:

References #598

Location:
trunk/doc/src/docbook/appendix
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/appendix/base.config.xml

    r3347 r3363  
    349349      The internal job queue is a simple queue that executes jobs more or
    350350      less in the order they were added to the queue. To make sure long-running
    351       jobs don't block the queue, there are four slots that uses to the
     351      jobs don't block the queue, there are four slots that uses the
    352352      expected execution time to decide if a job should be allowed to execute
    353353      or not.
  • trunk/doc/src/docbook/appendix/jobagent.properties.xml

    r3334 r3363  
    3131 
    3232  <para>
    33     This document is only available in the old format.
    34     See <ulink url="http://base.thep.lu.se/chrome/site/doc/admin/jobagent.properties.html"
    35       >http://base.thep.lu.se/chrome/site/doc/admin/jobagent.properties.html</ulink>.
     33    The <filename>jobagent.properties</filename> file is the main configuration file
     34    for job agents. It is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename>
     35    directory.
    3636  </para>
    3737
     38  <simplesect id="appendix.jobagent.properties.base">
     39    <title>BASE settings</title>
     40   
     41    <para>
     42      This section describes the configuration parameters that
     43      are used by the job agent to get access to the BASE server.
     44    </para>
     45   
     46    <variablelist>
     47    <varlistentry>
     48      <term><property>agent.user</property></term>
     49      <listitem>
     50        <para>
     51          Required. The BASE user account the job agent should use to login
     52          to the BASE server. The user account must have sufficient privileges
     53          to access jobs and job agents. The <emphasis>Job agent</emphasis>
     54          role is a predefined role with all permissions a job agent needs.
     55          There is also a predefined user account with the login
     56          <emphasis>jobagent</emphasis>. This account is disabled by default and
     57          has to be enabled and given a password before it can be used.
     58        </para>
     59      </listitem>
     60    </varlistentry>
     61
     62    <varlistentry>
     63      <term><property>agent.password</property></term>
     64      <listitem>
     65        <para>
     66          Required. The password for the user account.
     67        </para>
     68      </listitem>
     69    </varlistentry>
     70
     71    <varlistentry>
     72      <term><property>agent.id</property></term>
     73      <listitem>
     74        <para>
     75          Required. A unique ID that identifies this job agent among other
     76          job agent. If multiple job agents are installed each job agent
     77          should have it's own unique ID.
     78        </para>
     79      </listitem>
     80    </varlistentry>
     81   
     82    <varlistentry>
     83      <term><property>agent.name</property></term>
     84      <listitem>
     85        <para>
     86          Optional. The name of the job agent. If not specified the ID is used.
     87          The name is only used when registering the job agent with the BASE
     88          server.
     89        </para>
     90      </listitem>
     91    </varlistentry>
     92   
     93    <varlistentry>
     94      <term><property>agent.description</property></term>
     95      <listitem>
     96        <para>
     97          Optional. A description of the job agent. This is only used when
     98          registering the job agent.
     99        </para>
     100      </listitem>
     101    </varlistentry>
     102    </variablelist>
     103   
     104  </simplesect>
     105
     106  <simplesect id="appendix.jobagent.properties.jobagent">
     107    <title>Job agent server settings</title>
     108   
     109    <para>
     110      This section describes the configuration parameters that
     111      affect the job agent server itself.
     112    </para>
     113   
     114    <variablelist>
     115    <varlistentry>
     116      <term><property>agent.port</property></term>
     117      <listitem>
     118        <para>
     119          Optional. The port the job agent listens to for control requests.
     120          Control requests are used for starting, stopping, pausing and getting
     121          status information from the job agent. It is also used by the
     122          <command>jobagent.sh</command> script to control
     123          the local job agent. The default value is 47822.
     124        </para>
     125      </listitem>
     126    </varlistentry>
     127   
     128    <varlistentry>
     129      <term><property>agent.remotecontrol</property></term>
     130      <listitem>
     131        <para>
     132          Optional. A comma-separated list of ip addresses or names of
     133          computers that are allowed to send control requests to the job
     134          agent. If no value is specified, only the local host is allowed
     135          to connect. It is recommended that the web server is added to
     136          the list if the job agent is not running on the same server as
     137          the web server.
     138        </para>
     139      </listitem>
     140    </varlistentry>
     141   
     142    <varlistentry>
     143      <term><property>agent.allowremote.stop</property></term>
     144      <listitem>
     145        <para>
     146          Optional. If the <command>stop</command> command should be
     147          accepted from remote hosts specified in the <property>agent.remotecontrol</property> setting.
     148          If <constant>false</constant>, which is the default value,
     149          only the local host is allowed to stop the job agent.
     150        </para>
     151       
     152        <note>
     153          <para>
     154          Once the job agent has been stopped it can't be started
     155          by remote control. You must use the <command>jobagent.sh</command>
     156          script for this.
     157          </para>
     158        </note>
     159       
     160      </listitem>
     161    </varlistentry>
     162   
     163    <varlistentry>
     164      <term><property>agent.allowremote.start</property></term>
     165      <listitem>
     166        <para>
     167          Optional. If the <command>start</command> command should be
     168          accepted from remote hosts specified in the <property>agent.remotecontrol</property> setting.
     169          If <constant>false</constant>, only the local host is allowed to
     170          start the job agent. The default value is <constant>true</constant>.
     171        </para>
     172      </listitem>
     173    </varlistentry>
     174
     175    <varlistentry>
     176      <term><property>agent.allowremote.pause</property></term>
     177      <listitem>
     178        <para>
     179          Optional. If the <command>pause</command> command should be
     180          accepted from remote hosts specified in the <property>agent.remotecontrol</property> setting.
     181          If <constant>false</constant>, only the local host is allowed to
     182          pause the job agent. The default value is <constant>true</constant>.
     183        </para>
     184      </listitem>
     185    </varlistentry>
     186    </variablelist>
     187
     188  </simplesect>
     189
     190  <simplesect id="appendix.jobagent.properties.execution">
     191    <title>Job execution settings</title>
     192   
     193    <para>
     194      This section describes the configuration parameters that
     195      affect the execution of jobs.
     196    </para>
     197   
     198    <variablelist>
     199    <varlistentry>
     200      <term><property>agent.executor.class</property></term>
     201      <listitem>
     202        <para>
     203          The name of the Java class that handles the actual execution of jobs.
     204          The default implementation for a job agent ships three
     205          implementations:
     206         
     207          <itemizedlist>
     208          <listitem>
     209            <para>
     210            <classname>net.sf.basedb.clients.jobagent.executors.ProcessJobExecutor</classname>:
     211            Executes the job in an
     212            external process. This is the recommended executor and is the default
     213            choice if no value has been specified. With this executor a
     214            misbehaving plugin doesn't affect the job agent or other jobs.
     215            The drawback is that since a new virtual machine has to be started,
     216            more memory is required and the startup time can be long.
     217            </para>
     218          </listitem>
     219         
     220          <listitem>
     221            <para>
     222            <classname>net.sf.basedb.clients.jobagent.executors.ThreadJobExecutor</classname>:     
     223            Executes the job in a separate thread. This is only recommended
     224            for plugins that are  trusted and safe. A misbehaving plugin can affect the job agent
     225            and other jobs, but the statup time is short and less memory
     226            is used.
     227            </para>
     228          </listitem>
     229         
     230          <listitem>
     231            <para>
     232            <classname>net.sf.basedb.clients.jobagent.executors.DummyJobExecutor</classname>:     
     233            Doesn't execute the job. It only marks the job as beeing executed,
     234            and after waiting some time, as finished successfully.
     235            Use it for debugging the job agent.
     236            </para>
     237          </listitem>
     238          </itemizedlist>
     239
     240          It is possible to create your own implemetnation of a job executor.
     241          Create a class that implements the
     242          <interfacename>net.sf.basedb.clients.jobagent.JobExecutor</interfacename>
     243          interface.         
     244        </para>
     245      </listitem>
     246    </varlistentry>
     247   
     248    <varlistentry>
     249      <term><property>agent.executor.process.java</property></term>
     250      <listitem>
     251        <para>
     252          Optional. The path to the Java executable used by the
     253          <classname>ProcessJobExecutor</classname>. If not specified the
     254          <envar>JAVA_HOME</envar> environment variable will be checked.
     255          As a last resort <command>java</command> is used without path
     256          information to let the operating system find the default
     257          installation.
     258        </para>
     259      </listitem>
     260    </varlistentry>
     261
     262    <varlistentry>
     263      <term><property>agent.executor.process.options</property></term>
     264      <listitem>
     265        <para>
     266          Optional. Additional command line options to the Java executable.
     267          Do not add memory options (<option>-Mx</option> or
     268          <option>-Ms</option>), it will be added automatically by the
     269          executor. This setting is used by the
     270          <classname>ProcessJobExecutor</classname> only.
     271        </para>
     272      </listitem>
     273    </varlistentry>
     274   
     275    <varlistentry>
     276      <term><property>agent.executor.dummy.wait</property></term>
     277      <listitem>
     278        <para>
     279          Optional. Number of seconds the <classname>DummyJobExecutor</classname> should
     280          wait before returning from the "job execution". The executor first sets
     281          the progress to 50% then waits the specified number of seconds before
     282          setting the job to completed. If no value is specified it returns immediately.
     283        </para>
     284      </listitem>
     285    </varlistentry>
     286
     287    <varlistentry>
     288      <term><property>agent.checkinterval</property></term>
     289      <listitem>
     290        <para>
     291          Optional. Number of seconds between checks to the database
     292          for jobs that are waiting for execution. The default value
     293          is 30 seconds.
     294        </para>
     295      </listitem>
     296    </varlistentry>
     297   
     298    </variablelist>
     299  </simplesect>
     300 
     301  <simplesect id="appendix.jobagent.properties.slots">
     302    <title>Slots and priorities</title>
     303   
     304    <para>
     305      The job agent doesn't execute any number of jobs at the same time.
     306      This would sooner or later break the server. Instead, it uses a
     307      simple system with four different slots. Each slot is reserved for
     308      jobs that are estimated to be finished in a certain amount of time.
     309      The exception is that a quick job may use a slot with longer expected time
     310      since that will not block the slot very long.
     311    </para>
     312   
     313    <para>
     314      With each slot is also associated a thread priority. The priority
     315      is a value between 1 and 10 as defined by the
     316      <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Thread.html"
     317        ><classname>java.lang.Thread</classname></ulink> class.
     318    </para>
     319   
     320    <informaltable frame="all" align="center">
     321    <tgroup cols="3">
     322      <colspec colname="property" />
     323      <colspec colname="default" align="center"/>
     324      <colspec colname="time" />
     325      <thead>
     326        <row>
     327          <entry>Property</entry>
     328          <entry>Default value</entry>
     329          <entry>Estimated execution time</entry>
     330        </row>
     331      </thead>
     332     
     333      <tbody>
     334        <row>
     335          <entry>agent.shortest.slots</entry>
     336          <entry>1</entry>
     337          <entry morerows="1">&lt; 1 minute</entry>
     338        </row>
     339        <row>
     340          <entry>agent.shortest.priority</entry>
     341          <entry>4</entry>
     342        </row>
     343        <row>
     344          <entry>agent.short.slots</entry>
     345          <entry>1</entry>
     346          <entry morerows="1">&lt; 10 minutes</entry>
     347        </row>
     348        <row>
     349          <entry>agent.short.priority</entry>
     350          <entry>4</entry>
     351        </row>
     352        <row>
     353          <entry>agent.medium.slots</entry>
     354          <entry>2</entry>
     355          <entry morerows="1">&lt; 1 hour</entry>
     356        </row>
     357        <row>
     358          <entry>agent.medium.priority</entry>
     359          <entry>3</entry>
     360        </row>
     361        <row>
     362          <entry>agent.long.slots</entry>
     363          <entry>2</entry>
     364          <entry morerows="1">&gt; 1 hour</entry>
     365        </row>
     366        <row>
     367          <entry>agent.long.priority</entry>
     368          <entry>3</entry>
     369        </row>
     370      </tbody>
     371    </tgroup>
     372    </informaltable>
     373   
     374
     375  </simplesect>
     376
     377
    38378</appendix>
    39379
Note: See TracChangeset for help on using the changeset viewer.