Installation

From a bare 2-node XCP-ng pool to replicated shared storage: seven steps, wizard included. There are no DRBD commands to learn and no config files to hand edit. One command installs, one command sets up, one command tears it all down.

Before you install

warning

1. Lab pool only. The Tech Preview is a pre-release test build, distributed for a community torture test. Do not run it on production.
2. Keep your backups. Two replicas protect against hardware failure, not against fat fingers, ransomware or "oops I deleted the wrong VM". Backups are mandatory defense in depth, with TwinStor or without it.
3. Safe by default. Auto-healing only fires when TwinStor is certain it cannot corrupt data. When in doubt, it prefers a clean outage over a risky recovery: a full-pool stop with intact data beats a split-brain every single time.
4. Honest about cheap disks. TwinStor uses direct, synchronous writes and disables volatile write caches on drives that report one; enterprise drives with power-loss protection are left at full performance. But no software can make a lying drive durable: if your disks are bargain-bin, know that risk.

Prerequisites

• 2 XCP-ng hosts in a pool. Multipath is enabled for you by twinstor setup; you do not need to turn it on yourself.
• A free local disk, partition, or md-RAID array on each host. The system disk and in-use devices are never offered by the wizard, but point it at the right device. (As a last resort on single-disk machines, the wizard can carve a partition from the system disk's unallocated free space, behind a stricter confirmation.) A ZFS zvol also works as a community-supported option: point setup at the stable /dev/zvol/<pool>/<dataset> path, and keep the dataset's sync property at standard (with sync=disabled, an acknowledged write is a lie and a power cut loses committed data).
• A decent inter-host network. 1 Gbps works; 10 Gbps is recommended for write-heavy workloads (synchronous replication rides this link). Bonded NICs and/or stacked switches are recommended for reliability.
• Fully update both hosts (yum update + reboot) before installing. A mixed-patch-level pool blocks HA configuration changes.
• In the BIOS of both hosts, set "Restore on AC Power Loss" to Power On so the pool comes back by itself after an outage. TwinStor recovers from a global power cut automatically, but only if the machines actually power back on.
• No permanently broken SRs in the pool. XCP-ng keeps a host disabled if any of its storage fails to plug at boot, and a disabled host blocks HA VM restarts. Forget or repair dead SRs first.
• The runtime dependencies (DRBD 9 kernel module, drbd-utils, targetcli and friends) are bundled in the Tech Preview tarball and installed for you. No RPM chasing.

Pick your topology

The setup wizard asks you this. Two choices; both keep your data safe.

Fate-shared (default)

One switch, one L2 segment, gateway on it. The safety property holds by construction: you cannot lose the peer without also losing the gateway. This fits the small-office and edge box with a single switch. Its one trade-off: the switch is a single point of failure. If it dies, both hosts self-fence into a clean full-pool outage, with no corruption.

Fate-shared · one switch carries everythingclients + replicationtiebreaker

One wire carries everything: the clients, the replication, and the gateway used as tiebreaker. That is the point: a host cannot lose its peer without losing everything else too, so it always knows to step aside.

Arbitrated (redundant network)

For multi-switch setups, add a back-to-back direct link (a DAC or crossover cable) between the two hosts. On a redundant network the direct link is required for safety, not a luxury: it is exactly the topology where the peer and the gateway can fail independently. Replication runs over both paths in active-backup mode with the direct link as the default active path, so a cable or NIC failure fails over to the switched network without interruption (and alerts loudly). The wizard can configure the direct-link IP for you.

Arbitrated · replication rides a dedicated cablereplicationclientstiebreaker

Each host is wired to both switches, so losing one switch takes out neither host. The direct cable carries the replication; the switched network carries the clients and stands by as the automatic replication fallback if the cable fails.

Choose the mode at install time: the second replication path cannot be added to a running cluster without a maintenance window.

Extra fence ping targets

The decision to keep serving during a partition is based on reaching the default gateway. You can add extra ping targets (a switch management IP, a second router) in /etc/twinstor/ping-targets, one IP per line: if any target answers, the node survives. Never put the direct-link IP in that file; an isolated node can still reach its peer over the cable while being invisible to every client.

Install the build on both hosts

For the Tech Preview there is no RPM yet; distribution is a tarball plus an install.sh. Get the current download link and its SHA-256 checksum from the Tech Preview announcement, then on each host (in dom0, as root):

root@twinstor-1 — install the build

# wget -O twinstor-test-<version>.tar.gz "<download URL>"
# verify before extracting (aborts if it does not match):
# echo "<published sha256>  twinstor-test-<version>.tar.gz" | sha256sum -c
# tar xzf twinstor-test-<version>.tar.gz && cd twinstor-test-<version> && ./install.sh

install.sh runs preflight checks, installs the bundled dependencies, places the twinstor binary and its systemd unit, verifies the DRBD kernel module loads, and prints the installed version. It configures nothing by itself: once it finishes, run twinstor setup.

Run the setup wizard on each node

No flags, just follow the prompts. Every answer has a sensible default:

root@twinstor-1 — twinstor setup

# twinstor setup

The wizard auto-detects the pool peer, asks which topology mode to use, lists the candidate disks with model, serial and size, and requires an explicit yes before wiping anything. Run it on the first node, then on the second: the second node inherits the cluster-wide choices the first node published, creates the shared SR, plugs it on both hosts, and enables HA (XHA).

On an already-installed node, twinstor setup instead shows the current settings and live status, with quit, uninstall, and reconfigure options.

For scripted deployments a non-interactive mode exists: twinstor setup --peer-ip <IP> --backing-device /dev/disk/by-id/<disk> on the first node prints the exact command to run on the peer. See twinstor --help for all flags.

If setup fails partway (a typo, a network hiccup), there is no automatic rollback, but setup is re-runnable: run it again with the same answers and it converges on the existing state, or run twinstor uninstall to clear the partial state and start clean. Before placing any workload, verify twinstor status reports ready on both nodes.

Firewall

Setup persistently adds two firewall rules on each host (marked with # TWINSTOR comments): 7789/tcp for replication and 3260/tcp for iSCSI.

Verify the cluster

A healthy twinstor status shows both nodes Primary / UpToDate / Connected:

root@twinstor-1 — twinstor status

# twinstor status

health:  ● healthy  — serving, peer redundant

✓ drbd
     role:       Primary
     disk:       UpToDate
     connection: Connected
     peer role:  Primary
     peer disk:  UpToDate

✓ readiness:   ready (local serving, peer redundant)

For the complete output and a field-by-field reading of every status line, see Administration.

That is it: you now have a shared SR. Create VMs on it, live-migrate them in every direction, and they will restart automatically on the survivor if a host dies.

Uninstall

twinstor uninstall removes TwinStor from a node and reverses everything in the correct order. By default it refuses to proceed while VMs still use the SR.

root@twinstor-1 — twinstor uninstall

# twinstor uninstall               # interactive confirmation
# twinstor uninstall --keep-data   # keep the backing device (do not wipe data)
# twinstor uninstall --force       # proceed even when the VM-safety check cannot confirm the SR is unused

Two things uninstall deliberately leaves in place: XCP-ng network objects (a back-to-back replication network and its dedicated-NIC IPs stay configured; remove them with xe pif-reconfigure-ip mode=None and xe network-destroy if you no longer want them), and any software-RAID array you built for the backing device (tear it down with mdadm --stop and --zero-superblock yourself).