Version 2.1.0 der dbatools – Ein Update mit Hindernissen

Das PowerShell-Modul dbatools wird seit vielen Jahren von Administratoren auf der ganzen Welt zur Installation und Verwaltung von SQL Server Instanzen genutzt.

Schaut man auf die Versionshistorie in der PowerShell Gallery, so gab es in diesem Jahr bereits zwei Versionssprünge. Am 28.04.2023 erschien die Version 2.0.0 als Nachfolger der Version 1.1.146, am 21.09.2023 die Version 2.1.0 als Nachfolger der Version 2.0.4.

In jedem Sprung gab es größere Anpassungen, die sowohl Auswirkungen auf die Installation als auch auf die Nutzung des Moduls haben. In diesem Artikel werfen wir einen Blick auf die wichtigsten Änderungen und geben Empfehlungen zur Konfiguration des Moduls. Vorab sei gesagt, dass wir jedem Anwender ein Update auf die aktuelle Version empfehlen.

Ein neues Basis-Modul: dbatools.library

Mit der Version 2.0.0 wurden alle externen Bibliotheken in das separate Modul dbatools.library ausgelagert, da sie nur selten aktualisiert werden. Somit wird das Modul dbatools mit dem PowerShell-Code kleiner und benötigt beim Update weniger Ressourcen. Für den Anwender ist das transparent, das Modul dbatools.library wird automatisch im Hintergrund geladen und aktualisiert. 

Microsoft legt Wert auf Sicherheit: Neue Standardwerte beim Aufbau einer Verbindung

Mit der Version 2.0.0 wurden auch die verwendeten Microsoft-Bibliotheken aktualisiert. Es sind die Gleichen, die auch in der Version 19 des SQL Server Management Studios enthalten sind. In diesen hat Microsoft wichtige Anpassungen für den Verbindungsaufbau vorgenommen. Jetzt wird als Standardwert immer die Option „Encrypt=True“ verwendet und damit eine verschlüsselte Verbindung mit dem SQL Server aufgebaut. Zudem werden mit der Option „Trust Server Certificate=False“ nur noch Zertifikate akzeptiert, die von einer vertrauenswürdigen Zertifizierungsstelle (Certificate Authority, CA) ausgestellt wurden. Das beim Start der SQL Server Instanz erstellte selbst-signierte Zertifikat kann weiterhin verwendet werden. Diesem muss jetzt aber explizit mit der Option „Trust Server Certificate=True“ vertraut werden. Andernfalls schlägt die Verbindung zum SQL Server mit der Meldung „Die Zertifikatkette wurde von einer nicht vertrauenswürdigen Zertifizierungsstelle ausgestellt“ fehl. Auf englischen Systemen lautet die Meldung „The certificate chain was issued by an authority that is not trusted“.

Bei jedem Import des Moduls wird auf diese Änderungen und die Webseite mit weiteren Informationen hingewiesen. Wir empfehlen, die Ausgabe dieser Meldung per Konfiguration zu unterdrücken. Um dies systemweit, also auch für andere Nutzer des Moduls, zu konfigurieren, verwenden Sie den folgenden Befehl:

Set-DbatoolsConfig -FullName Import.EncryptionMessageCheck -Value $false -PassThru | Register-DbatoolsConfig -Scope SystemDefault

Damit wird diese Konfiguration in der Registrierung unter „HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\WindowsPowerShell\dbatools\Config\Default“ abgelegt. Sind Sie der einzige Benutzer auf dem System oder wollen Sie diese Einstellung aus anderen Gründen nur für den aktuellen Benutzer setzen, so verwenden Sie diesen Befehl:

Set-DbatoolsConfig -FullName Import.EncryptionMessageCheck -Value $false –Register

Damit wird diese Konfiguration in der Registrierung unter „HKEY_CURRENT_USER\Software\Microsoft\WindowsPowerShell\dbatools\Config\Default“ abgelegt.

Alles soll bleiben, wie es war: Verwendung der bisherigen Standardwerte

