UCS-test API

From Univention Wiki

Jump to: navigation, search

UCS-test UDM API

Introduction

The Application Programmer’s Interface to UCS-test UDM gives python programmers an access wrapper to Univention Directory Manager CLI to simplify creation/modification of UDM objects. The wrapper is also able to automatically remove created objects during wrapper destruction.

Warnings:

  • The API currently allows:
    • the creation of new object
    • the modification of objects created by the wrapper itself
    • the deletion of objects created by the wrapper itself.
  • Not all UDM object types are currently supported.
  • The API is still under development and may/will change!

Usability

This module contains only one class which wraps the implemented functionality of UCS-test UDM module in public methods:

class UCSTestUDM(object):

It supports the following UDM actions:

  • create: Create a new object
  • modify: Modify an existing object
  • remove: Remove an existing object
  • move: Move object in directory tree

If a instance of this class is used via the python with-statement, the wrapper class automatically tries to clean up when leaving the corresponding with block. Objects created by the wrapper class will be automatically removed. Please note, that it is not possible to restore the original state of the LDAP directory. So some internal counters (like next free IP address) are not restored.

Creating new LDAP object

Wrapper method for udm create.

def create_object(modulename, wait_for_replication=True, **kwargs)

This method creates a LDAP object via UDM. For simplicity values for UDM properties can be passed via keyword arguments only and have to exactly match UDM options or property names (case-sensitive!).

  • modulename: name of UDM module (e.g. 'users/user', 'groups/group', ...)
  • kwargs: contains the UDM CLI arguments. The UDM CLI option names have to be set as dictionary key (see example below).
    • The following UDM options are currently supported as keyword arguments:
      • binddn: bind DN
      • bindpwd: bind password
      • bindpwdfile: file containing bind password
      • position: Set position in tree
      • set: Set variable to value, e.g. foo=bar
      • superordinate: Use superordinate module
      • policy_reference: Reference to policy given by DN
  • Return value: DN of the newly created LDAP object.
Usage example to create a new user with random data
#!/usr/share/ucs-test/runner python2.7
import univention.testing.strings as uts
import univention.testing.udm as udm_test
import univention.testing.ucr as ucr_test
with udm_test.UCSTestUDM() as udm:
	with ucr_test.UCSTestConfigRegistry() as ucr:
		userdn = udm.create_object(
			'users/user',
			binddn='uid=Administrator,cn=users,%s' % ucr.get('ldap/base'),
			bindpwd='univention',
			position='cn=users,%s' % ucr.get('ldap/base'),
			set={
				'username': uts.random_name(),
				'password':uts.random_string(),
				'lastname':uts.random_name(),
				'userexpiry': '2014-11-25'
				},
			options={}
			)

# or parameters can be passed simply like this:
with udm_test.UCSTestUDM() as udm:
	with ucr_test.UCSTestConfigRegistry() as ucr:
		userdn = udm.create_object(
			'users/user',
			binddn='uid=Administrator,cn=users,%s' % ucr.get('ldap/base'),
			bindpwd='univention',
			position='cn=users,%s' % ucr.get('ldap/base'),
			username=uts.random_name(),
			lastname=uts.random_name(),
			password=uts.random_string(),
			phone=['00494219999999999', '00494219999999988']
		)

Modifying an existing LDAP object

Wrapper method for udm modify:

def modify_object(self, modulename, wait_for_replication = True, **kwargs):

Modifies a LDAP object via UDM. Values for UDM properties can be passed via keyword arguments only and have to exactly match UDM options or property names (case-sensitive!). Please note: the object has to be created by the method create_object otherwise this call will raise an exception!

  • modulename: name of UDM module (e.g. 'users/user', 'groups/group', ...)
  • kwargs: contains the UDM CLI arguments. The UDM CLI option names have to be set as dictionary key (see example below).
    • The following UDM options are currently supported as keyword arguments:
      • dn: DN of the object to be modified
      • binddn: bind DN
      • bindpwd: bind password
      • bindpwdfile: file containing bind password
      • set: Set variable to value, e.g. foo=bar
      • append: Append value to variable, e.g. foo=bar
      • remove: Remove value from variable, e.g. foo=bar
      • option Use only given module options
      • superordinate: Use superordinate module
      • policy_reference: Reference to policy given by DN
      • policy_dereference: Remove reference to policy given by DN
  • Return value: DN of the modified LDAP object.
Usage example to change the last name of a user to NEW_LASTNAME, and remove its first name
import univention.testing.udm as udm_test
with udm_test.UCSTestUDM() as udm:
	# Note: create user object via UCSTestUDM before calling modify_object()
	userdn = udm.modify_object(
		'users/user',
		dn=userdn,
		set={	                     # or just lastname=NEW_LASTNAME,
			'lastname': NEW_LASTNAME,
		},
		remove={
			'firstname': [FIRSTNAME]
		}
		)

