Join-Skript-Bibliothek

From Univention Wiki

Revision as of 09:42, 24 February 2011 by Klaeser (talk | contribs) (→‎Allgemeines)
Jump to: navigation, search

Das Paket univention-join installiert (ab Version 2.0.1) die bash-Bibliothek /usr/share/univention-join/joinscripthelper.lib mit, die typische Aufgaben für Join-Skripte zusammenfasst.

Das folgende Beispiel eines fiktiven Join-Skripts demonstriert die wichtigsten Variablen und Funktionen:

# Versionsnummer des Joint-Skripts muss zuerst angegeben werden.
# Es werden nur Skripte neuerer Version auf einem System ausgeführt.
VERSION=3

# Einbinden der Bilbiotheksfunktionen
. /usr/share/univention-join/joinscripthelper.lib
joinscript_init

#-----------------------------------------------------
echo "Führe Join-Aktionen für ${JS_PACKAGE} aus..."

# Importieren aller UCR-Variablen in den Scope des Skriptes.
eval "$(univention-config-registry shell)"

# Beispielaktion: Beenden eines Daemons
/etc/init.d/fictional_daemon stop

if [ $JS_LAST_EXECUTED_VERSION -le 2 ]; then
  # Aktionen, die nur beim Upgrade von einer Version kleiner oder gleich 2 ausgeführt werden sollen
fi

# Beispielaktion: Anlegen eines Container-Objekts
# Dem Join-Skript werden als Parameter --binddn und --bindpwd Optionen für den Aufruf von 
# univention-directory-manager übergeben; hier werden diese weiter gegeben über die Variable "$@".
univention-directory-manager container/cn create "$@" --ignore_exists --position="$ldap_base" \
    --set name="myContainer" --set description="My Objects"

# Aktionen, die bei jeder Erhöhung der Versionsnummer durchgeführt werden sollen

# Beispielaktion: Neustart des Daemons
/etc/init.d/fictional_daemon start
#-----------------------------------------------------

# Speichern der aktuellen Version des Join-Skriptes.
joinscript_save_current_version

# Das korrekte Beenden (=Exit-Code 0) des Skriptes ist wichtig.
exit 0 
  • Die Versionsnummer $VERSION wird mit jeder neuen Skript-/Paket-Version erhöht, wobei neue Join-Skripte mit Version 1 beginnen !
  • Versionsdefinitionen müssen der grep-regex "^[[:space:]]*VERSION=([1-9][0-9]*|\"[1-9][0-9]*\"|'[1-9][0-9]*')[[:space:]]*$" entsprechen, damit die Verwendung der joinscripthelper.lib von außerhalb eines Join-Skripts (siehe weiter unten) funktioniert. Dabei wird im Falle von mehreren solcher Definitionen nur die letzte beachtet.
  • joinscript_init prüft wie, bzw. ob das System der Domäne bereits beigetreten ist, ob diese Version des Join-Skriptes bereits ausgeführt wurde, und bricht ggf. ab. Außerdem initialisiert es die Variable JS_LAST_EXECUTED_VERSION.
  • JS_LAST_EXECUTED_VERSION=0 gibt an, dass das Skript noch nie ausgeführt wurde.
  • Am Ende des Skripts wird der Aufruf von joinscript_save_current_version erwartet, damit die erfolgreiche Ausführung gespeichert wird.
  • Dem Join-Skript werden als Parameter --binddn und --bindpwd Optionen übergeben, die direkt weitergeben werden können an univention-directory-manager zur Authentifizierung.

Weitere, detailliertere Informationen darüber, welche Versionen des Skripts bereits ausgeführt wurden, stellen die folgenden Funktionen bereit:

  • joinscript_check_any_version_executed(): Gibt 0 zurück, falls bereits irgendeine Version des Skripts vorher ausgeführt wurde, sonst 1
  • joinscript_check_specific_version_executed(): Erwartet als Parameter eine Versionsnummer und gibt 0 zurück, falls die angegebene Version des Skripts bereits ausgeführt wurde, sonst 1.
  • joinscript_check_version_in_range_executed(): Erwartet eine untere und obere Versionsnummer als Parameter und gibt 0 zurück, falls eine Version zwischen den beiden angegebenen Versionsnummern (inklusive) bereits ausgeführt wurde, sonst 1.

Verwendung außerhalb von Join-Skripten

Die Bibliothek kann auch außerhalb eines Join-Skriptes verwendet werden. Da sich die Bibliothek immer auf ein konkretes Join-Skript bezieht, muss für die Initialisierung der jeweilige Skriptname übergeben werden.

Die Methode joinscript_extern_init initialisiert die Bibliothek für das Skript. Sie gibt 1 zurück, falls das Join-Skript ungültig ist, ansonsten 0. Anschließend können alle Methoden aus der Bibliothek normal verwendet werden. Die Bibliothek kann dabei mit joinscript_extern_init beliebig oft auf ein neues Skript reinitialisiert werden, genauso wie sie mit joinscript_init auf das gerade laufende Skript (re-)initialisiert werden kann.

Exit-Code-Konventionen

Um die Ausgabe des Meta-Skripts univention-run-join-scripts konsistent zu gestalten, ist es vorgesehen, dass Join-Skripte einheitliche und ausreichend differenzierende Exit-codes verwenden. Die folgende Tabelle fasst die derzeitig verwendeten Exit-Codes zusammen und wird in Zukunft - wenn notwending - erweitert.

Exit Code Wird wann angewendet Bemerkungen
0 Erfolgreiches Terminieren, sowie erfolgreiches Erreichen des Skriptendes trotz Fehler Deswegen "exit 0" an jedem Skript-Ende
1 Abbruch Für den Fall, dass das System noch nicht der Domäne beigetreten ist oder das Skript bereits ausgeführt wurde
2 Inkorrekte Verwendung der shell-builtins führt zu vorzeitigem Skriptende siehe bash(1) Abschnitt "EXIT STATUS"
Personal tools