UCS is based on the Debian distribution, which is using the deb format to package software. The program dpkg is used for handling a set of packages. On installation packages are unpacked and configured, while on un-installation packages are de-configured and the files belonging to the packages are removed from the system. On top of that the apt-tools provide a software repository, which allows software to be downloaded from central file servers. Package files provide an index of all packages contained in the repository, which is used to resolve dependencies between packages: while dpkg works on a set of packages given on the command line, apt-get builds that set of packages and their dependencies before invoking dpkg on this set. apt-get is a command line tool, which is fully described in its manual page apt-get(8). A more modern version with a text based user interface is aptitude, while synaptic provides a graphical frontend.

On UCS systems the administrator is not supposed to use these tools directly. Instead all software maintenance can be done through the UMC, which maps the requests to invocations of the commands given above.

This chapter describes some simple examples using existing packages as examples. For downloading and building them, two packages must be installed on the system used as a development system. subversion is used to checkout the source files belonging to the packages. build-essential must be installed for building the package.

This can be achieved by running the following command as user root:

apt-get install subversion build-essential

Source code: http://forge.univention.org/svn/dev/branches/ucs-4.0/ucs-4.0-0/doc/developer-reference/packaging/testdeb/

The following example provides a walk-through for packaging a Python script called testdeb.py. It creates a file testdeb-DATE-time in the /tmp/ directory.

A directory needs to be crated for each source package, which hosts all other files and sub-directories.

mkdir testdeb-0.1
cd testdeb-0.1

The file testdeb.py, which is the program to be installed, will be put into that directory.

#!/usr/bin/env python
"""
Example for creating UCS packages.
"""
import time

now = time.localtime()
filename = '/tmp/testdeb-%s' % time.strftime('%y%m%d%H%M', now)
tmpfile = open(filename, 'a')
tmpfile.close()

In addition to the files to be installed some meta-data needs to be created in the debian/ sub-directory. This directory contains several files, which are needed to build a Debian package. The files and their format will be described in the following sections.

To create an initial debian/ directory with all template files, invoke the dh_make(8) command provided by the dh-make packet:

dh_make --native --single --email user@example.com

Here several options are given to create the files for a source package, which contains all files in one archive and only creates one binary package at the end of the build process. More details are given in Section B.2.

The program will output the following information:

Maintainer name  : John Doe
Email-Address    : user@example.com
Date             : Thu, 28 Feb 2013 08:11:30 +0100
Package Name     : testdeb
Version          : 0.1
License          : blank
Type of Package  : Single
Hit <enter> to confirm:

The package name testdeb and version “0.1” were determined from the name of the directory testdeb-0.1, the maintainer name and address were gathered from the UNIX account information.

After pressing the enter key some warning message will be shown:

Currently there is no top level Makefile. This may require additional
tuning. Done. Please edit the files in the debian/ subdirectory now.
You should also check that the testdeb Makefiles install into $DESTDIR
and not in / .

Since this example is created from scratch, the missing Makefile is normal and this warning can be ignored. Instead of writing a Makefile to install the single executable, dh_install will be used later to install the file.

Since the command completed successfully, several files were created in the debian/ directory. Most of them are template files, which are unused in this example. To improve understandability they are deleted:

