Open Source · dbatools

dbatools installieren und sicher verbinden

Der erste Befehl nach der Installation ist oft auch die erste Fehlermeldung: Certificate failed chain validation. Seit Version 2 verschlüsselt dbatools jede Verbindung und prüft dabei das Zertifikat des Servers. Die meisten SQL Server haben aber kein Zertifikat, dem der Client vertraut.

Geprüft mit dbatools 2.9.1 am 17.11.2026 · ca. 12 Minuten

Teil 1 · EinstiegGeprüft mit dbatools 2.9.1Lab Linux · Windows
Die erste Verbindung seit Version 2Connect-DbaInstanceohne ZusatzZertifikatsfehler-TrustServerCertificateverschlüsseltSet-DbatoolsInsecureConnectionunverschlüsselt, dauerhaftZertifikat auf dem Serververschlüsselt, geprüftverschlüsseltunverschlüsseltZertifikat abgelehnt

Die schnellste Abhilfe, die man dafür findet, heißt Set-DbatoolsInsecureConnection. Sie wirkt sofort. In unserem Lab hat sie aber auch die Verschlüsselung abgeschaltet, und zwar über die Sitzung hinaus. Diese Seite zeigt die Installation, die Signaturprüfung und die Wege durch den Zertifikatsfehler, jeweils mit dem, was im Lab tatsächlich passiert ist.

In 60 Sekunden

  • Installieren: Install-Module dbatools -Scope CurrentUser holt dbatools und die Bibliothek dbatools.library. Unter Linux und macOS braucht es PowerShell 7.4 oder neuer. Halten Sie die Version fest, statt blind zu aktualisieren.
  • Signatur: Seit Version 2.5.5 ist dbatools über Azure Trusted Signing signiert. Prüfen lässt sich das mit Get-AuthenticodeSignature, aber nur unter Windows. Unter Linux gibt es den Befehl nicht; dort bleibt der Vergleich der Prüfsumme mit der PowerShell Gallery.
  • Der Zertifikatsfehler ist Absicht. Seit Version 2 gilt: verschlüsseln und Zertifikat prüfen. Gegen ein selbstsigniertes Zertifikat scheiterte die Verbindung auf SQL Server 2017, 2019, 2022 und 2025 gleich, unter Windows auch mit Windows-Anmeldung gegen die lokale Instanz.
  • -TrustServerCertificate je Verbindung vertraut dem Zertifikat und bleibt verschlüsselt. Im Lab meldete SQL Server encrypt_option = TRUE.
  • Set-DbatoolsInsecureConnection schaltet die Verschlüsselung ab (encrypt_option = FALSE) und gilt ohne -SessionOnly dauerhaft für den Benutzer. Unter Windows entfernte Unregister-DbatoolsConfig es wieder, unter Linux nur mit -Scope FileUserLocal.
  • -AllowTrustServerCertificate soll erst normal verbinden und nur bei einem Zertifikatsfehler vertrauen. Im Lab griff dieser zweite Versuch nie.
  • Achten Sie auf Warnungen. Get-DbaDatabase lieferte bei gescheiterter Verbindung null Datenbanken und zwei Warnungen, aber keinen Fehler.

1 · Installieren

dbatools liegt in der PowerShell Gallery. Unter Windows reicht laut Projekt Windows PowerShell 3 oder neuer, unter Linux und macOS braucht es PowerShell 7.4 oder neuer. Die Installation für den eigenen Benutzer braucht keine Administratorrechte:

# Bestimmte Version für den aktuellen Benutzer installieren
Install-Module dbatools -RequiredVersion 2.9.1 -Scope CurrentUser

# Was ist installiert?
Get-Module dbatools, dbatools.library -ListAvailable | Select-Object Name, Version

Seit Version 2 gehört das Modul dbatools.library dazu. Es enthält die .NET-Bibliotheken, die dbatools nutzt, darunter SMO und den Treiber Microsoft.Data.SqlClient. Install-Module dbatools holt es automatisch; dbatools 2.9.1 verlangt dbatools.library 2026.9.14 oder neuer. Es ist der größere Teil: entpackt 304 MB gegenüber 31 MB für dbatools selbst.

