Replace VM occurences with 'guest' or 'container' when appropriate
[pve-docs.git] / vzdump.adoc
CommitLineData
82b4917a
DM
1ifdef::manvolnum[]
2PVE({manvolnum})
3================
38fd0958 4include::attributes.txt[]
82b4917a
DM
5
6NAME
7----
8
9vzdump - Backup Utility for VMs and Containers
10
11
12SYNOPSYS
13--------
14
15include::vzdump.1-synopsis.adoc[]
16
17
18DESCRIPTION
19-----------
20endif::manvolnum[]
21
22ifndef::manvolnum[]
23Backup and Restore
24==================
38fd0958 25include::attributes.txt[]
82b4917a
DM
26endif::manvolnum[]
27
c31f32a9
EK
28'vzdump' is a utility to make consistent snapshots of running guest
29systems. It basically creates an archive of the guest private
30area, which also includes the guest configuration files. 'vzdump'
82b4917a
DM
31currently supports LXC containers and QemuServer VMs.
32
33There are several ways to provide consistency (option `mode`):
34
35`stop` mode::
36
c31f32a9 37Stop the guest during backup. This results in a very long downtime.
82b4917a
DM
38
39`suspend` mode::
40
6c60aebf
EK
41For containers, this mode uses rsync to copy the container data to a temporary
42location (see option `--tmpdir`). Then the container is suspended and a second
43rsync copies changed files. After that, the container is started (resumed)
871e1fd6 44again. This results in minimal downtime, but needs additional space
6c60aebf 45to hold the container copy.
0006064d 46+
6c60aebf
EK
47When the container is on a local filesystem and the target storage of the backup
48is an NFS server, you should set `--tmpdir` to reside on a local filesystem too,
49as this will result in a many fold performance improvement.
50Use of a local `tmpdir` is also required if you want to backup in `suspend`
51mode a local container using ACLs to an NFS server.
0006064d 52+
82b4917a 53For QemuServer, this mode will suspend the VM, start
0006064d
DM
54a live backup, and resume the VM. This does not require a temporary
55storage.
82b4917a
DM
56
57`snapshot` mode::
58
59For containers, this mode uses the snapshotting facilities of the
60underlying storage. A snapshot will be made of the container volume,
61and the snapshot content will be archived in a tar file.
0006064d 62+
82b4917a 63For QemuServer, this mode will do a live backup similar to the
871e1fd6 64`suspend` mode, but without suspending/resuming the VM.
82b4917a
DM
65
66A technical overview of the Proxmox VE live backup for QemuServer can
67be found online
68https://git.proxmox.com/?p=pve-qemu-kvm.git;a=blob;f=backup.txt[here],
69
70Backup File Names
71-----------------
72
871e1fd6 73Newer versions of vzdump encode the virtual machine type and the
82b4917a
DM
74backup time into the filename, for example
75
76 vzdump-lxc-105-2009_10_09-11_04_43.tar
77
871e1fd6 78That way it is possible to store several backup in the same
82b4917a 79directory. The parameter `maxfiles` can be used to specify the
871e1fd6 80maximum number of backups to keep.
82b4917a
DM
81
82Restore
83-------
84
85The resulting archive files can be restored with the following programs.
86
87
871e1fd6 88`pct restore`:: Container restore utility
82b4917a
DM
89
90`qmrestore`:: QemuServer restore utility
91
92For details see the corresponding manual pages.
93
94Configuration
95-------------
96
97Global configuration is stored in '/etc/vzdump.conf'.
98
99 tmpdir: DIR
100 dumpdir: DIR
101 storage: STORAGE_ID
102 mode: snapshot|suspend|stop
103 bwlimit: KBPS
104 ionize: PRI
105 lockwait: MINUTES
106 stopwait: MINUTES
107 size: MB
108 maxfiles: N
109 script: FILENAME
110 exclude-path: PATHLIST
111
112Hook Scripts
113------------
114
115You can specify a hook script with option `--script`. This script is
116called at various phases of the backup process, with parameters
117accordingly set. You can find an example in the documentation
118directory ('vzdump-hook-script.pl').
119
120File Exclusions
121---------------
122
123First, this option is only available for container backups. 'vzdump'
124skips the following files with option `--stdexcludes`
125
bf01f882
WB
126 /var/log/?*
127 /tmp/?*
128 /var/tmp/?*
129 /var/run/?*pid
82b4917a
DM
130
131Or you can manually specify exclude paths, for example:
132
bf01f882 133 # vzdump 777 --exclude-path /tmp/ --exclude-path '/var/foo*'
82b4917a
DM
134
135(only excludes tmp directories)
136
137Configuration files are also stored inside the backup archive
138(`/etc/vzdump/`), and will be correctly restored.
139
140Examples
141--------
142
c31f32a9 143Simply dump guest 777 - no snapshot, just archive the guest private area and
82b4917a
DM
144configuration files to the default dump directory (usually
145'/var/liv//vz/dump/').
146
147 # vzdump 777
148
871e1fd6 149Use rsync and suspend/resume to create a snapshot (minimal downtime).
82b4917a
DM
150
151 # vzdump 777 --mode suspend
152
c31f32a9 153Backup all guest systems and send notification mails to root and admin.
82b4917a
DM
154
155 # vzdump --all --mode suspend --mailto root --mailto admin
156
157Use snapshot mode (no downtime).
158
159 # vzdump 777 --dumpdir /mnt/backup --mode snapshot
160
c31f32a9 161Backup more than one guest (selectively)
82b4917a
DM
162
163 # vzdump 101 102 103 --mailto root
164
c31f32a9 165Backup all guests excluding 101 and 102
82b4917a
DM
166
167 # vzdump --mode suspend --exclude 101,102
168
c31f32a9 169Restore a container to a new CT 600
82b4917a
DM
170
171 # pct restore 600 /mnt/backup/vzdump-lxc-777.tar
172
c31f32a9 173Restore a QemuServer VM to VM 601
82b4917a
DM
174
175 # qmrestore /mnt/backup/vzdump-qemu-888.vma 601
176
177Clone an existing container 101 to a new container 300 with a 4GB root
178file system, using pipes
179
180 # vzdump 101 --stdout | pct restore --rootfs 4 300 -
181
182
183ifdef::manvolnum[]
184include::pve-copyright.adoc[]
185endif::manvolnum[]
186