.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\" ========================================================================
.\"
.IX Title "virt-sysprep 1"
.TH virt-sysprep 1 "2013-12-07" "libguestfs-1.18.1" "Virtualization Support"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
virt\-sysprep \- Reset or unconfigure a virtual machine so clones can be made
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& virt\-sysprep [\-\-options] \-d domname
\&
\& virt\-sysprep [\-\-options] \-a disk.img [\-a disk.img ...]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Virt-sysprep \*(L"resets\*(R" or \*(L"unconfigures\*(R" a virtual machine so that
clones can be made from it. Steps in this process include removing
\&\s-1SSH\s0 host keys, removing persistent network \s-1MAC\s0 configuration, and
removing user accounts. Each step can be enabled or disabled as
required.
.PP
Virt-sysprep modifies the guest or disk image \fIin place\fR. The guest
must be shut down. If you want to preserve the existing contents of
the guest, you \fImust copy or clone the disk first\fR.
See \*(L"\s-1COPYING\s0 \s-1AND\s0 \s-1CLONING\s0\*(R" below.
.PP
You do \fInot\fR 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.
.PP
\&\*(L"Sysprep\*(R" stands for \*(L"system preparation\*(R" tool. The name comes from
the Microsoft program \f(CW\*(C`sysprep.exe\*(C'\fR which is used to unconfigure
Windows machines in preparation for cloning them. Having said that,
virt-sysprep does \fInot\fR currently work on Microsoft Windows guests.
We plan to support Windows sysprepping in a future version, and we
already have code to do it.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-\-help\fR" 4
.IX Item "--help"
Display brief help.
.IP "\fB\-a\fR file" 4
.IX Item "-a file"
.PD 0
.IP "\fB\-\-add\fR file" 4
.IX Item "--add file"
.PD
Add \fIfile\fR which should be a disk image from a virtual machine.
.Sp
The format of the disk image is auto-detected. To override this and
force a particular format use the \fI\-\-format\fR option.
.IP "\fB\-c\fR \s-1URI\s0" 4
.IX Item "-c URI"
.PD 0
.IP "\fB\-\-connect\fR \s-1URI\s0" 4
.IX Item "--connect URI"
.PD
If using libvirt, connect to the given \fI\s-1URI\s0\fR. If omitted, then we
connect to the default libvirt hypervisor.
.Sp
If you specify guest block devices directly (\fI\-a\fR), then libvirt is
not used at all.
.IP "\fB\-d\fR guest" 4
.IX Item "-d guest"
.PD 0
.IP "\fB\-\-domain\fR guest" 4
.IX Item "--domain guest"
.PD
Add all the disks from the named libvirt guest. Domain UUIDs can be
used instead of names.
.IP "\fB\-n\fR" 4
.IX Item "-n"
.PD 0
.IP "\fB\-\-dry\-run\fR" 4
.IX Item "--dry-run"
.PD
Perform a read-only \*(L"dry run\*(R" on the guest. This runs the sysprep
operation, but throws away any changes to the disk at the end.
.IP "\fB\-\-enable\fR operations" 4
.IX Item "--enable operations"
Choose which sysprep operations to perform. Give a comma-separated
list of operations, for example:
.Sp
.Vb 1
\& \-\-enable ssh\-hostkeys,udev\-persistent\-net
.Ve
.Sp
would enable \s-1ONLY\s0 \f(CW\*(C`ssh\-hostkeys\*(C'\fR and \f(CW\*(C`udev\-persistent\-net\*(C'\fR operations.
.Sp
If the \fI\-\-enable\fR option is not given, then we default to trying most
sysprep operations (see \fI\-\-list\-operations\fR to show which are
enabled).
.Sp
Regardless of the \fI\-\-enable\fR option, sysprep operations are skipped
for some guest types.
.Sp
Use \fI\-\-list\-operations\fR to list operations supported by a particular
version of virt-sysprep.
.Sp
See \*(L"\s-1OPERATIONS\s0\*(R" below for a list and an explanation of each
operation.
.IP "\fB\-\-format\fR raw|qcow2|.." 4
.IX Item "--format raw|qcow2|.."
.PD 0
.IP "\fB\-\-format\fR auto" 4
.IX Item "--format auto"
.PD
The default for the \fI\-a\fR option is to auto-detect the format of the
disk image. Using this forces the disk format for \fI\-a\fR options which
follow on the command line. Using \fI\-\-format auto\fR switches back to
auto-detection for subsequent \fI\-a\fR options.
.Sp
For example:
.Sp
.Vb 1
\& virt\-sysprep \-\-format raw \-a disk.img
.Ve
.Sp
forces raw format (no auto-detection) for \f(CW\*(C`disk.img\*(C'\fR.
.Sp
.Vb 1
\& virt\-sysprep \-\-format raw \-a disk.img \-\-format auto \-a another.img
.Ve
.Sp
forces raw format (no auto-detection) for \f(CW\*(C`disk.img\*(C'\fR and reverts to
auto-detection for \f(CW\*(C`another.img\*(C'\fR.
.Sp
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 (\s-1CVE\-2010\-3851\s0).
.IP "\fB\-\-list\-operations\fR" 4
.IX Item "--list-operations"
List the operations supported by the virt-sysprep program.
.Sp
These are listed one per line, with one or more single-space-separated
fields, eg:
.Sp
.Vb 6
\& $ virt\-sysprep \-\-list\-operations
\& bash\-history * Remove the bash history in the guest
\& cron\-spool * Remove user at\-jobs and cron\-jobs
\& dhcp\-client\-state * Remove DHCP client leases
\& dhcp\-server\-state * Remove DHCP server leases
\& [etc]
.Ve
.Sp
The first field is the operation name, which can be supplied
to \fI\-\-enable\fR. The second field is a \f(CW\*(C`*\*(C'\fR character if the
operation is enabled by default or blank if not. Subsequent
fields on the same line are the description of the operation.
.Sp
Before libguestfs 1.17.33 only the first (operation name) field was
shown and all operations were enabled by default.
.IP "\fB\-q\fR" 4
.IX Item "-q"
.PD 0
.IP "\fB\-\-quiet\fR" 4
.IX Item "--quiet"
.PD
Don't print log messages.
.Sp
To enable detailed logging of individual file operations, use \fI\-x\fR.
.IP "\fB\-\-selinux\-relabel\fR" 4
.IX Item "--selinux-relabel"
.PD 0
.IP "\fB\-\-no\-selinux\-relabel\fR" 4
.IX Item "--no-selinux-relabel"
.PD
\&\fI\-\-selinux\-relabel\fR forces SELinux relabelling next time the guest
boots. \fI\-\-no\-selinux\-relabel\fR disables relabelling.
.Sp
The default is to try to detect if SELinux relabelling is required.
See \*(L"\s-1SELINUX\s0 \s-1RELABELLING\s0\*(R" below for more details.
.IP "\fB\-v\fR" 4
.IX Item "-v"
.PD 0
.IP "\fB\-\-verbose\fR" 4
.IX Item "--verbose"
.PD
Enable verbose messages for debugging.
.IP "\fB\-V\fR" 4
.IX Item "-V"
.PD 0
.IP "\fB\-\-version\fR" 4
.IX Item "--version"
.PD
Display version number and exit.
.IP "\fB\-x\fR" 4
.IX Item "-x"
Enable tracing of libguestfs \s-1API\s0 calls.
.ie n .IP "\fB\-\-hostname\fR hostname (see ""hostname"" below)" 4
.el .IP "\fB\-\-hostname\fR hostname (see \f(CWhostname\fR below)" 4
.IX Item "--hostname hostname (see hostname below)"
Change the hostname. If not given, defaults to \f(CW\*(C`localhost.localdomain\*(C'\fR.
.ie n .IP "\fB\-\-script\fR script (see ""script"" below)" 4
.el .IP "\fB\-\-script\fR script (see \f(CWscript\fR below)" 4
.IX Item "--script script (see script below)"
Run the named \f(CW\*(C`script\*(C'\fR (a shell script or program) against the
guest. The script can be any program on the host. The script's
current directory will be the guest's root directory.
.Sp
\&\fBNote:\fR If the script is not on the \f(CW$PATH\fR, then you must give
the full absolute path to the script.
.ie n .IP "\fB\-\-scriptdir\fR scriptdir (see ""script"" below)" 4
.el .IP "\fB\-\-scriptdir\fR scriptdir (see \f(CWscript\fR below)" 4
.IX Item "--scriptdir scriptdir (see script below)"
The mount point (an empty directory on the host) used when
the \f(CW\*(C`script\*(C'\fR operation is enabled and one or more scripts
are specified using \fI\-\-script\fR parameter(s).
.Sp
\&\fBNote:\fR \f(CW\*(C`scriptdir\*(C'\fR \fBmust\fR be an absolute path.
.Sp
If \fI\-\-scriptdir\fR is not specified then a temporary mountpoint
will be created.
.SH "OPERATIONS"
.IX Header "OPERATIONS"
If the \fI\-\-enable\fR option is \fInot\fR given, then most sysprep
operations are enabled.
.PP
Use \f(CW\*(C`virt\-sysprep \-\-list\-operations\*(C'\fR to list all operations for your
virt-sysprep binary. The ones which are enabled by default are marked
with a \f(CW\*(C`*\*(C'\fR character. Regardless of the \fI\-\-enable\fR option, sysprep
operations are skipped for some guest types.
.PP
Operations can be individually enabled using the \fI\-\-enable\fR option.
Use a comma-separated list, for example:
.PP
.Vb 1
\& virt\-sysprep \-\-enable=ssh\-hostkeys,udev\-persistent\-net [etc..]
.Ve
.PP
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.
.PP
\&\f(CW\*(C`*\*(C'\fR = enabled by default when no \fI\-\-enable\fR option is given.
.SS "\fBbash-history\fP *"
.IX Subsection "bash-history *"
Remove the bash history in the guest.
.PP
Remove the bash history of user \*(L"root\*(R" and any other users
who have a \f(CW\*(C`.bash_history\*(C'\fR file in their home directory.
.SS "\fBblkid-tab\fP *"
.IX Subsection "blkid-tab *"
Remove blkid tab in the guest.
.SS "\fBca-certificates\fP"
.IX Subsection "ca-certificates"
Remove \s-1CA\s0 certificates in the guest.
.SS "\fBcron-spool\fP *"
.IX Subsection "cron-spool *"
Remove user at-jobs and cron-jobs.
.SS "\fBdhcp-client-state\fP *"
.IX Subsection "dhcp-client-state *"
Remove \s-1DHCP\s0 client leases.
.SS "\fBdhcp-server-state\fP *"
.IX Subsection "dhcp-server-state *"
Remove \s-1DHCP\s0 server leases.
.SS "\fBdovecot-data\fP *"
.IX Subsection "dovecot-data *"
Remove Dovecot (mail server) data.
.SS "\fBflag-reconfiguration\fP"
.IX Subsection "flag-reconfiguration"
Flag the system for reconfiguration.
.PP
Note that this may require user intervention when the
guest is booted.
.SS "\fBhostname\fP *"
.IX Subsection "hostname *"
Change the hostname of the guest.
.PP
This operation changes the hostname of the guest to the value
given in the \fI\-\-hostname\fR parameter.
.PP
If the \fI\-\-hostname\fR parameter is not given, then the hostname is changed
to \f(CW\*(C`localhost.localdomain\*(C'\fR.
.SS "\fBkerberos-data\fP"
.IX Subsection "kerberos-data"
Remove Kerberos data in the guest.
.SS "\fBlogfiles\fP *"
.IX Subsection "logfiles *"
Remove many log files from the guest.
.PP
On Linux the following files are removed:
.PP
.Vb 10
\& /root/anaconda\-ks.cfg
\& /root/install.log
\& /root/install.log.syslog
\& /var/account/pacct
\& /var/cache/gdm/*
\& /var/lib/AccountService/users/*
\& /var/lib/fprint/*
\& /var/lib/logrotate.status
\& /var/log/*.log*
\& /var/log/BackupPC/LOG
\& /var/log/audit/*
\& /var/log/btmp*
\& /var/log/ceph/*.log
\& /var/log/chrony/*.log
\& /var/log/cron*
\& /var/log/cups/*_log
\& /var/log/dmesg*
\& /var/log/glusterfs/*glusterd.vol.log
\& /var/log/glusterfs/glusterfs.log
\& /var/log/httpd/*log
\& /var/log/jetty/jetty\-console.log
\& /var/log/lastlog*
\& /var/log/libvirt/libvirtd.log
\& /var/log/libvirt/lxc/*.log
\& /var/log/libvirt/qemu/*.log
\& /var/log/libvirt/uml/*.log
\& /var/log/mail/*
\& /var/log/maillog*
\& /var/log/messages*
\& /var/log/ppp/connect\-errors
\& /var/log/secure*
\& /var/log/setroubleshoot/*.log
\& /var/log/spooler*
\& /var/log/squid/*.log
\& /var/log/tallylog*
\& /var/log/wtmp*
\& /var/named/data/named.run
.Ve
.SS "\fBmail-spool\fP *"
.IX Subsection "mail-spool *"
Remove email from the local mail spool directory.
.SS "\fBnet-hwaddr\fP *"
.IX Subsection "net-hwaddr *"
Remove \s-1HWADDR\s0 (hard-coded \s-1MAC\s0 address) configuration.
.PP
For Fedora and Red Hat Enterprise Linux,
this is removed from \f(CW\*(C`ifcfg\-*\*(C'\fR files.
.SS "\fBpackage-manager-cache\fP *"
.IX Subsection "package-manager-cache *"
Remove package manager cache.
.SS "\fBpam-data\fP *"
.IX Subsection "pam-data *"
Remove the \s-1PAM\s0 data in the guest.
.SS "\fBrandom-seed\fP *"
.IX Subsection "random-seed *"
Generate random seed for guest.
.PP
Write some random bytes from the host into the random seed file of the
guest.
.PP
See \*(L"\s-1RANDOM\s0 \s-1SEED\s0\*(R" below.
.SS "\fBrhn-systemid\fP *"
.IX Subsection "rhn-systemid *"
Remove the \s-1RHN\s0 system \s-1ID\s0.
.SS "\fBsamba-db-log\fP *"
.IX Subsection "samba-db-log *"
Remove the database and log files of Samba.
.SS "\fBscript\fP *"
.IX Subsection "script *"
Run arbitrary scripts against the guest.
.PP
The \f(CW\*(C`script\*(C'\fR module lets you run arbitrary shell scripts or programs
against the guest.
.PP
Note this feature requires \s-1FUSE\s0 support. You may have to enable
this in your host, for example by adding the current user to the
\&\f(CW\*(C`fuse\*(C'\fR group, or by loading a kernel module.
.PP
Use one or more \fI\-\-script\fR parameters to specify scripts or programs
that will be run against the guest.
.PP
The script or program is run with its current directory being the
guest's root directory, so relative paths should be used. For
example: \f(CW\*(C`rm etc/resolv.conf\*(C'\fR in the script would remove a Linux
guest's \s-1DNS\s0 configuration file, but \f(CW\*(C`rm /etc/resolv.conf\*(C'\fR would
(try to) remove the host's file.
.PP
Normally a temporary mount point for the guest is used, but you
can choose a specific one by using the \fI\-\-scriptdir\fR parameter.
.SS "\fBsmolt-uuid\fP *"
.IX Subsection "smolt-uuid *"
Remove the Smolt hardware \s-1UUID\s0.
.SS "\fBssh-hostkeys\fP *"
.IX Subsection "ssh-hostkeys *"
Remove the \s-1SSH\s0 host keys in the guest.
.PP
The \s-1SSH\s0 host keys are regenerated (differently) next time the guest is
booted.
.PP
If, after cloning, the guest gets the same \s-1IP\s0 address, ssh will give
you a stark warning about the host key changing:
.PP
.Vb 4
\& @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
\& @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
\& @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
\& IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
.Ve
.SS "\fBssh-userdir\fP *"
.IX Subsection "ssh-userdir *"
Remove \*(L".ssh\*(R" directories in the guest.
.PP
Remove the \f(CW\*(C`.ssh\*(C'\fR directory of user \*(L"root\*(R" and any other
users who have a \f(CW\*(C`.ssh\*(C'\fR directory in their home directory.
.SS "\fBsssd-db-log\fP *"
.IX Subsection "sssd-db-log *"
Remove the database and log files of sssd.
.SS "\fBudev-persistent-net\fP *"
.IX Subsection "udev-persistent-net *"
Remove udev persistent net rules.
.PP
Remove udev persistent net rules which map the guest's existing \s-1MAC\s0
address to a fixed ethernet device (eg. eth0).
.PP
After a guest is cloned, the \s-1MAC\s0 address usually changes. Since the
old \s-1MAC\s0 address occupies the old name (eg. eth0), this means the fresh
\&\s-1MAC\s0 address is assigned to a new name (eg. eth1) and this is usually
undesirable. Erasing the udev persistent net rules avoids this.
.SS "\fBuser-account\fP"
.IX Subsection "user-account"
Remove the user accounts in the guest.
.PP
Remove all the user accounts and their home directories.
The \*(L"root\*(R" account is not removed.
.SS "\fButmp\fP *"
.IX Subsection "utmp *"
Remove the utmp file.
.PP
This file records who is currently logged in on a machine. In modern
Linux distros it is stored in a ramdisk and hence not part of the
virtual machine's disk, but it was stored on disk in older distros.
.SS "\fByum-uuid\fP *"
.IX Subsection "yum-uuid *"
Remove the yum \s-1UUID\s0.
.PP
Yum creates a fresh \s-1UUID\s0 the next time it runs when it notices that the
original \s-1UUID\s0 has been erased.
.SH "COPYING AND CLONING"
.IX Header "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.
.PP
A virtual machine (when switched off) consists of two parts:
.IP "\fIconfiguration\fR" 4
.IX Item "configuration"
The configuration or description of the guest. eg. The libvirt
\&\s-1XML\s0 (see \f(CW\*(C`virsh dumpxml\*(C'\fR), the running configuration of the guest,
or another external format like \s-1OVF\s0.
.Sp
Some configuration items that might need to be changed:
.RS 4
.IP "\(bu" 4
name
.IP "\(bu" 4
\&\s-1UUID\s0
.IP "\(bu" 4
path to block device(s)
.IP "\(bu" 4
network card \s-1MAC\s0 address
.RE
.RS 4
.RE
.IP "\fIblock device(s)\fR" 4
.IX Item "block device(s)"
One or more hard disk images, themselves containing files,
directories, applications, kernels, configuration, etc.
.Sp
Some things inside the block devices that might need to be changed:
.RS 4
.IP "\(bu" 4
hostname and other net configuration
.IP "\(bu" 4
\&\s-1UUID\s0
.IP "\(bu" 4
\&\s-1SSH\s0 host keys
.IP "\(bu" 4
Windows unique security \s-1ID\s0 (\s-1SID\s0)
.IP "\(bu" 4
Puppet registration
.RE
.RS 4
.RE
.SS "\s-1COPYING\s0 \s-1THE\s0 \s-1BLOCK\s0 \s-1DEVICE\s0"
.IX Subsection "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.
.PP
.Vb 7
\& virt\-sysprep
\& |
\& v
\& original guest \-\-\-\-\-\-\-\-> template \-\-\-\-\-\-\-\-\-\->
\& \e\-\-\-\-\-\-> cloned
\& \e\-\-\-\-\-> guests
\& \e\-\-\-\->
.Ve
.PP
You can, of course, just copy the block device on the host using
\&\fIcp\fR\|(1) or \fIdd\fR\|(1).
.PP
.Vb 5
\& dd dd
\& original guest \-\-\-\-\-\-\-\-> template \-\-\-\-\-\-\-\-\-\->
\& \e\-\-\-\-\-\-> cloned
\& \e\-\-\-\-\-> guests
\& \e\-\-\-\->
.Ve
.PP
There are some smarter (and faster) ways too:
.IP "\(bu" 4
.Sp
.Vb 5
\& snapshot
\& template \-\-\-\-\-\-\-\-\-\->
\& \e\-\-\-\-\-\-> cloned
\& \e\-\-\-\-\-> guests
\& \e\-\-\-\->
.Ve
.Sp
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).
.Sp
Note that writing to the backing file once you have created guests on
top of it is not possible: you will corrupt the guests.
.Sp
Tools that can do this include:
\&\fIqemu\-img\fR\|(1) (with the \fIcreate \-f qcow2 \-o backing_file\fR option),
\&\fIlvcreate\fR\|(8) (\fI\-\-snapshot\fR option). Some filesystems (such as
btrfs) and most Network Attached Storage devices can also create cheap
snapshots from files or LUNs.
.IP "\(bu" 4
Get your \s-1NAS\s0 to snapshot and/or duplicate the \s-1LUN\s0.
.IP "\(bu" 4
Prepare your template using \fIvirt\-sparsify\fR\|(1). See below.
.SS "VIRT-CLONE"
.IX Subsection "VIRT-CLONE"
A separate tool, \fIvirt\-clone\fR\|(1), can be used to duplicate the block
device and/or modify the external libvirt configuration of a guest.
It will reset the name, \s-1UUID\s0 and \s-1MAC\s0 address of the guest in the
libvirt \s-1XML\s0.
.PP
\&\fIvirt\-clone\fR\|(1) does not use libguestfs and cannot look inside the
disk image. This was the original motivation to write virt-sysprep.
.SS "\s-1SPARSIFY\s0"
.IX Subsection "SPARSIFY"
.Vb 2
\& virt\-sparsify
\& original guest \-\-\-\-\-\-\-\-> template
.Ve
.PP
\&\fIvirt\-sparsify\fR\|(1) can be used to make the cloning template smaller,
making it easier to compress and/or faster to copy.
.PP
Notice that since virt-sparsify also copies the image, you can use it
to make the initial copy (instead of \f(CW\*(C`dd\*(C'\fR).
.SS "\s-1RESIZE\s0"
.IX Subsection "RESIZE"
.Vb 5
\& virt\-resize
\& template \-\-\-\-\-\-\-\-\-\->
\& \e\-\-\-\-\-\-> cloned
\& \e\-\-\-\-\-> guests
\& \e\-\-\-\->
.Ve
.PP
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 \fIvirt\-resize\fR\|(1). Virt-resize performs a copy and resize, and
thus is ideal for cloning guests from a template.
.SH "SECURITY"
.IX Header "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"\s-1OPERATIONS\s0\*(R" above and the guest afterwards.
.PP
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 \fIvirt\-sparsify\fR\|(1) as one way to remove this content. See
also the \fIscrub\fR\|(1) command to get rid of deleted content in
directory entries and inodes.
.SS "\s-1RANDOM\s0 \s-1SEED\s0"
.IX Subsection "RANDOM SEED"
\&\fI(This section applies to Linux guests only)\fR
.PP
The virt-sysprep \f(CW\*(C`random\-seed\*(C'\fR operation writes a few bytes of
randomness from the host into the guest's random seed file.
.PP
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 \s-1SSH\s0 host keys and \s-1TCP\s0 sequence numbers may be predictable.
.PP
Therefore you should arrange to add more randomness \fIafter\fR cloning
from a template too, which can be done by just enabling the
\&\f(CW\*(C`random\-seed\*(C'\fR operation:
.PP
.Vb 2
\& cp template.img newguest.img
\& virt\-sysprep \-\-enable random\-seed \-a newguest.img
.Ve
.SS "\s-1SELINUX\s0 \s-1RELABELLING\s0"
.IX Subsection "SELINUX RELABELLING"
\&\fI(This section applies to Linux guests using SELinux only)\fR
.PP
If any new files are created by virt-sysprep, then virt-sysprep
touches \f(CW\*(C`/.autorelabel\*(C'\fR 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.
.PP
You can force relabelling for all guests by supplying the
\&\fI\-\-selinux\-relabel\fR option.
.PP
You can disable relabelling entirely by supplying the
\&\fI\-\-no\-selinux\-relabel\fR option.
.SH "SHELL QUOTING"
.IX Header "SHELL QUOTING"
Libvirt guest names can contain arbitrary characters, some of which
have meaning to the shell such as \f(CW\*(C`#\*(C'\fR and space. You may need to
quote or escape these characters on the command line. See the shell
manual page \fIsh\fR\|(1) for details.
.SH "EXIT STATUS"
.IX Header "EXIT STATUS"
This program returns 0 on success, or 1 if there was an error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIguestfs\fR\|(3),
\&\fIguestfish\fR\|(1),
\&\fIvirt\-clone\fR\|(1),
\&\fIvirt\-rescue\fR\|(1),
\&\fIvirt\-resize\fR\|(1),
\&\fIvirt\-sparsify\fR\|(1),
\&\fIvirsh\fR\|(1),
\&\fIlvcreate\fR\|(8),
\&\fIqemu\-img\fR\|(1),
\&\fIscrub\fR\|(1),
,
.
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones
.PP
Wanlong Gao, Fujitsu Ltd.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2011\-2012 Red Hat Inc.
.PP
Copyright (C) 2012 Fujitsu Ltd.
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, \s-1MA\s0 02110\-1301 \s-1USA\s0.