8.2. Troubleshoot OX Connector on Nubus for UCS

Use this page to troubleshoot problems with the OX Connector app on Nubus for UCS. It explains how to inspect log files. It also covers known problems, including duplicate display names, missing group members, and invalid identifier values.

8.2.1. Log files

The OX Connector app writes logs to several locations. This section lists the log file per involved component.

OX Connector Provisioning Consumer

Standard output of the OX Connector container. To read the output, run the command in Listing 8.19.

Contains log information from the OX Connector Provisioning Consumer about object create, update, and delete actions. It also reports warnings and errors when the OX Connector configuration isn’t correct or the connector can’t connect to the SOAP API.

Listing 8.19 View the log output of the OX Connector Provisioning Consumer

$ univention-app logs ox-connector

Provisioning Service

/var/log/univention/listener_modules/nubus-provisioning.log

Contains log information from the Provisioning Service about changes detected in the LDAP directory and delivered to subscribed services. The Provisioning Service containers write additional log information to /var/log/syslog.

Database management script

/var/lib/univention-appcenter/apps/ox-connector/data/univention-ox-connector-task-management.log

Contains log information from the database management script described in Manage provisioning tasks.

App Center

/var/log/univention/appcenter.log

Contains log information about App Center activities.

The App Center writes OX Connector-related information to this file when you run app lifecycle tasks, such as installing, updating, or uninstalling the app, or when you change the app settings.

For information about App Center logging and diagnostics, see Logging and diagnostics in Nubus for UCS 5.2 - Operation Manual [1].

Domain join

/var/log/univention/join.log

Contains log information from domain join processes. When the App Center installs OX Connector, the app also joins the domain.

For information about the domain join process, see Domain join process in Nubus for UCS 5.2 - Operation Manual [1].

8.2.2. Ensure OX database ID integrity

The OX Connector caches the internal IDs that OX App Suite assigns to objects. After you restore an OX App Suite database backup, the cached IDs can become stale or inconsistent. For more information about the cache, see Database of stored object state.

To rebuild the cache, run the command in Listing 8.20.

Listing 8.20 Rebuild cache for internal ID

$ /usr/sbin/univention-ox-connector-task-management rewrite-ox-db-id

Tip

Retrieve all users per context in one request

Rebuilding the cache can take a long time and depends on the number of users in the OX App Suite database.

The command in Listing 8.21 can speed up cache rebuilding because it retrieves up to 1,000 users from one context per request.

Listing 8.21 Increase performance on rebuilding the cache

$ /usr/sbin/univention-ox-connector-task-management \
   rewrite-ox-db-id \
   --build-cache-size=1000

Warning

Memory consumption

On the Nubus for UCS system with OX Connector, the rebuild process can use up to 1 GB of memory per 10,000 users in the OX App Suite database.

System load

Furthermore, the process may generate a lot of load on the OX App Suite system and the OX Connector app.

8.2.3. Duplicate display names

Since OX Connector version 2.2.0, the UDM property oxDisplayName no longer has a unique constraint.

If OX App Suite isn’t configured to allow duplicate display names, SOAP API calls fail with the exception as shown in Listing 8.22.

Listing 8.22 Exception when OX App Suite doesn’t allow duplicate display names

