source: trunk/doc/src/docbook/appendix/jobagent.properties.xml @ 3413

Last change on this file since 3413 was 3413, checked in by Martin Svensson, 14 years ago

Removed 'term' element inside 'listitem' - not supported in the xslt-stylesheets

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 11.9 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE appendix PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: jobagent.properties.xml 3413 2007-05-30 15:44:22Z martin $
7 
8  Copyright (C) Authors contributing to this file.
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17 
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<appendix id="appendix.jobagent.properties">
30  <title>jobagent.properties reference</title>
31 
32  <para>
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.
36  </para>
37
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 used by the job agent to log on
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 user name
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 job agent 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 agents. 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.pause</property></term>
165      <listitem>
166        <para>
167          Optional. If the <command>pause</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          pause the job agent. The default value is <constant>true</constant>.
171        </para>
172      </listitem>
173    </varlistentry>
174   
175    <varlistentry>
176      <term><property>agent.allowremote.start</property></term>
177      <listitem>
178        <para>
179          Optional, valid only when job agent is paused. If
180          the <command>start</command> command should be accepted from
181          remote hosts specified in
182          the <property>agent.remotecontrol</property> setting.
183          If <constant>false</constant>, only the local host is
184          allowed to start the job agent when it is paused. The
185          default value is <constant>true</constant>.
186        </para>
187      </listitem>
188    </varlistentry>
189    </variablelist>
190
191  </simplesect>
192
193  <simplesect id="appendix.jobagent.properties.execution">
194    <title>Job execution settings</title>
195   
196    <para>
197      This section describes the configuration parameters that
198      affect the execution of jobs.
199    </para>
200   
201    <variablelist>
202    <varlistentry>
203      <term><property>agent.executor.class</property></term>
204      <listitem>
205        <para>
206          The name of the Java class that handles the actual execution of jobs.
207          The default implementation for a job agent ships three
208          implementations:
209         
210          <itemizedlist>
211          <listitem>           
212            <para>
213            <classname>net.sf.basedb.clients.jobagent.executors.ProcessJobExecutor</classname>:
214            Executes the job in an
215            external process. This is the recommended executor and is the default
216            choice if no value has been specified. With this executor, a
217            misbehaving plugin doesn't affect the job agent or other jobs.
218            The drawback is that since a new virtual machine has to be started,
219            more memory is required and the start up time can be long.
220            </para>
221          </listitem>
222         
223          <listitem>
224            <para>
225            <classname>net.sf.basedb.clients.jobagent.executors.ThreadJobExecutor</classname>:     
226            Executes the job in a separate thread. This is only recommended
227            for plugins that are  trusted and safe. A misbehaving plugin can affect the job agent
228            and other jobs, but the start up time is short and less memory
229            is used.
230            </para>
231          </listitem>
232         
233          <listitem>
234            <para>
235            <classname>net.sf.basedb.clients.jobagent.executors.DummyJobExecutor</classname>:     
236            Doesn't execute the job. It only marks the job as being executed,
237            and after waiting some time, as finished successfully.
238            Use it for debugging the job agent.
239            </para>
240          </listitem>
241          </itemizedlist>
242
243          It is possible to create your own implementation of a job executor.
244          Create a class that implements the
245          <interfacename>net.sf.basedb.clients.jobagent.JobExecutor</interfacename>
246          interface.         
247        </para>
248      </listitem>
249    </varlistentry>
250   
251    <varlistentry>
252      <term><property>agent.executor.process.java</property></term>
253      <listitem>
254        <para>
255          Optional. The path to the Java executable used by the
256          <classname>ProcessJobExecutor</classname>. If not specified the
257          <envar>JAVA_HOME</envar> environment variable will be checked.
258          As a last resort <command>java</command> is used without path
259          information to let the operating system find the default
260          installation.
261        </para>
262      </listitem>
263    </varlistentry>
264
265    <varlistentry>
266      <term><property>agent.executor.process.options</property></term>
267      <listitem>
268        <para>
269          Optional. Additional command line options to the Java executable.
270          Do not add memory options (<option>-Mx</option> or
271          <option>-Ms</option>), it will be added automatically by the
272          executor. This setting is used by the
273          <classname>ProcessJobExecutor</classname> only.
274        </para>
275      </listitem>
276    </varlistentry>
277   
278    <varlistentry>
279      <term><property>agent.executor.dummy.wait</property></term>
280      <listitem>
281        <para>
282          Optional. Number of seconds the <classname>DummyJobExecutor</classname> should
283          wait before returning from the "job execution". The executor first sets
284          the progress to 50% then waits the specified number of seconds before
285          setting the job to completed. If no value is specified it returns immediately.
286        </para>
287      </listitem>
288    </varlistentry>
289
290    <varlistentry>
291      <term><property>agent.checkinterval</property></term>
292      <listitem>
293        <para>
294          Optional. Number of seconds between querying the database
295          for jobs that are waiting for execution. The default value
296          is 30 seconds.
297        </para>
298      </listitem>
299    </varlistentry>
300   
301    </variablelist>
302  </simplesect>
303 
304  <simplesect id="appendix.jobagent.properties.slots">
305    <title>Slots and priorities</title>
306   
307    <para>
308      The job agent doesn't execute an arbitrary number of jobs simultaneously.
309      This would sooner or later break the server. Instead, it uses a
310      simple system with four different slots. Each slot is reserved for
311      jobs that are estimated to be finished in a certain amount of time.
312      The exception is that a quick job may use a slot with longer expected time
313      since that will not block the slot very long.
314    </para>
315   
316    <para>
317      A thread priority is associated with each slot. The priority
318      is a value between 1 and 10 as defined by the
319      <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Thread.html"
320        ><classname>java.lang.Thread</classname></ulink> class.
321    </para>
322   
323    <informaltable frame="all" align="center">
324    <tgroup cols="3">
325      <colspec colname="property" />
326      <colspec colname="default" align="center"/>
327      <colspec colname="time" />
328      <thead>
329        <row>
330          <entry>Property</entry>
331          <entry>Default value</entry>
332          <entry>Estimated execution time</entry>
333        </row>
334      </thead>
335     
336      <tbody>
337        <row>
338          <entry>agent.shortest.slots</entry>
339          <entry>1</entry>
340          <entry morerows="1">&lt; 1 minute</entry>
341        </row>
342        <row>
343          <entry>agent.shortest.priority</entry>
344          <entry>4</entry>
345        </row>
346        <row>
347          <entry>agent.short.slots</entry>
348          <entry>1</entry>
349          <entry morerows="1">&lt; 10 minutes</entry>
350        </row>
351        <row>
352          <entry>agent.short.priority</entry>
353          <entry>4</entry>
354        </row>
355        <row>
356          <entry>agent.medium.slots</entry>
357          <entry>2</entry>
358          <entry morerows="1">&lt; 1 hour</entry>
359        </row>
360        <row>
361          <entry>agent.medium.priority</entry>
362          <entry>3</entry>
363        </row>
364        <row>
365          <entry>agent.long.slots</entry>
366          <entry>2</entry>
367          <entry morerows="1">&gt; 1 hour</entry>
368        </row>
369        <row>
370          <entry>agent.long.priority</entry>
371          <entry>3</entry>
372        </row>
373      </tbody>
374    </tgroup>
375    </informaltable>
376   
377
378  </simplesect>
379
380
381</appendix>
382
Note: See TracBrowser for help on using the repository browser.