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 Smolt hardware UUID.
208 Remove the SSH host keys in the guest.
210 The SSH host keys are regenerated (differently) next time the guest is
213 If, after cloning, the guest gets the same IP address, ssh will give
214 you a stark warning about the host key changing:
216 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
217 @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
218 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
219 IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
221 =head2 udev-persistent-net
223 Remove udev persistent net rules which map the guest's existing MAC
224 address to a fixed ethernet device (eg. eth0).
226 After a guest is cloned, the MAC address usually changes. Since the
227 old MAC address occupies the old name (eg. eth0), this means the fresh
228 MAC address is assigned to a new name (eg. eth1) and this is usually
229 undesirable. Erasing the udev persistent net rules avoids this.
235 yum creates a fresh UUID the next time it runs when it notices that
236 the original UUID has been erased.
238 =head1 COPYING AND CLONING
240 Virt-sysprep can be used as part of a process of cloning guests, or to
241 prepare a template from which guests can be cloned. There are many
242 different ways to achieve this using the virt tools, and this section
243 is just an introduction.
245 A virtual machine (when switched off) consists of two parts:
249 =item I<configuration>
251 The configuration or description of the guest. eg. The libvirt
252 XML (see C<virsh dumpxml>), the running configuration of the guest,
253 or another external format like OVF.
255 Some configuration items that might need to be changed:
269 path to block device(s)
273 network card MAC address
277 =item I<block device(s)>
279 One or more hard disk images, themselves containing files,
280 directories, applications, kernels, configuration, etc.
282 Some things inside the block devices that might need to be changed:
288 hostname and other net configuration
300 Windows unique security ID (SID)
310 =head2 COPYING THE BLOCK DEVICE
312 Starting with an original guest, you probably wish to copy the guest
313 block device and its configuration to make a template. Then once you
314 are happy with the template, you will want to make many clones from
320 original guest --------> template ---------->
325 You can, of course, just copy the block device on the host using
326 L<cp(1)> or L<dd(1)>.
329 original guest --------> template ---------->
334 There are some smarter (and faster) ways too:
346 Use the block device as a backing file and create a snapshot on top
347 for each guest. The advantage is that you don't need to copy the
348 block device (very fast) and only changes are stored (less storage
351 Note that writing to the backing file once you have created guests on
352 top of it is not possible: you will corrupt the guests.
354 Tools that can do this include:
355 L<qemu-img(1)> (with the I<create -f qcow2 -o backing_file> option),
356 L<lvcreate(8)> (I<--snapshot> option). Some filesystems (such as
357 btrfs) and most Network Attached Storage devices can also create cheap
358 snapshots from files or LUNs.
362 Get your NAS to snapshot and/or duplicate the LUN.
366 Prepare your template using L<virt-sparsify(1)>. See below.
372 A separate tool, L<virt-clone(1)>, can be used to duplicate the block
373 device and/or modify the external libvirt configuration of a guest.
374 It will reset the name, UUID and MAC address of the guest in the
377 L<virt-clone(1)> does not use libguestfs and cannot look inside the
378 disk image. This was the original motivation to write virt-sysprep.
383 original guest --------> template
385 L<virt-sparsify(1)> can be used to make the cloning template smaller,
386 making it easier to compress and/or faster to copy.
388 Notice that since virt-sparsify also copies the image, you can use it
389 to make the initial copy (instead of C<dd>).
399 If you want to give people cloned guests, but let them pick the size
400 of the guest themselves (eg. depending on how much they are prepared
401 to pay for disk space), then instead of copying the template, you can
402 run L<virt-resize(1)>. Virt-resize performs a copy and resize, and
403 thus is ideal for cloning guests from a template.
407 Although virt-sysprep removes some sensitive information from
408 the guest, it does not pretend to remove all of it. You should
409 examine the L</OPERATIONS> above, and the implementation of
410 the operations in the shell script.
412 You should also examine the guest afterwards.
414 Sensitive files are simply removed. The data they contained may still
415 exist on the disk, easily recovered with a hex editor or undelete
416 tool. Use L<virt-sparsify(1)> as one way to remove this content. See
417 also the L<scrub(1)> command to get rid of deleted content in
418 directory entries and inodes.
422 I<(This section applies to Linux guests only)>
424 The virt-sysprep C<random-seed> operation writes a few bytes of
425 randomness from the host into the guest's random seed file.
427 If this is just done once and the guest is cloned from the same
428 template, then each guest will start with the same entropy, and things
429 like SSH host keys and TCP sequence numbers may be predictable.
431 Therefore you should arrange to add more randomness I<after> cloning
432 from a template too, which can be done by just enabling the
433 C<random-seed> operation:
435 cp template.img newguest.img
436 virt-sysprep --enable=random-seed -a newguest.img
438 =head2 SELINUX RELABELLING
440 I<(This section applies to Linux guests using SELinux only)>
442 If any new files are created by virt-sysprep, then virt-sysprep
443 touches C</.autorelabel> so that these will be correctly labelled by
444 SELinux the next time the guest is booted. This process interrupts
445 boot and can take some time.
447 You can force relabelling for all guests by supplying the
448 I<--selinux-relabel> option.
450 You can disable relabelling entirely by supplying the
451 I<--no-selinux-relabel> option.
455 Libvirt guest names can contain arbitrary characters, some of which
456 have meaning to the shell such as C<#> and space. You may need to
457 quote or escape these characters on the command line. See the shell
458 manual page L<sh(1)> for details.
462 This program returns 0 on success, or 1 if there was an error.
476 L<http://libguestfs.org/>,
477 L<http://libvirt.org/>.
481 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
485 Copyright (C) 2011 Red Hat Inc.
487 This program is free software; you can redistribute it and/or modify
488 it under the terms of the GNU General Public License as published by
489 the Free Software Foundation; either version 2 of the License, or
490 (at your option) any later version.
492 This program is distributed in the hope that it will be useful,
493 but WITHOUT ANY WARRANTY; without even the implied warranty of
494 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
495 GNU General Public License for more details.
497 You should have received a copy of the GNU General Public License
498 along with this program; if not, write to the Free Software
499 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.