Appendix C. base.config reference

The base.config file is the main configuration file for BASE. It is located in the <basedir>/www/WEB-INF/classes directory.

Database driver section

This section has parameters needed for the database connection, such as the database dialect, username and password.

db.dialect

The Hibernate dialect to use when generating SQL commands to the database. Use:

  • org.hibernate.dialect.MySQLInnoDBDialect for MySQL
  • org.hibernate.dialect.PostgreSQLDialect for PostgreSQL

Other dialects may work but are not supported.

db.driver

The JDBC driver to use when connecting to the database. Use:

  • com.mysql.jdbc.Driver for MySQL
  • org.postgresql.Driver for PostgreSQL

Other JDBC drivers may work but are not supported.

db.url

The connection URL that locates the BASE database. The exact syntax of the string depends on the JDBC driver. Here are two examples which leaves all other settings to their defaults:

  • jdbc:mysql://localhost/base2 for MySQL
  • jdbc:postgresql:base2 for PostgreSQL

You can get more information about the parameters that are supported on the connection URL by reading the documentation from MySQL and PostgreSQL.

[Note] Note

For MySQL we recommend that you set the character encoding to UTF-8 and enable the server-side cursors feature. The latter option will reduce memory usage since the JDBC driver does not have to load all data into memory. The value below should go into one line jdbc:mysql://localhost/base2?characterEncoding=UTF-8& useCursorFetch=true&defaultFetchSize=100&useServerPrepStmts=true

Some MySQL versions (for example, 5.0.27) contains a bug that causes some queries to fail if useCursorFetch=true. If you experience this problem, you have to set it to false. For more information see http://base.thep.lu.se/ticket/509.

db.dynamic.catalog

The name of the catalog where the dynamic database used to store analysed data is located. If not specified the same catalog as the regular database is used. The exact meaning of catalog depends on the actual database. For MySQL the catalog is the name of the database so this value is simply the name of the dynamic database. PostgreSQL does not support connecting to multiple databases with the same connection so this should have the same value as the database in the db.url setting.

db.dynamic.schema

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

db.username

The username to connect to the database. The user should have full permission to both the regular and the dynamic database.

db.password

The password for the user.

db.batch-size

The batch size to use when inserting/updating items with the Batch API. A higher value requires more memory, a lower value degrades performance since the number of database connections increases. The default value is 50.

db.queries

The location of an XML file which contains database-specific queries overriding those that does not work from the /common-queries.xml file. Use:

  • /mysql-queries.xml for MySQL
  • /postgres-queries.xml for PostgreSQL

See also Section J.1, “mysql-queries.xml and postgres-queries.xml”.

db.extended-properties

The location of an XML file describing the extended properties for extendable item types, ie. the reporters. The default value is /extended-properties.xml. See Appendix D, extended-properties.xml reference for more information about extended properties.

db.raw-data-types

The location of an XML file describing all raw data types and their properties. The default value is /raw-data-types.xml. See Appendix E, Platforms and raw-data-types.xml reference for more information about raw data types.

db.cleanup.interval

Interval in hours between database cleanups. Set this to 0 to disable (recommened for job agents). The default value is 24.

export.max.items

The maximum number of items the export function should try to load in a single query. This setting exists because MySQL prior to 5.0.2 does not support scrollable result sets, but loads all data into memory. This will result in out of memory exception if exporting too many items at the same time. PostgreSQL does not have this problem. Use:

  • 0 for PostgreSQL

  • 0 for MySQL version 5.0.2 or above. Requires that useCursorFetch=true is specified in the connection url and that defaultFetchSize=xxx is set to a value > 0.

  • As large as possible value for other MySQL versions. A low value results in more queries and slower performance when exporting data.

Authentication section

This section describes parameters that are needed if you are going to use external authentication. If you let BASE handle this you will not have to bother about these settings. See Section 26.6.1, “Authentication plug-ins” for more information about external authentication.

auth.driver

