XRPL Validator Linux Package Monitoring Guide

Revision: July 2026

Need monitoring credentials? If you do not have a Basic Auth username and password, request monitoring access before you start this guide.

Introduction

This guide explains how to connect an xrpld validator host to the XRPL monitoring platform with Grafana Alloy. You can use the guided installer or make the same changes yourself with the manual steps.

Still running rippled (pre-3.2.0)? rippled was renamed to xrpld in version 3.2.0. The installer detects legacy rippled nodes automatically: it also checks /etc/opt/ripple/rippled.cfg, /opt/ripple/etc/rippled.cfg, and /etc/rippled/rippled.cfg, the rippled systemd unit, and running rippled processes. Where this guide says xrpld.cfg or /var/log/xrpld/, use your existing rippled paths instead.

Opting in gives the validator operator access to validator health in Grafana. Metrics and logs make it easier to catch problems early, confirm that telemetry is flowing, and troubleshoot incidents without manually collecting log files after the fact.

The setup is designed to stay under the operator’s control. Alloy reads local telemetry and pushes it with credentials provided by the XRPL Foundation. The guided installer does not edit xrpld.cfg, does not restart xrpld, and asks before starting or enabling Alloy. The manual path shows every command and file so you decide when to make each change.

The mental model is simple:

xrpld -> Grafana Alloy -> XRPL monitoring proxy -> Grafana

Grafana Alloy runs on the validator host. It reads local xrpld telemetry and pushes it to the monitoring platform:

  • StatsD metrics are collected.
  • debug.log and perf.log are collected.
  • Grafana shows the validator dashboards.

The trusted validator identity is the Basic Auth username provided by the XRPL Foundation. The local node label is only a dashboard filter. Operators can optionally add the validator’s public master key to correlate the collector with public XRPL network statistics.

The guided installer is intentionally careful:

  • It does not edit xrpld.cfg.
  • It does not restart xrpld.
  • It verifies the monitoring credentials before writing the final Alloy config.
  • It asks before starting or enabling Alloy.

Before You Start

What You Need

The XRPL Foundation provides:

  • Monitoring push host: push.monitoring.xrplf.org.
  • Grafana URL: https://monitoring.xrplf.org.
  • Basic Auth username and password.
  • Grafana account access.

The validator host needs:

  • systemd.
  • sudo, unless you work as root.
  • A readable xrpld.cfg.
  • Optionally, the validator’s public 52-character nH master key for correlation with public XRPL network statistics.
  • StatsD metrics, debug.log, and perf.log available from xrpld.
  • Outbound HTTPS access to push.monitoring.xrplf.org and Grafana’s package repository.

The current official XRPL package guides list these 64-bit x86 hosts:

  • Ubuntu 22.04 or 24.04, which receive the highest support and testing.
  • Debian 12 Bookworm, for which packages are available.
  • RHEL 9.6, which is supported.

See the XRPL system requirements, Ubuntu and Debian install guide, and RHEL install guide for current platform guidance. The steps below cover APT on Ubuntu or Debian and DNF or YUM on RHEL-family hosts.

Choose A Setup Path

Both paths create the same Alloy setup and send the same telemetry.

  • Guided install: download the hosted installer, review it if you want, and answer each prompt. The installer explains each change before making it.
  • Manual install: run each command yourself, review the downloaded shared config, and create the small host-specific files by hand.

Use only one path. If you use the guided installer, continue with the next section. If you want to make every change yourself, skip to Manual Install.

Guided Install

Run The Installer

Use the hosted installer provided by the XRPL Foundation:

curl -fsSL https://push.monitoring.xrplf.org/alloy/install \
  | bash

To download and verify the installer before running it:

push_host="https://push.monitoring.xrplf.org"
install_sha256="749ba31360f1af17a8bcff90d869e320050ba6fab6f61c7ce03dae025d8e7b7d"
installer="install-xrpl-monitoring.sh"
curl -fsSL "$push_host/alloy/install" -o "$installer"
printf '%s  %s\n' "$install_sha256" "$installer" | sha256sum -c -

