Manage provisioning tasks

8.1. Manage provisioning tasks#

Use the OX Connector command-line interface to query and manage its database. The database tracks current tasks, objects that the OX Connector has synchronized, and errors.

Nubus for UCS

On Nubus for UCS with the OX Connector app installed, you find the command-line interface at the location shown in Listing 8.1.

Listing 8.1 List all commands of the CLI#

$ /usr/sbin/univention-ox-connector-task-management --help

The tool operates on the SQLite database /var/lib/univention-appcenter/apps/ox-connector/data/ox-connector.db. The terminology of the tool is as follows:

Nubus for Kubernetes

To run the univention-ox-connector-task-management command, you need to use kubectl with the execute action on the OX Connector pod.

Replace the placeholder <NAMESPACE> with the Kubernetes namespace for the OX Consumer.

Use the commands in Listing 8.2. The example has the pod name ox-connector-0.

Listing 8.2 Open a shell to the OX Connector#

$ export NAMESPACE_FOR_CONSUMER="<NAMESPACE>"
$ kubectl \
   --namespace "$NAMESPACE_FOR_CONSUMER" \
   get pods | grep "ox-connector"
ox-connector-0    1/1   Running   0  19h

$ export POD_NAME_FOR_OX_CONNECTOR="ox-connector-0"
$ kubectl \
   --namespace "$NAMESPACE_FOR_CONSUMER" \
   execute \
   --stdin \
   --tty \
   "$POD_NAME_FOR_OX_CONNECTOR" \
   -- \
   univention-ox-connector-task-management --help

Tasks#: A database table managed by the OX Connector. A row represents an active task. The OX Connector iterates over all tasks and synchronizes them to the OX App Suite.
Old#: A database table managed by the OX Connector. A row represents the state of an item when the OX Connector successfully synchronized it. The row is a copy of a previous task. The OX Connector needs it when synchronizing items that reference other items, for example, groups that contain users. The OX Connector also stores the database ID assigned by OX so that it can look up objects faster.
Morgue#: A database table managed by the OX Connector. A row represents a failed task. The OX Connector or an administrator moved the task to this table, so the OX Connector doesn’t process it actively. Administrators can examine items in the morgue and decide how to proceed.

8.1.1. Check provisioning health#

To check the provisioning health, use the following steps:

Inspect the log output of the OX Connector Provisioning Consumer.

Nubus for UCS

To check the provisioning health, first inspect the log output of the OX Connector Provisioning Consumer for warnings and errors. For more information, see Log files.

Nubus for Kubernetes

To check the provisioning health, first inspect the log output of the OX Connector Provisioning Consumer for warnings and errors. For more information, see Log files.

Inspect the provisioning queue. The following listings show the commands. If the number of pending tasks keeps growing after a change in the LDAP directory, the OX Connector Provisioning Consumer or the Provisioning Service can’t process tasks.

Nubus for UCS

Listing 8.3 Show pending tasks#

$ /usr/sbin/univention-ox-connector-task-management summarize-tasks
$ /usr/sbin/univention-ox-connector-task-management search-tasks

Nubus for Kubernetes

To set the proper environment variables in the following listing, use the commands in Listing 8.2.

Listing 8.4 Show pending tasks#

$ kubectl \
   --namespace "$NAMESPACE_FOR_CONSUMER" \
   execute \
   --stdin \
   --tty \
   "$POD_NAME_FOR_OX_CONNECTOR" \
   -- \
   univention-ox-connector-task-management summarize-tasks

$ kubectl \
   --namespace "$NAMESPACE_FOR_CONSUMER" \
   execute \
   --stdin \
   --tty \
   "$POD_NAME_FOR_OX_CONNECTOR" \
   -- \
   univention-ox-connector-task-management search-tasks

Then inspect failed tasks in the morgue. This is relevant only if you configured the connector to OX Connector continues after faulty items.
Nubus for UCS
Listing 8.5 Show failed tasks in the morgue#
$ /usr/sbin/univention-ox-connector-task-management search-morgue
Nubus for Kubernetes
To set the proper environment variables in the following listing, use the commands in Listing 8.2.
Listing 8.6 Show failed tasks in the morgue#
$ kubectl \ --namespace "$NAMESPACE_FOR_CONSUMER" \ execute \ --stdin \ --tty \ "$POD_NAME_FOR_OX_CONNECTOR" \ -- \ univention-ox-connector-task-management search-morgue

