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

Last change on this file since 3411 was 3411, checked in by Jari Häkkinen, 14 years ago

Fixes #601.

  • 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 3411 2007-05-30 14:41:36Z jari $
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            <term>
213            <classname>net.sf.basedb.clients.jobagent.executors.ProcessJobExecutor</classname>
214            </term>
215            <para>
216            Executes the job in an
217            external process. This is the recommended executor and is the default
218            choice if no value has been specified. With this executor, a
219            misbehaving plugin doesn't affect the job agent or other jobs.
220            The drawback is that since a new virtual machine has to be started,
221            more memory is required and the start up time can be long.
222            </para>
223          </listitem>
224         
225          <listitem>
226            <para>
227            <classname>net.sf.basedb.clients.jobagent.executors.ThreadJobExecutor</classname>:     
228            Executes the job in a separate thread. This is only recommended
229            for plugins that are  trusted and safe. A misbehaving plugin can affect the job agent
230            and other jobs, but the start up time is short and less memory
231            is used.
232            </para>
233          </listitem>
234         
235          <listitem>
236            <para>
237            <classname>net.sf.basedb.clients.jobagent.executors.DummyJobExecutor</classname>:     
238            Doesn't execute the job. It only marks the job as being executed,
239            and after waiting some time, as finished successfully.
240            Use it for debugging the job agent.
241            </para>
242          </listitem>
243          </itemizedlist>
244
245          It is possible to create your own implementation of a job executor.
246          Create a class that implements the
247          <interfacename>net.sf.basedb.clients.jobagent.JobExecutor</interfacename>
248          interface.         
249        </para>
250      </listitem>
251    </varlistentry>
252   
253    <varlistentry>
254      <term><property>agent.executor.process.java</property></term>
255      <listitem>
256        <para>
257          Optional. The path to the Java executable used by the
258          <classname>ProcessJobExecutor</classname>. If not specified the
259          <envar>JAVA_HOME</envar> environment variable will be checked.
260          As a last resort <command>java</command> is used without path
261          information to let the operating system find the default
262          installation.
263        </para>
264      </listitem>
265    </varlistentry>
266
267    <varlistentry>
268      <term><property>agent.executor.process.options</property></term>
269      <listitem>
270        <para>
271          Optional. Additional command line options to the Java executable.
272          Do not add memory options (<option>-Mx</option> or
273          <option>-Ms</option>), it will be added automatically by the
274          executor. This setting is used by the
275          <classname>ProcessJobExecutor</classname> only.
276        </para>
277      </listitem>
278    </varlistentry>
279   
280    <varlistentry>
281      <term><property>agent.executor.dummy.wait</property></term>
282      <listitem>
283        <para>
284          Optional. Number of seconds the <classname>DummyJobExecutor</classname> should
285          wait before returning from the "job execution". The executor first sets
286          the progress to 50% then waits the specified number of seconds before
287          setting the job to completed. If no value is specified it returns immediately.
288        </para>
289      </listitem>
290    </varlistentry>
291
292    <varlistentry>
293      <term><property>agent.checkinterval</property></term>
294      <listitem>
295        <para>
296          Optional. Number of seconds between querying the database
297          for jobs that are waiting for execution. The default value
298          is 30 seconds.
299        </para>
300      </listitem>
301    </varlistentry>
302   
303    </variablelist>
304  </simplesect>
305 
306  <simplesect id="appendix.jobagent.properties.slots">
307    <title>Slots and priorities</title>
308   
309    <para>
310      The job agent doesn't execute an arbitrary number of jobs simultaneously.
311      This would sooner or later break the server. Instead, it uses a
312      simple system with four different slots. Each slot is reserved for
313      jobs that are estimated to be finished in a certain amount of time.
314      The exception is that a quick job may use a slot with longer expected time
315      since that will not block the slot very long.
316    </para>
317   
318    <para>
319      A thread priority is associated with each slot. The priority
320      is a value between 1 and 10 as defined by the
321      <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Thread.html"
322        ><classname>java.lang.Thread</classname></ulink> class.
323    </para>
324   
325    <informaltable frame="all" align="center">
326    <tgroup cols="3">
327      <colspec colname="property" />
328      <colspec colname="default" align="center"/>
329      <colspec colname="time" />
330      <thead>
331        <row>
332          <entry>Property</entry>
333          <entry>Default value</entry>
334          <entry>Estimated execution time</entry>
335        </row>
336      </thead>
337     
338      <tbody>
339        <row>
340          <entry>agent.shortest.slots</entry>
341          <entry>1</entry>
342          <entry morerows="1">&lt; 1 minute</entry>
343        </row>
344        <row>
345          <entry>agent.shortest.priority</entry>
346          <entry>4</entry>
347        </row>
348        <row>
349          <entry>agent.short.slots</entry>
350          <entry>1</entry>
351          <entry morerows="1">&lt; 10 minutes</entry>
352        </row>
353        <row>
354          <entry>agent.short.priority</entry>
355          <entry>4</entry>
356        </row>
357        <row>
358          <entry>agent.medium.slots</entry>
359          <entry>2</entry>
360          <entry morerows="1">&lt; 1 hour</entry>
361        </row>
362        <row>
363          <entry>agent.medium.priority</entry>
364          <entry>3</entry>
365        </row>
366        <row>
367          <entry>agent.long.slots</entry>
368          <entry>2</entry>
369          <entry morerows="1">&gt; 1 hour</entry>
370        </row>
371        <row>
372          <entry>agent.long.priority</entry>
373          <entry>3</entry>
374        </row>
375      </tbody>
376    </tgroup>
377    </informaltable>
378   
379
380  </simplesect>
381
382
383</appendix>
384
Note: See TracBrowser for help on using the repository browser.