Falling Over to a ZFS Replica: The Manual Proxmox Failover That Actually Works

Falling over to a ZFS replica in Proxmox means promoting the latest snapshot on the backup node and pointing the VM at it. The GUI won’t do it for you. Here’s the exact sequence, tested on a two-node homelab with ZFS replication jobs.

When You Actually Need This

Replication keeps a recent copy of your VM on another node. But if the primary node dies, the replica is just a snapshot on the other node’s ZFS pool. You have to promote it to a full filesystem and attach it to a new VM config. If you only have one node left, you’re doing this by hand.

Promote the Replica

First, find the snapshot name. It’s usually vm-101-disk-0@rep_<something>. List snapshots on the backup node:

zfs list -t snapshot | grep vm-101

Promote the latest one to a full filesystem. This makes it writable and independent:

zfs rollback -R rpool/data/vm-101-disk-0@rep_latest
zfs promote rpool/data/vm-101-disk-0

Wait, that’s wrong. Rollback goes back to an earlier state; promote makes the clone the parent. For a replica, you actually want to clone the snapshot, not promote it. Here’s the correct way:

zfs clone rpool/data/vm-101-disk-0@rep_latest rpool/data/vm-101-disk-0-new

Now you have a writable dataset rpool/data/vm-101-disk-0-new that contains the replicated data.

Attach the Disk to a VM

Create a new VM config or reuse the old one. If the old node is gone, the VM config lives in /etc/pve/qemu-server/101.conf on the surviving node only if you had HA or manually copied it. Otherwise, recreate it. Then attach the cloned disk:

qm set 101 -scsi0 rpool/data/vm-101-disk-0-new,size=32G

Adjust the size to match the original. Boot the VM and check that it comes up. If it doesn’t, you might need to fix the boot order or the disk interface. This is where most forum advice stops, and it’s not enough.

Why the Simple Steps Fail

The clone method works but leaves the original snapshot in place. If you then try to replicate back to the primary node after it’s fixed, you’ll get conflicts because the clone is not a replication target. You need to promote the clone to a full filesystem and then set up replication again. Also, the VM config might reference the old disk by a different path. Check /etc/pve/qemu-server/101.conf and update the disk line if needed.

Another gotcha: if you used zfs promote directly on the snapshot’s filesystem, you’d break the replication chain. The snapshot is read-only; promoting it makes it writable, but then it’s no longer a replica. That’s why cloning is safer.

My Take

This is a pain in the butt because Proxmox doesn’t have a “failover” button for replication. You’re left with ZFS commands and manual VM config edits. For a homelab, I’d keep it simple: test this procedure once before you need it. Write down the exact commands for your VM IDs and pool names. And if you have a second node, set up HA so the VM auto-starts on the replica. That’s a separate topic, but it saves you from typing all this during an outage.

If you’re using ZFS replication with TrueNAS as the target, the process is similar but you’ll need to import the pool on the Proxmox side first. See Proxmox iSCSI Multipath: Setup with TrueNAS and Failover Test for a related scenario.