Konfiguration des Dienstes (Referenz)

Jeder Konfigurationsschlüssel des Dienstes unter Gateway mit Vorgabe und Wirkung. Die Werte kommen aus appsettings.json, appsettings.<Umgebung>.json, Umgebungsvariablen, Startparametern und appsettings.Local.json; bei gleichem Schlüssel gilt die spätere Quelle, appsettings.Local.json also vor allen anderen; mit einem Verwaltungsspeicher stehen die Betriebsdaten (Datenquellen, Regeln, Zuordnungen) dort statt in der Datei. Eine Konfiguration, die die Startprüfung nicht besteht, verhindert den Start; das Protokoll nennt jeden Fehler.

{
  "Gateway": {
    "Databases": [ { "Name": "fachdaten", "Provider": "sqlserver", "ConnectionString": "…" } ],
    "MetadataCacheSeconds": 300,
    "ResponseCompression": true,
    "Security": { "AuthMode": "ApiKey, Windows", "ApiKeys": [], "Clients": [] },
    "Limits": { "DefaultTop": 1000, "MaxTop": 10000 },
    "Store": { "Path": "store/gateway.db", "MasterKey": "env:WKL_GW_MASTER_KEY" },
    "Certificate": { "Subject": "daten.example.com" },
    "Downloads": { "Path": "downloads" }
  },
  "Kestrel": { "Endpoints": { } }
}

Als Umgebungsvariable mit doppeltem Unterstrich: Gateway__Databases__0__ConnectionString.

Die Dateien appsettings*.json und jeder relative Pfad dieser Seite beziehen sich auf den Inhaltsstamm des Dienstes: als Windows-Dienst der Programmordner, sonst das Arbeitsverzeichnis beim Start (unter systemd WorkingDirectory). Der Startparameter --contentRoot <ordner> setzt ihn ausdrücklich.

appsettings.json beschreibt die Form und die Voreinstellungen und enthält keine Verbindungszeichenfolge und keinen Schlüssel. Beides gehört zur betriebenen Instanz:

• appsettings.Local.json im Inhaltsstamm – der Dienst liest sie in jeder Umgebung; in der Entwicklung ist sie git-ignoriert, im Betrieb trägt sie etwa den Wechsel des Hauptschlüssels;
• Umgebungsvariablen (Gateway__Databases__0__ConnectionString) im Dienstbetrieb.

Schlüssel werden ausschließlich als Verweis konfiguriert:

Ein Verweis, der sich nicht auflösen lässt, verhindert den Start. Das ist beabsichtigt: eine nicht gesetzte Umgebungsvariable würde sonst als Aufrufer auftreten, der sich unerklärlich nicht anmelden kann.

Komprimierte Antworten (Gateway:ResponseCompression, Vorgabe true): Nennt der Aufrufer Accept-Encoding, packt der Dienst jede Antwort mit Brotli oder gzip auf der schnellsten Stufe – auch über HTTPS. JSON wiederholt in jeder Zeile die Spaltennamen und lässt sich deshalb stark packen; über eine langsame Leitung verkürzt das die Ladezeit großer Tabellen deutlich. Der Treiber und Power Query entpacken von sich aus. Zum Angriff BREACH, der komprimierte HTTPS-Antworten ausnutzt (RFC 7457, Abschnitt 2.6): Er braucht ein Geheimnis in derselben Antwort wie ein vom Angreifer gewählter Text und einen Browser mit selbsttätiger Anmeldung. Datenantworten tragen nur die angefragten Daten; die Antworten auf den Austausch und die Einrichtung des zweiten Faktors und auf das Ausstellen eines Schlüssels tragen aber ein Geheimnis und werden ebenfalls komprimiert. Wer eine Browseranwendung mit Windows-Anmeldung vom selben Ursprung bedient und die Frage ausschließen will, schaltet den Schalter ab.