Um die neuen Standardwerte mithilfe einer Konfiguration innerhalb von dbatools durch die alten Werte zu überschreiben, wurde der Befehl Set-DbatoolsInsecureConnection eingeführt. Die Änderungen betreffen nur den aktuellen Nutzer, können aber mit dem Parameter -Scope SystemDefault auch systemweit festgelegt werden.

Wir empfehlen jedoch, die Verschlüsselung eingeschaltet zu lassen und nur den selbst-signierten Zertifikaten zu vertrauen, wenn Sie keine signierten Zertifikate verwenden können. Auch diese Einstellung erfolgt mit Set-DbatoolsConfig, wie bereits weiter oben beschrieben. Der vollständige Name der Konfiguration lautet dabei "sql.connection.trustcert". Damit lautet der Befehl für die von uns empfohlene systemweite Konfiguration wie folgt:

Set-DbatoolsConfig -FullName sql.connection.trustcert -Value $true -PassThru | Register-DbatoolsConfig -Scope SystemDefault

Um die Konfiguration nur für den aktuellen Benutzer zu setzen, verwenden Sie:

Set-DbatoolsConfig -FullName sql.connection.trustcert -Value $true -Register

Mehr Sicherheit auch für Ihre Umgebung: Verwendung von signierten Zertifikaten

Durch die Verwendung von global signierten Zertifikaten kann bei jedem Verbindungsaufbau die Identität des SQL Servers überprüft werden. Zur Erstellung eines geeigneten Zertifikates stellt das Modul dbatools zwar den Befehl New-DbaComputerCertificate bereit, in vielen Unternehmen gibt es jedoch einen individuellen Weg, diese Zertifikate zu generieren. Der Import des Zertifikates kann entweder mit dem Befehl Add-DbaComputerCertificate oder einem in Ihrem Unternehmen vorgesehenen Weg erfolgen. Bitte sprechen Sie daher im Vorfeld mit Ihren Systemadministratoren. Wenn dbatools für die Erstellung der Zertifikate verwendet wird, besteht die Möglichkeit, die Zertifikate direkt durch die CA des Active Directory signieren zu lassen.

Die Einrichtung des Zertifikats kann dann entweder mit dem Befehl Set-DbaNetworkCertificate oder mit dem SQL Server Configuration Manager erfolgen. Wenn Sie hierbei Unterstützung benötigen, sprechen Sie uns gerne an.

Update-Module schlägt fehl: Ein neues Zertifikat für dbatools erfordert einmalig etwas mehr Aufwand

Das Modul dbatools ist, wie viele Softwareprodukte und auch einige andere PowerShell-Module, digital signiert. Mit dieser Signatur können Sie sicherstellen, dass der bei Ihnen ausgeführte Code nicht nachträglich manipuliert wurde.

Die Anforderungen an das zur Signierung verwendete Zertifikat haben sich am 01.06.2023 geändert, auf den Webseiten der Zertifizierungsstellen ist nun diese Information zu lesen: „Starting on June 1, 2023, at 00:00 UTC, industry standards will require private keys for standard code signing certificates to be stored on hardware certified as FIPS 140 Level 2, Common Criteria EAL 4+, or equivalent. This change strengthens private key protection for code signing certificates and aligns it with EV (Extended Validation) code signing certificate private key protection.“

Eine Folge dieser Änderung ist die Änderung des zur Signierung des Zertifikates verwendeten Root-Zertifikates. Dieses Root-Zertifikat wird vom Befehl Update-Module geprüft, um sicherzustellen, dass die neue Version des Moduls vom gleichen Hersteller wie die bisherige Version stammt. Wenn Sie aktuell ein Update von der Version 2.0.4 oder einer älteren Version auf die Version 2.1.0 oder eine neuere Version durchführen möchten, so erhalten Sie die folgende Fehlermeldung: „PackageManagement\Install-Package : Authenticode issuer 'CN=DigiCert Global Root G3, OU=www.digicert.com, O=DigiCert Inc, C=US' of the new module 'dbatools' with version '2.1.0' is not matching with the authenticode issuer 'CN=DigiCert Assured ID Root CA, OU=www.digicert.com, O=DigiCert Inc, C=US' of the previously-installed module 'dbatools' with version '2.0.4'. If you still want to install or update, use -SkipPublisherCheck parameter.“

Der angebende Parameter -SkipPublisherCheck kann jedoch nicht mit Update-Module, sondern nur mit Install-Module verwendet werden. Da bereits eine frühere Version des Moduls installiert ist, muss zusätzlich der Parameter -Force verwendet werden. Es muss damit einmalig dieser Befehl zur Aktualisierung auf die aktuelle Version verwendet werden:

Install-Module -Name dbatools -Force -SkipPublisherCheck

Einmal Aufräumen bitte: Alle Versionen vom System entfernen

Jedes Update-Module installiert nur zusätzlich die neue Version und lässt die bisherigen Versionen unangetastet. Das kann in einigen Fällen praktisch sein, weil mit Import-Module -Name dbatools -RequiredVersion 1.1.146 eine ältere Version (hier die letzte Version vor der Version 2.0.0) geladen werden kann, wenn es mit der aktuellen Version Probleme gibt. Über die Zeit sammelt sich da aber unter Umständen einiges an. Von Zeit zu Zeit darf, unserer Meinung nach, gerne aufgeräumt werden.

Diese beiden Zeilen können Sie nutzen, um alle Versionen der Module dbatools und dbatools.library zu entfernen:

while (Get-Module -Name dbatools -ListAvailable) { Uninstall-Module -Name dbatools }

while (Get-Module -Name dbatools.library -ListAvailable) { Uninstall-Module -Name dbatools.library }

Dann funktioniert die Installation der aktuellen Version auch wieder ganz ohne Probleme mit Install-Module -Name dbatools. Da die Konfiguration in der Registrierung gespeichert wird, bleibt diese erhalten und wird automatisch für die neu installierten Versionen genutzt.

Für neue Systeme: Alle Schritte der Installation im Überblick

Starten Sie erst jetzt mit dbatools und haben vorher vielleicht auch noch kein anderes PowerShell-Modul auf dem System verwendet, so sind einmalig ein paar zusätzliche Schritte notwendig, um dbatools zu installieren und zu konfigurieren.

Hier alle Schritte in der Übersicht:

# Auf älteren Systemen ist TLS 1.2 evtl. noch nicht aktiviert, wird aber von den Microsoft-Servern verlangt. 
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 

# Einrichtung des Paketmanagers NuGet, um auf die PowerShellGallery zugreifen zu können. 
$null = Install-PackageProvider -Name Nuget -Force 

# Der PowerShellGallery vertrauen, um PowerShell-Module ohne Nachfragen installieren zu können. 
Set-PSRepository -Name PSGallery -InstallationPolicy Trusted 

# Installation der aktuellen Version des PowerShell-Moduls dbatools. 
Install-Module -Name dbatools 

# Konfiguration, um den Hinweis beim Import zu unterdrücken. Die Meldung wird allerdings bei der Ausführung des Befehls einmalig angezeigt. 
Set-DbatoolsConfig -FullName Import.EncryptionMessageCheck -Value $false -PassThru | Register-DbatoolsConfig -Scope SystemDefault 

# Konfiguration, um den selbst-signierten Zertifikaten der SQL Server Instanzen zu vertrauen. Nur notwendig, wenn keine signierten Zertifikate verwendet werden. 
Set-DbatoolsConfig -FullName sql.connection.trustcert -Value $true -PassThru | Register-DbatoolsConfig -Scope SystemDefault  

Fazit

Auch wenn das Update auf die aktuelle Version des PowerShell-Moduls dbatools etwas mehr Aufwand erfordert, empfehlen wir diesen Schritt auf jeden Fall. Neben der Verbesserung der Funktionalität wurden die zugrundeliegenden Microsoft-Bibliotheken aktualisiert und entsprechen jetzt wieder dem aktuellen Stand.

Wenn Sie weitere Fragen haben oder Unterstützung bei der Aktualisierung benötigen, so sprechen Sie uns an. Wir helfen gerne.

Seminarempfehlungen