vmsync: incrementally replicate libvirt based virtual machines to remote hosts using dirty bitmaps.

This utility can be used to sync or "replicate" virtual machines to other libvirt hosts. On the first execution, a complete (full) replication will be executed and an dirty bitmap is created. For any following command calls, it will only synchronize incremental changes since the last checkpoint.

See release directory

Workflow

• Identify the virtual disks (qcow2 images only)
• Create a checkpoint and pull based libvirt backup job, expose checkpoint via NBD
• Connect to the source NBD port and query block regions
• Connect to the remote system via SSH and create qcow files on target system
• Start an NBD target service backing the qcow2 files on the target system
• Synchronize block regions
• Stop backup job
• Stop target NDB Service
• Define VM on target system with latest configuration

./vmsync -source-domain SOURCE_DOMAIN \
        -source-uri qemu+ssh://hostA/system \
        -target-domain TARGET_DOMAIN \          # optional, otherwise use original VM name
        -target-uri qemu+ssh://hostB/system \
        -ssh-user root  \                       # user for all ssh related operations

./vmsync -source-domain fstrim -source-uri qemu+ssh://root@localhost/system --ssh-user root --target-uri qemu+ssh://192.168.161.196/system
[..]
2026/04/16 08:27:14 INFO discovered source domain domain=fstrim
2026/04/16 08:27:14 INFO discovered qcow2 disks count=2
2026/04/16 08:27:14 INFO source URI uses SSH; qemu-img info will run remotely user=root host=localhost port=22
2026/04/16 08:27:14 INFO running remote qemu-img info disk=sda path=/tmp/tmp.NU7Aaf6bVg/fstrim.qcow2
2026/04/16 08:27:15 INFO disk info disk=sda format=qcow2 virtual_size=42949672960 path=/tmp/tmp.NU7Aaf6bVg/fstrim.qcow2
2026/04/16 08:27:15 INFO running remote qemu-img info disk=sdb path=/tmp/tmp.NU7Aaf6bVg/fstrim-2.qcow2
2026/04/16 08:27:15 INFO disk info disk=sdb format=qcow2 virtual_size=42949672960 path=/tmp/tmp.NU7Aaf6bVg/fstrim-2.qcow2
2026/04/16 08:27:15 INFO Successfully freezed file systems using guest agent
2026/04/16 08:27:15 INFO created initial checkpoint=vmsync-cpt-000001
2026/04/16 08:27:15 INFO Successfully thawed file systems using guest agent
2026/04/16 08:27:15 INFO starting full pull backup (no incremental bitmap)
2026/04/16 08:27:15 INFO libvirt backup export started on source via tcp host=localhost port=10809
2026/04/16 08:27:15 INFO waiting for all processes to finish
2026/04/16 08:27:15 INFO reading disk via libvirt backup NBD tcp export disk=sdb export=sdb
2026/04/16 08:27:15 INFO nbd connect for extents host=localhost port=10809 export=sdb checkpoint=vmsync-cpt-000001 incremental=false
2026/04/16 08:27:15 INFO reading disk via libvirt backup NBD tcp export disk=sda export=sda
2026/04/16 08:27:15 INFO nbd connect for extents host=localhost port=10809 export=sda checkpoint=vmsync-cpt-000001 incremental=false
2026/04/16 08:27:15 INFO nbd connected for extent query export=sdb
2026/04/16 08:27:15 INFO nbd export size export=sdb bytes=42949672960
2026/04/16 08:27:15 INFO nbd connected for extent query export=sda
2026/04/16 08:27:15 INFO nbd export size export=sda bytes=42949672960
2026/04/16 08:27:15 INFO nbd extent scan complete export=sda extents=493 selected=243
2026/04/16 08:27:15 INFO nbd extent scan complete export=sdb extents=577 selected=285
2026/04/16 08:27:15 INFO target nbd export started path=/tmp/tmp.NU7Aaf6bVg/fstrim.qcow2 host=192.168.161.196 port=20809
2026/04/16 08:27:15 INFO copy extents to remote target extents=493 path=/tmp/tmp.NU7Aaf6bVg/fstrim.qcow2 disk_size=42949672960
2026/04/16 08:27:15 INFO target nbd export started path=/tmp/tmp.NU7Aaf6bVg/fstrim-2.qcow2 host=192.168.161.196 port=20810
2026/04/16 08:27:15 INFO copy extents to remote target extents=577 path=/tmp/tmp.NU7Aaf6bVg/fstrim-2.qcow2 disk_size=42949672960
2026/04/16 08:27:16 INFO nbd: copy progress (sda)  7.79% (50266112/645464064 bytes) 47.93 MiB/s
2026/04/16 08:27:16 INFO nbd: copy progress (sdb)  8.00% (50331648/629473280 bytes) 47.96 MiB/s
2026/04/16 08:27:17 INFO nbd: copy progress (sdb)  16.65% (104792064/629473280 bytes) 49.87 MiB/s
2026/04/16 08:27:17 INFO nbd: copy progress (sda)  16.88% (108986368/645464064 bytes) 49.64 MiB/s
2026/04/16 08:27:18 INFO nbd: copy progress (sda)  24.63% (158990336/645464064 bytes) 47.50 MiB/s
2026/04/16 08:27:19 INFO nbd: copy progress (sdb)  29.19% (183762944/629473280 bytes) 51.26 MiB/s
2026/04/16 08:27:20 INFO nbd: copy progress (sda)  34.89% (225181696/645464064 bytes) 48.62 MiB/s
[..]
2026/04/16 08:27:28 INFO nbd copy complete written_bytes=629473280 device=sdb
2026/04/16 08:27:28 INFO Stopping remote daemon device=sdb
2026/04/16 08:27:28 INFO Commiting changes to base image image=/tmp/tmp.NU7Aaf6bVg/fstrim-2.qcow2
2026/04/16 08:27:28 INFO nbd: copy progress (sda)  97.59% (629932032/645464064 bytes) 46.56 MiB/s
2026/04/16 08:27:28 INFO nbd: copy progress (sda)  100.00% (645464064/645464064 bytes) 46.93 MiB/s
2026/04/16 08:27:28 INFO nbd copy complete written_bytes=645464064 device=sda
2026/04/16 08:27:28 INFO Stopping remote daemon device=sda
2026/04/16 08:27:28 INFO Commiting changes to base image image=/tmp/tmp.NU7Aaf6bVg/fstrim.qcow2
2026/04/16 08:27:28 INFO stopping libvirt backup job trigger=cleanup

• One way sync: if the target VM is started in between replications, this is not taken care of.
• Dirty blocks: currently the NBD client implementation does not detect overlapping fstrimmed/sparse block regions
• Does not care about attached cdrom, raw, TPM or specific kernel image files that may be required to execute the VM on the target system, if so.
• Both source and target libvirt system must run on same operating system / libvirt version
• Target qcow files are created with defaults, may loose settings of original source qcow files (compression settings,..etc)
• Add treshold parameter: only start sync if certain amount of bytes have changed