fix typo
[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
DM
58
59
60.Backup `mode` for Containers:
82b4917a
DM
61
62`stop` mode::
63
c31f32a9 64Stop the guest during backup. This results in a very long downtime.
82b4917a
DM
65
66`suspend` mode::
67
01d37422 68This mode uses rsync to copy the container data to a temporary
6c60aebf
EK
69location (see option `--tmpdir`). Then the container is suspended and a second
70rsync copies changed files. After that, the container is started (resumed)
871e1fd6 71again. This results in minimal downtime, but needs additional space
6c60aebf 72to hold the container copy.
0006064d 73+
6c60aebf
EK
74When the container is on a local filesystem and the target storage of the backup
75is an NFS server, you should set `--tmpdir` to reside on a local filesystem too,
76as this will result in a many fold performance improvement.
77Use of a local `tmpdir` is also required if you want to backup in `suspend`
78mode a local container using ACLs to an NFS server.
82b4917a
DM
79
80`snapshot` mode::
81
01d37422
DM
82This mode uses the snapshotting facilities of the underlying
83storage. A snapshot will be made of the container volume, and the
84snapshot content will be archived in a tar file.
82b4917a 85
82b4917a
DM
86
87Backup File Names
88-----------------
89
871e1fd6 90Newer versions of vzdump encode the virtual machine type and the
82b4917a
DM
91backup time into the filename, for example
92
93 vzdump-lxc-105-2009_10_09-11_04_43.tar
94
871e1fd6 95That way it is possible to store several backup in the same
82b4917a 96directory. The parameter `maxfiles` can be used to specify the
871e1fd6 97maximum number of backups to keep.
82b4917a
DM
98
99Restore
100-------
101
102The resulting archive files can be restored with the following programs.
103
104
871e1fd6 105`pct restore`:: Container restore utility
82b4917a
DM
106
107`qmrestore`:: QemuServer restore utility
108
109For details see the corresponding manual pages.
110
111Configuration
112-------------
113
114Global configuration is stored in '/etc/vzdump.conf'.
115
116 tmpdir: DIR
117 dumpdir: DIR
118 storage: STORAGE_ID
119 mode: snapshot|suspend|stop
120 bwlimit: KBPS
121 ionize: PRI
122 lockwait: MINUTES
123 stopwait: MINUTES
124 size: MB
125 maxfiles: N
126 script: FILENAME
127 exclude-path: PATHLIST
128
129Hook Scripts
130------------
131
132You can specify a hook script with option `--script`. This script is
133called at various phases of the backup process, with parameters
134accordingly set. You can find an example in the documentation
135directory ('vzdump-hook-script.pl').
136
137File Exclusions
138---------------
139
140First, this option is only available for container backups. 'vzdump'
141skips the following files with option `--stdexcludes`
142
bf01f882
WB
143 /var/log/?*
144 /tmp/?*
145 /var/tmp/?*
146 /var/run/?*pid
82b4917a
DM
147
148Or you can manually specify exclude paths, for example:
149
bf01f882 150 # vzdump 777 --exclude-path /tmp/ --exclude-path '/var/foo*'
82b4917a
DM
151
152(only excludes tmp directories)
153
154Configuration files are also stored inside the backup archive
155(`/etc/vzdump/`), and will be correctly restored.
156
157Examples
158--------
159
c31f32a9 160Simply dump guest 777 - no snapshot, just archive the guest private area and
82b4917a
DM
161configuration files to the default dump directory (usually
162'/var/liv//vz/dump/').
163
164 # vzdump 777
165
871e1fd6 166Use rsync and suspend/resume to create a snapshot (minimal downtime).
82b4917a
DM
167
168 # vzdump 777 --mode suspend
169
c31f32a9 170Backup all guest systems and send notification mails to root and admin.
82b4917a
DM
171
172 # vzdump --all --mode suspend --mailto root --mailto admin
173
174Use snapshot mode (no downtime).
175
176 # vzdump 777 --dumpdir /mnt/backup --mode snapshot
177
c31f32a9 178Backup more than one guest (selectively)
82b4917a
DM
179
180 # vzdump 101 102 103 --mailto root
181
c31f32a9 182Backup all guests excluding 101 and 102
82b4917a
DM
183
184 # vzdump --mode suspend --exclude 101,102
185
c31f32a9 186Restore a container to a new CT 600
82b4917a
DM
187
188 # pct restore 600 /mnt/backup/vzdump-lxc-777.tar
189
c31f32a9 190Restore a QemuServer VM to VM 601
82b4917a
DM
191
192 # qmrestore /mnt/backup/vzdump-qemu-888.vma 601
193
194Clone an existing container 101 to a new container 300 with a 4GB root
195file system, using pipes
196
197 # vzdump 101 --stdout | pct restore --rootfs 4 300 -
198
199
200ifdef::manvolnum[]
201include::pve-copyright.adoc[]
202endif::manvolnum[]
203