8.1.2. Handle failed tasks#

Decide how to handle failed tasks in the morgue.

Nubus for UCS

Use Listing 8.5 to find the UniventionObjectIdentifier of the affected object. Replace OBJECT_ID in the following commands with this identifier.

Nubus for Kubernetes

Use Listing 8.6 to find the UniventionObjectIdentifier of the affected object. Replace OBJECT_ID in the following commands with this identifier.

Remove the task from the morgue: The OX Connector treats the object as though it had never received the task. If the underlying object changes in the LDAP directory, the OX Connector can synchronize it again and create a new task.
Nubus for UCS
Run the command in Listing 8.7.
Listing 8.7 Remove an item from the morgue#
$ /usr/sbin/univention-ox-connector-task-management \ remove-from-morgue \ --obj-id=OBJECT_ID
Nubus for Kubernetes
Run the command in Listing 8.8. To set the proper environment variables in the following listing, use the commands in Listing 8.2.
Listing 8.8 Remove an item from the morgue#
$ kubectl \ --namespace "$NAMESPACE_FOR_CONSUMER" \ execute \ --stdin \ --tty \ "$POD_NAME_FOR_OX_CONNECTOR" \ -- \ univention-ox-connector-task-management \ remove-from-morgue \ --obj-id=OBJECT_ID
Retry the same task: After you resolve the problem, the OX Connector copies the failed task back to the task list. For example, you might first deactivate a validation rule in OX App Suite.
Nubus for UCS
Run the command in Listing 8.9.
Listing 8.9 Retry an item from the morgue#
$ /usr/sbin/univention-ox-connector-task-management \ retry-from-morgue \ --obj-id=OBJECT_ID
Nubus for Kubernetes
Run the command in Listing 8.10. To set the proper environment variables in the following listing, use the commands in Listing 8.2.
Listing 8.10 Retry an item from the morgue#
$ kubectl \ --namespace "$NAMESPACE_FOR_CONSUMER" \ execute \ --stdin \ --tty \ "$POD_NAME_FOR_OX_CONNECTOR" \ -- \ univention-ox-connector-task-management \ retry-from-morgue \ --obj-id=OBJECT_ID
Resynchronize the object: The OX Connector adds the object to the task list with its current attributes instead of the attributes from the failed synchronization. It fetches the object again from the LDAP directory. This works only for the first matching object, so asterisks might not produce the expected result.
Nubus for UCS
Run the command in Listing 8.11.
Listing 8.11 Re-sync an existing item through UDM#
$ /usr/sbin/univention-ox-connector-task-management \ resync-item \ --obj-id=OBJECT_ID
Nubus for Kubernetes
Run the command in Listing 8.12. To set the proper environment variables in the following listing, use the commands in Listing 8.2.
Listing 8.12 Re-sync an existing item through UDM#
$ kubectl \ --namespace "$NAMESPACE_FOR_CONSUMER" \ execute \ --stdin \ --tty \ "$POD_NAME_FOR_OX_CONNECTOR" \ -- \ univention-ox-connector-task-management \ resync-item \ --obj-id=OBJECT_ID

8.1.3. Resolve blocked provisioning#

If provisioning has stopped, a previous change in Univention Directory Manager (UDM) might be the cause. The OX Connector can’t process the change and retries the action until an administrator resolves the cause.

Nubus for UCS

First, see Log files. Then look for warnings and errors. If the problem isn’t temporary, such as a network connectivity problem, resolve it manually.

As a last resort, move the task to the morgue. Find the task ID in the log file. It follows tasks: in an entry such as uid=...; OBJECT_IDENTIFIER; tasks:TASK_ID. Replace TASK_ID in the command in Listing 8.13.

Listing 8.13 Move a task to the morgue#

$ /usr/sbin/univention-ox-connector-task-management \
   move-task-to-morgue \
   --task-id=TASK_ID \
   --error-msg="Manual intervention after careful consideration"

Nubus for Kubernetes

First, see Log files. Then look for warnings and errors. If the problem isn’t temporary, such as a network connectivity problem, resolve it manually.