Je Eintrag ein Alias. Mit Verwaltungsspeicher stehen die Datenquellen dort (Menge DataSources).

Der Alias (Name) wird Teil jeder Adresse (/odata/v4/<alias>/…, /api/v1/cf/<alias>/…) und wird gegen die Regeln der Aufrufer verglichen. Deshalb gilt für ihn dieselbe Regel wie für einen gewöhnlichen Bezeichner von SQL Server, ohne Schema-Teil:

Ein Verstoß verhindert den Start mit der Meldung „'<Name>' ist kein zulaessiger Aliasname“. Über die Verwaltungsschnittstelle (Menge DataSources) wird der Eintrag nicht übernommen: Antwort 422 mit derselben Meldung; der Speicher bleibt unverändert.

Quelle der Regel im Code: GatewayIdentifier.IsValidPart im Vertragspaket Wkl.Data.Gateway.Contracts; eine Anwendung, die das Paket bezieht, kann vor dem Speichern genau diese Methode aufrufen.

Ressourcengrenzen über Gateway:Limits, verfeinerbar je Objekt. Eine Regel wird gegen <alias>/<art>/<objekt> geprüft; die erste passende gewinnt, in der konfigurierten Reihenfolge.

Der Dienst sucht beim Start in zwei Ordnern, jeweils mit dem Aufbau <Ordner>/<Kennung>/<Fassung>/ und einer Datei provider.json darin: im Ordner providers neben dem Programm (mitgelieferte Provider; eine Aktualisierung ersetzt ihn) und unter Path (gehört dem Betreiber und bleibt bei einer Aktualisierung stehen). Ein Paket wird nur geladen, wenn Ordnername und Kennung übereinstimmen, die Fassung des Provider-Vertrags passt, die Plattform passt und jede Datei ihre Prüfsumme (SHA-256) trifft. Ein Paket des Betreibers darf weder die Kennung noch einen Zweitnamen eines mitgelieferten Providers belegen.

Ein Provider läuft im Dienst mit dessen Rechten. Schreiben dürfen in beide Ordner nur Konten, die auch den Dienst selbst ändern dürfen; über das Netz lässt sich kein Paket ablegen.

{
  "Gateway": {
    "Store": {
      "Path": "store/gateway.db",
      "MasterKey": "env:WKL_GW_MASTER_KEY",
      "PollSeconds": 5
    }
  }
}

SetupKey und EmergencyAccess gibt es nicht mehr. Der Einrichtungsschlüssel galt über HTTPS von jedem Rechner aus und wurde von selbst wieder gültig, sobald kein Administrator mehr anmelden konnte – dann ohne zweiten Faktor. Den ersten Administrator legt jetzt der Befehl init-admin am Server an. Eine Konfiguration, die die Werte noch nennt, startet weiter; der Dienst meldet beim Start, dass er sie nicht beachtet.

Das Anmeldeprotokoll in der Protokolldatei neben dem Verwaltungsspeicher, die Anmelderegeln und die Meldung ihrer Befunde; ohne Speicher zeichnet der Dienst nichts auf.

"Gateway": {
  "SignInLog": {
    "TimeZone": "Europe/Berlin",
    "Networks": [ { "Name": "Werk 3", "Network": "10.3.0.0/16" } ],
    "GeoIp": { "StaleDays": 60 },
    "Alerts": { "Recipients": [ "sicherheit@example.com" ], "DigestHour": 7 }
  }
}

Die Quelle der Geodatenbank steht nicht hier, sondern im Speicher (set-geoip-source), weil ein Lizenzschlüssel dazugehören kann und die Verwaltung sie ändern soll.

Meldung der Befunde. Jeder Befund steht im Dienstprotokoll – act als Warnung, ask als Information – mit Regel, Zeit und Person. Mit Alerts:Recipients schickt der Dienst zusätzlich jeden Befund der Stufe act sofort als Mail und die Befunde der Stufe ask einmal am Tag gesammelt. Eine Mail nennt Regel, Zeitpunkt, Person und Nummer des Befunds, nie Adresse, Land oder Schlüssel; diese stehen nur in der Verwaltungsschnittstelle für Berechtigte. Eine Sammlung, die niemand annahm, holt der Dienst am nächsten Tag nach.