Version festhalten. Ein neues Release kann Standardwerte und Parameter ändern; Version 2.8.0 etwa hat die Parameterform von Install-DbaMaintenanceSolution geändert. Installieren Sie auf Servern und in Pipelines eine bestimmte Version, aktualisieren Sie bewusst, und testen Sie Ihre Skripte vorher.

Ohne Internet: Laut Projekt lädt man das Modul auf einem Rechner mit Internet mit Save-Module dbatools -Path <Ordner> und kopiert den Ordner auf dem Zielrechner in einen Modulordner. Das README nennt C:\Program Files\WindowsPowerShell\Modules für alle Benutzer und $HOME\Documents\WindowsPowerShell\Modules für den eigenen; allgemein gilt jeder Pfad aus $env:PSModulePath. Für unser Lab haben wir die beiden Pakete direkt von der Gallery geladen, ihre Prüfsummen mit den dort angegebenen verglichen und sie dann in den Container eingehängt. Der Import dauerte 6,2 Sekunden und gab keine Warnung aus.

2 · Signatur prüfen

dbatools ist seit Version 2.5.5 über Azure Trusted Signing signiert, vorher mit einem Zertifikat von DigiCert. Weil Aussteller und Wurzelzertifikat gewechselt haben, verlangt PowerShellGet laut den Maintainern beim Wechsel von einer älteren Version einmalig -SkipPublisherCheck. Danach sollten Sie die Signatur der installierten Dateien selbst prüfen:

# Nur unter Windows: Signaturstatus aller Moduldateien zählen
$m = Get-Module dbatools -ListAvailable | Sort-Object Version -Descending | Select-Object -First 1
Get-ChildItem (Split-Path $m.Path) -Recurse -File -Include *.ps1, *.psm1, *.psd1, *.dll |
    Get-AuthenticodeSignature | Group-Object Status | Select-Object Name, Count

Unsere Prüfung am 13.11.2026 lief unter Windows PowerShell über beide Module. Alle signierten Dateien hatten den Status Valid. Zwei Kopien einer mitgelieferten Drittbibliothek (Bogus.dll) waren NotSigned. Signiert hat CN=dbatools, O=dbatools, L=Vienna, S=Virginia, C=US, ausgestellt von CN=Microsoft ID Verified CS EOC CA 04.

Das Signaturzertifikat von dbatools 2.9.1 war nur bis zum 17.10.2026 gültig. Die Signatur bleibt trotzdem gültig, weil sie einen Zeitstempel trägt; ohne Zeitstempel würde sie mit dem Zertifikat ablaufen (Microsoft). Unter Windows zeigte Get-AuthenticodeSignature am 17.11.2026, einen Monat nach Ablauf, weiterhin Valid. Laut den Maintainern wechselt das Zertifikat bei Azure Trusted Signing täglich. Wer mit den Ausführungsrichtlinien AllSigned oder RemoteSigned arbeitet, muss dem Herausgeber nach Updates deshalb unter Umständen erneut vertrauen. Das haben wir nicht nachgestellt.

Unter Linux gibt es Get-AuthenticodeSignature nicht; Microsoft führt den Befehl als nur unter Windows verfügbar. PowerShell meldet, der Befehl sei unbekannt (… is not recognized as a name of a cmdlet …). Dort bleibt der Vergleich der Prüfsumme des Pakets mit dem Wert auf der Gallery-Seite, oder Sie prüfen die Signatur einmal unter Windows und verteilen dann genau diese Dateien.

3 · Warum die erste Verbindung scheitert

dbatools folgt den Vorgaben des Treibers Microsoft.Data.SqlClient. Dass das Zertifikat des Servers gültig sein muss (TrustServerCertificate=False), gilt laut den Maintainern schon seit dbatools 1.1. Mit Version 2.0 kam die Verschlüsselung als Vorgabe dazu (Encrypt=True), die Microsoft mit SqlClient 4.0 eingeführt hatte (Release Notes 4.0). Ein SQL Server ohne eigenes, vertrauenswürdiges Zertifikat erzeugt laut Microsoft beim Start ein selbstsigniertes. Diesem vertraut der Client nicht, und sein Name passt meist auch nicht zum Servernamen. In unserem Lab sah das so aus:

