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