Ignore:
Timestamp:
May 15, 2007, 1:23:00 PM (16 years ago)
Author:
Nicklas Nordborg
Message:

References #594: Write "Appendix: base.config reference"

Now ready for reading.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/src/docbook/appendix/base.config.xml

    r3334 r3340  
    3232
    3333  <para>
    34     This document is only available in the old format.
    35     See <ulink url="http://base.thep.lu.se/chrome/site/doc/admin/base.config.html"
    36       >http://base.thep.lu.se/chrome/site/doc/admin/base.config.html</ulink>.
     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.
    3737  </para>
    3838 
     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 regaular 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 the 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 to 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 authenitcation. If you let BASE handle this
     277      you will not have to bother about theese 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 to the
     352      expected execution time to decide if a job should be allowed to excute
     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 includs, 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 repsonse 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 paramters 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 seconday 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-separted 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    </variablelist>
     553  </simplesect>
    39554
    40555</appendix>
Note: See TracChangeset for help on using the changeset viewer.