Difference between revisions of "Entwicklung und Integration eigener Module in Univention Directory Manager"

From Univention Wiki

Jump to: navigation, search
Line 157: Line 157:
 
}
 
}
 
</pre>
 
</pre>
 +
 +
Nach den Optionen werden die Attribute des Moduls festgelegt. Dabei werden die Attribute durch textuelle Beschreibungen, Syntaxdefinitionen und Anweisungen für das  Web-Frontend des Univention Directory Managers definiert.
 +
 +
<pre>
 +
property_descriptions={
 +
</pre>
 +
 +
Das Attribut '''name''' definiert den "Rechnernamen" des IP-Telefons. Mit dem Parameter '''syntax''' wird dem Univention Directory Manager mitgeteilt, dass gültige Werte für dieses Attribut der Syntax eines Rechnernamen entsprechen müssen. Weitere vordefinierte Syntaxdefinitionen sind in dem Abschnitt 2.3 zu finden. Eine Besonderheit dieses
 +
Attributs ist der Parameter may\_change, der in diesem Fall auf 0 gesetzt ist. Dadurch ist festgelegt, dass dieses Attribut nach dem Anlegen des Objektes nicht mehr
 +
geändert werden kann.

Revision as of 16:25, 10 March 2010

Einführung

Univention Directory Manager verwendet zur Verwaltung der Daten des Verzeichnisdienstes flexible und erweiterbare Struktur aus Python-Modulen. Zusätzlich einzubindende Module werden nach Ablage im Dateisystem automatisch erkannt und zur Verwendung an Kommandozeile und Web-Interface angeboten.

Die Entwicklung eigener Module erlaubt Univention Directory Manager über den Funktionsumfang von erweiterten Attributen hinaus flexibel zu erweitern.

Univention Directory Manager-Module

Übersicht

Univention Directory Manager (kurz UDM) verwendet zur Abbildung von LDAP-Objekten eine eigene Modulstruktur. Im Regelfall entspricht eines dieser UDM-Module einem LDAP-Objekt (z.B. einem Benutzer, einer Gruppe oder einem Container).

Die Module sind nach Aufgabenbereichen strukturiert im Verzeichnis /usr/lib/python2.4/site-packages/univention/admin/handlers/. Die Module für die Verwaltung der verschiedenen Rechnerobjekte befinden sich beispielsweise unterhalb des Ordners computers. Dieses Objekt kann von der Kommandzeilenschnittstelle durch computers/windows angesprochen werden.

Eigene Module sollten nach Möglichkeit in einem eigenen Unterverzeichnis abgelegt werden, um Konflikte mit eventuell später in UCS integrierten Standardmodulen zu vermeiden. Damit die Module initialisiert werden können, muss im Verzeichnis eine Datei __init__.py existieren.

Aufbau eines Moduls

Ein Modul besteht aus der Definition der Modul-Attribute und der Definition einer von univention.admin.simpleLdap abgeleiteten Klasse object.

Im folgenden wird mit einer ausführlichen Beschreibung der zu definierenden Variablen begonnen. Im darauf folgenden Abschnitt wird die Klasse object genauer betrachtet und notwendige Definitionen und Funktionen in der Klasse aufgelistet. Abschließend werden noch zwei optionale Funktionen definiert und erklärt.

Globale Variablen

Im folgende werden die globalen Variablen definiert, die in einem Univention Directory Manager-Modul besondere Bedeutungen haben. Dabei wird zwischen zwingend notwendigen und optionalen Variablen unterschieden. Die folgende Liste enthält die erforderlichen Variablen, die jedes Modul definieren muss:

module

String, der dem Namen des UDM-Moduls entsprechen muss, z.B. computers/computer

operations

Liste von Strings, enthält alle mit diesem Objekt erlaubten LDAP-Operationen. Mögliche Operationen sind: ['add','edit','remove','search','move']

short_description

Diese Beschreibung wird im Web-Frontend des Univention Directory Manager als Name angezeigt. Im Bereich Navigation wird dieser Text in der Auswahlliste für mögliche Objekttypen angezeigt.

childs

Gibt an, ob es sich bei diesem LDAP-Objekt um einen Container handelt. In diesem Fall wird diese Variable auf den Wert 1 gesetzt und andernfalls auf 0.

long_description

Eine ausführliche Beschreibung des Moduls

options

Ein Python-Dictionary, das Optionen definiert, die genutzt werden können um einzelne Attribute (properties) dieses Moduls auszublenden. In diesem Dictionary werden die Optionen (als univention.admin.option Objekte) einer eindeutigen Zeichenkette zugeordnet, die später zur Referenzierung verwendet wird (siehe property-descriptions). Jede Option erhält zwei Parameter:

  • short_description: Eine kurze Beschreibung der Option, die beispielsweise im Web-Frontend des Univention Directory Manager als beschreibender Text zu den Eingabefeldern genutzt wird.
  • default Definiert, ob diese Option standardmäßig aktiviert sein soll. Eine 1 steht dabei für aktiv und eine 0 für inaktiv.

Beispiel:

options = { 'opt1' : univention.admin.option(
 short_description = 'short description',
 default = 1 ) 
 }

property-descriptions

Dieses Python-Dictionary enthält alle Attribute, die dieses Modul zur Verfügung stellt. Dabei werden die Attribute (als univention.admin.property-Objekte), wie schon die Optionen, über eine eindeutige Zeichenkette als Schlüssel referenziert. Ein solches Modul-Attribut entspricht in der Regel einem LDAP-Attribut. Ein Beispiel:

property_descriptions = { 'prop1' : univention.admin.property(
		short_description = 'name'
		long_description = 'long description',
		syntax = univention.admin.syntax.string,
		multivalue = 0,
		required = 1,
		may_change = 1,
		identifies = 0,
		dontsearch = 0,
		show_in_lists = 0,
		one_only = 0,
		options = [ 'opt1' ] )

Die Parameter haben folgende Bedeutung:

  • short_description Eine kurze Beschreibung, die beispielsweise im Web-Frontend des Univention Directory Manager als beschreibender Text zu den Eingabefeldern genutzt wird.
  • long_description: Eine ausführlichere Beschreibung, die im Web-Frontend des Univention Directory Manager für die Tooltips genutzt wird.
  • syntax: Dieser Parameter definiert den Typ eines Attributs. Die folgende Liste enthält die wichtigsten Beispiele für mögliche Werte. All diesen Werten ist das Prefix  univention.admin.syntax. voranzustellen: string (eine beliebige Zeichenkette), integer (ein ganzzahliger positiver Wert), boolean (kann nur eine 0 oder eine 1 enthalten), filesize (ein ganzzahliger positiver Wert mit einer optional folgenden Angabe der Einheit. Unterstützt werden die Einheiten: B, KB, MB, GB, die Groß- und Kleinschreibung ist irrelevant), phone (eine Telefonnummer),  uid (ein Benutzername), uid_umlauts  (ein Benutzername mit Umlauten), gid (ein Gruppenname), sharePath (ein Pfad einer Freigabe), passwd (ein Passwort von min. acht Zeichen Länge), userPasswd (ein Passwort mit min. einem Zeichen), hostName (ein Rechnername nach RfC 952), ipAddress (eine IPv4-Adresse), hostOrIP (ein Rechnername oder eine IPv4-Adresse), netmask (eine Netzmaske), absolutePath (ein absoluter Pfad nach UNIX-Syntax, d.h. der Wert muss mit einem '/' anfangen),  emailAddress (eine Email-Adresse), emailAddressTemplate (eine E-Mail Adresse mit Nutzername),  date (ein Datum in verschiedenen Kurzschreibweisen: TT.MM.JJ oder \\ TT.MM.JJJJ oder JJJJ-MM-TT). Anhand dieser Typ-Definitionen  kann der Univention Directory Manager die angegebenen Werte für das Attribut überprüfen und bei ungültigen Werten eine detaillierte Fehlermeldung liefern. Zusätzlich zu den vordefinierten Typdefinitionen können auch eigene Typen erstellt werden. Dies sollte im Normalfall nicht notwendig sein
  • multivalue Kann die Werte 1 oder 0 annehmen. Ist dieser Parameter auf 1 gesetzt handelt es sich bei beim dem Wert des Attributs um eine Liste. Der Parameter syntax gibt in diesem Fall den Typ der Elemente dieser Liste an.
  • may_change: Ist dieser Parameter auf 1 gesetzt, kann der Wert dieses Attributs auch nach der Erstellung des Objektes verändert werden.
  • options: Eine Liste von Schlüsselwörtern, die Optionen identifizieren mit denen dieses Attribut ein- bzw. ausgeblendet werden kann.
  • identifies: diese Option sollte bei genau einem Attribut eines Moduls gesetzt sein. Sie wird verwendet um ein Objekt anhand dieses Attributs eindeutig zu identifizieren.

layout

Die Attribute eines Objektes können in Gruppen angeordnet werden. Diese werden beispielsweise im Univention Directory Manager als Reiter dargestellt. In dieser Variable wird diese Struktur definiert.

mapping

Definiert die Abbildung der Attribute des Univention Directory Manager Moduls auf LDAP-Attribute (siehe Beispiel).

Folgende Angaben sind optional und müssen nur definiert werden wenn das Modul diese speziellen Attribute besitzt:

virtual

Module, die diese Variable auf 1 setzen sind eine Art Hilfsmodul für andere Module, die keine zugehörigen LDAP-Objekte haben. Ein Beispiel hierfür ist das Modul computers/computer, das als Hilfsmodul für alle Rechnertypen dient.


template

Ein Modul, das diese Variable auf 1 setzt, bietet die Möglichkeit Vorgabewerte für die Attribute von anderen Modulen zu definieren. Ein Beispiel hierfür ist die Benutzer-Vorlage (Module settings/usertemplate). Eine solche Vorlage kann dann beispielsweise beim Anlegen eines Benutzers ausgewählt werden und die darin definierten Werte werden als Vorgaben in die Eingabemasken übernommen.

Die object-Klasse

Die Klasse object eines Moduls bildet die Schnittstelle zwischen Univention Directory Manager und den LDAP-Operationen, die beim Anlegen, Verändern oder Löschen eines Objekts ausgelöst werden. Diese Klasse unterstützt den Univention Directory Manager bei der Abbildung der definierten Attribute des Moduls auf LDAP-Objekte und -Attribute.

Dafür ist eine vordefinierte API der Klasse einzuhalten. Die Basisklasse univention.admin.handlers.simpleLdap bietet für einfache LDAP-Objekte die wesentliche Funktionaltät, so dass hierfür nur noch wenige Anpassungen notwendig sind. Um weitergehende Anpassungen vornehmen zu können, bietet die simpleLdap-Klasse die Möglichkeit vor und nach der LDAP-Operation durch den Aufruf von Funktionen weitere Anpassungen vorzunehmen. Beispielsweise wird vor dem Anlegen eines LDAP-Objekte die Funktion _ldap_pre_create aufgerufen und nach dem Vorgang die Funktion _ldap_post_create. Diese Pre- und Post-Funktionen existieren auch für die Operationen modify, move und delete.

Die Funktionen identify und lookup

Diese Funktionen werden genutzt um bei Suchanfragen aus dem Web-Frontend des Univention Directory Manager die dazugehörigen Objekte zu finden (lookup) und um LDAP-Objekte einem Univention Directory Manager-Modul zuzuordnen. Später werden Beispielimplementierungen für diese zwei Funktionen vorgestellt, die für einfache LDAP-Objekte nur leicht modifiziert werden müssen.

Beispiel-Modul

Im folgenden wird ein Beispiel-Modul für den Univention Directory Manager vorgestellt, dass auch als Paket univention-admin-module-example unter http://download.univention.de/download/addons/documentation/ verfügbar ist.

Ein Univention Directory Manager Modul bestimmt in der Regel immer aus zwei Komponenten: Einmal dem Python-Modul, das die Implementierung der Schnittstelle zum Univention Directory Manager enthält und einem LDAP-Schema, das das zu verwaltende LDAP-Objekt definiert. Im folgenden werden beide Teile beschrieben, wobei der Schwerpunkt bei der Erstellung des Python Moduls und der Installation beider Teile liegt.

Python-Modul des Beispiel-Moduls

Das folgende Modul für den Univention Directory Manager demonstriert die rudimentäre Verwaltung von IP-Telefonen. Dabei wird versucht mit einem einfach gehaltenen Beispiel möglichst viele der Möglichkeiten eines Univention Directory Manager-Moduls aufzuzeigen.

Vor der Definition eigentlichen Modul-Quellcodes müssen einige Basis-Python-Module importiert werden, die auf jeden Fall notwendig sind:

import univention.admin.filter
import univention.admin.handlers
import univention.admin.syntax

Diese Liste von Python-Modulen kann natürlich noch erweitert werden. Wie in Abschnitt "Globale Variablen" beschrieben, werden in einem Univention Directory Manager-Modul zu Beginn einige notwendige globale Variablen definiert, die eine Beschreibung des Moduls liefern:

module = 'test/ip-phone'
childs = 0
short_description = u'IP-Telefon'
long_description = u'Ein Beispiel-Modul für den \
		     Univention Directory Manager zur Verwaltung von IP-Telefonen'
operations=['add','edit','remove','search','move']

Eine weitere für das Web-Frontend des Univention Directory Manager wichtige globale Variable ist layout. Sie strukturiert die Anordnung der einzelnen Attribute des Objektes auf die Reiter. Es handelt sich dabei um eine Liste aus Elementen vom Typ univention.admin.tab, die jeweils den Inhalt eines Reiters bestimmen. In diesem Fall gibt es einen Reiter Allgemein und einen weiteren Reiter Erweiterungen.

Achtung: Es können nicht mehr als zwei Felder nebeneinander angeben werden, d.h. ein Listenelement darf nicht aus mehr als zwei Objekten vom Typ univention.admin.field bestehen!

Als nächstes sollten die Optionen und Attribute des Moduls definiert werden.

In diesem Fall wird eine Option extended angelegt, deren Funktion später noch erläutert wird. Um die Parameter zu konfigurieren wird dem Objekt univention.admin.option der Option short_description für eine Kurzbeschreibung übergeben. Mit default kann die Vorkonfiguration bestimmt werden, mit 1 ist die Option standardmässig aktiviert, mit 0 deaktiviert.

options={
    'extended' : univention.admin.option(
            short_description= u'Erweiterte Einstellungen',
            default=1
        )
}

Nach den Optionen werden die Attribute des Moduls festgelegt. Dabei werden die Attribute durch textuelle Beschreibungen, Syntaxdefinitionen und Anweisungen für das Web-Frontend des Univention Directory Managers definiert.

property_descriptions={

Das Attribut name definiert den "Rechnernamen" des IP-Telefons. Mit dem Parameter syntax wird dem Univention Directory Manager mitgeteilt, dass gültige Werte für dieses Attribut der Syntax eines Rechnernamen entsprechen müssen. Weitere vordefinierte Syntaxdefinitionen sind in dem Abschnitt 2.3 zu finden. Eine Besonderheit dieses Attributs ist der Parameter may\_change, der in diesem Fall auf 0 gesetzt ist. Dadurch ist festgelegt, dass dieses Attribut nach dem Anlegen des Objektes nicht mehr geändert werden kann.

Personal tools