Back up, restore, and move the administration store

Everything administration sets up—data sources, rules, people, keys, second factors, sign-in rules—is in one file: the administration store. Without a backup, it's lost if the disk fails, and every person needs new keys and a newly set up second factor.

An installation consists of four parts, which you back up separately:

The store alone opens no database: the connection strings and second-factor secrets in it are encrypted with the master key. Without the master key, a backup is worthless. The installation package creates it as the file geheim\hauptschluessel.key in the data folder %ProgramData%\Wkl.Data.Gateway.

Backing up from the administration app—for occasional use, such as before a larger change: open Übersicht (Overview) and choose Speicher sichern (Back up store) on the command bar. The copy is created on the service's computer in the sicherungen folder next to the store, under a name based on the time (gateway-YYYYMMDD-hhmmss.db, with the log file next to it as gateway-YYYYMMDD-hhmmss-logs.db); the message names the file. The service chooses the location, not the application. Weitere (More) > Speicher prüfen (Check store) or a click on the Pflege (Maintenance) tile checks the store without changing anything. This folder is on the same disk as the store: to cover a disk failure, you additionally need the regular backup to another location, as follows.

Backing up as a scheduled task—during operation, on the service's computer. The backup-store command writes a self-consistent copy of the store and one of the log file, even while the service is writing, checks both, and ends with 0; it overwrites nothing. With --to-folder, it chooses the file names based on the time (gateway-YYYYMMDD-hhmmss.db and gateway-YYYYMMDD-hhmmss-logs.db), so that a daily task always writes new files. It doesn't need the master key. The log file can grow up to its configured size (Gateway:Store:LogMaxMegabytes, default 4,096 MB); plan the space and duration of the backup accordingly.

Prerequisites a scheduled task has to meet:

• Working directory = program folder. The commands read the configuration (appsettings*.json) from the working directory; if it's missing there, the command finds no store and ends with 2.
• Read permission on the store. Only the service account and the administrators may read it; the task therefore runs as SYSTEM or as an administrator.
• Target on another disk or another computer, so that a disk failure doesn't hit the store and the backup at the same time.

Example (PowerShell as an administrator; installation with the installation package):

$program = Join-Path $env:ProgramFiles 'Wkl\Data Gateway'
$action = New-ScheduledTaskAction -Execute (Join-Path $program 'dbgwsvc.exe') `
    -Argument 'backup-store --to-folder "E:\Backup\DataService"' -WorkingDirectory $program
$trigger = New-ScheduledTaskTrigger -Daily -At 2am
Register-ScheduledTask -TaskName 'Back up data service' -Action $action -Trigger $trigger `
    -User 'NT AUTHORITY\SYSTEM' -RunLevel Highest

Afterwards, check once with Start-ScheduledTask -TaskName 'Back up data service' that a file is created and that the task reports the result 0 (Get-ScheduledTaskInfo). The command doesn't delete old backups; you set the retention period yourself and clean up the target folder accordingly.

Restoring—on the same computer, as an administrator:

1. Stop the service: Stop-Service Wkl.Data.Gateway.
2. Replace the store file with the backup and delete the -wal and -shm files next to it. Copy, don't move (Copy-Item): a copied file inherits the permissions of the data folder, which include the service account. A moved file keeps the permissions of the backup, which name only the backing-up account and the administrators; the service then couldn't read it. The store file is the one set under Gateway:Store:Path; with the installation package, that's %ProgramData%\Wkl.Data.Gateway\dbgwsvc.db. Replace the log file the same way with the backup …-logs.db (location per Gateway:Store:LogPath, otherwise dbgwsvc-logs.db next to the store). Without it, the service starts with an empty sign-in log and load log. Keep the replaced files until the check in step 4 has passed.
3. Start the service: Start-Service Wkl.Data.Gateway.
4. Check in the administration app: Übersicht—the Pflege tile reports the store as OK, the Datenquellen gestört (Data sources with faults) tile shows 0—and for each data source, Verbindung prüfen (Test connection).

If the service doesn't start, the event log names the reason. The two most common:

The service converts a backup of an older version to its own version at startup and first creates a copy dbgwsvc.db.v<old>-<timestamp>.bak.

Moving—to a new computer:

1. Install the service, take over the configuration file, adjust addresses and certificate.
2. Put the backup in place as the store file, in a directory of its own that only the service account and the administrators may read, and the backup of the log file next to it under the store file's name with -logs appended (dbgwsvc.db and dbgwsvc-logs.db).
3. Provide the previous master key under the same ID.
4. Start and check as when restoring.

Result: people, keys, and second factors remain valid; they depend on the store and the master key, not on the computer.

• Don't just copy the file. Next to the file are -wal and -shm; a copy in the middle of a write can contain a half-finished state. Always use backup-store.
• Whatever was changed after the backup is lost after restoring—including keys issued afterwards, which the service then refuses.
• Whatever was blocked after the backup is open again after restoring: blocked keys, blocked people, reset second factors. Block them again after restoring, before the service becomes reachable again.
• New address after the move: the clients have to learn it—Access applications relink their tables, and the administration app gets the address on the sign-in card. A key stored in Windows applies per address and has to be stored again once.
• Wrong master key after the move: if it doesn't match, the service refuses to start and names every affected data source; nothing is changed.
• Permissions of the copied file: a copied store file inherits the permissions of the folder it's copied into. If that folder is more open than just the service account and administrators, startup names every additional account in a warning.
• Backups contain readable names, rules, people, and the change log; the backup of the log file also contains sign-ins with addresses and people. Keep them locked away.

The return values of backup-store are listed under Server commands: backup-store.

• Change the master key
• `backup-store` command (reference)