How-to: OX Connector: Troubleshooting Guide

Knowledge Base Community
, , , , ,
1

Univention OX Connector: Troubleshooting Guide

This guide provides structured solutions and workarounds for common issues encountered when using the Univention OX Connector. Each section corresponds directly to topics covered in the official troubleshooting documentation.

1. Log Files & Debug

Check these key logs to understand the Connector’s behavior and errors:

  • Listener Converter: /var/log/univention/listener_modules/ox-connector.log
    Contains records of create/update/delete events, configuration issues, and SOAP API failures. (SOAP API)
  • OX-Connector Debug Enable Advanced Debug
  • App Center: /var/log/univention/appcenter.log
    Logs lifecycle actions such as install, update, uninstall, or config changes.
  • Domain Join: /var/log/univention/join.log
    Captures domain join events triggered during the OX Connector installation.

2. Health Check

Ensure the provisioning queue is clear and the system is healthy:

  1. Confirm no pending provisioning files in the listener directories:
$ DIR_LISTENER="/var/lib/univention-appcenter/listener/ox-connector"
$ ls -1 "$DIR_LISTENER"/ | wc -l  # should be 0

$ DIR_CONVERTER="/var/lib/univention-appcenter/apps/ox-connector/data/listener"
$ ls -1 "$DIR_CONVERTER"/ | wc -l  # should be 0
  1. Look for consecutive errors labeled like INFO This is consecutive error #… in the listener log, these indicate queue processing problems.
  2. Use get_current_error.py to integrate health checks:
  • univention-app shell ox-connector /usr/local/share/ox-connector/resources/get_current_error.py

Output example on error:

{'errors': '10', 'message': "…Connection refused", 'filename': '…timestamp.json'}

Clean output when healthy:

{'errors': '0'}

This script supports integration with Nagios or other monitoring tools.
Ox-Connector Health-Check

3. Provisioning Stops

The provisioning process may hang if a UDM change introduces inconsistency. Perform the following:

  • Review logs for persistent errors.
  • If warranted, manually delete the problematic queue file (see Section 4.1).

4. Queue Management

You can inspect and manipulate the connector’s queue of pending JSON files:

4.1 Delete a Single Item

To remove an unprocessable record:

  1. Identify the filename from the listener converter’s error logs.
  2. Delete it manually:
rm /var/lib/univention-appcenter/apps/ox-connector/data/listener/<timestamp>.json

4.2 Re‑provision One UDM Object

If a user or group is missing or corrupted, requeue it:

DN="uid=user100,cn=users,$(ucr get ldap/base)"
ENTRY_UUID="$(univention-ldapsearch -b "$DN" + | grep entryUUID | awk '{print $2}')"
cat > /var/lib/univention-appcenter/listener/ox-connector/$(date +%F-%H-%M-%S).json <<EOF
{
  "entry_uuid": "$ENTRY_UUID",
  "dn": "$DN",
  "object_type": "users/user",
  "command": "modify"
}
EOF

4.3 Re‑provision All Data

Warning: This action may be time-consuming and is not recommended routinely.

univention-directory-listener-ctrl resync ox-connector

Note: Delete operations are not triggered, but objects with isOxGroup = Not may still be removed. (Re-provision all data)

5. Rebuild Cache

If internal OX object IDs are corrupted (e.g., after a database restore), rebuild the cache:

univention-app shell ox-connector
/oxp # update-ox-db-cache --delete
/oxp # update-ox-db-cache

From version 2.0.0 onwards, this is mandatory after upgrades. To speed this up:

update-ox-db-cache --build-cache

Note: Cache rebuild may require about 1 GB RAM per 10,000 users and may generate significant load. (Rebuild cache)

6. Duplicate Display Names

In OX Connector 2.2.0, oxDisplayName is no longer unique. If duplicates exist and OX SOAP rejects this, the following error appears:

zeep.exceptions.Fault: The displayname is already used; exceptionId …

To disable enforcement, add to user.properties on the OX App Suite:

com.openexchange.user.enforceUniqueDisplayName=false
com.openexchange.folderstorage.database.preferDisplayName=false

Note: These settings are default with App Center installs. (Duplicated displaynames

7. Group Provisioning Tracebacks

If a TRACEBACK occurs during group sync (e.g., due to missing old backup objects):

  • Run this command to detect missing old JSON files:
univention-ldapsearch "(&(univentionObjectType=users/user)(isOxUser=OK))" entryUUID |
sed -ne 's/entryUUID: //p' |
xargs -I{} bash -c "test -e /var/lib/univention-appcenter/apps/ox-connector/data/listener/old/{}.json || univention-ldapsearch -LLL entryUUID={} 1.1"

8. Verify Data Consistency

Starting with version 2.2.8, use check_sync_status.py to audit consistency among UDM, listener/old, and the OX database:

univention-app shell ox-connector
/oxp # ./check_sync_status.py \
    --dn <FULL_DN> \
    --udm_admin_account administrator \
    --udm_password_file udm.secret \
    --udm_host https://master.ucs

Options include --resync to auto‑add listener files for inconsistent objects. (Verify data consistency)

9. Preparing a Support Ticket

Before submitting a ticket, gather:

  • Relevant environment details
  • Log and traceback excerpts (especially from listener logs)
  • Steps to reliably reproduce the issue
  • Expected versus observed behaviour
  • The provisioning JSON files causing errors (Collect information for support ticket)

10. Invalid Identifier Values

Ensure that OX_USER_IDENTIFIER and OX_GROUP_IDENTIFIER are single-valued and not empty. Invalid settings result in assertion errors in the listener log, e.g.:

assert self.name is not None

Fix by assigning appropriate single-value identifiers. (Invalid values for OX_USER_IDENTIFIER or OX_GROUP_IDENTIFIER)

Summary

This article extracts and structures essential troubleshooting steps from the official Univention documentation. Use it as your go-to reference when diagnosing and resolving OX Connector issues.

For detailed examples and context, please refer to the original troubleshooting documentation 6. Troubleshooting — OX Connector app.

See also: