VIRT-V2V

Section: User Contributed Perl Documentation (1)
Updated: 2012-06-22
Index Return to Main Contents

NAME

virt-v2v - Convert a guest to use KVM

SYNOPSIS

 virt-v2v -i libvirtxml -os imported --network default guest-domain.xml

 virt-v2v -ic esx://esx.server/ -os imported --network default esx_guest

 virt-v2v -ic esx://esx.server/ \
          -o rhev -os rhev.nfs.storage:/export_domain --network rhevm \
          esx_guest

DESCRIPTION

virt-v2v converts guests from a foreign hypervisor to run on KVM, managed by libvirt or Red Hat Enterprise Virtualisation (RHEV) version 2.2 or later. It can currently convert Red Hat Enterprise Linux and Windows guests running on Xen and VMware ESX. It will enable VirtIO drivers in the converted guest if possible.

OPTIONS

-i input

Specifies what input method to use to obtain the guest for conversion. The default is "libvirt". Supported options are:

libvirt: Guest argument is the name of a libvirt domain.
libvirtxml: Guest argument is the path to an XML file containing a libvirt domain.

-ic URI

Specifies the connection to use when using the libvirt input method. If omitted, this defaults to qemu:///system when virt-v2v runs as root, or qemu:///session when virt-v2v runs as a regular user.

N.B. virt-v2v can currently automatically obtain guest storage from local libvirt connections, ESX connections, and connections over SSH. Other types of connection are not supported.

-o method

Specifies the output method. Supported output methods are:

libvirt: Create a libvirt guest. -os must specify a libvirt storage pool for the libvirt output method.
Also see the -oc option.
rhev: Create a guest on a RHEV 'Export' storage domain, which can later be imported into RHEV using the UI. -os must specify the location of a RHEV export storage domain for the RHEV output method.

: If no output type is specified, it defaults to libvirt.

-oc URI

Specifies the libvirt connection to use to create the converted guest. If omitted, this defaults to qemu:///system when virt-v2v runs as root, or qemu:///session when virt-v2v runs as a regular user.

N.B. virt-v2v must be able to write directly to storage described by this libvirt connection. This makes writing to a remote connection impractical at present.

-os storage

The output method dependent location where new storage will be created for the converted guest.

For the libvirt output method, this must be the name of a storage pool.

For the rhev output method, this specifies the NFS path to a RHEV Export storage domain. Note that the storage domain must have been previously initialised by RHEV. The domain must be in the format <host>:<path>, eg:

 rhev-storage.example.com:/rhev/export

The nfs export must be mountable and writable by the machine running virt-v2v.

-op pool

See -os for the libvirt output method.

DEPRECATED Use -os instead.

-osd domain

See -os for the rhev output method.

DEPRECATED Use -os instead.

-of format

Specifies the on-disk format which will be used for the converted guest. Currently supported options are raw and qcow2. If not specified, the converted guest will use the same format as the source guest.

-oa allocation

Specifies whether the converted guest should be sparse or preallocated. If not specified, the converted guest will use the same allocation scheme as the source.

-on outputname

Rename the guest.

If this option is not given, then the output name is the same as the input name.

--vmtype type

Specify the type of guest which will be created on a RHEV target. Options are desktop or server. If this option is not specified, a default option will be chosen based on the detected guest operating system:

Desktop

*: Fedora
*: RHEL Client/Workstation/Desktop
*: Windows XP/Vista/7

Server

*: RHEL Server/AS/ES
*: Windows 2003/2003r2/2008/2008r2

: If the guest OS is not detected as any of the above, it will default to server.

-f file | --config file

Load a virt-v2v configuration from file. Multiple configuration files can be specified, which will be searched in the order they are specified on the command line. If no configuration is specified, defaults to /etc/virt-v2v.conf and /var/lib/virt-v2v/virt-v2v.db in that order.

When overriding the default config file it is recommended that /var/lib/virt-v2v/virt-v2v.db is also specified, as it contains default configuration data required for conversions.

-n network | --network network

Map all guest bridges or networks which don't have a mapping in the configuration file to network.

