vzdump(1)

📦 version 1.2.6, in ubuntu jammy

💖 vzdump(1) — the Proxmox Documentation classic, but make it a group chat 💖

okay bestie, sit down, hydrate, because this is vzdump, the backup utility for virtual machines, and she is that girl. this is the vzdump(1) page from Proxmox Documentation, and I'm gonna walk you through every single flag like we're ranking them in a tier list. no cap, nothing gets skipped. 🫶

✨ NAME ✨

vzdump — backup utility for virtual machine. that's it, that's the whole vibe. she backs up VMs. iconic behavior. 👑

🌸 SYNOPSIS 🌸

vzdump OPTIONS [--all | <VMID>]

so you're giving her some OPTIONS, and then either --all (everybody gets a backup 🎀) or a single <VMID>. choose your fighter.

💅 OPTIONS 💅

this is the main character section. every option, in order, no skipping, periodt.

  • --exclude VMID — yeet this VMID out of the backup. heads up: this assumes --all, so it only makes sense in all-VM mode. 🙈
  • --exclude-path REGEX — skip certain files/directories by regex. you can drop this option more than once to specify multiple exclude paths. stack 'em like bracelets. ✨
  • --stdexcludes — exclude temporary files and logs. the standard exclusions, the default lil cleanup crew. 🧹
  • --compress — compress the dump file with gzip. squeeze her. 🗜️
  • --storage STORAGE_ID — store the resulting files to STORAGE_ID. (PVE only, so don't come for me if you're not on PVE.) 💾
  • --script — execute the hook script. we love a callback. 🎬
  • --dumpdir DIR — store the resulting files in DIR. pick your destination, bestie. 📁
  • --maxfiles N — maximal number of backup files per VM. she keeps a roster and she sticks to it. 🗂️
  • --tmpdir DIR — store temporary files in DIR. and btw --suspend and --stop are using this directory to store a copy of the VM, so like, it needs room. 🫶
  • --mailto EMAIL — send notification mail to EMAIL. you can use this option more than once to specify multiple receivers. cc the whole group chat. 📧
  • --stop — stop/start VM if running. dramatic entrance, dramatic exit. 💀
  • --suspend — suspend/resume VM when running. nap time, but make it efficient. 😴
  • --snapshot — use LVM snapshot when running. zero downtime, zero stress. 🔥
  • --size MB — LVM snapshot size. default is 1024. 📏
  • --bwlimit KBPS — limit I/O bandwidth, in KBytes per second. throttle her, gently. 🚦
  • --lockwait MINUTES — maximal time to wait for the global lock. so like, vzdump uses a global lock file to make sure that only one instance is running (because running several instance puts too much load on a server, and we do not do that to her). default is 180 (3 hours). ⏳
  • --stopwait MINUTES — maximal time to wait until a VM is stopped. patience is a virtue. 🕰️

🦋 DESCRIPTION 🦋

vzdump is an utility to make consistent snapshots of running virtual machines (VMs). basically she creates a tar archive of the VM private area, which also includes the VM configuration files. vzdump currently supports OpenVZ and QemuServer VMs. two icons, one tool.

now, there are several ways to provide consistency, and each one is a different flavor of chaos:

"stop" mode

Stop the VM during backup. this results in a very long downtime. not the moment, ngl. 😭

"suspend" mode

For OpenVZ, this mode uses rsync to copy the VM to a temporary location (see option --tmpdir). then the VM is suspended and a second rsync copies changed files. after that, the VM is started (resume) again. this results in a minimal downtime, but needs additional space to hold the VM copy. lowkey the smartest one.

For QemuServer, this mode work like "stop" mode, but uses suspend/resume instead of stop/start. same energy, softer landing. ✨

"snapshot" mode

This mode uses LVM2 snapshots. there is no downtime, but snapshot mode needs LVM2 and some free space on the corresponding volume group to create the LVM snapshot. no downtime?? we love to see it. 💖

🎀 BACKUP FILE NAMES 🎀

Newer version of vzdump encodes the virtual machine type and the backup time into the filename, for example:

vzdump-openvz-105-2009_10_09-11_04_43.tar

that way it is possible to store several backup into the same directory. the parameter "maxfiles" can be used to specify the maximal number of backups to keep. organizational queen. 👑

🌈 RESTORE 🌈

the resulting tar files can be restored with the following programs:

  • vzrestore: OpenVZ restore utility
  • qmrestore: QemuServer restore utility

for details see the corresponding manual pages. (iykyk — go read them.) 📖

⭐ CONFIGURATION ⭐

global configuration is stored in /etc/vzdump.conf. here's the whole menu:

tmpdir: DIR
dumpdir: DIR
storage: STORAGE_ID
mode: snapshot|suspend|stop
bwlimit: KBPS
lockwait: MINUTES
stopwait: MINUTES
size: MB
maxfiles: N
script: FILENAME

pick your mode, bestie. snapshot, suspend, or stop. choose wisely. 💅

🧚 HOOK SCRIPT 🧚

you can specify a hook script with option --script. this script is called at various phases of the backup process, with parameters accordingly set. you can find an example in the documentation directory (hook-script.pl). she's got a whole choreography and the hook script is the choreographer. 🎬

💜 EXCLUSIONS (OpenVZ only) 💜

vzdump skips the following files wit option --stdexcludes:

/var/log/.+
/tmp/.+
/var/tmp/.+
/var/run/.+pid

you can manually specify exclude paths, for example:

vzdump --exclude-path "/tmp/.+" --exclude-path "/var/tmp/.+" 777

(only excludes tmp directories) — that's the parenthetical, not me, I'm just relaying it fr fr.

configuration files are also stored inside the backup archive (/etc/vzdump), and will be correctly restored. so like, don't worry about your configs, they're coming back. 🫶

😭 LIMITATIONS 😭

VZDump does not save ACLs. that's the whole limitation. she said no ACLs today. 💀

🔥 EXAMPLES 🔥

Simply dump VM 777 — no snapshot, just archive the VM private area and configuration files to the default dump directory (usually /vz/dump/).

vzdump 777

Use rsync and suspend/resume to create an snapshot (minimal downtime).

vzdump --suspend 777

Backup all VMs and send notification mails to root.

vzdump --suspend --all --mailto root

Use LVM2 to create snapshots (no downtime).

vzdump --dumpdir /mnt/backup --snapshot 777

Backup all VMs excluding VM 101 and 102

vzdump --suspend --exclude 101 --exclude 102

Restore an OpenVZ machine to VM 600

vzrestore /mnt/backup/vzdump-openvz-777.tar 600

Restore an Qemu/KVM machine to VM 601

qmrestore /mnt/backup/vzdump-qemu-888.tar 601

🫶 SEE ALSO 🫶

💖 AUTHOR 💖

Dietmar Maurer <dietmar@proxmox.com> — thank you for your service, king. 🫡

Many thanks to Proxmox Server Solutions (www.proxmox.com) for sponsoring this work. sponsors really said "we believe in her." 💐

Copyright (C) 2007-2009 Proxmox Server Solutions GmbH

Copyright: vzdump is under GNU GPL, the GNU General Public License.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 dated June, 1991.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

okay real talk for one sec, because this part is not a joke: no warranty, bestie. not even the implied kind. the GPL says it plainly and so do I. 💜

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.

and that's the whole page, start to finish, every flag accounted for, nothing skipped, we ate and left no crumbs. 🍓 this was vzdump(1) from Proxmox Documentation, version 1.2, dated 2020-04-27 — so if you're citing her, that's the era, periodt. go make some backups, bestie, your future self is obsessed with you for it. 💅✨

📦 where this page comes from