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

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: base.config.xml 4477 2008-09-05 15:15:25Z jari $
  
  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Martin Svensson
  
  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/
  
  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.
  
  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place - Suite 330,
  Boston, MA  02111-1307, USA.
-->

<appendix id="appendix.base.config">
  
  <title>base.config reference</title>

  <para>
    The <filename>base.config</filename> file is the main configuration file
    for BASE. It is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename>
    directory.
  </para>
  
  <simplesect id="appendix.base.config.dbdriver">
    <title>Database driver section</title>
    
    <para>
      This section has parameters needed for the database connection, such
      as the database dialect, username and password.
    </para>
    
    <variablelist>
    <varlistentry>
      <term><property>db.dialect</property></term>
      <listitem>
        <para>
          The Hibernate dialect to use when generating SQL commands to the database. 
          Use:
          <itemizedlist>
          <listitem>
            <userinput>org.hibernate.dialect.MySQLInnoDBDialect</userinput> 
            for MySQL
          </listitem>
          <listitem>
            <userinput>org.hibernate.dialect.PostgreSQLDialect</userinput> 
            for Postgres
          </listitem>
          </itemizedlist> 
          Other dialects may work but are not supported.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>db.driver</property></term>
      <listitem>
        <para>
          The JDBC driver to use when connecting to the database. Use:
          <itemizedlist>
          <listitem>
            <userinput>com.mysql.jdbc.Driver</userinput> 
            for MySQL
          </listitem>
          <listitem>
            <userinput>org.postgresql.Driver</userinput> 
            for Postgres
          </listitem>
          </itemizedlist> 
          Other JDBC drivers may work but are not supported.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>db.url</property></term>
      <listitem>
        <para>
          The connection URL that locates the BASE 2 database. The exact syntax 
          of the string depends on the JDBC driver. Here are two examples which 
          leaves all other settings to their defaults:
          <itemizedlist>
          <listitem>
            <userinput>jdbc:mysql://localhost/base2</userinput> 
            for MySQL
          </listitem>
          <listitem>
            <userinput>jdbc:postgresql:base2</userinput> 
            for Postgres
          </listitem>
          </itemizedlist>
          
          You can get more information about the parameters that are supported on the 
          connection URL by reading the documentation from 
          <ulink url="http://dev.mysql.com/doc/refman/5.0/en/connector-j-reference-configuration-properties.html"
            >MySQL</ulink> and 
          <ulink url="http://jdbc.postgresql.org/documentation/81/connect.html"
            >Postgres</ulink>.
            
            
          <note>
            <para>
            For MySQL we recommend that you enable the server-side cursors feature.
            It will reduce memory usage since the JDBC driver does not have to
            load all data into memory:
            <userinput>
            jdbc:mysql://localhost/base2?useCursorFetch=true&amp;defaultFetchSize=100
            </userinput>
            </para>
            
            <para>
            Some MySQL versions (for example, 5.0.27) contains a bug that causes some 
            queries to fail if <userinput>useCursorFetch=true</userinput>. If you experience
            this problem, you have to set it to false. For more information
            see <ulink url="http://base.thep.lu.se/ticket/509">http://base.thep.lu.se/ticket/509</ulink>.
            </para>
          </note>
            
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>db.dynamic.catalog</property></term>
      <listitem>
        <para>
        The name of the catalog where the dynamic database used to store
        analysed data is located. If not specified the same catalog as the regular 
        database is used. The exact meaning of catalog depends on the actual database. 
        For MySQL the catalog is the name of the database so this value is simply the 
        name of the dynamic database. Postgres does not support connecting to multiple 
        databases with the same connection so this should have the same value as the 
        database in the <property>db.url</property> setting.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><property>db.dynamic.schema</property></term>
      <listitem>
        <para>
        The name of the schema where the dynamic database used to store
        analysed data is located. MySQL does not have schemas so this value should 
        be left empty. Postgres supports schemas and we recommend that the dynamic 
        part is created in it's own schema to avoid mixing the dynamic tables with
        the regular ones.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><property>db.username</property></term>
      <listitem>
        <para>
        The username to connect to the database. The user should have full permission 
        to both the regular and the dynamic database.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>db.password</property></term>
      <listitem>
        <para>
         The password for the user.
         </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>db.batch-size</property></term>
      <listitem>
        <para>
        The batch size to use when inserting/updating items with the Batch API. 
        A higher value requires more memory, a lower value degrades performance
        since the number of database connections increases. The default value is 
        50.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>db.queries</property></term>
      <listitem>
        <para>
        The location of an XML file which contains database-specific 
        queries overriding those that does not work from the 
        <filename>/common-queries.xml</filename> file. Use:
        
        <itemizedlist>
          <listitem><userinput>/mysql-queries.xml</userinput> for MySQL</listitem>
          <listitem><userinput>/postgres-queries.xml</userinput> for Postgres</listitem>
        </itemizedlist>
          See also <xref linkend="appendix.otherconfig.sql" />.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>db.extended-properties</property></term>
      <listitem>
        <para>
        The location of an XML file describing the extended properties for extendable 
        item types, ie. the reporters. The default value is <userinput>/extended-properties.xml</userinput>.
        See <xref linkend="appendix.extendedproperties" /> for more information
        about extended properties.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>db.raw-data-types</property></term>
      <listitem>
        <para>
        The location of an XML file describing all raw data types and their properties. 
        The default value is <userinput>/raw-data-types.xml</userinput>.
        See <xref linkend="appendix.rawdatatypes" /> for more information
        about raw data types.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>export.max.items</property></term>
      <listitem>
        <para>
        The maximum number of items the export function should try to load in a single 
        query. This setting exists because MySQL prior to 5.0.2 does not support scrollable 
        result sets, but loads all data into memory. This will result in out of memory 
        exception if exporting too many items at the same time. Postgres does not have 
        this problem. Use:
        
        <itemizedlist>
        <listitem><para>0 for Postgres</para></listitem>
        <listitem>
          <para>
            0 for MySQL version 5.0.2 or above.
            Requires that <userinput>useCursorFetch=true</userinput> is specified in 
            the connection url and  that <userinput>defaultFetchSize=xxx</userinput>
            is set to a value &gt; 0.
          </para>
        </listitem>
        <listitem>
          <para>
            As large as possible value for other MySQL versions. 
            A low value results in more queries and slower performance when 
            exporting data.
          </para>
        </listitem>
        </itemizedlist>
        </para>
      </listitem>
    </varlistentry>
    </variablelist>
    
  </simplesect>
  
  <simplesect id="appendix.base.config.authentication">
    <title>Authentication section</title>
    <para>
      This section describes parameters that are needed if you are
      going to use external authentication. If you let BASE handle this
      you will not have to bother about these settings. See
      <xref linkend="plugin_developer.other.authentication"/> for more information about 
      external authentication.
    </para>
    
    <variablelist>
    <varlistentry>
      <term><property>auth.driver</property></term>
      <listitem>
        <para>
        The class name of the plug-in that acts as the authentication driver. 
        BASE ships with a simple plugin that checks if a user has a valid email 
        account on a POP3 server. It is not enabled by default. The class name 
        of that plugin is <classname docapi="net.sf.basedb.core.authentication">net.sf.basedb.core.authentication.POP3Authenticator</classname>. 
        If no class is specified internal authentication is used.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>auth.init</property></term>
      <listitem>
        <para>
        Initialisation parameters sent to the plug-in when calling the 
        <methodname>init()</methodname> method. The syntax and meaning of this 
        string depends on the plugin. For the <classname docapi="net.sf.basedb.core.authentication">POP3Authenticator</classname> 
        this is simply the name or IP-address of the mail server.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>auth.synchronize</property></term>
      <listitem>
        <para>
        If this setting is 1 or TRUE, BASE will synchronize the extra 
        information (name, address, email, etc.) sent by the authentication driver 
        when a user logs in to BASE. This setting is ignored if the driver does not 
        support extra information.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>auth.cachepasswords</property></term>
      <listitem>
        <para>
        If passwords should be cached by BASE or not. If the passwords are 
        cached a user may login to BASE even if the external authentication 
        server is down. The cached passwords are only used if the external
        authentication does not answer properly.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>auth.daystocache</property></term>
      <listitem>
        <para>
        How many days a cached password is valid if caching is enabled. A value of
        0 caches the passwords forever.
          </para>
      </listitem>
    </varlistentry>
    </variablelist>
  </simplesect>
  
  <simplesect id="appendix.base.config.jobqueue">
    <title>Internal job queue section</title>
    
    <para>
      This section contains setting that control the internal job queue.
      The internal job queue is a simple queue that executes jobs more or
      less in the order they were added to the queue. To make sure long-running
      jobs do not block the queue, there are four slots that uses the
      expected execution time to decide if a job should be allowed to execute 
      or not.
    </para>
    
    <variablelist>
    <varlistentry>
      <term><property>jobqueue.internal.enabled</property></term>
      <listitem>
        <para>
         If <userinput>0</userinput> or <userinput>FALSE</userinput> the internal 
         job queue will be disabled.
         </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>jobqueue.internal.runallplugins</property></term>
      <listitem>
        <para>
         If <userinput>1</userinput> or <userinput>TRUE</userinput> the internal 
         job queue will ignore the <property>useInternalJobQueue</property>
         flag specified on plug-ins. If <userinput>0</userinput> or <userinput>FALSE</userinput>
         the internal job queue will only execute plug-ins which has
         <property>useInternalJobQueue=true</property>
         </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><property>jobqueue.internal.signalreceiver.class</property></term>
      <listitem>
        <para>
         A class implementing the <interfacename docapi="net.sf.basedb.core.signal"
         >SignalReceiver</interfacename>
         interface. The class must have a public no-argument constructor. If
         no value is specified the default setting is:
         <classname docapi="net.sf.basedb.core.signal"
         >net.sf.basedb.core.signal.LocalSignalReceiver</classname>.
         </para>
         <para>
         Change to <classname docapi="net.sf.basedb.core.signal"
         >net.sf.basedb.core.signal.SocketSignalReceiver</classname>
         if the internal job queue must be able to receive signals from outside
         this JVM.
         </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>jobqueue.internal.signalreceiver.init</property></term>
      <listitem>
        <para>
        Initialisation string sent to <methodname>SignalReceiver.init()</methodname>.
        The syntax and meaning of the string depends on the actual implementation
        that is used. Please see the javadoc for more information.
         </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><property>jobqueue.internal.checkinterval</property></term>
      <listitem>
        <para>
         The number of seconds between checks to the database for jobs 
         that are waiting for execution.
         </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>jobqueue.internal.shortest.threads</property></term>
      <term><property>jobqueue.internal.short.threads</property></term>
      <term><property>jobqueue.internal.medium.threads</property></term>
      <term><property>jobqueue.internal.long.threads</property></term>
      <listitem>
        <para>
        Maximum number of threads to reserve for jobs with a given expected
        execution time. A job with a short execution time may use a thread
        from one of the slots with longer execution time. When all threads
        are in use, new jobs will have to wait until an executing job
        has finished.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>jobqueue.internal.shortest.threadpriority</property></term>
      <term><property>jobqueue.internal.short.threadpriority</property></term>
      <term><property>jobqueue.internal.medium.threadpriority</property></term>
      <term><property>jobqueue.internal.long.threadpriority</property></term>
      <listitem>
        <para>
        The priority to give to jobs. The priority is a value between 1 and 10. 
        See <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Thread.html"
        >http://java.sun.com/javase/6/docs/api/java/lang/Thread.html</ulink> 
        for more information about thread priorities.
        </para>
      </listitem>
    </varlistentry>
    </variablelist>

  </simplesect>

  <simplesect id="appendix.base.config.jobagent">
    <title>Job agent section</title>
    
    <para>
      This section contains settings that BASE uses when communicating
      with external job agents. See <xref linkend="installation_upgrade.jobagents"/> 
      for more information about job agents.
    </para>
    
    <variablelist>
    <varlistentry>
      <term><property>agent.maxage</property></term>
      <listitem>
        <para>
        Number of seconds to keep job agent information in the internal cache. 
        The information includes, CPU and memory usage and the status of executing 
        jobs. This setting controls how long the information is kept in the cache 
        before a new request is made to the job agent. The default value is 60 seconds.
          </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term><property>agent.connection.timeout</property></term>
      <listitem>
        <para>
        The timeout in milliseconds to wait for a response from a job agent 
        when sending a request to it. The default timeout is 1000 milliseconds. 
        This should be more than enough if the job agent is on the internal 
        network, but may have to be increased if it is located somewhere else.
          </para>
      </listitem>
    </varlistentry>

    </variablelist>
    
  </simplesect>

  <simplesect id="appendix.base.config.secondary">
    <title>Secondary storage controller</title>
    
    <para>
      This section contains settings for the secondary storage controller. See
      <xref linkend="plugin_developer.other.secondary"/> for more
      information about secondary storage.
    </para>
    
    <variablelist>
    <varlistentry>
      <term><property>secondary.storage.driver</property></term>
      <listitem>
        <para>
        The class name of the plug-in that acts as the secondary storage controller. 
        BASE ships with a simple plug-in that just moves files to another directory, 
        but it is not enabled by default. The class name of that plug-in is 
        <classname docapi="net.sf.basedb.core">net.sf.basedb.core.InternalStorageController</classname>. 
        If no class is specified the secondary storage feature is disabled.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>secondary.storage.init</property></term>
      <listitem>
        <para>
        Initialisation parameters sent to the plug-in when calling the 
        <methodname>init()</methodname> method. The syntax and meaning of this 
        string depends on the plug-in. For the internal controller this is simply 
        the path to the secondary directory.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>secondary.storage.interval</property></term>
      <listitem>
        <para>
        Interval in seconds between each execution of the secondary storage 
        controller plug-in. It must be a value greater than zero or the secondary 
        storage feature will be disabled.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>secondary.storage.time</property></term>
      <listitem>
        <para>
        Time-point values specifying the time(s) of day that the secondary storage controller 
        should be executed. If present, this setting overrides the 
        <property>secondary.storage.interval</property> setting. 
        Time-point values are given as comma-separated list of two-digit, 24-based hour 
        and two-digit minute values. For example: <userinput>03:10,09:00,23:59</userinput>.
          </para>
      </listitem>
    </varlistentry>
    </variablelist>
    
  </simplesect>
  
  <simplesect id="appendix.base.config.secondary.other">
    <title>Other settings</title>
    
    <variablelist>
    <varlistentry>
      <term><property>userfiles</property></term>
      <listitem>
        <para>
        The path to the directory where uploaded and generated files should 
        be stored. This is the primary file storage. See <xref linkend="appendix.base.config.secondary" /> 
        for information about how to configure the secondary storage. Files are not 
        stored in the same directory structure or with the same names as in 
        the BASE filesystem. The internal structure may contain subdirectories.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>permission.timeout</property></term>
      <listitem>
        <para>
        Number of minutes to cache a logged in user's permissions before 
        reloading them. The default value is 10. This setting affect how 
        quickly a changed permission propagate to a logged in user. Permissions 
        are always reloaded when a user logs in.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>cache.timeout</property></term>
      <listitem>
        <para>
        Number of minutes to keep user sessions in the internal cache 
        before the user is automatically logged out. The timeout is counted 
        from the last access made from the user.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>helptext.update</property></term>
      <listitem>
        <para>
          Defines if already existing helptexts in BASE should be overwritten when
          updating the program,
          <xref linkend="installation_upgrade.upgrade" />
          <itemizedlist>
            <listitem>
              <simpara>
                <userinput>true</userinput>
                will overwrite existing helptexts.
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <userinput>false</userinput>
                will leave the existing helptexts in database unchanged and only
                insert new helptexts.
              </simpara>
            </listitem>
          </itemizedlist>
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>plugins.autounload</property></term>
      <listitem>
        <para>
          Enable this setting to let BASE detect if a plug-in JAR file is changed
          and automatically load and use the new code instead of the old code.
          This setting is useful for plug-in developers since they don't have to
          restart the webserver each time the plug-in is recompiled.
          <itemizedlist>
            <listitem>
              <simpara>
                <userinput>true,yes,1</userinput>
                to enable
              </simpara>
            </listitem>
            <listitem>
              <simpara>
                <userinput>false,no,0</userinput>
                to disable (default if no value is specified)
              </simpara>
            </listitem>
          </itemizedlist>
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>plugins.dir</property></term>
      <listitem>
        <para>
          The path to the directory where jar-files for external plugins should be located
          if they should be used with the auto-installer. All new plugins found in this directory, 
          or in any of it's subdirectories, can be selected for installation, see
          <xref linkend="plugins.installation" />. 
          The plugin auto-installer will not be availble if this property isn't defined. 
        </para>

        <para>
          Another benefit is that all plug-ins inside this directory are registered
          with relative paths. This means that there is a lot less hassle when 
          using job agents to run plug-ins. Just change this setting for the job
          agent installation and all plug-ins will work. For plug-ins that are outside
          of this directory you may have to manually register the path if it is different from
          the main path. It will also be a lot easier if you plan to move all plug-ins to
          a different directory. Just move the JAR files and change this setting. There is
          no need to change the paths for each plug-in in the database.
        </para>
            
      </listitem>
    </varlistentry>
    </variablelist>
  </simplesect>

</appendix>