$cred = Get-Credential sa
Connect-DbaInstance -SqlInstance sql2022 -SqlCredential $cred
Ausgabe im Lab
Error connecting to [sql2022]: Certificate failed chain validation. Error(s): 'self-signed certificate, [Status: UntrustedRoot]
'.
Certificate name mismatch. The provided 'DataSource' or 'HostNameInCertificate' does not match the name in the certificate.

Darunter steht die Meldung des Treibers: A connection was successfully established with the server, but then an error occurred during the pre-login handshake. Die Verbindung kam also zustande. Gescheitert ist sie erst an der Prüfung des Zertifikats. SQL Server 2017, 2019, 2022 und 2025 verhielten sich gleich. Es ist also kein Versionsproblem, sondern die gewollte Vorgabe.

Die meisten Befehle werfen keinen Fehler. Connect-DbaInstance bricht standardmäßig ab. Andere Befehle wie Get-DbaDatabase geben nur eine Warnung aus und machen weiter:

Get-DbaDatabase -SqlInstance sql2022 -SqlCredential $cred
Ausgabe im Lab
[06:19:33][Connect-DbaInstance] Failure | Error connecting to [sql2022]: Certificate failed chain validation. …
[06:19:33][Get-DbaDatabase] Failure | Certificate failed chain validation. …

Das sind die beiden Warnungen, gekürzt. Unter Windows, mit Windows-Anmeldung gegen die lokale Instanz eines frisch installierten SQL Server 2022, lautete der Grund The certificate chain was issued by an authority that is not trusted. Auch dort gab es zwei Warnungen und null Treffer. Zurück kamen null Datenbanken. Ein Skript, das nur auf Fehler prüft, liest das als „keine Datenbanken“. Viele Befehle haben den Schalter -EnableException, der aus der Warnung einen Fehler macht; für Skripte ist das die sichere Wahl. Bei Connect-DbaInstance ist es umgekehrt: Der Befehl wirft von sich aus, -DisableException macht daraus eine Warnung.

4 · Drei Wege durch den Zertifikatsfehler

WegVerschlüsselt?Wirkt fürWann
Richtiges Zertifikat auf dem Server (vertrauenswürdige Stelle, passender Name)ja, geprüftalle ClientsProduktion
-TrustServerCertificate beim Verbindenja, ohne Prüfung des Zertifikatsdiese eine VerbindungLabor, Test, Übergang
Set-DbatoolsInsecureConnectionneinalle Verbindungen des Benutzers, dauerhaft; mit -SessionOnly nur die Sitzungnicht empfohlen

Im Lab haben wir jede Variante gegen alle vier Versionen probiert. Die Spalte encrypt_option stammt aus sys.dm_exec_connections der jeweiligen Verbindung:

Aufruf von Connect-DbaInstance2017201920222025encrypt_option
ohne ZusatzFehlerFehlerFehlerFehler–
-TrustServerCertificateokokokokTRUE
-AllowTrustServerCertificateFehlerFehlerFehlerFehler–
-EncryptConnection:$falseokokokokFALSE
nach Set-DbatoolsInsecureConnectionokokokokFALSE

Die letzte Zeile haben wir gegen 2022 gemessen. Unter Windows, mit Windows PowerShell 5.1 und Windows-Anmeldung, zeigte -TrustServerCertificate dasselbe: encrypt_option = TRUE, angemeldet über NTLM.

Produktion: ein richtiges Zertifikat

Auf Dauer gehört auf den Server ein Zertifikat, dem die Clients vertrauen und dessen Name zum Verbindungsnamen passt. Dann funktionieren die Vorgaben ohne jeden Zusatz. Die Maintainer nennen dafür eigene Befehle, etwa New-DbaComputerCertificate, Set-DbaNetworkCertificate und Enable-DbaForceNetworkEncryption; sie richten das Zertifikat auf Windows-Servern ein. Unter Linux richtet man es mit mssql-conf ein. Beides haben wir nicht im Lab aufgebaut.

