Difference between revisions of "Integration with UCS/Join"

From Univention Wiki

Jump to: navigation, search
(Content moved to https://docs.software-univention.de/app-provider.html#installation:joinscript)
 
(3 intermediate revisions by one other user not shown)
Line 1: Line 1:
[[Category:App Center Developer Guide]]
+
#REDIRECT [[App Center Developer Guide]]
 
 
The join script is a fundamental feature of UCS. UCS is used to run and [[UCS|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 [[UDM|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 =
 
 
 
<pre>
 
#!/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
 
</pre>
 
 
 
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.
 
 
 
<pre>
 
udm users/user create "$@" ... || die "Could not create user"
 
</pre>
 
 
 
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".
 
 
 
<pre>
 
SERVICE="My App"
 
ucs_addServiceToLocalhost "${SERVICE}" "$@"
 
</pre>
 
 
 
= 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.
 
 
 
<pre>
 
#!/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
 
</pre>
 

Latest revision as of 07:58, 3 December 2018

Personal tools