sha256sum -c - must print OK. You can open the file in a text editor before you run it. When you are ready, run the same downloaded file:

bash "$installer"

What The Installer Does

The installer:

  1. Detects the OS and checks prerequisites.
  2. Installs Grafana Alloy from the official Grafana package repository.
  3. Finds and checks xrpld.cfg.
  4. Checks StatsD, debug.log, perf.log, and Alloy’s read access to the logs.
  5. Asks for a node label.
  6. Offers to add the validator’s public master key for network correlation.
  7. Asks for the push host, username, and password.
  8. Checks the credentials.
  9. Writes and validates the Alloy config.
  10. Asks before starting Alloy and before enabling it at boot.

If an xrpld.cfg change is needed, the installer prints what to add, then waits. You edit xrpld.cfg, restart xrpld using your normal process, and press Enter to let the installer check again.

Changes The Installer May Request

StatsD must be enabled. If you are not already using StatsD, the installer asks you to add a block like this:

[insight]
server=statsd
address=127.0.0.1:9125
prefix=xrpld

If you already use StatsD, you do not need to change your existing prefix or lose your existing collector. The installer detects the current prefix and configures Alloy for it.

The only change the installer may ask for is the StatsD address, so xrpld sends packets to Alloy first. Alloy then acts as a middleman:

xrpld -> Alloy -> existing StatsD collector
              |
              +-> XRPL monitoring

The existing collector receives the original packets unchanged. The monitoring copy is handled separately by Alloy.

The debug log can use any path, as long as the file exists and Alloy can read it. Example:

[debug_logfile]
/var/log/xrpld/debug.log

The perf log must also be enabled:

[perf]
perf_log=/var/log/xrpld/perf.log
log_interval=2

Back up xrpld.cfg before changing it. The installer does not back up or edit this file because it belongs to the validator operator.

On xrpld package installs, the log directory is usually not readable by the Alloy service user. The installer detects this and asks before adding the alloy user to the log directory’s group so Alloy can read the logs. It does not change the xrpld service or log files.

Manual Install

The manual path follows the same order as the guided installer. Read each step before running its commands. The examples use sudo. If you are already root, omit it from ordinary commands. Open files with your preferred editor instead of sudoedit, and follow the root-specific note for sudo -u alloy in step 6.

1. Check The Host

Confirm the CPU architecture and operating system:

uname -m
cat /etc/os-release

For the supported production hosts listed above, uname -m prints x86_64. Also confirm that xrpld is running under systemd:

sudo systemctl status xrpld

On versions before 3.2.0, use rippled instead of xrpld in service commands.

2. Install Grafana Alloy

Grafana Alloy is installed from Grafana’s official package repository. These commands follow Grafana’s Linux installation guide. First check whether Alloy is already installed:

alloy --version

If this prints a version, skip the package commands and continue with step 3. Otherwise, use the section for your operating system.

Ubuntu Or Debian With APT

Install curl if it is not already available:

sudo apt-get update
sudo apt-get install -y curl

Download the Grafana signing key, add the repository, and install Alloy:

grafana_key="$(mktemp)"
curl -fsSL https://apt.grafana.com/gpg-full.key -o "$grafana_key"
sudo install -d -m 0755 /etc/apt/keyrings
sudo install -m 0644 "$grafana_key" /etc/apt/keyrings/grafana.asc
rm -f "$grafana_key"
grafana_repo='deb [signed-by=/etc/apt/keyrings/grafana.asc]'
grafana_repo="$grafana_repo https://apt.grafana.com stable main"
printf '%s\n' "$grafana_repo" \
  | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt-get update
sudo apt-get install -y alloy

RHEL With DNF Or YUM

Install curl if it is not already available:

sudo dnf install -y curl

Use yum in place of dnf if that is the package manager on your host. Download the Grafana signing key and add the repository:

grafana_key="$(mktemp)"
curl -fsSL https://rpm.grafana.com/gpg.key -o "$grafana_key"
sudo install -D -m 0644 "$grafana_key" \
  /etc/pki/rpm-gpg/RPM-GPG-KEY-grafana
