Schritt für Schritt Anleitung

Installieren des Matrix42 PreOS Package Editors

Das Matrix42 PreOS Package Editor Paket 1.0 ist Teil des Matrix42 Empirum v18.0 Releases. Nach dem Empirum Installation bzw. Update kann das Paket wie üblich über die Matrix42 Management Console in der Administration einem Computer zugewiesen und die Installation aktiviert werden.

Die aktuelle Version Matrix42 PreOS Package Editor Paket ist Teil des WinPE PreBoot Support Pakets und ist über den Matrix42 Marketplace erhältlich.

Nach der Installation des WinPE PreBoot Support Pakets liegt das Matrix42 PreOS Package Editor Paket im Configurator$\PackageStore Verzeichnis des Empirum-Servers und kann wie üblich mit Hilfe der Matrix42 Management Console in der Depot-Konfiguration importiert werden.

Starten des Matrix42 PreOS Package Editors

Mit der Installation des Matrix42 PreOS Package Editor Pakets wird eine Verknüpfung auf dem Desktop angelegt, mit dessen Hilfe der Editor geöffnet werden kann.

Der Matrix42 PreOS Package Editor ist ein PowerShell ISE Add-On Tool. Beim Starten des Editors wird somit die PowerShell ISE Anwendung geöffnet, die den Matrix42 PreOS Package Editor mit öffnet.

Das Add-On Tool wird automatisch geladen, wenn man das PowerShell ISE startet.

Im Dateimenü unter Add-Ons sieht man den Eintrag zum OS Package Editor.

Erstellen eines neuen PreOS Paketes

Um ein neues PreOS-Paket zu erstellen benötigt man nicht viel. Über die Schaltfläche "New" ist es rasch erledigt. Man erstellt damit eine Struktur für das neue PreOS Paket und muss die Werte Name, Vendor, Version und Description angeben und das Paket mit "Save" abspeichern.

• Über die Schaltfläche "New" wird eine neue, leere Paket-Struktur angelegt.
• Werte für Name, Vendor, Version und Description angeben.
• Über die Schaltfläche "Save" das Paket und damit auch die Paket-Informationen abspeichern.

Beim ersten Speichern öffnet sich der Ordnerauswahl Dialog, damit das Arbeitsverzeichnis, wo das neue Paket gespeichert werden soll, ausgewählt werden kann.

Im ausgewählten Ordner wird die benötigte Ordner-Struktur des neuen Pakets angelegt. Generell besteht ein PreOS-Paket aus einer mehrschichtigen Ordnerstruktur mit zwei fundamentalen Dateien darin. Die Datei EmpirumPackageData.xml enthält alle Informationen zu einem Paket, sowie die zugehörigen Empirum-Variablen und liegt auf der höchsten Ebene - direkt im Paket-Ordner.

Darunter findet man im Ordner Data einen Ordner mit dem Namen des Herstellers (engl. Vendor) - in unserem Beispiel ist es "Matrix42". Unterhalb des Herstellers befindet sich nun der eigentliche PreOS-Paket-Ordner mit dem Namen des Pakets. Dieser und der oberste Ordner haben meistens den gleichen Namen. Hier im Beispiel ist es "WindowsInstallation". Im inneren Paket Ordner befinden sich alle zum Ausführen des Paketes benötigten Dateien, also Massendaten und ein "Install" Ordner.

In diesem Beispiel ist es einer Readme.txt für den Paket-Benutzer, eine unattend.xml für die automatische/unbeaufsichtigte Betriebssystem-Installation und eine EmpirumAgent.bat für die Installation des Matrix42 Empirum Agenten direkt nach der Windows-Installation. Und schließlich findet man im Install Ordner das Bindeglied für alle diese Massendaten und die Paket-Logik an sich, das PowerShell-Skript Install.ps1.

Nach Namenskonvention muss im "Install" Ordner ein Install.ps1 Skript liegen, das zur WinPE-Laufzeit ausgeführt wird. In diesem Fall ist es ein Skript, das auf Empirum-Variablen für den Client-Computer zugreift, die unattend.xml für die Windows-Installation vorbereitet und die Installation durchführt.