As a last resort, move the task to the morgue. Find the task ID in the log file. It follows tasks: in an entry such as uid=...; OBJECT_IDENTIFIER; tasks:TASK_ID. Replace TASK_ID in the command in Listing 8.14.

To set the proper environment variables in the following listing, use the commands in Listing 8.2.

Listing 8.14 Move a task to the morgue#

$ kubectl \
   --namespace "$NAMESPACE_FOR_CONSUMER" \
   execute \
   --stdin \
   --tty \
   "$POD_NAME_FOR_OX_CONNECTOR" \
   -- \
   univention-ox-connector-task-management \
   move-task-to-morgue \
   --task-id=TASK_ID \
   --error-msg="Manual intervention after careful consideration"

8.1.4. Re-provision all data#

To re-provision all data, recreate the OX Connector subscription and enable prefill, as described below. The Provisioning Service sends existing Univention Directory Manager (UDM) objects from subscribed modules to the OX Connector. The OX Connector Provisioning Consumer adds them to its queue.

Warning

Depending on the number of users and groups in the Nubus for UCS LDAP directory, this task can take a long time.

Avoid re-provisioning all data.

The Provisioning Service doesn’t add deleted UDM objects to the queue. Therefore, the OX Connector doesn’t run delete operations during re-provisioning. Previously deleted UDM objects aren’t removed from OX during this procedure.

Nubus for UCS

To re-provision all data, run the commands in Listing 8.15 on the Primary Directory Node. The commands do the following:

Set up configuration parameters, such as base URL, administrator password, and subscription password.
Delete the existing subscription.
Configure the connector subscription to subscribe to all relevant UDM modules.
Create the subscription using the configuration from the JSON file.
Delete the subscription configuration.
Save the Provisioning Service credentials to a file in the OX Connector configuration directory and restrict the file permissions.
Restart the OX Connector app.

Listing 8.15 Re-provisioning all UDM objects to OX App Suite#

$ export BASE_URL="https://$(ucr get ldap/master)/univention/provisioning"
$ export ADMIN_PASSWORD="$(python3 -c 'import json; print(json.load(open("/etc/provisioning-secrets.json"))["PROVISIONING_API_ADMIN_PASSWORD"])')"
$ export SUBSCRIPTION_PASSWORD="$(openssl rand -hex 32)"
$ curl --user "admin:$ADMIN_PASSWORD" \
    -X DELETE "$BASE_URL/v1/subscriptions/ox-connector" || true
$ umask 077
$ cat > /tmp/ox-connector-subscription.json <<EOF
{
  "name": "ox-connector",
  "realms_topics": [
    {"realm":"udm", "topic":"users/user"},
    {"realm":"udm", "topic":"groups/group"},
    {"realm":"udm", "topic":"oxmail/oxcontext"},
    {"realm":"udm", "topic":"oxmail/accessprofile"},
    {"realm":"udm", "topic":"oxresources/oxresources"},
    {"realm":"udm", "topic":"oxmail/functional_account"},
    {"realm":"udm", "topic":"oxmail/shared_account"},
    {"realm":"udm", "topic":"oxmail/shared_account_permission"}
  ],
  "request_prefill": true,
  "password": "$SUBSCRIPTION_PASSWORD"
}
EOF
$ curl --fail --user "admin:$ADMIN_PASSWORD" \
    -H "Content-Type: application/json" \
    -X POST "$BASE_URL/v1/subscriptions" \
    --data @/tmp/ox-connector-subscription.json \
    || { rm -f /tmp/ox-connector-subscription.json; exit 1; }
$ rm -f /tmp/ox-connector-subscription.json
$ printf 'export PROVISIONING_API_USERNAME=ox-connector\nexport PROVISIONING_API_PASSWORD=%s\n' \
    "$SUBSCRIPTION_PASSWORD" \
    > /var/lib/univention-appcenter/apps/ox-connector/conf/provisioning.env
$ chmod 640 /var/lib/univention-appcenter/apps/ox-connector/conf/provisioning.env
$ univention-app restart ox-connector

Nubus for Kubernetes

Before you can run the commands in Listing 8.18 you need to complete the following prerequisites:

Open an access to the Provisioning API endpoint. See Access to Provisioning API endpoint in Univention Nubus - Customization and Modification Manual [5].

