3.5. 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 about the change and notifies any subscribed services about the change. In contrast to the Univention Directory Listener, it provides the UDM representation of the change objects instead of the LDAP representation.

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

Note

There are no services integrated into UCS that make use of the Provisioning Service. You can create services that use the Provisioning Service according to Provisioning API in Nubus for Kubernetes - Customization and Modification Manual 1.x [5].

Note

The Provisioning Service is part of Univention Nubus in the Identity Store and Directory Service component. For more information about Nubus, refer to What is Univention Nubus?

3.5.1. Installation

Univention App Center provides the Provisioning Service as an application. 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 app is a package based app that installs integration packages in 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 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 like any other app through Univention App Center. For general information about 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.1.

Listing 3.1 Install Provisioning Service through command line

$ univention-app install provisioning-service

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

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

Provisioning UDM Transformer

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

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 Primary Directory Node and Backup Directory Node.

Provisioning API

The Provisioning API runs on the Primary Directory Node and the Backup Directory Node and is the API that applications use to subscribe to events.

NATS

NATS handles the actual event streaming service.

On the Backup Directory Node the Provisioning Dispatcher connects to the NATS Service running 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 [4] for information about the architecture of the Provisioning Service

Provisioning API

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

3.5.3. Endpoints and ports

The Provisioning Service provides endpoints and ports as outlined in Table 3.1.

You can access the Provisioning API locally through http://localhost:7777, or remotely through https://<Primary FQDN>/univention/provisioning/.

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 API.
8222	NATS Monitoring endpoint.

Important

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

3.5.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 that ensures TLS encryption between Primary Directory Node and Backup Directory Node, writes logs to /var/log/stunnel4/stunnel.log.

3.5.5. Provisioning Service settings

The following references show the available settings within the Provisioning Service app. Univention recommends keeping the default values.

To change settings after the app installation, sign in to the UCS management system with a user account in the Domain Admins group and go to App Center ‣ Provisioning Service ‣ Manage Installations ‣ Select instance via checkbox ‣ ⋯ More ‣ App Settings. On the Configure Provisioning Service page, you can change the settings and apply them to the app by clicking Apply Changes.

The App Center then reinitializes the Docker containers for the Provisioning Service app. Reinitialize means that the App Center throws away the running containers comprising the app and creates a fresh set of containers with the just changed settings.

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

Listing 3.2 Restart the Directory Listener

$ systemctl restart univention-directory-listener

3.5.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 REST API host.

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

provisioning-service/primary

Fully qualified domain name (FQDN) of the Primary Directory Node.

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

nats/max_retry_count

Number of times the Provisioning Listener re-tries to synchronize each transaction to the provisioning NATS service. After you change this setting you need to restart the univention-directory-listener, see Listing 3.2.

Required	Default value	Set
Yes	3	Installation and app configuration

nats/retry_delay

The number of seconds to wait between each attempt to synchronize a transaction to the provisioning NATS service. After you change this setting you need to restart the univention-directory-listener, see Listing 3.2.

Required	Default value	Set
Yes	1	Installation and app configuration

nats/max_reconnect_attempts

The maximum number of times to attempt to reconnect to the NATS service. After you change this setting you need to restart the univention-directory-listener, see Listing 3.2.

Required	Default value	Set
Yes	3	Installation and app configuration

3.5.5.2. UCR Variables

Additionally, the Provisioning Service considers the following UCR variables that don’t appear in the app settings. Univention recommends keeping the default values.

nats/stunnel/accept/port

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

Required	Default value	Set
Yes	4230	Installation and app configuration.

nats/stunnel/connect/port

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

Required	Default value	Set
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 Primary Directory Node.

Required	Default value	Set
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 Primary Directory Node.

Required	Default value	Set
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 Primary Directory Node.

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