Labor: -TrustServerCertificate je Verbindung

Die Verbindung bleibt verschlüsselt, nur die Prüfung des Zertifikats entfällt. Öffnen Sie die Verbindung einmal und geben Sie das Verbindungsobjekt an die folgenden Befehle weiter:

$cred = Get-Credential sa
$s = Connect-DbaInstance -SqlInstance sql2022 -SqlCredential $cred -TrustServerCertificate

Get-DbaDatabase -SqlInstance $s                 # nutzt die offene Verbindung
$s.Query("SELECT encrypt_option FROM sys.dm_exec_connections WHERE session_id = @@SPID")

Im Lab kamen die vier Systemdatenbanken zurück, und encrypt_option stand auf TRUE.

Eine Ausnahme: Manche Befehle bauen intern eine neue Verbindung über den Instanznamen auf und übernehmen dabei das Vertrauen des Verbindungsobjekts nicht. Bei Test-DbaLastBackup war das so (Teil 4). Dort hilft die Konfiguration nur für die laufende Sitzung:

# Nur diese PowerShell-Sitzung: Zertifikat nicht prüfen, Verschlüsselung bleibt an
Set-DbatoolsConfig -FullName sql.connection.trustcert -Value $true

Set-DbatoolsConfig allein speichert nichts. Dauerhaft wird ein Wert erst mit Register-DbatoolsConfig; genau das tut Set-DbatoolsInsecureConnection ohne -SessionOnly (Quelltext 2.9.1). Im Lab blieb die Verbindung mit dieser Einstellung verschlüsselt.

5 · Was Set-DbatoolsInsecureConnection wirklich tut

Der Befehl setzt zwei Werte: sql.connection.trustcert auf true und sql.connection.encrypt auf false. Der zweite Wert ist der, den man leicht übersieht. Wir haben in sechs aufeinanderfolgenden PowerShell-Sitzungen desselben Benutzers gemessen, jeweils mit einer Verbindung ohne Zusatz gegen SQL Server 2022:

SchrittKonfiguration danachVerbindung ohne Zusatz
Set-DbatoolsInsecureConnection -SessionOnlyencrypt aus, trustcert anok, unverschlüsselt
neue SitzungVorgaben zurückZertifikatsfehler
Set-DbatoolsInsecureConnectionencrypt aus, trustcert anok, unverschlüsselt
neue Sitzungencrypt aus, trustcert anok, unverschlüsselt: gilt weiter
Unregister-DbatoolsConfig … -Scope FileUserLocalDatei gelöscht–
neue SitzungVorgaben zurückZertifikatsfehler
Set-DbatoolsInsecureConnection in sechs Sitzungen, Verbindung ohne Zusatz gegen SQL Server 2022dauerhaft gespeichert: encrypt ausGespeichert unter Linux in ~/.config/PowerShell/dbatools/psf_config.json, unter Windows in derRegistrierung des Benutzers1Unsicher, nurSitzung-SessionOnlyok,unverschlüsselt2Neue SitzungZertifikatsfehler3Unsicher,dauerhaftohne -SessionOnlyok,unverschlüsselt4Neue Sitzungunverschlüsselt:gilt weiter5RückwegUnregister-…–Datei gelöscht6Neue SitzungZertifikatsfehler
Set-DbatoolsInsecureConnection in sechsSitzungen, Verbindung ohne Zusatz gegen SQLServer 2022dauerhaft gespeichert1Unsicher, nur Sitzung -SessionOnlyok, unverschlüsselt2Neue SitzungZertifikatsfehler3Unsicher, dauerhaft ohne -SessionOnlyok, unverschlüsselt4Neue Sitzungunverschlüsselt: gilt weiter5Rückweg Unregister-…Datei gelöscht–6Neue SitzungZertifikatsfehlerLinux: psf_config.json im Benutzerprofil ·Windows: Registrierung des Benutzers
Was nach Set-DbatoolsInsecureConnection in den folgenden Sitzungen desselben Benutzers galt. Gemessen unter Linux; unter Windows verhielt es sich gleich, dort genügte für den Rückweg der Befehl ohne -Scope.

