---
last_review: "2025-01-01"
last_reviewer: "-"
documented_code: [ ]
---

```{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.
:::
% TODO: Issue: https://gitlab.indiscale.com/caosdb/src/linkahead-docs/-/issues/89

## 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](https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/server.conf).

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](/explanation/general/permissions.md) which are automatically set, based on user
roles. See the [default file](https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/global_entity_permissions.xml).

`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](/reference/server/api/org/caosdb/server/accessControl/UserSource.rst)
and its implementing classes. The provided
[template file](https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/usersources.ini.template)
also has some information. The general concept about authentication realms is described in
[UserSources](/reference/server/api/org/caosdb/server/accessControl/UserSources.rst).

`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](https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/authtoken.example.yaml).

`cache.ccf`

: Configuration for the Java Caching System (JCS) which can be used by the server. More
  documentation is [upstream](http://commons.apache.org/proper/commons-jcs/getting_started/intro.html)
  and inside [the file](https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/cache.ccf).

`log4j2-default.properties`, `log4j2-debug.properties`

: Configuration for logging, following the standard described by the [log4j library](https://logging.apache.org/log4j/2.x/).
  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](/reference/pylib/api/linkahead.common.administration.rst)
module.