univention.udm package

Univention Directory Manager Modules (UDM) API

This is a simplified API for accessing UDM objects. It consists of UDM modules and UDM object. UDM modules are factories for UDM objects. UDM objects manipulate LDAP objects.

The UDM class is a LDAP connection and UDM module factory.

Usage:

from univention.udm import UDM

user_mod = UDM.admin().version(2).get('users/user')

or:

user_mod = UDM.machine().version(2).get('users/user')

or:

user_mod = UDM.credentials('myuser', 's3cr3t').version(2).get('users/user')

obj = user_mod.get(dn)
obj.props.firstname = 'foo'  # modify property
obj.position = 'cn=users,cn=example,dc=com'  # move LDAP object
obj.save()  # apply changes

obj = user_mod.get(dn)
obj.delete()

obj = user_mod.new()
obj.props.username = 'bar'
obj.props.lastname = 'baz'
obj.props.password = 'v3r7s3cr3t'
obj.props.unixhome = '/home/bar'
obj.save()

for obj in user_mod.search('uid=a*'):  # search() returns a generator
        print(obj.props.firstname, obj.props.lastname)

A shortcut exists to get UDM objects directly, without knowing their univention object type:

UDM.admin().version(2).obj_by_dn(dn)

A shortcut exists to get UDM objects directly, knowing their univention object type, but without knowing their DN:

UDM.admin().version(2).get('groups/group').get_by_id('Domain Users')

The API is versioned. A fixed version must be hard coded in your code. Supply it as argument to the UDM module factory or via version():

UDM(lo, 0)              # use API version 0 and an existing LDAP connection object
    UDM.admin().version(1)  # use API version 1
    UDM.credentials('myuser', 's3cr3t').version(2).obj_by_dn(dn)  # get object using API version 2
  • Version 0: values of UDM properties are the same as with the low level UDM API: mostly strings.

  • Version 1: values of (most) UDM properties are de/encoded to useful Python types (e.g. “0” -> 0 or False)

  • Version 2: an encoder for settings/portal_category properties was added.

The LDAP connection to use must be supplies as an argument to the UDM module factory or set via admin(), machine(), or credentials():

UDM(lo)        # use an already existing uldap connection object
UDM.admin()    # cn=admin connection
UDM.machine()  # machine connection
UDM.credentials(identity, password, base=None, server=None, port=None)  # custom connection,
    # `identity` is either a username or a DN. LDAP base, server FQDN/IP and port are optional.
    # If it is a username, a machine connection is used to retrieve the DN it belongs to.
class univention.udm.UDM(connection, api_version=None)[source]

Bases: object

Dynamic factory for creating BaseModule objects:

group_mod = UDM.admin().version(2).get('groups/group')
folder_mod = UDM.machine().version(2).get('mail/folder')
user_mod = UDM.credentials('myuser', 's3cr3t').version(2).get('users/user')

A shortcut exists to get UDM objects directly:

UDM.admin().version(2).obj_by_dn(dn)

Use the provided connection.

Parameters
  • connection – Any connection object (e.g., univention.admin.uldap.access)

  • api_version (int) – load only UDM modules that support the specified version, can be set later using version().

Returns

None

Return type

None

classmethod admin()[source]

Use a cn=admin connection.

Returns

a univention.udm.udm.UDM instance

Return type

univention.udm.udm.UDM

Raises

univention.udm.exceptions.ConnectionError – Non-Primary systems, server down, etc.

classmethod machine()[source]

Use a machine connection.

Returns

a univention.udm.udm.UDM instance

Return type

univention.udm.udm.UDM

Raises

univention.udm.exceptions.ConnectionError – File permissions, server down, etc.

classmethod credentials(identity, password, base=None, server=None, port=None)[source]

Use the provided credentials to open an LDAP connection.

identity must be either a username or a DN. If it is a username, a machine connection is used to retrieve the DN it belongs to.

