Your Burrow runs on your machine and updates itself from RatelKey's update service. Your Burrow always fetches updates itself. RatelKey never pushes anything to it, and an update has to pass your Burrow's own checks before anything is written to disk. This page covers how a release is made, what your Burrow checks, and what happens when it installs one. The switch for automatic installs is covered on the Burrow config page.
How a release is signed#
Every Burrow release is signed with RatelKey's release key, an Ed25519 private key. The signature covers four things: the product, the version number, the SHA-256 checksum of the release file, and its size. RatelKey's update service stores and serves releases and their signatures, but it never holds the private key.
The matching public key is built into every copy of Burrow. Your Burrow checks releases against that built-in key only.
What your Burrow checks#
Whether an update installs automatically or you install it yourself, your Burrow runs the same checks, in this order. If any of them fails, nothing is installed and your Burrow keeps running the version it has.
Signature. The release must carry a valid signature from RatelKey's release key. An unsigned release, or one whose signature doesn't match, is refused.
Version. The version must be newer than the one running. An older or equal version is refused, so a Burrow can't be moved back onto an earlier release, even a properly signed one.
Size. The download is stopped as soon as it passes the size in the signed release, and never allowed past 256 MB.
Checksum. The downloaded file's SHA-256 checksum must match the signed one. Since the signature covers the checksum, this ties the exact bytes on your machine to what RatelKey signed.
Build. The file must be a Burrow build for your machine's platform.
No sign-in is involved in checking for or downloading an update. The requests carry the platform your Burrow needs a build for, such as Linux or Windows on x86-64, and the version numbers involved, and nothing else about your Burrow.
Installing#
By default your Burrow checks for a new release every six hours, and tells you when one is available whether or not automatic installs are on. With Auto-install updates on, it installs the release after the checks pass. With it off, installing is your choice, from Burrow config, and the same checks run when you do.
Installing an update by hand needs permission to change the Burrow's config. Every install you start is recorded in the audit log with the version it moved from and to, and so is every check you run by hand.
Updates install only on a Burrow started by its installed launcher, since the launcher is what brings the new version up.
Handing over to the new version#
Once a release passes every check, your Burrow writes it beside the running version without touching the running one. It then takes a copy of its database and stops. The launcher saves a copy of the current version, moves the new one into place, and starts it.
If the new version can't be moved into place, the launcher removes it and starts the version you had.
If a new version fails to start#
One failed start is retried. If the new version fails to start twice in a row, your Burrow puts back the copy of the version that was running before and starts that. If it still can't start after five attempts in a row, it stops trying and leaves the reason in its log, since at that point the problem is with the machine rather than the version.
What RatelKey controls#
RatelKey decides which release is current, and can withdraw a release so that it's no longer offered to any Burrow. That is the extent of it. RatelKey can't install a release your Burrow hasn't checked, can't move your Burrow to an older version, and can't reach into your Burrow to change it. Your Burrow fetches updates itself and installs them only when you have allowed it to.