This option cannot be used in conjunction with --bridge.

-b bridge | --bridge bridge

Map all guest bridges or networks which don't have a mapping in the configuration file to bridge.

This option cannot be used in conjunction with --network.

-p profile | --profile profile

Take default values for output method, output storage and network mappings from profile in the configuration file.

--root=ask

--root=single

--root=first

--root=/dev/sdX

Choose the root filesystem to be converted.

In the case where the virtual machine is dual-boot or multi-boot, or where the VM has other filesystems that look like operating systems, this option can be used to select the root filesystem (a.k.a. ``C: drive'' or ``/'') of the operating system that is to be converted. The Windows Recovery Console, certain attached DVD drives, and bugs in libguestfs inspection heuristics, can make a guest look like a multi-boot operating system.

The default in virt-v2v X 0.7.1 was --root=single, which causes virt-v2v to die if a multi-boot operating system is found.

Since virt-v2v X 0.7.2 the default is now --root=ask: If the VM is found to be multi-boot, then virt-v2v will stop and list the possible root filesystems and ask the user which to use. This requires that virt-v2v is run interactively.

--root=first means to choose the first root device in the case of a multi-boot operating system. Since this is a heuristic, it may sometimes choose the wrong one.

You can also name a specific root device, eg. --root=/dev/sda2 would mean to use the second partition on the first hard drive. If the named root device does not exist or was not detected as a root device, then virt-v2v will fail.

Note that there is a bug in grub which prevents it from successfully booting a multiboot system if VirtIO is enabled. Grub is only able to boot an operating system from the first VirtIO disk. Specifically, /boot must be on the first VirtIO disk, and it cannot chainload an OS which is not in the first VirtIO disk.

--list-profiles

Display a list of target profile names specified in the configuration file.

--help

Display brief help.

--version

Display version number and exit.

PREPARING TO CONVERT A GUEST

Local storage requirements

Whenever possible, virt-v2v copies a guest's storage directly from the source hypervisor to the target hypervisor without using any local storage. However, this is not possible in all circumstances. Specifically when transferring a guest's storage over SSH and also either doing a format conversion, or changing the allocation policy of qcow2 storage, virt-v2v will cache a local copy of the guest's storage. By default, this local cache will be created in /tmp. If /tmp does not have sufficient storage space, it can be written to another directory by setting the TMPDIR environment variable.

Local Xen guests

N.B. The following is required when converting guests on a host which used to run Xen, but has been updated to run KVM. It is not required when converting a Xen guest imported directly from a running libvirt/Xen instance.

virt-v2v uses a libvirt domain description to determine the current configuration of the guest, including the location of its storage. This should be obtained from the host running the guest pre-conversion by running:

 virsh dumpxml <domain> > <domain>.xml

This will require a reboot if the host running Xen is the same host that will run KVM. This is because libvirt needs to connect to a running xen hypervisor to obtain its metadata.

Converting to run on libvirt/KVM

Create a local storage pool for transferred storage

virt-v2v copies the guest storage to the local machine during import. When converting to run on libvirt, it creates new storage in a locally defined libvirt pool. This pool can be defined using any libvirt tool, and can be of any type.

The simplest way to create a new pool is with virt-manager(1). Pools can be defined from the Storage tab under Host Details.

Create local network interfaces

The local machine must have an appropriate network for the converted guest to connect to. This is likely to be a bridge interface. A bridge interface can be created using standard tools on the host.

Since version 0.8.3, virt-manager(1) can also create and manage bridges.

Converting to run on RHEV

Create an NFS export domain

virt-v2v can convert guests to run on RHEV 2.2 or later. It does this by writing the converted guest directly to an 'Export' NFS storage domain. The guest can later be imported into a RHEV Data Center through the UI.

In RHEV 2.2, a new Export storage domain is created by clicking on 'New Domain' in the Storage tab. Ensure that the Domain function is 'Export' and the Storage type is 'NFS'. See the RHEV documentation for details. The NFS storage domain must be mountable by the machine running virt-v2v.

N.B. When exporting to RHEV, virt-v2v must run as root.

