José Active-Directory-Dokumentation: Version 2.0 ist fertig

Achtung, Update 28. Mai 2010: Version 3.0 ist aktuell! Nutzt die Suchfunktion für nähere Informationen.

Die neue Version 2.0 meines Dokumentationstools José für Active Directory ist endlich fertig! Nach langer Wartezeit und einer sehr produktiven Betaphase steht die neue Fassung nun hier zum Download bereit:

  José Active-Directory-Dokumentation (86,1 KiB, 201.911-mal heruntergeladen, letzte Änderung am 9. April 2019)

Die wichtigsten Neuerungen im Überblick:

• José besteht nun aus zwei Teilen: Die bekannte grafische Oberfläche zum Konfigurieren der Dokumentation und ein Kommandozeilen-Tool zum Erzeugen des Reports. Dadurch kann man José nun endlich auch automatisiert ausführen oder einen bestimmten Report immer wieder erzeugen. Bei der grafischen Bedienung ändert sich (fast) nichts. Die Automatisierung arbeitet mit einfachen Definitions-Dateien (lassen sich grafisch erzeugen) und einer simplen Kommandozeile.
• Die Oberfläche ist modernisiert und poliert.
• Beim Aufruf der grafischen Oberfläche zeigt José nicht mehr zwingend die ganze OU-Struktur der Domäne an. In großen Umgebungen entfallen so ärgerliche Wartezeiten.
• Die eigentliche Reporting-Engine habe ich jetzt ebenfalls recht deutlich erweitert und verändert. Vor allem über Gruppenrichtlinien erzeugt José nun recht umfassende Berichte (über die Metadaten – nicht über die Einstellungen selbst). Daneben ist es nun viel einfacher, zusätzliche Attribute in einen Report einzufügen, und für manche solcher Attribute enthält José spezielle Logik.

Für die Unterstützung der Betaphase danke ich dem MCSEboard.de und besonders Norbert Fehlauer.

Hier die Dokumentation:

José Active-Directory-Dokumentation 2.0

José grüßt!

Was das ist: José ist ein kleines, HTML- und skriptbasiertes Tool zur Dokumentation der Objekte des Active Directory. Es liest dabei das Verzeichnis aus und generiert eine HTML-Datei, in der Informationen über OUs, Benutzer, Gruppen, Computer, Policies usw. angezeigt werden.

Was das nicht ist: José ist kein Verwaltungsprogramm. Es führt keinerlei Änderungen am Verzeichnis durch. Und José generiert keine dynamischen Seiten, d. h. es ist nicht möglich, die angezeigte Ordnerstruktur nachträglich auf- oder zuzuklappen oder Ähnliches.

Vorsicht: José ist für überschaubare Umgebungen konzipiert. Da die Abfragen, die José verwendet, nicht besonders optimiert sind, kann es in großen Umgebungen zu langen Wartezeiten sowie u.U. zu größerer Netzwerklast kommen. Zudem sollte der erzeugte Report nicht wesentlich mehr als 2000 Objekte (Benutzer, Gruppen usw.) umfassen, weil die Anzeige im Browser sonst problematisch werden kann. Wer sehr große Umgebungen verwaltet, sollte seine Reports daher immer auf eine bestimmte Ebene oder eine bestimmte Objektklasse eingrenzen und z.B. mit mehreren Teil-Reports arbeiten.

Benutzung

Seit Version 2.0 hat José zwei Betriebsarten:

1. Interaktiver Betrieb mit GUI
2. Skriptgesteuerter Betrieb per Kommandozeile

Aus diesem Grund besteht José nun aus zwei ausführbaren Dateien: Jose.hta und JoseExec.vbs. Wer wie bislang arbeiten will, nutzt auch weiterhin nur die Jose.hta.

Interaktiver Modus: Jose.hta

