21.11. virt-sysprep: Resetting Virtual Machine Settings

The virt-sysprep command-line tool can be used to reset or unconfigure a guest virtual machine so that clones can be made from it. This process involves removing SSH host keys, removing persistent network MAC configuration, and removing user accounts. Virt-sysprep can also customize a virtual machine, for instance by adding SSH keys, users or logos. Each step can be enabled or disabled as required.
To use virt-sysprep, the guest virtual machine must be offline, so you must shut it down before running the commands. Note that virt-sysprep modifies the guest or disk image in place without making a copy of it. If you want to preserve the existing contents of the guest virtual machine, you must snapshot, copy or clone the disk first. For more information on copying and cloning disks, see libguestfs.org.
It is recommended not to use virt-sysprep as root, unless you need root in order to access the disk image. In such a case, however, it is better to change the permissions on the disk image to be writable by the non-root user running virt-sysprep.
To install virt-sysprep, enter the following command:
# yum install /usr/bin/virt-sysprep
The following command options are available to use with virt-sysprep:

Table 21.1. virt-sysprep commands

Command Description Example
--help Displays a brief help entry about a particular command or about the virt-sysprep command. For additional help, see the virt-sysprep man page. $ virt-sysprep --help
-a [file] or --add [file] Adds the specified file, which should be a disk image from a guest virtual machine. The format of the disk image is auto-detected. To override this and force a particular format, use the --format option. $ virt-sysprep --add /dev/vms/disk.img
-a [URI] or --add [URI] Adds a remote disk. The URI format is compatible with guestfish. For more information, see Section 21.4.2, “Adding Files with guestfish”. $ virt-sysprep -a rbd://example.com[:port]/pool/disk
-c [URI] or --connect [URI] Connects to the given URI, if using libvirt. If omitted, then it connects via the KVM hypervisor. If you specify guest block devices directly (virt-sysprep -a), then libvirt is not used at all. $ virt-sysprep -c qemu:///system
-d [guest] or --domain [guest] Adds all the disks from the specified guest virtual machine. Domain UUIDs can be used instead of domain names. $ virt-sysprep --domain 90df2f3f-8857-5ba9-2714-7d95907b1c9e
-n or --dry-run Performs a read-only "dry run" sysprep operation on the guest virtual machine. This runs the sysprep operation, but throws away any changes to the disk at the end. $ virt-sysprep -n
--enable [operations] Enables the specified operations. To list the possible operations, use the --list command. $ virt-sysprep --enable ssh-hostkeys,udev-persistent-net
--operation or --operations Chooses which sysprep operations to perform. To disable an operation, use the - before the operation name. $ virt-sysprep --operations ssh-hotkeys,udev-persistent-net would enable both operations, while $ virt-sysprep --operations firewall-rules,-tmp-files would enable the firewall-rules operation and disable the tmp-files operation. For a list of valid operations, see libguestfs.org.
--format [raw|qcow2|auto] The default for the -a option is to auto-detect the format of the disk image. Using this forces the disk format for -a options that follow on the command line. Using --format auto switches back to auto-detection for subsequent -a options (see the -a command above). $ virt-sysprep --format raw -a disk.img forces raw format (no auto-detection) for disk.img, but virt-sysprep --format raw -a disk.img --format auto -a another.img forces raw format (no auto-detection) for disk.img and reverts to auto-detection for 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.
--list-operations List the operations supported by the virt-sysprep program. These are listed one per line, with one or more single-space-separated fields. The first field in the output is the operation name, which can be supplied to the --enable flag. The second field is a * character if the operation is enabled by default, or is blank if not. Additional fields on the same line include a description of the operation. $ virt-sysprep --list-operations
--mount-options Sets the mount options for each mount point in the guest virtual machine. Use a semicolon-separated list of mountpoint:options pairs. You may need to place quotes around this list to protect it from the shell. $ virt-sysprep --mount-options "/:notime" will mount the root directory with the notime operation.
-q or --quiet Prevents the printing of log messages. $ virt-sysprep -q
-v or --verbose Enables verbose messages for debugging purposes. $ virt-sysprep -v
-V or --version Displays the virt-sysprep version number and exits. $ virt-sysprep -V
--root-password Sets the root password. Can either be used to specify the new password explicitly, or to use the string from the first line of a selected file, which is more secure.
$ virt-sysprep --root-password password:123456 -a guest.img
or
$ virt-sysprep --root-password file:SOURCE_FILE_PATH -a guest.img
For more information, see the libguestfs documentation.