Skip to content

Update xahaud

The process for updating xahaud varies depending on the install method used, however, all three methods rely on the releases published at https://build.xahau.tech. When updating a validator, hub, or other ‘critical’ infrastructure, please check the network health prior to restarting a server to install an update. It is possible to automate the update process using a crontab entry and an update script, however, administrators are discouraged from doing so, as automatic updates may result in restarts at times when the network is unstable. Similarly, human presence allows operators to ensure updates are successful, thereby minimizing downtime.

Backup

Section titled “Backup”

Users should always keep backups of:

  1. The primary configuration file: xahaud.cfg
    • Location varies based on install type.
  2. The trusted validators file: validators-xahau.txt
    • Location is specified in ‘xahaud.cfg’.
  3. The server’s identity credentials: wallet.db
    • Located in the database directory defined in ‘xahaud.cfg’.
  4. Validators must keep their validation private key backed up in a secure, offline location.

Updating Docker Containers

Section titled “Updating Docker Containers”

Updating xahaud inside a Docker container involves replacing the currently running binary with the new version, downloaded from https://build.xahau.tech. This can be accomplished either by replacing the xahaud binary inside the container or by updating the entire container.


To update the xahaud binary inside a running Docker container:

  1. Download the script: wget https://gist.githubusercontent.com/WietseWind/2ed35d85dcd056d82645de2958934f86/raw/34be773fd6af42e82cc3a21baf70bfb1e2a6c583/update.sh
  2. Edit the script and change the first line to the release version you would like to install.
  3. Run the script: bash ./update.sh
  4. Verify xahaud is running: docker exec xahaud-[mainnet/testnet] xahaud server_info

To replace the current Docker image with a new version, without overwriting databases or configuration files (which are ignored via the .gitignore file):

  1. Navigate to the repository: cd [/path/to/docker-repo]
  2. Update to the latest version git pull
  3. List running Docker containers and note the name of the xahaud container: docker ps
  4. Stop the old xahaud instance: docker stop xahaud-[mainnet/testnet]
  5. Remove the old instance: docker rm xahaud-[mainnet/testnet]
  6. Start the new instance: ./build && ./up

Updating Local Installations

Section titled “Updating Local Installations”

To update a locally installed version of xahaud, simply replace the current binary with a new binary:

  1. Download the new binary from: https://build.xahau.tech
  2. Mark the new binary executable: chmod +x [/path/to/download]
  3. Stop the currently running xahaud instance: /opt/xahaud/bin/xahaud stop
  4. Replace the old binary with the new: mv [/path/to/download] /opt/xahaud/bin/xahaud
  5. Start xahaud: systemctl start xahaud
  6. Verify xahaud is running: /opt/xahaud/bin/xahaud server_info

A script that automates the above steps is available.

Updating Binary Files

Section titled “Updating Binary Files”

Updating the xahaud binary files is essentially the same as the original install instructions:

  1. Remove the currently running version: rm [/path/to/xahaud]
  2. Download the new version: https://build.xahau.tech
  3. Mark the download as executable: chmod 500 [/path/to/xahaud]
  4. Start xahaud: ./[path/to/xahud] --net --conf [/path/to/xahaud.cfg]

Amendment-Blocked Servers Stop

Section titled “Amendment-Blocked Servers Stop”

Starting with 2026.10.13-release+4119, a server that does not support an amendment the network is about to activate (or has activated) shuts down instead of running in a degraded “amendment blocked” state:

  • Before activation: once an unsupported amendment has reached majority and is expected to activate, the server checks on every validated ledger. When activation is less than 5 minutes away (or the expected time has passed and it is only waiting for the flag ledger), it stops, while it can still read the ledgers it is given.
  • After activation: a server that is already past the activation (for example, an old build being started) also stops.
  • Receipt file: on stopping, it writes README_AMENDMENT_BLOCKED into the config directory. The file contains the text XAHAUD STOPPED: UPGRADE REQUIRED, the stop time, the build version, the IDs of the unsupported amendments with their expected or actual activation time, and instructions to upgrade and restart.
  • On restart: the receipt is removed automatically. If the build is still unsupported, the server stops again and rewrites the file. Nothing needs to be deleted by hand.
  • Standalone mode does not write or remove the receipt.
  • Logs: fatal log lines are written, and the stop reason includes the receipt’s path.

To avoid unplanned downtime:

  • Upgrade before new amendments activate. Amendments that have reached majority are visible with the feature admin method.
  • Monitor for the shutdown, for example by alerting when README_AMENDMENT_BLOCKED appears in the config directory or when the xahaud process exits.
  • If the server stops, read the receipt to see which amendments it lacks, upgrade, and restart.

See Amendment Blocked Servers for background.