José wird gestartet durch Doppelklick auf „jose.hta“. Es öffnet sich ein Formular, in dem der zu erzeugende Bericht konfiguriert werden kann. Die einzelnen Abschnitte beziehen sich auf unterschiedliche Objektklassen des Active Directory (Benutzerkonten, Gruppen usw.). Dabei gilt stets: Der oberste, fett gedruckte Eintrag einer Liste gibt an, ob die zugehörige Klasse überhaupt angezeigt wird. So lässt sich steuern, welche Objektklassen im Report erscheinen sollen. Wenn eine Klasse gar nicht angezeigt wird, werden die einzelnen Attribute automatisch ignoriert.

Die LDAP-Namen der Attribute, die ein- oder abgeschaltet werden können, werden in einem kleinen Infofenster angezeigt, wenn man mit der Maus auf das Kästchen zeigt. Beim Start von José ist ein Standard-Set von Attributen ausgewählt, die in den meisten Fällen einen interessanten Bericht ergeben. Diese Standardauswahl lässt sich durch den Button „Standardauswahl“ wiederherstellen (die Buttons „alle Eigenschaften“ und „keine Eigenschaften“ sollten selbsterklärend sein).

Wenn man „OU-Struktur anzeigen“ abschaltet, geht José die Ordner und OUs nicht durch. Das ist nützlich für Reports, die nur die Doänendaten oder nur die GPO-Liste ausgeben sollen.

Filtern

Beim Start wird ab Version 2.0 nicht mehr automatisch die Active-Directory-Struktur eingelesen. Dies hat sich in großen Umgebungen als hinderlich herausgestellt. Einen Ebenen-Filter kann man nun ganz oben in das Feld „Ausgabe ab OU“ in LDAP-Notation eintragen. Beispiel: OU=EDV, OU=Benutzer, DC=faq-o-matic, DC=net. Wer die Auswahl lieber per Maus treffen möchte, klickt auf den Button „OUs anzeigen“ neben dem Eingabefeld. Daraufhin blendet José im linken Bereich die AD-Struktur mit Optionsfeldern ein (Achtung: In einer sehr komplexen Umgebung kann das einen Moment dauern!). Durch Markieren einer OU oder eines Ordners wird dessen LDAP-Name in das Filterfeld eingetragen. Dadurch kann man die Ausgabe der Objekte auf die gewählte OU bzw. den ausgewählten Ordner (und untergeordnete) beschränken. Sofern die Ausgabe auf eine bestimmte Ebene beschränkt wird, erscheint im Bericht ein Hinweis darauf.

Diverses

Achtung bei Gruppenmitgliedschaften: Die Auswahl von „Gruppenmitgliedschaften“ unter „Benutzerkonten“ bzw. von „Mitglieder“ unter „Gruppen“ führt u. U. zu einer recht langen Bearbeitungszeit.

Bei Auswahl von „Gruppenrichtlinien“ werden nur die Namen der Richtlinien angezeigt, nicht aber die Einstellungen, die innerhalb der Richtlinien gesetzt sind. Diese Informationen lassen sich (derzeit) nicht per Skript auslesen.

Die Terminalserver-Einstellungen (TS-Profil und TS-Home) kann José derzeit nur auf einem Windows Server 2003 oder auf Windows XP auslesen. Warum das unter Vista und Windows Server 2008 nicht funktioniert, ist mir noch nicht klar. Ich arbeite dran.

Report ausführen

Im Eingabefeld „Report-Name“ kann man eine Überschrift für den generierten Bericht angeben. Zusammen mit den Optionen „Legende anzeigen“, „Objektname anstelle des LDAP-Namens anzeigen (bei Gruppenmitgliedschaften)“ und „Eigenschaften in Umgangssprache“ ist die Dokumentation auch für Nicht-Techies geeignet.

Unter „Report-Dateiname“ kann man einen Dateinamen für den Report angeben – nur den Namen, keinen Pfad (die Endung „.htm“ fügt José bei Bedarf selbst hinzu). Bleibt das Feld leer, so erzeugt José selbst einen Namen. Achtung: Wenn der gewählte Dateiname bereits vergeben ist, überschreibt José den vorhandenen Report.