Define the following environment variables:

NAMESPACE_FOR_CONSUMER, see Listing 8.16. Replace the placeholder <NAMESPACE> with the Kubernetes namespace for the OX Consumer.
POD_NAME_FOR_OX_CONNECTOR, see Listing 8.16.
PROVISIONING_API_ADMIN_SECRET_NAME, see Listing 8.17

Listing 8.16 Define POD_NAME_FOR_OX_CONNECTOR#

$ export NAMESPACE_FOR_CONSUMER="<NAMESPACE>"
$ kubectl \
   --namespace "$NAMESPACE_FOR_CONSUMER" \
   get pods | grep "ox-connector"
ox-connector-0    1/1   Running   0  19h

$ export POD_NAME_FOR_OX_CONNECTOR="ox-connector-0"

Listing 8.17 Define PROVISIONING_API_ADMIN_SECRET_NAME#

$ kubectl \
   --namespace "$NAMESPACE_FOR_CONSUMER" \
   get secret | grep provisioning-api-admin
ums-provisioning-api-admin    Opaque  1  73d

$ export PROVISIONING_API_ADMIN_SECRET_NAME="ums-provisioning-api-admin"

To re-provision all data, run the commands in Listing 8.18. The commands do the following:

Set up configuration parameters, such as base URL, administrator password, and subscription password.
Delete the existing subscription.
Configure the connector subscription to subscribe to all relevant UDM modules.
Create the subscription using the configuration from the JSON file.
Delete the subscription configuration.
Save the Provisioning Service credentials to a file in the directory where you run the commands and restrict the file permissions.
Recreate the pod for the OX Connector.

Listing 8.18 Re-provisioning all UDM objects to OX App Suite#

$ export BASE_URL="http://localhost:7777"
$ export ADMIN_PASSWORD="$(kubectl \
   --namespace "$NAMESPACE_FOR_CONSUMER" \
   get secret \
   $PROVISIONING_API_ADMIN_SECRET_NAME \
   -o json \
   | jq -r ".data.password" \
   | base64 -d)"
$ export SUBSCRIPTION_PASSWORD="$(openssl rand -hex 32)"
$ curl --user "admin:$ADMIN_PASSWORD" \
    -X DELETE "$BASE_URL/v1/subscriptions/ox-connector" || true
$ umask 077
$ cat > /tmp/ox-connector-subscription.json <<EOF
{
  "name": "ox-connector",
  "realms_topics": [
    {"realm":"udm", "topic":"users/user"},
    {"realm":"udm", "topic":"groups/group"},
    {"realm":"udm", "topic":"oxmail/oxcontext"},
    {"realm":"udm", "topic":"oxmail/accessprofile"},
    {"realm":"udm", "topic":"oxresources/oxresources"},
    {"realm":"udm", "topic":"oxmail/functional_account"},
    {"realm":"udm", "topic":"oxmail/shared_account"},
    {"realm":"udm", "topic":"oxmail/shared_account_permission"}
  ],
  "request_prefill": true,
  "password": "$SUBSCRIPTION_PASSWORD"
}
EOF
$ curl --fail --user "admin:$ADMIN_PASSWORD" \
    -H "Content-Type: application/json" \
    -X POST "$BASE_URL/v1/subscriptions" \
    --data @/tmp/ox-connector-subscription.json \
    || { rm -f /tmp/ox-connector-subscription.json; exit 1; }
$ rm -f /tmp/ox-connector-subscription.json
$ printf 'export PROVISIONING_API_USERNAME=ox-connector\nexport PROVISIONING_API_PASSWORD=%s\n' \
    "$SUBSCRIPTION_PASSWORD" \
    > provisioning.env
$ chmod 640 provisioning.env
$ kubectl delete pod "$POD_NAME_FOR_OX_CONNECTOR"

Caution

The OX Connector can delete objects based on the data that it receives. For example, it deletes a group object when isOxGroup = False.

OX Connector for Nubus documentation 4.x

Manage provisioning tasks

Contents

8.1. Manage provisioning tasks#

8.1.1. Check provisioning health#

8.1.2. Handle failed tasks#

8.1.3. Resolve blocked provisioning#

8.1.4. Re-provision all data#