The class name of the plug-in that acts as the authentication driver. BASE ships with a simple plug-in that checks if a user has a valid email account on a POP3 server. It is not enabled by default. The class name of that plug-in is net.sf.basedb.core.authentication.POP3Authenticator. If no class is specified internal authentication is used.

auth.init

Initialisation parameters sent to the plug-in when calling the init() method. The syntax and meaning of this string depends on the plug-in. For the POP3Authenticator this is simply the name or IP-address of the mail server.

auth.synchronize

If this setting is 1 or TRUE, BASE will synchronize the extra information (name, address, email, etc.) sent by the authentication driver when a user logs in to BASE. This setting is ignored if the driver does not support extra information.

auth.cachepasswords

If passwords should be cached by BASE or not. If the passwords are cached a user may login to BASE even if the external authentication server is down. The cached passwords are only used if the external authentication does not answer properly.

auth.daystocache

How many days a cached password is valid if caching is enabled. A value of 0 caches the passwords forever.

Internal job queue section

This section contains setting that control the internal job queue. The internal job queue is a simple queue that executes jobs more or less in the order they were added to the queue. To make sure long-running jobs do not block the queue, there are four slots that uses the expected execution time to decide if a job should be allowed to execute or not.

jobqueue.internal.enabled

If 0 or FALSE the internal job queue will be disabled.

jobqueue.internal.runallplugins

If 1 or TRUE the internal job queue will ignore the useInternalJobQueue flag specified on plug-ins. If 0 or FALSE the internal job queue will only execute plug-ins which has useInternalJobQueue=true

jobqueue.internal.signalreceiver.class

A class implementing the SignalReceiver interface. The class must have a public no-argument constructor. If no value is specified the default setting is: net.sf.basedb.core.signal.LocalSignalReceiver.

Change to net.sf.basedb.core.signal.SocketSignalReceiver if the internal job queue must be able to receive signals from outside this JVM.

jobqueue.internal.signalreceiver.init

Initialisation string sent to SignalReceiver.init(). The syntax and meaning of the string depends on the actual implementation that is used. Please see the Javadoc for more information.

jobqueue.internal.checkinterval

The number of seconds between checks to the database for jobs that are waiting for execution.

jobqueue.internal.shortest.threads, jobqueue.internal.short.threads, jobqueue.internal.medium.threads, jobqueue.internal.long.threads

Maximum number of threads to reserve for jobs with a given expected execution time. A job with a short execution time may use a thread from one of the slots with longer execution time. When all threads are in use, new jobs will have to wait until an executing job has finished.

jobqueue.internal.shortest.threadpriority, jobqueue.internal.short.threadpriority, jobqueue.internal.medium.threadpriority, jobqueue.internal.long.threadpriority

The priority to give to jobs. The priority is a value between 1 and 10. See http://java.sun.com/javase/6/docs/api/java/lang/Thread.html for more information about thread priorities.

Job agent section

This section contains settings that BASE uses when communicating with external job agents. See Section 21.2, “Installing job agents” for more information about job agents.

agent.maxage

Number of seconds to keep job agent information in the internal cache. The information includes, CPU and memory usage and the status of executing jobs. This setting controls how long the information is kept in the cache before a new request is made to the job agent. The default value is 60 seconds.

agent.connection.timeout

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

Secondary storage controller

This section contains settings for the secondary storage controller. See Section 26.6.2, “Secondary file storage plugins” for more information about secondary storage.

secondary.storage.driver

The class name of the plug-in that acts as the secondary storage controller. BASE ships with a simple plug-in that just moves files to another directory, but it is not enabled by default. The class name of that plug-in is net.sf.basedb.core.InternalStorageController. If no class is specified the secondary storage feature is disabled.

secondary.storage.init

Initialisation parameters sent to the plug-in when calling the init() method. The syntax and meaning of this string depends on the plug-in. For the internal controller this is simply the path to the secondary directory.

secondary.storage.interval