Auch -SessionOnly schaltet also die Verschlüsselung ab, nur eben nicht dauerhaft. Unter Linux speichert dbatools die dauerhafte Einstellung in ~/.config/PowerShell/dbatools/psf_config.json:

[
  {
    "Type": 2,
    "Style": "default",
    "Version": 1,
    "Value": "false",
    "FullName": "sql.connection.encrypt"
  },
  {
    "Type": 2,
    "Style": "default",
    "Version": 1,
    "Value": "true",
    "FullName": "sql.connection.trustcert"
  }
]

Rückweg unter Linux:

Unregister-DbatoolsConfig -FullName sql.connection.trustcert, sql.connection.encrypt -Scope FileUserLocal

Ohne -Scope scheiterte derselbe Befehl unter Linux mit einer Meldung, die nicht auf die Ursache hinweist:

Ausgabe im Lab
Cannot process argument transformation on parameter 'EnableException'. Cannot convert value "" to type "System.Boolean". Boolean parameters accept only Boolean values and numbers, such as $True, $False, 1 or 0.

Mit -Scope FileUserShared lief er ohne Fehler durch, die Datei blieb aber stehen.

Unter Windows schreibt dbatools die dauerhafte Einstellung in die Registrierung des Benutzers. Im Lab stand sie unter HKEY_CURRENT_USER\SOFTWARE\Microsoft\WindowsPowerShell\dbatools\Config\Default mit den Werten sql.connection.trustcert und sql.connection.encrypt. Eine neue Sitzung verband sich danach ohne Zusatz und unverschlüsselt (encrypt_option = FALSE). Hier genügte der Befehl ohne -Scope:

Unregister-DbatoolsConfig -FullName sql.connection.trustcert, sql.connection.encrypt

In der nächsten Sitzung galten wieder die Vorgaben: sql.connection.encrypt auf True, sql.connection.trustcert auf False. Für Skripte, die auf beiden Systemen laufen, heißt das: den Rückweg je Betriebssystem prüfen und nicht davon ausgehen, dass er überall gleich aussieht.

Einordnung: Für ein Wegwerf-Labor ist Set-DbatoolsInsecureConnection bequem, und in Diskussionen im Projekt wird es für selbstsignierte Zertifikate auch empfohlen (Beispiel). Wer es benutzt, sollte wissen, dass damit alle späteren Verbindungen dieses Benutzers unverschlüsselt laufen, auch die zu Servern mit gutem Zertifikat. Auf Arbeitsplätzen und Servern, von denen aus Sie Produktion verwalten, gehört es nicht hin.

6 · -AllowTrustServerCertificate: gute Idee, greift im Lab nicht

