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

From Univention Wiki

Jump to: navigation, search
(Moved to Developer Reference)
Tag: Replaced
 
(104 intermediate revisions by 11 users not shown)
Line 1: Line 1:
= Einführung =
+
=Hinweis=
  
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.
+
Dieser Artikel wurde in die [https://docs.software-univention.de/developer-reference-5.0.html#udm:modules offizielle Dokumentation] integriert, überarbeitet und angepasst. Der Inhalt dieser Seite ist demnach veraltet und wurde entfernt.
 
 
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:<span style="font-style: italic;"> </span>''['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:  
 
<pre>options = { 'opt1'&nbsp;: univention.admin.option(
 
short_description = 'short description',
 
default = 1 )
 
}
 
</pre>
 
==== '''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:
 
<pre>property_descriptions = { 'prop1'&nbsp;: 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' ] )
 
</pre>
 
Die Parameter haben folgende Bedeutung:
 
 
 
*'''short_description&nbsp;'''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&nbsp; ''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),&nbsp; '''uid''' (ein Benutzername), '''uid_umlauts'''&nbsp; (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),&nbsp; '''emailAddress''' (eine Email-Adresse), '''emailAddressTemplate''' (eine E-Mail Adresse mit Nutzername),&nbsp; '''date''' (ein Datum in verschiedenen Kurzschreibweisen: TT.MM.JJ oder \\ TT.MM.JJJJ oder JJJJ-MM-TT). Anhand dieser Typ-Definitionen&nbsp; 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:
 
 
 
<pre>
 
import univention.admin.filter
 
import univention.admin.handlers
 
import univention.admin.syntax
 
</pre>
 
 
 
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:
 
 
 
<pre>
 
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']
 
</pre>
 
 
 
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.
 
 
 
<pre>
 
options={
 
    'extended' : univention.admin.option(
 
            short_description= u'Erweiterte Einstellungen',
 
            default=1
 
        )
 
}
 
</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 finden sich im Abschnitt "Globale Variablen". Eine Besonderheit dieses Attributs ist der Parameter '''may_change''', der in diesem Fall auf 0 gesetzt ist. Dadurch wird festgelegt, dass dieses Attribut nach dem Anlegen des Objektes nicht mehr
 
geändert werden kann:
 
 
 
<pre>
 
    'name': univention.admin.property(
 
            short_description= u'Name',
 
            long_description= u'Name des Telefons',
 
            syntax=univention.admin.syntax.hostName,
 
            multivalue=0,
 
            options=[],
 
            required=1,
 
            may_change=0,
 
            identifies=1
 
        ),
 
</pre>
 
 
 
 
 
'''active''' ist ein Beispiel für ein boolsches/binäres Attribut, die nur die Werte ''1'' oder ''0'' annehmen kann. In diesem Beispiel definiert es eine Freischaltung/Sperrung des IP-Telefons. Durch dem Parameter ''default=1'' wird das Telefon initial freigeschaltet:
 
 
 
<pre>
 
    'active': univention.admin.property(
 
            short_description= u'freigeschaltet',
 
            long_description= u'Ein IP-Telefon kann gesperrt werden',
 
            syntax=univention.admin.syntax.boolean,
 
            multivalue=0,
 
            options=[],
 
            required=0,
 
            default='1',
 
            may_change=1,
 
            identifies=0
 
        ),
 
</pre>
 
 
 
Das Attribut '''protocol''' legt fest, welches VoIP-Protokoll von dem Telefon unterstützt wird. Dabei wird für dieses Attribut keine Standard-Syntaxdefinition verwendet, sondern eine eigens dafür deklarierte Klasse '''SynVoIP_Protocols'''. (Der Quellcode dieser Klasse folgt in einem späteren Abschnitt). Die Syntax der Klasse definiert eine  Auswahlliste mit einer vordefinierten Menge an Möglichkeiten. Durch den Parameter '''default '''wird der Wert mit dem Schlüssel ''sip'' vorausgewählt.
 
 
 
<pre>
 
    'protocol': univention.admin.property(
 
            short_description= u'Protokoll',
 
            long_description= u'Welches VoIP Protokoll \
 
    wird von dem Telefon unterstützt',
 
            syntax=SynVoIP_Protocols,
 
            multivalue=0,
 
            options=[],
 
            required=0,
 
            default='sip',
 
            may_change=1,
 
            identifies=0
 
        ),
 
</pre>
 

Latest revision as of 11:39, 3 November 2021

Hinweis

Dieser Artikel wurde in die offizielle Dokumentation integriert, überarbeitet und angepasst. Der Inhalt dieser Seite ist demnach veraltet und wurde entfernt.

Personal tools