Service configuration (reference)

Every configuration key of the service under Gateway, with its default and effect. The values come from appsettings.json, appsettings.<environment>.json, environment variables, command-line arguments, and appsettings.Local.json; for the same key the later source wins, so appsettings.Local.json takes precedence over all others; with an administration store, the operating data (data sources, rules, assignments) is kept there instead of in the file. A configuration that fails the startup check prevents the service from starting; the log names each error.

{
  "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": { } }
}

As an environment variable with double underscores: Gateway__Databases__0__ConnectionString.

The appsettings*.json files and every relative path on this page refer to the service's content root: as a Windows service, the program folder; otherwise the working directory at startup (under systemd, WorkingDirectory). The startup argument --contentRoot <folder> sets it explicitly.

appsettings.json describes the shape and the defaults and contains no connection string and no key. Both belong to the instance being operated:

• appsettings.Local.json in the content root—the service reads it in every environment; in development it's ignored by git, in operation it holds, for example, the change of the master key;
• environment variables (Gateway__Databases__0__ConnectionString) when running as a service.

Keys are configured exclusively as a reference:

A reference that can't be resolved prevents startup. That's intentional: an unset environment variable would otherwise show up as a caller that inexplicably can't sign in.

Compressed responses (Gateway:ResponseCompression, default true): if the caller sends Accept-Encoding, the service compresses every response with Brotli or gzip at the fastest level—also over HTTPS. JSON repeats the column names in every row and therefore compresses well; over a slow line, this noticeably shortens the time it takes to load large tables. The driver and Power Query decompress automatically. Regarding the BREACH attack, which exploits compressed HTTPS responses (RFC 7457, section 2.6): it needs a secret in the same response as a text chosen by the attacker, and a browser that signs in automatically. Data responses carry only the requested data; however, the responses to the exchange and setup of the second factor and to issuing a key do carry a secret and are also compressed. If you serve a browser application with Windows sign-in from the same origin and want to rule out the question, turn the switch off.

One alias per entry. With an administration store, the data sources are kept there (set DataSources).

The alias (Name) becomes part of every address (/odata/v4/<alias>/…, /api/v1/cf/<alias>/…) and is compared against the callers' rules. That's why the same rule applies to it as to a regular SQL Server identifier, without a schema part:

