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

Last change on this file since 5442 was 5442, checked in by Nicklas Nordborg, 13 years ago

Fixes #1524: Send messages as emails
  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 36.1 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 5442 2010-10-07 06:48:16Z nicklas $
7 
8  Copyright (C) 2007 Peter Johansson, Nicklas Nordborg, Martin Svensson
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 3
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 BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<appendix id="appendix.base.config">
28 
29  <title>base.config reference</title>
30
31  <para>
32    The <filename>base.config</filename> file is the main configuration file
33    for BASE. It is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename>
34    directory.
35  </para>
36 
37  <simplesect id="appendix.base.config.dbdriver">
38    <title>Database driver section</title>
39   
40    <para>
41      This section has parameters needed for the database connection, such
42      as the database dialect, username and password.
43    </para>
44   
45    <variablelist>
46    <varlistentry>
47      <term><property>db.dialect</property></term>
48      <listitem>
49        <para>
50          The Hibernate dialect to use when generating SQL commands to the database.
51          Use:
52          <itemizedlist>
53          <listitem>
54            <userinput>org.hibernate.dialect.MySQLInnoDBDialect</userinput> 
55            for MySQL
56          </listitem>
57          <listitem>
58            <userinput>org.hibernate.dialect.PostgreSQLDialect</userinput> 
59            for PostgreSQL
60          </listitem>
61          </itemizedlist> 
62          Other dialects may work but are not supported.
63        </para>
64      </listitem>
65    </varlistentry>
66   
67    <varlistentry>
68      <term><property>db.driver</property></term>
69      <listitem>
70        <para>
71          The JDBC driver to use when connecting to the database. Use:
72          <itemizedlist>
73          <listitem>
74            <userinput>com.mysql.jdbc.Driver</userinput> 
75            for MySQL
76          </listitem>
77          <listitem>
78            <userinput>org.postgresql.Driver</userinput> 
79            for PostgreSQL
80          </listitem>
81          </itemizedlist> 
82          Other JDBC drivers may work but are not supported.
83        </para>
84      </listitem>
85    </varlistentry>
86   
87    <varlistentry>
88      <term><property>db.url</property></term>
89      <listitem>
90        <para>
91          The connection URL that locates the BASE database. The exact syntax
92          of the string depends on the JDBC driver. Here are two examples which
93          leaves all other settings to their defaults:
94          <itemizedlist>
95          <listitem>
96            <userinput>jdbc:mysql://localhost/base2</userinput> 
97            for MySQL
98          </listitem>
99          <listitem>
100            <userinput>jdbc:postgresql:base2</userinput> 
101            for PostgreSQL
102          </listitem>
103          </itemizedlist>
104         
105          You can get more information about the parameters that are supported on the
106          connection URL by reading the documentation from
107          <ulink url="http://dev.mysql.com/doc/refman/5.0/en/connector-j-reference-configuration-properties.html"
108            >MySQL</ulink> and
109          <ulink url="http://jdbc.postgresql.org/documentation/81/connect.html"
110            >PostgreSQL</ulink>.
111           
112           
113          <note>
114            <para>
115            For MySQL we recommend that you set the character encoding to UTF-8
116            and enable the server-side cursors feature. The latter option will
117            reduce memory usage since the JDBC driver does not have to
118            load all data into memory. The value below should go into one line
119            <userinput>
120            jdbc:mysql://localhost/base2?characterEncoding=UTF-8&amp;
121              useCursorFetch=true&amp;defaultFetchSize=100&amp;useServerPrepStmts=true
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. PostgreSQL does not support connecting to multiple
146        databases with the same connection so this should have the same value as the
147        database in the <property>db.url</property> setting.
148        </para>
149      </listitem>
150    </varlistentry>
151
152    <varlistentry>
153      <term><property>db.dynamic.schema</property></term>
154      <listitem>
155        <para>
156        The name of the schema where the dynamic database used to store
157        analysed data is located. MySQL does not have schemas so this value should
158        be left empty. PostgreSQL supports schemas and we recommend that the dynamic
159        part is created in it's own schema to avoid mixing the dynamic tables with
160        the regular ones.
161        </para>
162      </listitem>
163    </varlistentry>
164
165    <varlistentry>
166      <term><property>db.username</property></term>
167      <listitem>
168        <para>
169        The username to connect to the database. The user should have full permission
170        to both the regular and the dynamic database.
171        </para>
172      </listitem>
173    </varlistentry>
174   
175    <varlistentry>
176      <term><property>db.password</property></term>
177      <listitem>
178        <para>
179         The password for the user.
180         </para>
181      </listitem>
182    </varlistentry>
183   
184    <varlistentry>
185      <term><property>db.batch-size</property></term>
186      <listitem>
187        <para>
188        The batch size to use when inserting/updating items with the Batch API.
189        A higher value requires more memory, a lower value degrades performance
190        since the number of database connections increases. The default value is
191        50.
192        </para>
193      </listitem>
194    </varlistentry>
195   
196    <varlistentry>
197      <term><property>db.queries</property></term>
198      <listitem>
199        <para>
200        The location of an XML file which contains database-specific
201        queries overriding those that does not work from the
202        <filename>/common-queries.xml</filename> file. Use:
203       
204        <itemizedlist>
205          <listitem><userinput>/mysql-queries.xml</userinput> for MySQL</listitem>
206          <listitem><userinput>/postgres-queries.xml</userinput> for PostgreSQL</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>db.cleanup.interval</property></term>
239      <listitem>
240        <para>
241        Interval in hours between database cleanups. Set this to
242        0 to disable (recommened for job agents). The default value
243        is 24.
244          </para>
245      </listitem>
246    </varlistentry>
247   
248    <varlistentry>
249      <term><property>export.max.items</property></term>
250      <listitem>
251        <para>
252        The maximum number of items the export function should try to load in a single
253        query. This setting exists because MySQL prior to 5.0.2 does not support scrollable
254        result sets, but loads all data into memory. This will result in out of memory
255        exception if exporting too many items at the same time. PostgreSQL does not have
256        this problem. Use:
257       
258        <itemizedlist>
259        <listitem><para>0 for PostgreSQL</para></listitem>
260        <listitem>
261          <para>
262            0 for MySQL version 5.0.2 or above.
263            Requires that <userinput>useCursorFetch=true</userinput> is specified in
264            the connection url and  that <userinput>defaultFetchSize=xxx</userinput>
265            is set to a value &gt; 0.
266          </para>
267        </listitem>
268        <listitem>
269          <para>
270            As large as possible value for other MySQL versions.
271            A low value results in more queries and slower performance when
272            exporting data.
273          </para>
274        </listitem>
275        </itemizedlist>
276        </para>
277      </listitem>
278    </varlistentry>
279    </variablelist>
280   
281  </simplesect>
282 
283  <simplesect id="appendix.base.config.authentication">
284    <title>Authentication section</title>
285    <para>
286      This section describes parameters that are needed if you are
287      going to use external authentication. If you let BASE handle this
288      you will not have to bother about these settings. See
289      <xref linkend="plugin_developer.other.authentication"/> for more information about
290      external authentication.
291    </para>
292   
293    <variablelist>
294    <varlistentry>
295      <term><property>auth.driver</property></term>
296      <listitem>
297        <para>
298        The class name of the plug-in that acts as the authentication driver.
299        BASE ships with a simple plug-in that checks if a user has a valid email
300        account on a POP3 server. It is not enabled by default. The class name
301        of that plug-in is <classname docapi="net.sf.basedb.core.authentication">net.sf.basedb.core.authentication.POP3Authenticator</classname>.
302        If no class is specified internal authentication is used.
303          </para>
304      </listitem>
305    </varlistentry>
306   
307    <varlistentry>
308      <term><property>auth.init</property></term>
309      <listitem>
310        <para>
311        Initialisation parameters sent to the plug-in when calling the
312        <methodname>init()</methodname> method. The syntax and meaning of this
313        string depends on the plug-in. For the <classname docapi="net.sf.basedb.core.authentication">POP3Authenticator</classname> 
314        this is simply the name or IP-address of the mail server.
315          </para>
316      </listitem>
317    </varlistentry>
318   
319    <varlistentry>
320      <term><property>auth.synchronize</property></term>
321      <listitem>
322        <para>
323        If this setting is 1 or TRUE, BASE will synchronize the extra
324        information (name, address, email, etc.) sent by the authentication driver
325        when a user logs in to BASE. This setting is ignored if the driver does not
326        support extra information.
327          </para>
328      </listitem>
329    </varlistentry>
330   
331    <varlistentry>
332      <term><property>auth.cachepasswords</property></term>
333      <listitem>
334        <para>
335        If passwords should be cached by BASE or not. If the passwords are
336        cached a user may login to BASE even if the external authentication
337        server is down. The cached passwords are only used if the external
338        authentication does not answer properly.
339          </para>
340      </listitem>
341    </varlistentry>
342   
343    <varlistentry>
344      <term><property>auth.daystocache</property></term>
345      <listitem>
346        <para>
347        How many days a cached password is valid if caching is enabled. A value of
348        0 caches the passwords forever.
349          </para>
350      </listitem>
351    </varlistentry>
352    </variablelist>
353  </simplesect>
354 
355  <simplesect id="appendix.base.config.jobqueue">
356    <title>Internal job queue section</title>
357   
358    <para>
359      This section contains setting that control the internal job queue.
360      The internal job queue is a simple queue that executes jobs more or
361      less in the order they were added to the queue. To make sure long-running
362      jobs do not block the queue, there are four slots that uses the
363      expected execution time to decide if a job should be allowed to execute
364      or not.
365    </para>
366   
367    <variablelist>
368    <varlistentry>
369      <term><property>jobqueue.internal.enabled</property></term>
370      <listitem>
371        <para>
372         If <userinput>0</userinput> or <userinput>FALSE</userinput> the internal
373         job queue will be disabled.
374         </para>
375      </listitem>
376    </varlistentry>
377   
378    <varlistentry>
379      <term><property>jobqueue.internal.runallplugins</property></term>
380      <listitem>
381        <para>
382         If <userinput>1</userinput> or <userinput>TRUE</userinput> the internal
383         job queue will ignore the <property>useInternalJobQueue</property>
384         flag specified on plug-ins. If <userinput>0</userinput> or <userinput>FALSE</userinput>
385         the internal job queue will only execute plug-ins which has
386         <property>useInternalJobQueue=true</property>
387         </para>
388      </listitem>
389    </varlistentry>
390
391    <varlistentry>
392      <term><property>jobqueue.internal.signalreceiver.class</property></term>
393      <listitem>
394        <para>
395         A class implementing the <interfacename docapi="net.sf.basedb.core.signal"
396         >SignalReceiver</interfacename>
397         interface. The class must have a public no-argument constructor. If
398         no value is specified the default setting is:
399         <classname docapi="net.sf.basedb.core.signal"
400         >net.sf.basedb.core.signal.LocalSignalReceiver</classname>.
401         </para>
402         <para>
403         Change to <classname docapi="net.sf.basedb.core.signal"
404         >net.sf.basedb.core.signal.SocketSignalReceiver</classname>
405         if the internal job queue must be able to receive signals from outside
406         this JVM.
407         </para>
408      </listitem>
409    </varlistentry>
410   
411    <varlistentry>
412      <term><property>jobqueue.internal.signalreceiver.init</property></term>
413      <listitem>
414        <para>
415        Initialisation string sent to <methodname>SignalReceiver.init()</methodname>.
416        The syntax and meaning of the string depends on the actual implementation
417        that is used. Please see the Javadoc for more information.
418         </para>
419      </listitem>
420    </varlistentry>
421
422    <varlistentry>
423      <term><property>jobqueue.internal.checkinterval</property></term>
424      <listitem>
425        <para>
426         The number of seconds between checks to the database for jobs
427         that are waiting for execution.
428         </para>
429      </listitem>
430    </varlistentry>
431   
432    <varlistentry>
433      <term><property>jobqueue.internal.shortest.threads</property></term>
434      <term><property>jobqueue.internal.short.threads</property></term>
435      <term><property>jobqueue.internal.medium.threads</property></term>
436      <term><property>jobqueue.internal.long.threads</property></term>
437      <listitem>
438        <para>
439        Maximum number of threads to reserve for jobs with a given expected
440        execution time. A job with a short execution time may use a thread
441        from one of the slots with longer execution time. When all threads
442        are in use, new jobs will have to wait until an executing job
443        has finished.
444        </para>
445      </listitem>
446    </varlistentry>
447   
448    <varlistentry>
449      <term><property>jobqueue.internal.shortest.threadpriority</property></term>
450      <term><property>jobqueue.internal.short.threadpriority</property></term>
451      <term><property>jobqueue.internal.medium.threadpriority</property></term>
452      <term><property>jobqueue.internal.long.threadpriority</property></term>
453      <listitem>
454        <para>
455        The priority to give to jobs. The priority is a value between 1 and 10.
456        See <ulink url="http://java.sun.com/javase/6/docs/api/java/lang/Thread.html"
457        >http://java.sun.com/javase/6/docs/api/java/lang/Thread.html</ulink> 
458        for more information about thread priorities.
459        </para>
460      </listitem>
461    </varlistentry>
462    </variablelist>
463
464  </simplesect>
465
466  <simplesect id="appendix.base.config.jobagent">
467    <title>Job agent section</title>
468   
469    <para>
470      This section contains settings that BASE uses when communicating
471      with external job agents. See <xref linkend="installation_upgrade.jobagents"/> 
472      for more information about job agents.
473    </para>
474   
475    <variablelist>
476    <varlistentry>
477      <term><property>agent.maxage</property></term>
478      <listitem>
479        <para>
480        Number of seconds to keep job agent information in the internal cache.
481        The information includes, CPU and memory usage and the status of executing
482        jobs. This setting controls how long the information is kept in the cache
483        before a new request is made to the job agent. The default value is 60 seconds.
484          </para>
485      </listitem>
486    </varlistentry>
487
488    <varlistentry>
489      <term><property>agent.connection.timeout</property></term>
490      <listitem>
491        <para>
492        The timeout in milliseconds to wait for a response from a job agent
493        when sending a request to it. The default timeout is 1000 milliseconds.
494        This should be more than enough if the job agent is on the internal
495        network, but may have to be increased if it is located somewhere else.
496          </para>
497      </listitem>
498    </varlistentry>
499
500    </variablelist>
501   
502  </simplesect>
503
504  <simplesect id="appendix.base.config.secondary">
505    <title>Secondary storage controller</title>
506   
507    <para>
508      This section contains settings for the secondary storage controller. See
509      <xref linkend="plugin_developer.other.secondary"/> for more
510      information about secondary storage.
511    </para>
512   
513    <variablelist>
514    <varlistentry>
515      <term><property>secondary.storage.driver</property></term>
516      <listitem>
517        <para>
518        The class name of the plug-in that acts as the secondary storage controller.
519        BASE ships with a simple plug-in that just moves files to another directory,
520        but it is not enabled by default. The class name of that plug-in is
521        <classname docapi="net.sf.basedb.core">net.sf.basedb.core.InternalStorageController</classname>.
522        If no class is specified the secondary storage feature is disabled.
523          </para>
524      </listitem>
525    </varlistentry>
526   
527    <varlistentry>
528      <term><property>secondary.storage.init</property></term>
529      <listitem>
530        <para>
531        Initialisation parameters sent to the plug-in when calling the
532        <methodname>init()</methodname> method. The syntax and meaning of this
533        string depends on the plug-in. For the internal controller this is simply
534        the path to the secondary directory.
535          </para>
536      </listitem>
537    </varlistentry>
538   
539    <varlistentry>
540      <term><property>secondary.storage.interval</property></term>
541      <listitem>
542        <para>
543        Interval in seconds between each execution of the secondary storage
544        controller plug-in. It must be a value greater than zero or the secondary
545        storage feature will be disabled.
546          </para>
547      </listitem>
548    </varlistentry>
549   
550    <varlistentry>
551      <term><property>secondary.storage.time</property></term>
552      <listitem>
553        <para>
554        Time-point values specifying the time(s) of day that the secondary storage controller
555        should be executed. If present, this setting overrides the
556        <property>secondary.storage.interval</property> setting.
557        Time-point values are given as comma-separated list of two-digit, 24-based hour
558        and two-digit minute values. For example: <userinput>03:10,09:00,23:59</userinput>.
559          </para>
560      </listitem>
561    </varlistentry>
562    </variablelist>
563   
564  </simplesect>
565 
566  <simplesect id="appendix.base.config.log">
567    <title>Change history logging section</title>
568   
569    <para>
570      This section contains settings for logging the change history
571      of items.
572    </para>
573   
574    <variablelist>
575    <varlistentry>
576      <term><property>changelog.factory</property></term>
577      <listitem>
578        <para>
579        The factory class that controls the entire logging system. The
580        factory has control of what should be logged, were it should
581        be logged, etc. BASE ships with one factory implementation
582        <classname docapi="net.sf.basedb.core.log.db">DbLogManagerFactory</classname>
583        which logs changes into tables in the database. The server admin
584        may choose a different implementation provided that it implements
585        the <interfacename docapi="net.sf.basedb.core.log">LogManagerFactory</interfacename>
586        interface. See <xref linkend="plugin_developer.other.logging" />.
587        If no factory is specified, logging is disabled.
588          </para>
589      </listitem>
590    </varlistentry>
591    <varlistentry>
592      <term><property>changelog.show-in-web</property></term>
593      <listitem>
594        <para>
595        A boolean value that specifies if the <guilabel>Change history</guilabel>
596        tab should be visible in the web interface or not. The change history
597        tab will show log information that has been stored in the database
598        and it doesn't make sense to show this tab unless the
599        <classname docapi="net.sf.basedb.core.log.db">DbLogManagerFactory</classname>
600        is used.
601          </para>
602         
603          <note>
604            <para>
605            By default, only users that are members of the
606            <guilabel>Administrator</guilabel> role have permission to
607            view the change history. To give other users the same permission,
608            add the <guilabel>Change history</guilabel> permission to
609            the appropriate role(s).
610            </para>
611          </note>
612      </listitem>
613    </varlistentry>
614    <varlistentry>
615      <term><property>changelog.dblogger.detailed-properties</property></term>
616      <listitem>
617        <para>
618        A boolean value that specifies the amount of information
619        that should be logged. If set, the log will contain information
620        about which properties that was modified on each item,
621        otherwise only the type of change (create, update, delete) is
622        logged.
623        </para>
624      </listitem>
625    </varlistentry>
626    </variablelist>
627   
628  </simplesect>
629 
630    <simplesect id="appendix.base.config.smtp">
631    <title>SMTP server section</title>
632   
633    <para>
634      This section contains settings for the SMTP server used for
635      outgoing mail. This is optional, and if not configured outgoing
636      mail will be disabled.
637    </para>
638   
639    <variablelist>
640    <varlistentry>
641      <term><property>mail.server.host</property></term>
642      <listitem>
643        <para>
644        The host name of the SMTP server to use for outgoing mail.
645        If not configured mailing functions will be disabled.
646          </para>
647      </listitem>
648    </varlistentry>
649    <varlistentry>
650      <term><property>mail.server.port</property></term>
651      <listitem>
652        <para>
653        The port the SMTP server is listening on. If not configured a
654        default port is used. Eg. 25 for regular mail server, 465 for
655        SSL mail server.
656          </para>
657      </listitem>
658    </varlistentry>
659    <varlistentry>
660      <term><property>mail.server.ssl</property></term>
661      <listitem>
662        <para>
663        A boolean value that specifies if the SMTP server is using
664        SSL or not.
665        </para>
666      </listitem>
667    </varlistentry>
668    <varlistentry>
669      <term><property>mail.server.tls</property></term>
670      <listitem>
671        <para>
672        A boolean value that specifies if the SMTP server is using
673        TLS or not.
674        </para>
675      </listitem>
676    </varlistentry>
677    <varlistentry>
678      <term><property>mail.from.email</property></term>
679      <listitem>
680        <para>
681        The email address that will be used as the sender of outgoing
682        emails. If not configured mailing functions will be disabled.
683        </para>
684      </listitem>
685    </varlistentry>
686    <varlistentry>
687      <term><property>mail.from.name</property></term>
688      <listitem>
689        <para>
690        Thename that will be used as the sender of outgoing
691        emails. If not configured, a default name is automatically
692        generated using the host name of the BASE server.
693        </para>
694      </listitem>
695    </varlistentry>
696    </variablelist>
697   
698  </simplesect>
699 
700 
701  <simplesect id="appendix.base.config.secondary.other">
702    <title>Other settings</title>
703   
704    <variablelist>
705    <varlistentry>
706      <term><property>userfiles</property></term>
707      <listitem>
708        <para>
709        The path to the directory where uploaded and generated files should
710        be stored. This is the primary file storage. See <xref linkend="appendix.base.config.secondary" /> 
711        for information about how to configure the secondary storage. Files are not
712        stored in the same directory structure or with the same names as in
713        the BASE file system. The internal structure may contain sub-directories.
714          </para>
715      </listitem>
716    </varlistentry>
717   
718    <varlistentry>
719      <term><property>permission.timeout</property></term>
720      <listitem>
721        <para>
722        Number of minutes to cache a logged in user's permissions before
723        reloading them. The default value is 10. This setting affect how
724        quickly a changed permission propagate to a logged in user. Permissions
725        are always reloaded when a user logs in.
726          </para>
727      </listitem>
728    </varlistentry>
729   
730    <varlistentry>
731      <term><property>cache.timeout</property></term>
732      <listitem>
733        <para>
734        Number of minutes to keep user sessions in the internal cache
735        before the user is automatically logged out. The timeout is counted
736        from the last access made from the user.
737          </para>
738      </listitem>
739    </varlistentry>
740   
741    <varlistentry>
742      <term><property>cache.static.disabled</property></term>
743      <listitem>
744        <para>
745        If the static cache should be enabled or disabled. It is enabled by
746        default. Disabling the static cache may reduce performance in some
747        cases. The static cache is used to cache processed information,
748        for example images, so that the database doesn't have to be queried
749        on every request.
750          </para>
751      </listitem>
752    </varlistentry>
753   
754    <varlistentry>
755      <term><property>cache.static.max-age</property></term>
756      <listitem>
757        <para>
758        The maximum age in days of files in the static cache. Files that
759        hasn't been accessed (read or written) in the specified amount
760        of time are deleted.
761          </para>
762      </listitem>
763    </varlistentry>
764   
765    <varlistentry>
766      <term><property>helptext.update</property></term>
767      <listitem>
768        <para>
769          Defines if already existing helptexts in BASE should be overwritten when
770          updating the program,
771          <xref linkend="installation_upgrade.upgrade" />
772          <itemizedlist>
773            <listitem>
774              <simpara>
775                <userinput>true</userinput>
776                will overwrite existing helptexts.
777              </simpara>
778            </listitem>
779            <listitem>
780              <simpara>
781                <userinput>false</userinput>
782                will leave the existing helptexts in database unchanged and only
783                insert new helptexts.
784              </simpara>
785            </listitem>
786          </itemizedlist>
787        </para>
788      </listitem>
789    </varlistentry>
790    <varlistentry>
791      <term><property>plugins.autounload</property></term>
792      <listitem>
793        <para>
794          Enable this setting to let BASE detect if a plug-in JAR file is changed
795          and automatically load and use the new code instead of the old code.
796          This setting is useful for plug-in developers since they don't have to
797          restart the web server each time the plug-in is recompiled.
798          <itemizedlist>
799            <listitem>
800              <simpara>
801                <userinput>true,yes,1</userinput>
802                to enable
803              </simpara>
804            </listitem>
805            <listitem>
806              <simpara>
807                <userinput>false,no,0</userinput>
808                to disable (default if no value is specified)
809              </simpara>
810            </listitem>
811          </itemizedlist>
812        </para>
813      </listitem>
814    </varlistentry>
815    <varlistentry>
816      <term><property>plugins.dir</property></term>
817      <listitem>
818        <para>
819          The path to the directory where jar-files for external plugins should be located
820          if they should be used with the auto-installer. All new plugins found in this directory,
821          or in any of it's sub-directories, can be selected for installation, see
822          <xref linkend="plugins.installation" />.
823          The plugging auto-installer will not be available if this property isn't defined.
824        </para>
825
826        <para>
827          Another benefit is that all plug-ins inside this directory are registered
828          with relative paths. This means that there is a lot less hassle when
829          using job agents to run plug-ins. Just change this setting for the job
830          agent installation and all plug-ins will work. For plug-ins that are outside
831          of this directory you may have to manually register the path if it is different from
832          the main path. It will also be a lot easier if you plan to move all plug-ins to
833          a different directory. Just move the JAR files and change this setting. There is
834          no need to change the paths for each plug-in in the database.
835        </para>
836           
837      </listitem>
838    </varlistentry>
839   
840    <varlistentry>
841      <term><property>locale.language</property></term>
842      <term><property>locale.country</property></term>
843      <term><property>locale.variant</property></term>
844      <listitem>
845        <para>
846          Configure the server to a specific locale. The language and
847          country should be valid ISO codes as specified by the
848          <ulink url="http://download.oracle.com/javase/6/docs/api/java/util/Locale.html"
849            >java.util.Locale</ulink> documentation. The variant
850          can be any value that is valid as part of a filename.
851        </para>
852
853        <note>
854          <para>
855          Note that language codes are usually lower-case but country codes are
856          upper case. Eg. <code>sv</code> is the language code for swedish, and
857          <code>SE</code> is the country code.
858          </para>
859        </note>
860
861        <para>
862          This configuration can be used to provide translations to some parts of the web gui.
863          The aim is to externalize all hard-coded gui elements from the code but
864          it's a long way before this is a reality. The default text elements of
865          the gui are shipped within the BASE jar files and doesn't have any
866          locale-specific dependency. This means that unless a more specific
867          translation is provided the default texts are always used as a fallback.
868          Most of the default texts are found in property files in the
869          <filename>/net/sf/basedb/clients/web/resources</filename>
870          directory inside the <filename>BASE2Webclient.jar</filename>
871          file. Translations should be located in the same relative path
872          either inside their own JAR file or in the <filename>WEB-INF/classes</filename> 
873          directory. The file names should be extended with the language, country
874          and variant separated with an underscore. For example, files with a swedish
875          translation should be named <filename>*_sv.properties</filename>, and files
876          with a swedish translation in Finland using the 'foo' variant should be
877          named <filename>*_sv_FI_foo.properties</filename>.
878        </para>
879       
880        <note>
881          <para>
882            Note that it is valid to have empty values for language and/or country
883            and still specify a variant. Underscores are NOT collapsed. For
884            example, in a swedish translation using the 'foo' variant the
885            files should be named <filename>*_sv__foo.properties</filename>.
886          </para>
887        </note>
888       
889        <important>
890          <para>
891            All files should be saved in UTF-8 format.
892          </para>
893        </important>
894       
895      </listitem>
896    </varlistentry>
897   
898    </variablelist>
899  </simplesect>
900
901  <simplesect id="appendix.base.config.ssl">
902    <title>SSL section</title>
903   
904    <para>
905      This section is for global configuration of SSL (HTTPS) connection
906      settings. Note that users can re-configure SSL connections per-file
907      basis by setting up File-server items, so there is usually no need
908      to change anything in this section. If the majority of users on the
909      BASE server is using a particular https file server for external files it
910      may make sense to register the certificates globally.
911    </para>
912   
913    <para>
914      When a https connection is made the server must present a valid
915      certificate or the client (BASE) will refuse to connect to it.
916      Typically, all certificates that have been signed by a recognised
917      Certification Authority are considered valid. The major reason for
918      configuring this section is to provide support for servers that
919      use a self-signed certificate.
920      Server-side certificate are stored in a <emphasis>trust-store</emphasis>.
921      A default trust-store is shipped with the Java runtime installation
922      and is found in <filename>&lt;java-home&gt;/jre/lib/security/cacerts</filename>.
923      This file contains the certificates of all recognised certification authorities.
924    </para>
925   
926    <para>
927      A https server may also require that the client has a valid certificate
928      in order to accept connections from it. Typically, the owner of the
929      server issues a certificate that the client must install in order
930      to access the server. This type of certificate is stored in a
931      <emphasis>key-store</emphasis>. By default, no key-store is setup.
932    </para>
933   
934    <para>
935      If all you need is to support servers with self-signed certificates we
936      recommend that those certificates are imported to the above mentioned file.
937      No configuration changes are needed. If a key-store is needed, you must also
938      configure the trust-store. Read the <ulink 
939      url="http://java.sun.com/javase/6/docs/technotes/guides/security/jsse/JSSERefGuide.html"
940      >Java Secure Socket Extension Reference Guide</ulink> for more information about Java
941      security and SSL. Java ships with a certificate management tool that can be used
942      to manage certificate files and a lot of other things. The
943      <ulink url="http://java.sun.com/javase/6/docs/technotes/tools/windows/keytool.html"
944      >keytool - Key and Certificate Management Tool</ulink> document contains more information
945      about this tool.
946    </para>
947   
948    <para>
949      If you want to setup your own test environment with a https server that only
950      accepts clients with a trusted certificate you can find some information about
951      this on our wiki: <ulink url="http://base.thep.lu.se/wiki/HttpsFiles"
952      >http://base.thep.lu.se/wiki/HttpsFiles</ulink>
953    </para>
954   
955    <variablelist>
956    <varlistentry>
957      <term><property>ssl.context.protocol</property></term>
958      <listitem>
959        <para>
960        The SSL protocol to use. The default value is TLS.
961          </para>
962      </listitem>
963    </varlistentry>
964    <varlistentry>
965      <term><property>ssl.context.provider</property></term>
966      <listitem>
967        <para>
968        A security provider implementation. If not specified a suitable default is
969        selected.
970          </para>
971      </listitem>
972    </varlistentry>
973    <varlistentry>
974      <term><property>ssl.keystore.file</property></term>
975      <listitem>
976        <para>
977        The full path to a key-store file. If not specified no key-store is used.
978          </para>
979      </listitem>
980    </varlistentry>
981    <varlistentry>
982      <term><property>ssl.keystore.password</property></term>
983      <listitem>
984        <para>
985        The password for unlocking the keys in the key-store. All keys must use
986        the same password.
987          </para>
988      </listitem>
989    </varlistentry>
990    <varlistentry>
991      <term><property>ssl.keystore.type</property></term>
992      <listitem>
993        <para>
994        The file type of the key-store file. The default value is 'JKS'.
995          </para>
996      </listitem>
997    </varlistentry>
998    <varlistentry>
999      <term><property>ssl.keystore.provider</property></term>
1000      <listitem>
1001        <para>
1002        The name of a provider implementation to use for reading the key-store file.
1003        If not specified a suitable default is used.
1004          </para>
1005      </listitem>
1006    </varlistentry>
1007    <varlistentry>
1008      <term><property>ssl.keystore.algorithm</property></term>
1009      <listitem>
1010        <para>
1011        The algorithm used in the key-store file. The default value is
1012        'SunX509'.
1013          </para>
1014      </listitem>
1015    </varlistentry>
1016    <varlistentry>
1017      <term><property>ssl.truststore.file</property></term>
1018      <listitem>
1019        <para>
1020        The full path to a trust-store certificate file. If not specified
1021        the default depends on the key-store setting. If no key-store is
1022        configured, the default trust-store is used. If a key-store has
1023        been configured no trust-store is used.
1024          </para>
1025      </listitem>
1026    </varlistentry>
1027    <varlistentry>
1028      <term><property>ssl.truststore.password</property></term>
1029      <listitem>
1030        <para>
1031        The password for unlocking the certificates in the trust-store. All certificates
1032        must use the same password.
1033          </para>
1034      </listitem>
1035    </varlistentry>
1036    <varlistentry>
1037      <term><property>ssl.truststore.type</property></term>
1038      <listitem>
1039        <para>
1040        The file type of the trust-store file. The default value is 'JKS'.
1041          </para>
1042      </listitem>
1043    </varlistentry>
1044    <varlistentry>
1045      <term><property>ssl.truststore.provider</property></term>
1046      <listitem>
1047        <para>
1048        The name of a provider implementation to use for reading the trust-store file.
1049        If not specified a suitable default is used.
1050          </para>
1051      </listitem>
1052    </varlistentry>
1053    <varlistentry>
1054      <term><property>ssl.truststore.algorithm</property></term>
1055      <listitem>
1056        <para>
1057        The algorithm used in the trust-store file. The default value is
1058        'PKIX'.
1059          </para>
1060      </listitem>
1061    </varlistentry>
1062    </variablelist>
1063   
1064  </simplesect>
1065
1066</appendix>
1067
Note: See TracBrowser for help on using the repository browser.