The xOne ops toolbox is the set of host tools in ops/tools/ of the xOneRS repository. Most tools only read or print a plan. A few write files, and one swaps a datadir. This post says which is which.

Each example below is the usage line from the tool's own header, with placeholders for hosts and paths. The repository docs do not show these commands yet. Read a tool's header before you run it.

What does xone-preflight.py check?

It checks a host before an install: OS, pending reboot, container runtime, clock, the mount of a path, and free disk and memory. The tool is read-only. It never installs, restarts or mounts anything.

  • Supported OS: Ubuntu 22.04 or 24.04, Debian 12.
  • Exit 1 means a check failed. A value it cannot read is "unknown", never "ok".
  • Disk and memory needs print as "unknown": no measured ranges exist yet (#717).
ops/tools/xone-preflight.py all <datadir> --json

What does xone-ports.py plan?

It plans ports for several instances on one host. plan writes a state file, firewall prints rules, and exposure reports listeners. The tool writes only the state file you name with --state.

  • A rerun of plan keeps the ports it already gave.
  • firewall applies nothing. It opens only the P2P port, on TCP and UDP.
  • exposure reads ss on this host. It exits 1 when it flags a port or API.
ops/tools/xone-ports.py plan --state <plan.json> <name>

What does xone-instance.py record?

It keeps a registry of named instances, a lock for each instance, and a history of actions. The tool writes under $XONE_HOME (default /etc/xone/managed).

  • rm removes the registry entry only. It never touches the datadir.
  • run starts your command under the instance lock and records the outcome. It does not record the command arguments.
ops/tools/xone-instance.py add <name> --network apothem --datadir <datadir>

What does xone-diag.py tell me?

It tells you why a systemd unit stopped, and it builds a redacted support bundle. The tool reads systemctl show and the last 300 journal lines. It deletes and restarts nothing.

  • incident prints a cause (for example start-limit, oom-kill, disk-admission or config-refusal) and a next step.
  • bundle writes a local archive of 2,000,000 bytes or less by default, with secrets redacted.
ops/tools/xone-diag.py incident <unit>

What does xone-datadir.py do to a datadir?

It works on a stopped follower datadir. It never touches custody files such as nodekey, keystore/ and safety/. The tool refuses a datadir that has a safety record.

  • resync-plan is a plan. With --yes it renames chain data into .quarantine-<time>.
  • backup writes an archive of chain data, a manifest with digests and a .sha256 file.
  • rehearse restores into a new empty directory and checks each digest.
ops/tools/xone-datadir.py backup <datadir> <backup.tar.gz>

What does xone-ssh.py do?

It opens a tunnel to a node's private RPC and hardens the login settings of a host. The tool needs the host key in known_hosts. A changed key stops the tunnel.

  • tunnel starts one child process and stops only that process.
  • harden prints by default. With --yes it writes two files: a login drop-in and a fail2ban jail.
  • harden refuses when your user has no authorized key. harden --undo --yes removes both files.
ops/tools/xone-ssh.py tunnel <user>@<host> --dry-run

What does xone-storage.py print?

It prints storage commands for you to review. The tool formats and shrinks nothing.

  • chown-plan prints one non-recursive chown. It refuses broad system paths and a directory that holds node data. With --yes it runs that one chown.
  • lvm-plan is read-only. It prints the grow commands for an LVM volume and stops when the storage is not LVM or is ambiguous.
ops/tools/xone-storage.py lvm-plan <mount> --grow-by <GiB>

What does xone-probe.py measure?

It measures a disk or one network endpoint, only when you ask. The tool gives measurements and no verdict, because no qualification data is published yet.

  • storage creates one new scratch file in the directory and removes it at exit. Caps: 1024 MiB and 120 s.
  • network makes one GET to a URL you name.
ops/tools/xone-probe.py storage <dir> --mb 64 --seconds 10

For disk sizing, see hardware and disk.

What does xone-validator-readiness.py report?

It reports whether a node could become a validator. The tool is read-only. It never signs, mines or sends a transaction.

  • It reads chain id, sync state and head over RPC. It checks that a keystore file and a password file exist, and does not read them.
  • The verdict is follower unless every check passes. Then it says only candidate. Enabling the signer is a separate owner decision.
  • Chain id 50 (mainnet) is unsupported for signing in this build. Supported: 51 (Apothem) and 2040 (net2040).
ops/tools/xone-validator-readiness.py --rpc http://127.0.0.1:8545 --datadir <datadir> --address <0x-address>

What does xone-rollback-restore.sh change?

It changes the datadir. It is step B3 of the rollback runbook, as one checked command. The script runs with the node stopped. Read how to upgrade or roll back an xOne node first.

  • It moves the current datadir to <datadir>.failed and keeps it.
  • It stages the backup in <datadir>.restore. On a signer host it then copies the current safety record over the backup's one, so the record is never lowered.
  • Any failure stops it before the swap. It never starts a service.

The command is the one in ops/upgrade-rollback.md:

ops/tools/xone-rollback-restore.sh <datadir> <backup-dir>

Which other tools are in ops/tools?

xone-adopt.py (record a manual install), xone-dashboard.py (local read-only page), xone-env-migrate.py (env file migration; report only by default), xone-health-hook.py (opt-in health webhook), xone-monitoring.py (monitoring on or off; plan by default), xone-release-check.py (running node against installed release), xone-remote.py (read-only host inventory) and xone-uninstall.py (uninstall plan that keeps data, keys and safety records).

For monitoring, see xOne node monitoring and node operations.

Frequently asked questions

Which xOne ops tools only read?

xone-preflight.py, xone-validator-readiness.py and xone-diag.py are read-only. xone-diag.py bundle writes an archive only when you ask. xone-storage.py lvm-plan and xone-ports.py firewall only print.

Which xOne ops tools write files?

xone-ports.py plan writes its state file. xone-instance.py writes under $XONE_HOME. xone-datadir.py backup writes an archive. xone-ssh.py harden --yes writes two files. xone-probe.py storage writes one scratch file and removes it.

Can an xOne ops tool touch my signer keys or safety record?

xone-datadir.py never moves or archives custody files and refuses a datadir that has a safety record. xone-rollback-restore.sh keeps the current safety record and never lowers it.

Does any tool start my node?

No tool in this post starts a service. xone-datadir.py and xone-rollback-restore.sh tell you to start the node yourself.

Sources