Parameters
  • identity (str) – username or user dn to use for LDAP connection

  • password (str) – password of user / DN to use for LDAP connection

  • base (str) – optional search base

  • server (str) – optional LDAP server address as FQDN

  • port (int) – optional LDAP server port

Returns

a univention.udm.udm.UDM instance

Return type

univention.udm.udm.UDM

Raises

univention.udm.exceptions.ConnectionError – Invalid credentials, server down, etc.

version(api_version)[source]

Set the version of the API that the UDM modules must support.

Use in a chain of methods to get a UDM module:

UDM.get_admin().version(2).get('groups/group')
Parameters

api_version (int) – load only UDM modules that support the specified version

Returns

self (the univention.udm.udm.UDM instance)

Return type

univention.udm.udm.UDM

Raises

univention.udm.exceptions.ApiVersionMustNotChange – if called twice

get(name)[source]

Get an object of BaseModule (or of a subclass) for UDM module name.

Parameters

name (str) – UDM module name (e.g. users/user)

Returns

object of a subclass of BaseModule

Return type

BaseModule

Raises
obj_by_dn(dn)[source]

Try to load an UDM object from LDAP. Guess the required UDM module from the univentionObjectType LDAP attribute of the LDAP object.

Parameters

dn (str) – DN of the object to load

Returns

object of a subclass of BaseObject

Return type

BaseObject

Raises
property api_version
exception univention.udm.CreateError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when an error occurred when creating an object.

exception univention.udm.DeleteError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when a client tries to delete a UDM object but fails.

exception univention.udm.DeletedError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

exception univention.udm.NotYetSavedError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when a client tries to delete or reload a UDM object that is not yet saved.

msg = 'Object has not been created/loaded yet.'
exception univention.udm.ModifyError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised if an error occurred when modifying an object.

exception univention.udm.MoveError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised if an error occurred when moving an object.