Import the appropriate Guest Tools ISO

When converting Windows guests, it is strongly recommended that the Guest Tools ISO is installed before the guest is converted. This must be done using the ISO Uploader, which can be found on your RHEV-M system under Start->Red Hat->RHEV Manager->ISO Uploader. This will allow RHEV to automatically update the guest's drivers to the latest versions and install any required agents.

CONVERTING A LOCAL XEN GUEST

The following requires that the domain XML is available locally, and that the storage referred to in the domain XML is available locally at the same paths.

To perform the conversion, run:

 virt-v2v -i libvirtxml -os <pool> [--network <network name>] \
          <domain>.xml

where "<domain>.xml" is the path to the exported guest domain's xml, and "<pool>" is the local storage pool where copies of the guest's disks will be created.

The --network option may be provided for simple network mappings. For more complex mappings, see virt-v2v.conf(5).

If it is not possible to provide software updates over the network in your environment, software will be installed as specified in virt-v2v.conf. See virt-v2v.conf(5) for a details.

It is possible to avoid specifying replacement kernels in the virt-v2v config file by ensuring that the guest has an appropriate kernel installed prior to conversion. If your guest uses a Xen paravirtualised kernel (it would be called something like kernel-xen or kernel-xenU), you can install a regular kernel, which won't reference a hypervisor in its name, alongside it. You shouldn't make this newly installed kernel your default kernel because Xen may not boot it. virt-v2v will make it the default during conversion.

CONVERTING A GUEST FROM VMWARE ESX

N.B. libvirt version 0.7.0 or greater is required to connect to ESX.

virt-v2v can convert a guest from VMware ESX, including transferring its storage.

N.B. virt-v2v does not transfer snapshots from ESX. Only the latest flat storage is transferred.

The guest MUST be shut down in ESX before conversion starts. virt-v2v will not proceed if the guest is still running. To convert the guest, run:

 virt-v2v -ic esx://<esx.server>/ -os <pool> [--network <network name>] \
          <domain>

where:

*: <esx.server> is the hostname of the ESX server hosting the guest to be converted.
N.B. This hostname must match the hostname reported in the ESX server's SSL certificate, or verification will fail.
*: <pool> is the name of the local storage pool where copies of the guest's storage will be created.
*: <domain> is the name of the guest on the ESX server which is to be converted.

The --network option may be provided for simple network mappings. For more complex mappings, see virt-v2v.conf(5).

Authenticating to the ESX server

Connecting to the ESX server will require authentication. virt-v2v supports password authentication when connecting to ESX. It reads passwords from $HOME/.netrc. The format of this file is described in netrc(5). An example entry is:

 machine esx01.example.com login root password s3cr3t

N.B. The permissions of .netrc MUST be set to 0600, or it will be ignored.

Connecting to an ESX server with an invalid certificate

In non-production environments, the ESX server may have an invalid certificate, for example a self-signed certificate. In this case, certificate checking can be explicitly disabled by adding '?no_verify=1' to the connection URI as shown below:

 ... -ic esx://<esx.server>/?no_verify=1 ...

EXPORTING A GUEST TO RHEV

virt-v2v can export to RHEV any guest that it can convert. This includes:

*: Local Xen guests
*: ESX guests
*: Local libvirt/KVM guests

To export to RHEV, specify -o rhev on the command line, and ensure -os specifies the location of a RHEV export storage domain as in the following examples:

Exporting a local Xen guest to RHEV

 virt-v2v -i libvirtxml -o rhev -os <export_sd> \
          [--network <network name>] <domain>.xml

Export a VMWare ESX guest to RHEV

 virt-v2v -ic esx://<esx.server>/ -o rhev -os <export_sd> \
          [--network <network name>] <domain>

Export a local libvirt/KVM guest to RHEV

 virt-v2v -o rhev -os <export_sd> [--network <network name>] \
          <domain>

RUNNING THE CONVERTED GUEST

Libvirt output method

On successful completion, virt-v2v will create a new libvirt domain for the converted guest with the same name as the original guest. It can be started as usual using libvirt tools, for example virt-manager(1).

RHEV output method

