Keyserver administration guide¶

The Keyserver is Undo’s license server. It grants floating licenses to UDB instances that connect to it, up to the number of seats in the license installed on it. This guide covers the most common way of running the Keyserver: installed to the default paths and managed by systemd. For less common setups, such as running under init.d, using a non-default installation prefix, or configuring multiple Keyservers, see the INSTALL.txt and README.txt files in the keyserver directory of the Undo release.

Installing the Keyserver¶

The Keyserver runs on 64-bit Linux, and is included in the Keyserver, UDB and Undo Suite release packages. To install it:

Download and extract the release package on the machine that will run the Keyserver, using the download link provided by Undo.
Install the Keyserver, telling it to install and start a systemd service:
```
$ cd undo-<version>/keyserver
$ sudo make install systemd=1
```

The installer creates a dedicated keyserver user and group to run the Keyserver, installs a systemd unit at /etc/systemd/system/undo-keyserver.service, and starts the service.

It uses the following default locations:

Purpose	Location
Binaries	`/usr/local/bin`
Usage log (SQLite database)	`/var/local/undo/undo-keyserver-ulog.sqlite`
Log file	`/var/local/undo/undo-keyserver.log`
License keys	`/etc/undo/keyserver/licenses`
Man pages	`/usr/local/man/man1`

If the release archive included a license key (server_key, in the keyserver directory), the installer installs that key too, so the Keyserver is ready to run as soon as installation completes. Otherwise, see Updating the license key below to install one.

Managing the service¶

Once installed, control the Keyserver using systemctl:

$ sudo systemctl start undo-keyserver.service
$ sudo systemctl stop undo-keyserver.service
$ sudo systemctl status undo-keyserver.service

To have the Keyserver start automatically when the machine boots (this is enabled by default after installation):

$ sudo systemctl enable undo-keyserver.service

Although UDB maintains a persistent connection to the Keyserver for the duration of a session, stopping or restarting the Keyserver doesn’t end any in-progress sessions: UDB simply pauses until the Keyserver becomes available again.

Log rotation¶

An example logrotate configuration is included in the release. To install it:

$ sudo cp logrotate.d_undo-keyserver /etc/logrotate.d/undo-keyserver

This configuration reloads the Keyserver via systemd after rotating its log file, so that the Keyserver re-opens the new file.

Updating the license key¶

The Keyserver loads license keys from the key store directory (/etc/undo/keyserver/licenses by default), automatically selecting the best non-expired key: the one with the most seats, and if several keys have the same number of seats, the one that expires furthest in the future. Manage these keys with undo-keyserver-ctl, which must be run on the Keyserver machine.

To install a license for the first time, given its license UID (available from Undo):

$ sudo undo-keyserver-ctl license get <UID>

This downloads and installs the key, and requires network access to Undo’s servers. To install a key that has already been downloaded to a file instead, use license install in place of license get.

To renew a license that’s already installed, fetching the latest version from Undo:

$ sudo undo-keyserver-ctl license update

To see which keys are currently installed, including their seat counts and expiry dates:

$ sudo undo-keyserver-ctl license list

Expired keys aren’t deleted automatically. To remove them:

$ sudo undo-keyserver-ctl license cleanup --force

(license cleanup without --force will list the licenses that would be deleted)

The Keyserver automatically reloads its keys when the one it’s using expires, but after installing a new key that you want to take effect immediately (for example, one with more seats), reload the Keyserver explicitly:

$ sudo systemctl reload undo-keyserver.service

Updating the Keyserver¶

To upgrade the Keyserver to a newer version, download and extract the new release archive as described in Installing the Keyserver, then run the same install command again from the new release directory:

$ cd undo-<version>/keyserver
$ sudo make install systemd=1

This replaces the installed binaries and restarts the service. It doesn’t affect the usage log database, installed license keys, or any other data in the Keyserver’s data or key store directories, so no separate backup step is needed before upgrading. As with any restart, in-progress UDB sessions pause and automatically reconnect once the upgrade completes.

Managing sessions¶

Use undo-keyserver-kick, run on the Keyserver machine, to list current sessions and terminate (“kick”) a specific one, reclaiming its license seat.

To list current sessions, in time order:

$ undo-keyserver-kick sessions
start time: 2026-07-10 09:12:03; shared id: <a1b2c3d4e5f6...>; version: 10.0.1

To kick a session, using the shared id shown by sessions, optionally giving a reason:

$ sudo undo-keyserver-kick kick --reason "reclaiming seat" <a1b2c3d4e5f6...>
Kicked <a1b2c3d4e5f6...>; the session will be terminated and the license released.

A kicked session ends without any opportunity to save unsaved work, so use this with care. Kicking a session needs write access to the usage log database, so kick (like interactive below) normally requires sudo or running as the keyserver user, unlike the read-only sessions and show sub-commands.

Rather than looking up shared ids by hand, undo-keyserver-kick interactive lists current sessions with a number and lets you select one to kick, prompting for confirmation and a reason:

$ sudo undo-keyserver-kick interactive
index: 1; start time: 2026-07-10 09:12:03; shared id: <a1b2c3d4e5f6...>; version: 10.0.1

Enter session index to kick (Enter to finish) : 1
Kick session <a1b2c3d4e5f6...> ? [y/N] : y
Reason for kicking : reclaiming seat
Kicked <a1b2c3d4e5f6...>; the session will be terminated and the license released.

Enter session index to kick (Enter to finish) :

To review sessions that have previously been kicked:

$ undo-keyserver-kick show

Kicks older than a week are considered expired and aren’t shown by default; pass --show-expired to include them, or a username to show only that user’s kicks.

Exporting usage information¶

The Keyserver continuously records usage information, such as license checkouts and user sessions, to its usage log database. Two tools can report on this data, and both should be run on the Keyserver machine.

undo-keyserver-usage produces human-readable reports for local use, for example:

$ undo-keyserver-usage --show-max-usage --show-num-sessions --show-num-users
Max concurrent sessions: 3. With recording: 2
Number of sessions: 18. With recording: 9
Number of users: 1. That used recording: 1

See undo-keyserver-usage --help for the full set of available reports, including options to filter or group by time period.

undo-keyserver-usage-export produces a structured JSON export intended for sending to Undo. With the Keyserver installed to the default locations, the only required argument is an output filename:

$ sudo undo-keyserver-usage-export undo-usage-$(date +'%Y%m%dT%H%M%S').json.xz

By default the output is compressed with XZ. Passing --auto-time-range makes the export incremental: it records the export time on disk and, on the next run, exports only data recorded since then, which is useful for scheduling regular exports with cron. Usernames and hostnames in the export can optionally be anonymised using --anonymise or --anonymise-key. See undo-keyserver-usage-export --help for the full set of options.