3.9. Provisioning Service

The Provisioning Service is an event and messaging service that can notify interested services about events in the LDAP directory service. When data changes in the LDAP directory on the Primary Directory Node, the Provisioning Service receives a notification and notifies subscribed services. In contrast to the Univention Directory Listener, it provides the Univention Directory Manager (UDM) representation of the change objects instead of the LDAP representation.

This page describes the installation and configuration of the Provisioning Service in Nubus for UCS. For more information about the inner workings of the Provisioning Service, see Provisioning Service in Nubus for Kubernetes - Architecture Manual 1.x [7].

Note

Optional Nubus components use the Provisioning Service in Nubus for UCS.

For information about how to use the Provisioning Service in your services and subscribe to the events, see Provisioning API in Nubus Customization and Modification Manual 1.x [8].

3.9.1. Installation

The Univention App Center provides the Provisioning Service as an application. Nubus for UCS doesn’t install it by default. You can install it on the Primary Directory Node and on every Backup Directory Node. It isn’t possible to install the Provisioning Service on other server system roles. The Provisioning Service consists of the following apps:

Provisioning Service

The Provisioning Service app is a container app that provides the main features of the Provisioning Service.

Provisioning Service Backend

The Provisioning Service Backend package-based app installs integration packages in Nubus for UCS. The App Center automatically installs it as a dependency of Provisioning Service. The packages include a listener module and host configuration for TLS encryption between multiple installations.

To install the Provisioning Service, choose one of the following installation methods. The App Center applies multiple settings to the Provisioning Service. For a reference, see Provisioning Service settings.

App Center

You can install the Provisioning Service app through the Univention App Center as you would any other app. For general information about the Univention App Center and how to use it for software installation, see Univention App Center.

Command line

To install the app through the command line, use the command in Listing 3.16 with root privileges.

Listing 3.16 Install the Provisioning Service through the command line

$ univention-app install provisioning-service

3.9.2. Provisioning workflow

The Provisioning Service delivers a stream of events about data changes in the LDAP directory service. It uses the following components:

Provisioning Listener

The Univention Directory Listener module nubus-provisioning.py reacts to all LDAP operations and pushes these changes to the Provisioning Service. It runs only on the Primary Directory Node.

Provisioning UDM Transformer

The Provisioning UDM Transformer transforms incoming LDAP-level change events into UDM-level provisioning events by calling the UDM HTTP REST API. It runs only on the Primary Directory Node.

Provisioning Prefill Service

The Provisioning Prefill Service streams all UDM objects of the subscribed type to the subscribed consumer app. It runs on the Primary Directory Node only.

Provisioning Dispatcher

The Provisioning Dispatcher routes events about all UDM objects to the provisioning queues of subscribed apps. It runs on the Primary Directory Node and Backup Directory Nodes.

Provisioning APIs

The Provisioning APIs runs on the Primary Directory Node and the Backup Directory Node. They’re a collection of various APIs for service registration to subscribe to events and messaging.

Event streaming service

NATS handles the actual event streaming service.

The Provisioning Dispatcher on the Backup Directory Node connects to the event streaming service on the Primary Directory Node. It streams data through a TLS-encrypted connection.

See also

Provisioning Service

in Nubus for Kubernetes - Architecture Manual 1.x [7] for information about the architecture of the Provisioning Service

Provisioning API

in Nubus Customization and Modification Manual 1.x [8] for information about how to use the Provisioning Service and create a subscription for a Provisioning Consumer.

3.9.3. Endpoints and ports

For Provisioning Service endpoints and ports, see Table 3.1.

You can access the Provisioning API locally through http://localhost:7777. For remote access, use https://<Primary FQDN>/univention/provisioning/. Replace <Primary FQDN> with the fully qualified domain name of the Primary Directory Node.

The Provisioning Service uses stunnel to ensure TLS encryption between Primary Directory Node and Backup Directory Node.

Table 3.1 Endpoints and ports

Port	Purpose
4230	The stunnel port. You can adjust it through the nats/stunnel/accept/port UCR variable.
4222	NATS client connections.
7777	Provisioning APIs.
8222	NATS monitoring endpoint.

Important

