Skip to navigation
Fleet Node

Update a Fleet Node

View as Markdown

Run the installer for an exact newer release on the Fleet Node host. Fleet Node does not update itself or resolve a moving latest channel.

Use a release supported by your Fleet deployment. When possible, use the same release tag as Fleet. Confirm that the target release includes install-fleet-node.sh and an archive for your host architecture on the Proto Fleet releases page.

1

Read the installed version

cat /opt/fleetnode/version.txt

The file reports the exact installed tag.

2

Install the target release

Set VERSION to the exact target tag. This example uses v0.3.1-rc.6:

VERSION=v0.3.1-rc.6
bash <(curl -fsSL "https://github.com/block/proto-fleet/releases/download/${VERSION}/install-fleet-node.sh") "${VERSION}"

The installer downloads and verifies the candidate before it interrupts an active service. It then stops the service, replaces the Fleet Node program and plugins, reloads the systemd unit, and starts the service again.

Enrollment state under /var/lib/fleetnode and configuration under /etc/fleetnode remain in place. You do not need to enroll the node again.

If the new service cannot start, the installer restores the previous program, plugins, service unit, and enrollment helper, then restarts the previous service.

3

Verify the update

cat /opt/fleetnode/version.txt
sudo systemctl is-active fleet-node.service
sudo journalctl -u fleet-node.service -n 100 --no-pager

Confirm that the version file contains the target tag, the service is active, and Settings → Nodes shows the node as Online without an update warning.

The service is briefly unavailable during replacement. Miners continue running, but Fleet cannot collect telemetry or send commands through this node until it reconnects.

If the service was already inactive or in an error state, the installer leaves it stopped after replacement. Start it after correcting the original problem:

sudo systemctl start fleet-node.service

Install from staged files

Use staged files when the Fleet Node host can’t download from GitHub releases. You download the release on another computer, copy it to the host, and the installer reads it from a local directory instead of the network. The same steps work for a first installation and for an update.

1

Download the release files

On a computer that can reach the release, set VERSION to the exact target tag and ARCH to the host architecture, amd64 or arm64. Then download the installer, the archive, and its checksum:

VERSION=<version>
ARCH=<arch>
RELEASE_URL="https://github.com/block/proto-fleet/releases/download/${VERSION}"
curl -fsSLO "${RELEASE_URL}/install-fleet-node.sh"
curl -fsSLO "${RELEASE_URL}/fleetnode-${VERSION}-linux-${ARCH}.tar.gz"
curl -fsSLO "${RELEASE_URL}/fleetnode-${VERSION}-linux-${ARCH}.tar.gz.sha256"

Use the installer from the same release as the archive. The installer rejects an archive whose metadata names a different repository.

Installers from Proto Fleet v0.6.0-rc.1 and later support --release-dir. To confirm, or for a release from another source, check the downloaded installer:

bash install-fleet-node.sh --help | grep -q -- --release-dir && echo "Staged installs supported"

If nothing prints, this release can’t install from staged files. Choose a newer release.

2

Stage the files on the host

Copy the three files to the Fleet Node host. On the host, as the user who will run the installer, go to the directory that holds the copied files and move the archive and checksum into a directory named after the release:

VERSION=<version>
mkdir -p "$HOME/fleetnode-releases/${VERSION}"
mv fleetnode-"${VERSION}"-linux-*.tar.gz fleetnode-"${VERSION}"-linux-*.tar.gz.sha256 \
  "$HOME/fleetnode-releases/${VERSION}/"
chmod -R go-w "$HOME/fleetnode-releases"

The installer checks the whole path before it reads the files:

  • Every directory from / down to the version directory, and both files, must be owned by root or by the user who runs the installer, and that user must be able to read them. If root owns the staged files, make them readable with sudo chmod -R a+rX <release-dir>.
  • The path can’t contain symbolic links.
  • The release directory, the version directory, and both files can’t be writable by group or others. A directory above the release directory can be writable by others only if it has the sticky bit, like /tmp.

These rules keep other accounts on the host from swapping the files before the installer copies them. A release directory in your home directory usually meets them.

The checksum file travels with the archive, so it catches a damaged copy but not a replaced one. Copy the files over a channel you trust. To confirm the copy, compare the checksum on the host with the .sha256 file on the download computer:

cat "$HOME/fleetnode-releases/${VERSION}/"fleetnode-*.tar.gz.sha256
3

Run the installer

Pass the absolute path of the release directory, not the version directory:

bash install-fleet-node.sh --release-dir "$HOME/fleetnode-releases" "${VERSION}"

Run this as the user who owns the staged files, not with sudo. The installer asks for sudo when it needs to change the system.

The installer copies the staged files, then checks and installs them the same way as a download, including the automatic rollback. If a file is missing or breaks the rules above, the installer stops before it changes the service. It never falls back to downloading from GitHub.

After a first installation, the service stays stopped until enrollment finishes. Continue with Start enrollment in Fleet in Install and enroll a Fleet Node. After an update, check the installed version, the service, and Settings → Nodes as described in Verify the update above.

For download, checksum, staging, startup, or rollback problems, see Fleet Node troubleshooting.