fish: Fix test-guestfish-events.sh so it works when LIBGUESTFS_DEBUG=1 is set.
[libguestfs.git] / sparsify / virt-sparsify.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 virt-sparsify - Make a virtual machine disk sparse
6
7 =head1 SYNOPSIS
8
9  virt-sparsify [--options] indisk outdisk
10
11 =head1 DESCRIPTION
12
13 Virt-sparsify is a tool which can make a virtual machine disk (or any
14 disk image) sparse a.k.a. thin-provisioned.  This means that free
15 space within the disk image can be converted back to free space on the
16 host.
17
18 Virt-sparsify can locate and sparsify free space in most filesystems
19 (eg. ext2/3/4, btrfs, NTFS, etc.), and also in LVM physical volumes.
20
21 Virt-sparsify can also convert between some disk formats, for example
22 converting a raw disk image to a thin-provisioned qcow2 image.
23
24 Virt-sparsify can operate on any disk image, not just ones from
25 virtual machines.  If a virtual machine has more than one attached
26 disk, you must sparsify each one separately.
27
28 =head2 IMPORTANT LIMITATIONS
29
30 =over 4
31
32 =item *
33
34 Virt-sparsify does not do in-place modifications.  It copies from a
35 source image to a destination image, leaving the source unchanged.
36 I<Check that the sparsification was successful before deleting the
37 source image>.
38
39 =item *
40
41 The virtual machine I<must be shut down> before using this tool.
42
43 =item *
44
45 Virt-sparsify may require up to 2x the virtual size of the source disk
46 image (1 temporary copy + 1 destination image).  This is in the worst
47 case and usually much less space is required.
48
49 =item *
50
51 Virt-sparsify cannot resize disk images.  To do that, use
52 L<virt-resize(1)>.
53
54 =item *
55
56 Virt-sparsify cannot handle encrypted disks.
57
58 =item *
59
60 Virt-sparsify cannot yet sparsify the space between partitions.  Note
61 that this space is often used for critical items like bootloaders so
62 it's not really unused.
63
64 =item *
65
66 Virt-sparsify does not yet know how to sparsify swapspace.  It is not
67 safe to do this unless we can be sure there is no hibernation data, so
68 at the moment swap partitions are ignored.
69
70 =back
71
72 You may also want to read the manual pages for the associated tools
73 L<virt-filesystems(1)> and L<virt-df(1)> before starting.
74
75 =head1 EXAMPLES
76
77 Typical usage is:
78
79  virt-sparsify indisk outdisk
80
81 which copies C<indisk> to C<outdisk>, making the output sparse.
82 C<outdisk> is created, or overwritten if it already exists.  The
83 format of the input disk is detected (eg. qcow2) and the same format
84 is used for the output disk.
85
86 To convert between formats, use the I<--convert> option:
87
88  virt-sparsify disk.raw --convert qcow2 disk.qcow2
89
90 Virt-sparsify tries to zero and sparsify free space on every
91 filesystem it can find within the source disk image.  You can get it
92 to ignore (don't zero free space on) certain filesystems by doing:
93
94  virt-sparsify --ignore /dev/sda1 indisk outdisk
95
96 See L<virt-filesystems(1)> to get a list of filesystems within a disk
97 image.
98
99 =head1 OPTIONS
100
101 =over 4
102
103 =item B<--help>
104
105 Display help.
106
107 =item B<--compress>
108
109 Compress the output file.  This I<only> works if the output format is
110 C<qcow2>.
111
112 =item B<--convert> raw
113
114 =item B<--convert> qcow2
115
116 =item B<--convert> [other formats]
117
118 Use C<output-format> as the format for the destination image.  If this
119 is not specified, then the input format is used.
120
121 Supported and known-working output formats are: C<raw>, C<qcow2>, C<vdi>.
122
123 You can also use any format supported by the L<qemu-img(1)> program,
124 eg. C<vmdk>, but support for other formats is reliant on qemu.
125
126 Specifying the I<--convert> option is usually a good idea, because
127 then virt-sparsify doesn't need to try to guess the input format.
128
129 For fine-tuning the output format, see: I<--compress>, I<-o>.
130
131 =item B<--debug-gc>
132
133 Debug garbage collection and memory allocation.  This is only useful
134 when debugging memory problems in virt-sparsify or the OCaml libguestfs
135 bindings.
136
137 =item B<--format> raw
138
139 =item B<--format> qcow2
140
141 Specify the format of the input disk image.  If this flag is not
142 given then it is auto-detected from the image itself.
143
144 If working with untrusted raw-format guest disk images, you should
145 ensure the format is always specified.
146
147 =item B<--ignore> filesystem
148
149 =item B<--ignore> volgroup
150
151 Ignore the named filesystem.  Free space on the filesystem will not be
152 zeroed, but existing blocks of zeroes will still be sparsified.
153
154 In the second form, this ignores the named volume group.  Use the
155 volume group name without the C</dev/> prefix, eg. I<--ignore vg_foo>
156
157 You can give this option multiple times.
158
159 =item B<--machine-readable>
160
161 This option is used to make the output more machine friendly
162 when being parsed by other programs.  See
163 L</MACHINE READABLE OUTPUT> below.
164
165 =item B<-o> option[,option,...]
166
167 Pass I<-o> option(s) to the L<qemu-img(1)> command to fine-tune the
168 output format.  Options available depend on the output format (see
169 I<--convert>) and the installed version of the qemu-img program.
170
171 You should use I<-o> at most once.  To pass multiple options, separate
172 them with commas, eg:
173
174  virt-sparsify --convert qcow2 \
175    -o cluster_size=512,preallocation=metadata ...
176
177 =item B<-q>
178
179 =item B<--quiet>
180
181 This disables progress bars and other unnecessary output.
182
183 =item B<-v>
184
185 =item B<--verbose>
186
187 Enable verbose messages for debugging.
188
189 =item B<-V>
190
191 =item B<--version>
192
193 Display version number and exit.
194
195 =item B<-x>
196
197 Enable tracing of libguestfs API calls.
198
199 =back
200
201 =head1 MACHINE READABLE OUTPUT
202
203 The I<--machine-readable> option can be used to make the output more
204 machine friendly, which is useful when calling virt-sparsify from
205 other programs, GUIs etc.
206
207 There are two ways to use this option.
208
209 Firstly use the option on its own to query the capabilities of the
210 virt-sparsify binary.  Typical output looks like this:
211
212  $ virt-sparsify --machine-readable
213  virt-sparsify
214  ntfs
215  btrfs
216
217 A list of features is printed, one per line, and the program exits
218 with status 0.
219
220 Secondly use the option in conjunction with other options to make the
221 regular program output more machine friendly.
222
223 At the moment this means:
224
225 =over 4
226
227 =item 1.
228
229 Progress bar messages can be parsed from stdout by looking for this
230 regular expression:
231
232  ^[0-9]+/[0-9]+$
233
234 =item 2.
235
236 The calling program should treat messages sent to stdout (except for
237 progress bar messages) as status messages.  They can be logged and/or
238 displayed to the user.
239
240 =item 3.
241
242 The calling program should treat messages sent to stderr as error
243 messages.  In addition, virt-sparsify exits with a non-zero status
244 code if there was a fatal error.
245
246 =back
247
248 All versions of virt-sparsify have supported the I<--machine-readable>
249 option.
250
251 =head1 EXIT STATUS
252
253 This program returns 0 if successful, or non-zero if there was an
254 error.
255
256 =head1 ENVIRONMENT VARIABLES
257
258 =over 4
259
260 =item TMPDIR
261
262 Location of the temporary directory used for the potentially large
263 temporary overlay file.
264
265 You should ensure there is enough free space in the worst case for a
266 full copy of the source disk (I<virtual> size), or else set C<$TMPDIR>
267 to point to another directory that has enough space.
268
269 This defaults to C</tmp>.
270
271 =back
272
273 For other environment variables, see L<guestfs(3)/ENVIRONMENT VARIABLES>.
274
275 =head1 SEE ALSO
276
277 L<virt-filesystems(1)>,
278 L<virt-df(1)>,
279 L<virt-resize(1)>,
280 L<virt-rescue(1)>,
281 L<guestfs(3)>,
282 L<guestfish(1)>,
283 L<truncate(1)>,
284 L<fallocate(1)>,
285 L<qemu-img(1)>,
286 L<http://libguestfs.org/>.
287
288 =head1 AUTHOR
289
290 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
291
292 =head1 COPYRIGHT
293
294 Copyright (C) 2011 Red Hat Inc.
295
296 This program is free software; you can redistribute it and/or modify
297 it under the terms of the GNU General Public License as published by
298 the Free Software Foundation; either version 2 of the License, or
299 (at your option) any later version.
300
301 This program is distributed in the hope that it will be useful,
302 but WITHOUT ANY WARRANTY; without even the implied warranty of
303 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
304 GNU General Public License for more details.
305
306 You should have received a copy of the GNU General Public License
307 along with this program; if not, write to the Free Software
308 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.