install gen-vzdump.conf.5-opts.pl
[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
01d37422
DM
28'vzdump' is a utility to make consistent backups of running guest
29systems. It basically creates an archive of the guest private area,
30which also includes the guest configuration files. 'vzdump' currently
31supports LXC containers and QemuServer VMs. There are several ways to
32provide consistency (option `mode`), depending on the guest type.
82b4917a 33
01d37422
DM
34.Backup `mode` for VMs:
35
36`stop` mode::
37
38This first performns a clean shutdown of the VM to make sure it is
39stopped. It then starts the VM in suspended mode and uses the qemu
40backup feature to dump all data. If the VM was running, we start
41(resume) it immediately after starting the qemu backup task. This
42keeps the downtime as low as possible.
43
44`suspend` mode::
45
46This mode does not really make sense for qemu. Please use snapshot
47mode instead.
48
49`snapshot` mode::
50
51This mode simply starts a qemu live backup task. If the guest agent
52is enabled (`agent: 1`) and running, it calls 'guest-fsfreeze-freeze'
53and 'guest-fsfreeze-thaw' to improve consistency.
54
55A technical overview of the Proxmox VE live backup for QemuServer can
56be found online
fccf8df6 57https://git.proxmox.com/?p=pve-qemu-kvm.git;a=blob;f=backup.txt[here].
01d37422 58
d083d3d3
DM
59NOTE: Qemu backup provides snapshots on any storage type. It does
60not require that the underlying storage supports snapshots.
61
01d37422
DM
62
63.Backup `mode` for Containers:
82b4917a
DM
64
65`stop` mode::
66
c31f32a9 67Stop the guest during backup. This results in a very long downtime.
82b4917a
DM
68
69`suspend` mode::
70
01d37422 71This mode uses rsync to copy the container data to a temporary
6c60aebf
EK
72location (see option `--tmpdir`). Then the container is suspended and a second
73rsync copies changed files. After that, the container is started (resumed)
871e1fd6 74again. This results in minimal downtime, but needs additional space
6c60aebf 75to hold the container copy.
0006064d 76+
6c60aebf
EK
77When the container is on a local filesystem and the target storage of the backup
78is an NFS server, you should set `--tmpdir` to reside on a local filesystem too,
79as this will result in a many fold performance improvement.
80Use of a local `tmpdir` is also required if you want to backup in `suspend`
81mode a local container using ACLs to an NFS server.
82b4917a
DM
82
83`snapshot` mode::
84
01d37422
DM
85This mode uses the snapshotting facilities of the underlying
86storage. A snapshot will be made of the container volume, and the
87snapshot content will be archived in a tar file.
82b4917a 88
82b4917a
DM
89
90Backup File Names
91-----------------
92
871e1fd6 93Newer versions of vzdump encode the virtual machine type and the
82b4917a
DM
94backup time into the filename, for example
95
96 vzdump-lxc-105-2009_10_09-11_04_43.tar
97
871e1fd6 98That way it is possible to store several backup in the same
82b4917a 99directory. The parameter `maxfiles` can be used to specify the
871e1fd6 100maximum number of backups to keep.
82b4917a
DM
101
102Restore
103-------
104
105The resulting archive files can be restored with the following programs.
106
107
871e1fd6 108`pct restore`:: Container restore utility
82b4917a
DM
109
110`qmrestore`:: QemuServer restore utility
111
112For details see the corresponding manual pages.
113
114Configuration
115-------------
116
d083d3d3
DM
117Global configuration is stored in '/etc/vzdump.conf'. The file uses a
118simple colon separated key/value format. Each line has the following
119format:
120
121 OPTION: value
122
123Blank lines in the file are ignored, and lines starting with a '#'
956afd0a
DM
124character are treated as comments and are also ignored. Values from
125this file are used as default, and can be overwritten on the command
126line.
d083d3d3
DM
127
128We currently support the following options:
129
130include::vzdump.conf.5-opts.adoc[]
131
132
133.Example 'vzdump.conf' Configuration
134----
135tmpdir: /mnt/fast_local_disk
136storage: my_backup_storage
137mode: snapshot
138bwlimit: 10000
139----
82b4917a
DM
140
141Hook Scripts
142------------
143
144You can specify a hook script with option `--script`. This script is
145called at various phases of the backup process, with parameters
146accordingly set. You can find an example in the documentation
147directory ('vzdump-hook-script.pl').
148
149File Exclusions
150---------------
151
152First, this option is only available for container backups. 'vzdump'
153skips the following files with option `--stdexcludes`
154
bf01f882
WB
155 /var/log/?*
156 /tmp/?*
157 /var/tmp/?*
158 /var/run/?*pid
82b4917a
DM
159
160Or you can manually specify exclude paths, for example:
161
bf01f882 162 # vzdump 777 --exclude-path /tmp/ --exclude-path '/var/foo*'
82b4917a
DM
163
164(only excludes tmp directories)
165
166Configuration files are also stored inside the backup archive
167(`/etc/vzdump/`), and will be correctly restored.
168
169Examples
170--------
171
c31f32a9 172Simply dump guest 777 - no snapshot, just archive the guest private area and
82b4917a
DM
173configuration files to the default dump directory (usually
174'/var/liv//vz/dump/').
175
176 # vzdump 777
177
871e1fd6 178Use rsync and suspend/resume to create a snapshot (minimal downtime).
82b4917a
DM
179
180 # vzdump 777 --mode suspend
181
c31f32a9 182Backup all guest systems and send notification mails to root and admin.
82b4917a
DM
183
184 # vzdump --all --mode suspend --mailto root --mailto admin
185
186Use snapshot mode (no downtime).
187
188 # vzdump 777 --dumpdir /mnt/backup --mode snapshot
189
c31f32a9 190Backup more than one guest (selectively)
82b4917a
DM
191
192 # vzdump 101 102 103 --mailto root
193
c31f32a9 194Backup all guests excluding 101 and 102
82b4917a
DM
195
196 # vzdump --mode suspend --exclude 101,102
197
c31f32a9 198Restore a container to a new CT 600
82b4917a
DM
199
200 # pct restore 600 /mnt/backup/vzdump-lxc-777.tar
201
c31f32a9 202Restore a QemuServer VM to VM 601
82b4917a
DM
203
204 # qmrestore /mnt/backup/vzdump-qemu-888.vma 601
205
206Clone an existing container 101 to a new container 300 with a 4GB root
207file system, using pipes
208
209 # vzdump 101 --stdout | pct restore --rootfs 4 300 -
210
211
212ifdef::manvolnum[]
213include::pve-copyright.adoc[]
214endif::manvolnum[]
215