Seit Ende 2025 hat Connect-DbaInstance den Schalter -AllowTrustServerCertificate, eingeführt auf Wunsch aus der Gemeinschaft (#10006). Die Idee: erst normal verbinden und nur bei einem Zertifikatsfehler einen zweiten Versuch mit Vertrauen starten. Das wäre der ideale Mittelweg für gemischte Umgebungen.

Im Lab scheiterte die Verbindung mit diesem Schalter auf allen vier Versionen genauso wie ohne ihn. Die Ursache steht im Quelltext von 2.9.1 (Connect-DbaInstance.ps1, Zeilen 1434–1439): Der zweite Versuch startet nur, wenn die Fehlermeldung eines der Wörter certificate, SSL, TLS oder trust enthält. Geprüft wird aber nur die äußerste Meldung. Wir haben die Stelle nachgebaut:

Ausgabe im Lab
Exception calling "ExecuteWithResults" with "1" argument(s): "Failed to connect to server sql2022."
  ConnectionFailureException: Failed to connect to server sql2022.
    SqlException: A connection was successfully established with the server, but then an error occurred during the pre-login handshake. …
      AuthenticationException: Certificate failed chain validation. …

Der Hinweis auf das Zertifikat steht erst in der innersten Ausnahme; die äußere Meldung enthält keines der Suchwörter. Unser Client war PowerShell 7 unter Linux mit SqlClient 7.0. Unter Windows haben wir nicht geprüft. Weil die äußere Meldung von SMO und PowerShell stammt, vermuten wir dort dasselbe Verhalten. Stand 16.11.2026 war der Befund im Projekt nicht gemeldet, und die Stelle war in der Entwicklungsfassung unverändert.

Bis das geklärt ist: -AllowTrustServerCertificate nicht als Mittelweg einplanen, sondern bewusst entscheiden: Zertifikat einrichten oder -TrustServerCertificate für genau die Ziele, bei denen Sie das Risiko tragen.

7 · Anmeldedaten

  • -SqlCredential übergibt eine SQL-Anmeldung, -Credential eine Windows-Anmeldung für den Zugriff auf den Host (etwa für Dienste oder Dateien). Ohne -SqlCredential versucht dbatools die Windows-Anmeldung des aktuellen Benutzers.
  • Interaktiv: Get-Credential fragt das Kennwort ab, ohne dass es im Verlauf landet.
  • In Skripten: Unter Windows schützt Export-Clixml ein Anmeldeobjekt mit DPAPI; lesbar ist es nur für denselben Benutzer auf demselben Rechner. Unter Linux und macOS steht das Kennwort im Klartext in der Datei. Laut Microsoft verschlüsselt Export-Clixml Anmeldedaten nur unter Windows. Dort brauchen Sie einen anderen Speicher, etwa einen Tresor wie das Modul SecretManagement mit einem passenden Speicher, oder Dateirechte, die nur den Dienstbenutzer lesen lassen. Im Lab haben wir das nicht nachgestellt.
  • Protokolle: dbatools schreibt Meldungen unter Linux nach ~/.local/share/PowerShell/dbatools/, unter Windows nach %APPDATA%\PowerShell\dbatools\. Das Kennwort unserer SQL-Testanmeldung stand unter Linux in keiner der sieben Dateien. Die Windows-Messung lief mit Windows-Anmeldung und sagt dazu nichts.

8 · Vor dem ersten schreibenden Befehl

  • Hilfe lesen: Get-Help Test-DbaLastBackup -Full zeigt Parameter, Standardwerte und Beispiele, dazu gibt es je Befehl eine Seite unter https://dbatools.io/<Befehl>. Find-DbaCommand sucht Befehle nach Stichwort.
  • Erst -WhatIf: Befehle, die etwas ändern, zeigen mit -WhatIf, was sie tun würden, ohne es zu tun. -Confirm fragt vor jedem Schritt.
  • Erst ein Testziel: Probieren Sie neue Befehle gegen eine Testinstanz oder einen Container, nicht gegen Produktion. Auch lesende Prüfungen können Last erzeugen.
  • Ergebnisse prüfen: Warnungen auswerten oder -EnableException setzen, wo der Befehl es anbietet (Abschnitt 3).

Was wir gemessen haben und was nicht

  • Gemessen (13. und 16.11.2026): dbatools 2.9.1 mit dbatools.library 2026.9.14 (SqlClient 7.0, SMO 18.100) unter PowerShell 7.6.8 in einem Linux-Container; SQL Server 2017 CU31, 2019 CU32, 2022 CU27 und 2025 CU9 in Linux-Containern ohne eigenes Zertifikat. Signaturprüfung unter Windows PowerShell auf einem Arbeitsplatz.
  • Unter Windows gemessen (17.11.2026): dieselben Modulversionen unter Windows PowerShell 5.1 auf Windows Server 2022, als Administrator mit Windows-Anmeldung gegen ein lokales SQL Server 2022 RTM ohne eigenes Zertifikat. Geprüft wurden Signatur (alle signierten Moduldateien Valid), Import, Zertifikatsfehler, -TrustServerCertificate, Set-DbatoolsInsecureConnection mit Ablage und Rückweg.
  • Nicht gemessen: Installation über Install-Module unter Windows, Ausführungsrichtlinien und -SkipPublisherCheck (aus README und Blog der Maintainer); -AllowTrustServerCertificate unter Windows, weil der Messschritt fehlerhaft war; PowerShell 7 unter Windows; ein Server mit Zertifikat einer echten Zertifizierungsstelle; Encrypt=Strict mit TDS 8.0.

Weiterlesen

Weitere Teile der Reihe