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