Somit erstellt man all das - außer der Massendaten - durch das Abspeichern des neuen Pakets über die Save Schaltfläche. Diese Struktur wird nun im ausgewählten Arbeitsverzeichnis erstellt.

Es wird, wie man erkennen kann, eine neue UUID für das neue Paket generiert und angezeigt. Alle sichtbaren Paketinformationen können nach dem Speichern noch angepasst und verändert werden. Die Ordner-Struktur des Pakets wird, je nach Änderung, angepasst.

Hat man alle Angaben gemacht, das Arbeitsverzeichnis ausgewählt und das Paket abgespeichert, wird auch die neu erstellte Install.ps1 Datei als neuer Tab im PowerShell ISE Editor geöffnet und kann nun bearbeitet werden. Die ersten Zeilen zum Paket sind darin als Kommentar zu erkennen.

Danach folgt eine grobe Struktur eines PreOS Paket-Skriptes. Generell sollte es aus PowerShell-Funktionen bestehen und einen direkten Aufruf beinhalten. Wie es in den Kommentaren des neuen Skriptes steht, ist es außerdem wichtig, dass ein Exit-Code im Falle eines Fehlers zurückgegeben wird. Der PE-Agent orientiert sich beim Ausführen der PreOS-Pakete daran und erkennt bei einem Exit-Code größer Null ein fehlgeschlagenes Paket.

Wenn kein Exit-Code oder der Code 0 mit dem "Exit" Befehl zurückgegeben wird, dann wird die Ausführung des Paketes als erfolgreich markiert, sogar wenn es zu Fehlern innerhalb des Paketes kommt, die weder behandelt noch abgefangen wurden. Diese kann man immer noch in der Logdatei, die bei der Ausführung geschrieben wird, sehen.

Jedoch wird das Paket in Empirum nicht als fehlgeschlagen markiert und der PE-Agent stoppt nicht die Ausführung, sondern fährt mit den nächsten zugeordneten Paketen fort.

Im Skript des neu erstellten Paketes ist dies als Vorlage umgesetzt: Man sieht eine "Main" Funktion, die etwas umsetzt - die Logik des Paketes. Darin wird ein try-catch-Block benutzt und bei Ausnahme-Fehlern wird im Catch-Block die ebenfalls vorhandene Funktion "ExitWithCodeMessage" mit einem Fehler-Code und einer Nachricht aufgerufen.

In der Funktion selbst sieht man, dass dort die Fehlermeldung mit Write-Error ausgegeben wird (das landet genauso wie die Write-Host-Aufrufe in der Log-Datei bei der Ausführung durch den PE-Agenten) und mit "Exit" der angegeben Error-Code zurückgegeben wird und die Ausführung des Skriptes damit auch endet.

Ganz unten folgt dann der sogenannte Entry-Point oder Einsprungspunkt - dort wird eben die "Main"-Funktion aufgerufen. Damit beginnt das Paket-Skript zu arbeiten. Wie auch immer die Implementierung des Skriptes umgesetzt wird, wichtig ist, dass man Fehler erkennt bzw. behandelt und im Fehlerfall mit "Exit" einen Fehlercode zurückgibt, damit der PE-Agent die Ausführung anhalten kann.

Der Kreativität und dem Einsatz sind keine Grenzen gesetzt. Alles was auf einem Client zu WinPE-Zeit ausgeführt und in Erfahrung gebracht werden kann, kann im Install.ps1-Skript umgesetzt werden.

Das Install.ps1-Skript kann und soll nun mit den Bord-Mitteln des PowerShell ISE bearbeitet und abgespeichert werden. Es wird jedoch auch abgespeichert, wenn man die Schaltfläche Save des OS Package Editor Add-On Tools betätigt.

In unserem Beispiel haben wir den Desktop-Ordner als Arbeitsverzeichnis ausgewählt und ein PreOS-Paket Namens SamplePreOsPackage erstellt.

Mit der Schaltfläche "Save To" kann man nun auch eine Kopie des aktuellen PreOS-Paketes erstellen bzw. an einem anderen Ort abspeichern.

