source: trunk/doc/src/docbook/appendix/base.config.xml @ 3944

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

References #819 The class-tag and interface-tag are now linking to the javadoc for the tagged class or interface.
Updated the source files of the documentation.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 20.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: base.config.xml 3944 2007-11-09 15:31:00Z martin $
7 
8  Copyright (C) 2007 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.base.config">
30 
31  <title>base.config reference</title>
32
33  <para>
34    The <filename>base.config</filename> file is the main configuration file
35    for BASE. It is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename>
36    directory.
37  </para>
38 
39  <simplesect id="appendix.base.config.dbdriver">
40    <title>Database driver section</title>
41   
42    <para>
43      This section has parameters needed for the database connection, such
44      as the database dialect, username and password.
45    </para>
46   
47    <variablelist>
48    <varlistentry>
49      <term><property>db.dialect</property></term>
50      <listitem>
51        <para>
52          The Hibernate dialect to use when generating SQL commands to the database.
53          Use:
54          <itemizedlist>
55          <listitem>
56            <userinput>org.hibernate.dialect.MySQLInnoDBDialect</userinput> 
57            for MySQL
58          </listitem>
59          <listitem>
60            <userinput>org.hibernate.dialect.PostgreSQLDialect</userinput> 
61            for Postgres
62          </listitem>
63          </itemizedlist> 
64          Other dialects may work but are not supported.
65        </para>
66      </listitem>
67    </varlistentry>
68   
69    <varlistentry>
70      <term><property>db.driver</property></term>
71      <listitem>
72        <para>
73          The JDBC driver to use when connecting to the database. Use:
74          <itemizedlist>
75          <listitem>
76            <userinput>com.mysql.jdbc.Driver</userinput> 
77            for MySQL
78          </listitem>
79          <listitem>
80            <userinput>org.postgresql.Driver</userinput> 
81            for Postgres
82          </listitem>
83          </itemizedlist> 
84          Other JDBC drivers may work but are not supported.
85        </para>
86      </listitem>
87    </varlistentry>
88   
89    <varlistentry>
90      <term><property>db.url</property></term>
91      <listitem>
92        <para>
93          The connection URL that locates the BASE 2 database. The exact syntax
94          of the string depends on the JDBC driver. Here are two examples which
95          leaves all other settings to their defaults:
96          <itemizedlist>
97          <listitem>
98            <userinput>jdbc:mysql://localhost/base2</userinput> 
99            for MySQL
100          </listitem>
101          <listitem>
102            <userinput>jdbc:postgresql:base2</userinput> 
103            for Postgres
104          </listitem>
105          </itemizedlist>
106         
107          You can get more information about the parameters that are supported on the
108          connection URL by reading the documentation from
109          <ulink url="http://dev.mysql.com/doc/refman/5.0/en/connector-j-reference-configuration-properties.html"
110            >MySQL</ulink> and
111          <ulink url="http://jdbc.postgresql.org/documentation/81/connect.html"
112            >Postgres</ulink>.
113           
114           
115          <note>
116            <para>
117            For MySQL we recommend that you enable the server-side cursors feature.
118            It will reduce memory usage since the JDBC driver does not have to
119            load all data into memory:
120            <userinput>
121            jdbc:mysql://localhost/base2?useCursorFetch=true&amp;defaultFetchSize=100
122            </userinput>
123            </para>
124           
125            <para>
126            Some MySQL versions (for example, 5.0.27) contains a bug that causes some
127            queries to fail if <userinput>useCursorFetch=true</userinput>. If you experience
128            this problem, you have to set it to false. For more information
129            see <ulink url="http://base.thep.lu.se/ticket/509">http://base.thep.lu.se/ticket/509</ulink>.
130            </para>
131          </note>
132           
133        </para>
134      </listitem>
135    </varlistentry>
136   
137    <varlistentry>
138      <term><property>db.dynamic.catalog</property></term>
139      <listitem>
140        <para>
141        The name of the catalog where the dynamic database used to store
142        analysed data is located. If not specified the same catalog as the regular
143        database is used. The exact meaning of catalog depends on the actual database.
144        For MySQL the catalog is the name of the database so this value is simply the
145        name of the dynamic database. Postgres does not support connecting to multiple
146        databases with the same connection so this should have the same value as the
147        database in the <property>db.url</property> setting.
148        </para>
149      </listitem>
150    </varlistentry>
151
152    <varlistentry>
153      <term><property>db.dynamic.schema</property></term>
154      <listitem>
155        <para>
156        The name of the schema where the dynamic database used to store
157        analysed data is located. MySQL does not have schemas so this value should
158        be left empty. Postgres supports schemas and we recommend that the dynamic
159        part is created in it's own schema to avoid mixing the dynamic tables with
160        the regular ones.
161        </para>
162      </listitem>
163    </varlistentry>
164
165    <varlistentry>
166      <term><property>db.username</property></term>
167      <listitem>
168        <para>
169        The username to connect to the database. The user should have full permission
170        to both the regular and the dynamic database.
171        </para>
172      </listitem>
173    </varlistentry>
174   
175    <varlistentry>
176      <term><property>db.password</property></term>
177      <listitem>
178        <para>
179         The password for the user.
180         </para>
181      </listitem>
182    </varlistentry>
183   
184    <varlistentry>
185      <term><property>db.batch-size</property></term>
186      <listitem>
187        <para>
188        The batch size to use when inserting/updating items with the Batch API.
189        A higher value requires more memory, a lower value degrades performance
190        since the number of database connections increases. The default value is
191        50.
192        </para>
193      </listitem>
194    </varlistentry>
195   
196    <varlistentry>
197      <term><property>db.queries</property></term>
198      <listitem>
199        <para>
200        The location of an XML file which contains database-specific
201        queries overriding those that does not work from the
202        <filename>/common-queries.xml</filename> file. Use:
203       
204        <itemizedlist>
205          <listitem><userinput>/mysql-queries.xml</userinput> for MySQL</listitem>
206          <listitem><userinput>/postgres-queries.xml</userinput> for Postgres</listitem>
207        </itemizedlist>
208          See also <xref linkend="appendix.otherconfig.sql" />.
209          </para>
210      </listitem>
211    </varlistentry>
212   
213    <varlistentry>
214      <term><property>db.extended-properties</property></term>
215      <listitem>
216        <para>
217        The location of an XML file describing the extended properties for extendable
218        item types, ie. the reporters. The default value is <userinput>/extended-properties.xml</userinput>.
219        See <xref linkend="appendix.extendedproperties" /> for more information
220        about extended properties.
221          </para>
222      </listitem>
223    </varlistentry>
224   
225    <varlistentry>
226      <term><property>db.raw-data-types</property></term>
227      <listitem>
228        <para>
229        The location of an XML file describing all raw data types and their properties.
230        The default value is <userinput>/raw-data-types.xml</userinput>.
231        See <xref linkend="appendix.rawdatatypes" /> for more information
232        about raw data types.
233          </para>
234      </listitem>
235    </varlistentry>
236   
237    <varlistentry>
238      <term><property>export.max.items</property></term>
239      <listitem>
240        <para>
241        The maximum number of items the export function should try to load in a single
242        query. This setting exists because MySQL prior to 5.0.2 does not support scrollable
243        result sets, but loads all data into memory. This will result in out of memory
244        exception if exporting too many items at the same time. Postgres does not have
245        this problem. Use:
246       
247        <itemizedlist>
248        <listitem><para>0 for Postgres</para></listitem>
249        <listitem>
250          <para>
251            0 for MySQL version 5.0.2 or above.
252            Requires that <userinput>useCursorFetch=true</userinput> is specified in
253            the connection url and  that <userinput>defaultFetchSize=xxx</userinput>
254            is set to a value &gt; 0.
255          </para>
256        </listitem>
257        <listitem>
258          <para>
259            As large as possible value for other MySQL versions.
260            A low value results in more queries and slower performance when
261            exporting data.
262          </para>
263        </listitem>
264        </itemizedlist>
265        </para>
266      </listitem>
267    </varlistentry>
268    </variablelist>
269   
270  </simplesect>
271 
272  <simplesect id="appendix.base.config.authentication">
273    <title>Authentication section</title>
274    <para>
275      This section describes parameters that are needed if you are
276      going to use external authentication. If you let BASE handle this
277      you will not have to bother about these settings. See
278      <xref linkend="plugin_developer.other.authentication"/> for more information about
279      external authentication.
280    </para>
281   
282    <variablelist>
283    <varlistentry>
284      <term><property>auth.driver</property></term>
285      <listitem>
286        <para>
287        The class name of the plug-in that acts as the authentication driver.
288        BASE ships with a simple plugin that checks if a user has a valid email
289        account on a POP3 server. It is not enabled by default. The class name
290        of that plugin is <classname docapi="net.sf.basedb.core.authentication">net.sf.basedb.core.authentication.POP3Authenticator</classname>.
291        If no class is specified internal authentication is used.
292          </para>
293      </listitem>
294    </varlistentry>
295   
296    <varlistentry>
297      <term><property>auth.init</property></term>
298      <listitem>
299        <para>
300        Initialisation parameters sent to the plug-in when calling the
301        <methodname>init()</methodname> method. The syntax and meaning of this
302        string depends on the plugin. For the <classname docapi="net.sf.basedb.core.authentication">POP3Authenticator</classname> 
303        this is simply the name or IP-address of the mail server.
304          </para>
305      </listitem>
306    </varlistentry>
307   
308    <varlistentry>
309      <term><property>auth.synchronize</property></term>
310      <listitem>
311        <para>
312        If this setting is 1 or TRUE, BASE will synchronize the extra
313        information (name, address, email, etc.) sent by the authentication driver
314        when a user logs in to BASE. This setting is ignored if the driver does not
315        support extra information.
316          </para>
317      </listitem>
318    </varlistentry>
319   
320    <varlistentry>
321      <term><property>auth.cachepasswords</property></term>
322      <listitem>
323        <para>
324        If passwords should be cached by BASE or not. If the passwords are
325        cached a user may login to BASE even if the external authentication
326        server is down. The cached passwords are only used if the external
327        authentication does not answer properly.
328          </para>
329      </listitem>
330    </varlistentry>
331   
332    <varlistentry>
333      <term><property>auth.daystocache</property></term>
334      <listitem>
335        <para>
336        How many days a cached password is valid if caching is enabled. A value of
337        0 caches the passwords forever.
338          </para>
339      </listitem>
340    </varlistentry>
341    </variablelist>
342  </simplesect>
343 
344  <simplesect id="appendix.base.config.jobqueue">
345    <title>Internal job queue section</title>
346   
347    <para>
348      This section contains setting that control the internal job queue.
349      The internal job queue is a simple queue that executes jobs more or
350      less in the order they were added to the queue. To make sure long-running
351      jobs do not block the queue, there are four slots that uses the
352      expected execution time to decide if a job should be allowed to execute
353      or not.
354    </para>
355   
356    <variablelist>
357    <varlistentry>
358      <term><property>jobqueue.internal.enabled</property></term>
359      <listitem>
360        <para>
361         If <userinput>0</userinput> or <userinput>FALSE</userinput> the internal
362         job queue will be disabled.
363         </para>
364      </listitem>
365    </varlistentry>
366   
367    <varlistentry>
368      <term><property>jobqueue.internal.runallplugins</property></term>
369      <listitem>
370        <para>
371         If <userinput>1</userinput> or <userinput>TRUE</userinput> the internal
372         job queue will ignore the <property>useInternalJobQueue</property>
373         flag specified on plug-ins. If <userinput>0</userinput> or <userinput>FALSE</userinput>
374         the internal job queue will only execute plug-ins which has
375         <property>useInternalJobQueue=true</property>
376         </para>
377      </listitem>
378    </varlistentry>
379
380    <varlistentry>
381      <term><property>jobqueue.internal.checkinterval</property></term>
382      <listitem>
383        <para>
384         The number of seconds between checks to the database for jobs
385         that are waiting for execution.
386         </para>
387      </listitem>
388    </varlistentry>
389   
390    <varlistentry>
391      <term><property>jobqueue.internal.shortest.threads</property></term>
392      <term><property>jobqueue.internal.short.threads</property></term>
393      <term><property>jobqueue.internal.medium.threads</property></term>
394      <term><property>jobqueue.internal.long.threads</property></term>
395      <listitem>
396        <para>
397        Maximum number of threads to reserve for jobs with a given expected
398        execution time. A job with a short execution time may use a thread
399        from one of the slots with longer execution time. When all threads
400        are in use, new jobs will have to wait until an executing job
401        has finished.
402        </para>
403      </listitem>
404    </varlistentry>
405   
406    <varlistentry>
407      <term><property>jobqueue.internal.shortest.threadpriority</property></term>
408      <term><property>jobqueue.internal.short.threadpriority</property></term>
409      <term><property>jobqueue.internal.medium.threadpriority</property></term>
410      <term><property>jobqueue.internal.long.threadpriority</property></term>
411      <listitem>
412        <para>
413        The priority to give to jobs. The priority is a value between 1 and 10.
414        See <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Thread.html"
415        >http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Thread.html</ulink> 
416        for more information about thread priorities.
417        </para>
418      </listitem>
419    </varlistentry>
420    </variablelist>
421
422  </simplesect>
423
424  <simplesect id="appendix.base.config.jobagent">
425    <title>Job agent section</title>
426   
427    <para>
428      This section contains settings that BASE uses when communicating
429      with external job agents. See <xref linkend="installation_upgrade.jobagents"/> 
430      for more information about job agents.
431    </para>
432   
433    <variablelist>
434    <varlistentry>
435      <term><property>agent.maxage</property></term>
436      <listitem>
437        <para>
438        Number of seconds to keep job agent information in the internal cache.
439        The information includes, CPU and memory usage and the status of executing
440        jobs. This setting controls how long the information is kept in the cache
441        before a new request is made to the job agent. The default value is 60 seconds.
442          </para>
443      </listitem>
444    </varlistentry>
445
446    <varlistentry>
447      <term><property>agent.connection.timeout</property></term>
448      <listitem>
449        <para>
450        The timeout in milliseconds to wait for a response from a job agent
451        when sending a request to it. The default timeout is 1000 milliseconds.
452        This should be more than enough if the job agent is on the internal
453        network, but may have to be increased if it is located somewhere else.
454          </para>
455      </listitem>
456    </varlistentry>
457
458    </variablelist>
459   
460  </simplesect>
461
462  <simplesect id="appendix.base.config.secondary">
463    <title>Secondary storage controller</title>
464   
465    <para>
466      This section contains settings for the secondary storage controller. See
467      <xref linkend="plugin_developer.other.secondary"/> for more
468      information about secondary storage.
469    </para>
470   
471    <variablelist>
472    <varlistentry>
473      <term><property>secondary.storage.driver</property></term>
474      <listitem>
475        <para>
476        The class name of the plug-in that acts as the secondary storage controller.
477        BASE ships with a simple plug-in that just moves files to another directory,
478        but it is not enabled by default. The class name of that plug-in is
479        <classname docapi="net.sf.basedb.core">net.sf.basedb.core.InternalStorageController</classname>.
480        If no class is specified the secondary storage feature is disabled.
481          </para>
482      </listitem>
483    </varlistentry>
484   
485    <varlistentry>
486      <term><property>secondary.storage.init</property></term>
487      <listitem>
488        <para>
489        Initialisation parameters sent to the plug-in when calling the
490        <methodname>init()</methodname> method. The syntax and meaning of this
491        string depends on the plug-in. For the internal controller this is simply
492        the path to the secondary directory.
493          </para>
494      </listitem>
495    </varlistentry>
496   
497    <varlistentry>
498      <term><property>secondary.storage.interval</property></term>
499      <listitem>
500        <para>
501        Interval in seconds between each execution of the secondary storage
502        controller plug-in. It must be a value greater than zero or the secondary
503        storage feature will be disabled.
504          </para>
505      </listitem>
506    </varlistentry>
507   
508    <varlistentry>
509      <term><property>secondary.storage.time</property></term>
510      <listitem>
511        <para>
512        Time-point values specifying the time(s) of day that the secondary storage controller
513        should be executed. If present, this setting overrides the
514        <property>secondary.storage.interval</property> setting.
515        Time-point values are given as comma-separated list of two-digit, 24-based hour
516        and two-digit minute values. For example: <userinput>03:10,09:00,23:59</userinput>.
517          </para>
518      </listitem>
519    </varlistentry>
520    </variablelist>
521   
522  </simplesect>
523 
524  <simplesect id="appendix.base.config.secondary.other">
525    <title>Other settings</title>
526   
527    <variablelist>
528    <varlistentry>
529      <term><property>userfiles</property></term>
530      <listitem>
531        <para>
532        The path to the directory where uploaded and generated files should
533        be stored. This is the primary file storage. See <xref linkend="appendix.base.config.secondary" /> 
534        for information about how to configure the secondary storage. Files are not
535        stored in the same directory structure or with the same names as in
536        the BASE filesystem. The internal structure may contain subdirectories.
537          </para>
538      </listitem>
539    </varlistentry>
540   
541    <varlistentry>
542      <term><property>permission.timeout</property></term>
543      <listitem>
544        <para>
545        Number of minutes to cache a logged in user's permissions before
546        reloading them. The default value is 10. This setting affect how
547        quickly a changed permission propagate to a logged in user. Permissions
548        are always reloaded when a user logs in.
549          </para>
550      </listitem>
551    </varlistentry>
552   
553    <varlistentry>
554      <term><property>cache.timeout</property></term>
555      <listitem>
556        <para>
557        Number of minutes to keep user sessions in the internal cache
558        before the user is automatically logged out. The timeout is counted
559        from the last access made from the user.
560          </para>
561      </listitem>
562    </varlistentry>
563    <varlistentry>
564      <term><property>helptext.update</property></term>
565      <listitem>
566        <para>
567          Defines if already existing helptexts in BASE should be overwritten when
568          updating the program,
569          <xref linkend="installation_upgrade.upgrade" />
570          <itemizedlist>
571            <listitem>
572              <simpara>
573                <userinput>true</userinput>
574                will overwrite existing helptexts.
575              </simpara>
576            </listitem>
577            <listitem>
578              <simpara>
579                <userinput>false</userinput>
580                will leave the existing helptexts in database unchanged and only
581                insert new helptexts.
582              </simpara>
583            </listitem>
584          </itemizedlist>
585        </para>
586      </listitem>
587    </varlistentry>
588    <varlistentry>
589      <term><property>plugins.autounload</property></term>
590      <listitem>
591        <para>
592          Enable this setting to let BASE detect if a plug-in JAR file is changed
593          and automatically load and use the new code instead of the old code.
594          This setting is useful for plug-in developers since they don't have to
595          restart the webserver each time the plug-in is recompiled.
596          <itemizedlist>
597            <listitem>
598              <simpara>
599                <userinput>true,yes,1</userinput>
600                to enable
601              </simpara>
602            </listitem>
603            <listitem>
604              <simpara>
605                <userinput>false,no,0</userinput>
606                to disable (default if no value is specified)
607              </simpara>
608            </listitem>
609          </itemizedlist>
610        </para>
611      </listitem>
612    </varlistentry>
613    <varlistentry>
614      <term><property>plugins.dir</property></term>
615      <listitem>
616        <para>
617          The path to the directory where jar-files for external plugins should be located
618          if they should be used with the auto-installer. All new plugins found in this directory, or
619          in any of it's subdirectories, can be selected for installation, see
620          <xref linkend="plugins.installation" />
621          . The plugin auto-installer will not be availble if this property isn't defined.
622        </para>
623      </listitem>
624    </varlistentry>
625    </variablelist>
626  </simplesect>
627
628</appendix>
629
Note: See TracBrowser for help on using the repository browser.