Custom Deployment

Ab der Enterprise-Edition können Sie Zertifikate mit eigenen PowerShell-Skripten auf Ziele verteilen, die TLSPilot nicht nativ unterstützt; die Skripte können auch andere Tools aufrufen, zum Beispiel um sich per SSH mit einem Linux-Server zu verbinden. Beispielskripte für Deployments und Health-Checks finden Sie unter %ProgramData%\iTrain\TLSPilot\Examples\Custom Deployment Script Examples, für FortiGate, Cisco ASA, Cisco FDM und Caddy, jeweils mit einem Deployment-Skript und einem Health-Check-Skript, dazu ein Health-Check-Skript, das den Thumbprint vergleicht. Die Beispiele werden ohne Support bereitgestellt. Für ein Custom Deployment lässt sich jeder Credential-Typ verwenden, für Appliances typischerweise Custom / other. Dieses Beispiel verteilt ein Zertifikat auf Caddy auf einem Linux-Server.

Das Skript läuft auf dem Management-Host unter dem TLSPilot-Dienstkonto, nicht über WinRM; jedes Modul oder Tool, das es verwendet, zum Beispiel ein SSH-Modul, muss deshalb für dieses Konto verfügbar sein. Die Zertifikatsdateien für das Skript werden in einen temporären Ordner geschrieben, der nur existiert, solange das Skript läuft.

1. Klicken Sie auf dem Dashboard auf die Kachel Credentials, um den Credentials Manager zu öffnen, und erstellen Sie wie in Kapitel Nginx beschrieben ein SSH-Credential für das Ziel, vorzugsweise mit einem privaten Schlüssel.
2. Stellen Sie wie in Kapitel Meine ersten Zertifikate beschrieben ein Zertifikat von einem beliebigen Aussteller aus, zum Beispiel «caddy.tlspilotlab.com». Schalten Sie im Schritt Deployments den Schalter Automatic deployment ein und klicken Sie auf Add…
3. Linked service: Wählen Sie Custom Deployment am Ende der Liste.
4. Display name, Target host und Credential: Geben Sie einen Namen für das Deployment und den Namen oder die IP-Adresse des Servers ein und wählen Sie das Credential aus Schritt 1. Braucht Ihr Skript den privaten Schlüssel als Encrypted PEM, geben Sie dafür unter Key password ein Passwort ein.
5. Shell: Wählen Sie Windows PowerShell oder PowerShell 7 (pwsh). Wird pwsh.exe nicht gefunden, verwendet TLSPilot Windows PowerShell.

6. Deployment Script: Geben Sie das Skript ein, das das Zertifikat verteilt. TLSPilot stellt die Variablen $Cert, $Target und $Cred bereit, siehe Kapitel Variablen in eigenen Skripten. Das Deployment schlägt fehl, wenn das Skript mit einem Code ungleich null endet, einen Fehler auslöst oder seine letzte Ausgabe $false ist. Text, der vor diesem $false ausgegeben wird, erscheint im Ergebnis und in der Historie und ändert die Entscheidung nicht. Das Skript darf bis zu 300 Sekunden laufen; danach stoppt TLSPilot es, und das Deployment schlägt mit Custom script timed out after 300s fehl.
   • Bisheriges Zertifikat (optional): TLSPilot kann das Ziel eines Custom Deployments nicht selbst lesen. Um das Zertifikat zu melden, das Ihr Skript ersetzt hat, geben Sie mit Write-Output die Zeile PREVIOUS|<thumbprint> aus, zum Beispiel Write-Output "PREVIOUS|$oldThumbprint". TLSPilot zeigt es als Previous thumbprint im Ergebnis, in der Historie und in der Alert-Mail. Ohne diese Zeile entfällt die Zeile Previous thumbprint. Es zählt die erste Zeile, die mit PREVIOUS| beginnt; die Zeile wird nur beim Deployment-Skript ausgewertet.

7. Health Check Script: Optional geben Sie ein Skript ein, das prüft, ob das Zertifikat verwendet wird. Es kann dieselben Variablen wie das Deployment-Skript verwenden. TLSPilot wertet die letzte Ausgabe des Skripts aus: $true bedeutet Healthy, $false bedeutet Unknown. Eine mit Write-Output ausgegebene Zeile HEALTH|Status|Message, zum Beispiel HEALTH|Drift|Old certificate bound, setzt diesen Status und diese Meldung; bei Drift verteilt der tägliche Zyklus das Zertifikat erneut. Status ist Healthy, Drift, Unknown, Unreachable oder Skipped. Optional ergänzen Sie als viertes Feld den auf dem Ziel gelesenen Thumbprint, zum Beispiel HEALTH|Healthy|Bound|<thumbprint>. Die erste HEALTH|-Zeile hat Vorrang vor $true oder $false. Das Skript darf bis zu 75 Sekunden laufen. Läuft es in einen Timeout, endet es mit einem Code ungleich null, löst es einen Fehler aus oder endet es ohne $true, $false oder eine HEALTH|-Zeile, wird das Ziel als nicht erreichbar gemeldet. Ist das Feld leer, kann TLSPilot auf diesem Ziel keinen Drift erkennen: Der tägliche Zyklus verteilt das Zertifikat, wenn das Ziel nicht das aktuelle Zertifikat hat, und überspringt es sonst. Der Tab des Deployments weist darauf hin.

8. Klicken Sie auf OK, schliessen Sie die übrigen Schritte wie in Kapitel Meine ersten Zertifikate beschrieben ab und stellen Sie das Zertifikat mit Issue now aus.

TLSPilot stellt das Zertifikat aus, führt Ihr Deployment-Skript aus und prüft die Health mit Ihrem Health Check Script. Schlägt das Deployment fehl, zeigt das Ergebnis die Zeile des Skripts, die den Fehler verursacht hat. Um das Skript zu korrigieren, doppelklicken Sie im Tab Deployments des Zertifikats auf das Deployment, nehmen Ihre Änderungen vor und klicken auf OK und Save. Klicken Sie danach mit der rechten Maustaste auf das Zertifikat, wählen Sie Deploy… und bestätigen Sie mit Deploy. Dieses Deployment läuft sofort, unabhängig davon, ob das Zertifikat erneuert wurde. Da das Deployment von Ihrem Skript abhängt und Test (dry run)… für Custom Deployments nicht verfügbar ist, prüfen Sie auf dem Zielsystem, ob das Zertifikat verwendet wird.

Variablen in eigenen Skripten

Im Deployment-Skript und im Health Check Script stehen die folgenden Variablen zur Verfügung:

Zusätzlich stehen Aliasse zur Verfügung: $Certificate, $TargetHost, $Credential, $PfxPath, $Thumbprint, $PemCertPath, $PemKeyPath, $PemBundlePath und $CredentialTarget.

Rückgabewerte des Health Check Script: TLSPilot setzt die Health des Ziels anhand der Ausgabe des Skripts.