Betätig man "Save To", wird der Browserauswahl-Dialog angezeigt und das neue (Ziel-) Arbeitsverzeichnis muss ausgewählt werden. Das Original bleibt hierbei als Kopie an seiner aktuellen Stelle.

Öffnen eines bestehenden PreOS Paketes

PreOS-Pakete lassen sich zur Bearbeitung oder auch nur zur Ansicht öffnen. Im OS Package Editor erreicht man das über die Schaltfläche "Open".

Dabei muss man die entsprechende EmpirumPackageData.xml eines PreOS-Paketes auswählen und mit OK bestätigen.

Daraufhin werden die Informationen des Paketes - die Metadaten - in der Maske angezeigt und das Install.ps1-Skript ist zum Bearbeiten im ISE-Editor geöffnet.

Ändern der Paket-Informationen

Es kann der Paket-Name, der Vendor (Hersteller), die Version und die Paket-Description (Beschreibung) geändert werden. In den entsprechenden Eingabefeldern können die Änderungen durchgeführt werden.

Speichern der Änderungen der Paket-Informationen

Über die Schaltfläche "Save" speichert man die Änderungen der Paketinformationen ab. Da sich die Paket-Informationen Name, Vendor und Version in der Ordnerstruktur spiegeln, werden beim Ändern der Informationen Ordner umbenannt bzw. verschoben. Eventuelle Massendaten werden mit verschoben. Informationen wie Description oder UUID sind dagegen in der EmpirumPackageData.xml hinterlegt.

Speichern einer Kopie

Über die Schaltfläche "Save As" speichert man das aktuelle Paket (zusammen mit den durchgeführten Änderungen) entweder an einer anderen Stelle, indem man einen anderen Zielordner auswählt, oder unter einem anderen Namen, falls man den Namen des Paketes verändert hat, ab.

Beim Letzteren kann man sowohl im gleichen Ordner neben dem Original Paket die Kopie mit einem anderen Namen als auch die Kopie in einem anderen Verzeichnis ablegen.
Werden weder der Name noch die Version eines Paketes verändert und mit "Save As" in das gleiche Verzeichnis, in dem das Original liegt, gespeichert, wird das Original überschrieben. Beim "Save As" wird eine neue UUID erzeugt und somit wird die Kopie im Sinne von Empirum zu einem eigenen, neuen Software Paket, das importiert werden kann.

Bearbeiten des Paket-Skriptes

Beim Öffnen oder Erstellen eines neuen PreOS-Paketes wird das Steuerungsskript "Install.ps1" in einem neuen Tab im ISE geöffnet. Beim neuen Paket ist dieses Skript leer und enthält allein die Paket-Informationen im Kopf als PowerShell-Kommentare.

Ein Paket-Ersteller kann nun das Skript ganz nach Bedarf implementieren und die nativen Tools des PowerShell ISE dabei verwenden.

Hinzufügen von Paket-Variablen

Zu jedem PreOS-Paket können Empirum-Variablen hinzugefügt werden. Variablen bereits existierender Pakete können angezeigt und entfernt werden. Hierzu muss man auf das Register "Variables" wechseln.

Zum Löschen wählt man eine Variablendefinition und klickt auf "Delete". Im Editor werden im Moment nur die Typen Text, Number und Password unterstützt.

Klickt man auf "Add", öffnet sich ein Fenster, in dem man die neue Variablen Definition eintragen und dem Paket - über Add - hinzufügen kann.

Die so erstellten Variablen werden beim Import des PreOS-Pakets mit importiert und können auf Gruppen generell, oder auf Computern, denen das PreOS-Paket zugewiesen ist, in der Matrix42 Management Console gesetzt werden.

Verwendung von Paket-Variablen im Skript

Öffnet man ein OS-Paket, werden die zugehörigen Paket-Variablen unter dem Register 'Variables' aufgelistet. Am Beispiel des GettingStarted-Pakets wird hier demonstriert, wie man diese Variablen zum Install.ps1-Skript hinzufügen kann. Innerhalb der OS-Pakete werden die zugeordneten Empirum-Variablen über das CMDLet 'Get-EmpirumVariable' abgefragt. Das Gleiche gilt für Paket-Variablen, die per OS-Paket importiert werden.

