Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

21.12. virt-customize: Customizing Virtual Machine Settings

The virt-customize command-line tool can be used to customize a virtual machine. For example, by installing packages and editing configuration files.
To use virt-customize, the guest virtual machine must be offline, so you must shut it down before running the commands. Note that virt-customize 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.

Warning

Using virt-customize on live virtual machines, or concurrently with other disk editing tools can cause disk corruption. The virtual machine must be shut down before using this command. In addition, disk images should not be edited concurrently.
It is recommended that you do not run virt-customize as root.
To install virt-customize, run one of the following commands: 
# yum install /usr/bin/virt-customize
or 
# yum install libguestfs-tools-c
The following command options are available to use with virt-customize:

Table 21.2. virt-customize options

Command Description Example
--help Displays a brief help entry about a particular command or about the virt-customize utility. For additional help, see the virt-customize man page. virt-customize --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-customize --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-customize -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-customize -a), then libvirt is not used at all. virt-customize -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-customize --domain 90df2f3f-8857-5ba9-2714-7d95907b1c9e
-n or --dry-run Performs a read-only "dry run" customize operation on the guest virtual machine. This runs the customize operation, but throws away any changes to the disk at the end. virt-customize -n
--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-customize --format raw -a disk.img forces raw format (no auto-detection) for disk.img, but virt-customize --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.
-m [MB] or --memsize [MB] Changes the amount of memory allocated to --run scripts. If --run scripts or the --install option cause out of memory issues, increase the memory allocation. virt-customize --memsize 1024
--network or --no-network Enables or disables network access from the guest during installation. The default is enabled. Use --no-network to disable access. This command does not affect guest access to the network after booting. For more information, see libguestfs documentation. virt-customize -a http://[user@]example.com[:port]/disk.img
-q or --quiet Prevents the printing of log messages. virt-customize -q
-smp [N] Enables N virtual CPUs that can be used by --install scripts. N must be 2 or more. virt-customize -smp 4
-v or --verbose Enables verbose messages for debugging purposes. virt-customize --verbose
-V or --version Displays the virt-customize version number and exits. virt-customize --V
-x Enables tracing of libguestfs API calls. virt-customize -x
The virt-customize command uses customization options to configure how the guest is customized. The following provides information about the --selinux-relabel customization option.
The --selinux-relabel customization option relabels files in the guest so that they have the correct SELinux label. This option tries to relabel files immediately. If unsuccessful, /.autorelabel is activated on the image. This schedules the relabel operation for the next time the image boots.

Note

This option should only be used for guests that support SELinux.
The following example installs the GIMP and Inkscape packages on the guest and and ensures that the SELinux labels will be correct the next time the guest boots.

Example 21.1. Using virt-customize to install packages on a guest

virt-customize -a disk.img --install gimp,inkscape --selinux-relabel
For more information, including customization options, see libguestfs.org.