virt-sysprep

List all supported operations (enabled operations are indicated with asterisks)

$ virt-sysprep --list-operations

$ sudo virt-sysprep [[-a|--add]] [path/to/image.qcow2]

$ sudo virt-sysprep [[-d|--domain]] [vm_name] [[-n|--dry-run]]

$ sudo virt-sysprep [[-d|--domain]] [vm_name] --operations [operation1,operation2,...]

$ sudo virt-sysprep [[-d|--domain]] [vm_name] --enable [customizations] --hostname [host_name] --operation [machine-id]

$ virt-sysprep [[-he|--help]]

virt-sysprep [OPTION...] -a DISK_IMAGE
virt-sysprep [OPTION...] --add DISK_IMAGE
virt-sysprep [OPTION...] -d GUEST_NAME
virt-sysprep [OPTION...] --domain GUEST_NAME

-a DISK_IMAGE, --add DISK_IMAGE
    Specifies the path to the guest disk image to be modified. The VM must be shut down or the disk detached.

-d GUEST_NAME, --domain GUEST_NAME
    Specifies the name of the libvirt guest whose disk image will be modified. The guest must be shut down.

--enable OPERATION[,...]
    Enables specific system preparation operations (e.g., ssh-hostkeys, network-configuration). Use --list-operations to see all available operations.

--operations FILE
    Reads sysprep operations and their arguments from a specified FILE, allowing complex or repeatable setups.

--ssh-inject USER:KEY_FILE
    Injects an SSH public key from KEY_FILE into the specified USER's ~/.ssh/authorized_keys within the guest.

--root-password PASSWORD_FILE
    Sets the root user's password using the content from PASSWORD_FILE (can be a plain text password or hashed).

--hostname HOSTNAME
    Sets the guest operating system's hostname to the specified HOSTNAME.

--run SCRIPT
    Executes a shell SCRIPT within the guest environment after all other sysprep operations are completed.

--delete /PATH
    Deletes a file or directory located at /PATH inside the guest filesystem.

--upload FILE:PATH
    Uploads a FILE from the host filesystem to a specific PATH within the guest filesystem.

--network
    Resets the network configuration of the guest, typically setting it to use DHCP for the primary network interface.

--timezone TIMEZONE
    Sets the guest operating system's timezone (e.g., 'America/New_York').

-v, --verbose
    Displays verbose output, showing more details about the operations being performed.

virt-sysprep is a command-line tool that modifies a virtual machine's disk image offline to prepare it for cloning and deployment as a template. It removes machine-specific identifiers and data that would cause conflicts if multiple VMs were deployed from the same image without modification.

This includes deleting SSH host keys, UIDs, machine IDs, user histories, DHCP client leases, and other unique system information. Beyond cleaning, virt-sysprep can also perform customization tasks, such as adding SSH public keys, resetting root passwords, configuring networking, and executing custom shell scripts or virt-sysprep operations from a file. This ensures that new instances cloned from the prepared image are unique and ready for initial boot without manual intervention, making it an essential tool for automated VM provisioning in cloud and virtualization environments. It utilizes the libguestfs library to safely access and modify the guest filesystem.

Requires the libguestfs library and associated tools to be installed.
Operates only on offline disk images; the virtual machine associated with the image must not be running.
Modifies the disk image directly and irreversibly; it is highly recommended to back up the image before running virt-sysprep.
Requires root privileges to access and modify disk images or libvirt domains.

When no specific operations are enabled with --enable or --operations, virt-sysprep runs a default set of clean-up tasks. These typically include removing SSH host keys, user history, DHCP client state, machine IDs, log files, package manager caches, and other unique identifiers that could cause conflicts when cloning. Users should be aware of these automatic actions.

A crucial aspect of virt-sysprep is that it always operates on an offline disk image. This means the virtual machine must be shut down or its disk detached before virt-sysprep can modify it. This design ensures data consistency and prevents conflicts with a running operating system.

virt-sysprep emerged as part of the broader libguestfs project, which began development around 2008-2009. Its purpose was to provide a robust, programmatic, and secure way to generalize Linux virtual machine images, mirroring the functionality of Microsoft's Sysprep for Windows. By leveraging libguestfs, it can directly manipulate guest filesystems without booting the VM, making it a powerful tool for automated VM provisioning and template management in virtualization and cloud environments.

virt-install(1), virt-builder(1), virt-customize(1), guestfish(1), libguestfs(3), virsh(1)