VIRTNBDBACKUP(1)

💖 NAME 💖

virtnbdbackup — the backup utility for libvirt, and honestly? she's that girl. 💅

---

✨ DESCRIPTION ✨

Okay bestie, gather round, because this is the whole entire vibe. Here's how you call her:

usage: virtnbdbackup [-h] -d DOMAIN [-l {copy,full,inc,diff,auto}]

[-t {stream,raw}] [-r] -o OUTPUT [-C CHECKPOINTDIR]
       [--scratchdir SCRATCHDIR] [-S] [--pause] [-i INCLUDE] [-x
       EXCLUDE] [-f SOCKETFILE] [-n] [-z [COMPRESS]] [-w WORKER] [-F
       FREEZE_MOUNTPOINT] [-e] [--no-sparse-detection] [-T THRESHOLD]
       [-U URI] [--user USER] [--ssh-user SSH_USER] [--ssh-port
       SSH_PORT] [--ssh-private-key SSH_PRIVATE_KEY] [--password
       PASSWORD] [-P NBD_PORT] [-I NBD_IP] [--tls] [--tls-cert TLS_CERT]
       [-L] [--quiet] [--nocolor] [-q] [-s] [-k] [-p] [-v] [-V]

Long story short: Backup libvirt/qemu virtual machines. That's the whole job. She ate and left no crumbs. 🍓

---

🎀 options 🎀

• -h, --help — prints this help message and dips. iconic behavior tbh. ✨

💅 General options 💅

• -d, --domain DOMAIN — the domain you wanna backup. your main character. 👑
• -l, --level {copy,full,inc,diff,auto} — the backup level. (default: copy)
• -t, --type {stream,raw} — what kind of output you want: stream or raw. (default: stream)
• -r, --raw — throw the full provisioned disk images into the backup too. (default: False)
• -o, --output OUTPUT — the output target directory. where the goods go. 🎁
• -C, --checkpointdir CHECKPOINTDIR — the persistent libvirt checkpoint storage directory.
• --scratchdir SCRATCHDIR — where the temporary scratch file lives. (default: /var/tmp)
• -S, --start-domain — if the VM is offline, start it up. (default: False)
• --pause — freeze-frame the VM while the backup job starts. (default: False)
• -i, --include INCLUDE — back up only the disk with this target dev name (like -i vda).
• -x, --exclude EXCLUDE — skip disk(s) by target dev name (like -x vda,vdb). not invited to the party. 🙈
• -f, --socketfile SOCKETFILE — use this file for the NBD Server socket (default: /var/tmp/virtnbdbackup.685309).
• -n, --noprogress — kill the progress bar. no thoughts, just silence.
• -z, --compress [COMPRESS] — compress with lz4 compression level. (default: False)
• -w, --worker WORKER — how many concurrent workers back up multiple disks at once. (default: amount of disks)
• -F, --freeze-mountpoint FREEZE_MOUNTPOINT — if the qemu agent is available, only freeze the filesystems on these mountpoints inside the VM (default: all).
• -e, --strict — flips the exit code if warnings pop up during the backup. (default: False)
• --no-sparse-detection — skips detecting sparse ranges during incremental or differential backup. (default: False)
• -T, --threshold THRESHOLD — only run the backup if the threshold is actually reached. no fake-outs. 🚫

🌈 Remote Backup options 🌈

• -U, --uri URI — the libvirt connection URI. (default: qemu:///session)
• --user USER — user to authenticate against libvirtd. (default: None)
• --ssh-user SSH_USER — user to authenticate against the remote sshd: used for the remote copy of files. (default: abi)
• --ssh-port SSH_PORT — port to connect to the remote sshd: used for the remote copy of files. (default: 22)
• --ssh-private-key SSH_PRIVATE_KEY — path to the private key file for SSH auth (same energy as ssh -i). (default: None)
• --password PASSWORD — password to authenticate against libvirtd. (default: None)
• -P, --nbd-port NBD_PORT — the port the remote NBD Service uses. should be unique for every backup you start. (default: 10809)
• -I, --nbd-ip NBD_IP — the IP to bind the remote NBD service on (default: hostname returned by libvirtd).
• --tls — enable and use TLS for the NBD connection. (default: False)
• --tls-cert TLS_CERT — path to the TLS certificates used during offline backup and restore. (default: /etc/pki/qemu/)

🌙 Logging options 🌙

• -L, --syslog — also send log messages to syslog. (default: False)
• --quiet — stop logging to stderr. (default: False)
• --nocolor — no colored output. (default: False)

🐛 Debug options 🐛

• -q, --qemu — use Qemu tools to query extents.
• -s, --startonly — only initialize the backup job via libvirt, don't actually back up any data.
• -k, --killonly — kill any running block job. 💀
• -p, --printonly — quit right after printing the estimated checkpoint size.
• -v, --verbose — turn on debug output.
• -V, --version — show the version and exit.

---

🧁 EXAMPLES 🧁

bestie, here's the playbook. copy-paste with confidence. 🫶

# full backup of domain 'webvm' with all attached disks:

virtnbdbackup -d webvm -l full -o /backup/

# incremental backup:

virtnbdbackup -d webvm -l inc -o /backup/

# differential backup:

virtnbdbackup -d webvm -l diff -o /backup/

# full backup, exclude disk 'vda':

virtnbdbackup -d webvm -l full -x vda -o /backup/

# full backup, backup only disk 'vdb':

virtnbdbackup -d webvm -l full -i vdb -o /backup/

# full backup, compression enabled:

virtnbdbackup -d webvm -l full -z -o /backup/

# full backup, create archive:

virtnbdbackup -d webvm -l full -o - > backup.zip

# full backup of vm operating on remote libvirtd:

virtnbdbackup -U qemu+ssh://root@remotehost/system --ssh-user
root -d webvm -l full -o /backup/

---

lowkey a reminder, highkey important: the remote one above wraps onto a second line in the original, so root -d webvm -l full -o /backup/ is the continuation of that same command. keep it together, don't let it get separated. 💜

---

and that's the whole page, bestie!! you're now officially fluent in virtnbdbackup. iykyk. 🌸🦋✨

slay, go back up those VMs. 💖

okay but for real, the credits: this was virtnbdbackup 2.49, dated July 2026, and the manual page is VIRTNBDBACKUP(1). periodt. 👑