The Provisioning Dispatcher needs access to the UDM HTTP REST API on port 443 on the Primary Directory Node and the Backup Directory Node.

3.9.4. Provisioning Service log files

If you encounter problems with the Provisioning Service, you can consult the following log files:

• The Provisioning Service containers write their logs to /var/log/syslog.

• The nubus-provisioning.py listener module that provides the Provisioning Service with information writes logs to /var/log/univention/listener_modules/nubus-provisioning.log.

• The stunnel service writes logs to /var/log/stunnel4/stunnel.log.

3.9.5. Provisioning Service settings

The following sections list the settings for the Provisioning Service app. Univention recommends keeping the default values.

To change settings after the app installation, use these steps:

1. Sign in to the Management UI with a user account in the Domain Admins group and go to App Center ‣ Provisioning Service ‣ Manage Installations.

2. Select the checkbox for the instance and go to ⋯ More ‣ App Settings.

3. On the Configure Provisioning Service page, change the settings.

4. To apply the settings, click Apply Changes.

The App Center then reinitializes the containers for the Provisioning Service app. Reinitialize means that the App Center replaces the running containers with new containers that use the updated settings.

For some setting changes, you need to restart the univention-directory-listener. Run the command in Listing 3.17.

Listing 3.17 Restart the Directory Listener

$ systemctl restart univention-directory-listener

3.9.5.1. App settings

The Provisioning Service app has the following app settings.

provisioning-service/udm-rest-api-host

Fully qualified domain name (FQDN) of the UDM HTTP REST API host.

Required	Default value	Applied during
Yes	Value from ldap/master	Installation and app configuration

provisioning-service/primary

FQDN of the Primary Directory Node.

Required	Default value	Applied during
Yes	Value from ldap/master	Installation and app configuration

nats/max_retry_count

Number of times the Provisioning Listener retries to synchronize each transaction to the Event streaming service. After you change this setting, you need to restart the univention-directory-listener. See Listing 3.17.

Required	Default value	Applied during
Yes	3	Installation and app configuration

nats/retry_delay

The number of seconds to wait between each attempt to synchronize a transaction to the Event streaming service. After you change this setting, you need to restart the univention-directory-listener. See Listing 3.17.

Required	Default value	Applied during
Yes	1	Installation and app configuration

nats/max_reconnect_attempts

The maximum number of times to attempt to reconnect to the Event streaming service. After you change this setting, you need to restart the univention-directory-listener. See Listing 3.17.

Required	Default value	Applied during
Yes	3	Installation and app configuration

3.9.5.2. UCR variables

The Provisioning Service also uses the following UCR variables, which don’t appear in the app settings. Univention recommends keeping the default values. For information about configuring UCR variables, see Configure the local system with Univention Configuration Registry.

nats/stunnel/accept/port

Listening port number of the stunnel securing the NATS connection between the Primary Directory Node and the Backup Directory Node.

Required	Default value	Applied during
Yes	4230	Installation and app configuration.

nats/stunnel/connect/port

Connection port of the stunnel securing the connection between Provisioning Dispatcher on the Backup Directory Node and NATS on the Primary Directory Node. Must match the nats/stunnel/accept/port of the Primary Directory Node.

Required	Default value	Applied during
Yes	4230	Installation and app configuration.

nats/stunnel/cert

Certificate for the stunnel NATS connection between Provisioning Dispatcher on a Backup Directory Node and NATS on the Primary Directory Node.

Required	Default value	Applied during
Yes	/etc/univention/ssl/@%@ldap/master@%@/cert.pem	Installation and app configuration.

nats/stunnel/key

Certificate key used for the stunnel NATS connection between Provisioning Dispatcher on a Backup Directory Node and NATS on the Primary Directory Node.

Required	Default value	Applied during
Yes	/etc/univention/ssl/@%@ldap/master@%@/private.key	Installation and app configuration.

nats/stunnel/cacert

The CA certificate used for the stunnel NATS connection between Provisioning Dispatcher on a Backup Directory Node and NATS on the Primary Directory Node.

Required	Default value	Applied during
Yes	/etc/univention/ssl/ucsCA/CAcert.pem	Installation and app configuration.