Befehle am Server (Referenz)

Das Programm Wkl.Data.Gateway (bzw. dotnet Wkl.Data.Gateway.dll) kennt neben dem Dienstbetrieb Befehle, die mit derselben Konfiguration und Umgebung wie der Dienst laufen, keinen Webserver starten und danach enden. Sie dürfen laufen, während der Dienst läuft; er übernimmt Änderungen am Speicher ohne Neustart. Sie brauchen die Rechte eines Administrators des Rechners.

Wkl.Data.Gateway <Befehl> [--Option Wert]… [--contentRoot DIR] [--environment NAME]

--contentRoot und --environment bestimmen wie beim Dienst, welche Konfiguration gilt. Eine unbekannte Option lehnt jeder Befehl ab (Rückgabe 2), damit ein Tippfehler nichts Ungemeintes tut.

Den ersten Administrator legt ein Befehl am Server an, und eine ausgesperrte Verwaltung retten Befehle am Server. Beides braucht die Speicherdatei und den Hauptschlüssel, also die Rechte eines Administrators dieses Rechners – das ist der Nachweis, und keine Anfrage über das Netz kann ihn erbringen. Die Befehle lesen dieselbe Konfiguration wie der Dienst und dürfen laufen, während er läuft; er übernimmt die Änderung ohne Neustart.

Wkl.Data.Gateway init-admin --name "Erika Muster"

init-admin legt an, was fehlt:

1. den Verwaltungsspeicher, wenn es ihn noch nicht gibt (mit den Betriebsdaten der Konfigurationsdatei, wie beim ersten Start des Dienstes);
2. die Regel verwaltung mit admin und jeder Methode – oder nimmt die erste vorhandene, nicht nur lesende Regel mit admin; ob sie auch POST, PATCH und DELETE nennt, prüft der Befehl nicht;
3. die Person mit dieser Regel (eine vorhandene gleichen Namens wird eingeschaltet);
4. einen persönlichen Schlüssel, den der Befehl einmal anzeigt.

Den zweiten Faktor richtet die Person bei der ersten Anmeldung in der Verwaltungsanwendung ein (siehe Einrichten bei der ersten Anmeldung). Mit --totp geschieht es gleich in der Konsole: Der Befehl zeigt den QR-Code und den Schlüssel zum Abtippen und speichert erst, wenn ein Code aus der App passt. Das Änderungsprotokoll nennt jede dieser Änderungen mit Konsole (Rechner, Konto).

Typische Lagen: Telefon mit der Authenticator-App verloren → reset-totp. Letzter Administratorschlüssel gesperrt oder abgelaufen → init-admin --name … --force stellt einen neuen aus. Regel gelöscht → init-admin --force legt sie wieder an. Eine Anmelderegel sperrt alle aus → list-sign-in-rules, dann remove-sign-in-rule.

Wkl.Data.Gateway save-person --name "Erika Muster" --rule fachdaten-lesen [--login erika] [--disabled]
Wkl.Data.Gateway issue-key --person "Erika Muster" --label "Excel Bericht" --read-only --database fachdaten --from 10.0.0.0/8 [--expires 2026-12-31]
Wkl.Data.Gateway revoke-key --id kAb3dE5fG
Wkl.Data.Gateway list-keys

save-person ersetzt die Regeln und die Angaben der Person als Ganzes: Fehlt --login, wird eine eingetragene SQL-Anmeldung entfernt; fehlt --disabled, ist die Person danach eingeschaltet. Einen Regelnamen prüft der Befehl nicht gegen die vorhandenen Regeln: Ein falsch geschriebener Name gibt der Person keine Rechte, und jede spätere Änderung in der Verwaltung scheitert mit 422, bis er berichtigt ist. --rule, --database, --from und --except-from dürfen mehrfach stehen. Ein unbekannter Name (etwa --rules) wird abgelehnt, damit ein Tippfehler keinen Schlüssel ohne die gemeinte Einschränkung ausstellt. issue-key gibt den Schlüssel einmal aus; list-keys zeigt Kennung, Person, letzte 4 Zeichen, Zustand, Ablauf, letzte Benutzung, Einschränkungen und Bezeichnung, nie den Schlüssel. Rückgabewerte wie bei reseal-store: 0 erledigt, 1 nicht alles möglich (etwa unbekannte Kennung), 2 Speicher, Einstellung oder Befehlszeile unbrauchbar.

Wkl.Data.Gateway reseal-store (bzw. dotnet Wkl.Data.Gateway.dll reseal-store)

