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

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

Addresses #1106. Missed to change reference wherefrom retrive GPLv3 license text. And some other changes.

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