Offline depot

An offline depot is the directory kyvernon-<version>/ that holds the packages and the index depot.json. It lets you install and upgrade servers that have no internet access. Verify it against the release public key of Kyvernon, which you obtain from Kyvernon and not from the depot. The installer does not accept the key from the depot itself (the copy under keys/ is only there for comparison): the point of the signature is that the depot cannot vouch for itself.

What the depot holds

The roles select packages. controller installs the controller and the command-line client, agent installs the host agent, the VMM and the packages in deps/, cli installs only the command-line client. all installs everything.

Before you start

• The depot directory and, separately, the release public key.
• For the commands with kyvernon depot, the package kyvernon-cli is installed. The script kyvernon-install in the depot works without it.
• Root access for installing. Verifying needs no privileges.

Verify the depot

Copy the depot onto the server, then verify it as a normal user.

With the CLI

cd kyvernon-0.1.0
./kyvernon-install --verify-only --pubkey /path/to/release-signing.minisign.pub

or, with the command-line client:

kyvernon depot verify kyvernon-0.1.0 --pubkey /path/to/release-signing.minisign.pub

Both check the signature over the index, then the size and checksum of every file, and refuse a directory with files that the index does not list, or with symbolic links. The script prints depot ok on success; on any other output, stop and contact your supplier. If you prefer the standard tool, minisign -Vm depot.json -p release-signing.minisign.pub verifies the same signature.

The command-line client looks for the key in this order: --pubkey, the environment variable KYVERNON_DEPOT_PUBKEY, /etc/kyvernon/release-signing.minisign.pub, /usr/share/kyvernon/keys/release-signing.minisign.pub, and the key built into the binary. The script uses the first three. A --pubkey that lies inside the depot directory is refused.

Install from the depot

Install by role. Verification runs first, and dpkg receives only verified copies of the packages, so nothing changed in the directory after the check is installed.

With the CLI

sudo ./kyvernon-install --role controller --pubkey /path/to/release-signing.minisign.pub
sudo ./kyvernon-install --role agent --pubkey /path/to/release-signing.minisign.pub

With the command-line client, kyvernon depot install does the same; --dry-run prints the dpkg command and runs nothing:

sudo kyvernon depot install kyvernon-0.1.0 --role agent \
  --pubkey /path/to/release-signing.minisign.pub --dry-run

A host without the distribution packages ovmf or swtpm makes dpkg fail with a list of what is missing. Install them from your mirror, or use a depot that carries them in deps/, and run the command again. The first installation is described in Install from an offline depot; a new version in Upgrade.

Sign a depot

A depot is signed on a machine that is offline. The private key is an OpenSSL PKCS#8 Ed25519 key and never leaves that machine.

With the CLI

kyvernon depot sign kyvernon-0.1.0 --key /path/to/release-signing.pem
kyvernon depot pubkey --key /path/to/release-signing.pem

depot sign writes depot.json.minisig next to the index. The signature covers a trusted comment that names the version by default; --comment sets another one. depot pubkey prints the public key in minisign format and its key id, which is the first 8 bytes of the SHA-256 of the public key. With --pubkey instead of --key it prints the key id of a public key file, so you can compare the key you hold with the key id that the supplier publishes.

Result

A verified depot ends with depot ok. After an installation the packages are in place and no service is started yet.

Related

• Upgrade
• Install from an offline depot
• Uninstall