Verschlüsselt jeden Wert des Verwaltungsspeichers, der noch unter einem abgelösten Hauptschlüssel (Gateway:Store:RetiredKeys) steht, mit dem aktuellen (MasterKey, MasterKeyId) neu: die Verbindungszeichenfolgen der Datenquellen, die Geheimnisse der zweiten Faktoren und den Lizenzschlüssel der Geodatenbank. Alles geschieht in einer Transaktion; Änderungszeiten bleiben. Der Befehl startet keinen Webserver und endet danach. Er darf laufen, während der Dienst läuft; der Dienst lädt den Speicher danach neu.

Voraussetzung: dieselbe Konfiguration wie der Dienst, also im Programmordner als Arbeitsverzeichnis ausgeführt, mit dem aktuellen und allen abgelösten Schlüsseln. Den ganzen Ablauf eines Wechsels beschreibt So wechseln Sie den Hauptschlüssel.

Ein Schlüsselbund ersetzt keinen verlorenen Schlüssel: Werte, deren Schlüssel nicht mehr vorliegt, lassen sich nur neu eingeben.

Speicher sichern. Im laufenden Betrieb mit dem Befehl backup-store, gestartet mit derselben Konfiguration und demselben Inhaltsstamm wie der Dienst:

Wkl.Data.Gateway backup-store --to "E:\Sicherung\gateway-2026-10-01.db"
# oder: dotnet Wkl.Data.Gateway.dll backup-store --to …

Der Befehl startet keinen Webserver. Er schreibt mit VACUUM INTO von SQLite eine einzelne, in sich stimmige Kopie dessen, was eine Lesetransaktion sieht, auch während der Dienst schreibt. Danach prüft er die Kopie mit PRAGMA integrity_check und endet. Die Datei einfach zu kopieren genügt nicht: Neben ihr liegen -wal und -shm, und eine Kopie mitten in einem Schreibvorgang kann einen halben Stand enthalten.

• Kein Hauptschlüssel nötig. Der Speicher wird nur lesend geöffnet; die versiegelten Werte wandern unverändert in die Kopie. Eine Sicherungsaufgabe kommt so ohne Zugang zum Schlüssel aus, und die Kopie öffnet ohne ihn keine Datenbankverbindung.
• Nur für das ausführende Konto und die Administratoren lesbar. Die Zieldatei wird leer und mit dieser Zugriffsliste angelegt, ohne vom Ordner zu erben, bevor SQLite hineinschreibt; unter Linux liest sie nur ihr Eigentümer. Das Dienstkonto steht nicht darin: Eine Sicherung ist kein Speicher im Betrieb. Namen, Regeln, Personen und das Änderungsprotokoll stehen darin lesbar und gehören unter Verschluss wie jede andere Sicherung.
• Überschreibt nichts. Ein vorhandenes Ziel wird abgelehnt; jede Sicherung bekommt einen neuen Namen. Das Verzeichnis des Ziels muss es geben.
• Ändert nichts. Es läuft keine Umstellung der Schemafassung; die Kopie hat die Fassung der Datei.
• Sichert die Protokolldatei mit. Die Protokolldatei (Gateway:Store:LogPath, sonst -logs neben dem Speicher) kopiert der Befehl auf demselben Weg neben das Ziel, mit -logs am Namen: --to "E:\Sicherung\gateway-2026-10-01.db" ergibt dazu gateway-2026-10-01-logs.db. So zurückgelegt, öffnen sich beide wie das Original. Gibt es keine Protokolldatei, sichert er nur den Speicher und sagt das. Es entstehen beide Kopien oder keine.

--to-folder DIR schreibt die Sicherung unter einem Namen nach dem Zeitpunkt (gateway-<JJJJMMTT-HHMMSS>.db, dazu gateway-<JJJJMMTT-HHMMSS>-logs.db) und legt den Ordner an; --skip-missing macht einen noch nicht vorhandenen Speicher zu keinem Fehler (Rückgabe 0). Beides nutzt das Installationspaket für die Sicherung vor einer Aktualisierung.

Wkl.Data.Gateway update-geoip lädt die Dateien der Geodatenbank von der Quelle, die in der Verwaltung gewählt ist (`set-geoip-source`).

Wkl.Data.Gateway import-geoip --file DATEI [--source dbip-lite|maxmind] [--force] übernimmt eine Datei, die auf anderem Weg auf den Server kam (.mmdb, .mmdb.gz oder das .tar.gz von MaxMind), für einen Server ohne Zugang zum Internet. --source bestimmt die Namensnennung, --force übernimmt auch eine ältere oder gleich alte Datei.

Beide legen die Datei in den Ordner der Geodatenbank (Gateway:SignInLog:GeoIp:Folder); ein laufender Dienst nimmt sie innerhalb einer Minute in Gebrauch. Die Ausgabe nennt je Datei Art, Erstellungsdatum und ob sie übernommen wurde.

