Configure Replication
This guide pairs two Cockpit sites and enrolls a VM for replication with a recovery policy.
Prerequisites
- Administrator (or replication-capable) access to both the primary and recovery Cockpit sites.
- A storage datastore at the recovery site with free space of at least the VM's provisioned disk size.
- For consistent recovery points and guest re-addressing: the QEMU Guest Agent installed and running in the guest.
Step 1 — Pair the sites
You only do this once per site pair.
- On the recovery Cockpit site, copy an API access token for the pairing (an admin token or a service-account API key).
- On the primary Cockpit site, select the datacenter/cluster node, open the Configure tab, and choose Site Pairs.
- Click Add Site Pair and enter:
- Site Name — a label for the recovery site, e.g.
DR-Site-B. - API Endpoint URL — the recovery Cockpit API, e.g.
https://<recovery-ip>:7771/api/v1. - Access Token — the token from step 1.
- TLS Certificate Path (optional) — a trusted CA/self-signed cert for the recovery endpoint.
- Site Name — a label for the recovery site, e.g.
- Click Link Site. The pair should show connected.
Tokens can expire
If the paired token expires or credentials change, the pair shows an error. Remove and re-add the pair with a fresh token.
Step 2 — Enroll a VM
- Select the VM in the inventory and open its Replication tab.
- In Configure Site Replication, set the policy:
| Field | What it does |
|---|---|
| Target Site | The paired recovery site to replicate to. |
| Target Datastore | The storage pool at the recovery site where the replica disks are written. Must be a real, hypervisor-accessible pool (not a home directory). |
| RPO | How often replication runs — 15 minutes, 30 minutes, 1 hour, 4 hours, or 24 hours. Smaller = less potential data loss, more traffic. |
| Recovery-point retention (MPIT) | How many historical recovery points to keep on the recovery site. Retention is grandfather-father-son: you can keep a number of hourly, daily, and weekly points so you can roll back hours or days (e.g. to before ransomware/corruption). |
| Compression | Compress the disk stream over the WAN. Saves bandwidth at a small CPU cost. |
(Optional) Expand the advanced options:
- Quiesce guest filesystem — freezes the guest filesystem via the QEMU Guest Agent during each sync for application-consistent recovery points. Requires the agent; without it, recovery points are crash-consistent (still bootable).
- Replicate specific disks — by default all disks replicate; you can select a subset (e.g. skip a scratch disk).
- Network mapping — map each source virtual network to the equivalent network at the recovery site, so the recovered VM attaches to the right network there.
- Guest IP re-addressing — set the address the guest should use after failover (per source network): address (CIDR, e.g.
10.20.0.5/24), optional gateway and nameservers. On failover Cockpit applies these inside the guest via the agent, so the recovered VM comes up on the recovery site's addressing. Requires the QEMU Guest Agent.
Click Enable Replication.
Cockpit registers the job and starts the baseline sync in the background. The first sync copies the whole disk and can take a while; subsequent syncs transfer only changed blocks on your RPO schedule.
What to expect
- The Replication Status panel shows the target, RPO, health, and Last Successful Sync time.
- Until the baseline completes, the VM is not yet recoverable. After it completes, recovery points accumulate per your RPO and retention.
- See Operate & monitor for health and manual syncs, and Failover & failback for recovery.