Ein Klick auf den Button „Jetzt dokumentieren!“ startet die Dokumentation. Es öffnet sich ein schwarzes CMD-Fenster, das nicht geschlossen werden darf! Es kann nun durchaus ein paar Minuten dauern, in denen das Fenster aussieht, als passiere nichts mehr. Nur Geduld! Nach dem Generieren des Reports gibt es unten unter „Status“ Informationen und ggf. Fehlermeldungen. Sobald die Doku fertig ist, zeigt ein kleines Feld an „OK“, und im Statusbereich steht ein Link auf die generierte HTML-Datei.

Alternativ bzw. zusätzlich kann man die vorhandenen Einstellungen auch als Definitions-Datei speichern, um einen gleichartigen Report mit JoseExec.vbs auszuführen. Hierzu drückt man den Button „Report-Definition speichern“. José fragt dann nach einem Namen für die Definitions-Datei, den man frei wählen kann (Angabe ohne Pfad – nur der Dateiname!). Die Definitions-Dateien liegen in dem Unterordner /Definitions.

Automatisierter Modus: JoseExec.vbs

Wer José automatisiert oder mit einer vorhandenen Berichts-Definition ausführen möchte, kann dies über das zusätzliche Skript „JoseExec.vbs“ tun. JoseExec.vbs entnimmt die Definition des Reports aus einer Definitionsdatei im Ordner /Definitions. Das Skript wird mit „cscript.exe“ in einem CMD-Fenster aufgerufen und hat mehrere Kommandozeilenoptionen:

cscript JoseExec /d:<Definition> [/r:<Report>] [/t:<Titel>] [/f:<Filter>]

• /d: Name einer José-Definitionsdatei
  Die Angabe erfolgt ohne Dateipfad – nur der Dateiname.
• /r: (optional) Name der zu erzeugenden Report-Datei (HTML)
  Die Angabe erfolgt ohne Dateipfad – nur der Dateiname. Achtung: Die Datei wird ohne Rückfrage überschrieben!
• /t: (optional) Titel des Berichts
• /f: (optional) LDAP-Objektfilter (Container/OU)

Der Parameter „/d“ ist zwingend. Bei falschem Aufruf (oder bei Aufruf mit /?) zeigt JoseExec.vbs eine Syntax-Übersicht an.

Es empfiehlt sich, alle Angaben in Anführungsstriche einzufassen (zwingend, sobald Leerzeichen enthalten sind).

Beispiel:

cscript JoseExec /d:"DomainData.txt" /r:"MyDomainData.htm" /t:"Meine Domäne" /f:"OU=EDV,OU=Benutzer,DC=domain,DC=tld"

Format der Definitions-Datei

Die Definitionsdatei ist eine einfache Textdatei mit einem recht simplen Aufbau. Hier ein Beispiel:

; --------------------------------------------
; José-Definitionsdatei AD-Definition 15.09.2008 16-27-08.txt
; Erzeugt: 15.09.2008 16:27:10
; von: FAQ-O-MATIC\Nils
; mit: José AD-Dokumentation 2.0
; Download auf http://www.faq-o-matic.net
; --------------------------------------------
[Meta]
ReportName=Active Directory
ReportFileName=AD-Doku 15.09.2008 16-27-08.htm
ObjectFilter=
ShowSymbols
ShowNaturalName
ShowFriendlyName
[Common]
fsmo
trust
folder
ObjektStruktur
gpo
number
Modify
[Printer]
serverName
printShareName
[Group]
[Contact]
[User]
samAccountName
userPrincipalName
profilePath
homeDirectory
homeDrive
scriptPath

Zeilen, die mit ; beginnen, sind Kommentare. Sie werden ignoriert. Achtung: Kommentare müssen in eigenen Zeilen stehen und können nicht an vorhandene Zeilen angefügt werden.

Jeder Abschnitt beginnt mit einem Label in eckigen Klammern. Derzeit sind nur die Labels [Meta], [Common], [Printer], [Group], [Contact] und [User] bekannt. Sie stehen – außer Meta und Common – für die Objektklassen, die José dokumentiert.

