How to: Enable Advanced Debugging for the OX-Connector in UCS
Description:
This article describes how to configure advanced debugging for the OX-Connector in a Univention Corporate Server (UCS) environment. The debugging process can be applied to both the listener-converter module and the Docker container of the OX-Connector. Following the instructions below will provide detailed debug information for troubleshooting and monitoring purposes.
1. Enabling Listener-Converter Debug
To increase the debug information for the OX-Connector listener-converter module, the following UCR variable can be set. After applying this setting, the listener-converter service must be restarted.
ucr set listener/module/ox-connector/debug/level=4systemctl restart univention-appcenter-listener-converter@ox-connector.service
Hint:
The Listener-Converter is the connection between the LDAP Listener module and the OX-Connector docker container.
Reference: 4. Architecture — OX Connector app
Log file location:
/var/log/univention/listener_modules/ox-connector.log
Full example ox-connector.log:
2025-10-08 19:57:09 INFO modify of cn=OX-Group-01,cn=groups,dc=univention,dc=intranet (id: b'83ce2743-3ba8-470e-b881-7796642b351b', file: /var/lib/univention-appcenter/listener//ox-connector/2025-10-08-19-57-09-863436.json)
2025-10-08 19:57:11 INFO univention-appcenter-listener-converter.get_app_connection:43 Using App account connection
2025-10-08 19:57:11 DEBUG univention-appcenter-listener-converter.find_and_convert_files:140 Converting /var/lib/univention-appcenter/listener/ox-connector/2025-10-08-19-57-09-863436.json
2025-10-08 19:57:11 INFO univention-appcenter-listener-converter.convert:124 conversion of cn=OX-Group-01,cn=groups,dc=univention,dc=intranet (id: 83ce2743-3ba8-470e-b881-7796642b351b, file: /var/lib/univention-appcenter/apps/ox-connector/data/listener/2025-10-08-19-57-09-863436.json)
2025-10-08 19:57:11 DEBUG univention-appcenter-listener-converter.find_and_convert_files:163 Deleting used /var/lib/univention-appcenter/listener/ox-connector/2025-10-08-19-57-09-863436.json
2025-10-08 19:57:11 DEBUG docker.execute:313 Using container.ead0 for container ead03f27982568a13759906b9dd0695ba3cc03df3b6710b69826986be0e4c243
2025-10-08 19:57:11 DEBUG utils.call_process:238 Calling docker exec -u root ead03f27982568a13759906b9dd0695ba3cc03df3b6710b69826986be0e4c243 chmod 0755 /tmp/univention-ox-connector.listener_trigger
2. Listing OX-Connector Container Configuration
The OX-Connector docker container has several app settings and this can be listed as follows:
univention-app configure ox-connector --list
Example output:
OX_SOAP_SERVER: 'https://ucs5primary.univention.intranet' (The server where Open-Xchange is installed)
OX_IMAP_SERVER: 'imap://ucs5primary.univention.intranet:143' (Default IMAP server for new users (if not set explicitly))
OX_SMTP_SERVER: 'smtp://ucs5primary.univention.intranet:587' (Default SMTP server for new users (if not set explicitly))
DEFAULT_CONTEXT: 10 (Default context for users (must exist))
OX_LANGUAGE: 'de_DE' (Default language for new users)
LOCAL_TIMEZONE: 'Europe/Berlin' (Default timezone for new users)
OX_MASTER_ADMIN: 'oxadminmaster' (OX Admin username)
OX_MASTER_PASSWORD: 'u-wchxBO5gX6hqTukgpA' (OX Admin password)
OX_IMAP_LOGIN: None
OX_FUNCTIONAL_ACCOUNT_LOGIN_TEMPLATE: None
OX_USER_IDENTIFIER: None
OX_GROUP_IDENTIFIER: None
OX_ENABLE_DEPUTY_PERMISSIONS: False
OX_CONNECTOR_LOG_LEVEL: 'INFO' (OX-Connector log level)
OX_CONNECTOR_STOP_ON_ERROR: True
3. Enabling Full Debug for SOAP API Calls
To log SOAP API calls in ox-connector.log, the OX_CONNECTOR_LOG_LEVEL must be set to DEBUG. Setting this value requires reconfiguring the app, which removes and recreates the Docker container.
univention-app configure ox-connector --set OX_CONNECTOR_LOG_LEVEL=DEBUG
Command output example:
root@ucs5primary:~# univention-app configure ox-connector --set OX_CONNECTOR_LOG_LEVEL=DEBUG
Configuring ox-connector=3.0.0
Setting OX_CONNECTOR_LOG_LEVEL to 'DEBUG'
ucr cannot be found, falling back to changing the database file directly
Saving data from old container (ox-connector=3.0.0)
Starting docker-app-ox-connector (via systemctl): docker-app-ox-connector.service.
Running command: docker cp ead03f27982568a13759906b9dd0695ba3cc03df3b6710b69826986be0e4c243:/etc/machine.secret /var/lib/univention-appcenter/apps/ox-connector/machine.secret
Starting docker-app-ox-connector (via systemctl): docker-app-ox-connector.service.
Stopping docker-app-ox-connector (via systemctl): docker-app-ox-connector.service.
Removing old container
ead03f27982568a13759906b9dd0695ba3cc03df3b6710b69826986be0e4c243
Setting up new container (ox-connector=3.0.0)
Module: ox-config
Creating data directories for ox-connector...
Registering UCR for ox-connector
Marking ox-connector=3.0.0 as installed
Creating /etc/init.d/docker-app-ox-connector
Adding localhost to LDAP object
Module: ox-config
Reloading apache2 configuration (via systemctl): apache2.service.
Initializing app image
Running command: docker create --hostname ox-co-59135265 --env-file /var/lib/univention-appcenter/apps/ox-connector/data/../ox-connector.env -v /var/lib/univention-appcenter/apps/ox-connector/data:/var/lib/univention-appcenter/apps/ox-connector/data -v /etc/apt/apt.conf.d/80proxy:/etc/apt/apt.conf.d/81proxy:ro -v /var/lib/univention-appcenter/apps/ox-connector/conf:/var/lib/univention-appcenter/apps/ox-connector/conf -v /sys/fs/cgroup:/sys/fs/cgroup:ro -v /var/lib/univention-appcenter/listener/ox-connector/:/var/lib/univention-appcenter/listener/ox-connector/ --tmpfs /run --tmpfs /run/lock --security-opt seccomp:/etc/docker/seccomp-systemd.json -e container=docker docker.software-univention.de/ox-connector:3.0.0
d19d87cd722ccd78165edd761cb475fb09d57b1e38689c6b5079d321794129c4
Module: ox-config
Preconfiguring container d19d87cd722ccd78165edd761cb475fb09d57b1e38689c6b5079d321794129c4
Starting docker-app-ox-connector (via systemctl): docker-app-ox-connector.service.
Configuring ox-connector=3.0.0
Setting OX_SOAP_SERVER to 'https://ucs5primary.univention.intranet'
Setting OX_IMAP_SERVER to 'imap://ucs5primary.univention.intranet:143'
Setting OX_SMTP_SERVER to 'smtp://ucs5primary.univention.intranet:587'
Setting DEFAULT_CONTEXT to '10'
Setting OX_LANGUAGE to 'de_DE'
Setting LOCAL_TIMEZONE to 'Europe/Berlin'
Setting OX_MASTER_ADMIN to 'oxadminmaster'
Unsetting OX_IMAP_LOGIN
Unsetting OX_FUNCTIONAL_ACCOUNT_LOGIN_TEMPLATE
Unsetting OX_USER_IDENTIFIER
Unsetting OX_GROUP_IDENTIFIER
Setting OX_ENABLE_DEPUTY_PERMISSIONS to 'false'
Setting OX_CONNECTOR_LOG_LEVEL to 'DEBUG'
Setting OX_CONNECTOR_STOP_ON_ERROR to 'true'
ucr cannot be found, falling back to changing the database file directly
Executing interface restore_data_before_setup for ox-connector
No interface defined
Executing interface restore_data_after_setup for ox-connector
Copying App Center's restore_data_after_setup to container's /tmp/ox-connector.restore_data_after_setup
updating certificates for ox-connector=3.0.0
Module: ox-config
Module: ox-config
Registering UCR for ox-connector
Marking ox-connector=3.0.0 as installed
Creating /etc/init.d/docker-app-ox-connector
Adding localhost to LDAP object
Reloading apache2 configuration (via systemctl): apache2.service.
Executing interface configure for ox-connector
Copying App Center's configure to container's /tmp/ox-connector.configure
Master credentials successfully set
Example Log with SOAP API Calls:
2025-10-08 20:15:29 INFO modify of cn=OX-Group-01,cn=groups,dc=univention,dc=intranet (id: b'83ce2743-3ba8-470e-b881-7796642b351b', file: /var/lib/univention-appcenter/listener//ox-connector/2025-10-08-20-15-
29-493765.json)
2025-10-08 20:15:32 INFO univention-appcenter-listener-converter.get_app_connection:43 Using App account connection
2025-10-08 20:15:32 DEBUG univention-appcenter-listener-converter.find_and_convert_files:140 Converting /var/lib/univention-appcenter/listener/ox-connector/2025-10-08-20-15-29-493765.json
2025-10-08 20:15:33 INFO univention-appcenter-listener-converter.convert:124 conversion of cn=OX-Group-01,cn=groups,dc=univention,dc=intranet (id: 83ce2743-3ba8-470e-b881-7796642b351b, file: /var/lib/univent
ion-appcenter/apps/ox-connector/data/listener/2025-10-08-20-15-29-493765.json)
2025-10-08 20:15:33 DEBUG univention-appcenter-listener-converter.find_and_convert_files:163 Deleting used /var/lib/univention-appcenter/listener/ox-connector/2025-10-08-20-15-29-493765.json
2025-10-08 20:15:33 DEBUG docker.execute:313 Using container.d19d for container d19d87cd722ccd78165edd761cb475fb09d57b1e38689c6b5079d321794129c4
2025-10-08 20:15:33 DEBUG utils.call_process:238 Calling docker exec -u root d19d87cd722ccd78165edd761cb475fb09d57b1e38689c6b5079d321794129c4 chmod 0755 /tmp/univention-ox-connector.listener_trigger
2025-10-08 20:15:33 DEBUG docker.execute:313 Using container.d19d for container d19d87cd722ccd78165edd761cb475fb09d57b1e38689c6b5079d321794129c4
2025-10-08 20:15:33 DEBUG utils.call_process:238 Calling docker exec -u root d19d87cd722ccd78165edd761cb475fb09d57b1e38689c6b5079d321794129c4 /tmp/univention-ox-connector.listener_trigger
2025-10-08 20:15:34 INFO utils._handle_output:246 univention.ox: Adding a new task from /var/lib/univention-appcenter/apps/ox-connector/data/listener/2025-10-08-20-15-29-493765.json
2025-10-08 20:15:34 INFO utils._handle_output:246 Parsing /var/lib/univention-appcenter/apps/ox-connector/data/listener/2025-10-08-20-15-29-493765.json
2025-10-08 20:15:34 INFO utils._handle_output:246 Task cn=ox-group-01,cn=groups,dc=univention,dc=intranet (83ce2743-3ba8-470e-b881-7796642b351b; groups/group; tasks:1) created
2025-10-08 20:15:34 INFO utils._handle_output:246 Yielding task cn=ox-group-01,cn=groups,dc=univention,dc=intranet (83ce2743-3ba8-470e-b881-7796642b351b; groups/group; tasks:1)
2025-10-08 20:15:34 INFO utils._handle_output:246 univention.ox: Processing Task cn=ox-group-01,cn=groups,dc=univention,dc=intranet (83ce2743-3ba8-470e-b881-7796642b351b; groups/group; tasks:1)
2025-10-08 20:15:34 INFO utils._handle_output:246 univention.ox: Loading old object for 83ce2743-3ba8-470e-b881-7796642b351b
2025-10-08 20:15:34 INFO utils._handle_output:246 Found old object cn=ox-group-01,cn=groups,dc=univention,dc=intranet (83ce2743-3ba8-470e-b881-7796642b351b; groups/group; old:39)
2025-10-08 20:15:34 INFO utils._handle_output:246 univention.ox: ... Object('groups/group', 'cn=ox-group-01,cn=groups,dc=univention,dc=intranet')
2025-10-08 20:15:34 INFO utils._handle_output:246 Group OX-Group-01 will be OX Group
2025-10-08 20:15:34 INFO utils._handle_output:246 univention.ox: Loading old object for uid=mirac.erde,cn=users,dc=univention,dc=intranet
2025-10-08 20:15:34 INFO utils._handle_output:246 Found old object uid=mirac.erde,cn=users,dc=univention,dc=intranet (0b51a0a7-43e0-402a-8aad-df0db28c7b2e; users/user; old:96)
2025-10-08 20:15:34 INFO utils._handle_output:246 univention.ox: Loading old object for uid=test01OX,cn=users,dc=univention,dc=intranet
2025-10-08 20:15:34 INFO utils._handle_output:246 Found old object uid=test01ox,cn=users,dc=univention,dc=intranet (a444f7c2-ae90-4041-86e0-3230c5c6ec44; users/user; old:36)
2025-10-08 20:15:34 INFO utils._handle_output:246 univention.ox: Loading old object for uid=test02OX,cn=users,dc=univention,dc=intranet
2025-10-08 20:15:34 INFO utils._handle_output:246 Found old object uid=test02ox,cn=users,dc=univention,dc=intranet (72b705f8-355f-48f5-bd13-d6230190f10d; users/user; old:15)
2025-10-08 20:15:34 INFO utils._handle_output:246 Object('groups/group', 'cn=ox-group-01,cn=groups,dc=univention,dc=intranet') will be processed with context 10
2025-10-08 20:15:34 INFO utils._handle_output:246 Modifying Object('groups/group', 'cn=ox-group-01,cn=groups,dc=univention,dc=intranet')
2025-10-08 20:15:34 INFO utils._handle_output:246 Loading remote data from: https://ucs5primary.univention.intranet/webservices/OXContextService?wsdl
2025-10-08 20:15:34 INFO utils._handle_output:246 Loading remote data from: https://ucs5primary.univention.intranet/webservices/OXGroupService?wsdl
2025-10-08 20:15:34 INFO utils._handle_output:246 Loading remote data from: https://ucs5primary.univention.intranet/webservices/OXResourceService?wsdl
2025-10-08 20:15:34 INFO utils._handle_output:246 Loading remote data from: https://ucs5primary.univention.intranet/webservices/OXSecondaryAccountService?wsdl
2025-10-08 20:15:34 INFO utils._handle_output:246 Loading remote data from: https://ucs5primary.univention.intranet/webservices/OXDeputyPermissionsService?wsdl
2025-10-08 20:15:34 INFO utils._handle_output:246 Loading remote data from: https://ucs5primary.univention.intranet/webservices/OXUserService?wsdl
2025-10-08 20:15:34 INFO utils._handle_output:246 Loading remote data from: https://ucs5primary.univention.intranet/webservices/OXGroupService?wsdl
2025-10-08 20:15:34 INFO utils._handle_output:246 HTTP Post to https://ucs5primary.univention.intranet:443/webservices/OXGroupService:
2025-10-08 20:15:34 INFO utils._handle_output:246 <?xml version='1.0' encoding='utf-8'?>
2025-10-08 20:15:34 INFO utils._handle_output:246 <soap-env:Envelope xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"><soap-env:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"><wsa:Action>urn:getData</wsa:Action><wsa:MessageID>urn:uuid:a8cea4a8-4946-490e-8103-f1097662415f</wsa:MessageID><wsa:To>https://ucs5primary.univention.intranet:443/webservices/OXGroupService</wsa:To></soap-env:Header><soap-env:Body><ns0:getData xmlns:ns0="http://soap.admin.openexchange.com"><ns0:ctx xmlns:ns2="http://dataobjects.soap.admin.openexchange.com/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:Context"><ns1:id xmlns:ns1="http://dataobjects.soap.admin.openexchange.com/xsd">10</ns1:id></ns0:ctx><ns0:grp xmlns:ns4="http://dataobjects.soap.admin.openexchange.com/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns4:Group"><ns3:name xmlns:ns3="http://dataobjects.soap.admin.openexchange.com/xsd">OX-Group-01</ns3:name></ns0:grp><ns0:auth xmlns:ns7="http://dataobjects.rmi.admin.openexchange.com/xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns7:Credentials"><ns5:login xmlns:ns5="http://dataobjects.rmi.admin.openexchange.com/xsd">oxadmin</ns5:login><ns6:password xmlns:ns6="http://dataobjects.rmi.admin.openexchange.com/xsd">O1ksn0vi6uDMlxJipSrD</ns6:password></ns0:auth></ns0:getData></soap-env:Body></soap-env:Envelope>
2025-10-08 20:15:34 INFO utils._handle_output:246 HTTP Response from https://ucs5primary.univention.intranet:443/webservices/OXGroupService (status: 500):
2025-10-08 20:15:34 INFO utils._handle_output:246 <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><soap:Body><soap:Fault><faultcode>soap:Server</faultcode><faultstring>com.openexchange.admin.rmi.exceptions.NoSuchObjectException: com.openexchange.admin.rmi.exceptions.NoSuchGroupException: No such group OX-Group-01 in context 10; exceptionId -1539371493-20; exceptionId -1539371493-22; exceptionId -1539371493-24</faultstring><detail><ns2:NoSuchGroupException xmlns:ns5="http://rmi.java/xsd" xmlns:ns4="http://exceptions.rmi.admin.openexchange.com/xsd" xmlns:ns3="http://dataobjects.rmi.admin.openexchange.com/xsd" xmlns:ns2="http://soap.admin.openexchange.com" xmlns="http://dataobjects.soap.admin.openexchange.com/xsd"><ns2:NoSuchGroupException><ns2:Exception xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"></ns2:Exception></ns2:NoSuchGroupException></ns2:NoSuchGroupException></detail></soap:Fault></soap:Body></soap:Envelope>
See also: