Sage 100: Wenn der BlobStorage nach einem Update nicht mehr startet

Nach einem Update der Sage 100 Serverkomponenten lässt sich der BlobStorage-Dienst nicht mehr starten. Im Ereignisprotokoll steht eine Meldung, die auf den ersten Blick nach einem Fehler in der Sage-Bibliothek aussieht:

Der Dienst kann nicht gestartet werden. System.ArgumentNullException:
Der Wert darf nicht NULL sein.
Parametername: configuration.Host
   bei Sagede.Shared.Identity.Sts.Client.StsAuthenticationClient..ctor(
        IStsClientConfiguration configuration, Boolean validateToken)
   bei Sagede.BlobStorageServer.Configuration.HostConfigHelper
        .LoadBasicHttpConfiguration(...)
   bei Sagede.BlobStorageServer.SageBlobStorageService.OnStart(String[] args)

Dazu kommt ein Application Error mit Ausnahmecode 0xe0434352. Das ist der Standardcode für eine unbehandelte .NET-Ausnahme. Der Dienst versucht den Start typischerweise mehrfach und stirbt jedes Mal in derselben Zeile.

Die Meldung sieht nach einem Defekt aus. Tatsächlich ist sie eine völlig korrekte Aussage über eine unvollständige Konfiguration. Wir hatten genau diesen Fall bei einem Kunden auf dem Tisch und zeigen Dir hier, wie Du ihn sauber diagnostizierst und behebst.

Was der STS ist und warum ihn der BlobStorage braucht

STS steht für Security Token Service. Das ist der interne Identity-Dienst der Sage 100. Er stellt Tokens aus, mit denen sich die Sage-Dienste untereinander und gegenüber den Clients authentifizieren.

Die Rollenverteilung ist für die Fehlersuche entscheidend:

• Der Applikationsserver hostet den STS, standardmäßig auf Port 5466. In seiner Kernkonfiguration Sagede.ApplicationServer.Core.config steht dafür ein <stsServer>-Knoten mit Host-Adresse und Zertifikats-Thumbprint.
• Alle anderen Dienste wie BlobStorage oder Application Gateway melden sich als Client an. Dafür steht in ihrer jeweiligen Konfiguration ein <stsClient>-Knoten mit Host, clientId und clientSecret.

Der BlobStorage baut beim Start für jeden seiner Endpunkte einen StsAuthenticationClient auf. Dessen Konstruktor prüft als Erstes, ob eine Host-Adresse vorliegt. Fehlt der <stsClient>-Knoten komplett, ist configuration.Host schlicht null. Der Dienst kommt dann gar nicht erst bis zum Öffnen seiner Ports.

Die Ursache: Das Setup schreibt Konfigurationen neu

Sage-Setups erzeugen die Dienst-Konfigurationsdateien aus mitgelieferten .default-Vorlagen neu. Diese Vorlagen enthalten die STS-Knoten nur als auskommentiertes Beispiel. Die echten, umgebungsspezifischen Werte werden bei der Ersteinrichtung eingetragen und sind der Vorlage naturgemäß unbekannt.

Läuft ein Update oder eine Reparaturinstallation, kann dabei die gepflegte Konfiguration durch die Vorlage ersetzt werden. Andere Änderungen des Setups bleiben sichtbar erhalten. In unserem Fall wurde etwa ein zusätzlicher SageId-Endpunkt eingetragen. Das zeigt, dass die Datei tatsächlich neu erzeugt und nicht nur zurückgesetzt wurde. Die STS-Konfiguration hingegen fehlt danach.

Ein guter Indikator: Stehen der Applikationsserver und der Administrationsdienst ebenfalls auf „Beendet" und wurden sie laut Ereignisprotokoll zum Zeitpunkt des Setups gestoppt, ohne je wieder gestartet worden zu sein, ist das Bild komplett.

Diagnose

Zwei Handgriffe genügen, um die Vermutung zu bestätigen.

Erstens: In den Installationsverzeichnissen der Dienste liegen neben der aktiven Konfiguration Sicherungskopien mit Zeitstempel im Namen, nach dem Muster JJJJMMTT_hhmmss_<Dateiname>.config. Sage legt sie bei jeder Änderung durch ein Setup selbst an. Ein Durchsuchen dieser Kopien nach stsClient zeigt sofort, welche Stände die Knoten hatten und ab welchem Zeitpunkt sie fehlen:

Get-ChildItem "<Installationspfad>" -Filter "*.config" | ForEach-Object {
    [PSCustomObject]@{
        Name = $_.Name
        Geaendert = $_.LastWriteTime
        STS = (Select-String -Path $_.FullName -Pattern "stsServer|stsClient" -Quiet)
    }
} | Sort-Object Geaendert -Descending | Format-Table -AutoSize

Achte darauf, nur Treffer außerhalb der Kommentarblöcke zu werten. Die Beispielkonfiguration in den Kommentaren enthält die Knoten ebenfalls.

Zweitens: Das Ereignisprotokoll rund um den Zeitstempel der Konfigurationsänderung zeigt, welche Dienste das Setup gestoppt hat. Zusammen ergibt das eine klare Chronologie.

Die Lösung

Übernimm die STS-Knoten aus der jüngsten Sicherungskopie, die sie noch enthält, in die aktuelle Konfiguration. Lege vorher eine eigene Kopie der aktuellen Dateien an. Die vom Setup erzeugten Sicherungen sind hilfreich, aber Du willst auch Deinen eigenen Zwischenstand zurückholen können.

In der Konfiguration des BlobStorage-Servers gehört der Client-Knoten in den <BlobStorage>-Abschnitt, hinter die Endpunktliste:

