Univention Corporate Server 5.0 Architecture

Download PDF

Univention Configuration Registry (UCR)

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.

../_images/UCR-consumers.svg

Fig. 5.1 Consumers of UCR#

5.1.1. UCR architecture#

Fig. 5.2 shows the architecture overview of UCR.

../_images/UCR-architecture.svg

Fig. 5.2 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.

See also

Administrators, refer to Univention Corporate Server - Manual for users and administrators [1]:

See also

Software developers and system engineers, refer to Univention Developer Reference [3]:

From Univention Corporate Server Python API 5.0 documentation [4]:

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.

../_images/UCR-architecture-persistence-layer.svg

Fig. 5.3 Architecture of Univention configuration registry persistence layer#

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 /etc/univention/templates/files/.

The mapping between which UCR template uses which UCR variables locates at /etc/univention/templates/info/.

System configuration files

When UCR variables change or administrators run the UCR commit command, 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 interfaces/restart/auto to no. Also, the Docker service restarts when UCR variables starting with proxy/* change.

Caution

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.

../_images/UCR-set-variable.svg

Fig. 5.4 Workflow after setting a UCR variable#

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.

See also

Administration of local system configuration with Univention Configuration Registry

for more information about using UCR in Univention Corporate Server - Manual for users and administrators [1].

See also

Software developers and system engineers, refer to Univention Developer Reference [3]:

For more information about how to run code or programs when specific UCR variables change, refer to the following documentation:

  • Script for more information about how to call external programs

  • Module for more information about how to run Python modules

  • File, refer to Preinst, Postinst, and /etc/univention/templates/scripts/.

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:

Default

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.

The package’s postinst may 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.

Normal

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 --force, --schedule, or --ldap-policy to explicitly use another layer.

LDAP

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 ldap/policy/cron.

Scheduled

The priority layer scheduled is specific to UCS@school. It temporarily overwrites UCR variables.

Forced

The priority layer forced has the highest priority for a regular UCS system by default. It applies to UCR variables set with the option --force.

Custom

The priority layer custom is an internal detail and not used by default. This layer applies only when the environment variable UNIVENTION_BASECONF has a value and points to a file. Then the custom layer has the highest priority for those processes only.

See also

System administrators refer to Univention Corporate Server - Manual for users and administrators [1]:

See also

Software developers and system engineers, refer to Univention Developer Reference [3]:

5.1.4. UCR limitations#

UCR has the following limitations:

  1. UCR variables store and return string values.

  2. Values must not contain newlines (\n, \r) or zero bytes (\0).

  3. 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.

  4. It’s recommended, that UCR variables shouldn’t exceed the length of 1024 characters 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.

  5. Access management:

    Write

    On the command line, only the user root can 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.

    See also

    See also the note about the path and access rights in Using UCR from shell in Univention Developer Reference [3].

    Read

    Any user or process on a UCS system can read UCR variables, because /etc/univention/base*.conf are world-readable.

    Warning

    Don’t access UCR variables directly from the files. Always use the interfaces such as:

On this page