sudo rpm --import "$grafana_key"
rm -f "$grafana_key"
sudo tee /etc/yum.repos.d/grafana.repo >/dev/null <<'EOF'
[grafana]
name=grafana
baseurl=https://rpm.grafana.com
repo_gpgcheck=1
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-grafana
sslverify=1
EOF
sudo dnf -y makecache --refresh
sudo dnf install -y alloy

Check the installed version:

alloy --version

3. Find And Back Up xrpld.cfg

The current package path is:

/etc/xrpld/xrpld.cfg

Older installations may use one of these paths:

/etc/opt/ripple/rippled.cfg
/opt/ripple/etc/rippled.cfg
/etc/rippled/rippled.cfg

If the file is elsewhere, systemctl cat xrpld or the command used to start xrpld may show a --conf path.

Back up the file before editing it. Replace the path below if your config is elsewhere:

sudo cp -a /etc/xrpld/xrpld.cfg /etc/xrpld/xrpld.cfg.bak.$(date +%s)
sudoedit /etc/xrpld/xrpld.cfg

Do not add a second copy of a section that already exists. Update the existing section instead.

4. Configure StatsD And Logs

Make sure these sections exist in xrpld.cfg:

[insight]
server=statsd
address=127.0.0.1:9125
prefix=xrpld

[debug_logfile]
/var/log/xrpld/debug.log

[perf]
perf_log=/var/log/xrpld/perf.log
log_interval=2

You may keep different log paths. You may also keep an existing non-empty StatsD prefix. Write down the exact prefix and paths because you use them again in the Alloy files.

If Another StatsD Collector Already Exists

Do not stop using it. Put Alloy in front of it so both systems receive the metrics.

For example, if xrpld currently sends to 127.0.0.1:8125:

  1. Keep 127.0.0.1:8125 as the relay address for the Alloy config.
  2. Choose a free local UDP port for Alloy, such as 127.0.0.1:9125 or 127.0.0.1:9126.
  3. Change only the [insight] address in xrpld.cfg to the new Alloy address.
  4. Keep the current StatsD prefix.

Check whether a UDP port is already in use:

sudo ss -lunp | grep ':9125 '

No output means the port is normally free. The final flow is:

xrpld -> Alloy -> existing StatsD collector
              |
              +-> XRPL monitoring

5. Apply Changes And Check The Inputs

Restart xrpld only if you changed xrpld.cfg in the previous step. Config changes do not take effect until the service restarts. Use your normal restart process. For a package install:

sudo systemctl restart xrpld

If you did not change xrpld.cfg, do not restart the service.

In either case, check that xrpld is running and that both log files exist:

sudo systemctl status xrpld
sudo ls -l /var/log/xrpld/debug.log /var/log/xrpld/perf.log

For a legacy service, use rippled in the service commands. Use your configured log paths if they are different.

6. Give Alloy Read Access To The Logs

First check whether the Alloy service user can read both files:

sudo -u alloy test -r /var/log/xrpld/debug.log && echo 'debug.log is readable'
sudo -u alloy test -r /var/log/xrpld/perf.log && echo 'perf.log is readable'

If you are working as root on a host without sudo, run the equivalent checks with runuser:

runuser -u alloy -- test -r /var/log/xrpld/debug.log && echo 'debug.log is readable'
runuser -u alloy -- test -r /var/log/xrpld/perf.log && echo 'perf.log is readable'

If both messages appear, continue to the next step. If not, check the group that owns the log directory:

sudo stat -c '%U %G %a %n' /var/log/xrpld

If the group is not root, add the alloy user to it. The group is commonly named xrpld:

sudo usermod -aG xrpld alloy

If the stat command showed another non-root group, use that group name instead.

If the directory uses the root group, never add the alloy user to that group. Instead, give the Alloy group access only to the log directory and the two configured log files:

