WKL Database Update service (reference)

The “WKL Database Update” service applies signed database update packages without the data service. It follows the same procedure as the update module of the data service: it checks the packages in a database's inbox, backs the database up, applies, announces and reports. If you run the data service, you do not need this service. For the setup steps, see Apply database updates without the data service.

msiexec /i Wkl.Data.Update-<version>.msi [PROPERTY=value]… [/qn]
Wkl.Data.Update.exe <command> [<id>] [arguments] [--json]

Run the commands on the server from an elevated command prompt.

Wkl.Data.Update-<version>.msi installs the program in C:\Program Files\Wkl\Database Update (self-contained, so the server needs no .NET runtime, and with the SQL Server provider), sets up the Windows service Wkl.Data.Update with automatic start, and starts it. It is separate from the installer of the data service.

During installation, the program (setup-host) creates the folders below with their own permissions and registers the event source WKL Database Update in the Application log. Removal deletes the event source again.

The folders are fixed below %ProgramData%\WKL\Database Update. None of them inherits the permissions of %ProgramData%.

A file <id>.json in databases sets up a database. Its structure and fields are the same as for the update module, with three differences:

• Sign-in. Without connection.secret, the service signs in with its own Windows account (Integrated Security=True in connection.string); that account needs the permissions in the database to change its structure and back it up. With connection.secret, it signs in with the SQL login in connection.string and takes the password from the environment variable or file (env:NAME, file:PATH).
• gatewayAlias has no effect: applications do not reach the database through a data service. The service sees open sessions of older applications through the database itself.
• mail names the mail server for the email channel: server, port (default 25), from, and an optional secret (env:NAME, file:PATH). Port 465 is encrypted from the first byte; any other port requires STARTTLS. The service never sends unencrypted, and the mail server's certificate must be valid. With secret, it signs in with the sender address as the user name; without it, it sends without signing in, for example through an internal relay. The data service's update module uses `Gateway:Mail` instead.

"mail": { "server": "smtp.example.com", "port": 587, "from": "updates@example.com", "secret": "file:C:\\ProgramData\\WKL\\Database Update\\mail.txt" }

A file that anyone other than Administrators and SYSTEM can change, a password in connection.string, or a file name that differs from the id leaves the database out; databases lists the file and the reason.

The service writes the file <id>.json in settings through the settings command. A missing key or file takes the default. The service does not replace a file that is not valid JSON or holds a value out of range with defaults: the database waits until the file is correct.

{
  "expand": "automatic", "contract": "confirm", "noticeMinutes": 60, "sessionWindowMinutes": 15,
  "backup": { "keepCount": 10, "keepDays": 30 },
  "notify": { "channels": ["eventlog", "file"], "email": { "to": null } }
}

Backup retention works as in the update module. Mail on the email channel goes through the mail server in the protected configuration's mail to notify.email.to, outside the update pass: a slow or unreachable mail server delays the mail, never a package. If mail is missing, secret cannot be resolved, or the mail server does not accept the message, a warning goes to the event log, where the report itself is recorded anyway.

<package> is the id column of status. --json prints the data as JSON; status --json has the same format as update-status of the data service.

Exit code. 0 done; 1 wrong call, unknown database or package, package in another status, database unreachable, or service unreachable; 10 a pass is applying a package right now (try again shortly); otherwise the package's code, for example 7 waiting for confirmation.

The Application log, source WKL Database Update, holds the events of the packages with IDs 4101 to 4106 (as for the update module), plus the start of the service and every administration command with the Windows account that ran it. The file channel writes log\<YYYY-MM-DD>.jsonl per day (UTC); the service never deletes these files.

• Who may administer. The commands hand the request to the running service through the named pipe \\.\pipe\Wkl.Data.Update. Only Administrators and SYSTEM may open it, and it refuses every connection from the network; there is no administration from another computer. Without an elevated command prompt, Windows denies access.
• Who acts. The service carries out every command with its own account. The administrator needs no permissions in the database. On a confirmation, the service records the caller's Windows account (DOMAIN\name) in the database as the one who confirmed.
• Only to the service. The command line sends only when the running service Wkl.Data.Update is at the other end of the pipe.
• No overlap. Commands and passes run one after the other. While a package is running, a command waits up to ten seconds and otherwise ends with 10.
• Pass. Every 15 seconds; without a file in databases, the service does nothing.

C:\> "C:\Program Files\Wkl\Database Update\Wkl.Data.Update.exe" status kunden
Stand von kunden.
  Kunden, Schema 13
  Paket 41  Kunden-schema-14.zip  Schema 14  contract  waiting  Grund 7
    Ein nicht abwärtsverträgliches Paket (contract) wartet auf Bestätigung.
 
C:\> "C:\Program Files\Wkl\Database Update\Wkl.Data.Update.exe" confirm kunden 41

The command line and the service answer in German.

• Apply database updates without the data service
• Service configuration (reference)
• HTTP: administration (reference)