Mailversand für die Meldung der Befunde. Ohne Eintrag verschickt der Dienst keine Mail.

"Gateway": {
  "Mail": {
    "Transport": "smtp",
    "Host": "mail.example.com",
    "Port": 587,
    "Encryption": "starttls",
    "Username": "gateway@example.com",
    "FromAddress": "gateway@example.com",
    "FromName": "Datengateway",
    "PublicBaseUrl": "https://gateway.example.com"
  }
}

Eine Einstellung, mit der kein Versand möglich ist, verhindert den Start mit dem Grund; ebenso Alerts:Recipients ohne Transport. none ohne Empfänger ist der gewöhnliche Zustand.

Das Lastprotokoll in der Protokolldatei neben dem Verwaltungsspeicher; ohne Speicher zeichnet der Dienst nichts auf.

"Gateway": {
  "LoadLog": { "PersonDays": 3, "SlowMilliseconds": 2000 }
}

Anfragen an /health zeichnet der Dienst nicht auf. In einer Minute hält er höchstens 5 000 verschiedene Formen und 2 000 langsame Anfragen fest; was darüber hinausgeht, zählt er nicht mit und meldet es im Protokoll des Dienstes.

"Gateway": {
  "Certificate": { "Subject": "daten.example.local", "StoreLocation": "LocalMachine", "StoreName": "My" }
}

"Gateway": {
  "Certificate": { "File": "zertifikat/gateway.pfx", "Password": "env:WKL_GW_CERT_PASSWORD" }
}

Wirkung und Wechsel ohne Neustart: HTTPS und Zertifikat.

Lauschadressen und ein festes Zertifikat nach den Regeln von ASP.NET Core (Kestrel:Endpoints); siehe HTTPS und Zertifikat. Ohne den Abschnitt gilt --urls.

• Die Startprüfung weist widersprüchliche Angaben ab, statt eine davon zu wählen: doppelte Schlüssel, zwei Regeln eines Aufrufers für denselben Alias, sql an einer nur lesenden Regel, ein Netz mit gesetzten Host-Bits, RequireTotp für Dienstschlüssel, unbekannte Windows-Konten.
• SqlLogin in AuthMode verlangt mindestens eine Datenquelle mit AllowSqlLogins und mindestens einen Eintrag unter SqlLogins. Ohne Verwaltungsspeicher verhindert eine fehlende Angabe den Start. Mit Verwaltungsspeicher startet der Dienst und meldet die Lücke im Protokoll, weil Schalter und Zuordnungen dort erst nach dem Verfahren gesetzt werden können; bis dahin endet eine SQL-Anmeldung mit 401. Umgekehrt weisen Startprüfung und Verwaltung AllowSqlLogins und Zuordnungen ohne das Verfahren ab. Reihenfolge: SQL-Anmeldung einrichten.
• Eine geänderte Konfigurationsdatei wirkt erst nach einem Neustart; Änderungen im Verwaltungsspeicher wirken sofort.

Ein Alias mit eigenen Anweisungen und ein Aufrufer, der sie nutzen darf:

{
  "Gateway": {
    "Databases": [
      { "Name": "fachdaten", "Provider": "sqlserver", "ConnectionString": "…",
        "AllowPassThrough": true }
    ],
    "Security": {
      "Clients": [
        { "Id": "auswertung", "Databases": [ "fachdaten" ],
          "Resources": [ "views", "sql" ], "Verbs": [ "GET", "POST" ], "ReadOnly": false }
      ]
    }
  }
}

• Verwaltungsspeicher und Hauptschlüssel
• Befehle am Server (Referenz)