Interval in seconds between each execution of the secondary storage controller plug-in. It must be a value greater than zero or the secondary storage feature will be disabled.

secondary.storage.time

Time-point values specifying the time(s) of day that the secondary storage controller should be executed. If present, this setting overrides the secondary.storage.interval setting. Time-point values are given as comma-separated list of two-digit, 24-based hour and two-digit minute values. For example: 03:10,09:00,23:59.

Change history logging section

This section contains settings for logging the change history of items.

changelog.factory

The factory class that controls the entire logging system. The factory has control of what should be logged, were it should be logged, etc. BASE ships with one factory implementation DbLogManagerFactory which logs changes into tables in the database. The server admin may choose a different implementation provided that it implements the LogManagerFactory interface. See Section 26.6.6, “Logging plug-ins”. If no factory is specified, logging is disabled.

changelog.show-in-web

A boolean value that specifies if the Change history tab should be visible in the web interface or not. The change history tab will show log information that has been stored in the database and it doesn't make sense to show this tab unless the DbLogManagerFactory is used.

[Note] Note

By default, only users that are members of the Administrator role have permission to view the change history. To give other users the same permission, add the Change history permission to the appropriate role(s).

changelog.dblogger.detailed-properties

A boolean value that specifies the amount of information that should be logged. If set, the log will contain information about which properties that was modified on each item, otherwise only the type of change (create, update, delete) is logged.

SMTP server section

This section contains settings for the SMTP server used for outgoing mail. This is optional, and if not configured outgoing mail will be disabled.

mail.server.host

The host name of the SMTP server to use for outgoing mail. If not configured mailing functions will be disabled.

mail.server.port

The port the SMTP server is listening on. If not configured a default port is used. Eg. 25 for regular mail server, 465 for SSL mail server.

mail.server.ssl

A boolean value that specifies if the SMTP server is using SSL or not.

mail.server.tls

A boolean value that specifies if the SMTP server is using TLS or not.

mail.from.email

The email address that will be used as the sender of outgoing emails. If not configured mailing functions will be disabled.

mail.from.name

Thename that will be used as the sender of outgoing emails. If not configured, a default name is automatically generated using the host name of the BASE server.

Other settings

userfiles

The path to the directory where uploaded and generated files should be stored. This is the primary file storage. See the section called “Secondary storage controller” for information about how to configure the secondary storage. Files are not stored in the same directory structure or with the same names as in the BASE file system. The internal structure may contain sub-directories.

permission.timeout

Number of minutes to cache a logged in user's permissions before reloading them. The default value is 10. This setting affect how quickly a changed permission propagate to a logged in user. Permissions are always reloaded when a user logs in.

cache.timeout

Number of minutes to keep user sessions in the internal cache before the user is automatically logged out. The timeout is counted from the last access made from the user.

cache.static.disabled

If the static cache should be enabled or disabled. It is enabled by default. Disabling the static cache may reduce performance in some cases. The static cache is used to cache processed information, for example images, so that the database doesn't have to be queried on every request.

cache.static.max-age

The maximum age in days of files in the static cache. Files that hasn't been accessed (read or written) in the specified amount of time are deleted.

helptext.update

Defines if already existing helptexts in BASE should be overwritten when updating the program, Section 21.1, “Upgrade instructions”

  • true will overwrite existing helptexts.
  • false will leave the existing helptexts in database unchanged and only insert new helptexts.

plugins.autounload

Enable this setting to let BASE detect if a plug-in JAR file is changed and automatically load and use the new code instead of the old code. This setting is useful for plug-in developers since they don't have to restart the web server each time the plug-in is recompiled.

  • true,yes,1 to enable
  • false,no,0 to disable (default if no value is specified)

plugins.dir

The path to the directory where jar-files for external plugins should be located if they should be used with the auto-installer. All new plugins found in this directory, or in any of it's sub-directories, can be selected for installation, see Section 22.1, “Installing plug-ins”. The plugging auto-installer will not be available if this property isn't defined.

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