Um die Variablen-Abfrage an die richtige Position im Skript (links) zu platzieren, muss man zuerst den Cursor in der gewünschten Zeile positionieren. Hier im Beispiel ist es die Zeile 7. Nun hat man entweder die Möglichkeit, rechts auf die gewünschte Variable doppelt zu klicken, oder diese mit einem einfachen Klick zunächst auszuwählen und dann die 'Snip It' Schaltfläche zu verwenden. Das Ergebnis ist identisch.

Einerseits wird das benötigte Code-Schnipsel, das es ermöglicht, die Variable zur Laufzeit abzufragen, in der ausgewählten Zeile im Skript eingefügt, anderseits wird der gleiche Schnipsel auch in die Konsole unten eingefügt, um die Ausführung direkt mal ausprobieren zu können. Darüber hinaus wird der Code-Schnipsel auch in die Zwischenablage kopiert und kann beliebig oft und an beliebiger Stelle im Skript mit STRG+V aus der Zwischenablage eingefügt werden.

Hier im Beispiel wird die Variable namens TextVar vom Typ Text in die siebte Zeile des Skripts per Doppelklick eingefügt. Als Variablenname innerhalb des Skriptes wird initial der Name der Variable selbst verwendet. Hier ist es '$TextVar'. Unten in der Konsole sieht man zudem das gleiche Code-Schnipsel.

$TextVar = Get-EmpirumVariable -Property GettingStarted.TextVar

Zusätzlich fügen wir hier im Beispiel noch eine Variable vom Typ Password ein - hier trägt die Paketvariable den Namen Password und wird als Variable $Password im Skript initialisiert.

$Password = Get-EmpirumVariable -Property GettingStarted.Password -Decrypt

Bei einer Passwort Variablen wird zusätzlich der Switch '-Decrypt' verwendet, um das Password im Klartext auszugeben. Hierbei handelt es sich um die entschlüsselte SYNC-Variante des Passwords. Möchte man die verschlüsselte Darstellung einer Passwort Variablen, muss man den Postfix '_SYNC' an den Namen der Variable hängen - ohne den '-Decrypt'-Switch.

$Password = Get-EmpirumVariable -Property GettingStarted.Password_SYNC

Speichern der Änderungen des Paket-Skripts

Das Install.ps1-Skript ist im Rahmen des PowerShell ISE geöffnet und Änderungen können über Menü > Datei ordentlich gespeichert werden. Zusätzlich werden die Änderungen am Skript auch über die Save Schaltfläche des Add-On Tools gespeichert.

Hinzufügen von zusätzlichen Dateien

Erstellt man ein neues Paket, befindet sich initial nur ein Install.ps1-Skript in einem Install Ordner. Man kann allerdings noch weitere Dateien dem Paket hinzufügen, auf die dann auch während der Ausführung des Pakets zugriffen werden kann. Wenn man weitere Dateien ins Paket einbinden möchte, kann man das unter dem Register "Files" vornehmen.

Symboldefinition:

•  Hauptknoten, der das Paketverzeichnis im Massendatenverzeichnis repräsentiert (z.B. Data\Matrix42\OsPackages\WindowsInstallation\3.4). Die untergeordneten zusätzlichen Dateien werden beim Importieren des PreOS Pakets ebenfalls in die entsprechende Configurator$-Freigabe kopiert und stehen während der Paketausführung zur Verfügung.
•  Zusätzlicher Ordner
•  Zusätzliche Datei
•  Nicht löschbare zusätzliche Dateien oder Ordner. Sie sind wesentlicher Bestandteil des PreOS Pakets und dürfen nicht gelöscht werden.

Hier werden die bereits vorhandenen Dateien in einer Baum-Struktur aufgelistet. Über die Schaltfläche "Add" kann man weitere Dateien (keine Ordner) zum Paket hinzufügen. In den meisten ausgelieferten Paketen sieht man dort die Readme.txt Datei und den Install Ordner mit dem Install.ps1-Skript darunter. Diese sind mit einem blauen Schloss-Symbol hinterlegt. Das bedeutet, sie können nicht gelöscht werden und es dürfen zum Install Ordner keine weiteren Dateien hinzugefügt werden. Des Weiteren kann man unterhalb des Install Ordners auch keine weiteren Ordner anlegen.

