Releases you can trust

Your node updates itself every day, from a mirror on the internet. This page explains why it installs only what the Dassie release key signed, and how it gets back on its feet when a new release does not start.

One key signs every release

Each release on the mirror at get.dassie.land comes as one bundle per platform and a Nix flake, and a file of their checksums, SHA256SUMS. That file is signed with minisign, using the release key. The signature's trusted comment reads dassie <version>, so the signed checksums of one release can never pass for another's.

• The public key is in the repository, in resources/minisign.pub. It is built into every dassie binary and into the install script. Nothing else is trusted.
• The secret key lives only in the release workflow on GitHub, which only a version tag can run. It is never on a developer's machine or in ordinary CI.
• Nothing is signed untested. The workflow signs a release only after the install tests pass on every Linux distribution it tests, and checks its own signature, with the code the updater uses, before it uploads anything.
• Published files never change. Once a version is on the mirror, its files stay exactly as they were signed.

Each release is built once, on one builder, and its signature vouches for what that build made. A second, independent build to compare it against is not there yet. What's next

Why minisign, and why it works this way

Checked before anything unpacks

The installer and the updater follow the same order, and stop at the first thing that does not check out:

1. Download SHA256SUMS and its signature, and verify the signature against the built-in key, for the version asked for. Nothing in the file is read before that.
2. Download the bundle and check it against its sum.
3. Unpack it into a staging directory, taking only plain files and folders: no links, and no path that leads outside the bundle.
4. Run the new binary's own check, dassie verify-install, and make sure it names the version it was installed as.

Only then does anything switch. The installer needs no extra tool for this: it uses minisign if you have it, and OpenSSL 1.1.1 or later if you do not.

What the mirror can and cannot do

The mirror is not trusted, and neither is its HTTPS certificate. It names the newest release in a file, meta/latest, which is not signed. So it never decides which way a node moves:

• On its own, the updater only ever moves to a later release than the one it runs. A mirror cannot take a node back to an old version.
• A mirror can hold a release back, or keep offering an old one. It cannot make a node install anything the key did not sign for that version.
• Only you can move a node to an older release, by naming the version yourself.

There is one channel, the newest release, and every version on it is a signed release. There are no nightly builds.

Pre-releases, on a channel a node joins only when its owner asks, are not there yet. What's next

Updating and rolling back

A systemd timer, dassie-update.timer, runs dassie update once a day, at a random moment in the hour after 03:20. Each version is unpacked into a folder of its own under /opt/dassie, and a link, /opt/dassie/current, names the one that runs. The switch is a single rename of that link, and the version before stays beside it.

After the switch, the updater restarts the node and waits for it to say it is ready. If it does not come up, the updater rolls back by itself:

• It points current back at the old version, with the old version's systemd units, and starts it again.
• If the new version had already moved your database forward, the old version could not open it. The node keeps a copy from just before it migrates, and the updater puts that copy back, keeping the newer database beside it as dassie.sqlite3.rolled-back. The copy was taken before the new version served anything, so nothing it is missing ever reached a peer.
• If the database cannot be put back safely, the updater does not start the old version at all, and tells you where each copy is, so you can choose. A node never starts afresh with a new identity and empty books by accident.
• A version that failed to start is not tried again until the mirror offers a newer one. You can still install it on purpose with --force or --target-version.

If you installed with --no-service, there is no timer, and you run the update yourself: dassie update --unit <name>.service=<data directory>, once for each unit that runs a node. It checks every release the same way. It then installs none of the release's units and restarts yours, and on a rollback it stops them, puts back each node's database and starts them again. A plain dassie update installs the release's units and restarts dassie.service, as on a normal install.

Every run is recorded, and dassie status shows how the last one went. See Updates and rollback for the commands.

On NixOS

Each release also publishes a Nix flake. Its package is the same signed bundle, fetched by the checksum in SHA256SUMS: nothing is compiled or patched. Nix checks the flake by your lock file, not by the release key, so check the flake once against the signed checksums, and your lock holds you to the signed binaries from then on. There is no updater on NixOS: you update by moving the flake input forward, and go back by going back a generation. If the newer release migrated your database, put back the copy it kept before migrating, by hand, before the older generation can start. See Dassie on NixOS for the steps.

The desktop app does not come from the mirror. You build it from the repository with Nix, and it does not update itself.

Check a release yourself

You can check any release by hand, with the same key the installer uses. For example, for the x86-64 bundle of 0.3.0:

$curl -sSfO https://get.dassie.land/0.3.0/SHA256SUMS
$curl -sSfO https://get.dassie.land/0.3.0/SHA256SUMS.minisig
$curl -sSfO https://get.dassie.land/0.3.0/dassie-0.3.0-linux-x64.tar.gz
$minisign -V -H -P RWQyFJT+UgaWXQaBu5IkTRgPZjjYDNcCm4Sl6Wci0znLMDI0mJEoN3h2 -m SHA256SUMS
Signature and comment signature verified
Trusted comment: dassie 0.3.0
$sha256sum --check --ignore-missing SHA256SUMS
dassie-0.3.0-linux-x64.tar.gz: OK

Make sure the trusted comment names the version you asked for. The mirror's layout and the key's details are on Release mirror and key.

What the release process trusts, in full