Tags: explanation

Server Configuration#

Note

This page has been migrated from the old documentation, and has not yet been fully revised. There might be inconsistencies or errors when using with current LinkAhead versions.

Main Configuration File#

The server is configured through configuration files. The main file is the server.conf.

The server.conf is a list of key-value pairs. A configuration file may contain empty lines, comment lines, and key-value lines. Comment lines begin with a hash (#). Key-value lines must have the format KEY_NAME=VALUE or KEY_NAME = VALUE.

The server default configuration is located at ./conf/core/server.conf. Upstream defaults are stored here. The possible configuration options are documented inside the default file.

User specific configuration should be in ./conf/ext/ and override settings in ./conf/core/.

The default configuration can be overridden by

  1. the file ./conf/ext/server.conf

  2. any file in ./conf/ext/server.conf.d/ in (approximately?) alphabetical order

  3. environment variables with the prefix CAOSDB_CONFIG_

in this order.

Further Configuration Files#

There are additional configuration files. Their default version is stored in ./conf/core/. Place a file with the same name in conf/ext/ and adjust the path to point to the new location in the server.conf file to override those defaults. These files are:

global_entity_permissions.xml

Permissions which are automatically set, based on user roles. See the default file.

usersources.ini

This file defines possible sources which are checked when a user tries to authenticate. Each defined source has a special section, the possible options are defined separately for each user source. At the moment the best place to look for this specific documentation is at the API documentation of UserSource and its implementing classes. The provided template file also has some information. The general concept about authentication realms is described in UserSources.

authtoken.yaml

Configuration for dispensed authentication tokens, which can be used to authenticate to CaosDB without the need of a user/password combination. One-time Authentication Tokens can be configured to be issued for special purposes (e.g. a call of a server-side script or initial setup after the server start) or to be written to a file on a regular basis. An example of a configuration is located at ./conf/core/authtoken.example.yaml. There is more documentation inside the template file.

cache.ccf

Configuration for the Java Caching System (JCS) which can be used by the server. More documentation is upstream and inside the file.

log4j2-default.properties, log4j2-debug.properties

Configuration for logging, following the standard described by the log4j library. The default file is always loaded, in debug mode the debug file iss added as well.

Changing the configuration at runtime#

Remark:

Only when the server is in debug mode, the general configuration can be changed at runtime.

In the debug case, the server provides the _server_properties resource which allows the GET and POST methods to access the server’s properties. The Python client library conveniently wraps this in the linkahead.common.administration module.