Zum Löschen einer Datei oder Verzeichnisses, wählt man zunächst die Datei oder das Verzeichnis in der Baumstruktur aus und verwendet dann die Schaltfläche Delete.

Möchte man neue Unterordner anlegen, kann man das über die Schaltfläche "New Folder" auf der rechten Seite durchführen. Dabei wird zunächst ein neuer Unterordner in dem auswählten Verzeichnis mit dem Namen "New Folder" angelegt, der im Anschluss umbenannt werden kann.

Zum Anlegen eines Unterordners auf der obersten Eben, muss man den Hauptknoten auswählen und dann die Schaltfläche "New Folder" verwenden.

HTTP(S) Unterstützung bei selbsterstellten PreOS Paketen

Eventuell sind selbst erstellte PreOS Pakete nicht sofort für den http(s) Transport geeignet. Der Grund dafür ist meistens, dass in den PowerShell-Skripten auf Dateien oder Verzeichnisse auf den Empirum-Share im SMB Fall zugegriffen werden, die nicht Teil des PreOS Paketes selbst sind.

Um die Anpassungen zu erleichtern, soll an dieser Stelle auf bestimmte Eigenheiten beim http(s) Transfer eingegangen werden.

• Generell wird im http(s) Fall mit lokalem Cache gearbeitet. Dateien und Verzeichnisse werden von der Empirum-Freigabe über http(s) in lokale Verzeichnisse transferiert. Es werden nicht alle Freigaben automatisch transferiert, sondern nur Verzeichnisse und Dateien, die angefragt werden.
• Im http(s) Fall wird vor der Ausführung des PreOS Paketes, der Inhalt des Paketes (z.B. wird im Fall des WindowsInstallation PreOS Paketes das Verzeichnis Configurator$\Packages\Matrix42\OsPackages\WindowsInstallation\5.0) zunächst lokal in ein Cache-Verzeichnis übertragen und im Anschluss das install.ps1 Skript lokal ausgeführt. Relative Zugriffe auf Dateien, die sich im Paket befinden, sind somit abgedeckt.
• Muss in einem PreOS Paket auf Dateien zugegriffen werden, die nicht in dem Paketverzeichnis vorhanden sind, muss dies über das Cmdlet Get-EmpirumPackagePath stattfinden. Die Methode wurde bereits in der Vergangenheit verwendet, um den Pfad auf die Empirum-Freigabe (oder das Offline Medium) zu bekommen. Diese Methode muss im http(s) Fall die angegebene Datei oder das Verzeichnis zunächst lokal in ein Cache-Verzeichnis übertragen und im Anschluss den lokalen Pfad zurückgeben. Das PreOS Paket kann somit mit dem lokalen Pfad weiterarbeiten und auf die Datei oder das Verzeichnis zugreifen.
• Das Cmdlet Get-EmpirumAgentSetting -PeAgentConfig RemoteLogFolder kann im http(s) nicht verwendet werden, um Log-Dateien auf der Empirum-Freigabe zu ändern. Für diese Zwecke wird das neue Cmdlet Get-EmpirumTransfer zur Verfügung gestellt. Mit dem Aufruf Get-EmpirumTransfer LogFolder -Type RemoteLogFolder, kann vergleichbar dem Get-EmpirumPackagePath Aufruf, das EmpInst$\Wizard\OS\WinPeStatus Unterverzeichnis lokal transferiert werden. Die Methode gibt ein Objekt zurück, mit dessen Hilfe über die Path-Eigenschaft auf den Pfad zum lokalen Cache zugegriffen werden kann. Das PreOS Skript kann nach den Anpassungen der Dateien im Cache das Synchronisieren der lokalen Dateien zum Server über die Methode Sync veranlassen. Dabei werden die lokalen Änderungen auf den Server übertragen.

Hier ein Beispiel aus dem HardwareInfo PreOS Paket:

$RemoteFolderObject = Get-EmpirumTransfer LogFolder -Type RemoteLogFolder -Verbose;

…

CreateAndCopyDriverJson $RemoteFolderObject.Path;

$RemoteFolderObject.Sync();