sudo chgrp alloy /var/log/xrpld
sudo chgrp alloy /var/log/xrpld/debug.log /var/log/xrpld/perf.log
sudo chmod g+rx /var/log/xrpld
sudo chmod g+r /var/log/xrpld/debug.log /var/log/xrpld/perf.log

These commands keep each file’s owner unchanged. If root owns a file, its ownership becomes root:alloy. Use your configured directory and file paths if they are different.

Run the two read checks again and do not continue until both messages appear. Do not make validator logs readable by every user. Check access again after log rotation in case the files are created with their old group.

7. Download The Shared XRPL Config

The shared config contains the StatsD, metrics, log processing, redaction, and push settings used by all validators. It contains no validator credentials. Download it without installing it first:

module_tmp="$(mktemp)"
curl -fsSL \
  https://push.monitoring.xrplf.org/alloy/config \
  -o "$module_tmp"
printf 'Downloaded to: %s\n' "$module_tmp"

Open the downloaded file in a text editor if you want to review every setting. Then check that it contains the expected module:

grep -F 'Managed by xrpl-monitoring Alloy installer' "$module_tmp"
grep -F 'declare "xrplf"' "$module_tmp"

Both commands must print a matching line. Install the reviewed file:

sudo install -d -m 0755 /etc/alloy
sudo install -m 0644 "$module_tmp" /etc/alloy/xrplf.alloy
rm -f "$module_tmp"

8. Create The StatsD Mapping

Create the mapping file:

sudoedit /etc/alloy/statsd-mapping.yml

For the standard prefix=xrpld, paste:

defaults:
  match_type: regex

mappings:
  - match: '^xrpld[.](.+)$'
    name: 'xrpld_${1}'

  - match: '.*'
    action: drop
    name: 'dropped'

The first match must use the same prefix as [insight]. For example, prefix=rippled needs ^rippled[.](.+)$. A literal dot in a custom prefix must be written as [.], and a literal hyphen can be written as [-]. The last rule drops unrelated StatsD packets from the monitoring path.

Set the file permissions:

sudo chmod 0644 /etc/alloy/statsd-mapping.yml

9. Check The Monitoring Credentials

Check the username and password before storing them in the Alloy config. Replace <username> with the Basic Auth username from the XRPL Foundation:

curl --fail-with-body \
  --user '<username>' \
  https://push.monitoring.xrplf.org/health

curl asks for the password without displaying it. A successful check prints:

ok

An HTTP 401 means the username or password is wrong. An HTTP 403 means the credentials are valid but are not yet assigned to a monitoring tenant. Contact the XRPL Foundation if either error continues.

10. Create The Host Config

The package normally creates a default /etc/alloy/config.alloy. Review it before replacing it:

sudo less /etc/alloy/config.alloy

Press q to close less. If the file contains an Alloy setup that you already use, do not replace it. Stop here and plan how to merge the XRPL block with the person who manages that setup.

If the file is only the package default, back it up and open it for editing:

sudo cp -a /etc/alloy/config.alloy /etc/alloy/config.alloy.bak.$(date +%s)
sudoedit /etc/alloy/config.alloy

Paste the following config and replace every value inside angle brackets. Never enter a validator token, seed, or private key.

// XRPL validator monitoring config.
// This file contains monitoring push credentials.

import.file "xrpl_monitoring" {
  filename = "/etc/alloy/xrplf.alloy"
}

xrpl_monitoring.xrplf "default" {
  node                 = "<node-label>"
  validator_master_key = "<public-validator-master-key>"

  push_host = "push.monitoring.xrplf.org"

  username = "<basic-auth-username>"
  password = "<basic-auth-password>"

  log_debug = "/var/log/xrpld/debug.log"
  log_perf  = "/var/log/xrpld/perf.log"

  statsd_listen     = "127.0.0.1:9125"
  statsd_relay_addr = ""

  // Keep "^$" when no extra redaction is needed.
  host   = "^$"
  pubkey = "^$"
}

logging {
  format = "logfmt"
  level  = "info"
}

