Server commands (reference)
Besides running as a service, the Wkl.Data.Gateway program (or dotnet Wkl.Data.Gateway.dll) provides
commands that run with the same configuration and environment as the service, don't start a web server,
and exit when they're done. They may run while the service is running; the service picks up changes to
the store without a restart. They require administrator rights on the computer.
Syntax
Wkl.Data.Gateway <command> [--option value]… [--contentRoot DIR] [--environment NAME]
As with the service, --contentRoot and --environment determine which configuration applies. Every
command rejects an unknown option (return code 2), so that a typo doesn't do anything unintended.
Parameters
First administrator and recovery
A command on the server creates the first administrator, and commands on the server recover a locked-out administration. Both need the store file and the master key, and therefore the rights of an administrator of this computer—that's the proof, and no request over the network can provide it. The commands read the same configuration as the service and may run while it's running; the service picks up the change without a restart.
Wkl.Data.Gateway init-admin --name "Jane Doe"
init-admin creates whatever is missing:
- the administration store, if it doesn't exist yet (with the operating data from the configuration file, as on the first start of the service);
- the rule
verwaltungwithadminand every method—or it takes the first existing rule withadminthat isn't read-only and lists*or every method of the administration (GET,POST,PATCH,DELETE); - the person with this rule (an existing person of the same name is enabled);
- a personal key, which the command displays once.
The person sets up the second factor at their first sign-in to the administration app (see
Set up at first sign-in). With --totp this happens
directly in the console: the command shows the QR code and the key for typing in, and saves only when a
code from the app matches. The change log records each of these changes with Konsole (Rechner, Konto)
(console (computer, account)).
| Command | Effect |
|---|---|
init-admin [--name N] [--windows ACCOUNT] [--no-key] [--label T] [--totp] [--force] [--service-account ACCOUNT] | First administrator as above; without --name, the command asks for the name. If the store is missing, it creates it, readable also for the account from --service-account (the account the service will run under). --windows sets the person's own Windows account and assigns it to the administration rule by its SID (WindowsAccounts); if Windows sign-in isn't turned on, the command tells you. --no-key works only together with --windows; see First administrator. Refused (return code 2) as long as someone can administer—except with --force, the recovery |
admin-status | Who can administer and what the others are missing (blocked, no valid key, no factor); return code 1 if nobody can administer. Someone who only has a Windows account without an assignment, or only a dormant or network-bound key, also counts as “can administer”; if in doubt, check with a real sign-in |
reset-totp --person N | Removes the person's second factor and opens setup at the next sign-in |
list-sign-in-rules | The sign-in rules with their IDs |
remove-sign-in-rule --id N | Removes a sign-in rule, such as a Deny rule that locks out the administration |
Typical situations: phone with the authenticator app lost → reset-totp. Last administrator key blocked
or expired → init-admin --name … --force issues a new one. Rule deleted → init-admin --force creates
it again. A sign-in rule locks everyone out → list-sign-in-rules, then remove-sign-in-rule.
People and keys
Wkl.Data.Gateway save-person --name "Jane Doe" [--rule fachdaten-lesen | --no-rules] [--login jane | --no-login] [--disabled | --enabled] Wkl.Data.Gateway issue-key --person "Jane Doe" --label "Excel report" --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 creates a person, or changes only what's given for an existing one; everything else stays.
Without further options, a new person is enabled, has no SQL Server login and no rules. --rule
replaces the rules as a whole, --no-rules removes them all, --no-login removes the SQL Server login,
and --enabled enables the person again. Every rule must be in the administration store; the command
refuses an unknown name (return code 2) and lists the existing rules. The change log records the change
as Konsole (computer, account). --rule,
--database, --from and --except-from may appear more than once. An unknown name (such as --rules)
is rejected, so that a typo doesn't issue a key without the intended restriction. issue-key outputs the
key once; list-keys shows ID, person, last 4 characters, state, expiry, last use, restrictions and
label, never the key. Return codes as for reseal-store: 0 done, 1 not everything possible (for
example an unknown ID), 2 store, setting or command line unusable.
reseal-store
Wkl.Data.Gateway reseal-store (or dotnet Wkl.Data.Gateway.dll reseal-store)
Re-encrypts every value in the administration store that is still under a retired master key
(Gateway:Store:RetiredKeys) with the current one (MasterKey, MasterKeyId): the connection strings
of the data sources, the secrets of the second factors, and the license key of the geolocation database. Everything happens in one transaction;
modification times are kept. The command doesn't start a web server and exits afterward. It may run while
the service is running; the service then reloads the store.
Prerequisite: the same configuration as the service, so run it with the program folder as the working directory, with the current key and all retired keys. The complete procedure for a key change is described in Change the master key.
Return code of reseal-store | Meaning |
|---|---|
0 | All values are sealed with the current key |
1 | Individual values couldn't be opened and stayed unchanged; the output names the data sources. The others are resealed |
2 | No administration store configured or settings unusable (the message names the setting) |
A key ring doesn't replace a lost key: values whose key is no longer available can only be entered again.
backup-store
Back up the store. While the service is running, use the backup-store command, started with the
same configuration and the same content root as the service:
Wkl.Data.Gateway backup-store --to "E:\Backup\gateway-2026-10-01.db" # or: dotnet Wkl.Data.Gateway.dll backup-store --to …
The command doesn't start a web server. Using SQLite's VACUUM INTO, it writes a single, self-consistent
copy of what a read transaction sees, even while the service is writing. It then checks the copy with
PRAGMA integrity_check and exits. Simply copying the file isn't enough: next to it are -wal and
-shm, and a copy taken in the middle of a write can contain a half-finished state.
- No master key needed. The store is opened read-only; the sealed values go into the copy unchanged. A backup task therefore doesn't need access to the key, and without it the copy can't open any database connection.
- Readable only by the executing account and the administrators. The target file is created empty and with this access control list, without inheriting from the folder, before SQLite writes to it; on Linux, only its owner can read it. The service account isn't included: a backup isn't a store in operation. Names, rules, people and the change log are readable in it and need to be kept locked away like any other backup.
- Doesn't overwrite anything. An existing target is rejected; each backup gets a new name. The target's directory must exist.
- Doesn't change anything. No schema version upgrade runs; the copy has the version of the file.
- Backs up the log file too. The command copies the log file (
Gateway:Store:LogPath, otherwise-logsnext to the store) the same way, next to the target, with-logsadded to the name:--to "E:\Backup\gateway-2026-10-01.db"also yieldsgateway-2026-10-01-logs.db. Put back that way, both open like the original. If there's no log file, it backs up only the store and says so. Either both copies are created or neither.
Return code of backup-store | Meaning |
|---|---|
0 | Copies written and checked; the output names the targets, schema version and sizes |
1 | Writing or checking failed (disk, permissions, check); incomplete copies are deleted |
2 | No store configured, store file missing, --to missing, a target exists or its directory is missing |
--to-folder DIR writes the backup under a name based on the time (gateway-<YYYYMMDD-HHMMSS>.db, plus
gateway-<YYYYMMDD-HHMMSS>-logs.db) and creates the folder; --skip-missing makes a store that doesn't exist yet not an error (return code 0).
The installation package uses both for the backup before an upgrade.
Geolocation database
Wkl.Data.Gateway update-geoip downloads the geolocation database files from the source chosen in the
administration (`set-geoip-source`).
Wkl.Data.Gateway import-geoip --file FILE [--source dbip-lite|maxmind] [--force] accepts a file that
reached the server another way (.mmdb, .mmdb.gz, or MaxMind's .tar.gz), for a server without
internet access. --source sets the attribution; --force also accepts a file that is older than or
as old as the current one.
Both put the file into the geolocation database folder (Gateway:SignInLog:GeoIp:Folder); a running
service puts it into use within a minute. The output lists the kind, build date, and whether each file
was accepted.
| Return value | Meaning |
|---|---|
0 | files accepted or already current |
1 | refused; the output gives the reason (no source, the source refuses, the file is unusable or older) |
2 | no administration store configured, unusable settings, a missing option, or the file given with --file can't be read |
Load log
Wkl.Data.Gateway export-load --to FILE [--days N] writes the load of the last N days (default
30, at most Gateway:LoadLog:HourDays) as a JSON file in the same format as the administration's
`export-load` command: shapes, hourly figures, and advice, without
persons, origins, or values. The command doesn't overwrite an existing file. Because it runs without
the service's catalog, the unindexedFilter advice is missing from the file.
| Exit code | Meaning |
|---|---|
0 | File written |
2 | No administration store configured, settings unusable, --to missing, --days out of range, or the file already exists |
setup-host and setup-remove
Wkl.Data.Gateway setup-host [--program DIR] [--data DIR] [--service-account ACCOUNT|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]
| Option | Default | Meaning |
|---|---|---|
--program DIR | folder of the program | program folder; the command writes appsettings.Production.json there |
--data DIR | %ProgramData%\Wkl.Data.Gateway | data folder with the store and geheim\hauptschluessel.key; permissions only for Administrators, System and the service account. It holds the folder updates for database updates: only Administrators and System change it, the service account reads |
--service-account ACCOUNT | none | NT SERVICE\Wkl.Data.Gateway | account the service runs under; a virtual account must already be registered as a service |
--mode standalone | iis | standalone | standalone: the service accepts HTTPS itself. iis: IIS accepts HTTPS and forwards to 127.0.0.1; the command enters 127.0.0.1 and ::1 as trusted proxies, sets AuthMode to PersonalKey (without Windows sign-in) and writes the template iis\web.config |
--port N | 8434 | HTTP port, only on 127.0.0.1 |
--https-port N | 8433 | HTTPS port (standalone only) |
--certificate NAME | — | subject of the certificate in the computer's store; without this option, no HTTPS |
--self-signed | off | creates a self-signed certificate for --certificate—for trying out only, refused with --access internet |
--access internal | internet | internal | internal creates no sign-in rules; internet creates sign-in rules for requests from outside the --networks—only as long as the administration store doesn't exist yet, after that its rules apply: administration refused or with a second factor (--admin-from-outside), Windows sign-in and SQL Server login to data with a second factor, service key refused. Personal keys remain without the requirement, because they're restricted per key |
--networks LIST | — | corporate networks, comma-separated; required with internet, and the basis of the firewall rule. Without networks, the rule allows every network with internal |
--admin-from-outside deny | totp | deny | administration from outside refused or with a second factor |
--firewall | off | inbound rule “Wkl.Data.Gateway HTTPS” for the HTTPS port (443 with iis), restricted to --networks with internal |
--pq-hybrid | off | turns on Windows' hybrid post-quantum key exchange (computer-wide, see HTTPS and certificate) |
--installation-name NAME | — | name of the installation in the authenticator app (Gateway:Store:TotpIssuer) |
--sql-server SERVER | — | writes the script for the service account's login on this SQL Server to the data folder as dienstkonto-anmeldung.sql, like `service-login` with --script. If that isn't possible (virtual account, SQL Server on another machine, machine in no domain), the command reports it and still completes the setup |
--sql-databases LIST | — | databases of the script, comma-separated |
--sql-roles readwrite | read | none | readwrite | roles of a new user in the script |
Return code 0: set up (a certificate that isn't in the store yet isn't an error—the service takes it
as soon as it's there); 1: a step failed; 2: wrong command line. The package rolls back on anything other
than 0. Rejected values include --access internet without networks, a network with host bits set or in
short, hexadecimal or octal notation (192.168, 0x7f.0.0.1, 017.0.0.1), --self-signed together
with --access internet, and an --installation-name with more than 64 characters, a colon or quotation
marks. Without --installation-name, Gateway:Store:TotpIssuer stays at the service's default value.
acme-client
Wkl.Data.Gateway acme-client
Names the wacs.exe that Zertifikat-LetsEncrypt.cmd orders with: the path on the first line of the
output, the reason on the error stream. That's an existing win-acme if its scheduled task
win-acme renew (…) points to it (version 2.2.9 or later), otherwise the bundled one in the program
folder. Exit code 0: path named; 1: the existing win-acme is too old or its version can't be read;
2: wrong command line. Needs administrative rights to read the tasks; without them, the bundled one
applies.
service-login
The service account's login in SQL Server and a user in each database: as a script for the database administrators, or created right away with the Windows account of the person who runs the command (not with the service account). Unlike the other commands, it reads no configuration and needs no administrative rights on the machine, only the permissions in SQL Server.
Wkl.Data.Gateway service-login --server SERVER [--database DB[,DB...]] [--roles readwrite|read|none]
[--account ACCOUNT] [--script FILE] [--apply] [--trust-server-certificate]
| Option | Default | Meaning |
|---|---|---|
--server SERVER | — | SQL Server as in a connection string, for example ., .\SQLEXPRESS, or tcp:db01,1433; without ;, =, quotation marks, and braces |
--database LIST | — | databases, comma-separated; without the option, only the login |
--roles readwrite | read | none | readwrite | roles of a new user: db_datareader and db_datawriter, db_datareader only, or none |
--account ACCOUNT | NT SERVICE\Wkl.Data.Gateway | account the service runs under. On another machine, the login for the virtual account is the computer account DOMAIN\MACHINE$; outside a domain that isn't possible (exit code 1) |
--script FILE | — | writes the script to this file (UTF-8); without --script and --apply, to the console |
--apply | off | creates instead of only writing the script: signs in to master with Windows authentication and runs the steps |
--trust-server-certificate | off | when creating, accepts a SQL Server certificate that no trusted authority issued (SQL Server Express creates its own) |
The script changes nothing that already exists: an existing login (looked up by the Windows account,
so also after a rename) and an existing user stay as they are, including their roles. A second run
therefore changes nothing. Each database is a transaction of its own: the user is created with its
roles or not at all. Names reach SQL Server as values and become identifiers there through QUOTENAME.
With --apply, the console shows one line per step:
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: The server principal ... is not able to access the database ...
A FEHLER (error) line names SQL Server's error number. If the login itself fails, no databases
follow. Exit code 0: everything created or already there; 1: a step was refused or the server wasn't
reached; 2: wrong command line.