<BlobStorage StorageRoot="...">
  <EndPoints>
    <!-- ... -->
  </EndPoints>
  <stsClient enabled="true"
             host="https://<servername>:<port>"
             clientId="<GUID>"
             clientSecret="<GUID>" />
  <MultiUserServer Name="\\." RegistryKey="Software\Sage\Office Line\9.0" />
</BlobStorage>

In der Kernkonfiguration des Applikationsservers gehören beide Knoten in den <security>-Abschnitt:

<security>
  <!-- ... -->
  <stsClient enabled="true"
             host="https://<servername>:<port>"
             clientId="<GUID>"
             clientSecret="<GUID>" />
  <stsServer enabled="true"
             host="https://<servername>:<port>"
             certificateThumbprint="<Thumbprint>" />
</security>

Beachte, dass Applikationsserver und BlobStorage unterschiedliche clientId/clientSecret-Paare verwenden. Jeder Dienst ist am STS als eigener Client registriert. Die Werte lassen sich nicht gegeneinander austauschen.

Anschließend startest Du die Dienste in dieser Reihenfolge:

• Applikationsserver, denn er bringt den STS hoch
• Administrationsdienst
• BlobStorage-Server

Die Stolperfalle: Der Zertifikats-Thumbprint

Hier lohnt sich Sorgfalt. Der certificateThumbprint im <stsServer>-Knoten bestimmt, mit welchem Zertifikat der Applikationsserver den STS-Port an HTTP.SYS bindet. Ein Setup stellt die Bindungen aber unter Umständen um, etwa von einem dedizierten STS-Zertifikat auf das allgemeine Maschinenzertifikat.

Was aktuell tatsächlich gebunden ist, zeigt Dir:

netsh http show sslcert

Übernimm den Thumbprint, der dort für den STS-Port hinterlegt ist, und nicht blind den Wert aus der alten Sicherungskopie. Andernfalls setzt der Applikationsserver beim Start die Bindung wieder um. Im ungünstigen Fall passt der Zertifikatsname anschließend nicht mehr zum Hostnamen, unter dem die Clients den STS ansprechen. Du hättest dann statt eines Startfehlers ein Zertifikatsproblem, und das ist deutlich schwerer zu diagnostizieren.

Prüfe bei der Gelegenheit auch, ob der Common Name des gebundenen Zertifikats zu der Host-Adresse passt, die in den stsClient-Knoten steht.

Was kein brauchbarer Funktionstest ist

Nach der Reparatur willst Du natürlich verifizieren, dass die Client-Zugangsdaten am STS noch gültig sind. Der naheliegende Versuch, ein Token per client_credentials über die Discovery-URL anzufordern, führt in die Irre: Der Sage-STS beantwortet auch das sonst anonyme /.well-known/openid-configuration mit 401 Unauthorized, und zwar unabhängig davon, ob Du anonym oder mit Windows-Anmeldeinformationen anfragst.

Ein 401 an dieser Stelle ist also kein Beleg dafür, dass clientId oder clientSecret ungültig wären. Er sagt schlicht gar nichts aus.

Ähnlich begrenzt aussagekräftig ist ein Aufruf der BlobStorage-Endpunkte: Ein 404 auf dem Wurzelpfad zeigt lediglich, dass der HTTP-Listener steht. Das ist eine sinnvolle Bestätigung, dass der Dienst seine Ports geöffnet hat, aber kein Nachweis funktionierender Authentifizierung.

Der belastbare Test ist ein echter Vorgang aus der Sage 100 heraus, der den BlobStorage nutzt. Etwa das Hinterlegen eines Briefpapiers oder ein Dokumenten-Upload. Erst wenn der durchläuft, ist die Kette vollständig geprüft. Schlägt er mit Authentifizierungsfehlern fehl, sind die Client-Registrierungen im STS tatsächlich verloren gegangen und müssen neu angelegt werden.

Vorbeugen

• Vor jedem Update die Konfigurationsdateien aller Sage-Dienste an einen Ort außerhalb der Installationsverzeichnisse sichern. Die vom Setup erzeugten Zeitstempel-Kopien sind eine gute Rückfallebene, aber sie liegen im selben Verzeichnis und können bei einer Deinstallation mit verschwinden.
• Nach jedem Update gezielt prüfen, ob die STS-Knoten noch vorhanden sind, bevor Anwender auf Fehler stoßen. Ein kurzes Skript über alle Dienstverzeichnisse genügt.
• Die clientId/clientSecret-Paare der einzelnen Dienste zusammen mit dem Zertifikats-Thumbprint in der Systemdokumentation festhalten. Wenn die Sicherungskopien einmal nicht ausreichen, ist das der schnellste Weg zurück.
• Nach einem Setup daran denken, dass gestoppte Dienste auch gestoppt bleiben. Ein Blick auf den Status aller Sage-Dienste gehört zum Abschluss jedes Updates.

Fazit

Die ArgumentNullException in configuration.Host liest sich wie ein Bug, ist aber eine präzise Aussage: Dem Dienst fehlt seine STS-Client-Konfiguration. Ursache ist in aller Regel ein Setup, das die gepflegte Konfiguration durch die Standardvorlage ersetzt hat. Der Fix ist unspektakulär: Die Knoten aus der letzten guten Sicherungskopie zurückschreiben und die Dienste in der richtigen Reihenfolge starten. Wichtig sind die beiden Details drumherum: Alle betroffenen Konfigurationen prüfen, nicht nur die des abstürzenden Dienstes, und beim Zertifikats-Thumbprint den Ist-Zustand der HTTP.SYS-Bindungen übernehmen statt den Wert von früher.

Wenn Deine Sage 100 nach einem Update streikt und Du nicht weiterkommst, schau Dir auch unseren Beitrag zur Performance-Optimierung des Applikationsservers an. Oder melde Dich direkt bei uns.