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

<?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 7548 2018-12-10 11:53:32Z nicklas $
  
  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 BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<appendix id="appendix.base.config">
  <?dbhtml filename="base.config.html" ?>
  
  <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. Most configuration properties have sensible defaults or are only used
    for advanced features. However, a few are required and may need to be specified
    or changed:
  </para>
  
  <itemizedlist>
    <listitem>
      <property>db.dialect</property>,
      <property>db.url</property>, <property>db.username</property>,
      <property>db.password</property>: 
      Settings for connecting to the database.
    </listitem>
    <listitem>
      <property>userfiles</property>: Setting that specify where uploaded files are stored 
      on the BASE server.
    </listitem>
    <listitem>
      <property>plugins.dir</property>: Settings that specify where plug-ins and extensions 
      are installed.
    </listitem>
  </itemizedlist>
  
  <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.MySQL5InnoDBDialect</userinput> 
            for MySQL
          </listitem>
          <listitem>
            <userinput>org.hibernate.dialect.PostgreSQL9Dialect</userinput> 
            for PostgreSQL
          </listitem>
          </itemizedlist> 
          Other dialects 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 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/basedb</userinput> 
            for MySQL
          </listitem>
          <listitem>
            <userinput>jdbc:postgresql:basedb</userinput> 
            for PostgreSQL
          </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.1/en/connector-j-reference-configuration-properties.html"
            >MySQL</ulink> and 
          <ulink url="http://jdbc.postgresql.org/documentation/81/connect.html"
            >PostgreSQL</ulink>.
            
            
          <note>
            <para>
            For MySQL we recommend that you set the character encoding to UTF-8
            and enable the server-side cursors feature. The latter option will 
            reduce memory usage since the JDBC driver does not have to
            load all data into memory. The value below should go into one line
            <userinput>
            jdbc:mysql://localhost/basedb?characterEncoding=UTF-8&amp;useCursorFetch=true&amp;defaultFetchSize=100&amp;useServerPrepStmts=true
            </userinput>
            </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. PostgreSQL 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. PostgreSQL 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 PostgreSQL</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>db.cleanup.interval</property></term>
      <listitem>
        <para>
        Interval in hours between database cleanups. Set this to
        0 to disable (recommened for job agents). The default value 
        is 24. The cleanup will remove entries in the database that
        have been orphaned due to other information that has been removed.
        For example, change history entries, any-to-any links and 
        permission keys.
          </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="extensions_developer.login-manager"/> for more information about 
      external authentication.
    </para>
    
    <variablelist>
    <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 manager 
        when a user logs in to BASE. This setting is ignored if the manager does not 
        provide 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://download.oracle.com/javase/6/docs/api/java/lang/Thread.html"
        >http://download.oracle.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.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>
    
    <note>
      This feature has been deprecated in BASE 3.14 and will be removed in a
      future release. The recommendation is to replace this with an
      external files solution instead.
    </note>
    
    <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. If this property is not specified, <property>secondary.storage.time</property>
        should be set, 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.log">
    <title>Change history logging section</title>
    
    <para>
      This section contains settings for logging the change history
      of items. Logging is disabled by default, but BASE ships
      with one implementation that log changes to the database.
      To enable it, log in to the web client with administrator
      privileges and enable the <guilabel>Database log manager</guilabel>
      extension. See <xref linkend="extensions_developer.logging" /> for more 
      information about implementing custom logging.
    </para>
    
    <variablelist>
    <varlistentry>
      <term><property>changelog.show-in-web</property></term>
      <listitem>
        <para>
        A boolean value that specifies if the <guilabel>Change history</guilabel>
        tab should be visible in the web interface or not. The change history
        tab will show log information that has been stored in the database
        and it doesn't make sense to show this tab unless the 
        <guilabel>Database log manager</guilabel> has been enabled.
          </para>
          
          <note>
            <para>
            By default, only users that are members of the 
            <guilabel>Administrator</guilabel> role have permission to 
            view the change history. To give other users the same permission,
            add the <guilabel>Change history</guilabel> permission to
            the appropriate role(s).
            </para>
          </note>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>changelog.dblogger.detailed-properties</property></term>
      <listitem>
        <para>
        A boolean value that specifies the amount of information 
        that should be logged by the database log manager. If set, the log 
        will contain information about which properties that was modified on each item, 
        otherwise only the type of change (create, update, delete) is logged.
        </para>
      </listitem>
    </varlistentry>
    </variablelist>
    
  </simplesect>
  
    <simplesect id="appendix.base.config.smtp">
    <title>SMTP server section</title>
    
    <para>
      This section contains settings for the SMTP server used for
      outgoing mail. This is optional, and if not configured outgoing
      mail (including 2-factor login) will be disabled.
    </para>
    
    <variablelist>
    <varlistentry>
      <term><property>mail.server.host</property></term>
      <listitem>
        <para>
        The host name of the SMTP server to use for outgoing mail.
        If not configured mailing functions will be disabled.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>mail.server.port</property></term>
      <listitem>
        <para>
        The port the SMTP server is listening on. If not configured a
        default port is used. Eg. 25 for regular mail server, 465 for
        SSL mail server.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>mail.server.ssl</property></term>
      <listitem>
        <para>
        A boolean value that specifies if the SMTP server is using
        SSL or not.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>mail.server.tls</property></term>
      <listitem>
        <para>
        A boolean value that specifies if the SMTP server is using
        TLS or not.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>mail.from.email</property></term>
      <listitem>
        <para>
        The email address that will be used as the sender of outgoing
        emails. If not configured mailing functions will be disabled.
        </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>mail.from.name</property></term>
      <listitem>
        <para>
        Thename that will be used as the sender of outgoing
        emails. If not configured, a default name is automatically
        generated using the host name of the BASE server.
        </para>
      </listitem>
    </varlistentry>
    </variablelist>
    
  </simplesect>
  
  <simplesect id="appendix.base.config.plugin">
    <title>Plug-ins and extensions</title>
    <variablelist>
    <varlistentry>
      <term><property>plugins.dir</property></term>
      <listitem>
        <para>
          The path to the directory where jar-files for external plug-ins and extensions 
          are located. All new plug-ins and extensions found in this directory, can be selected 
          for installation, see <xref linkend="plugins.installation" />. 
        </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 web server 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>
          Note that extensions doesn't support this feature. Use the installation
          wizard to update an extension.
        </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>extensions.disabled</property></term>
      <listitem>
        <para>
          A boolean flag that, if set, disables all external extensions.
          Plug-ins or core extensions will never be disabled.
        </para>
      </listitem>
    </varlistentry>
    
    </variablelist>
  </simplesect>
  
  <simplesect id="appendix.base.config.other">
    <title>Other settings</title>

    <variablelist>
    <varlistentry>
      <term><property>app.title</property></term>
      <listitem>
        <para>
        The title that is displayed in the browser tab. Use <code>$VERSION</code>
        to include the current BASE version and <code>$SERVER</code> to include the 
        server name.
          </para>
      </listitem>
    </varlistentry>

    <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 file system. The internal structure may contain sub-directories.
          </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>cache.static.disabled</property></term>
      <listitem>
        <para>
        If the static cache should be enabled or disabled. It is enabled by
        default. Disabling the static cache may reduce performance in some
        cases. The static cache is used to cache processed information,
        for example images, so that the database doesn't have to be queried
        on every request.
          </para>
      </listitem>
    </varlistentry>
    
    <varlistentry>
      <term><property>cache.static.max-age</property></term>
      <listitem>
        <para>
        The maximum age in days of files in the static cache. Files that 
        hasn't been accessed (read or written) in the specified amount
        of time are deleted. 
          </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" />
          <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>locale.language</property></term>
      <term><property>locale.country</property></term>
      <term><property>locale.variant</property></term>
      <listitem>
        <para>
          Configure the server to a specific locale. The language and
          country should be valid ISO codes as specified by the
          <ulink url="http://download.oracle.com/javase/6/docs/api/java/util/Locale.html"
            >java.util.Locale</ulink> documentation. The variant
          can be any value that is valid as part of a filename. 
        </para>

        <note>
          <para>
          Note that language codes are usually lower-case but country codes are
          upper case. Eg. <code>sv</code> is the language code for swedish, and
          <code>SE</code> is the country code.
          </para>
        </note>

        <para>
          This configuration can be used to provide translations to some parts of the web gui. 
          The aim is to externalize all hard-coded gui elements from the code but
          it's a long way before this is a reality. The default text elements of
          the gui are shipped within the BASE jar files and doesn't have any
          locale-specific dependency. This means that unless a more specific 
          translation is provided the default texts are always used as a fallback.
          Most of the default texts are found in property files in the 
          <filename>/net/sf/basedb/clients/web/resources</filename>
          directory inside the <filename>base-webclient-3.x.jar</filename>
          file. Translations should be located in the same relative path
          either inside their own JAR file or in the <filename>WEB-INF/classes</filename> 
          directory. The file names should be extended with the language, country 
          and variant separated with an underscore. For example, files with a swedish 
          translation should be named <filename>*_sv.properties</filename>, and files
          with a swedish translation in Finland using the 'foo' variant should be 
          named <filename>*_sv_FI_foo.properties</filename>.
        </para>
        
        <note>
          <para>
            Note that it is valid to have empty values for language and/or country
            and still specify a variant. Underscores are NOT collapsed. For
            example, in a swedish translation using the 'foo' variant the
            files should be named <filename>*_sv__foo.properties</filename>.
          </para>
        </note>
        
        <important>
          <para>
            All files should be saved in UTF-8 format.
          </para>
        </important>
        
      </listitem>
    </varlistentry>
    
    </variablelist>
  </simplesect>

  <simplesect id="appendix.base.config.ssl">
    <title>SSL section</title>
    
    <para>
      This section is for global configuration of SSL (HTTPS) connection
      settings used when BASE need to access external file items. Note that 
      users can re-configure SSL connections per-file
      basis by setting up File-server items, so there is usually no need
      to change anything in this section. If the majority of users on the 
      BASE server is using a particular https file server for external files it
      may make sense to register the certificates globally.
    </para>
    
    <para>
      When a https connection is made the server must present a valid 
      certificate or the client (BASE) will refuse to connect to it. 
      Typically, all certificates that have been signed by a recognised
      Certification Authority are considered valid. The major reason for
      configuring this section is to provide support for servers that
      use a self-signed certificate.
      Server-side certificate are stored in a <emphasis>trust-store</emphasis>.
      A default trust-store is shipped with the Java runtime installation
      and is found in <filename>&lt;java-home&gt;/jre/lib/security/cacerts</filename>.
      This file contains the certificates of all recognised certification authorities.
    </para>
    
    <para>
      A https server may also require that the client has a valid certificate
      in order to accept connections from it. Typically, the owner of the 
      server issues a certificate that the client must install in order
      to access the server. This type of certificate is stored in a 
      <emphasis>key-store</emphasis>. By default, no key-store is setup.
    </para>
    
    <para>
      If all you need is to support servers with self-signed certificates we
      recommend that those certificates are imported to the above mentioned file.
      No configuration changes are needed. If a key-store is needed, you must also
      configure the trust-store. Read the <ulink 
      url="http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html"
      >Java Secure Socket Extension Reference Guide</ulink> for more information about Java 
      security and SSL. Java ships with a certificate management tool that can be used
      to manage certificate files and a lot of other things. The
      <ulink url="http://java.sun.com/javase/6/docs/technotes/tools/windows/keytool.html"
      >keytool - Key and Certificate Management Tool</ulink> document contains more information
      about this tool.
    </para>
    
    <para>
      If you want to setup your own test environment with a https server that only
      accepts clients with a trusted certificate you can find some information about
      this on our wiki: <ulink url="http://base.thep.lu.se/wiki/HttpsFiles"
      >http://base.thep.lu.se/wiki/HttpsFiles</ulink>
    </para>
    
    <variablelist>
    <varlistentry>
      <term><property>ssl.context.protocol</property></term>
      <listitem>
        <para>
        The SSL protocol to use. The default value is TLS.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>ssl.context.provider</property></term>
      <listitem>
        <para>
        A security provider implementation. If not specified a suitable default is
        selected.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>ssl.keystore.file</property></term>
      <listitem>
        <para>
        The full path to a key-store file. If not specified no key-store is used.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>ssl.keystore.password</property></term>
      <listitem>
        <para>
        The password for unlocking the keys in the key-store. All keys must use
        the same password.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>ssl.keystore.type</property></term>
      <listitem>
        <para>
        The file type of the key-store file. The default value is 'JKS'.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>ssl.keystore.provider</property></term>
      <listitem>
        <para>
        The name of a provider implementation to use for reading the key-store file.
        If not specified a suitable default is used.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>ssl.keystore.algorithm</property></term>
      <listitem>
        <para>
        The algorithm used in the key-store file. The default value is
        'SunX509'.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>ssl.truststore.file</property></term>
      <listitem>
        <para>
        The full path to a trust-store certificate file. If not specified 
        the default depends on the key-store setting. If no key-store is 
        configured, the default trust-store is used. If a key-store has
        been configured no trust-store is used.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>ssl.truststore.password</property></term>
      <listitem>
        <para>
        The password for unlocking the certificates in the trust-store. All certificates
        must use the same password.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>ssl.truststore.type</property></term>
      <listitem>
        <para>
        The file type of the trust-store file. The default value is 'JKS'.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>ssl.truststore.provider</property></term>
      <listitem>
        <para>
        The name of a provider implementation to use for reading the trust-store file.
        If not specified a suitable default is used.
          </para>
      </listitem>
    </varlistentry>
    <varlistentry>
      <term><property>ssl.truststore.algorithm</property></term>
      <listitem>
        <para>
        The algorithm used in the trust-store file. The default value is
        'PKIX'.
          </para>
      </listitem>
    </varlistentry>
    </variablelist>
    
  </simplesect>
  
  <simplesect id="appendix.base.config.migrate">
    <title>Migration section</title>
    
    <para>
      The settings in this section only affect the migration program that can
      be used to move a BASE installation from a MySQL database to PostgreSQL.
      For more information about this see <xref linkend="installation.migrate" />.
    </para>
    
    <variablelist>
      <varlistentry>
        <term><property>migrate.export.compress</property></term>
        <listitem>
          <para>
            Enable this option
            to compress the data files generated by the export. This may
            improve performance in case disk speed is a limiting factor.
            Default is to not compress.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><property>migrate.export.fetch-size</property></term>
        <listitem>
          <para>
            The number
            of rows that should be fetch at the same time from the database.
            A higher value may increase the performance but uses more
            memory. The default value is 20000.
          </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><property>migrate.import.analyze</property></term>
        <listitem>
          <para>
            Enable this flag to issue an SQL statment for statistical
            analysis of the imported data before continuing with the next
            table. Disabling this may result in very poor performance. This
            option is enabled by default.
          </para>
        </listitem>
      </varlistentry>
  
      <varlistentry>
        <term><property>migrate.import.drop-primary-key</property></term>
        <listitem>
          <para>
            Enable this flag to drop the primary key of a table before 
            importing data to it. This may increase the performance. The 
            primary key is re-created after the data has been imported.
            This option is enabled by default.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><property>migrate.import.drop-constraints</property></term>
        <listitem>
          <para>
            Enable this flag to drop unique constraints and indexes before 
            importing data to a table. This may increase the performance. 
            The constraints and indexes are re-created after the data has been 
            imported. NOTE! Foreign key constraints are not affected by this flag, 
            since they must always be dropped. This option is enabled by
            default.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
    
  </simplesect>

</appendix>