source: branches/2.6-stable/doc/src/docbook/appendix/base.config.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: 22.7 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 4175 2008-03-14 08:47:48Z nicklas $
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.signalreceiver.class</property></term>
382      <listitem>
383        <para>
384         A class implementing the <interfacename docapi="net.sf.basedb.core.signal"
385         >SignalReceiver</interfacename>
386         interface. The class must have a public no-argument constructor. If
387         no value is specified the default setting is:
388         <classname docapi="net.sf.basedb.core.signal"
389         >net.sf.basedb.core.signal.LocalSignalReceiver</classname>.
390         </para>
391         <para>
392         Change to <classname docapi="net.sf.basedb.core.signal"
393         >net.sf.basedb.core.signal.SocketSignalReceiver</classname>
394         if the internal job queue must be able to receive signals from outside
395         this JVM.
396         </para>
397      </listitem>
398    </varlistentry>
399   
400    <varlistentry>
401      <term><property>jobqueue.internal.signalreceiver.init</property></term>
402      <listitem>
403        <para>
404        Initialisation string sent to <methodname>SignalReceiver.init()</methodname>.
405        The syntax and meaning of the string depends on the actual implementation
406        that is used. Please see the javadoc for more information.
407         </para>
408      </listitem>
409    </varlistentry>
410
411    <varlistentry>
412      <term><property>jobqueue.internal.checkinterval</property></term>
413      <listitem>
414        <para>
415         The number of seconds between checks to the database for jobs
416         that are waiting for execution.
417         </para>
418      </listitem>
419    </varlistentry>
420   
421    <varlistentry>
422      <term><property>jobqueue.internal.shortest.threads</property></term>
423      <term><property>jobqueue.internal.short.threads</property></term>
424      <term><property>jobqueue.internal.medium.threads</property></term>
425      <term><property>jobqueue.internal.long.threads</property></term>
426      <listitem>
427        <para>
428        Maximum number of threads to reserve for jobs with a given expected
429        execution time. A job with a short execution time may use a thread
430        from one of the slots with longer execution time. When all threads
431        are in use, new jobs will have to wait until an executing job
432        has finished.
433        </para>
434      </listitem>
435    </varlistentry>
436   
437    <varlistentry>
438      <term><property>jobqueue.internal.shortest.threadpriority</property></term>
439      <term><property>jobqueue.internal.short.threadpriority</property></term>
440      <term><property>jobqueue.internal.medium.threadpriority</property></term>
441      <term><property>jobqueue.internal.long.threadpriority</property></term>
442      <listitem>
443        <para>
444        The priority to give to jobs. The priority is a value between 1 and 10.
445        See <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Thread.html"
446        >http://java.sun.com/javase/6/docs/api/java/lang/Thread.html</ulink> 
447        for more information about thread priorities.
448        </para>
449      </listitem>
450    </varlistentry>
451    </variablelist>
452
453  </simplesect>
454
455  <simplesect id="appendix.base.config.jobagent">
456    <title>Job agent section</title>
457   
458    <para>
459      This section contains settings that BASE uses when communicating
460      with external job agents. See <xref linkend="installation_upgrade.jobagents"/> 
461      for more information about job agents.
462    </para>
463   
464    <variablelist>
465    <varlistentry>
466      <term><property>agent.maxage</property></term>
467      <listitem>
468        <para>
469        Number of seconds to keep job agent information in the internal cache.
470        The information includes, CPU and memory usage and the status of executing
471        jobs. This setting controls how long the information is kept in the cache
472        before a new request is made to the job agent. The default value is 60 seconds.
473          </para>
474      </listitem>
475    </varlistentry>
476
477    <varlistentry>
478      <term><property>agent.connection.timeout</property></term>
479      <listitem>
480        <para>
481        The timeout in milliseconds to wait for a response from a job agent
482        when sending a request to it. The default timeout is 1000 milliseconds.
483        This should be more than enough if the job agent is on the internal
484        network, but may have to be increased if it is located somewhere else.
485          </para>
486      </listitem>
487    </varlistentry>
488
489    </variablelist>
490   
491  </simplesect>
492
493  <simplesect id="appendix.base.config.secondary">
494    <title>Secondary storage controller</title>
495   
496    <para>
497      This section contains settings for the secondary storage controller. See
498      <xref linkend="plugin_developer.other.secondary"/> for more
499      information about secondary storage.
500    </para>
501   
502    <variablelist>
503    <varlistentry>
504      <term><property>secondary.storage.driver</property></term>
505      <listitem>
506        <para>
507        The class name of the plug-in that acts as the secondary storage controller.
508        BASE ships with a simple plug-in that just moves files to another directory,
509        but it is not enabled by default. The class name of that plug-in is
510        <classname docapi="net.sf.basedb.core">net.sf.basedb.core.InternalStorageController</classname>.
511        If no class is specified the secondary storage feature is disabled.
512          </para>
513      </listitem>
514    </varlistentry>
515   
516    <varlistentry>
517      <term><property>secondary.storage.init</property></term>
518      <listitem>
519        <para>
520        Initialisation parameters sent to the plug-in when calling the
521        <methodname>init()</methodname> method. The syntax and meaning of this
522        string depends on the plug-in. For the internal controller this is simply
523        the path to the secondary directory.
524          </para>
525      </listitem>
526    </varlistentry>
527   
528    <varlistentry>
529      <term><property>secondary.storage.interval</property></term>
530      <listitem>
531        <para>
532        Interval in seconds between each execution of the secondary storage
533        controller plug-in. It must be a value greater than zero or the secondary
534        storage feature will be disabled.
535          </para>
536      </listitem>
537    </varlistentry>
538   
539    <varlistentry>
540      <term><property>secondary.storage.time</property></term>
541      <listitem>
542        <para>
543        Time-point values specifying the time(s) of day that the secondary storage controller
544        should be executed. If present, this setting overrides the
545        <property>secondary.storage.interval</property> setting.
546        Time-point values are given as comma-separated list of two-digit, 24-based hour
547        and two-digit minute values. For example: <userinput>03:10,09:00,23:59</userinput>.
548          </para>
549      </listitem>
550    </varlistentry>
551    </variablelist>
552   
553  </simplesect>
554 
555  <simplesect id="appendix.base.config.secondary.other">
556    <title>Other settings</title>
557   
558    <variablelist>
559    <varlistentry>
560      <term><property>userfiles</property></term>
561      <listitem>
562        <para>
563        The path to the directory where uploaded and generated files should
564        be stored. This is the primary file storage. See <xref linkend="appendix.base.config.secondary" /> 
565        for information about how to configure the secondary storage. Files are not
566        stored in the same directory structure or with the same names as in
567        the BASE filesystem. The internal structure may contain subdirectories.
568          </para>
569      </listitem>
570    </varlistentry>
571   
572    <varlistentry>
573      <term><property>permission.timeout</property></term>
574      <listitem>
575        <para>
576        Number of minutes to cache a logged in user's permissions before
577        reloading them. The default value is 10. This setting affect how
578        quickly a changed permission propagate to a logged in user. Permissions
579        are always reloaded when a user logs in.
580          </para>
581      </listitem>
582    </varlistentry>
583   
584    <varlistentry>
585      <term><property>cache.timeout</property></term>
586      <listitem>
587        <para>
588        Number of minutes to keep user sessions in the internal cache
589        before the user is automatically logged out. The timeout is counted
590        from the last access made from the user.
591          </para>
592      </listitem>
593    </varlistentry>
594    <varlistentry>
595      <term><property>helptext.update</property></term>
596      <listitem>
597        <para>
598          Defines if already existing helptexts in BASE should be overwritten when
599          updating the program,
600          <xref linkend="installation_upgrade.upgrade" />
601          <itemizedlist>
602            <listitem>
603              <simpara>
604                <userinput>true</userinput>
605                will overwrite existing helptexts.
606              </simpara>
607            </listitem>
608            <listitem>
609              <simpara>
610                <userinput>false</userinput>
611                will leave the existing helptexts in database unchanged and only
612                insert new helptexts.
613              </simpara>
614            </listitem>
615          </itemizedlist>
616        </para>
617      </listitem>
618    </varlistentry>
619    <varlistentry>
620      <term><property>plugins.autounload</property></term>
621      <listitem>
622        <para>
623          Enable this setting to let BASE detect if a plug-in JAR file is changed
624          and automatically load and use the new code instead of the old code.
625          This setting is useful for plug-in developers since they don't have to
626          restart the webserver each time the plug-in is recompiled.
627          <itemizedlist>
628            <listitem>
629              <simpara>
630                <userinput>true,yes,1</userinput>
631                to enable
632              </simpara>
633            </listitem>
634            <listitem>
635              <simpara>
636                <userinput>false,no,0</userinput>
637                to disable (default if no value is specified)
638              </simpara>
639            </listitem>
640          </itemizedlist>
641        </para>
642      </listitem>
643    </varlistentry>
644    <varlistentry>
645      <term><property>plugins.dir</property></term>
646      <listitem>
647        <para>
648          The path to the directory where jar-files for external plugins should be located
649          if they should be used with the auto-installer. All new plugins found in this directory,
650          or in any of it's subdirectories, can be selected for installation, see
651          <xref linkend="plugins.installation" />.
652          The plugin auto-installer will not be availble if this property isn't defined.
653        </para>
654
655        <para>
656          Another benefit is that all plug-ins inside this directory are registered
657          with relative paths. This means that there is a lot less hassle when
658          using job agents to run plug-ins. Just change this setting for the job
659          agent installation and all plug-ins will work. For plug-ins that are outside
660          of this directory you may have to manually register the path if it is different from
661          the main path. It will also be a lot easier if you plan to move all plug-ins to
662          a different directory. Just move the JAR files and change this setting. There is
663          no need to change the paths for each plug-in in the database.
664        </para>
665           
666      </listitem>
667    </varlistentry>
668    </variablelist>
669  </simplesect>
670
671</appendix>
672
Note: See TracBrowser for help on using the repository browser.