subnera updates: notices, the daily check and verifying downloads

subnera tells you when a newer version exists and can install it for you when you ask (or when you opt in to automatic installs). This guide covers how that notice reaches you, what the check sends over the network, and how to install an update safely.

How you are told

• Menu bar app: a menu item "Update to subnera X…" appears (X is the new version). Choosing it downloads the update, verifies it and restarts subnera on the new version; Train at Home keeps running. During a bandwidth measurement the item reads "Update to subnera X (after the bandwidth measurement)" and is disabled. When the app cannot replace itself (a development build, run from the DMG, or not in a writable folder) it reads "Update Available: subnera X — Download…" and opens the download page. There is no notification and no badge on the menu bar icon. To check right away instead of waiting for the daily check, choose Check for Updates…: it answers in a dialog (newer version available, up to date, or why the check failed) and offers to update. The version you are running is shown just above Quit subnera.
• Command-line agent: subnera-agent status shows an update: line with the version and the download address, and the agent writes one line to its log (~/Library/Logs/subnera/agent.log) for each new version it sees.

What the daily check sends

At start-up, and then at most once a day once a check succeeds, the app or agent makes two small requests:

GET https://downloads.subnera.com/latest.json
GET https://downloads.subnera.com/latest.json.sig

The User-Agent header carries the product and its version (subnera/<version> from the app, subnera-agent/<version> from the agent), so the server knows which version asked. The requests have no identifier, no cookie and no query string, and they are sent in an ephemeral session that stores nothing. The files are served through Cloudflare, which, like any web host, sees your IP address. subnera first checks that latest.json is signed by the subnera release key (latest.json.sig) and ignores it otherwise. It then compares the version in the answer with its own and, if it is newer, shows the notice. If the request fails (offline, a captive portal, a malformed answer, a missing or invalid signature), nothing is shown and nothing else happens. The app tries again about 30 minutes later; the agent tries again the next day. The check only ever downloads those two small files; the update itself is downloaded only when you choose "Update to subnera X…", run subnera-agent update, or have turned on automatic installs.

Turning it off

• App: Options → Check for subnera Updates (untick it).
• CLI: subnera-agent update-check off (and on to turn it back on). subnera-agent status shows the current value as update check.

With the check off, subnera makes no request of its own to downloads.subnera.com; you can still choose Check for Updates… (one request, only when you click) or look on the download page↗ whenever you like.

Installing an update

• App: choose Update to subnera X…. subnera downloads the DMG from downloads.subnera.com, checks the SHA-256 against the signed release manifest and the code signature, replaces itself and restarts. To have this done for you, tick Options → Install subnera Updates Automatically (off by default).

• App, fallback: a copy run straight from the disk image, or from a folder your account cannot write to, cannot replace itself; the menu then offers the download link instead. Open the DMG and drag subnera to Applications, replacing the existing copy (quit the app first).

• App, first time: the app moves to the first self-updating version (1.0.7) with a normal DMG install; after that, updates install from the menu.

• CLI: subnera-agent update downloads, verifies and installs the new binary, then restarts the agent if it runs at login. subnera-agent update --check only says whether a newer version exists. subnera-agent update --auto on makes the running agent install updates by itself (off by default). Versions up to 1.0.6 have no update command: reinstall once with the install script, then subnera-agent install:

  curl -fsSL https://subnera.com/install.sh | sh
  subnera-agent install
  

  The second command is idempotent: it rewrites the LaunchAgent and restarts the agent on the new binary. From then on, subnera-agent update is enough.

Verifying a download

The download page↗ shows the SHA-256 of the DMG and of the agent archive, taken from the signed release manifest. Compare the checksum of what you downloaded with the value shown there:

shasum -a 256 ~/Downloads/<the file you downloaded>

The two values must be identical. The install script does the same comparison for the agent automatically and stops, installing nothing, on a mismatch.

Why automatic installs are off by default

A tool that replaces software on its own can interrupt a miner in the middle of a task, and it asks you to trust whatever it fetches. So subnera only installs when you ask, unless you opt in. Whatever the trigger, an update is installed only if the download comes from downloads.subnera.com, its SHA-256 matches the signed manifest, its code signature is valid and its version is the announced one. The check is the only network request subnera makes by default besides your own hub reports and the optional features described in the privacy guide.