2023-05-30 11:59:31 WARNING Traceback (most recent call last):
2023-05-30 11:59:31 WARNING   File "/tmp/univention-ox-connector.listener_trigger", line 324, in run_on_files
2023-05-30 11:59:31 WARNING     f(obj)
2023-05-30 11:59:31 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/provisioning/__init__.py", line 86, in run
2023-05-30 11:59:31 WARNING     modify_user(obj)
2023-05-30 11:59:31 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/provisioning/users.py", line 420, in modify_user
2023-05-30 11:59:31 WARNING     user.modify()
2023-05-30 11:59:31 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/soap/backend.py", line 477, in modify
2023-05-30 11:59:31 WARNING     super(SoapUser, self).modify()
2023-05-30 11:59:31 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/soap/backend.py", line 180, in modify
2023-05-30 11:59:31 WARNING     self.service(self.context_id).change(obj)
2023-05-30 11:59:31 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/soap/services.py", line 536, in change
2023-05-30 11:59:31 WARNING     return self._call_ox('change', usrdata=user)
2023-05-30 11:59:31 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/soap/services.py", line 163, in _call_ox
2023-05-30 11:59:31 WARNING     return getattr(service, func)(**kwargs)
2023-05-30 11:59:31 WARNING   File "/usr/lib/python3.9/site-packages/zeep/proxy.py", line 46, in __call__
2023-05-30 11:59:31 WARNING     return self._proxy._binding.send(
2023-05-30 11:59:31 WARNING   File "/usr/lib/python3.9/site-packages/zeep/wsdl/bindings/soap.py", line 135, in send
2023-05-30 11:59:31 WARNING     return self.process_reply(client, operation_obj, response)
2023-05-30 11:59:31 WARNING   File "/usr/lib/python3.9/site-packages/zeep/wsdl/bindings/soap.py", line 229, in process_reply
2023-05-30 11:59:31 WARNING     return self.process_error(doc, operation)
2023-05-30 11:59:31 WARNING   File "/usr/lib/python3.9/site-packages/zeep/wsdl/bindings/soap.py", line 329, in process_error
2023-05-30 11:59:31 WARNING     raise Fault(
2023-05-30 11:59:31 WARNING zeep.exceptions.Fault: The displayname is already used; exceptionId 1170523631-4

To allow duplicate display names, add the properties in Listing 8.23 to the user.properties file in OX App Suite.

Listing 8.23 Configuration to allow duplicate display names in OX App Suite

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

Note

The OX App Suite installation from the App Center configures these properties by default.

8.2.4. Missing group members

When the OX Connector synchronizes a group, it needs the internal ID of every group member. For more information, see Database of stored object state. The connector looks up each member in its database of old entries. If a user belongs to a group but isn’t in that database, the OX Connector skips the user without failing. It logs a message, as shown in Listing 8.24.

Re-provision the missing user object manually. For example, re-provision uid=oxuser1,cn=users,dc=example,dc=com. Follow Handle failed tasks to synchronize the missing user. When the OX Connector next processes the group object, the OX Connector Provisioning Consumer adds the user to the group again.

Listing 8.24 Log message for missing group members

 2024-11-15 16:06:33 INFO    Group will be OX Group
 2024-11-15 16:06:33 INFO    Group wants user as member. But the user is unknown. Ignoring...

8.2.5. Invalid values for OX_USER_IDENTIFIER or OX_GROUP_IDENTIFIER

A UDM user property, or a UDM group property for OX_GROUP_IDENTIFIER, is valid only when it contains a single value that isn’t None. If the configured UDM property contains an empty value or a list of values, the OX Connector enters an error state. Set a valid value to resolve the error.

Setting an invalid value for the app settings OX_USER_IDENTIFIER or OX_GROUP_IDENTIFIER leads to the errors in Listing 8.25 or Listing 8.26.

Listing 8.25 Error caused by an invalid value for app settings OX_USER_IDENTIFIER

 2024-01-11 13:57:39 WARNING Traceback (most recent call last):
 2024-01-11 13:57:39 WARNING   File "/tmp/univention-ox-connector.listener_trigger", line 351, in run_on_files
 2024-01-11 13:57:39 WARNING     function(obj)
 2024-01-11 13:57:39 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/provisioning/__init__.py", line 86, in run
 2024-01-11 13:57:39 WARNING     modify_user(obj)
 2024-01-11 13:57:39 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/provisioning/users.py", line 454, in modify_user
 2024-01-11 13:57:39 WARNING     user.modify()
 2024-01-11 13:57:39 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/soap/backend.py", line 475, in modify
 2024-01-11 13:57:39 WARNING     super(SoapUser, self).modify()
 2024-01-11 13:57:39 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/soap/backend.py", line 176, in modify
 2024-01-11 13:57:39 WARNING     assert self.name is not None
 2024-01-11 13:57:39 WARNING No name for this attribute. Missing or misconfigured identifier app settings
 2024-01-11 13:57:39 WARNING (OX_USER_IDENTIFIER or OX_GROUP_IDENTIFIER) might be the reason, see
 2024-01-11 13:57:39 WARNING https://docs.software-univention.de/ox-connector-app/latest/troubleshooting.html#invalid-values-for-ox-user-identifier-or-ox-group-identifier
 2024-01-11 13:57:39 WARNING for more information.

Listing 8.26 Error caused by an invalid value for app settings OX_GROUP_IDENTIFIER

 setting "users" udm property for groups
 2024-01-11 13:59:36 WARNING Traceback (most recent call last):
 2024-01-11 13:59:36 WARNING   File "/tmp/univention-ox-connector.listener_trigger", line 351, in run_on_files
 2024-01-11 13:59:36 WARNING     function(obj)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/provisioning/__init__.py", line 108, in run
 2024-01-11 13:59:36 WARNING     modify_group(new_obj)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/provisioning/groups.py", line 146, in modify_group
 2024-01-11 13:59:36 WARNING     group.modify()
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/soap/backend.py", line 180, in modify
 2024-01-11 13:59:36 WARNING     self.service(self.context_id).change(obj)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/soap/services.py", line 607, in change
 2024-01-11 13:59:36 WARNING     return self._call_ox('change', grp=grp)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/univention/ox/soap/services.py", line 194, in _call_ox
 2024-01-11 13:59:36 WARNING     return getattr(service, func)(**kwargs)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/proxy.py", line 46, in __call__
 2024-01-11 13:59:36 WARNING     return self._proxy._binding.send(
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/wsdl/bindings/soap.py", line 123, in send
 2024-01-11 13:59:36 WARNING     envelope, http_headers = self._create(
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/wsdl/bindings/soap.py", line 73, in _create
 2024-01-11 13:59:36 WARNING     serialized = operation_obj.create(*args, **kwargs)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/wsdl/definitions.py", line 224, in create
 2024-01-11 13:59:36 WARNING     return self.input.serialize(*args, **kwargs)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/wsdl/messages/soap.py", line 79, in serialize
 2024-01-11 13:59:36 WARNING     self.body.render(body, body_value)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/elements/element.py", line 232, in render
 2024-01-11 13:59:36 WARNING     self._render_value_item(parent, value, render_path)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/elements/element.py", line 256, in _render_value_item
 2024-01-11 13:59:36 WARNING     return self.type.render(node, value, None, render_path)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/types/complex.py", line 307, in render
 2024-01-11 13:59:36 WARNING     element.render(node, element_value, child_path)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/elements/indicators.py", line 256, in render
 2024-01-11 13:59:36 WARNING     element.render(parent, element_value, child_path)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/elements/element.py", line 232, in render
 2024-01-11 13:59:36 WARNING     self._render_value_item(parent, value, render_path)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/elements/element.py", line 255, in _render_value_item
 2024-01-11 13:59:36 WARNING     return value._xsd_type.render(node, value, xsd_type, render_path)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/types/complex.py", line 307, in render
 2024-01-11 13:59:36 WARNING     element.render(node, element_value, child_path)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/elements/indicators.py", line 256, in render
 2024-01-11 13:59:36 WARNING     element.render(parent, element_value, child_path)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/elements/element.py", line 232, in render
 2024-01-11 13:59:36 WARNING     self._render_value_item(parent, value, render_path)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/elements/element.py", line 256, in _render_value_item
 2024-01-11 13:59:36 WARNING     return self.type.render(node, value, None, render_path)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/types/simple.py", line 96, in render
 2024-01-11 13:59:36 WARNING     node.text = value if isinstance(value, etree.CDATA) else self.xmlvalue(value)
 2024-01-11 13:59:36 WARNING   File "/usr/lib/python3.9/site-packages/zeep/xsd/types/builtins.py", line 27, in _wrapper
 2024-01-11 13:59:36 WARNING     raise ValueError(
 2024-01-11 13:59:36 WARNING ValueError: The String type doesn't accept collections as value