Difference between revisions of "Command line tools - PVE 3.x"

From Proxmox VE
Jump to navigation Jump to search
Line 134: Line 134:
qmrestore - restore QemuServer vzdump backups
qmrestore [OPTIONS] <archive> <VMID>
: --info                    #read/verify archive and print relevant information (test run)
: --storage <STORAGE_ID>    #restore to storage <STORAGE_ID>
: --prealloc                #never generate sparse files
Restore the QemuServer vzdump backup <archive> to virtual machine <VMID>. Volumes are allocated on the original storage if there is no "--storage" specified.
=Cluster management=
=Cluster management=

Revision as of 12:26, 15 March 2010


This page lists the important Proxmox VE and Debian command line tools. All CLI tools have also manual pages.

KVM specific


OpenVZ specific




cat /proc/user_beancounters



vzdump - backup utility for virtual machine


vzdump OPTIONS [--all | <VMID>]

(where <VMID> is the ID pve assigns to each virtual machine created)


--exclude VMID #exclude VMID (assumes :--all)
--exclude-path REGEX #exclude certain files/directories. You can use this option more than once to specify multiple exclude paths
--stdexcludes #exclude temporary files and logs
--compress #compress dump file (gzip)
--storage STORAGE_ID #store resulting files to STORAGE_ID (PVE only)
--script #execute hook script
--dumpdir DIR #store resulting files in DIR
--maxfiles N #maximal number of backup files per VM.
--tmpdir DIR #store temporary files in DIR. :--suspend and :--stop are using this directory to store a copy of the VM.
--mailto EMAIL #send notification mail to EMAIL. You can use this option more than once to specify multiple receivers
--stop #stop/start VM if running
--suspend #suspend/resume VM when running
--snapshot #use LVM snapshot when running
--size MB #LVM snapshot size (default 1024)
--bwlimit KBPS #limit I/O bandwidth; KBytes per second
--lockwait MINUTES #maximal time to wait for the global lock. vzdump uses a global lock file to make sure that only one instance is running (running several instance puts too much load on a server). Default is 180 (3 hours).
--stopwait MINUTES #maximal time to wait until a VM is stopped.


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

There are several ways to provide consistency:

  • "stop" mode: Stop the VM during backup. This results in a very long downtime.
  • "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. For QemuServer, this mode work like "stop" mode, but uses suspend/resume instead of stop/start.
  • "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.


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


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.


The resulting tar files can be restored with the following programs.

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


Global configuration is stored in /etc/vzdump.conf.

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


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").


vzdump skips the following files wit option --stdexcludes


You can manually specify exclude paths, for example:

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

(only excludes tmp directories)

Configuration files are also stored inside the backup archive (/etc/vzdump), and will be correctly restored.


VZDump does not save ACLs.


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


vzrestore - restore OpenVZ vzdump backups


vzrestore <archive> <VMID>

Restore the OpenVZ vzdump backup <archive> to virtual machine <VMID>.


qmrestore - restore QemuServer vzdump backups


qmrestore [OPTIONS] <archive> <VMID>

--info #read/verify archive and print relevant information (test run)
--storage <STORAGE_ID> #restore to storage <STORAGE_ID>
--prealloc #never generate sparse files


Restore the QemuServer vzdump backup <archive> to virtual machine <VMID>. Volumes are allocated on the original storage if there is no "--storage" specified.

Cluster management


PVE Cluster Administration Toolkit


  • pveca -l # show cluster status
  • pveca -c # create new cluster with localhost as master
  • pveca -s [-h IP] # sync cluster configuration from master (or IP)
  • pveca -d ID # delete a node
  • pveca -a [-h IP] # add new node to cluster
  • pveca -m # force local node to become master
  • pveca -i # print node info (CID NAME IP ROLE)

Software version check


Proxmox VE version info - Print version information for Proxmox VE packages.

USAGE: pveversion [--verbose]

  • without any argument shows the version of pve-manager, something like:
  • with -v argument it shows a list of programs versions related to pve, like:
pve-manager: 1.5-7 (pve-manager/1.5/4660)
running kernel: 2.6.18-2-pve
proxmox-ve-2.6.18: 1.5-5
pve-kernel-2.6.18-2-pve: 2.6.18-5
pve-kernel-2.6.18-1-pve: 2.6.18-4
qemu-server: 1.1-11
pve-firmware: 1.0-3
libpve-storage-perl: 1.0-10
vncterm: 0.9-2
vzctl: 3.0.23-1pve8
vzdump: 1.2-5
vzprocps: 2.0.11-1dso2
vzquota: 3.0.11-1
pve-qemu-kvm-2.6.18: 0.9.1-5


Standard Debian package update tool





Debian Appliance Builder


See Debian_Appliance_Builder

Other useful tools


Simple host performance test.

(from man page)


pveperf [PATH]


Tries to gather some CPU/Hardisk performance data on the hardisk mounted at PATH (/ is used as default)

It dumps on the terminal:

  • CPU BOGOMIPS: bogomips sum of all CPUs
  • REGEX/SECOND: regular expressions per second (perl performance test), should be above 300000
  • HD SIZE: harddisk size
  • BUFFERED READS: simple HD read test. Modern HDs should reach at least 40 MB/sec
  • AVERAGE SEEK TIME: tests average seek time. Fast SCSI HDs reach values < 8 milliseconds. Common IDE/SATA disks get values from 15 to 20 ms.
  • FSYNCS/SECOND: value should be greater than 200 (you should enable "write back" cache mode on you RAID controller - needs a battery backed cache (BBWC)).
  • DNS EXT: average time to resolve an external DNS name
  • DNS INT: average time to resolve a local DNS name

Note: this command may require root privileges (or sudo) to run, otherwise you get an error after "HD SIZE" value, like: <<sh: /proc/sys/vm/drop_caches: Permission denied unable to open HD at /usr/bin/pveperf line 149.>>