5 virt-sysprep - Reset or unconfigure a virtual machine so clones can be made
9 virt-sysprep [--options] -d domname
11 virt-sysprep [--options] -a disk.img [-a disk.img ...]
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
21 Virt-sysprep is a simple shell script, allowing easy inspection or
22 customization by the system administrator.
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.
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.
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.
54 Add I<file> which should be a disk image from a virtual machine.
56 The format of the disk image is auto-detected. To override this and
57 force a particular format use the I<--format=..> option.
61 =item B<--connect> URI
63 If using libvirt, connect to the given I<URI>. If omitted, then we
64 connect to the default libvirt hypervisor.
66 If you specify guest block devices directly (I<-a>), then libvirt is
71 =item B<--domain> guest
73 Add all the disks from the named libvirt guest. Domain UUIDs can be
74 used instead of names.
78 Choose which sysprep operations to perform. Give a comma-separated
79 list of operations, for example:
81 --enable=ssh-hostkeys,udev-persistent-net
83 would enable ONLY C<ssh-hostkeys> and C<udev-persistent-net> operations.
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
89 Use I<--list-operations> to list operations supported by a particular
90 version of virt-sysprep.
92 See L</OPERATIONS> below for a list and an explanation of each
95 =item B<--format=raw|qcow2|..>
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.
106 virt-sysprep --format=raw -a disk.img
108 forces raw format (no auto-detection) for C<disk.img>.
110 virt-sysprep --format=raw -a disk.img --format -a another.img
112 forces raw format (no auto-detection) for C<disk.img> and reverts to
113 auto-detection for C<another.img>.
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).
119 =item B<--hostname> newhostname
121 Change the hostname. See the L</hostname> operation below.
122 If not given, defaults to C<localhost.localdomain>.
124 =item B<--list-operations>
126 List the operations supported by the virt-sysprep program.
128 =item B<--selinux-relabel>
130 =item B<--no-selinux-relabel>
132 I<--selinux-relabel> forces SELinux relabelling next time the guest
133 boots. I<--no-selinux-relabel> disables relabelling.
135 The default is to try to detect if SELinux relabelling is required.
136 See L</SELINUX RELABELLING> below for more details.
142 Enable verbose messages for debugging.
148 Display version number and exit.
152 Enable tracing of libguestfs API calls.
158 If the I<--enable> option is I<not> given, then all sysprep operations
159 in the list below are enabled, although some are skipped depending on
162 Operations can be individually enabled using the I<--enable> option.
163 Use a comma-separated list, for example:
165 virt-sysprep --enable=ssh-hostkeys,udev-persistent-net [etc..]
167 To list the operations supported by the current version of
168 virt-sysprep, use I<--list-operations>.
170 =head2 dhcp-client-state
172 Remove DHCP client leases.
174 =head2 dhcp-server-state
176 Remove DHCP server leases.
180 Changes the hostname of the guest to the value given in the
181 I<--hostname> parameter.
183 If the I<--hostname> parameter is not given, then the hostname is
184 changed to C<localhost.localdomain>.
188 Remove many log files.
192 Remove HWADDR (hard-coded MAC address) configuration. For Fedora and
193 Red Hat Enterprise Linux, this is removed from C<ifcfg-*> files.
197 Write some random bytes from the host into the random seed file of
200 See C</RANDOM SEED> below.
204 Remove the RHN system ID.
208 Remove the Smolt hardware UUID.
212 Remove the SSH host keys in the guest.
214 The SSH host keys are regenerated (differently) next time the guest is
217 If, after cloning, the guest gets the same IP address, ssh will give
218 you a stark warning about the host key changing:
220 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
221 @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
222 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
223 IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
225 =head2 udev-persistent-net
227 Remove udev persistent net rules which map the guest's existing MAC
228 address to a fixed ethernet device (eg. eth0).
230 After a guest is cloned, the MAC address usually changes. Since the
231 old MAC address occupies the old name (eg. eth0), this means the fresh
232 MAC address is assigned to a new name (eg. eth1) and this is usually
233 undesirable. Erasing the udev persistent net rules avoids this.
239 yum creates a fresh UUID the next time it runs when it notices that
240 the original UUID has been erased.
242 =head1 COPYING AND CLONING
244 Virt-sysprep can be used as part of a process of cloning guests, or to
245 prepare a template from which guests can be cloned. There are many
246 different ways to achieve this using the virt tools, and this section
247 is just an introduction.
249 A virtual machine (when switched off) consists of two parts:
253 =item I<configuration>
255 The configuration or description of the guest. eg. The libvirt
256 XML (see C<virsh dumpxml>), the running configuration of the guest,
257 or another external format like OVF.
259 Some configuration items that might need to be changed:
273 path to block device(s)
277 network card MAC address
281 =item I<block device(s)>
283 One or more hard disk images, themselves containing files,
284 directories, applications, kernels, configuration, etc.
286 Some things inside the block devices that might need to be changed:
292 hostname and other net configuration
304 Windows unique security ID (SID)
314 =head2 COPYING THE BLOCK DEVICE
316 Starting with an original guest, you probably wish to copy the guest
317 block device and its configuration to make a template. Then once you
318 are happy with the template, you will want to make many clones from
324 original guest --------> template ---------->
329 You can, of course, just copy the block device on the host using
330 L<cp(1)> or L<dd(1)>.
333 original guest --------> template ---------->
338 There are some smarter (and faster) ways too:
350 Use the block device as a backing file and create a snapshot on top
351 for each guest. The advantage is that you don't need to copy the
352 block device (very fast) and only changes are stored (less storage
355 Note that writing to the backing file once you have created guests on
356 top of it is not possible: you will corrupt the guests.
358 Tools that can do this include:
359 L<qemu-img(1)> (with the I<create -f qcow2 -o backing_file> option),
360 L<lvcreate(8)> (I<--snapshot> option). Some filesystems (such as
361 btrfs) and most Network Attached Storage devices can also create cheap
362 snapshots from files or LUNs.
366 Get your NAS to snapshot and/or duplicate the LUN.
370 Prepare your template using L<virt-sparsify(1)>. See below.
376 A separate tool, L<virt-clone(1)>, can be used to duplicate the block
377 device and/or modify the external libvirt configuration of a guest.
378 It will reset the name, UUID and MAC address of the guest in the
381 L<virt-clone(1)> does not use libguestfs and cannot look inside the
382 disk image. This was the original motivation to write virt-sysprep.
387 original guest --------> template
389 L<virt-sparsify(1)> can be used to make the cloning template smaller,
390 making it easier to compress and/or faster to copy.
392 Notice that since virt-sparsify also copies the image, you can use it
393 to make the initial copy (instead of C<dd>).
403 If you want to give people cloned guests, but let them pick the size
404 of the guest themselves (eg. depending on how much they are prepared
405 to pay for disk space), then instead of copying the template, you can
406 run L<virt-resize(1)>. Virt-resize performs a copy and resize, and
407 thus is ideal for cloning guests from a template.
411 Although virt-sysprep removes some sensitive information from
412 the guest, it does not pretend to remove all of it. You should
413 examine the L</OPERATIONS> above, and the implementation of
414 the operations in the shell script.
416 You should also examine the guest afterwards.
418 Sensitive files are simply removed. The data they contained may still
419 exist on the disk, easily recovered with a hex editor or undelete
420 tool. Use L<virt-sparsify(1)> as one way to remove this content. See
421 also the L<scrub(1)> command to get rid of deleted content in
422 directory entries and inodes.
426 I<(This section applies to Linux guests only)>
428 The virt-sysprep C<random-seed> operation writes a few bytes of
429 randomness from the host into the guest's random seed file.
431 If this is just done once and the guest is cloned from the same
432 template, then each guest will start with the same entropy, and things
433 like SSH host keys and TCP sequence numbers may be predictable.
435 Therefore you should arrange to add more randomness I<after> cloning
436 from a template too, which can be done by just enabling the
437 C<random-seed> operation:
439 cp template.img newguest.img
440 virt-sysprep --enable=random-seed -a newguest.img
442 =head2 SELINUX RELABELLING
444 I<(This section applies to Linux guests using SELinux only)>
446 If any new files are created by virt-sysprep, then virt-sysprep
447 touches C</.autorelabel> so that these will be correctly labelled by
448 SELinux the next time the guest is booted. This process interrupts
449 boot and can take some time.
451 You can force relabelling for all guests by supplying the
452 I<--selinux-relabel> option.
454 You can disable relabelling entirely by supplying the
455 I<--no-selinux-relabel> option.
459 Libvirt guest names can contain arbitrary characters, some of which
460 have meaning to the shell such as C<#> and space. You may need to
461 quote or escape these characters on the command line. See the shell
462 manual page L<sh(1)> for details.
466 This program returns 0 on success, or 1 if there was an error.
480 L<http://libguestfs.org/>,
481 L<http://libvirt.org/>.
485 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
489 Copyright (C) 2011 Red Hat Inc.
491 This program is free software; you can redistribute it and/or modify
492 it under the terms of the GNU General Public License as published by
493 the Free Software Foundation; either version 2 of the License, or
494 (at your option) any later version.
496 This program is distributed in the hope that it will be useful,
497 but WITHOUT ANY WARRANTY; without even the implied warranty of
498 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
499 GNU General Public License for more details.
501 You should have received a copy of the GNU General Public License
502 along with this program; if not, write to the Free Software
503 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.