On successful completion virt-v2v will have written the new guest to the export storage domain, but it will not yet be ready to run. It must be imported into RHEV using the UI before it can be used.

In RHEV 2.2 this is done from the Storage tab. Select the export domain the guest was written to. A pane will appear underneath the storage domain list displaying several tabs, one of which is 'VM Import'. The converted guest will be listed here. Select the appropriate guest an click 'Import'. See the RHEV documentation for additional details.

POST-CONVERSION TASKS

Guest network configuration

virt-v2v cannot currently reconfigure a guest's network configuration. If the converted guest is not connected to the same subnet as the source, its network configuration may have to be updated.

Converting a Windows guest

When converting a Windows guests, the conversion process is split into 2 stages:

1.: Offline conversion.
2.: First boot.

The guest will be bootable after the offline conversion stage, but will not yet have all necessary drivers installed to work correctly. These will be installed automatically the first time the guest boots.

N.B. Take care not to interrupt the automatic driver installation process when logging in to the guest for the first time, as this may prevent the guest from subsequently booting correctly.

Windows Recovery Console

virt-v2v does not support conversion of the Windows Recovery Console. If a guest has a recovery console installed and VirtIO was enabled during conversion, attempting to boot the recovery console will result in a BSOD.

Windows XP x86 does not support the Windows Recovery Console on VirtIO systems, so there is no resolution to this. However, on Windows XP AMD64 and Windows 2003 (x86 and AMD64), the recovery console can be re-installed after conversion. The re-installation procedure is the same as the initial installation procedure. It is not necessary to remove the recovery console first. Following re-installation, the recovery console will work as intended.

GUEST CONFIGURATION CHANGES

As well as configuring libvirt appropriately, virt-v2v will make certain changes to a guest to enable it support running under a KVM host either with or without virtio driver. These changes are guest OS specific. Currently only Red Hat based Linux distributions are supported.

Linux

virt-v2v will make the following changes to a Linux guest:

Kernel: Un-bootable, i.e. xen paravirtualised, kernels will be uninstalled. No new kernel will be installed if there is a remaining kernel which supports virtio. If no remaining kernel supports virtio and the configuration file specifies a new kernel it will be installed and configured as the default.
X reconfiguration: If the guest has X configured, its display driver will be updated. See ``GUEST DRIVERS'' for which driver will be used.
Rename block devices: If changes have caused block devices to change name, these changes will be reflected in /etc/fstab.
Configure device drivers: Whether virtio or non-virtio drivers are configured, virt-v2v will ensure that the correct network and block drivers are specified in the modprobe configuration.
initrd: virt-v2v will ensure that the initrd for the default kernel supports booting the root device, whether it is using virtio or not.
SELinux: virt-v2v will initiate a relabel of the guest on the next boot. This ensures that any changes it has made are correctly labelled according to the guest's local policy.

LINUX GUEST DRIVERS

Virt-v2v will configure the following drivers in a Linux guest:

VirtIO

 X display      cirrus
 Block          virtio_blk
 Network        virtio_net

Additionally, initrd will preload the virtio_pci driver.

Non-VirtIO

 X display      cirrus
 Block          IDE
 Network        e1000

WINDOWS GUEST DRIVERS

Virt-v2v will configure the following drivers in a Windows guest:

VirtIO

 X display      cirrus
 Block          viostor
 Network        netkvm

Non-VirtIO

 X display      cirrus
 Block          IDE
 Network        rtl8139

BUGS

To get a list of bugs against virt-v2v use this link:

<https://bugzilla.redhat.com/buglist.cgi?component=virt-v2v&product=Virtualization+Tools>

To report a new bug against virt-v2v use this link:

<https://bugzilla.redhat.com/enter_bug.cgi?component=virt-v2v&product=Virtualization+Tools>

When reporting a bug, please check:

*: That the bug hasn't been reported already.
*: That you are testing a recent version.
*: Describe the bug accurately, and give a way to reproduce it.

AUTHOR

Richard W.M. Jones <http://et.redhat.com/~rjones/>

Matthew Booth <mbooth@redhat.com>

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.