Nym-node auto-updater - keeps your node current, with health-check + auto-rollback (open source)

Running a node means babysitting releases: spotting a new version, downloading, verifying, swapping the binary, restarting, and hoping it comes back up. I wrote a small, self-contained tool that does all of that on a schedule and is built so it can’t leave a node down. Sharing it here in case it’s useful to other operators.

Repo + docs: GitHub - vvmmaann/nym-node-autoupdate: Safe auto-updater for nym-node: systemd timer, checksum-verified, auto-rollback · GitHub

Install (run as root):

curl -fsSL https://raw.githubusercontent.com/vvmmaann/nym-node-autoupdate/main/nym-node-autoupdate.sh -o nym-node-autoupdate.sh && sudo bash nym-node-autoupdate.sh

What it does

  • Installs a systemd timer that checks hourly and updates only when a new STABLE release is out (skips pre-releases).
  • Auto-detects your role (mixnode / entry / exit gateway) and shows you what it found before touching anything — nothing to configure by hand.
  • Updates nym-node on every role; on gateways it also updates the QUIC bridge and the exit-tunnel iptables rules (network-tunnel-manager).

Why it won’t break your node

  • nym-node is SHA-256 verified and refuses to install without a checksum.
  • After each swap it health-checks the service and auto-rolls-back if it doesn’t come back up.
  • Firewall changes are snapshotted and reverted if the tunnel stops passing traffic.

Handy

  • Read-only check anytime (no root): ./nym-node-autoupdate.sh check
  • Opt out of any part via /etc/nym-node-autoupdate.conf
  • Remove: sudo nym-node-autoupdate.sh uninstall

Trust model (stated plainly)
The QUIC bridge and the tunnel-manager script ship no upstream checksum, so those steps trust GitHub + the nym org — same as updating them by hand. nym-node itself is checksum-gated. Set NTM_ENABLED=0 to skip the firewall part.

I’m running it on my 4 nodes (2 gateways + 2 mixnodes). Feedback and PRs welcome.

3 Likes

Update - a few things landed since this went up.

The big one: it now has a Telegram companion, Nymi. Link a node (nym-node-autoupdate.sh link @yourtelegram) and Nymi pings you the moment the updater does something worth knowing - your node updated, a health-check rollback fired, or the node went offline - plus release / stake / stress alerts and an on-demand /status. It also adds a /update button that force-updates a node right now instead of waiting for the hourly timer. The node never holds a bot token - it authenticates with a per-node secret it generates itself. Full writeup: Nymi - my auto-updater, my checker, and a 3-year-old mascot walk into a Telegram bot.

Now works on systemctl --user nodes. If your nym-node runs as a lingering non-root user under systemctl --user rather than a system unit, the updater detects and drives it correctly now, instead of only seeing system-scope units.

NTM stays correct across releases (exit gateways). On a release that touches tunnel/firewall behavior, the updater now reads the operator changelog (not the dev one) to decide whether to re-run network-tunnel-manager - still pinned to the release commit, still snapshot-and-rollback protected.

Safety pass. Removed the changelog command auto-execution outright: the updater no longer evals anything fetched from the network - changelog commands are only surfaced for you to run by hand. Nymi’s calls are HTTPS-only and secret-authenticated. The whole thing (updater + Nymi) went through a security review.

Get the new stuff - update the script and link your node in one line:

curl -fsSL https://raw.githubusercontent.com/vvmmaann/nym-node-autoupdate/main/nym-node-autoupdate.sh -o /usr/local/sbin/nym-node-autoupdate.sh && chmod +x /usr/local/sbin/nym-node-autoupdate.sh && /usr/local/sbin/nym-node-autoupdate.sh link @yourtelegram

then press Start in @nyminodebot. Fresh installs ask for your @nick at the end and do it for you.

Repo (README now covers Nymi): GitHub - vvmmaann/nym-node-autoupdate: Safe auto-updater for nym-node: systemd timer, checksum-verified, auto-rollback · GitHub

1 Like

I have just installed the autoupdater and also added the telegram integration. Looks very nice so far.

Thanks for providing this tool!

1 Like

Welcome! Share any thoughts, bugs and improvements about it anytime!

Security update: pairing to Nymi changed

Since the updater now ties into Nymi and can be told to force-update from Telegram, the way a node links itself to you was the weak point, and it’s been reworked.

What changed. It used to link a node to you by a Telegram handle sent from the node (link @nick). The problem: anyone who knew a node’s public IP could send that and claim it. That’s gone. The new command is nym-node-autoupdate pair @yourhandle, run on the node, and it proves control by the pairing request coming from the node’s own IP. One step, on the box, and only after that can the bot force-update it. From the bot side, /addnode stays watch-only (alerts, no control); pairing is what unlocks force-update.

What still holds (unchanged, but worth stating in a security note): nym-node is SHA-256 verified against the release’s own checksums and refuses to install on a mismatch (or on no checksum, unless you explicitly override); the swap is atomic; a health check runs after restart with automatic rollback if the service doesn’t come back; a lock file prevents overlapping runs; and nothing fetched from the network is ever executed (changelog commands are surfaced for you to run by hand, never run for you).

Honest on the trust boundary. nym-node has that independent checksum verification. The QUIC bridge and the exit-gateway tunnel manager are fetched over HTTPS from the Nym GitHub and run without an independent checksum, which is the same trust as running Nym’s documented install by hand; where possible that fetch is content-pinned to a commit SHA, the tunnel step is opt-out, and any firewall change it makes is snapshotted first and reverted if an egress probe fails afterwards.

