Command line tools

From Proxmox VE
Jump to navigation Jump to search


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


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.



Cluster management


PVE Cluster Administration Toolkit

USAGE: (man page)

  • 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.>>