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

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

Fixes #598 Read "Appendix: jobagent.properties reference"

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 11.8 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 3365 2007-05-23 09:12:59Z 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 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 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. If the <command>start</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          start the job agent when it's paused. 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 startup 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 being 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 implementation 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
378</appendix>
379
Note: See TracBrowser for help on using the repository browser.