Integration with UCS/Join

The join script is a fundamental feature of UCS. UCS is used to run and administrate a domain. New computers may "join" the domain. The computer searches for the Domain Controller Master (DC Master) and adds itself to LDAP (hostname, IP address, etc). Join scripts are used to "join software packages" into the domain. This means that if you install your App, it may need to register important bits somewhere and make some changes in the domain.

The domain is administrated by manipulating the core database on the DC Master, the LDAP database. Normally, this is done by using tools provided by Univention, mainly the Univention Directory Manager (UDM).

Important

UDM needs Admin credentials to work on any other system then the DC Master. For that, calling UDM in the postinst of a package will not work in general.

For App Providers, a Join Script functions as a postinst of the App. But it has write access to the LDAP database (even when not installed on the DC Master).

Important

Join scripts that fail to run through do not abort the installation. Instead, administrators are notified that a join script has not yet been executed.

Important

Output of the Join scripts goes to /var/log/univention/join.log on the Docker Host.

Example Join script

#!/bin/bash
VERSION=1
. /usr/share/univention-appcenter/joinscripthelper.sh
joinscript_init
eval "$(ucr shell ldap/base)"

joinscript_run_in_container sed -i /opt/myapp/some_script ... || die

udm users/user create "$@" --ignore_exists \
	--position "cn=users,$ldap_base" \
	--set username="myapp-systemuser" \
	--set lastname="My App" \
	--set password="$(makepasswd --chars 20)" \
	--option ldap_pwd || die

joinscript_save_current_version
exit 0

Some points to the usage of udm in the script above:

• UDM needs Admin credentials! Join scripts are called with Admin credentials. To pass them over to UDM, just *use "$@" in any udm call*.
• Join scripts may be run more than once. The user may have already been created. That's why --ignore_exists has to be passed. Else udm fails.
• $ldap_base was set by "eval "$(ucr shell ldap/base)"" a few lines earlier

Join Script Helper

TBD

Best practices

die

Secure successful execution of important commands with a meaningful error message.

udm users/user create "$@" ... || die "Could not create user"

Most, if not all, commands are important. You may use "die" everywhere.

Service

It is a good idea to add a service name to the localhost, this is basically a human readable way of telling: "This system runs My App".

SERVICE="My App"
ucs_addServiceToLocalhost "${SERVICE}" "$@"

Unjoin

Unjoin is the opposite of the join script, called after the App is uninstalled, not after it is installed. It serves the same purpose, but as a postrm.

#!/bin/bash
VERSION="1"

. /usr/share/univention-lib/ldap.sh
. /usr/share/univention-appcenter/joinscripthelper.sh

joinscript_init

eval "$(ucr shell)"
SERVICE="My App"
APP="myapp"

ucs_removeServiceFromLocalhost "${SERVICE}" "$@"

if ucs_isServiceUnused "${SERVICE}" "$@"; then
  udm users/user remove --dn "uid=myapp-systemuser,cn=users,$ldap_base"
fi

joinscript_remove_script_from_status_file "$APP"
exit 0