1 Like

Update: v1.1.0 and v1.2.0

  • Self-update (v1.1.0). sudo /usr/local/sbin/nym-node-autoupdate.sh self-update pulls the latest script from GitHub, checks that it really is this script and parses cleanly, keeps a timestamped backup, and does nothing if you’re already current. version prints the version, and status shows it too.
  • Gateways update on their own (v1.2.0).
    • The health check waits for 60 s of stable uptime within 180 s. A gateway that restarts once at startup on a chain RPC hiccup and comes back up passes; a crash loop rolls back. The rollback is verified the same way.
    • A gateway nym-node is stopped with SIGKILL, so an update costs seconds of downtime. On our gateways a graceful stop took 3-4 min. Mixnodes stop gracefully as before.
    • Nymi gets the real outcome of a force-update: updated, rolled back with the node still up, or busy with an hourly run.
    • Tunable via NYM_HEALTH_STABLE, NYM_HEALTH_MAX and NYM_STOP_MODE.
  • Releases and changelog are on GitHub: Releases · vvmmaann/nym-node-autoupdate · GitHub

To update an existing install: sudo /usr/local/sbin/nym-node-autoupdate.sh self-update

Update: v1.3.0 and v1.4.0

nym-api support (v1.3.0). If the box runs nym-api.service (validator API / ecash signer), the updater now updates it too, alone or next to a nym-node. Same release, SHA-256 check, 2h soak and hourly timer as nym-node. After the restart the API has to report healthy on the new build, and a signer has to keep its signing keys, otherwise it rolls back. It never restarts nym-api in the middle of a DKG ceremony. “Update now” in Nymi works for it after pair @yourhandle.

Quiet gate (v1.4.0). A mixnode is now restarted only while it is idle. Before the restart the updater reads the node’s own traffic (/api/v1/metrics/mixing). At 10 packets/s or more it waits for a later hourly run, and it checks again right before stopping the node. After 48h of waiting for the same release it updates anyway. Missing or stale metrics never block an update. Gateways are not gated by default. Tune it with QUIET_GATE, QUIET_PPS and QUIET_MAX_HOURS in /etc/nym-node-autoupdate.conf. “Update now” in Nymi skips the gate. Thanks to Andrew for the idea.

To update an existing install:

sudo /usr/local/sbin/nym-node-autoupdate.sh self-update

Changelog: nym-node-autoupdate/CHANGELOG.md at main · vvmmaann/nym-node-autoupdate · GitHub

Update: v1.5.0 to v1.7.0

Two upstream changes had made parts of the updater stop working, without any error. Both are fixed, and it now watches for this kind of change on its own.

QUIC bridge 0.3.0 (v1.5.0). nym-bridges changed its release tags from bridge-binaries-v* to v*, so gateways stayed on bridge 0.1.2. The updater takes v* tags now (still no prereleases) and moves gateways to 0.3.0. Only the binary is replaced, the same as the official upgrade-nym-bridge.sh --no-tls-ssh: same QUIC port, same key. After the swap the bridge has to listen on every port its config names, otherwise it rolls back. TLS and SSH are not turned on; for those, run the official upgrade script.

NTM notes (v1.5.0). On 14 October the Nym docs moved from pages/ to content/. After that the updater could not read the operator changelog, and re-ran network-tunnel-manager only when the tunnel stopped passing traffic. It reads the new path again. If a release is installed before its operator notes are written, it keeps checking for up to 48h, so a “re-run NTM” note that comes later is still acted on.

doctor (v1.6.0, v1.7.0). sudo /usr/local/sbin/nym-node-autoupdate.sh doctor checks what the updater relies on: release tag prefixes and asset names, where the operator notes live, and that NTM has every subcommand the updater calls. The hourly run does this by itself on every new nym-node or bridge release, prereleases included, so a rename shows up before a stable release needs it. If something is off, it alerts once (Telegram, if set up) and once more when it’s fixed.

Thanks to Merve for the question that turned this up.

To update an existing install:

sudo /usr/local/sbin/nym-node-autoupdate.sh self-update

Changelog: nym-node-autoupdate/CHANGELOG.md at main · vvmmaann/nym-node-autoupdate · GitHub

Update: v1.8.0

A small one. When a node paired with Nymi checks in, it now also sends the updater version (an X-Updater-Version header). That way I can see which paired nodes still run an old updater, instead of guessing who missed a fix. A check-in now carries the node’s IP, its secret and this version, nothing else. Update logic is unchanged, and if you don’t use Nymi, nothing changes for you.

To update:

sudo /usr/local/sbin/nym-node-autoupdate.sh self-update

Changelog: nym-node-autoupdate/CHANGELOG.md at main · vvmmaann/nym-node-autoupdate · GitHub

nym-node-autoupdate 1.9.2

The updater now reads the operator notes for each release and does what they ask, by node role, with Nym’s own scripts:

  • Exit gateways: NTM from develop, complete_networking_configuration
  • Gateways with a 0.3 bridge: quic_bridge_deployment.sh (TLS/SSH transports)

Update:

sudo /usr/local/sbin/nym-node-autoupdate.sh self-update

Repo: GitHub - vvmmaann/nym-node-autoupdate: Safe auto-updater for nym-node: systemd timer, checksum-verified, auto-rollback · GitHub