source: branches/2.6-stable/doc/src/docbook/appendix/jobagent.properties.xml @ 4175

Last change on this file since 4175 was 4175, checked in by Nicklas Nordborg, 14 years ago

Fixes #949: Installation documentation has incorrect information about which Java version to use

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