exception univention.udm.MultipleObjects(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when more than one UDM object was found when there should be at most one.

exception univention.udm.NoObject(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when a UDM object could not be found at a DN.

exception univention.udm.UdmError(msg=None, dn=None, module_name=None)[source]

Bases: Exception

Base class of Exceptions raised by (simplified) UDM modules.

msg = ''
exception univention.udm.UnknownProperty(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when a client tries to set a property on BaseObject.props, that it does not support.

exception univention.udm.UnknownModuleType(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when an LDAP object has no or empty attribute univentionObjectType.

exception univention.udm.WrongObjectType(msg=None, dn=None, module_name=None, univention_object_type=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when the LDAP object to be loaded does not match the module type (BaseModule.name).

exception univention.udm.ConnectionError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when something goes wrong getting a connection.

exception univention.udm.NoSuperordinate(msg=None, dn=None, module_name=None, superordinate_types=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when no superordinate was supplied but one is needed.

exception univention.udm.NoApiVersionSet(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when UDM.get() or UDM.obj_by_id() is used before setting an API version.

msg = 'No API version has been set.'
exception univention.udm.ApiVersionNotSupported(msg=None, module_name=None, requested_version=None)[source]

Bases: univention.udm.exceptions.UdmError

exception univention.udm.ApiVersionMustNotChange(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when UDM.version() is called twice.

msg = 'The version of an UDM instance must not be changed.'

Submodules

univention.udm.base module

Base classes for (simplified) UDM modules and objects.

class univention.udm.base.LdapMapping(ldap2udm, udm2ldap)

Bases: tuple

Create new instance of LdapMapping(ldap2udm, udm2ldap)

property ldap2udm

Alias for field number 0

property udm2ldap

Alias for field number 1

class univention.udm.base.BaseObjectProperties(udm_obj)[source]

Bases: object

Container for UDM properties.

class univention.udm.base.BaseObject[source]

Bases: object

Base class for UDM object classes.

Usage:

  • Creation of instances is always done through BaseModule.new(), BaseModule.get() or BaseModule.search().

  • Modify an object:

    user.props.firstname = 'Peter'
    user.props.lastname = 'Pan'
    user.save()
    
  • Move an object:

    user.position = 'cn=users,ou=Company,dc=example,dc=com'
    user.save()
    
  • Delete an object:

    obj.delete()
    

After saving a BaseObject, it is reload()ed automatically because UDM hooks and listener modules often add, modify or remove properties when saving to LDAP. As this involves LDAP, it can be disabled if the object is not used afterwards and performance is an issue:

user_mod.meta.auto_reload = False

Don’t instantiate a BaseObject directly. Use BaseModule.get(), BaseModule.new() or BaseModule.search().

udm_prop_class

alias of univention.udm.base.BaseObjectProperties

reload()[source]

Refresh object from LDAP.

Returns

self

Return type

BaseObject

save()[source]

Save object to LDAP.

Returns

self

Return type

BaseObject

Raises

univention.udm.exceptions.MoveError – when a move operation fails

delete(remove_childs=False)[source]

Remove the object (and optionally its child nodes) from the LDAP database.

Parameters

remove_childs (bool) – if there are UDM objects below this objects DN, recursively remove them before removing this object

Returns

None

class univention.udm.base.BaseModuleMetadata(meta)[source]

Bases: object

Base class for UDM module meta data.

auto_open = True

Whether UDM objects should be open()ed.

auto_reload = True

Whether UDM objects should be reload()ed after saving.

instance(udm_module, api_version)[source]
property identifying_property

UDM property of which the mapped LDAP attribute is used as first component in a DN, e.g. username (LDAP attribute uid) or name (LDAP attribute cn).

lookup_filter(filter_s=None)[source]

Filter the UDM module uses to find its corresponding LDAP objects.

This can be used in two ways:

  • get the filter to find all objects:

    myfilter_s = obj.meta.lookup_filter()
    
  • get the filter to find a subset of the corresponding LDAP objects (filter_s will be combined with & to the filter for all objects):

    `myfilter = obj.meta.lookup_filter('(|(givenName=A*)(givenName=B*))')`
    
Parameters

filter_s (str) – optional LDAP filter expression

Returns

an LDAP filter string

Return type

str

property mapping

UDM properties to LDAP attributes mapping and vice versa.

Returns

a namedtuple containing two mappings: a) from UDM property to LDAP attribute and b) from LDAP attribute to UDM property

Return type

LdapMapping

class univention.udm.base.ModuleMeta(name, bases, attrs)[source]

Bases: univention.udm.plugins.Plugin

udm_meta_class

alias of univention.udm.base.BaseModuleMetadata

class univention.udm.base.BaseModule(name, connection, api_version)[source]

Bases: object

Base class for UDM module classes. UDM modules are basically UDM object factories.

Usage:

  1. Get module using:

    user_mod = UDM.admin/machine/credentials().version(2).get('users/user')
    
  2. Create fresh, not yet saved BaseObject:

    new_user = user_mod.new()
    
  3. Load an existing object:

    group = group_mod.get('cn=test,cn=groups,dc=example,dc=com')
    group = group_mod.get_by_id('Domain Users')
    
  4. Search and load existing objects:

    dc_slaves = dc_slave_mod.search(filter_s='cn=s10*')
    campus_groups = group_mod.search(base='ou=campus,dc=example,dc=com')
    
  5. Load existing object(s) without open()ing them:

    user_mod.meta.auto_open = False
    user = user_mod.get(dn)
    user.props.groups == []
    
meta = BaseModuleMetadata(supported_api_versions=(), suitable_for=[], used_api_version=None)
new(superordinate=None)[source]

Create a new, unsaved BaseObject object.

Parameters

superordinate (str or GenericObject) – DN or UDM object this one references as its superordinate (required by some modules)

Returns

a new, unsaved BaseObject object

Return type

BaseObject

get(dn)[source]

Load UDM object from LDAP.

Parameters

dn (str) – DN of the object to load.

Returns

an existing BaseObject instance.

Return type

BaseObject

Raises
get_by_id(id)[source]

Load UDM object from LDAP by searching for its ID.

This is a convenience function around search().

Parameters

id (str) – ID of the object to load (e.g. username (uid) for users/user, name (cn) for groups/group etc.)

Returns

an existing BaseObject object.

Return type

BaseObject

Raises
search(filter_s='', base='', scope='sub', sizelimit=0)[source]

Get all UDM objects from LDAP that match the given filter.

Parameters
  • filter_s (str) – LDAP filter (only object selector like uid=foo required, objectClasses will be set by the UDM module)

  • base (str) – LDAP search base.

  • scope (str) – LDAP search scope, e.g. base or sub or one.

  • sizelimit (int) – LDAP size limit for searched results.

Returns

iterator of BaseObject objects

Return type

Iterator(BaseObject)

univention.udm.binary_props module

Classes for holding binary UDM object properties.

univention.udm.binary_props.FileType

alias of univention.udm.binary_props.namedtuple

univention.udm.binary_props.get_file_type(filename_or_file)[source]

Get mime_type and encoding of file filename_or_file.

Handles both magic libraries.

Parameters

filename_or_file (str or file) – filename or open file

Returns

mime_type and encoding of filename_or_file

Return type

FileType

class univention.udm.binary_props.BaseBinaryProperty(name, encoded_value=None, raw_value=None)[source]

Bases: object

Container for a binary UDM property.

Data can be set and retrieved in both its raw form or encoded for LDAP.

Internally data is held in the encoded state (the form in which it will be saved to LDAP).

property encoded
property raw
property content_type
class univention.udm.binary_props.Base64BinaryProperty(name, encoded_value=None, raw_value=None)[source]

Bases: univention.udm.binary_props.BaseBinaryProperty

Container for a binary UDM property encoded using base64.

obj.props.<prop>.encoded == base64.b64encode(obj.props.<prop>.decoded)

>>> binprop = Base64BinaryProperty('example', raw_value=b'raw value')
>>> Base64BinaryProperty('example', encoded_value=binprop.encoded).raw == b'raw value'
True
>>> import base64
>>> binprop.encoded == base64.b64encode(binprop.raw)
True
property raw
class univention.udm.binary_props.Base64Bzip2BinaryProperty(name, encoded_value=None, raw_value=None)[source]

Bases: univention.udm.binary_props.BaseBinaryProperty

Container for a binary UDM property encoded using base64 after using bzip2.

obj.props.<prop>.encoded == base64.b64encode(obj.props.<prop>.decoded)

>>> binprop = Base64Bzip2BinaryProperty('example', raw_value=b'raw value')
>>> Base64Bzip2BinaryProperty('example', encoded_value=binprop.encoded).raw == b'raw value'
True
>>> import bz2, base64
>>> binprop.encoded == base64.b64encode(bz2.compress(binprop.raw))
True
property raw

univention.udm.connections module

class univention.udm.connections.LDAP_connection[source]

Bases: object

Caching LDAP connection factory.

classmethod get_admin_connection()[source]
classmethod get_machine_connection()[source]
classmethod get_credentials_connection(identity, password, base=None, server=None, port=None)[source]

univention.udm.encoders module

En/Decoders for object properties.

class univention.udm.encoders.BaseEncoder(property_name=None, *args, **kwargs)[source]

Bases: object

static = False
encode(value=None)[source]
decode(value=None)[source]
class univention.udm.encoders.Base64BinaryPropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = False
decode(value=None)[source]
encode(value=None)[source]
class univention.udm.encoders.Base64Bzip2BinaryPropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = False
decode(value=None)[source]
encode(value=None)[source]
class univention.udm.encoders.DatePropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = True
static decode(value=None)[source]
static encode(value=None)[source]
class univention.udm.encoders.DisabledPropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = True
static decode(value=None)[source]
static encode(value=None)[source]
class univention.udm.encoders.HomePostalAddressPropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = True
static decode(value=None)[source]
static encode(value=None)[source]
class univention.udm.encoders.ListOfListOflTextToDictPropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = True
static decode(value=None)[source]
static encode(value=None)[source]
class univention.udm.encoders.MultiLanguageTextAppcenterPropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = True
static decode(value=None)[source]
static encode(value=None)[source]
class univention.udm.encoders.SambaGroupTypePropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = True
choices = {'': '', '2': 'Domain Group', '3': 'Local Group', '5': 'Well-Known Group'}
choices_reverted = {'': '', 'Domain Group': '2', 'Local Group': '3', 'Well-Known Group': '5'}
classmethod decode(value=None)[source]
classmethod encode(value=None)[source]
class univention.udm.encoders.SambaLogonHoursPropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = True
classmethod decode(value=None)[source]
classmethod encode(value=None)[source]
class univention.udm.encoders.StringCaseInsensitiveResultLowerBooleanPropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = True
result_case_func = 'lower'
false_string = 'false'
true_string = 'true'
classmethod decode(value='')[source]
classmethod encode(value=None)[source]
class univention.udm.encoders.StringCaseInsensitiveResultUpperBooleanPropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.StringCaseInsensitiveResultLowerBooleanPropertyEncoder

result_case_func = 'upper'
class univention.udm.encoders.StringIntBooleanPropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = True
static decode(value=None)[source]
static encode(value=None)[source]
class univention.udm.encoders.StringIntPropertyEncoder(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = False
decode(value=None)[source]
static encode(value=None)[source]
class univention.udm.encoders.StringListToList(property_name=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

static = True
separator = ' '
classmethod decode(value=None)[source]
classmethod encode(value=None)[source]
class univention.udm.encoders.DnListPropertyEncoder(property_name=None, connection=None, api_version=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

Given a list of DNs, return the same list with an additional member objs. objs is a lazy object that will become the list of UDM objects the DNs refer to, when accessed.

dn_list_property_encoder_for() will dynamically produce subclasses of this for every UDM module required.

static = False
udm_module_name = ''
class DnsList(iterable=(), /)[source]

Bases: list

objs = None
class MyProxy[source]

Bases: Proxy

decode(value=None)[source]
static encode(value=None)[source]
property udm
class univention.udm.encoders.CnameListPropertyEncoder(property_name=None, connection=None, api_version=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.DnListPropertyEncoder

Given a list of CNAMEs, return the same list with an additional member objs. objs is a lazy object that will become the list of UDM objects the CNAMEs refer to, when accessed.

udm_module_name = 'dns/alias'
class univention.udm.encoders.DnsEntryZoneAliasListPropertyEncoder(property_name=None, connection=None, api_version=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.DnListPropertyEncoder

Given a list of dnsEntryZoneAlias entries, return the same list with an additional member objs. objs is a lazy object that will become the list of UDM objects the dnsEntryZoneAlias entries refer to, when accessed.

udm_module_name = 'dns/alias'
class univention.udm.encoders.DnsEntryZoneForwardListMultiplePropertyEncoder(property_name=None, connection=None, api_version=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.DnListPropertyEncoder

Given a list of dnsEntryZoneForward entries, return the same list with an additional member objs. objs is a lazy object that will become the list of UDM objects the dnsEntryZoneForward entries refer to, when accessed.

udm_module_name = 'dns/forward_zone'
class univention.udm.encoders.DnsEntryZoneForwardListSinglePropertyEncoder(property_name=None, connection=None, api_version=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.DnsEntryZoneForwardListMultiplePropertyEncoder

Given a list of dnsEntryZoneForward entries, return the same list with an additional member objs. objs is a lazy object that will become the list of UDM objects the dnsEntryZoneForward entries refer to, when accessed.

udm_module_name = 'dns/forward_zone'
class univention.udm.encoders.DnsEntryZoneReverseListMultiplePropertyEncoder(property_name=None, connection=None, api_version=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.DnsEntryZoneForwardListMultiplePropertyEncoder

Given a list of dnsEntryZoneReverse entries, return the same list with an additional member objs. objs is a lazy object that will become the list of UDM objects the dnsEntryZoneReverse entries refer to, when accessed.

udm_module_name = 'dns/reverse_zone'
class univention.udm.encoders.DnsEntryZoneReverseListSinglePropertyEncoder(property_name=None, connection=None, api_version=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.DnsEntryZoneReverseListMultiplePropertyEncoder

Given a list of dnsEntryZoneReverse entries, return the same list with an additional member objs. objs is a lazy object that will become the list of UDM objects the dnsEntryZoneReverse entries refer to, when accessed.

udm_module_name = 'dns/reverse_zone'
class univention.udm.encoders.DnPropertyEncoder(property_name=None, connection=None, api_version=None, *args, **kwargs)[source]

Bases: univention.udm.encoders.BaseEncoder

Given a DN, return a string object with the DN and an additional member obj. obj is a lazy object that will become the UDM object the DN refers to, when accessed.

dn_property_encoder_for() will dynamically produce subclasses of this for every UDM module required.

static = False
udm_module_name = ''
class DnStr[source]

Bases: str

obj = None
class MyProxy[source]

Bases: Proxy

decode(value=None)[source]
static encode(value=None)[source]
property udm
univention.udm.encoders.dn_list_property_encoder_for(udm_module_name)[source]

Create a (cached) subclass of DnListPropertyEncoder specific for each UDM module.

Parameters

udm_module_name (str) – name of UDM module (e.g. users/user) or auto if auto-detection should be done. Auto-detection requires one additional LDAP-query per object (still lazy though)!

Returns

subclass of DnListPropertyEncoder

Return type

type(DnListPropertyEncoder)

univention.udm.encoders.dn_property_encoder_for(udm_module_name)[source]

Create a (cached) subclass of DnPropertyEncoder specific for each UDM module.

Parameters

udm_module_name (str) – name of UDM module (e.g. users/user) or auto if auto-detection should be done. Auto-detection requires one additional LDAP-query per object (still lazy though)!

Returns

subclass of DnPropertyEncoder

Return type

type(DnPropertyEncoder)

univention.udm.exceptions module

exception univention.udm.exceptions.UdmError(msg=None, dn=None, module_name=None)[source]

Bases: Exception

Base class of Exceptions raised by (simplified) UDM modules.

msg = ''
exception univention.udm.exceptions.ApiVersionMustNotChange(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when UDM.version() is called twice.

msg = 'The version of an UDM instance must not be changed.'
exception univention.udm.exceptions.ConnectionError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when something goes wrong getting a connection.

exception univention.udm.exceptions.ApiVersionNotSupported(msg=None, module_name=None, requested_version=None)[source]

Bases: univention.udm.exceptions.UdmError

exception univention.udm.exceptions.CreateError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when an error occurred when creating an object.

exception univention.udm.exceptions.DeletedError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

exception univention.udm.exceptions.DeleteError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when a client tries to delete a UDM object but fails.

exception univention.udm.exceptions.NotYetSavedError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when a client tries to delete or reload a UDM object that is not yet saved.

msg = 'Object has not been created/loaded yet.'
exception univention.udm.exceptions.ModifyError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised if an error occurred when modifying an object.

exception univention.udm.exceptions.MoveError(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised if an error occurred when moving an object.

exception univention.udm.exceptions.NoApiVersionSet(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when UDM.get() or UDM.obj_by_id() is used before setting an API version.

msg = 'No API version has been set.'
exception univention.udm.exceptions.NoObject(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when a UDM object could not be found at a DN.

exception univention.udm.exceptions.NoSuperordinate(msg=None, dn=None, module_name=None, superordinate_types=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when no superordinate was supplied but one is needed.

exception univention.udm.exceptions.SearchLimitReached(msg=None, dn=None, module_name=None, search_filter=None, sizelimit=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when the search results in more objects than specified by the sizelimit.

exception univention.udm.exceptions.MultipleObjects(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when more than one UDM object was found when there should be at most one.

exception univention.udm.exceptions.UnknownModuleType(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when an LDAP object has no or empty attribute univentionObjectType.

exception univention.udm.exceptions.UnknownProperty(msg=None, dn=None, module_name=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when a client tries to set a property on BaseObject.props, that it does not support.

exception univention.udm.exceptions.WrongObjectType(msg=None, dn=None, module_name=None, univention_object_type=None)[source]

Bases: univention.udm.exceptions.UdmError

Raised when the LDAP object to be loaded does not match the module type (BaseModule.name).

univention.udm.helpers module

univention.udm.helpers.get_all_udm_module_names()[source]

Get the names of all installed UDM modules.

Returns

list with UDM module names

Return type

list(str)

univention.udm.plugins module

class univention.udm.plugins.Plugin(name, bases, attrs)[source]

Bases: type

Meta class for plugins.

class univention.udm.plugins.Plugins(python_path)[source]

Bases: object

Register Plugin subclasses and iterate over them.

Parameters

python_path (str) – fully dotted Python path that the plugins will be found below

classmethod add_plugin(plugin)[source]

Called by Plugin meta class to register a new Plugin subclass.

Parameters

plugin (type) – a Plugin subclass

load()[source]

Load plugins.

univention.udm.udm module

Univention Directory Manager Modules (UDM) API

This is a simplified API for accessing UDM objects. It consists of UDM modules and UDM object. UDM modules are factories for UDM objects. UDM objects manipulate LDAP objects.

The UDM class is a LDAP connection and UDM module factory.

Usage:

from univention.udm import UDM

user_mod = UDM.admin().version(2).get('users/user')

or:

user_mod = UDM.machine().version(2).get('users/user')

or:

user_mod = UDM.credentials('myuser', 's3cr3t').version(2).get('users/user')

obj = user_mod.get(dn)
obj.props.firstname = 'foo'  # modify property
obj.position = 'cn=users,cn=example,dc=com'  # move LDAP object
obj.save()  # apply changes

obj = user_mod.get(dn)
obj.delete()

obj = user_mod.new()
obj.props.username = 'bar'
obj.props.lastname = 'baz'
obj.props.password = 'v3r7s3cr3t'
obj.props.unixhome = '/home/bar'
obj.save()

for obj in user_mod.search('uid=a*'):  # search() returns a generator
        print(obj.props.firstname, obj.props.lastname)

A shortcut exists to get UDM objects directly, without knowing their univention object type:

UDM.admin().version(2).obj_by_dn(dn)

A shortcut exists to get UDM objects directly, knowing their univention object type, but without knowing their DN:

UDM.admin().version(2).get('groups/group').get_by_id('Domain Users')

The API is versioned. A fixed version must be hard coded in your code. Supply it as argument to the UDM module factory or via version():

UDM(lo, 0)              # use API version 0 and an existing LDAP connection object
    UDM.admin().version(1)  # use API version 1
    UDM.credentials('myuser', 's3cr3t').version(2).obj_by_dn(dn)  # get object using API version 2
  • Version 0: values of UDM properties are the same as with the low level UDM API: mostly strings.

  • Version 1: values of (most) UDM properties are de/encoded to useful Python types (e.g. “0” -> 0 or False)

  • Version 2: an encoder for settings/portal_category properties was added.

The LDAP connection to use must be supplies as an argument to the UDM module factory or set via admin(), machine(), or credentials():

UDM(lo)        # use an already existing uldap connection object
UDM.admin()    # cn=admin connection
UDM.machine()  # machine connection
UDM.credentials(identity, password, base=None, server=None, port=None)  # custom connection,
    # `identity` is either a username or a DN. LDAP base, server FQDN/IP and port are optional.
    # If it is a username, a machine connection is used to retrieve the DN it belongs to.
class univention.udm.udm.UDM(connection, api_version=None)[source]

Bases: object

Dynamic factory for creating BaseModule objects:

group_mod = UDM.admin().version(2).get('groups/group')
folder_mod = UDM.machine().version(2).get('mail/folder')
user_mod = UDM.credentials('myuser', 's3cr3t').version(2).get('users/user')

A shortcut exists to get UDM objects directly:

UDM.admin().version(2).obj_by_dn(dn)

Use the provided connection.

Parameters
  • connection – Any connection object (e.g., univention.admin.uldap.access)

  • api_version (int) – load only UDM modules that support the specified version, can be set later using version().

Returns

None

Return type

None

classmethod admin()[source]

Use a cn=admin connection.

Returns

a univention.udm.udm.UDM instance

Return type

univention.udm.udm.UDM

Raises

univention.udm.exceptions.ConnectionError – Non-Primary systems, server down, etc.

classmethod machine()[source]

Use a machine connection.

Returns

a univention.udm.udm.UDM instance

Return type

univention.udm.udm.UDM

Raises

univention.udm.exceptions.ConnectionError – File permissions, server down, etc.

classmethod credentials(identity, password, base=None, server=None, port=None)[source]

Use the provided credentials to open an LDAP connection.

identity must be either a username or a DN. If it is a username, a machine connection is used to retrieve the DN it belongs to.

Parameters
  • identity (str) – username or user dn to use for LDAP connection

  • password (str) – password of user / DN to use for LDAP connection

  • base (str) – optional search base

  • server (str) – optional LDAP server address as FQDN

  • port (int) – optional LDAP server port

Returns

a univention.udm.udm.UDM instance

Return type

univention.udm.udm.UDM

Raises

univention.udm.exceptions.ConnectionError – Invalid credentials, server down, etc.

version(api_version)[source]

Set the version of the API that the UDM modules must support.

Use in a chain of methods to get a UDM module:

UDM.get_admin().version(2).get('groups/group')
Parameters

api_version (int) – load only UDM modules that support the specified version

Returns

self (the univention.udm.udm.UDM instance)

Return type

univention.udm.udm.UDM

Raises

univention.udm.exceptions.ApiVersionMustNotChange – if called twice

get(name)[source]

Get an object of BaseModule (or of a subclass) for UDM module name.

Parameters

name (str) – UDM module name (e.g. users/user)

Returns

object of a subclass of BaseModule

Return type

BaseModule

Raises
obj_by_dn(dn)[source]

Try to load an UDM object from LDAP. Guess the required UDM module from the univentionObjectType LDAP attribute of the LDAP object.

Parameters

dn (str) – DN of the object to load

Returns

object of a subclass of BaseObject

Return type

BaseObject

Raises
property api_version

univention.udm.utils module

class univention.udm.utils.UDebug[source]

Bases: object

univention.debug convenience wrapper

target = 10
level2str = {0: 'ERROR', 1: 'WARN', 2: 'INFO', 3: 'INFO', 4: 'DEBUG'}
classmethod all(msg)[source]

Write a debug message with level ALL (as in DEBUG)

classmethod debug(msg)

Write a debug message with level ALL (as in DEBUG)

classmethod error(msg)[source]

Write a debug message with level ERROR

classmethod info(msg)[source]

Write a debug message with level INFO

classmethod process(msg)[source]

Write a debug message with level PROCESS

classmethod warn(msg)[source]

Write a debug message with level WARN

classmethod warning(msg)

Write a debug message with level WARN