Move an existing LDAP object in the directory tree

Wrapper method for udm move:

def move_object(self, modulename, wait_for_replication = True, **kwargs):
  • modulename: name of UDM module (e.g. 'users/user', 'groups/group', ...)
  • kwargs: contains the UDM CLI arguments. The UDM CLI option names have to be set as dictionary key (see example below).
    • The following UDM options are currently supported as keyword arguments:
      • dn: Move object with DN
      • binddn: bind DN
      • bindpwd: bind password
      • bindpwdfile: file containing bind password
      • position: Move to position in tree
  • Return value: None if successful, otherwise the method will raise an exception.
Usage example to move a GROUP_NAME to NEW_POSITION
import univention.testing.udm as udm_test
with udm_test.UCSTestUDM() as udm:
	# Note: create group object via UCSTestUDM before calling move_object()
	userdn = udm.move_object(
		'groups/group',
		dn=groupdn,
		position=NEW_POSITION,
	)

Remove an existing LDAP object from the directory tree

Wrapper Method for udm remove:

def remove_object(self, modulename, wait_for_replication = True, **kwargs):
  • modulename: name of UDM module (e.g. 'users/user', 'groups/group', ...)
  • kwargs: contains the UDM CLI arguments. The UDM CLI option names have to be set as dictionary key (see example below).
    • The following UDM options are currently supported as keyword arguments:
      • dn: DN of the object to be removed
      • binddn: bind DN
      • bindpwd: bind password
      • bindpwdfile: file containing bind password
      • superordinate: Use superordinate module
      • remove_referring: remove referring objects
  • Return value: None if successful, otherwise the method will raise an exception.
Usage example to move a GROUP_NAME to NEW_POSITION
import univention.testing.udm as udm_test
with udm_test.UCSTestUDM() as udm:
	userdn = udm.remove_object(
		'users/user',
		dn=userdn
	)

Create User

This represent a special case of create_object where modulename='users/user':

def create_user(self, wait_for_replication = True, **kwargs):

Creates a user via UDM CLI. Values for UDM properties can be passed via keyword arguments only and have to exactly match UDM property names (case-sensitive!). Some properties have default values:

  • position:: 'cn=users,$ldap_base'
  • username:: <random string>
  • password:: 'univention'
  • firstname:: <random string>
  • lastname:: <random string>

If username is not specified, a random user name will be used.

Return value: a tuple: (dn, username)

Usage example to create new user with random data
import univention.testing.udm as udm_test
with udm_test.UCSTestUDM() as udm:
	userdn, username = udm.create_user()

Create Group

This represent a special case of create_object where modulename='groups/group':

def create_group(self, wait_for_replication = True, *	*kwargs):

Creates a group via UDM CLI. Values for UDM properties can be passed via keyword arguments only and have to exactly match UDM property names (case-sensitive!). Some properties have default values:

  • position: 'cn=users,$ldap_base'
  • name: <random string>

If "groupname" is missing, a random group name will be used.

Return value: (dn, groupname)

Usage example to create new empty group with random data
import univention.testing.udm as udm_test
with udm_test.UCSTestUDM() as udm:
	dn, groupname = udm.create_group()

Cleanup

Automatically removes LDAP objects via UDM CLI that have been created before using this module.

def cleanup(self):

Return Value: None, just prints the message: 'UCSTestUDM cleanup done' if successful.

Usage example to create new user and group then cleanup every thing without "with" statement
import univention.testing.udm as udm_test
udm = udm_test.UCSTestUDM()
userdn, username = udm.create_user()
dn, groupname = udm.create_group()
udm.cleanup()

Restart UDM CLI server

This restarts the UDM CLI server. Mainly it just stops it, and it is automatically started when any cli command is sent.

def stop_cli_server(self):

Return Value: None, just prints some declaration messages.

Usage example to create new user and group then cleanup every thing without "with" statement
import univention.testing.udm as udm_test
udm = udm_test.UCSTestUDM()
udm.stop_cli_server()

Add clean up lock

Used to add more values to the _cleanupLocks items {lock_type:[values]} to be removed when the cleanup is called or after exiting the "with" statement.

def addCleanupLock(self, lockType, lockValue):
Usage example to add new cleanup locks
import univention.testing.udm as udm_test
udm = udm_test.UCSTestUDM()
udm.addCleanupLock('mac', '01:23:45:67:89:ab')
udm.addCleanupLock('mac', ldap.getAttr(computer_DN, 'macAddress')[0])
udm.addCleanupLock('sid', computer_sambaSID)
Personal tools