5.1. Univention Configuration Registry (UCR)#
This section describes the architecture of UCR. For a general overview about system management and the role of UCR, refer to System management.
You find the source code for UCR at UCS source: base/univention-config-registry/.
Every UCS system installs UCR per default, regardless of the system role. UCR stores all configuration settings of a UCS system, and also some other information for quick lookup, for example the validity of certificates. Administrators set values for configuration settings. Also, packages set configuration values with default values during their installation. As shown in Fig. 5.1 UCR is an important component used everywhere, for example by UCS Packages, Services, Scripts and also Apps.
5.1.1. UCR architecture#
Fig. 5.2 shows the architecture overview of UCR.
UCR provides configuration values to Scripts, Apps, UCS Packages and Services with its various configuration values from the UCR variables. Users such as administrators use UCR through the web interface of UMC - Univention Management Console with HTTP/HTTPS and through the command line with Terminal / SSH. And UCR Python API offers a programming interface for UCS components and other Python programs. UCR C API is a small API in C for only getting and setting UCR variables.
Administrators, refer to Univention Corporate Server - Manual for users and administrators :
5.1.2. UCR persistence layer#
Fig. 5.3 shows the relation between the active Univention Configuration Registry (UCR) [application component] and the passive UCR variables, UCR templates and System configuration files.
- UCR variables
UCR is independent from any LDAP directory service. Instead, UCR uses plain text files as its storage backend for UCR variables and saves them in
/etc/univention/base*.conf. Most UCR commands read UCR variables. The UCR set / unset command changes UCR variables.
The variables don’t follow a hierarchy. The slash (
/) separator exists for readability.
- UCR templates
UCR templates are text file templates for configuration files of various services in UCS. They include placeholders for the UCR variables. Additionally, they can include Python code for algorithms and more complex use cases.
The template files locate at
The mapping between which UCR template uses which UCR variables locates at
- System configuration files
When UCR variables change or administrators run the
UCR commitcommand, the UCR configuration manager determines the affected system configuration files. The manager reads the respective UCR templates, parses them, replaces the variable placeholders with the values from the UCR variables, and writes System configuration files. UCR commands like ucr set and ucr unset automatically trigger UCR commit on all affected System configuration files referencing the changed UCR variables.
UCR usually doesn’t reload services affected by configuration file changes, because only the administrator knows when configuration tasks are complete and safe for restart.
Exceptions to this behavior exist. For example, changes to UCR variables starting with
interfaces/trigger a restart of the networking service, unless you set UCR variable
no. Also, the Docker service restarts when UCR variables starting with
Beware that UCR overwrites any manual changes to configuration files that are under control of UCR. Such configuration files include a header with a warning. Overwriting can happen during system updates or other events that trigger a rewriting of configuration files.
Fig. 5.4 shows this general workflow after an administrator sets a UCR variable. Other actors can be UCS Packages, Scripts, or Services.
The Administrator triggers the event UCR set variable by using the UCR command. UCR set / unset writes one of the UCR variables and triggers a UCR commit. The UCR commit uses the UCR variable priority, the UCR variables, and the UCR templates to write and update the System configuration. After UCR commit finished, it triggers the Configuration written event.
- Administration of local system configuration with Univention Configuration Registry
for more information about using UCR in Univention Corporate Server - Manual for users and administrators .
Software developers and system engineers, refer to Univention Developer Reference :
Using UCR for more information about how to extend or develop with UCR
UCR Template files conffiles/path/to/file for more information about writing UCR template files
For more information about how to run code or programs when specific UCR variables change, refer to the following documentation:
5.1.3. UCR variable priorities#
UCR uses priority layers to determine what value actually becomes effective. The following layers from low priority to high priority exist:
The lowest priority represents the default value for UCR variables. The package that introduces the UCR variable sets the default value. This priority layer avoids default values scattered across the program code in UCS.
New in version 5.0: Default layer added to UCR
Packages must explicitly register a default value in its UCR info file, so that the UCR variables uses the Default layer.
postinstmay still set the default value of UCR variables using ucr set name?value. This command stores the UCR variable in the Normal layer.
Changing a UCR variable default value the “old way” without the Default layer requires updates in multiple code locations resulting in a major drawback with increased effort.
The priority layer normal becomes effective after an administrator, a package installation or something else explicitly sets a value for a UCR variable. UCR uses this layer by default, when a role like administrator or script uses none of the options
--ldap-policyto explicitly use another layer.
By default each UCS system has its own independent UCR. For managing multiple UCS systems, administrators can define the same UCR policies in LDAP and apply them to several UCS systems consistently. UCS stores the values of these settings in the priority layer LDAP, which takes precedence over both previous layers.
By default, UCS systems apply UCR policies once per hour, but not at a fixed minute to avoid load peaks on the LDAP server. You can change the default value of once per hour with the UCR variable
The priority layer scheduled is specific to UCS@school. It temporarily overwrites UCR variables.
The priority layer forced has the highest priority for a regular UCS system by default. It applies to UCR variables set with the option
The priority layer custom is an internal detail and not used by default. This layer applies only when the environment variable
UNIVENTION_BASECONFhas a value and points to a file. Then the custom layer has the highest priority for those processes only.
System administrators refer to Univention Corporate Server - Manual for users and administrators :
5.1.4. UCR limitations#
UCR has the following limitations:
UCR variables store and return string values.
Values must not contain newlines (
\r) or zero bytes (
UCR variable names should be restricted to alpha-numeric characters from the ASCII alphabet.
UCR commands validate the variable name using the function
validate_key(), that prohibits using many shell control characters. For more information, refer to UCS source: base/univention-config-registry/python/univention/config_registry/misc.py#L131.
It’s recommended, that UCR variables shouldn’t exceed the length of
1024characters counting the length of the key and the length of the value plus 3: \(key.length + value.length + 3 <= 1024\)
The underlying C implementation of UCR is the reason for the limitation. The limit isn’t enforced in the implementation.
On the command line, only the user
rootcan change UCR variables. UMC policies can grant proper rights to users, so that a normal user can also set UCR variables through UMC - Univention Management Console.
Any user or process on a UCS system can read UCR variables, because
Don’t access UCR variables directly from the files. Always use the interfaces such as: