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.
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 CurrentUserholt 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.
-TrustServerCertificateje Verbindung vertraut dem Zertifikat und bleibt verschlüsselt. Im Lab meldete SQL Serverencrypt_option = TRUE.Set-DbatoolsInsecureConnectionschaltet die Verschlüsselung ab (encrypt_option = FALSE) und gilt ohne-SessionOnlydauerhaft für den Benutzer. Unter Windows entfernteUnregister-DbatoolsConfiges wieder, unter Linux nur mit-Scope FileUserLocal.-AllowTrustServerCertificatesoll erst normal verbinden und nur bei einem Zertifikatsfehler vertrauen. Im Lab griff dieser zweite Versuch nie.- Achten Sie auf Warnungen.
Get-DbaDatabaselieferte 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, VersionSeit 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, CountUnsere 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 $credError 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[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
| Weg | Verschlüsselt? | Wirkt für | Wann |
|---|---|---|---|
| Richtiges Zertifikat auf dem Server (vertrauenswürdige Stelle, passender Name) | ja, geprüft | alle Clients | Produktion |
-TrustServerCertificate beim Verbinden | ja, ohne Prüfung des Zertifikats | diese eine Verbindung | Labor, Test, Übergang |
Set-DbatoolsInsecureConnection | nein | alle Verbindungen des Benutzers, dauerhaft; mit -SessionOnly nur die Sitzung | nicht 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-DbaInstance | 2017 | 2019 | 2022 | 2025 | encrypt_option |
|---|---|---|---|---|---|
| ohne Zusatz | Fehler | Fehler | Fehler | Fehler | – |
-TrustServerCertificate | ok | ok | ok | ok | TRUE |
-AllowTrustServerCertificate | Fehler | Fehler | Fehler | Fehler | – |
-EncryptConnection:$false | ok | ok | ok | ok | FALSE |
nach Set-DbatoolsInsecureConnection | ok | ok | ok | ok | FALSE |
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 $trueSet-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:
| Schritt | Konfiguration danach | Verbindung ohne Zusatz |
|---|---|---|
Set-DbatoolsInsecureConnection -SessionOnly | encrypt aus, trustcert an | ok, unverschlüsselt |
| neue Sitzung | Vorgaben zurück | Zertifikatsfehler |
Set-DbatoolsInsecureConnection | encrypt aus, trustcert an | ok, unverschlüsselt |
| neue Sitzung | encrypt aus, trustcert an | ok, unverschlüsselt: gilt weiter |
Unregister-DbatoolsConfig … -Scope FileUserLocal | Datei gelöscht | – |
| neue Sitzung | Vorgaben zurück | Zertifikatsfehler |
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 FileUserLocalOhne -Scope scheiterte derselbe Befehl unter Linux mit einer Meldung, die nicht auf die Ursache hinweist:
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.encryptIn 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:
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,-Credentialeine Windows-Anmeldung für den Zugriff auf den Host (etwa für Dienste oder Dateien). Ohne-SqlCredentialversucht dbatools die Windows-Anmeldung des aktuellen Benutzers.- Interaktiv:
Get-Credentialfragt das Kennwort ab, ohne dass es im Verlauf landet. - In Skripten: Unter Windows schützt
Export-Clixmlein 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üsseltExport-ClixmlAnmeldedaten 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 -Fullzeigt Parameter, Standardwerte und Beispiele, dazu gibt es je Befehl eine Seite unterhttps://dbatools.io/<Befehl>.Find-DbaCommandsucht Befehle nach Stichwort. - Erst
-WhatIf: Befehle, die etwas ändern, zeigen mit-WhatIf, was sie tun würden, ohne es zu tun.-Confirmfragt 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
-EnableExceptionsetzen, 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-DbatoolsInsecureConnectionmit Ablage und Rückweg. - Nicht gemessen: Installation über
Install-Moduleunter Windows, Ausführungsrichtlinien und-SkipPublisherCheck(aus README und Blog der Maintainer);-AllowTrustServerCertificateunter Windows, weil der Messschritt fehlerhaft war; PowerShell 7 unter Windows; ein Server mit Zertifikat einer echten Zertifizierungsstelle;Encrypt=Strictmit TDS 8.0.
Weiterlesen
- dbatools: README mit Installation, New defaults for SQL Server connections (Begründung der Vorgaben), dbatools and Azure Trusted Signing, Hilfe zu Set-DbatoolsInsecureConnection.
- Microsoft: Microsoft.Data.SqlClient 4.0, Release Notes (
Encryptstandardmäßig an), Verschlüsselung für SQL Server konfigurieren (selbstsigniertes Ersatzzertifikat), Get-AuthenticodeSignature, Export-Clixml. - Bei PSG: dbatools-Übersicht, Teil 3: Was
Test-Dbawirklich sagt, Teil 4: Backups wirklich prüfen, SQL Server unter Linux für Windows-Admins.