tests/protocol: Contains a Perl test so we must set PERL5LIB.
[libguestfs.git] / clone / virt-sysprep.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 virt-sysprep - Reset or unconfigure a virtual machine so clones can be made
6
7 =head1 SYNOPSIS
8
9  virt-sysprep [--options] -d domname
10
11  virt-sysprep [--options] -a disk.img [-a disk.img ...]
12
13 =head1 DESCRIPTION
14
15 Virt-sysprep "resets" or "unconfigures" a virtual machine so that
16 clones can be made from it.  Steps in this process include removing
17 SSH host keys, removing persistent network MAC configuration, and
18 removing user accounts.  Each step can be enabled or disabled as
19 required.
20
21 Virt-sysprep is a simple shell script, allowing easy inspection or
22 customization by the system administrator.
23
24 Virt-sysprep modifies the guest or disk image I<in place>.  The guest
25 must be shut down.  If you want to preserve the existing contents of
26 the guest, you I<must copy or clone the disk first>.
27 See L</COPYING AND CLONING> below.
28
29 You do I<not> need to run virt-sysprep as root.  In fact we'd
30 generally recommend that you don't.  The time you might want to run it
31 as root is when you need root in order to access the disk image, but
32 even in this case it would be better to change the permissions on the
33 disk image to be writable as the non-root user running virt-sysprep.
34
35 "Sysprep" stands for "system preparation" tool.  The name comes from
36 the Microsoft program C<sysprep.exe> which is used to unconfigure
37 Windows machines in preparation for cloning them.  Having said that,
38 virt-sysprep does I<not> currently work on Microsoft Windows guests.
39 We plan to support Windows sysprepping in a future version, and we
40 already have code to do it.
41
42 =head1 OPTIONS
43
44 =over 4
45
46 =item B<--help>
47
48 Display brief help.
49
50 =item B<-a> file
51
52 =item B<--add> file
53
54 Add I<file> which should be a disk image from a virtual machine.
55
56 The format of the disk image is auto-detected.  To override this and
57 force a particular format use the I<--format=..> option.
58
59 =item B<-c> URI
60
61 =item B<--connect> URI
62
63 If using libvirt, connect to the given I<URI>.  If omitted, then we
64 connect to the default libvirt hypervisor.
65
66 If you specify guest block devices directly (I<-a>), then libvirt is
67 not used at all.
68
69 =item B<-d> guest
70
71 =item B<--domain> guest
72
73 Add all the disks from the named libvirt guest.  Domain UUIDs can be
74 used instead of names.
75
76 =item B<--enable=...>
77
78 Choose which sysprep operations to perform.  Give a comma-separated
79 list of operations, for example:
80
81  --enable=ssh-hostkeys,udev-persistent-net
82
83 would enable ONLY C<ssh-hostkeys> and C<udev-persistent-net> operations.
84
85 If the I<--enable> option is not given, then we default to trying all
86 possible sysprep operations.  But some sysprep operations are skipped
87 for some guest types.
88
89 Use I<--list-operations> to list operations supported by a particular
90 version of virt-sysprep.
91
92 See L</OPERATIONS> below for a list and an explanation of each
93 operation.
94
95 =item B<--format=raw|qcow2|..>
96
97 =item B<--format>
98
99 The default for the I<-a> option is to auto-detect the format of the
100 disk image.  Using this forces the disk format for I<-a> options which
101 follow on the command line.  Using I<--format> with no argument
102 switches back to auto-detection for subsequent I<-a> options.
103
104 For example:
105
106  virt-sysprep --format=raw -a disk.img
107
108 forces raw format (no auto-detection) for C<disk.img>.
109
110  virt-sysprep --format=raw -a disk.img --format -a another.img
111
112 forces raw format (no auto-detection) for C<disk.img> and reverts to
113 auto-detection for C<another.img>.
114
115 If you have untrusted raw-format guest disk images, you should use
116 this option to specify the disk format.  This avoids a possible
117 security problem with malicious guests (CVE-2010-3851).
118
119 =item B<--hostname> newhostname
120
121 Change the hostname.  See the L</hostname> operation below.
122 If not given, defaults to C<localhost.localdomain>.
123
124 =item B<--list-operations>
125
126 List the operations supported by the virt-sysprep program.
127
128 =item B<--selinux-relabel>
129
130 =item B<--no-selinux-relabel>
131
132 I<--selinux-relabel> forces SELinux relabelling next time the guest
133 boots.  I<--no-selinux-relabel> disables relabelling.
134
135 The default is to try to detect if SELinux relabelling is required.
136 See L</SELINUX RELABELLING> below for more details.
137
138 =item B<-v>
139
140 =item B<--verbose>
141
142 Enable verbose messages for debugging.
143
144 =item B<-V>
145
146 =item B<--version>
147
148 Display version number and exit.
149
150 =item B<-x>
151
152 Enable tracing of libguestfs API calls.
153
154 =back
155
156 =head1 OPERATIONS
157
158 If the I<--enable> option is I<not> given, then
159 I<all sysprep operations are enabled>, although some are skipped
160 depending on the type of guest.
161
162 Operations can be individually enabled using the I<--enable> option.
163 Use a comma-separated list, for example:
164
165  virt-sysprep --enable=ssh-hostkeys,udev-persistent-net [etc..]
166
167 To list the operations supported by the current version of
168 virt-sysprep, use I<--list-operations>.
169
170 Future versions of virt-sysprep may add more operations.  If you are
171 using virt-sysprep and want predictable behaviour, specify only the
172 operations that you want to have enabled.
173
174 =head2 cron-spool
175
176 Remove user at-jobs and cron-jobs.
177
178 =head2 dhcp-client-state
179
180 Remove DHCP client leases.
181
182 =head2 dhcp-server-state
183
184 Remove DHCP server leases.
185
186 =head2 hostname
187
188 Changes the hostname of the guest to the value given in the
189 I<--hostname> parameter.
190
191 If the I<--hostname> parameter is not given, then the hostname is
192 changed to C<localhost.localdomain>.
193
194 =head2 logfiles
195
196 Remove many log files.
197
198 =head2 mail-spool
199
200 Remove email from the local mail spool directory.
201
202 =head2 net-hwaddr
203
204 Remove HWADDR (hard-coded MAC address) configuration.  For Fedora and
205 Red Hat Enterprise Linux, this is removed from C<ifcfg-*> files.
206
207 =head2 random-seed
208
209 Write some random bytes from the host into the random seed file of
210 the guest.
211
212 See L</RANDOM SEED> below.
213
214 =head2 rhn-systemid
215
216 Remove the RHN system ID.
217
218 =head2 smolt-uuid
219
220 Remove the Smolt hardware UUID.
221
222 =head2 ssh-hostkeys
223
224 Remove the SSH host keys in the guest.
225
226 The SSH host keys are regenerated (differently) next time the guest is
227 booted.
228
229 If, after cloning, the guest gets the same IP address, ssh will give
230 you a stark warning about the host key changing:
231
232  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
233  @    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
234  @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
235  IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
236
237 =head2 udev-persistent-net
238
239 Remove udev persistent net rules which map the guest's existing MAC
240 address to a fixed ethernet device (eg. eth0).
241
242 After a guest is cloned, the MAC address usually changes.  Since the
243 old MAC address occupies the old name (eg. eth0), this means the fresh
244 MAC address is assigned to a new name (eg. eth1) and this is usually
245 undesirable.  Erasing the udev persistent net rules avoids this.
246
247 =head2 utmp
248
249 Remove the utmp file.
250
251 This records who is currently logged in on a machine.  In modern Linux
252 distros it is stored in a ramdisk and hence not part of the virtual
253 machine's disk, but it was stored on disk in older distros.
254
255 =head2 yum-uuid
256
257 Remove the yum UUID.
258
259 Yum creates a fresh UUID the next time it runs when it notices that
260 the original UUID has been erased.
261
262 =head1 COPYING AND CLONING
263
264 Virt-sysprep can be used as part of a process of cloning guests, or to
265 prepare a template from which guests can be cloned.  There are many
266 different ways to achieve this using the virt tools, and this section
267 is just an introduction.
268
269 A virtual machine (when switched off) consists of two parts:
270
271 =over 4
272
273 =item I<configuration>
274
275 The configuration or description of the guest.  eg. The libvirt
276 XML (see C<virsh dumpxml>), the running configuration of the guest,
277 or another external format like OVF.
278
279 Some configuration items that might need to be changed:
280
281 =over 4
282
283 =item *
284
285 name
286
287 =item *
288
289 UUID
290
291 =item *
292
293 path to block device(s)
294
295 =item *
296
297 network card MAC address
298
299 =back
300
301 =item I<block device(s)>
302
303 One or more hard disk images, themselves containing files,
304 directories, applications, kernels, configuration, etc.
305
306 Some things inside the block devices that might need to be changed:
307
308 =over 4
309
310 =item *
311
312 hostname and other net configuration
313
314 =item *
315
316 UUID
317
318 =item *
319
320 SSH host keys
321
322 =item *
323
324 Windows unique security ID (SID)
325
326 =item *
327
328 Puppet registration
329
330 =back
331
332 =back
333
334 =head2 COPYING THE BLOCK DEVICE
335
336 Starting with an original guest, you probably wish to copy the guest
337 block device and its configuration to make a template.  Then once you
338 are happy with the template, you will want to make many clones from
339 it.
340
341                         virt-sysprep
342                              |
343                              v
344  original guest --------> template ---------->
345                                       \------> cloned
346                                        \-----> guests
347                                         \---->
348
349 You can, of course, just copy the block device on the host using
350 L<cp(1)> or L<dd(1)>.
351
352                    dd                 dd
353  original guest --------> template ---------->
354                                       \------> cloned
355                                        \-----> guests
356                                         \---->
357
358 There are some smarter (and faster) ways too:
359
360 =over 4
361
362 =item *
363
364                           snapshot
365                 template ---------->
366                             \------> cloned
367                              \-----> guests
368                               \---->
369
370 Use the block device as a backing file and create a snapshot on top
371 for each guest.  The advantage is that you don't need to copy the
372 block device (very fast) and only changes are stored (less storage
373 required).
374
375 Note that writing to the backing file once you have created guests on
376 top of it is not possible: you will corrupt the guests.
377
378 Tools that can do this include:
379 L<qemu-img(1)> (with the I<create -f qcow2 -o backing_file> option),
380 L<lvcreate(8)> (I<--snapshot> option).  Some filesystems (such as
381 btrfs) and most Network Attached Storage devices can also create cheap
382 snapshots from files or LUNs.
383
384 =item *
385
386 Get your NAS to snapshot and/or duplicate the LUN.
387
388 =item *
389
390 Prepare your template using L<virt-sparsify(1)>.  See below.
391
392 =back
393
394 =head2 VIRT-CLONE
395
396 A separate tool, L<virt-clone(1)>, can be used to duplicate the block
397 device and/or modify the external libvirt configuration of a guest.
398 It will reset the name, UUID and MAC address of the guest in the
399 libvirt XML.
400
401 L<virt-clone(1)> does not use libguestfs and cannot look inside the
402 disk image.  This was the original motivation to write virt-sysprep.
403
404 =head2 SPARSIFY
405
406               virt-sparsify
407  original guest --------> template
408
409 L<virt-sparsify(1)> can be used to make the cloning template smaller,
410 making it easier to compress and/or faster to copy.
411
412 Notice that since virt-sparsify also copies the image, you can use it
413 to make the initial copy (instead of C<dd>).
414
415 =head2 RESIZE
416
417                          virt-resize
418                 template ---------->
419                             \------> cloned
420                              \-----> guests
421                               \---->
422
423 If you want to give people cloned guests, but let them pick the size
424 of the guest themselves (eg. depending on how much they are prepared
425 to pay for disk space), then instead of copying the template, you can
426 run L<virt-resize(1)>.  Virt-resize performs a copy and resize, and
427 thus is ideal for cloning guests from a template.
428
429 =head1 SECURITY
430
431 Although virt-sysprep removes some sensitive information from the
432 guest, it does not pretend to remove all of it.  You should examine
433 the L</OPERATIONS> above, and the implementation of the operations in
434 the shell script.  You should also examine the guest afterwards.
435
436 Sensitive files are simply removed.  The data they contained may still
437 exist on the disk, easily recovered with a hex editor or undelete
438 tool.  Use L<virt-sparsify(1)> as one way to remove this content.  See
439 also the L<scrub(1)> command to get rid of deleted content in
440 directory entries and inodes.
441
442 =head2 RANDOM SEED
443
444 I<(This section applies to Linux guests only)>
445
446 The virt-sysprep C<random-seed> operation writes a few bytes of
447 randomness from the host into the guest's random seed file.
448
449 If this is just done once and the guest is cloned from the same
450 template, then each guest will start with the same entropy, and things
451 like SSH host keys and TCP sequence numbers may be predictable.
452
453 Therefore you should arrange to add more randomness I<after> cloning
454 from a template too, which can be done by just enabling the
455 C<random-seed> operation:
456
457  cp template.img newguest.img
458  virt-sysprep --enable=random-seed -a newguest.img
459
460 =head2 SELINUX RELABELLING
461
462 I<(This section applies to Linux guests using SELinux only)>
463
464 If any new files are created by virt-sysprep, then virt-sysprep
465 touches C</.autorelabel> so that these will be correctly labelled by
466 SELinux the next time the guest is booted.  This process interrupts
467 boot and can take some time.
468
469 You can force relabelling for all guests by supplying the
470 I<--selinux-relabel> option.
471
472 You can disable relabelling entirely by supplying the
473 I<--no-selinux-relabel> option.
474
475 =head1 SHELL QUOTING
476
477 Libvirt guest names can contain arbitrary characters, some of which
478 have meaning to the shell such as C<#> and space.  You may need to
479 quote or escape these characters on the command line.  See the shell
480 manual page L<sh(1)> for details.
481
482 =head1 EXIT STATUS
483
484 This program returns 0 on success, or 1 if there was an error.
485
486 =head1 SEE ALSO
487
488 L<guestfs(3)>,
489 L<guestfish(1)>,
490 L<virt-clone(1)>,
491 L<virt-rescue(1)>,
492 L<virt-resize(1)>,
493 L<virt-sparsify(1)>,
494 L<virsh(1)>,
495 L<lvcreate(8)>,
496 L<qemu-img(1)>,
497 L<scrub(1)>,
498 L<http://libguestfs.org/>,
499 L<http://libvirt.org/>.
500
501 =head1 AUTHOR
502
503 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
504
505 =head1 COPYRIGHT
506
507 Copyright (C) 2011 Red Hat Inc.
508
509 This program is free software; you can redistribute it and/or modify
510 it under the terms of the GNU General Public License as published by
511 the Free Software Foundation; either version 2 of the License, or
512 (at your option) any later version.
513
514 This program is distributed in the hope that it will be useful,
515 but WITHOUT ANY WARRANTY; without even the implied warranty of
516 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
517 GNU General Public License for more details.
518
519 You should have received a copy of the GNU General Public License
520 along with this program; if not, write to the Free Software
521 Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.