Skip to content

Install xahaud

When running a node, users will have to configure settings based on whether the node will run on the test network or the main network. When transitioning a single node from one network to the other, database files must be wiped, except wallet.db, which contains the server’s identity credentials.

The most common techniques for installing xahaud are either locally using systemd or inside a container, such as Docker.

Linux Install Process

Section titled “Linux Install Process”

Regardless of how xahaud is installed (Docker or system-wide), the overall process is similar across Linux systems. The following sections, Docker Container and Local Install, take advantage of bash scripts, which automate the following steps:

  1. Obtain the xahaud binary:
  2. Obtain the configuration files:
  3. If desired, create a xahaud user and group, which can own the binary and other relevant files:
    • sudo groupadd --system xahaud
    • sudo useradd --system --gid xahaud --no-create-home xahaud
  4. Decide on (and create) a directory structure to store:
    • The xahaud binary. The default is typically: /opt/xahaud/bin/xahaud
    • Two xahaud configuration files, xahaud.cfg and validators-xahau.txt. The default is: /etc/xahaud/, though /opt/xahaud/etc/ is often used. These two locations can be symbolically linked.
    • The xahaud databases. The default is often: /opt/xahaud/db/
    • A logfile location, such as: /var/log/xahaud/default.log
  5. Move the xahaud binary and configuration files into their places in the directory structure.
  6. Edit xahaud.cfg so paths in the configuration match the paths in the directory structure.
  7. If needed, change ownership permissions. If running xahaud as a validator, it is important to restrict the xahaud.cfg file, as that contains the validation token.
    • chown -R xahaud:xahaud /opt/xahaud /var/log/xahaud
    • chmod -R 750 /opt/xahaud /var/log/xahaud
  8. Create a systemd service file (such as the example below to run xahaud as a daemon.
    • The file is located at: /etc/systemd/system/xahaud.service
    • After creating or editing the file, run: systemctl daemon-reload
    • To run xahaud automatically at system startup: systemctl enable --now xahaud
    • If preferred, xahaud can be run without systemd: /path/to/xahaud --conf=/path/to/xahaud.cfg
  9. Create a wrapper to run xahaud commands without having to specify the full path.
    • Typically stored at /usr/local/bin/xahaud
    • Contents might be: exec ${XAHAUD_DIR}xahaud --conf=${CONF_DIR}xahaud.cfg "$@"

Example systemd Service File

Section titled “Example systemd Service File”

The following service file should be modified based on the user’s selected directory structure and ownership permissions.

[Unit]
Description=Xahaud Daemon
After=network-online.target
Wants=network-online.target


[Service]
Type=simple
ExecStart=/path/to/xahaud --silent --conf=/path/to/xahaud.cfg
Restart=on-failure
User=xahaud
Group=xahaud
LimitNOFILE=65536


[Install]
WantedBy=multi-user.target

Example Linux Install Script

Section titled “Example Linux Install Script”

A basic bash script used to install xahaud. This script follows the instructions provided earlier this this section.

### VARIABLES ###


#### Directory structure ####
XAHAUD_DIR="/opt/xahaud/bin/"  # Path where xahaud binary will be stored
CONF_DIR="/opt/xahaud/etc/"    # Path where the xahaud.cfg and validators-xahau.txt will be stored
DB_DIR="/opt/xahaud/db/"    # Path where xahaud will store databases
LOG_DIR="/var/log/xahaud/"    # Path where logfile(s) will be stored.


#### Ownership ####
XAHAUD_USER="xahaud"      # User that owns the xahaud process.


#### Download links ####
BINARY_URL="https://build.xahau.tech/2025.9.8-HEAD%2B2194"                      # URL to the xahaud binary that will be downloaded.
CFG_URL="https://raw.githubusercontent.com/Xahau/xahaud/refs/heads/dev/cfg/xahaud-example.cfg"    # This will be renamed to 'xahaud.cfg'
VAL_URL="https://raw.githubusercontent.com/Xahau/xahaud/refs/heads/dev/cfg/validators-example.txt"  # This will be renamed to 'validators-xahau.txt'






########## SCRIPT BEGINS HERE. DO NOT ADJUST VARIABLES BELOW THIS LINE ##########


### CREATE DIRECTORIES ####
echo "Checking directory structure."
sudo mkdir -p ${XAHAUD_DIR} ${CONF_DIR} ${DB_DIR} ${LOG_DIR}


### CREATE xahaud GROUP AND USER ###
echo "Checking for user and group."
if ! getent group ${XAHAUD_USER} > /dev/null; then
  sudo groupadd --system ${XAHAUD_USER}
fi


if ! getent passwd ${XAHAUD_USER} > /dev/null; then
  sudo useradd --system --gid ${XAHAUD_USER} --no-create-home ${XAHAUD_USER}
fi


### DOWNLOAD CONFIGURATION FILES ###
echo "Downloading files."
if [[ ! -f "${CONF_DIR}xahaud.cfg" ]]; then
  curl -fsSL ${CFG_URL} -o ${CONF_DIR}xahaud.cfg
fi
if [[ ! -f "${CONF_DIR}validators-xahau.txt" ]]; then
  curl -fsSL ${VAL_URL} -o ${CONF_DIR}validators-xahau.txt
fi


### DOWNLOAD xahaud ###
if [[ ! -f "${XAHAUD_DIR}xahaud" ]]; then
  curl -fsSL ${BINARY_URL} -o ${XAHAUD_DIR}xahaud
elif [[ -f "${XAHAUD_DIR}xahaud" ]]; then
  echo "Existing xahaud binary found. It will be renamed to 'xahaud.old'."
  mv ${XAHAUD_DIR}xahaud ${XAHAUD_DIR}xahaud.old
  curl -fsSL ${BINARY_URL} -o ${XAHAUD_DIR}xahaud
fi


### CHANGE OWNERSHIP AND PERMISSIONS ###
echo "Checking ownership and permissions."
sudo chown -R ${XAHAUD_USER}:${XAHAUD_USER} ${XAHAUD_DIR} ${CONF_DIR} ${DB_DIR} ${LOG_DIR}
sudo chmod -R 0750 ${XAHAUD_DIR} ${CONF_DIR} ${DB_DIR} ${LOG_DIR}


### Install systemd SERVICE FILE ###
if [[ ! -f "/etc/systemd/system/xahaud.service" ]]; then
echo "Installing system service file."
sudo cat > /etc/systemd/system/xahaud.service <<EOF
[Unit]
Description=Xahaud Daemon
After=network-online.target
Wants=network-online.target


[Service]
Type=simple
ExecStart=${XAHAUD_DIR}xahaud --silent --conf=${CONF_DIR}xahaud.cfg
Restart=on-failure
User=${XAHAUD_USER}
Group=${XAHAUD_USER}
LimitNOFILE=65536


[Install]
WantedBy=multi-user.target
EOF
fi


### RUN COMMANDS AS 'xahaud' WITHOUT SPECIFYING FULL PATHS ###
if [[ ! -f "/usr/local/bin/xahaud" ]]; then
echo "Creating xahaud wrapper."
sudo cat > /usr/local/bin/xahaud <<EOF
#!/usr/bin/env bash
set -euo pipefail


exec ${XAHAUD_DIR}xahaud --conf=${CONF_DIR}xahaud.cfg "\$@"
EOF
fi


sudo chmod 0755 /usr/local/bin/xahaud


### ENABLE AND START xahaud ###
sudo systemctl daemon-reload
sudo systemctl stop xahaud
sudo systemctl enable --now xahaud
sudo systemctl status xahaud
echo "The install script completed successfully."

Docker Container Install Script

Section titled “Docker Container Install Script”

To run xahaud in a Docker Container:

  1. Clone the appropriate (Mainnet or Testnet) Xahau Docker GitHub repository using the URL in the table below: git clone [repository-url]
  2. Navigate to the repository directory: cd [repository-name]
  3. Run: ./build
  4. Run: ./up
  5. Commands and additional information are located in the README.md file in the Docker repository. Configuration files and databases are located in the store directory inside the Docker directory.

Local Install Script

Section titled “Local Install Script”

The Xahau Docker repositories (Mainnet and Testnet) each contains a script to automate the local install process, so that xahaud can be run outside of Docker. These scripts are similar to the Linux Install Summary, as they will create systemd files, a ‘xahaud’ user, and default configuration files. The URLs for these scripts are in the table at the bottom of this page. To install locally:

  1. Download and run the install script: curl -sL [https://link-to-script] | bash
  2. Edit the configuration file: /opt/xahahud/etc/xahaud.cfg
  3. Verify and, if needed, edit the contents of the trusted validators file: /opt/xahaud/etc/validators-xahau.txt
  4. Start and enable xahaud to run automatically: systemctl enable —now xahaud
  5. Verify xahaud is running: /opt/xahaud/bin/xahaud server_info

Resources, Peering, and Configurations

Section titled “Resources, Peering, and Configurations”

This peering is relevant for both Docker containers and local installations.

ResourceMain NetworkTest Network
Documentation and Resourceshttps://xahau.network/Same as Mainnet
Hooks Smart Contract Documentationhttps://xahau.network/docs/hooks/Same as Mainnet
Explorerhttps://explorer.xahau.network/https://explorer.xahau-test.net
Public WebSocket URLwss://xahau.networkwss://xahau-test.net
Network ID and Peer Listening Port21337 IANA assigned port21338
Peering and Bootstrap Serversbacab.alloy.ee 21337
hubs.xahau.as16089.net 21337		79.110.60.122 21338
79.110.60.124 21338
79.110.60.125 21338
79.110.60.121 21338

2a0c:3bc0::1c74 21338
2a0c:3bc0::169d 21338
2a0c:3bc0::1aaf 21338
2a0c:3bc0::1d78 21338
Docker Containerhttps://github.com/Xahau/mainnet-dockerhttps://github.com/Xahau/Xahau-Testnet-Docker
Local Install Scriptshttps://raw.githubusercontent.com/Xahau/mainnet-docker/refs/heads/main/xahaud-install-update.shhttps://github.com/Xahau/Xahau-Testnet-Docker/blob/main/xahaud-install-update.sh
Binary Releaseshttps://build.xahau.techSame as Mainnet
Sample Configuration Filehttps://github.com/Xahau/xahaud/blob/dev/cfg/xahaud-example.cfghttps://github.com/Xahau/Xahau-Testnet-Docker/blob/main/store/etc/xahaud.cfg
Sample Trusted Validators (UNL) Filehttps://github.com/Xahau/xahaud/blob/dev/cfg/validators-example.txthttps://github.com/Xahau/Xahau-Testnet-Docker/blob/main/store/etc/validators-xahau.txt
Documented Configuration Fileshttps://github.com/Xahau/xahaud/tree/dev/cfgSame as Mainnet
Github Build Actions (release numbers)https://github.com/Xahau/xahaud/actions?query=branch%3Arelease+is%3Asuccess+build+using+dockerSame as Mainnet