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

Last change on this file was 7997, checked in by Nicklas Nordborg, 4 months ago

Updated documentation about MySQL support is ending.

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