Command line tools - PVE 3.x

Introduction

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

KVM specific

qm

qm - qemu/kvm manager - see qm manual

OpenVZ specific

vzctl

vzctl - utility to control an OpenVZ container.

vztop

vztop - display top CPU processes

user_beancounters

cat /proc/user_beancounters

Backup

vzdump

vzdump - backup utility for virtual machine

USAGE

vzdump OPTIONS [--all | <VMID>]

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

OPTIONS:

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

DESCRIPTION

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.

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.

RESTORE

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

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

CONFIGURATION

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

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

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)

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

LIMITATIONS

VZDump does not save ACLs.

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

vzrestore

vzrestore - restore OpenVZ vzdump backups

USAGE

vzrestore <archive> <VMID>

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

qmrestore

qmrestore - restore QemuServer vzdump backups

USAGE

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

DESCRIPTION

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

pveca

PVE Cluster Administration Toolkit

USAGE

• 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

pveversion

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:

pve-manager/1.5/4660

• 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

aptitude

Standard Debian package update tool

DRBD

See DRBD

Debian Appliance Builder

dab

See Debian_Appliance_Builder

Other useful tools

pveperf

Simple host performance test.

(from man page)

USAGE

pveperf [PATH]

DESCRIPTION

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