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

Last change on this file since 3411 was 3363, checked in by Nicklas Nordborg, 15 years ago

References #598

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 19.2 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 3363 2007-05-22 20:48:49Z nicklas $
7 
8  Copyright (C) Authors contributing to this file.
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 2
16  of the License, or (at your option) any later version.
17 
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with this program; if not, write to the Free Software
25  Foundation, Inc., 59 Temple Place - Suite 330,
26  Boston, MA  02111-1307, USA.
27-->
28
29<appendix id="appendix.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 doesn't 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 doesn't 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 doesn't 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 doesn't 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 doesn't 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 doesn't 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>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>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 doesn't
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 doesn't 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 don't 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. If you are using job agents to execute jobs,
363         the recommendation is to disable the internal job queue. Otherwise you must
364         leave it enabled.
365         </para>
366      </listitem>
367    </varlistentry>
368
369    <varlistentry>
370      <term><property>jobqueue.internal.checkinterval</property></term>
371      <listitem>
372        <para>
373         The number of seconds between checks to the database for jobs
374         that are waiting for execution.
375         </para>
376      </listitem>
377    </varlistentry>
378   
379    <varlistentry>
380      <term><property>jobqueue.internal.shortest.threads</property></term>
381      <term><property>jobqueue.internal.short.threads</property></term>
382      <term><property>jobqueue.internal.medium.threads</property></term>
383      <term><property>jobqueue.internal.long.threads</property></term>
384      <listitem>
385        <para>
386        Maximum number of threads to reserve for jobs with a given expected
387        execution time. A job with a short execution time may use a thread
388        from one of the slots with longer execution time. When all threads
389        are in use, new jobs will have to wait until an executing job
390        has finished.
391        </para>
392      </listitem>
393    </varlistentry>
394   
395    <varlistentry>
396      <term><property>jobqueue.internal.shortest.threadpriority</property></term>
397      <term><property>jobqueue.internal.short.threadpriority</property></term>
398      <term><property>jobqueue.internal.medium.threadpriority</property></term>
399      <term><property>jobqueue.internal.long.threadpriority</property></term>
400      <listitem>
401        <para>
402        The priority to give to jobs. The priority is a value between 1 and 10.
403        See <ulink url="http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Thread.html"
404        >http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Thread.html</ulink> 
405        for more information about thread priorities.
406        </para>
407      </listitem>
408    </varlistentry>
409    </variablelist>
410
411  </simplesect>
412
413  <simplesect id="appendix.base.config.jobagent">
414    <title>Job agent section</title>
415   
416    <para>
417      This section contains settings that BASE uses when communicating
418      with external job agents. See <xref linkend="installation_upgrade.jobagents"/> 
419      for more information about job agents.
420    </para>
421   
422    <variablelist>
423    <varlistentry>
424      <term><property>agent.maxage</property></term>
425      <listitem>
426        <para>
427        Number of seconds to keep job agent information in the internal cache.
428        The information includes, CPU and memory usage and the status of executing
429        jobs. This setting controls how long the information is kept in the cache
430        before a new request is made to the job agent. The default value is 60 seconds.
431          </para>
432      </listitem>
433    </varlistentry>
434
435    <varlistentry>
436      <term><property>agent.connection.timeout</property></term>
437      <listitem>
438        <para>
439        The timeout in milliseconds to wait for a response from a job agent
440        when sending a request to it. The default timeout is 1000 milliseconds.
441        This should be more than enough if the job agent is on the internal
442        network, but may have to be increased if it is located somewhere else.
443          </para>
444      </listitem>
445    </varlistentry>
446
447    </variablelist>
448   
449  </simplesect>
450
451  <simplesect id="appendix.base.config.secondary">
452    <title>Secondary storage controller</title>
453   
454    <para>
455      This section contains settings for the secondary storage controller. See
456      <xref linkend="plugin_developer.other.secondary"/> for more
457      information about secondary storage.
458    </para>
459   
460    <variablelist>
461    <varlistentry>
462      <term><property>secondary.storage.driver</property></term>
463      <listitem>
464        <para>
465        The class name of the plug-in that acts as the secondary storage controller.
466        BASE ships with a simple plug-in that just moves files to another directory,
467        but it is not enabled by default. The class name of that plug-in is
468        <classname>net.sf.basedb.core.InternalStorageController</classname>.
469        If no class is specified the secondary storage feature is disabled.
470          </para>
471      </listitem>
472    </varlistentry>
473   
474    <varlistentry>
475      <term><property>secondary.storage.init</property></term>
476      <listitem>
477        <para>
478        Initialisation parameters sent to the plug-in when calling the
479        <methodname>init()</methodname> method. The syntax and meaning of this
480        string depends on the plug-in. For the internal controller this is simply
481        the path to the secondary directory.
482          </para>
483      </listitem>
484    </varlistentry>
485   
486    <varlistentry>
487      <term><property>secondary.storage.interval</property></term>
488      <listitem>
489        <para>
490        Interval in seconds between each execution of the secondary storage
491        controller plug-in. It must be a value greater than zero or the secondary
492        storage feature will be disabled.
493          </para>
494      </listitem>
495    </varlistentry>
496   
497    <varlistentry>
498      <term><property>secondary.storage.time</property></term>
499      <listitem>
500        <para>
501        Time-point values specifying the time(s) of day that the secondary storage controller
502        should be executed. If present, this setting overrides the
503        <property>secondary.storage.interval</property> setting.
504        Time-point values are given as comma-separated list of two-digit, 24-based hour
505        and two-digit minute values. For example: <userinput>03:10,09:00,23:59</userinput>.
506          </para>
507      </listitem>
508    </varlistentry>
509    </variablelist>
510   
511  </simplesect>
512 
513  <simplesect id="appendix.base.config.secondary.other">
514    <title>Other settings</title>
515   
516    <variablelist>
517    <varlistentry>
518      <term><property>userfiles</property></term>
519      <listitem>
520        <para>
521        The path to the directory where uploaded and generated files should
522        be stored. This is the primary file storage. See <xref linkend="appendix.base.config.secondary" /> 
523        for information about how to configure the secondary storage. Files are not
524        stored in the same directory structure or with the same names as in
525        the BASE filesystem. The internal structure may contain subdirectories.
526          </para>
527      </listitem>
528    </varlistentry>
529   
530    <varlistentry>
531      <term><property>permission.timeout</property></term>
532      <listitem>
533        <para>
534        Number of minutes to cache a logged in user's permissions before
535        reloading them. The default value is 10. This setting affect how
536        quickly a changed permission propagate to a logged in user. Permissions
537        are always reloaded when a user logs in.
538          </para>
539      </listitem>
540    </varlistentry>
541   
542    <varlistentry>
543      <term><property>cache.timeout</property></term>
544      <listitem>
545        <para>
546        Number of minutes to keep user sessions in the internal cache
547        before the user is automatically logged out. The timeout is counted
548        from the last access made from the user.
549          </para>
550      </listitem>
551    </varlistentry>
552    <varlistentry>
553      <term><property>helptext.update</property></term>
554      <listitem>
555        <para>
556          Defines if already existing helptexts in BASE should be overwritten when
557          updating the program,
558          <xref linkend="installation_upgrade.upgrade" />
559          <itemizedlist>
560            <listitem>
561              <simpara>
562                <userinput>true</userinput>
563                will overwrite existing helptexts.
564              </simpara>
565            </listitem>
566            <listitem>
567              <simpara>
568                <userinput>false</userinput>
569                will leave the existing helptexts in database unchanged and only
570                insert new helptexts.
571              </simpara>
572            </listitem>
573          </itemizedlist>
574        </para>
575      </listitem>
576    </varlistentry>
577    </variablelist>
578  </simplesect>
579
580</appendix>
581
Note: See TracBrowser for help on using the repository browser.