locale.language, locale.country, locale.variant

Configure the server to a specific locale. The language and country should be valid ISO codes as specified by the java.util.Locale documentation. The variant can be any value that is valid as part of a filename.

[Note] Note

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

This configuration can be used to provide translations to some parts of the web gui. The aim is to externalize all hard-coded gui elements from the code but it's a long way before this is a reality. The default text elements of the gui are shipped within the BASE jar files and doesn't have any locale-specific dependency. This means that unless a more specific translation is provided the default texts are always used as a fallback. Most of the default texts are found in property files in the /net/sf/basedb/clients/web/resources directory inside the BASE2Webclient.jar file. Translations should be located in the same relative path either inside their own JAR file or in the WEB-INF/classes directory. The file names should be extended with the language, country and variant separated with an underscore. For example, files with a swedish translation should be named *_sv.properties, and files with a swedish translation in Finland using the 'foo' variant should be named *_sv_FI_foo.properties.

[Note] Note

Note that it is valid to have empty values for language and/or country and still specify a variant. Underscores are NOT collapsed. For example, in a swedish translation using the 'foo' variant the files should be named *_sv__foo.properties.

[Important] Important

All files should be saved in UTF-8 format.

SSL section

This section is for global configuration of SSL (HTTPS) connection settings. Note that users can re-configure SSL connections per-file basis by setting up File-server items, so there is usually no need to change anything in this section. If the majority of users on the BASE server is using a particular https file server for external files it may make sense to register the certificates globally.

When a https connection is made the server must present a valid certificate or the client (BASE) will refuse to connect to it. Typically, all certificates that have been signed by a recognised Certification Authority are considered valid. The major reason for configuring this section is to provide support for servers that use a self-signed certificate. Server-side certificate are stored in a trust-store. A default trust-store is shipped with the Java runtime installation and is found in <java-home>/jre/lib/security/cacerts. This file contains the certificates of all recognised certification authorities.

A https server may also require that the client has a valid certificate in order to accept connections from it. Typically, the owner of the server issues a certificate that the client must install in order to access the server. This type of certificate is stored in a key-store. By default, no key-store is setup.

If all you need is to support servers with self-signed certificates we recommend that those certificates are imported to the above mentioned file. No configuration changes are needed. If a key-store is needed, you must also configure the trust-store. Read the Java Secure Socket Extension Reference Guide for more information about Java security and SSL. Java ships with a certificate management tool that can be used to manage certificate files and a lot of other things. The keytool - Key and Certificate Management Tool document contains more information about this tool.

If you want to setup your own test environment with a https server that only accepts clients with a trusted certificate you can find some information about this on our wiki: http://base.thep.lu.se/wiki/HttpsFiles

ssl.context.protocol

The SSL protocol to use. The default value is TLS.

ssl.context.provider

A security provider implementation. If not specified a suitable default is selected.

ssl.keystore.file

The full path to a key-store file. If not specified no key-store is used.

ssl.keystore.password

The password for unlocking the keys in the key-store. All keys must use the same password.

ssl.keystore.type

The file type of the key-store file. The default value is 'JKS'.

ssl.keystore.provider

The name of a provider implementation to use for reading the key-store file. If not specified a suitable default is used.

ssl.keystore.algorithm

The algorithm used in the key-store file. The default value is 'SunX509'.

ssl.truststore.file

The full path to a trust-store certificate file. If not specified the default depends on the key-store setting. If no key-store is configured, the default trust-store is used. If a key-store has been configured no trust-store is used.

ssl.truststore.password

The password for unlocking the certificates in the trust-store. All certificates must use the same password.

ssl.truststore.type

The file type of the trust-store file. The default value is 'JKS'.

ssl.truststore.provider

The name of a provider implementation to use for reading the trust-store file. If not specified a suitable default is used.

ssl.truststore.algorithm

The algorithm used in the trust-store file. The default value is 'PKIX'.