Wkl.Data.Gateway export-load --to DATEI [--days N] schreibt die Last der letzten N Tage (Vorgabe 30, höchstens Gateway:LoadLog:HourDays) als JSON-Datei im selben Format wie der Befehl `export-load` der Verwaltung: Formen, Stundenwerte und Hinweise, ohne Personen, Herkunft und Werte. Eine vorhandene Datei überschreibt der Befehl nicht. Weil er ohne den Katalog des Dienstes läuft, fehlt in der Datei der Hinweis unindexedFilter.

Wkl.Data.Gateway setup-host [--program DIR] [--data DIR] [--service-account KONTO|none]
                            [--mode standalone|iis] [--port 8434] [--https-port 8433]
                            [--certificate NAME [--self-signed]] [--access internal|internet]
                            [--networks 10.0.0.0/8,...] [--admin-from-outside deny|totp]
                            [--firewall] [--pq-hybrid] [--installation-name NAME]
                            [--sql-server SERVER [--sql-databases DB,...] [--sql-roles readwrite|read|none]]
Wkl.Data.Gateway setup-remove [--remove-data DIR]

Rückgabe 0: eingerichtet (ein Zertifikat, das noch nicht im Speicher liegt, ist kein Fehler – der Dienst nimmt es, sobald es da ist); 1: ein Schritt scheiterte; 2: falsche Befehlszeile. Das Paket rollt bei allem außer 0 zurück. Abgelehnt werden unter anderem --access internet ohne Netze, ein Netz mit gesetzten Host-Bits oder in Kurz-, Hexadezimal- oder Oktalschreibweise (192.168, 0x7f.0.0.1, 017.0.0.1), --self-signed zusammen mit --access internet und ein --installation-name mit mehr als 64 Zeichen, Doppelpunkt oder Anführungszeichen. Ohne --installation-name bleibt Gateway:Store:TotpIssuer beim Vorgabewert des Dienstes.

Wkl.Data.Gateway acme-client

Nennt das wacs.exe, mit dem Zertifikat-LetsEncrypt.cmd bestellt: in der ersten Zeile der Ausgabe den Pfad, im Fehlerkanal den Grund. Das ist ein vorhandenes win-acme, wenn dessen geplante Aufgabe win-acme renew (…) darauf zeigt (ab Fassung 2.2.9), sonst das mitgebrachte im Programmordner. Rückgabe 0: Pfad genannt; 1: das vorhandene win-acme ist zu alt oder seine Fassung unlesbar; 2: falsche Befehlszeile. Braucht Administratorrechte, um die Aufgaben zu lesen; ohne sie gilt das mitgebrachte.

Die Anmeldung des Dienstkontos in SQL Server und ein Benutzer in jeder Datenbank: als Skript für die Datenbankverwaltung oder gleich angelegt, mit dem Windows-Konto der Person, die den Befehl ausführt (nicht mit dem Dienstkonto). Anders als die übrigen Befehle liest er keine Konfiguration und braucht keine Administratorrechte des Rechners, nur die Rechte in SQL Server.

Wkl.Data.Gateway service-login --server SERVER [--database DB[,DB...]] [--roles readwrite|read|none]
                               [--account KONTO] [--script DATEI] [--apply] [--trust-server-certificate]

Das Skript ändert nichts, was schon besteht: Eine vorhandene Anmeldung (gesucht über das Windows-Konto, also auch nach einer Umbenennung) und ein vorhandener Benutzer bleiben, wie sie sind, auch ihre Rollen. Ein zweiter Lauf ändert deshalb nichts. Jede Datenbank ist eine eigene Transaktion: Der Benutzer entsteht mit seinen Rollen oder gar nicht. Namen erreichen SQL Server als Werte und werden dort mit QUOTENAME zu Bezeichnern.

Mit --apply steht je Schritt eine Zeile auf der Konsole:

OK      Anmeldung NT SERVICE\Wkl.Data.Gateway: angelegt
OK      Benutzer in [Fachdaten] (db_datareader, db_datawriter): vorhanden, unveraendert
FEHLER  Benutzer in [Lager] (db_datareader, db_datawriter): 916: Der Serverprinzipal ... kann nicht auf die Datenbank zugreifen ...

Eine Zeile FEHLER nennt die Fehlernummer von SQL Server. Scheitert die Anmeldung selbst, folgen keine Datenbanken. Rückgabe 0: alles angelegt oder vorhanden; 1: ein Schritt abgelehnt oder der Server nicht erreicht; 2: falsche Befehlszeile.

• So legen Sie den ersten Administrator an · Notfallzugang · Sicherung
• Installationspaket (Referenz)