Use these values:

  • node: a short label for this host. The full hostname is a good default.
  • validator_master_key: the optional public 52-character validator master key that starts with nH. Use an empty string ("") to opt out. Never use a validator token, signing key, private key, or seed.
  • username and password: credentials from the XRPL Foundation.
  • log_debug and log_perf: exact paths from xrpld.cfg.
  • statsd_listen: exact [insight] address from xrpld.cfg.
  • statsd_relay_addr: the old collector address, or an empty string if there is no other collector.

Alloy strings use double quotes. If a value itself contains " or \, put a backslash before that character.

The config contains the monitoring password. Give the Alloy service group read access, but do not make the file public:

alloy_group="$(systemctl show alloy.service -p Group --value)"
sudo chown "root:${alloy_group:-alloy}" /etc/alloy/config.alloy
sudo chmod 0640 /etc/alloy/config.alloy

11. Validate And Start Alloy

Validate the complete config before starting Alloy:

sudo alloy validate /etc/alloy/config.alloy

Do not start Alloy if validation reports an error. Fix the named file and run the check again.

If Alloy is not running, start it:

sudo systemctl start alloy

If it was already running with the package’s default config, restart it:

sudo systemctl restart alloy

Enable Alloy so it starts after a reboot:

sudo systemctl enable alloy.service

Starting or restarting Alloy begins sending the configured metrics and logs to push.monitoring.xrplf.org.

12. Verify The Manual Install

Check the service:

sudo systemctl status alloy

Check its recent logs:

sudo journalctl -u alloy -n 100 --no-pager

The status should be active and the logs should not show repeated read, config, authentication, or push errors. After a few minutes, continue to Grafana Setup & Access and confirm that the node appears in the dashboards.

Configuration Reference

Both setup paths use the same three files: the guided installer writes them for you, while the manual path has you create them yourself.

/etc/alloy/config.alloy
/etc/alloy/xrplf.alloy
/etc/alloy/statsd-mapping.yml

Most operators do not need to edit the files after setup. It is useful to know what they contain.

/etc/alloy/config.alloy contains the monitoring credentials and is written with mode 0640.

/etc/alloy/xrplf.alloy contains the shared XRPL telemetry module and is written with mode 0644.

/etc/alloy/statsd-mapping.yml contains no secrets and is written with mode 0644.

The guided installer backs up an existing file before replacing it:

<path>.bak.<unix-seconds>

The manual path shows the backup command before you replace the package config.

Values You Should Recognize

The host config includes:

  • node: dashboard label for this host.
  • validator_master_key: optional public 52-character nH validator master key for network correlation.
  • push_host: monitoring host without https:// and without a path.
  • username and password: Basic Auth credentials from the XRPL Foundation.
  • log_debug: path to debug.log.
  • log_perf: path to perf.log.
  • statsd_listen: local UDP address Alloy listens on.
  • statsd_relay_addr: optional existing StatsD collector to relay to.
  • host and pubkey: optional redaction regexes, disabled by default.

All generated connections to the push host use HTTPS.

Optional Validator Correlation

Set validator_master_key to the validator’s public 52-character master key that starts with nH to correlate the collector with public XRPL network statistics. This is not an account address, signing key, private key, seed, or validator token. Leave the value exactly empty to opt out:

validator_master_key = ""

The public master key is attached only to the Prometheus up metric. It is not attached to other metrics or any Loki log stream, and it does not replace the Basic Auth tenant as the trusted identity. After changing the value, validate the config and restart Alloy.

Optional Redaction

Host or public-key redaction is optional. The guided installer does not ask for it, and the manual config leaves it disabled.

By default, the generated config contains:

host   = "^$"
pubkey = "^$"

^$ is the disabled value. Keep it when no extra redaction is needed.

Alloy always redacts IPv4 and IPv6 addresses from debug.log. To also redact a host, domain, or public key, edit /etc/alloy/config.alloy after install and replace one or both values with a regex that matches only the value you want to hide.

  • host redacts matching host or domain values from debug.log and perf.log.
  • pubkey redacts matching public-key values from debug.log.