Im Abschnitt [Meta] hinterlegt José die Report-Optionen. Der Name des Berichts, der Report-Dateiname und der Ebenen-Filter können mit Hilfe der Kommandozeilenparameter /r, /t bzw. /f von JoseExec.vbs übersteuert werden – sobald sie also im Kommando auftauchen, wertet JoseExec die jeweilige Angabe in der Definitionsdatei nicht mehr aus.

Im Abschnitt [Common] listet José die aktiven Optionen auf, die im grafischen Fenster ganz oben links stehen.

Die weiteren Abschnitte sind simpel: Wenn ein Abschnitt zu einer Objektklasse auftaucht, wird diese Objektklasse (z.B. User) mindestens mit dem Namen und der Beschreibung im Report dokumentiert. Unter dem Label folgen dann die zu berücksichtigenden Attribute.

Reports erweitern

Die Architektur von JoseExec.vbs erlaubt es, Reports um neue Attribute zu erweitern bzw. vorhandenen Definitions-Dateien nachträglich zu bearbeiten. Dies geschieht mit einem einfachen Texteditor. Um Attribute aus einer Definition zu entfernen, löscht man einfach die Angabe des Attributs. Um neue Attribute aufzunehmen, trägt man den Attributnamen einfach bei der gewünschten Klasse ein (z.B. employeeID). Das eignet sich allerdings nur für Textattribute. Mit mehrwertigen Attributen kann José umgehen. Problematisch sind Binärattribute, weil diese nicht ohne Weiteres per Skript zugänglich sind.

Für folgende Attribute hat José eine eigene Unterstützung eingebaut – sie sind nur über die ERweiterung der Definitionsdatei zugänglich:

• pwdLastSet (letzte Kennwortänderung)
• lastLogonTimestamp (letztes repliziertes Anmeldedatum)
• canonicalName (OU-Pfad wie in der Erweiterten Ansicht unter „Objekt“ als Kanonischer Name angezeigt)

Der Parser für die Definitionsdatei ist recht robust. Die Reihenfolge der Abschnitte ist egal, Leerzeilen stören nicht. Attribute, die nicht existieren, werden einfach ignoriert. Groß- und Kleinschreibung ist egal.

Reports

Die generierten HTML-Dateien werden ausschließlich im Unterverzeichnis Reports gespeichert (ab und an mal leeren), das bei Bedarf erzeugt wird. Wer diese generierten Dateien weitergeben oder woanders speichern will, hat mehrere Möglichkeiten:

• die beiden Ordner „Dateien“ und „Reports“ gemeinsam kopieren. Sie müssen auf derselben Ebene liegen, damit die Grafiken richtig eingefügt werden.
• die HTML-Datei im Internet-Explorer öffnen und über  [Datei -> Speichern unter … (Dateityp: „Website, komplett (.htm, .html)“)] abspeichern. So werden alle benötigten „*.gif“-Bilder und das Stylesheet in ein Unterverzeichnis des gewählten Speicherortes kopiert und die Links relativ dazu angepasst.

Hinweis bei Kontenattributen

Bei der Auswertung von Kontenattributen insbesondere bei Benutzerkonten kann es Berechtigungsprobleme geben. Diese führen dazu, dass Informationen zu deaktivierten, gesperrten oder ablaufenden Konten – ggf. aber auch andere Informationen – nicht richtig dargestellt werden.

Um verlässliche Informationen zu diesen Konten-Statusdaten zu erhalten, führen Sie José bzw. JoseExec mit einem Konto aus, das volle Leserechte auf die relevanten Attribute hat (z.B. ein Domänen-Administratorkonto). Unter Windows Vista und Windows Server 2008 sollten Sie José bzw. JoseExec dazu von einer Eingabeaufforderung aus starten, die Sie ausdrücklich als Administrator gestartet haben. (Näheres zu den Besonderheiten von Vista und Windows Server 2008 finden Sie in diesem Artikel.)

Die freie Weitergabe des Programms ist erlaubt. Ebenso ist es erlaubt, den Quelltext zu ändern. Der Autor dieses Programms übernimmt allerdings keinerlei Gewähr oder Support!