diff options
Diffstat (limited to 'sysprep/virt-sysprep.pod')
| -rwxr-xr-x | sysprep/virt-sysprep.pod | 435 |
1 files changed, 435 insertions, 0 deletions
diff --git a/sysprep/virt-sysprep.pod b/sysprep/virt-sysprep.pod new file mode 100755 index 00000000..8120c78d --- /dev/null +++ b/sysprep/virt-sysprep.pod @@ -0,0 +1,435 @@ +=encoding utf8 + +=head1 NAME + +virt-sysprep - Reset or unconfigure a virtual machine so clones can be made + +=head1 SYNOPSIS + + virt-sysprep [--options] -d domname + + virt-sysprep [--options] -a disk.img [-a disk.img ...] + +=head1 DESCRIPTION + +Virt-sysprep "resets" or "unconfigures" a virtual machine so that +clones can be made from it. Steps in this process include removing +SSH host keys, removing persistent network MAC configuration, and +removing user accounts. Each step can be enabled or disabled as +required. + +Virt-sysprep modifies the guest or disk image I<in place>. The guest +must be shut down. If you want to preserve the existing contents of +the guest, you I<must copy or clone the disk first>. +See L</COPYING AND CLONING> below. + +You do I<not> need to run virt-sysprep as root. In fact we'd +generally recommend that you don't. The time you might want to run it +as root is when you need root in order to access the disk image, but +even in this case it would be better to change the permissions on the +disk image to be writable as the non-root user running virt-sysprep. + +"Sysprep" stands for "system preparation" tool. The name comes from +the Microsoft program C<sysprep.exe> which is used to unconfigure +Windows machines in preparation for cloning them. Having said that, +virt-sysprep does I<not> currently work on Microsoft Windows guests. +We plan to support Windows sysprepping in a future version, and we +already have code to do it. + +=head1 OPTIONS + +=over 4 + +=item B<--help> + +Display brief help. + +=item B<-a> file + +=item B<--add> file + +Add I<file> which should be a disk image from a virtual machine. + +The format of the disk image is auto-detected. To override this and +force a particular format use the I<--format> option. + +=item B<-c> URI + +=item B<--connect> URI + +If using libvirt, connect to the given I<URI>. If omitted, then we +connect to the default libvirt hypervisor. + +If you specify guest block devices directly (I<-a>), then libvirt is +not used at all. + +=item B<-d> guest + +=item B<--domain> guest + +Add all the disks from the named libvirt guest. Domain UUIDs can be +used instead of names. + +=item B<-n> + +=item B<--dry-run> + +Perform a read-only "dry run" on the guest. This runs the sysprep +operation, but throws away any changes to the disk at the end. + +=item B<--enable> operations + +Choose which sysprep operations to perform. Give a comma-separated +list of operations, for example: + + --enable ssh-hostkeys,udev-persistent-net + +would enable ONLY C<ssh-hostkeys> and C<udev-persistent-net> operations. + +If the I<--enable> option is not given, then we default to trying all +possible sysprep operations. But some sysprep operations are skipped +for some guest types. + +Use I<--list-operations> to list operations supported by a particular +version of virt-sysprep. + +See L</OPERATIONS> below for a list and an explanation of each +operation. + +=item B<--format> raw|qcow2|.. + +=item B<--format> auto + +The default for the I<-a> option is to auto-detect the format of the +disk image. Using this forces the disk format for I<-a> options which +follow on the command line. Using I<--format auto> switches back to +auto-detection for subsequent I<-a> options. + +For example: + + virt-sysprep --format raw -a disk.img + +forces raw format (no auto-detection) for C<disk.img>. + + virt-sysprep --format raw -a disk.img --format auto -a another.img + +forces raw format (no auto-detection) for C<disk.img> and reverts to +auto-detection for C<another.img>. + +If you have untrusted raw-format guest disk images, you should use +this option to specify the disk format. This avoids a possible +security problem with malicious guests (CVE-2010-3851). + +=item B<--list-operations> + +List the operations supported by the virt-sysprep program. + +=item B<--selinux-relabel> + +=item B<--no-selinux-relabel> + +I<--selinux-relabel> forces SELinux relabelling next time the guest +boots. I<--no-selinux-relabel> disables relabelling. + +The default is to try to detect if SELinux relabelling is required. +See L</SELINUX RELABELLING> below for more details. + +=item B<-v> + +=item B<--verbose> + +Enable verbose messages for debugging. + +=item B<-V> + +=item B<--version> + +Display version number and exit. + +=item B<-x> + +Enable tracing of libguestfs API calls. + +@EXTRA_OPTIONS@ + +=back + +=head1 OPERATIONS + +If the I<--enable> option is I<not> given, then +I<all sysprep operations are enabled>, although some are skipped +depending on the type of guest. + +Operations can be individually enabled using the I<--enable> option. +Use a comma-separated list, for example: + + virt-sysprep --enable=ssh-hostkeys,udev-persistent-net [etc..] + +To list the operations supported by the current version of +virt-sysprep, use I<--list-operations>. + +Future versions of virt-sysprep may add more operations. If you are +using virt-sysprep and want predictable behaviour, specify only the +operations that you want to have enabled. + +@OPERATIONS@ + +=head1 COPYING AND CLONING + +Virt-sysprep can be used as part of a process of cloning guests, or to +prepare a template from which guests can be cloned. There are many +different ways to achieve this using the virt tools, and this section +is just an introduction. + +A virtual machine (when switched off) consists of two parts: + +=over 4 + +=item I<configuration> + +The configuration or description of the guest. eg. The libvirt +XML (see C<virsh dumpxml>), the running configuration of the guest, +or another external format like OVF. + +Some configuration items that might need to be changed: + +=over 4 + +=item * + +name + +=item * + +UUID + +=item * + +path to block device(s) + +=item * + +network card MAC address + +=back + +=item I<block device(s)> + +One or more hard disk images, themselves containing files, +directories, applications, kernels, configuration, etc. + +Some things inside the block devices that might need to be changed: + +=over 4 + +=item * + +hostname and other net configuration + +=item * + +UUID + +=item * + +SSH host keys + +=item * + +Windows unique security ID (SID) + +=item * + +Puppet registration + +=back + +=back + +=head2 COPYING THE BLOCK DEVICE + +Starting with an original guest, you probably wish to copy the guest +block device and its configuration to make a template. Then once you +are happy with the template, you will want to make many clones from +it. + + virt-sysprep + | + v + original guest --------> template ----------> + \------> cloned + \-----> guests + \----> + +You can, of course, just copy the block device on the host using +L<cp(1)> or L<dd(1)>. + + dd dd + original guest --------> template ----------> + \------> cloned + \-----> guests + \----> + +There are some smarter (and faster) ways too: + +=over 4 + +=item * + + snapshot + template ----------> + \------> cloned + \-----> guests + \----> + +Use the block device as a backing file and create a snapshot on top +for each guest. The advantage is that you don't need to copy the +block device (very fast) and only changes are stored (less storage +required). + +Note that writing to the backing file once you have created guests on +top of it is not possible: you will corrupt the guests. + +Tools that can do this include: +L<qemu-img(1)> (with the I<create -f qcow2 -o backing_file> option), +L<lvcreate(8)> (I<--snapshot> option). Some filesystems (such as +btrfs) and most Network Attached Storage devices can also create cheap +snapshots from files or LUNs. + +=item * + +Get your NAS to snapshot and/or duplicate the LUN. + +=item * + +Prepare your template using L<virt-sparsify(1)>. See below. + +=back + +=head2 VIRT-CLONE + +A separate tool, L<virt-clone(1)>, can be used to duplicate the block +device and/or modify the external libvirt configuration of a guest. +It will reset the name, UUID and MAC address of the guest in the +libvirt XML. + +L<virt-clone(1)> does not use libguestfs and cannot look inside the +disk image. This was the original motivation to write virt-sysprep. + +=head2 SPARSIFY + + virt-sparsify + original guest --------> template + +L<virt-sparsify(1)> can be used to make the cloning template smaller, +making it easier to compress and/or faster to copy. + +Notice that since virt-sparsify also copies the image, you can use it +to make the initial copy (instead of C<dd>). + +=head2 RESIZE + + virt-resize + template ----------> + \------> cloned + \-----> guests + \----> + +If you want to give people cloned guests, but let them pick the size +of the guest themselves (eg. depending on how much they are prepared +to pay for disk space), then instead of copying the template, you can +run L<virt-resize(1)>. Virt-resize performs a copy and resize, and +thus is ideal for cloning guests from a template. + +=head1 SECURITY + +Although virt-sysprep removes some sensitive information from the +guest, it does not pretend to remove all of it. You should examine +the L</OPERATIONS> above and the guest afterwards. + +Sensitive files are simply removed. The data they contained may still +exist on the disk, easily recovered with a hex editor or undelete +tool. Use L<virt-sparsify(1)> as one way to remove this content. See +also the L<scrub(1)> command to get rid of deleted content in +directory entries and inodes. + +=head2 RANDOM SEED + +I<(This section applies to Linux guests only)> + +The virt-sysprep C<random-seed> operation writes a few bytes of +randomness from the host into the guest's random seed file. + +If this is just done once and the guest is cloned from the same +template, then each guest will start with the same entropy, and things +like SSH host keys and TCP sequence numbers may be predictable. + +Therefore you should arrange to add more randomness I<after> cloning +from a template too, which can be done by just enabling the +C<random-seed> operation: + + cp template.img newguest.img + virt-sysprep --enable random-seed -a newguest.img + +=head2 SELINUX RELABELLING + +I<(This section applies to Linux guests using SELinux only)> + +If any new files are created by virt-sysprep, then virt-sysprep +touches C</.autorelabel> so that these will be correctly labelled by +SELinux the next time the guest is booted. This process interrupts +boot and can take some time. + +You can force relabelling for all guests by supplying the +I<--selinux-relabel> option. + +You can disable relabelling entirely by supplying the +I<--no-selinux-relabel> option. + +=head1 SHELL QUOTING + +Libvirt guest names can contain arbitrary characters, some of which +have meaning to the shell such as C<#> and space. You may need to +quote or escape these characters on the command line. See the shell +manual page L<sh(1)> for details. + +=head1 EXIT STATUS + +This program returns 0 on success, or 1 if there was an error. + +=head1 SEE ALSO + +L<guestfs(3)>, +L<guestfish(1)>, +L<virt-clone(1)>, +L<virt-rescue(1)>, +L<virt-resize(1)>, +L<virt-sparsify(1)>, +L<virsh(1)>, +L<lvcreate(8)>, +L<qemu-img(1)>, +L<scrub(1)>, +L<http://libguestfs.org/>, +L<http://libvirt.org/>. + +=head1 AUTHOR + +Richard W.M. Jones L<http://people.redhat.com/~rjones/> + +=head1 COPYRIGHT + +Copyright (C) 2011-2012 Red Hat Inc. + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. |