Python UDM REST Client¶
Python library to interact with the Univention UDM REST API, implements the interface of the Python UDM API.
- Free software: GNU Affero General Public License version 3
- Documentation: https://udm-rest-client.readthedocs.io
Features¶
- Asynchronous
- Automatic handling of HTTP(S) sessions
- Type annotations
- 100% test coverage (unittests + integration tests)
- Python 3.6, 3.7, 3.8, 3.9, 3.10, 3.11
Usage¶
The UDM
context manager opens and closes a HTTP session:
>>> import asyncio
>>> from udm_rest_client.udm import UDM
>>>
>>> async def get_obj(mod_name, dn):
... async with UDM(
... "USERNAME",
... "PASSWORD",
... "https://FQDN.OF.UCS/univention/udm",
... ssl_ca_cert="ucs-root-ca.crt"
... ) as udm:
... mod = udm.get(mod_name)
... return await mod.get(dn)
...
>>> # Python 3.6:
>>> loop = asyncio.get_event_loop()
>>> obj = loop.run_until_complete(get_obj("users/user", "uid=foo,cn=users,BASE-DN"))
>>>
>>> # Python 3.7+:
>>> obj = asyncio.run(get_obj("users/user", "uid=foo,cn=users,BASE-DN"))
>>>
>>> print(obj)
UdmObject('users/user', 'uid=foo,cn=users,BASE-DN')
>>> print(obj.props.username)
foo
There are more examples in the docs usage section.
If the SSL CA certificate is not available verify_ssl=False
can be used in place of ssl_ca_cert=...
. Obviously that is not safe! The CA of any UCS server can always be downloaded from http://FQDN.OF.UCS/ucs-root-ca.crt
.
Installation¶
Install Python UDM REST Client via pip from PyPI:
$ pip install udm-rest-client
Install the OpenAPI client library used by the udm-rest-client. It is created by software from the OpenAPI Generator project. You need to either have a local Java installation (Java 8+) or run the projects Docker container. The process is scripted:
$ update_openapi_client --generator docker ucs.master.fqdn.or.ip # use Docker $ update_openapi_client --generator java ucs.master.fqdn.or.ip # use Java
Use --insecure
to ignore SSL verification errors. See --help
for more options.
Use --username
and --password
to provide credentials if access to your openapi.json is protected. This is the
default in newer versions of UCS and thus credentials are needed.
Important:
Whenever a new UDM module is installed in the domain, it is necessary to rerun update_openapi_client
.
The new UDM module will otherwise not be available in the Python UDM REST Client.
Very few apps (like UCS@school and Open-Xchange) install new UDM modules.
New extended attributes do not require to rebuild the OpenAPI client library.
Tests¶
There are some isolated unittests, but most tests run against a real UDM REST API. Either an existing UCS installation can be used, or a LXD container started.
Run tests with the current Python interpreter:
$ make test
Using tox the tests can be executed with all supported Python versions:
$ make test-all
Using the UCS LXD container is automated in the Makefile
. It has commands to download and start the LXD image (1 GB) and running the tests:
$ make create-lxd-test-server-config
$ make test
Initializing LXD is however left up to the developer (see https://linuxcontainers.org/lxd/). Using storage backend lvm
, btrfs
or zfs
is recommended for repeated use. To run the tests only once, the storage backend dir
is the easiest to use. It is very slow though, as it requires unpacking the image every time the container is started.
The Makefile
also needs yq
to be installed: https://github.com/mikefarah/yq
It is also possible to use an existing UCS server for the tests. Export UCS_HOST
(the servers IP/FQDN), UCS_USERDN
(the DN of an administrator account, usually uid=Administrator,cn=users,dc=...
) and UCS_PASSWORD
(the accounts password), before starting the tests:
$ export UCS_HOST="my.server.local"
$ export UCS_USERDN="uid=Administrator,cn=users,dc=domain,dc=local"
$ export UCS_PASSWORD="s3cr3t"
$ make test
Much more comfortable (especially for repeated use) is creating a file test_server.yaml
in the tests
directory, which will automatically be used by the tests:
$ cp test_server_example.yaml test/test_server.yaml
$ $EDITOR test_server.yaml
Don’t forget to update the OpenAPI client library before running the test against a new server:
$ update_openapi_client --generator <docker|java> --username Administrator --password s3cr3t $UCS_HOST
Run update_openapi_client --help
to see further options.
To get the IP address of the running UCS LXD container execute:
$ . lxd.sh ; lxd_container_ip
Logging¶
Standard logging is used for tracking the libraries activity.
To capture the log messages for this project, subscribe to a logger named udm_rest_client
.
The UDM REST API on the UCS server logs into the file /var/log/univention/directory-manager-rest.log
.
Repo permissions¶
- GitHub: @dansan and @JuergenBS
- GitLab: @JuergenBS
- PyPI: @dansan and @SamuelYaron
- RTD: @dansan and @SamuelYaron
Credits¶
This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.