diff --git a/README_SETUP.md b/README_SETUP.md
index 3cde99c9fc82a57524fc6e7d31d88353deeec221..afc63592e7797adafa8cd58df37d0aff0a8d5b15 100644
--- a/README_SETUP.md
+++ b/README_SETUP.md
@@ -118,7 +118,7 @@ server:
- `INSERT_FILES_IN_DIR_ALLOWED_DIRS`: add mounted filesystems here that
shall be accessible by CaosDB
* Maybe set another `SESSION_TIMEOUT_MS`.
- * See also [CONFIGURATION.rst](https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/src/doc/administration/configuration.rst)
+ * See also [CONFIGURATION.rst](src/doc/administration/configuration.rst)
6. Copy `conf/core/usersources.ini.template` to `conf/ext/usersources.ini`.
* You can skip this if you do not want to use an external authentication.
Local users (CaosDB realm) are always available.
diff --git a/src/doc/administration/configuration.rst b/src/doc/administration/configuration.rst
index 196acb34ee9afbe6b35d530b058fac6c275299aa..c91ac16b1068b9261638aa697f3d11fd42a0d5cc 100644
--- a/src/doc/administration/configuration.rst
+++ b/src/doc/administration/configuration.rst
@@ -1,29 +1,43 @@
-Configuration
-=============
+Server Configuration
+====================
-The server is configured through configuration files. There are two directories with config files:
+Main Configuration File
+-----------------------
-``conf/core``
- Upstream defaults are stored here.
-``conf/ext``
- User specific configuration should be stored here, settings in ``ext`` override settings in
- ``core``. Additionally, configuration files may be stored in ``*.d`` directories here, named
- after the original config file name. For example, the general server configuration will be
- assembled from ``conf/core/server.conf``, ``conf/ext/server.conf`` and any ``*.conf`` files found
- in ``conf/ext/server.conf.d``.
+The server is configured through configuration files. The main file is the
+`server.conf`.
-Configuration files
--------------------
+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`.
-In each of these directories, the server looks for the following files:
-``server.conf``
- General server configuration options. The possible configuration options are documented inside
- the `default file
- <https://gitlab.indiscale.com/caosdb/src/caosdb-server/-/blob/dev/conf/core/server.conf>`__.
+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 overriden 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
+---------------------------
+
+Further settings are to be set in files which are by default stored in `./conf/core/`:
``global_entity_permissions.xml``
- :doc:`Permissions<../Permissions>` which are automatically set, based on user roles. See the
+ :doc:`Permissions<../permissions>` 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>`__.
@@ -39,8 +53,10 @@ In each of these directories, the server looks for the following files:
``authtoken.yaml``
Configuration for dispensed authentication tokens, which can be used to authenticate to CaosDB
- without the need of a user/password combination. Possible use cases are server-side scripts or
- initial setup after the server start. There is more documentation inside the `template file
+ without the need of a user/password combination. One-time Authentication Tokens can be configure
+ 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``
@@ -54,6 +70,9 @@ In each of these directories, the server looks for the following files:
<https://logging.apache.org/log4j/2.x/>`_. The ``default`` file is always loaded, in debug mode
the ``debug`` file iss added as well.
+The administrator may set the corresponding options in the main configuration
+file (`./conf/core/server.conf` and it's friends) to replace these special
+files with custom configuration.
Changing the configuration at runtime
-------------------------------------
diff --git a/src/doc/roles.md b/src/doc/roles.md
index 5f4641b7a6f6fcb1b63cdd26edb706af117ee7d6..2d1d36c47c34658a306384e39033f7ea4e5eb040 100644
--- a/src/doc/roles.md
+++ b/src/doc/roles.md
@@ -10,7 +10,7 @@ users may have the same role, and there may be roles without any users.
The user and their roles are always returned by the server in answers to requests
and can thus be interpreted and used by clients. The most important use though
-is [permission](Permissions) checking in the server: Access and
+is [permission](doc:`permissions`) checking in the server: Access and
modification of
entities can be controlled via roles, so that users of a given role are allowed
or denied certain actions. Incidentally, the permission to edit the permissions
@@ -32,4 +32,4 @@ There are some special roles, which are automatically assigned to users:
Except for the `anonymous` role, these special roles are not returned by the
server, but can nevertheless be used to define
-[permissions](Permissions).
+[permissions](doc:`permissions`).