Example:

host   = "validator[.]example[.]com"
pubkey = "n9KExamplePublicKey"

Then restart Alloy:

sudo systemctl restart alloy

Do not use broad patterns such as .*, because every match is replaced in the logs. Since /etc/alloy/config.alloy contains monitoring credentials, keep its private file permissions.

StatsD

xrpld sends StatsD packets to Alloy. Alloy converts them into metrics for the Grafana dashboards.

The mapping file keeps only the configured StatsD prefix and drops unrelated StatsD packets from the monitoring path.

If another StatsD collector already exists, Alloy sits in front of it:

xrpld -> Alloy -> existing StatsD collector
              |
              +-> XRPL monitoring

In that setup, the guided installer configures statsd_relay_addr automatically. In the manual path, you enter the old collector address yourself. The existing collector receives the original packets unchanged.

Logs

Alloy tails:

  • debug.log
  • perf.log

It parses timestamps, adds dashboard labels, applies the built-in and optional redaction described above, and sends the logs to the monitoring platform.

Useful service commands:

sudo systemctl status alloy
sudo journalctl -u alloy -n 100 --no-pager
sudo systemctl restart alloy
sudo systemctl stop alloy

Grafana Setup & Access

The XRPL Foundation provides Grafana account access. Open:

https://monitoring.xrplf.org

After Alloy starts, wait a few minutes, then open:

  • XRPL Validator Health
  • XRPL StatsD Metrics
  • XRPL Logs & Triage

Use the dashboard filters:

  • validator: the monitoring tenant.
  • node: the node label entered during install.
  • For logs: file, level, and module.

If data does not appear:

  • Check Alloy:

    sudo systemctl status alloy

  • Check Alloy logs:

    sudo journalctl -u alloy -n 100 --no-pager

  • Confirm xrpld is sending StatsD to the same address Alloy listens on.

  • Confirm debug.log and perf.log paths exist and are readable.

  • Confirm the push host and credentials with the XRPL Foundation.

Uninstall

Guided Uninstall

If you used the guided installer, run:

curl -fsSL \
  https://push.monitoring.xrplf.org/alloy/install \
  | bash -s -- --uninstall

The uninstall flow asks before it:

  • Stops Alloy.
  • Disables Alloy at boot.
  • Removes managed /etc/alloy files.
  • Removes the Grafana package repository and signing key.
  • Removes the alloy package.

/etc/alloy/config.alloy holds the monitoring credentials, so it is removed without keeping a backup, and any leftover config.alloy backup copies are offered for removal too.

It does not touch xrpld.cfg. If the install put Alloy in front of an existing StatsD collector, the uninstall prints the original collector address so you can restore the [insight] address yourself and restart xrpld using your normal process.

Manual Uninstall

First stop Alloy and disable it at boot:

sudo systemctl stop alloy
sudo systemctl disable alloy

If you put Alloy in front of an older StatsD collector, restore the old [insight] address in xrpld.cfg now and restart xrpld using your normal process.

Remove the three config files. Check any backup before removing it because config.alloy backups may also contain the monitoring password:

sudo rm -i /etc/alloy/config.alloy
sudo rm -i /etc/alloy/xrplf.alloy
sudo rm -i /etc/alloy/statsd-mapping.yml
sudo find /etc/alloy -maxdepth 1 \
  \( -name 'config.alloy.bak.*' -o -name 'config.alloy.rpmsave' \) \
  -exec rm -i {} \;

Remove the package with the command for your operating system:

sudo apt-get remove alloy

Or:

sudo dnf remove alloy

The Grafana repository can stay in place for package updates or other Grafana software. If you want to remove it too, follow the optional repository-removal step in Grafana’s Linux uninstall guide.

Disable Without Removing Alloy

To stop monitoring but keep the package and config:

sudo systemctl stop alloy
sudo systemctl disable alloy

If you changed xrpld.cfg to send StatsD to Alloy and want to go back to a previous collector, restore the previous [insight] address yourself and restart xrpld using your normal process.

Back to top