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, die Informationen über OUs, Benutzer, Gruppen, Computer, Policies usw. anzeigt.
Was das nicht ist: Und José generiert keine dynamischen Seiten, d. h. es ist nicht möglich, die angezeigte Ordnerstruktur nachträglich auf- oder zuzuklappen oder Ähnliches.
Und: José liest das AD nur aus und ändert nichts. Daher benötigt es keine Schreibrechte im AD und kann auch mit normalen Benutzerrechten ausgeführt werden (in dem Fall können aber fehlende Berechtigungen dazu führen, dass José einiges nicht lesen kann). José ist daher "sicher" in Bezug auf Active Directory.
Vorsicht aber: 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 zu groß werden, weil die Anzeige im Browser sonst problematisch werden kann. Umgebungen mit mehreren tausend Objekten sind allerdings schon erfolgreich dokumentiert worden. 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.
Bekannte Einschränkungen:
Die aktuelle Version von José ist zu finden unter: http://www.faq-o-matic.net/jose/
In Version 3.0 hat Ansgar Wiechers den Skriptcode von JoseExec.vbs komplett neu aufgebaut. Der Code ist nun leichter zu warten und zu erweitern. Dadurch hat sich allerdings auch die Betriebsweise des Skripts geändert, sodass es in vielen Fällen mehr Zeit benötigt. Das halten wir aber für gut vertretbar.
Ab Version 3.0 gibt José die Beschreibung (description) von Objekten nur optional aus. Diese Option ist allerdings standardmäßig aktiviert. Sie findet sich in jose.hta oben links bei den allgemeinen Optionen. In der Definitionsdatei steuert die Angabe "description" im Abschnitt "[common]" das Verhalten - fehlt sie, gibt José keine Beschreibungen aus.
Seit Version 2.0 hat José zwei Betriebsarten:
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.
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).
Als letzte Auswahl bei jeder Klasse gibt es das Feld "Andere". Hier kann man selbst weitere Felder eintragen, wobei deren ADSI- bzw. LDAP-Name relevant ist. Mehrere Felder trennt man durch Komma, Leerzeichen bitte nicht einfügen. Sollen diese Felder im Report erscheinen, muss das Häkchen vor "Andere" auch aktiviert sein.
Wenn man "OU-Struktur und Objekte" abschaltet, geht José die Ordner und OUs nicht durch. Das ist nützlich für Reports, die nur die Domänendaten oder nur die GPO-Liste ausgeben sollen.
Beim Start wird ab Version 2.0 nicht mehr automatisch die Active-Directory-Struktur eingelesen. Dies hatte 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.
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. Hierfür empfehlen wir die Skripts der Group Policy Management Console (GPMC), insbesondere "GetReportsForAllGPOs.wsf".
Die Terminalserver-Einstellungen (TS-Profil und TS-Home) kann José zwar auf zwei Arten auslesen (ADSI-Zugriff auf "userParameters" und die neuen "msTS*"-LDAP-Felder seit Windows Server 2008), allerdings funktioniert tatsächlich nur die erste Variante, weil die in Windows Server 2008 neu eingeführten Felder im AD noch gar nicht implementiert sind.
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.
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 (oder per Batch) aufgerufen und hat mehrere Kommandozeilenoptionen:
cscript JoseExec /d:<Definition> [/r:<Report>] [/t:<Titel>] [/f:<Filter>]
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"
Um ein Debug-Protokoll zu erzeugen, hängt man den Parameter /debug an die Kommandozeile an. Sinnvollerweise sollte man die Ausgabe des Kommandos dann in eine Textdatei umleiten.
Beispiel:
cscript JoseExec /d:"DomainData.txt" /r:"MyDomainData.htm" /debug > C:\Daten\josedebug.txt
Die Definitionsdatei ist eine einfache Textdatei mit einem recht simplen Aufbau. Hier ein Beispiel:
; -------------------------------------------- ; José-Definitionsdatei AD-Definition-Beispiel.txt ; Erzeugt: 10.03.2010 06:44:20 ; von: FAQ-O-MATIC\Nils ; mit: José AD-Dokumentation 3.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 OU 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 kennt José die Labels [Meta], [Common], [Printer], [Group], [Contact] und [User]. 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 im Report dokumentiert. Unter dem Label folgen dann die zu berücksichtigenden Attribute.
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.
Ab Version 3.2 kann man zusätzliche Attribute auch über das GUI "Jose.hta" in einer neuen Definitionsdatei oder zu einem interaktiven Report hinzufügen, indem man sie jeweils unter "Andere" einträgt und das zugehörige Kästchen davor aktiviert. Das nachträgliche Ändern einer Definitionsdatei ist aber nicht über das GUI möglich, sondern nur per Texteditor.
Für folgende Attribute hat José eine eigene Unterstützung eingebaut - sie sind nur über die Erweiterung der Definitionsdatei zugänglich:
Ein Beispiel für eine erweiterte Datei:
; -------------------------------------------- ; José-Definitionsdatei AD-Definition-Beispiel.txt ; Erzeugt: 10.03.2010 06:44:20 ; von: FAQ-O-MATIC\Nils ; mit: José AD-Dokumentation 3.0 ; Download auf http://www.faq-o-matic.net ; -------------------------------------------- [Meta] ReportName=Active Directory ReportFileName=AD-Doku-Beispiel.htm ObjectFilter= ShowSymbols ShowNaturalName ShowFriendlyName [Common] fsmo trust folder OU gpo number Modify description [User] samAccountName userPrincipalName ; ab hier: manuell hinzugefügt distinguishedName logonHours pwdLastSet lastLogonTimestamp employeeID
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.
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:
Im José-Hauptverzeichnis gibt es eine Datei "Standard-Reports.bat". Sie führt automatisiert fünf vordefinierte AD-Reports aus, die für viele Diagnosezwecke nützliche Informationen zusammenstellen. Dabei erzeugt sie die Dateinamen automatisch, indem sie den NetBIOS-Namen der Domäne sowie eine Zufallszahl einfügt. Dadurch kann man die Standard-Reports auch wiederholt ausführen, ohne die vorherigen Daten zu verlieren. Zur Ausführung reichen ein Doppelklick auf "Standard-Reports.bat" sowie etwas Geduld.
Bei der Auswertung verschiedener Objekte oder Attribute 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 Objekten und Attributen 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/Windows 7 und Windows Server 2008 bzw. R2 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 bis Windows Server 2008 R2 finden Sie in diesem Artikel.)
Falls so etwas auftritt, kann man über den Schalter "Erweiterter Berechtigungshinweis" oben rechts bzw. durch den Eintrag "permission" im Abschnitt "[common]" der Definitionsdatei Details zu den nicht lesbaren Objekten ausgeben lassen. Diese Angaben sind dann allerdings ohne Gewähr, weil José keine weitere Überprüfung anstellt, warum er Daten nicht lesen konnte.
Die freie Weitergabe des Programms ist erlaubt. Ebenso ist es erlaubt, den Quelltext zu ändern. Die Autoren dieses Programms übernehmen allerdings keinerlei Gewähr oder Support!
© 2002-2014 Nils Kaczenski, Nils Weinhold und Ansgar Wiechers - Freie Weitergabe erlaubt, keine Gewähr!