A violation prevents startup with the message “'<Name>' ist kein zulaessiger Aliasname” ('<Name>' isn't a valid alias name). Via the administration API (set DataSources), the entry isn't accepted: response 422 with the same message; the store stays unchanged.

Source of the rule in code: GatewayIdentifier.IsValidPart in the contract package Wkl.Data.Gateway.Contracts; an application that references the package can call exactly this method before saving.

Resource limits via Gateway:Limits, refinable per object. A rule is checked against <alias>/<kind>/<object>; the first match wins, in the configured order.

At startup, the service searches two folders, each with the layout <folder>/<id>/<version>/ and a provider.json file in it: the providers folder next to the program (included providers; an upgrade replaces it) and under Path (belongs to the operator and stays in place during an upgrade). A package is loaded only if the folder name and ID match, the version of the provider contract fits, the platform fits, and every file matches its checksum (SHA-256). An operator package may use neither the ID nor an alternative name of an included provider.

A provider runs inside the service with the service's rights. Only accounts that may also change the service itself may write to either folder; no package can be placed over the network.

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

SetupKey and EmergencyAccess no longer exist. The setup key was valid over HTTPS from any computer and became valid again on its own as soon as no administrator could sign in anymore—then without a second factor. The first administrator is now created by the init-admin command on the server. A configuration that still contains these values continues to start; the service reports at startup that it ignores them.

The sign-in log in the log file next to the administration store, the sign-in rules, and the reporting of their findings; without a store, the service records nothing.

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

The source of the geolocation database isn't set here but in the store (set-geoip-source), because a license key can belong to it and the administration is meant to change it.

Reporting findings. Every finding appears in the service log—act as a warning, ask as information—with rule, time, and person. With Alerts:Recipients, the service also sends each finding at level act by email right away and the findings at level ask once a day as a digest. An email names the rule, time, person, and number of the finding, never the address, country, or key; those appear only in the administration API, for those entitled to see them. A digest that nobody accepted is sent again the next day.

Mail delivery for reporting findings. Without an entry, the service sends no email.

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

A setting that makes delivery impossible prevents startup and names the reason; so does Alerts:Recipients without a Transport. none without recipients is the ordinary state.

The load log in the log file next to the administration store; without a store, the service records nothing.

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

The service doesn't record requests to /health. Within one minute, it holds at most 5,000 distinct shapes and 2,000 slow requests; anything beyond that isn't counted, and the service reports it in its log.

The access log (audit): every answered or refused request with caller, person, alias, resource, target (key address or query), allowing access rule, method, and result, and every custom statement with its text, never with parameter values. The service writes it to the log category Wkl.Data.Gateway.Audit and, with an administration store, once a minute to the log file. You read it through the AuditEntries set of the administration API.

"Gateway": {
  "AuditLog": { "Days": 180 }
}

Without an administration store, AuditEntries shows the last 10,000 entries since the service started; the log category is then the only lasting record.

Data protection: The target of a request contains key and filter values, such as a contract number or a name. They can be personal data and are kept as long as the rest of the entry (Days); choose the period according to the purpose of the record.

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

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

Effect and change without restart: HTTPS and certificate.

The update module applies database updates to the databases for which this folder holds a protected configuration. Without the data service, the WKL Database Update service does this with the same configuration files.

A configuration counts only when no one but Administrators and SYSTEM can change the file and its folder (the service account reads them) and the file name matches the id; otherwise the module leaves the database out and names the reason in update-databases. The module connects with its own SQL Server login, never with the service's account; the password isn't in the file but in an environment variable or in a file only Administrators, SYSTEM, and the service account can read:

{
  "format": 1, "id": "demo-prod", "gatewayAlias": "demo", "product": "Demo", "dialect": "sqlserver",
  "connection": { "string": "Server=sql01;Database=Demo;User ID=wkl_update;Encrypt=True",
                  "secret": "file:C:\\ProgramData\\Wkl.Data.Gateway\\secrets\\demo-update.txt" },
  "keys": [ "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE…" ],
  "inbox": "D:\\Updates\\Demo", "archive": "D:\\Updates\\Demo-Archiv",
  "backup": { "mode": "native", "target": "D:\\Sicherung" }
}

keys are the public keys of the publishers the database trusts. With backup.mode native, the module backs the database up before every package into the folder backup.target on the database server; with external, IT takes the backups itself and every package waits for confirmation. starterSource (optional) is the folder the module writes the schema state for the WKL Bootstrapper into. With no file in the folder, the module does nothing.

Backup retention. After each new backup, the module deletes older backups of the same database, but only a backup that has at least BackupKeepCount newer ones (default 10) and is older than BackupKeepDays days (default 30; 0: only the count matters). The newest BackupKeepCount always remain. Both are set in `UpdateSettings`. Only files the module created itself count (<database>-<yyyyMMdd-HHmmss>-<package>.bak, time in UTC); other files in the folder are left alone. The module deletes through the file system, and only when it can see the backup it just wrote under backup.target: on the same machine as SQL Server, or in a shared folder both can reach (\\server\share\...). If the folder exists only on a different database server, the module says so once in the service log and keeps every backup; IT then has to clean up.

Reports. The module reports what becomes of a package on the channels switched on for the database in the set `UpdateSettings`:

• Event log (default): the application log, source Wkl.Data.Gateway. The installation registers the source (setup-host); without it, the service log says so once.
• File: one file per day (UTC), %ProgramData%\Wkl.Data.Gateway\logs\updates\<YYYY-MM-DD>.jsonl, with one JSON object per line (utc, database, product, event, file, schema, code, message). The folder is fixed; the module never deletes the files.
• Mail: to the recipients of the database, through the service's mail settings (`Gateway:Mail`), with the same text as in the event log. The mail is sent outside the pass; a slow or unreachable mail server holds up no package.

The module reports a wait only when its reason changes, not at every pass.

Listening addresses and a fixed certificate according to the ASP.NET Core rules (Kestrel:Endpoints); see HTTPS and certificate. Without this section, --urls applies.

• The startup check rejects contradictory settings instead of choosing one of them: duplicate keys, two rules of one caller for the same alias, sql on a read-only rule, a network with host bits set, RequireTotp for service keys, unknown Windows accounts.
• SqlLogin in AuthMode requires at least one data source with AllowSqlLogins and at least one entry under SqlLogins. Without an administration store, a missing one prevents the start. With an administration store, the service starts and logs the gap, because the switch and the mappings can only be set there once the method is on; until then, a SQL Server sign-in ends with 401. The other way around, both the start check and the administration refuse AllowSqlLogins and mappings without the method. Order of steps: Set up a SQL Server login.
• A changed configuration file takes effect only after a restart; changes in the administration store take effect immediately.

An alias with custom statements and a caller that may use them:

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

• Administration store and master key
• Server commands (reference)