16.12. 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, persistent network MAC configuration, and 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.
The term "sysprep" is derived from the System Preparation tool (sysprep.exe) which is used with the Microsoft Windows systems. Despite this, the tool does not currently work on Windows guests.

Note

libguestfs and guestfish do not require root privileges. You only need to run them as root if the disk image being accessed needs root access to read or write or both.
The virt-sysprep tool is part of the libguestfs-tools-c package, which is installed with the following command:
$ yum install libguestfs-tools-c
Alternatively, just the virt-sysprep tool can be installed with the following command:
$ yum install /usr/bin/virt-sysprep

Important

virt-sysprep modifies the guest or disk image in place. To use virt-sysprep, the guest virtual machine must be offline, so you must shut it down before running the commands. To preserve the existing contents of the guest virtual machine, you must snapshot, copy or clone the disk first. Refer to libguestfs.org for more information on copying and cloning disks.
The following commands are available to use with virt-sysprep:

Table 16.1. virt-sysprep commands

Command Description Example
--help Displays a brief help entry about a particular command or about the whole package. 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
-c [URI] or --connect [URI] Connects to the given URI, if using libvirt. If omitted, it will connect 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 or --dryrun 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-hotkeys,udev-persistent-net
--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 which 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 Lists 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.
--selinux-relabel and --no-selinux-relabel virt-sysprep does not always schedule a SELinux relabelling at the first boot of the guest. In some cases, a relabel is performed (for example, when virt-sysprep has modified files). However, when all operations only remove files (for example, when using --enable delete --delete /some/file) no relabelling is scheduled. Using the --selinux-relabel option always forces SELinux relabelling, while with --no-selinux-relabel set, relabelling is never scheduled. It is recommended to use --selinux-relabel to ensure that files have the correct SELinux labels. $ virt-sysprep --selinux-relabel
-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, refer to the libguestfs documentation.