rm debian/*.ex debian/*.EX
rm debian/README* debian/doc

The remaining files are required and control the build process of all binary packages. Most of them don't need to be modified for this example, but others must be completed using an editor.

Now the package is ready and can be built by invoking the following command:

dpkg-buildpackage -us -uc

The command should then produce the following output:

dpkg-buildpackage: source package testdeb
dpkg-buildpackage: source version 0.1-1
dpkg-buildpackage: source changed by John Doe <user@example.com>
dpkg-buildpackage: host architecture amd64
 dpkg-source --before-build testdeb
 fakeroot debian/rules clean
dh clean
   dh_testdir
   dh_auto_clean
   dh_clean
 dpkg-source -b testdeb
dpkg-source: Information: Quellformat »3.0 (native)« wird verwendet
dpkg-source: Information: testdeb wird in testdeb_0.1-1.tar.gz gebaut
dpkg-source: Information: testdeb wird in testdeb_0.1-1.dsc gebaut
 debian/rules build
dh build
   dh_testdir
   dh_auto_configure
   dh_auto_build
   dh_auto_test
 fakeroot debian/rules binary
dh binary
   dh_testroot
   dh_prep
   dh_installdirs
   dh_auto_install
   dh_install
   dh_installdocs
   dh_installchangelogs
   dh_installexamples
   dh_installman
   dh_installcatalogs
   dh_installcron
   dh_installdebconf
   dh_installemacsen
   dh_installifupdown
   dh_installinfo
   dh_pysupport
dh_pysupport: This program is deprecated, you should use dh_python2 instead. Migration guide: http://deb.li/dhs2p
   dh_installinit
   dh_installmenu
   dh_installmime
   dh_installmodules
   dh_installlogcheck
   dh_installlogrotate
   dh_installpam
   dh_installppp
   dh_installudev
   dh_installwm
   dh_installxfonts
   dh_installgsettings
   dh_bugfiles
   dh_ucf
   dh_lintian
   dh_gconf
   dh_icons
   dh_perl
   dh_usrlocal
   dh_link
   dh_compress
   dh_fixperms
   dh_installdeb
   dh_gencontrol
   dh_md5sums
   dh_builddeb
dpkg-deb: building package `testdeb' in `../testdeb_0.1-1_all.deb'.
 dpkg-genchanges -b >../testdeb_0.1-1_amd64.changes
dpkg-genchanges: binary-only upload - not including any source code
 dpkg-source --after-build testdeb
dpkg-buildpackage: full upload; Debian-native package (full source is included)

The binary package file testdeb_0.1-1_all.deb is stored in the parent directory. When it is installed manually using dpkg -i ../testdeb_0.1-2_all.deb as root, the Python script is installed as /usr/bin/testdeb.py. It is automatically invoked by the postint script, so a file named /tmp/testdeb-date-time has been created, too.

Congratulations! You've successfully built your first own Debian package.

Until now the binary package is only available locally, thus for installation it needs to be copied manually to each host and must be installed manually using dpkg -i. If the package required additional dependencies, the installation process will abort, since packages are not downloaded by dpkg, but by apt. To support automatic installation and dependency resolution, the package must be put into an apt repository, which needs to be made available through http or some other mechanism.

For this example the repository is created below /var/www/repository/, which is exported by default on all UCS systems, where apache2 is installed. Below that directory several other sub-directories and files must be created to be compatible with the UCS Updater. The following example commands create a repository for UCS version 3.1 with the component name testcomp:

WWW_BASE="/var/www/repository/4.0/maintained/component"
TESTCOMP="testcomp/all"
install -m755 -d "$WWW_BASE/$TESTCOMP"
install -m644 -t "$WWW_BASE/$TESTCOMP" *.deb
( cd "$WWW_BASE" &&
  rm -f "$TESTCOMP/Packages"* &&
  apt-ftparchive packages "$TESTCOMP" > "Packages" &&
  gzip -9 < "Packages" > "$TESTCOMP/Packages.gz" &&
  mv "Packages" "$TESTCOMP/Packages" )

This repository can be included on any UCS system by appending the following line to /etc/apt/sources.list, assuming the FQDN of the host providing the repository is named repository.server:

deb http://repository.server/repository/4.0/maintained/component testcomp/all/

Instead of editing the sources.list file directly, the repository can also be included as a component, which can be configured by setting several UCR variables. As UCR variables can also be configured through UDM policies, this simplifies the task of installing packages from such a repository on may hosts. For the repository above the following variables need to be set:

ucr set \
	repository/online/component/testcomp=yes \
	repository/online/component/testcomp/server=repository.server \
	repository/online/component/testcomp/prefix=repository

The openSUSE Build Service (OBS) is a framework to generate packages for a wide range of distributions. Additional information can be found at https://build.opensuse.org/. If OBS is already used to build packages for other distributions, it can also be used for Univention Corporate Server builds. The build target for UCS 4.0 is called Univention UCS 4.0. Note that OBS doesn't handle the integration steps described in later chapters (e.g. the use of Univention Configuration Registry templates).

Univention Configuration Registry provides two interfaces, which allows easy access from shell scripts and Python programs.

from univention.config_registry import ConfigRegistry
ucr = ConfigRegistry()
ucr.load()
print ucr['variable/name']
print ucr.get('variable/name', '<not set>')

if ucr.is_true('repository/online/unmaintained'):
	print "unmaintained is explicitly enabled"
if ucr.is_true('repository/online/unmaintained', True):
	print "unmaintained is enabled"
if ucr.is_false('repository/online/unmaintained'):
	print "unmaintained is explicitly disabled"
if ucr.is_false('repository/online/unmaintained', True):
	print "unmaintained is disabled"

from univention.config_registry.frontend import ucr_update
ucr_update(ucr, {
	'foo': 'bar',
	'baz': '42',
	'bar': None,
	})

from univention.config_registry import handler_set, handler_unset
handler_set(['foo=bar', 'baz?42'])
handler_unset(['foo', 'bar'])

Packages can use the UCR functionality to create customized configuration files themselves. UCR diverts files shipped by Debian packages and replaces them by generated files. If variables are changed, the affected files are committed, which regenerated their content. This diversion is persistent and even outlives updates, so they are not overwritten by configuration files of new packages.

For this, packages need to ship additional files:

In addition to these files code needs to be inserted into the package maintainer scripts (see Section B.3.5), which registers and unregisters these files. This is done by calling univention-install-config-registry from debian/rules during the package build binary phase. The command is part of the univention-config-dev package, which needs to be added as a Build-Depends build dependency of the source package in debian/control.

Type: <type>
[Multifile|File]: <filename>
[Subfile: <fragment-filename>]
Variables: <variable1>
...

Type: file
File: <filename>
Variables: <variable1>
User: <owner>
Group: <group>
Mode: <file-mode>
Preinst: <module>
Postinst: <module>
...

Type: multifile
Multifile: <target-filename>
User: <owner>
Group: <group>
Mode: <file-mode>
Preinst: <module>
Postinst: <module>
Variables: <variable1>

Type: subfile
Multifile: <target-filename>
Subfile: <fragment-filename>
Variables: <variable1>
...

Type: script
Script: <filename>
Variables: <variable1>

Type: module
Module: <filename>
Variables: <variable1>

[<variable/name>]
Description[en]=<description>
Description[<language>]=<description>
Type=<type>
ReadOnly=<yes|no>
Categories=<category,...>

[<category-name>]
name[en]=<name>
name[<language>]=<translated-name>
icon=<file-name>

[<service-name>]
description[<language>]=<description>
start_type=<service-name>/autostart
icon=<service/icon_name>
programs=<executable>

For each file, which should be written, one or more template files need be to created below the conffiles/ directory. For a single-File template (see Section 2.2.1.1), the filename must match the filename given in the File: stanza of the file entry itself. For a Multifile template (see Section 2.2.1.2), the filename must match the filename given in the File: stanza of the subfile entries.

Each template file is normally a text file, where certain sections get substituted by computed values during the file commit. Each section starts and ends with a special marker. UCR currently supports the following kinds of markers:

During package build time univention-install-config-registry needs to be called. This should be done by overriding the dh_auto_install_target in debian/rules:

override_dh_auto_install:
	univention-install-config-registry
	dh_auto_install

This invocation copies the referenced files to the right location in the binary package staging area debian/package/etc/univention/. Internally univention-install-config-registry-info and univention-install-service-info are invoked, which should not be called explicitly anymore. The calls also insert code into the files debian/package.preinst.subst, debian/package.postinst.subst and debian/package.postrm.subst to register and un-register the templates. Therefore it's important that customized maintainer scripts use the #DEBHELPER# marker, so that the generated code gets inserted into the corresponding preinst, postinst and postrm files of the generated binary package.

The invocation also adds univention-config to misc:Depends to ensure that the package is available during package configuration time. Therefore it's important that ${misc:Depends} is used in the Depends line of the package section in the debian/control file.

Package: ...
Depends: ..., ${misc:Depends}, ...

This sections contains several simple examples for the use of Univention Configuration Registry. The complete source of these examples is available separately. The download location is given in each example below. Since almost all Univention Corporate Server packages use UCR, their source code provides additional examples.

Packages requiring write access to the Univention directory service can provide so called join scripts. They are installed into /usr/lib/univention-install/. The name of each join script is normally derived from the name of the binary package containing it. It is prefixed with a two-digit number, which is used to order the scripts lexicographically. The filename either ends in .inst or .uinst, which distinguishes between join script and unjoin script (see Section 3.5). The file must have the executable permission bits set.

For each join script a version number is tracked. This is used to skip re-executing join scripts, which already have been executed. This is mostly a performance optimization, but is also used to find join scripts which need to be run.

The text file /var/univention-join/status is used to keep track of the state of all join scripts. For each successful run of a join script a line is appended to that file. That record consists of three space separated entries:

$script_name v$version successful

If a new version of the join script is invoked, it just appends a new record with a higher version number at the end of the file.

There exist three commands related to running join scripts:

When packages are installed, it depends on the server role, if join scripts are invoked automatically from the postinst Debian maintainer script or not. This only happens on master and backup domain controller system roles, where the local root user has access to the file containing the LDAP credentials. On all other system roles the join scripts need to be run manually by invoking univention-run-join-scripts or doing so through UMC.

Similar to the Debian maintainer scripts (see Section B.3.5) they should be idem-potent: They should transform the system from any state into the state required by the package, that is:

Join scripts may be called from multiple system roles and different versions. Therefore it is important that these scripts do not destroy or remove data still used by other systems!

On package removal packages should clean up the data in Univention directory service. Removing data from LDAP also requires appropriate credentials, while removing a package only requires local root privileges. Therefore UCS provides support for so-called unjoin scripts. In most cases it reverts the changes of a corresponding join script.

Just like join scripts an unjoin script is prefixed with a two-digit number for lexicographical ordering. To reverse the order of the unjoin scripts in comparison to the corresponding join scripts, the number of the unjoin script should be 100 minus the number of the corresponding join script. The suffix of an unjoin script is -uninstall.uinst and it should be installed in /usr/lib/univention-uninstall/.

On package removal the unjoin script would be deleted as well, while the Univention directory service might still contain data managed by the package. Therefore the script must be copied from there to /usr/lib/univention-install/ in the prerm maintainer script.

Example: The package univention-fetchmail provides both a join script /usr/lib/univention-install/91univention-fetchmail.inst and the corresponding unjoin script as /usr/lib/univention-uninstall/09univention-fetchmail-uninstall.uinst.

As of UCS 3.1 .inst and .uinst are not distinguishable in the UMC Join module by the user. Therefore it is important to use the -uninstall suffix to give users a visual hint. Internally join scripts are always executed before unjoin scripts and then ordered lexicographically by their prefix.

To decide if an unjoin script is the last instance and should remove the data from LDAP, a service can be registered for each host where the package is installed.

For example the package univention-fetchmail uses ucs_addServiceFromLocalhost "Fetchmail" "$@" in the join script to register and ucs_removeServiceFromLocalhost "Fetchmail" "$@" in the unjoin script to unregister a service for the host. The data is removed from LDAP when in the unjoin script ucs_isServiceUnused "Fetchmail" "$@" returns 0. As a side effect adding the service also allows using this information to find and list those servers currently providing the Fetchmail service.

An LDAP server provides authenticated and controlled access to directory objects over the network. LDAP objects consist of a collection of attributes which conform to so called LDAP schemata. An in depth documentation of LDAP is beyond the scope of this document, other sources cover this topic exhaustively, e.g. http://www.zytrax.com/books/ldap/ or the man pages (slapd.conf, slapd.access).

At least it should be noted that OpenLDAP offers two fundamentally different tool sets for direct access or modification of LDAP data: The slap* commands (slapcat, etc.) are very low level, operating directly on the LDAP backend data and should only be used in rare cases, usually with the LDAP server not running. The ldap* commands (ldapsearch, etc.) on the other hand are the proper way to perform LDAP operations from the command line and their functionality can equivalently be used from all major programming languages.

On top of the raw LDAP layer, the Univention Directory Manager offers an object model on a higher level, featuring advanced object semantics (see Chapter 6). That is the level that usually appropriate for app developers, which should be considered before venturing down to the level of direct LDAP operations. On the other hand, for the development of new UDM extensions it is important to understand some of the essential concepts of LDAP as used in UCS.

One essential trait of LDAP as used in UCS, is the strict enforcement of LDAP schemata. An LDAP server refuses to start if an unknown LDAP attribute is referenced either in the configuration or in the backend data. This makes it critically important to install schemata on all systems. To simplify this task UCS features a builtin mechanism for automatic schema replication to all UCS hosted LDAP servers in the UCS domain (see Chapter 5). The schema replication mechanism is triggered by installation of a new schema extension package on the UCS master. For redundancy it is strongly recommended to install schema extension packages also on the UCS backup systems. This way, a UCS backup can replace a UCS master in case the master needs to be replaced for some reason. To simplify these tasks even further, UCS offers methods to register new LDAP schemata and associated LDAP ACLs from any UCS system.

For some purposes, e.g. for app installation, it is convenient to be able to register a new LDAP schema extension from any system in the UCS domain. For this purpose, the schema extension can be stored as a special type of UDM object. The module responsible for this type of objects is called settings/ldapschema. As these objects are replicated throughout the UCS domain, the master domain controller and backup domain controller systems listen for modifications of these objects and integrate them into the local LDAP schema directory. As noted above, this simplifies the task of keeping the schema on the backup domain controller systems up to date with that on the master domain controller.

The commands to create the LDAP schema extension objects in UDM may be put into any join script (see Chapter 3). A LDAP schema extension object is created by using the UDM command line interface univention-directory-manager or its alias udm. LDAP schema extension objects can be stored anywhere in the LDAP directory, but the recommended location would be cn=ldapschema,cn=univention, below the LDAP base. Since the join script creating the attribute may be called on multiple hosts, it is a good idea to add the --ignore_exists option, which suppresses the error exit code in case the object already exists in LDAP.

The UDM module settings/ldapschema requires several parameters:

Since many of these parameters are determined automatically by the ucs_registerLDAPExtension shell library function, it is recommended to use the shell library function to create these objects (see Section 9.10.1).

export UNIVENTION_APP_IDENTIFIER="appID-appVersion"	## example
. /usr/share/univention-lib/ldap.sh

ucs_registerLDAPExtension "$@" \
  --schema /path/to/appschemaextension.schema

For some purposes, e.g. for app installation, it is convenient to be able to register a new LDAP ACL extension from any system in the UCS domain. For this purpose, the UCR template for an ACL extension can be stored as a special type of UDM object. The module responsible for this type of objects is called settings/ldapacl. As these objects are replicated throughout the UCS domain, the master domain controller, backup domain controller and slave domain controller systems listen for modifications on these objects and integrate them into the local LDAP ACL UCR template directory. This simplifies the task of keeping the LDAP ACLs on the backup domain controller systems up to date with those on the master domain controller.

The commands to create the LDAP ACL extension objects in UDM may be put into any join script (see Chapter 3). A LDAP ACL extension object is created by using the UDM command line interface univention-directory-manager or its alias udm. LDAP ACL extension objects can be stored anywhere in the LDAP directory, but the recommended location would be cn=ldapacl,cn=univention, below the LDAP base. Since the join script creating the attribute may be called on multiple hosts, it is a good idea to add the --ignore_exists option, which suppresses the error exit code in case the object already exists in LDAP.

The UDM module settings/ldapacl requires several parameters:

Since many of these parameters are determined automatically by the ucs_registerLDAPExtension shell library function, it is recommended to use the shell library function to create these objects (see Section 9.10.1).

export UNIVENTION_APP_IDENTIFIER="appID-appVersion"	## example
. /usr/share/univention-lib/ldap.sh

ucs_registerLDAPExtension "$@" \
  --acl /path/to/appaclextension.acl

The credentials for different UCS domain accounts are stored in plain-text files on some UCS systems. The files are named /etc/*.secret. They are owned by the user root and allow read-access for different groups.

During package installation, only the maintainer scripts (see Section B.3.5) on master and backup domain controller can use their root permission to directly read /etc/ldap.secret. Thus only on those roles the join scripts get automatically executed when the package is installed. On all other system roles, the join scripts need to be executed manually. This can either be done through the UMC Join module or through the command line tool univention-run-join-scripts. Both methods require appropriate credentials.

#!/bin/sh
case "$1" in
prechange)
	# nothing to do before the password is changed
	exit 0
	;;
nochange)
	# nothing to do after a failed password change
	exit 0
	;;
postchange)
	# restart daemon after password was changed
	invoke-rc.d my-daemon restart
	;;
esac

Each listener module must declare several string constants. They are required by the Univention Directory Listener to handle each module. They should be defined at the beginning of the module.

name = "module_name"
description = "Module description"
filter = "(objectClass=*)"
attribute = ["objectClass"]
modrdn = "1"

In addition to the static strings a module must implement several functions. They are called in different situations of the live-cycle of the module.

def initialize(): pass
def handler(dn, new, old[, command='']): pass
def clean(): pass
def prerun(): pass
def postrun(): pass
def setdata(key, value): pass

All changes trigger a call to the function handle(). For simplicity and readability it is advisable to delegate the different change types to different sub-functions.

def handler(dn, new, old):
	if new and not old:
		handler_add(dn, new)
	elif new and old:
		handler_modify(dn, old, new)
	elif not new and old:
		handler_remove(dn, old)
	else:
		pass  # ignore


def handler_add(dn, new):
	"""Handle addition of object."""
	pass  # replace this


def handler_modify(dn, old, new):
	"""Handle modification of object."""
	pass  # replace this


def handler_remove(dn, old):
	"""Handle removal of object."""
	pass  # replace this

modrdn = "1"

_delay = None


def handler(dn, new, old, command):
	global _delay
	if _delay:
		old_dn, old = _delay
		_delay = None
		if "a" == command and old['entryUUID'] == new['entryUUID']:
			handler_move(old_dn, old, dn, new)
			return
		handler_remove(old_dn, old)

	if "n" == command and "cn=Subschema" == dn:
		handler_schema(old, new)
	elif new and not old:
		handler_add(dn, new)
	elif new and old:
		handler_modify(dn, old, new)
	elif not new and old:
		if "r" == command:
			_delay = (dn, old)
		else:
			handler_remove(dn, old)
	else:
		pass  # ignore, reserved for future use


def handler_move(old_dn, old, new_dn, dn):
	"""Handle rename or move of object."""
	pass  # replace this


def handlee_schema(old, new):
	"""Handle change in LDAP schema."""
	pass  # replace this

"""
Example for a listener module, which logs changes to users.
"""
__package__ = ""  # workaround for PEP 366
import listener
import os
import errno
import univention.debug as ud
from collections import namedtuple

name = 'printusers'
description = 'print all names/users/uidNumbers into a file'
filter = """\
(&
	(|
		(&
			(objectClass=posixAccount)
			(objectClass=shadowAccount)
		)
		(objectClass=univentionMail)
		(objectClass=sambaSamAccount)
		(objectClass=simpleSecurityObject)
		(objectClass=inetOrgPerson)
	)
	(!(objectClass=univentionHost))
	(!(uidNumber=0))
	(!(uid=*$))
)""".translate(None, '\t\n\r')
attributes = ['uid', 'uidNumber', 'cn']
_Rec = namedtuple('Rec', ' '.join(attributes))

USER_LIST = '/root/UserList.txt'


def handler(dn, new, old):
	"""
	Write all changes into a text file.
	This function is called on each change.
	"""
	if new and old:
		_handle_change(dn, new, old)
	elif new and not old:
		_handle_add(dn, new)
	elif old and not new:
		_handle_remove(dn, old)


def _handle_change(dn, new, old):
	"""
	Called when an object is modified.
	"""
	o_rec = _rec(old)
	n_rec = _rec(new)
	ud.debug(ud.LISTENER, ud.INFO, 'Edited user "%s"' % (o_rec.uid,))
	_writeit(o_rec, u'edited. Is now:')
	_writeit(n_rec, None)


def _handle_add(dn, new):
	"""
	Called when an object is newly created.
	"""
	n_rec = _rec(new)
	ud.debug(ud.LISTENER, ud.INFO, 'Added user "%s"' % (n_rec.uid,))
	_writeit(n_rec, u'added')


def _handle_remove(dn, old):
	"""
	Called when an previously existing object is removed.
	"""
	o_rec = _rec(old)
	ud.debug(ud.LISTENER, ud.INFO, 'Removed user "%s"' % (o_rec.uid,))
	_writeit(o_rec, u'removed')


def _rec(data):
	"""
	Retrieve symbolic, numeric ID and name from user data.
	"""
	return _Rec(*(data.get(attr, (None,))[0] for attr in attributes))


class AsRoot(object):
	"""
	Temporarily change effective UID to 'root'.
	"""
	def __enter__(self):
		listener.setuid(0)

	def __exit__(self, exc_type, exc_value, traceback):
		listener.unsetuid()


def _writeit(rec, comment):
	"""
	Append CommonName, symbolic and numeric User-IDentifier, and comment to file.
	"""
	nuid = u'*****' if rec.uid in ('root', 'spam') else rec.uidNumber
	indent = '\t' if comment is None else ''
	try:
		with AsRoot():
			with open(USER_LIST, 'a') as out:
				print >> out, u'%sName: "%s"' % (indent, rec.cn)
				print >> out, u'%sUser: "%s"' % (indent, rec.uid)
				print >> out, u'%sUID: "%s"' % (indent, nuid)
				if comment:
					print >> out, u'%s%s' % (indent, comment,)
	except IOError as ex:
		ud.debug(
			ud.LISTENER, ud.ERROR,
			'Failed to write "%s": %s' % (USER_LIST, ex))


def initialize():
	"""
	Remove the log file.
	This function is called when the module is forcefully reset.
	"""
	try:
		with AsRoot():
			os.remove(USER_LIST)
		ud.debug(
			ud.LISTENER, ud.INFO,
			'Successfully deleted "%s"' % (USER_LIST,))
	except OSError as ex:
		if errno.ENOENT == ex.errno:
			ud.debug(
				ud.LISTENER, ud.INFO,
				'File "%s" does not exist, will be created' % (USER_LIST,))
		else:
			ud.debug(
				ud.LISTENER, ud.WARN,
				'Failed to delete file "%s": %s' % (USER_LIST, ex))

__package__ = ""  # workaround for PEP 366
name = "refcheck"
description = "Check referential integrity of uniqueMember relations"
filter = "(uniqueMember=*)"
attribute = ["uniqueMember"]
modrdn = "1"

import os
import ldap
import listener
import univention.debug as ud
from pwd import getpwnam


class LocalLdap(object):
	PORT = 7389

	def __init__(self):
		self.data = {}
		self.con = None

	def setdata(self, key, value):
		self.data[key] = value

	def prerun(self):
		try:
			self.con = ldap.open(self.data["ldapserver"], port=self.PORT)
			self.con.simple_bind_s(self.data["binddn"], self.data["bindpw"])
		except ldap.LDAPError as ex:
			ud.debug(ud.LISTENER, ud.ERROR, str(ex))

	def postrun(self):
		try:
			self.con.unbind()
			self.con = None
		except ldap.LDAPError as ex:
			ud.debug(ud.LISTENER, ud.ERROR, str(ex))


class LocalFile(object):
	USER = "listener"
	LOG = "/var/log/univention/refcheck.log"

	def initialize(self):
		try:
			ent = getpwnam(self.USER)
			with AsRoot():
				open(self.LOG, "wb")
				os.chown(self.LOG, ent.pw_uid, -1)
		except OSError as ex:
			ud.debug(ud.LISTENER, ud.ERROR, str(ex))

	def log(self, msg):
		with open(self.LOG, 'ab') as log:
			print >> log, msg

	def clean(self):
		try:
			with AsRoot():
				os.remove(self.LOG)
		except OSError as ex:
			ud.debug(ud.LISTENER, ud.ERROR, str(ex))


class AsRoot(object):
	"""
	Temporarily change effective UID to 'root'.
	"""
	def __enter__(self):
		listener.setuid(0)

	def __exit__(self, exc_type, exc_value, traceback):
		listener.unsetuid()


class ReferentialIntegrityCheck(LocalLdap, LocalFile):
	MESSAGES = {
		(False, False): "Still invalid: ",
		(False, True): "Now valid: ",
		(True, False): "Now invalid: ",
		(True, True): "Still valid: ",
	}

	def __init__(self):
		super(ReferentialIntegrityCheck, self).__init__()
		self._delay = None

	def handler(self, dn, new, old, command=''):
		if self._delay:
			old_dn, old = self._delay
			self._delay = None
			if "a" == command and old['entryUUID'] == new['entryUUID']:
				self.handler_move(old_dn, old, dn, new)
				return
			self.handler_remove(old_dn, old)

		if "n" == command and "cn=Subschema" == dn:
			self.handler_schema()
		elif new and not old:
			self.handler_add(dn, new)
		elif new and old:
			self.handler_modify(dn, old, new)
		elif not new and old:
			if "r" == command:
				self._delay = (dn, old)
			else:
				self.handler_remove(dn, old)
		else:
			pass  # ignore, reserved for future use

	def handler_add(self, dn, new):
		if not self._validate(new):
			self.log("New invalid object: " + dn)

	def handler_modify(self, dn, old, new):
		valid = (self._validate(old), self._validate(new))
		msg = self.MESSAGES[valid]
		self.log(msg + dn)

	def handler_remove(self, dn, old):
		if not self._validate(old):
			self.log("Removed invalid: " + dn)

	def handler_move(self, old_dn, old, new_dn, new):
		valid = (self._validate(old), self._validate(new))
		msg = self.MESSAGES[valid]
		self.log("%s %s -> %s" % (msg, old_dn, new_dn))

	def handler_schema(self):
		self.log("Schema change")

	def _validate(self, data):
		try:
			for dn in data["uniqueMember"]:
				self.con.search_ext_s(dn, ldap.SCOPE_BASE, attrlist=[], attrsonly=1)
			return True
		except ldap.NO_SUCH_OBJECT:
			return False
		except ldap.LDAPError as ex:
			ud.debug(ud.LISTENER, ud.ERROR, str(ex))
			return False


_instance = ReferentialIntegrityCheck()
initialize = _instance.initialize
handler = _instance.handler
clean = _instance.clean
prerun = _instance.prerun
postrun = _instance.postrun
setdata = _instance.setdata

The command line client udm provides different modes of operation.

Each UDM module provides a set of mappings from LDAP attributes to properties. This set is not complete, because LDAP objects can be extended with additional auxiliary objectClasses Extended Attributes can be used to extend modules to show additional properties. These properties can be mapped to any already defined LDAP attribute, but objects can also be extended by adding additional auxiliary object classes, which can provide new attributes.

For packing purpose any additional LDAP schema needs to be registered on the master domain controller, which is replicated from there to all other Domaincontrollers via the Listener/Notifier mechanism (see Chapter 5). This is best done trough a separate schema package, which should be installed on the master domain controller and backup domain controller. Since Extended Attributes are declared in LDAP, the commands to create them can be put into any join script (see Chapter 3). To be convenient, the declaration should be also included with the schema package, since installing it there does not require the Administrator to provide additional LDAP credentials.

An Extended Attribute is created by using the UDM command line interface univention-directory-manager or its alias udm. The module is called settings/extended_attribute. Extended Attributes can be stored anywhere in the LDAP, but the default location would be cn=custom attributes,cn=univention, below the LDAP base. Since the join script creating the attribute may be called on multiple hosts, it is a good idea to add the --ignore_exists option, which suppresses the error exit code in case the object already exists in LDAP.

The module settings/extended_attribute requires many parameters. They are described in ????.

#objectIdentifier univention 1.3.6.1.4.1.10176
#objectIdentifier univentionCustomers univention:99999
#objectIdentifier univentionExamples univentionCustomers:0
objectIdentifier univentionExamples 1.3.6.1.4.1.10176:99999:0
objectIdentifier univentionExmaplesUdm univentionExamples:1
objectIdentifier univentionExmaplesUdmAttributeType univentionExmaplesUdm:1
objectIdentifier univentionExmaplesUdmObjectClass univentionExmaplesUdm:2

attributetype ( univentionExmaplesUdmAttributeType:1
	NAME 'univentionExamplesUdmAttribute'
	DESC 'An example attribute for UDM'
	EQUALITY caseIgnoreMatch
	SUBSTR caseIgnoreSubstringsMatch
	SYNTAX 1.3.6.1.4.1.1466.115.121.1.15{42}
	SINGLE-VALUE
	)

objectClass ( univentionExmaplesUdmObjectClass:1
	NAME 'univentionExamplesUdmOC'
	DESC 'An example object class for UDM'
	SUP top
	AUXILIARY
	MUST ( univentionExamplesUdmAttribute )
	)

#!/bin/sh

#DEBHELPER#

. /usr/share/univention-lib/base.sh
. /usr/share/univention-lib/ldap.sh

ucs_registerLDAPSchema /usr/share/extended-attribute/extended-attribute.schema

call_joinscript 50extended-attribute.inst

exit 0

#!/bin/bash
VERSION=1
. /usr/share/univention-join/joinscripthelper.lib
joinscript_init

# Register new service entry for this host
eval "$(ucr shell)"
udm settings/extended_attribute create "$@" --ignore_exists \
	--position "cn=custom attributes,cn=univention,$ldap_base" \
	--set name="My Attribute" \
	--set CLIName="myAttribute" \
	--set shortDescription="Example attribute" \
	--set translationShortDescription='"de_DE" "Beispielattribut"' \
	--set longDescription="An example attribute" \
	--set translationLongDescription='"de_DE" "Ein Beispielattribut"' \
	--set tabAdvanced=1 \
	--set tabName="Examples" \
	--set translationTabName='"de_DE" "Beispiele"' \
	--set tabPosition=1 \
	--set module="groups/group" \
	--set module="computers/memberserver" \
	--set syntax=string \
	--set default="Lorem ipsum" \
	--set multivalue=0 \
	--set valueRequired=0 \
	--set mayChange=1 \
	--set doNotSearch=1 \
	--set objectClass=univentionExamplesUdmOC \
	--set ldapMapping=univentionExamplesUdmAttribute \
	--set deleteObjectClass=0
	# --set overwritePosition=
	# --set overwriteTab=
	# --set hook=
	# --set options=

# Terminate UDM server to force module reload
. /usr/share/univention-lib/base.sh
stop_udm_cli_server

joinscript_save_current_version
exit 0

class StaticSelection(select):
	choices = [
		('value1', 'Description for selection 1'),
		('value2', 'Description for selection 2'),
		('value3', 'Description for selection 3'),
	]

class DynamicSelection(UDM_Objects):
	udm_modules = ('container/cn',)
	udm_filter = '(&(objectClass=organizationalRole)(ou:dn:=DynamicSelection))'
	simple = True  # only one value is selected
	empty_value = True  # allow selecting nothing
	key = '%(name)s'  # this is stored
	label = '%(description)s'  # this is displayed
	regex = None  # no validation in frontend
	error_message = 'Invalid value'

syntax='DynamicSelection'
base="cn=univention,$(ucr get ldap/base)"

udm container/ou create --position "$base" \
	--set name="$syntax" --set description='UCS profession level'
dn="ou=$syntax,$base"

udm container/cn create --position "$dn" \
	--set name="value1" --set description='UCS Guru (> 5)'
udm container/cn create --position "$dn" \
	--set name="value2" --set description='UCS Regular (1..5)'
udm container/cn create --position "$dn" \
	--set name="value3" --set description='UCS Beginner (< 1)'

udm container/cn create --ignore_exists --position "$base" \
	--set name='udm_syntax'
dn="cn=udm_syntax,$base"
udm settings/udm_syntax create --position "$dn" \
	--set name="$syntax" --set filename="DynamicSelection.py" \
	--set data="$(bzip2 <DynamicSelection.py | base64)" \
	--set package="$syntax" --set packageversion="1"

udm settings/extended_attribute create --position "cn=custom attributes,$base" \
	--set name='Profession' \
	--set module='users/user' \
	--set tabName='General' \
	--set translationTabName='"de_DE" "Allgemein"' \
	--set groupName='Personal information' \
	--set translationGroupName='"de_DE" "Persönliche Informationen"' \
	--set shortDescription='UCS profession level' \
	--set translationShortDescription='"de_DE" "UCS Erfahrung"' \
	--set longDescription='Select a level of UCS experience' \
	--set translationLongDescription='"de_DE" "Wählen Sie den Level der Erfahrung mit UCS"' \
	--set objectClass='univentionFreeAttributes' \
	--set ldapMapping='univentionFreeAttribute1' \
	--set syntax="$syntax" --set mayChange=1 --set valueRequired=0

eval "$(ucr shell)"
udm settings/extended_options create "$@" --ignore_exists \
	--position "cn=custom attributes,cn=univention,$ldap_base" \
	--set name="My Option" \
	--set shortDescription="Example option" \
	--set translationShortDescription='"de_DE" "Beispieloption"' \
	--set longDescription="An example option" \
	--set translationLongDescription='"de_DE" "Eine Beispieloption"' \
	--set default=0 \
	--set editable=0 \
	--set module="users/user" \
	--set objectClass=univentionExamplesUdmOC

from univention.admin.hook import simpleHook

class RemoveObjClassUnused(simpleHook):
	type = 'RemoveObjClassUnused'

	def hook_ldap_post_modify(self, module):
		"""Remove unused objectClass."""
		ext_attr_name = 'isSampleUser'
		class_name = 'univentionFreeAttributes'

		if module.oldinfo.get(ext_attr_name) in ('1',) and \
				module.info.get(ext_attr_name) in ('0', None):
			if class_name in module.oldattr.get('objectClass', []):
				module.lo.modify(module.dn,
					[('objectClass', class_name, '')])

udm settings/extended_attribute modify \
	--dn ... \
	--set hook=RemoveObjClassUnused

The development of Univention Directory Manager modules is currently only documented in Univention Wiki (currently only available in German): http://wiki.univention.de/index.php?title=Entwicklung_und_Integration_eigener_Module_in_Univention_Directory_Manager

Every UDM property has a syntax, which is used to check the value for correctness. Univention Corporate Server already provides several syntax types, which are defined in the Python file /usr/share/pyshared/univention/admin/syntax.py. The following list of syntaxes is not complete, for a complete overview the file should be consulted directly.

Additional syntax classes can be added by placing a Python file in /usr/share/pyshared/univention/admin/syntax.d/. They're automatically imported by UDM.

For some purposes, e.g. for app installation, it is convenient to be able to deploy a new UDM hook in the UCS domain from any system in the domain. For this purpose, a UDM hook can be stored as a special type of UDM object. The module responsible for this type of objects is called settings/udm_hook. As these objects are replicated throughout the UCS domain, the UCS servers listen for modifications on these objects and integrate them into the local UDM.

The commands to create the UDM hook objects in UDM may be put into any join script (see Chapter 3). Like every UDM object a UDM hook object can be created by using the UDM command line interface univention-directory-manager or its alias udm. UDM hook objects can be stored anywhere in the LDAP directory, but the recommended location would be cn=udm_hook,cn=univention, below the LDAP base. Since the join script creating the attribute may be called on multiple hosts, it is a good idea to add the --ignore_exists option, which suppresses the error exit code in case the object already exists in LDAP.

The module settings/udm_hook requires several parameters. Since many of these are determined automatically by the ucs_registerLDAPExtension shell library function, it is recommended to use the shell library function to create these objects (see Section 9.10.1).

For some purposes, e.g. for app installation, it is convenient to be able to deploy a new UDM module in the UCS domain from any system in the domain. For this purpose, a UDM module can be stored as a special type of UDM object. The module responsible for this type of objects is called settings/udm_module. As these objects are replicated throughout the UCS domain, the UCS servers listen for modifications on these objects and integrate them into the local UDM.

The commands to create the UDM module objects in UDM may be put into any join script (see Chapter 3). Like every UDM object a UDM module object can be created by using the UDM command line interface univention-directory-manager or its alias udm. UDM module objects can be stored anywhere in the LDAP directory, but the recommended location would be cn=udm_module,cn=univention, below the LDAP base. Since the join script creating the attribute may be called on multiple hosts, it is a good idea to add the --ignore_exists option, which suppresses the error exit code in case the object already exists in LDAP.

The module settings/udm_module requires several parameters. Since many of these are determined automatically by the ucs_registerLDAPExtension shell library function, it is recommended to use the shell library function to create these objects (see Section 9.10.1).

For some purposes, e.g. for app installation, it is convenient to be able to deploy a new UDM syntax in the UCS domain from any system in the domain. For this purpose, a UDM syntax can be stored as a special type of UDM object. The module responsible for this type of objects is called settings/udm_syntax. As these objects are replicated throughout the UCS domain, the UCS servers listen for modifications on these objects and integrate them into the local UDM.

The commands to create the UDM syntax objects in UDM may be put into any join script (see Chapter 3). Like every UDM object a UDM syntax object can be created by using the UDM command line interface univention-directory-manager or its alias udm. UDM syntax objects can be stored anywhere in the LDAP directory, but the recommended location would be cn=udm_syntax,cn=univention, below the LDAP base. Since the join script creating the attribute may be called on multiple hosts, it is a good idea to add the --ignore_exists option, which suppresses the error exit code in case the object already exists in LDAP.

The module settings/udm_syntax requires several parameters. Since many of these are determined automatically by the ucs_registerLDAPExtension shell library function, it is recommended to use the shell library function to create these objects (see Section 9.10.1).

Files for building a UMC module.

Module: module-name
Python: umc
Definition: umc/module-name.xml
Javascript: umc
Icons: umc/icons

<?xml version="1.0" encoding="UTF-8"?>
<!--DOCTYPE umc SYSTEM "branches/ucs-4.0/ucs-4.0-0/management/univention-management-console/doc/module.dtd"-->
<umc version="2.0">
	<module id="udm" icon="udm-MODULE" version="1.0" translationId="MODULE">
		<name>...</name>
		<description>...</description>
		<flavor>...</flavor>
		<categories>
			<category name="domain"/>
		</categories>
		<command>...</command>
	</module>
</umc>

<?xml version="1.0" encoding="UTF-8"?>
<umc version="2.0">
	<categories>
		<category id="category" priority="..." icon="....svg" color="#xxxxxx"/>
	</categories>
</umc>

Use umc-create-module to template for custom module. http://wiki.univention.de/index.php?title=UCS_3.0_UMC_API_for_Modules

Done through flavour.

<?xml version="1.0" encoding="UTF-8"?>
<umc version="2.0">
	<module id="udm" icon="udm-MODULE" version="1.0" translationId="MODULE">
		<flavor priority="25" icon="udm-MODULE-SUBMODULE" id="MODULE/SUBMODULE">
			<name>MODULE name</name>
			<description>MODULE description</description>
		</flavor>
		<categories>
			<category name="domain"/>
		</categories>
	</module>
</umc>

Must use /umc/module/category/@name="domain"! Must use /umc/module/@translationId to specify alternative translation file, which must be installed as /usr/share/univention-management-console/i18n/language/module.mo.

To disabling a module use the following XML file as a template:

<?xml version="1.0" encoding="UTF-8"?>
<umc version="2.0">
	<module id="udm" icon="udm/module" version="1.0" translationId="MODULE">
		<name/>
		<description/>
		<flavor id="MODULE/SUBMODULE" deactivated="yes" />
	</module>
</umc>

When a user opens http://localhost/ or http://hostname/ in a browser, she is redirected to the UCS overview page.

Depending on the preferred language negotiated by the web browser the user is either redirected to the German or English version. The overview page is split between Installed web services and Administration entries.

The start page can be extended using Univention Configuration Registry variables. PACKAGE refers to a unique identifier, typically the name of the package shipping the extensions to the overview page. The configurable options are explained below:

To configure an extension of the overview page the following options must/can be set using the pattern ucs/web/overview/entries/admin/PACKAGE/OPTION=VALUE (and likewise for services).

The following example configures the link to the Nagios web interface:

ucs/web/overview/entries/admin/nagios/description/de: Netzwerk-, Host- und Serviceüberwachung
ucs/web/overview/entries/admin/nagios/description: Network, host and service monitoring system
ucs/web/overview/entries/admin/nagios/icon: /icon/50x50/nagios.png
ucs/web/overview/entries/admin/nagios/label/de: Univention Nagios
ucs/web/overview/entries/admin/nagios/label: Univention Nagios
ucs/web/overview/entries/admin/nagios/link: /nagios/
ucs/web/overview/entries/admin/nagios/priority: 50

The requirements for providing a software solution in Univention App Center are:

The following items are no disqualifying criteria:

The following items are important for packaging:

The App Center is based on the Debian package system. From a technical point of view, the installation of an application via the App Center consists roughly of two steps: (1) adding a new repository to the system which resides on the App Center server and (2) apt-get which installs the required package. This means that 3rd party vendors need to package their application as a .deb file and send that to Univention.

For deeper integration in Univention Corporate Server it is necessary to add at least one more file, a Join Script (see Section 9.9.2). This file can be included in the core package of the application or in a dedicated package for Univention Corporate Server integration, say, univention-appname and have a dependency on the core application (on dpkg level).

See Appendix B for further details on how to build Debian packages.

In most cases the core application depends on several other packages, e.g. apache, python, etc. Those packages are automatically installed by the App Center (via apt). All packages (except games) from Debian were rebuilt for Univention Corporate Server, but not all packages are maintained by Univention. The maintained repository for Univention Corporate Server contains the most common packages, but it may be that the application needs some specific packages not found there. If this packages exists for Debian, it can be found in the unmaintained repository. But as the unmaintained repository is not activated by default the App Center cannot install the application without user configuration if some packages are only available through the unmaintained repository. But this is a requirement for any application! To workaround this issue, the vendor has to do the following: In a first step he has to grab the packages from the unmaintained repository (see for example https://updates.software-univention.de/4.0/unmaintained/) and bundle it with his own packages so that they are put into the app's own repository. In a second step he should inform Univention about these packages. We will probably move them into maintained so that this procedure will become obsolete in future versions of the application.

As soon as the software complies to the requirements the following steps are to be taken:

See also Section 9.8 for how to proceed if an update is to be released.

The App Center needs some meta information about the application to handle the installation and to present information to the user. The application needs a so-called .ini file for that. The particulars in the meta data have to be in English at least.

An example along with some comments on the variables is attached:

[Application]
# internal id
ID=application

# display name of the application
Name=The Application

# application version
Version=7.1

# whether the user's email address will be transmitted to the vendor
NotifyVendor=False

# a short description of the application (max. 90 characters)
Description=Lorem ipsum dolor sit amet, consetetur sadipscing elitr, se.

# a more complete description of the application (max. 1400 characters)
# in order to use multiple lines, preceed lines with one or more
# white spaces
LongDescription=Lorem ipsum dolor sit amet, consetetur sadipscing
 elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore
 magna aliquyam erat, sed diam voluptua. At vero eos et accusam et
 justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea
 takimata sanctus est Lorem ipsum dolor sit amet.  Lorem ipsum dolor
 sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
 invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 At vero eos et accusam et justo duo dolores et.

# reference to screenshot file (.png or .jpg file) (optional)
Screenshot=application_screenshot.jpg

# applicable category
Categories=System services

# website for more information about the product (e.g. landing page)
Website=http://www.software.com/products/application/welcome

# website for getting support (or information about how to buy a license)
SupportURL=http://www.software.com/products/application/buy

# display name of the vendor
Vendor=Software GmbH

# contact email address for the customer
#Contact=

# email address that should be used to send notifications.
# If none is provided the address from "Contact" will be used
# Note: An empty email (NotificationEmail=) is not valid! Remove the line (or
# put in comments) in this case
#NotificationEmail=

# optional: website of the vendor for more information
WebsiteVendor=http://www.software.com/

# optional: display name of the maintainer
# If the vendor does not maintain the application, this is the place,
# where the maintainer can be named. This value is optional.
Maintainer=Maintain GmbH

# optional: website of the maintainer for more information
WebsiteMaintainer=http://www.maintain.com

# optional: If the Application provides its own web interface
# it can be specified. The App Center then points to it if installed.
WebInterface=/application-webinterface

# optional: A dedicated name for the web interface may be given.
# If not, Name is taken
WebInterfaceName=Web interface of The Application

# WebInterface will be added to UCS startsite.
# Possible values: service, admin, False. If not given "service" is used.
# Only useful when a WebInterface is defined
UCSOverviewCategory=admin

# The minimal amount of memory in MB. This value is compared with the
# currently available memory (without Swap) when trying to install the
# application. A value of 0 disables the check
MinPhysicalRAM=1024

# other applications which cannot be installed at the same time (comma
# separated list) (optional)
ConflictedApps=fooapp,barapp

# other applications which need to be installed first (comma separated list)
# (optional)
RequiredApps=bazapp,quxapp

# system packages which conflict with the application (comma separated
# list) ... these are essential similar to those conflicts specified in
# the debian packages themselves, however, in order to show conflicts
# directly in the app center and without querying the debian package
# information, these can be specified in the .ini file, as well
# (optional)
ConflictedSystemPackages=mysql5,python2.5

# application packages to be installed (comma separated list)
DefaultPackages=univention-application

# optional: If the application adds its own UMC Module, it can be added
# here.  The App Center can then directly point to that module if it is
# installed.  Name as specified in the UMC XML File of that module.
UMCModuleName=univention-application-module

# optional: A module may have a multiple Flavors. UDM uses this
# functionality.  If the application does not add a dedicated UMC Module
# but extends UDM, the UMCModuleName should be "udm" and the flavor
# should be specified:
#UMCModuleFlavor=users/user

# optional: If domain users have to be somehow modified ("activated") to
# use the application, the following line should be included so that the
# App Center can give a hint and point to the Users module of UDM.
UserActivationRequired=True

# allow installation on these server roles
ServerRole=domaincontroller_master,domaincontroller_backup,domaincontroller_slave,memberserver

# allow installation on these architectures
#   possible values are (comma separated): amd64, i386
# if not set, both architectures are supported
#SupportedArchitectures=amd64,i386

# whether a "Shop" button is displayed in the App details, leading to the ShopURL
UseShop=True

# URL that the user is directed to. Only makes sense in combination with UseShop=True.
# Default is https://shop.univention.com
ShopURL=https://shop.maintain.com/application

# When UCS is not managing the domain but instead is only part of a Windows
# controlled Active Directory domain, the environment in which the app runs is
# different and certain services that this app relies may not not be running.
# Thus, there are issues and incompatibilities that should be stated:
# * App should not be installed in an AD (results in not being shown in the App
#   Center in such environments):
#ADMemberIssueHide=True
# * App needs a password service running on the Windows domain controller, e.g.
#   because it needs the samba hashes to authenticate users (results in a
#   warning and a link to the documentation how to set up that service in such
#   environments)
#ADMemberIssuePassword=True

# German translations
[de]
Description=Lorem ipsum dolor sit amet, consetetur sadipscing elitr, se.
LongDescription=Lorem ipsum dolor sit amet, consetetur sadipscing
 elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore
 magna aliquyam erat, sed diam voluptua. At vero eos et accusam et
 justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea
 takimata sanctus est Lorem ipsum dolor sit amet.  Lorem ipsum dolor
 sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
 invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua.
 At vero eos et accusam et justo duo dolores et.

# Sizing information about a single server running the app that manages X users (computers...)
# Optional
#[Sizing: 10]
#CPU=1
#RAM=1 GB
#Disk=20 GB
#
#[Sizing: 100]
#CPU=2
#RAM=2 GB
#Disk=30 GB
#
#[Sizing: 5000]
#CPU=8
#RAM=32 GB
#Disk=500 GB

This file needs to be shipped with the application and should be updated with each new version of the application at least changing Version.

Besides the text file and the above mentioned statements, a product logo and a screenshot, if given, are needed:

A few variables of the ini file need further explanation:

Along with the .ini file, there are more files that can be shipped along with the Application, each of them optionally (at least in English if given):

If the meta data (text file, logo and screenshot) and the packages are ready for upload, they can be put into a file archive (.zip or (preferably) .tar.gz) and uploaded to http://upload.univention.de. If the archive is larger than 150 MB it has to be split into single parts not larger than 150 MB.

A unique upload ID will be displayed after the download that has to be forwarded to Univention. Please send the following information via e-mail to <appcenter@univention.de>:

All further communication will be done through the ticket system after the upload.

Univention always receives an estranged notification for statistical purposes upon installation and uninstallation of an application in Univention App Center that is only saved at Univention for data processing and will not be forwarded to any third party.

Depending on the guideline of the respective application vendor an updated UCS license key with so-called key identification (Key ID) is required for the installation of an application. In this case, the Key ID will be sent to Univention together with the notification. As a result the application vendor regularly receives a message from Univention with the following information:

The description of every application includes a respective indication for such cases and is shown before installation.

If a UCS environment does not have such a key at its disposal (e.g. UCS Core Edition) and the vendor requires a Key ID, the user will be asked to request an updated license key directly from Univention. Afterwards the new key can be applied and the application installed.

If an update for an application is available, the software vendor has to provide the recent packages to Univention. The updated packages go in general through the same procedure as with the initial process described in Section 9.3.

This holds for minor updates (i.e. just small bug fixes) as well as major updates (added functionality, overhauled interface, etc.). The vendor is responsible for a smooth transition from one version to another.

For the App Center, there is no difference between a minor and a major update. The old version is completely replaced by the newer one. We do not natively support two (more or less independent) "versions lines" of the same application (e.g. one for those who want the newest features and one for those who wish to have a stable platform with nothing but conservative bug fixes). If this is desired, two separate applications need to be uploaded to the App Center that will show up next to each other. In this case the ID in the ini file needs to be changed and the application somehow needs to make sure that they cannot both be installed in parallel (e.g. a version dependency on dpkg level of some meta package). Univention may help you with the details.

Updates for the application description (.ini file), the product logo, the screenshot, readme files (especially README_UPDATE) and the packages are all submitted to <appcenter@univention.de>. Only those files that changed need to be uploaded again, everything else can be copied by Univention. The ini file needs to change every time, because the Version has to be increased. If this is the only change in the ini file, this may be stated in the email instead of shipping the file and we will take care of that during copying. Please use the upload if a higher amount of data has to be transferred (see Section 9.6).

As the application has already gone through the initial approval process and passed, Univention will offer to "semi-automatically" publish the application. I.e. we will run our test suite while giving you the chance to test your application. If our tests go well and we do not hear anything contrary from you, we will publish the application by then.

A list of the integrated repository components is in the UMC module Repository Settings. Applications which have been added via the Univention App Center are still listed here, but should be managed via the App Center module.

A further component can be set up with Add. The Component name identifies the component on the repository server. A free text can be entered under Description, for example, for describing the functions of the component in more detail.

The host name of the download server is to be entered in the input field Repository server, and, if necessary, an additional file path in Repository prefix.

A Username and Password can be configured for repository servers which require authentication.

A software component is only available once Enable this component has been activated.

A differentiation is also made for components between maintained and unmaintained components.

The following Univention Configuration Registry variables can be used to register a repository component. It is also possible to activate further functions here which cannot be configured via the UMC module. NAME stands for the component's name:

By default UCS includes English and German localisation. A package is provided to enable users to create additional translations for the Univention Management Console.

This section describes all steps necessary to create a working translation package for UCS. To create a new translation package it is advised to have a running UCS server where the package can be setup. A current Subversion checkout of the UCS source code is required. After installing the translation template package, a new translation for a target language can be created.

cd ~/translation
univention-ucs-translation-build-package \
	-s ~/translation/ucs-4.0-0 -c fr -l fr_FR.UTF-8:UTF-8 -n French

cd ~/translation/univention-ucs-translation-fr
dpkg-buildpackage 
dpkg -i ../univention-ucs-translation-fr_*.deb

UCS releases are provided either via DVD images or via online repositories. For each major, minor and patchlevel release there is a separate online repository. They are automatically added to the files in /etc/apt/sources.list.d/ depending on the Univention Configuration Registry variables version/version and version/patchlevel, which are managed by the updater.

Separate repositories are used to prevent automatic updates of software packages. This is done to encouraged users to thoroughly test a new release before their systems are updated. The only exception from this rule are the errata updates, which are put into a single repository, which is updated incrementally.

Therefor the updater will include the repositories of a new release in a file called /etc/apt/sources.list.d/00_ucs_temporary_errata__components_update.list and then do the updates. Only at the end of a successful update are the Univention Configuration Registry variables updated.

Additional components can be added as separate repositories using Univention Configuration Registry variables repository/online/component/…, which are described in ???? manual. Setting the variable …/version=current can be used to mark a component as required, which blocks an upgrade until the component is available for the new release.

In addition to the regular Debian Maintainer Scripts (see Section B.3.5) the UCS updater supports additional scripts, which are called before and after each release update. Each UCS release and each component can include its own set of scripts.

The scripts are located in the all/ component of each release and component. For UCS-4.0 this would be 4.0/maintained/4.0-0/all/preup.sh and 4.0/maintained/components/some-component/all/preup.sh for the preup.sh script. The same applies to the postup.sh script. The full process is shown in Procedure 12.1.

For an release update the following steps are performed. It assumes a single component is enabled. If multiple components are enabled, the order in which their scripts are called is unspecified. It shows which scripts are called in which order with which arguments.

UCS ships with two major database management systems, which are used for UCS internal purposes, but can also be used for custom additions.

Use ucslint to find packaging mistakes. Called best from debian/rules, needs build dependency on ucslint.

override_dh_auto_test:
	dh_auto_test
	ucslint

For each issue, ucslint prints one line, which line contains several fields separated by ::

severity:module-id-test-id[:filename[:line-number[:column-number]]]: message

For some issues extra context data is printed on the following lines, which are indented with space characters. All other lines start with a letter specifying the severity:

The severities are ordered by importance. By default ucslint only aborts on errors, but this can be overwritten using the --exitcode-categories argument followed by a subset of the characters EWIS.

After the severity an identifier follows, which uniquely identifies the module and the test. The module is given as four digits, which is followed by a dash and the number of the test in that module. Currently the following modules exist:

The module and test number may be optionally followed by a file name, line number in that file, and column number in that line, where the issue was found. After that a message is printed, which describes the issue in more detail.

Since ucslint is very Univention centric, many of its tests return false positives for software packages by other parties. Therefore many tests need to be disables. For that a file debian/ucslint.overrides can be created with list of modules and test, which should be ignored. Without specifying the optional filename, line number and column number, the test is globally disabled for all files.

The source package univention-lib provides two binary packages shell-univention-lib and python-univention-lib, which contain common library functions usable in shell or Python programs.

Access control to services can be configured for individual services by setting certain Univention Configuration Registry variables. Setting auth/SERVICE/restrict to true enables access control for that service. This will include the file /etc/security/access-SERVICE.conf, which contains the list of allowed users and groups permitted to login to the service. Users and groups can be added to that file by setting auth/SERVICE/user/USER and auth/SERVICE/group/GROUP to true respectively.

Firewall rules are setup by univention-firewall and can be configured through Univention Configuration Registry or by providing additional UCR templates.

security/packetfilter/tcp/2000/all=DROP
security/packetfilter/tcp/2000/all/en=Drop all packets to TCP port 2000
security/packetfilter/udp/500:600/all=ACCEPT
security/packetfilter/udp/500:600/all/en=Accept UDP port 500 to 600

nmap 192.168.1.100 -p 400
nmap 192.168.1.110 -sU -p 400-500