1.21. The LinOTP configuration

LinOTP can be configured via parameters specified in configuration files, or also via the process environment for increased convenience in container-based setups (e.g., Docker). The configuration files and environment variables can only be changed at the OS level by a user with appropriate access and not by a LinOTP token administrator.

1.21.1. Configuration parameters

To see the current configuration of your LinOTP instance, run:

linotp config show

This will show you all configuration parameters supported by LinOTP. Parameters that do not occur explicitly in the current configuration are listed with their hard-coded default values.

For more details on any configuration entry, say, ACTIVE_SECURITY_MODULE, do:

linotp config explain ACTIVE_SECURITY_MODULE

A detailed explanation of the linotp config commands can be found in the linotp-config(1) man page.

Warning

You need to restart LinOTP every time you make changes to the configuration, as the configuration settings are read only once, on startup.

1.21.2. Setting the configuration parameters in a configuration file

Configuration settings can be loaded from multiple locations. These locations are determined by the value of the LINOTP_CFG environment variable, which may contain a colon-separated list of directory names and file glob expressions. LinOTP checks these names and file glob expressions in the order they occur in LINOTP_CFG, and reads any matching files. File names resulting from the expansion of a glob expression are processed in lexicographic order. Directory names have *.cfg appended to them implicitly. Relative directory names and file glob expressions are taken relative to the application root directory (where the app.py file is found).

If LINOTP_CFG is not set and a file called linotp-cfg-default exists in the application root directory, the content of that file is used as the default value for LINOTP_CFG (this feature is generally used to establish a distribution-specific search order for configuration files). If the file does not exist, linotp.cfg is assumed as the default value.

The following table lists configuration file locations for Debian packages (as per linotp-cfg-default):

File path	Description
/usr/share/linotp/linotp.cfg	Distribution defaults - these settings are supplied by the packaging and represent settings that are appropriate for the distribution and packaging format used.
/etc/linotp/linotp.cfg	Central configuration settings.
/etc/linotp/conf.d/*	Configuration snippets can be placed in this directory. The Debian packaging places the database configuration in 01-debian-database.cfg

The order of the locations in the above table matters. Settings in later files in the search order will override settings previously found. For example, if LOGFILE_DIR is defined in the following places:

LOGFILE_DIR=/srv/linotp-logs in the file /etc/linotp/linotp.cfg and

LOGFILE_DIR=/var/log/linotp in the file /usr/share/linotp/linotp.cfg,

then the value that is used is /srv/linotp-logs, because that was the last one encountered.

Note

Configuration settings whose names end in _FILE or _DIR contain file or directory names, respectively. These names can be either absolute (starting with a slash) or relative, in which case they are evaluated starting from the directory named by the ROOT_DIR configuration setting. This setting must contain an absolute directory name.

To ensure that relative paths are correctly resolved, the respective settings are only evaluated after the entire configuration has been read and the definitive value for ROOT_DIR has been determined.

This means that if the /usr/share/linotp/linotp.cfg file contains a setting like DATA_DIR = "data" and the very last line of /etc/linotp/linotp.cfg, which is read after /usr/share/linotp/linotp.cfg, says ROOT_DIR = /var/lib/my-special-linotp, then the effective value of DATA_DIR will be /var/lib/my-special-linotp/data, even though the ROOT_DIR setting was seen after the DATA_DIR setting.

1.21.3. Setting the configuration parameters via environment variables

For the benefit of people who run LinOTP in container-based environments such as Docker, all of the LinOTP parameters can also be defined in environment variables. However, the parameter names must be prefixed with LINOTP_. For example, to set the value for ACTIVE_SECURITY_MODULE, you must assign it to an environment variable called LINOTP_ACTIVE_SECURITY_MODULE.

Note

Parameters defined in environment variables override the respective parameter value assigned in configuration files.