virt-v2v

Langue: en

Version: 2010-07-01 (fedora - 01/12/10)

Section: 1 (Commandes utilisateur)

NAME

virt-v2v - Convert a guest to use KVM

SYNOPSIS

  virt-v2v -f virt-v2v.conf -i libvirtxml -op transfer guest-domain.xml
 
  virt-v2v -f virt-v2v.conf -ic esx://esx.server/ -op transfer esx_guest
 
  virt-v2v -f virt-v2v.conf -ic esx://esx.server/ \
           -o rhev -osd rhev.nfs.storage:/export_domain guest 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 Fedora 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.

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.

-it method
Specifies the transport method used to obtain raw storage from the source guest. This is currently only a placeholder, and does nothing.
-o method
Specifies the output method. Supported output methods are:
libvirt
Create a libvirt guest. See the -oc and -op options. -op must be specified for the libvirt output method.
rhev
Create a guest on a RHEV 'Export' storage domain, which can later be imported into RHEV using the UI. -osd must be specified 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 ommitted, this defaults to qemu:///system.

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.

-op pool
Specifies the pool which will be used to create new storage for the converted guest.
-osd domain
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.

-f file | --config file
Load the virt-v2v configuration from file. Defaults to /etc/virt-v2v.conf if it exists;
-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.

--help
Display brief help.
--version
Display version number and exit.

PREPARING TO CONVERT A GUEST

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.

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 -f virt-v2v.conf -i libvirtxml -op <pool> <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. See virt-v2v.conf(5) for a details of virt-v2v.conf.

If it is not possible to provide software updates over the network in your environment, it is still 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 -f virt-v2v.conf -ic esx://<esx.server>/ -op <pool> <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.

See virt-v2v.conf(5) for a details of virt-v2v.conf.

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 -osd <export_sd> ...
 
 

on the command line in place of -op as in the following examples:

Exporting a local Xen guest to RHEV
virt-v2v -f virt-v2v.conf -i libvirtxml -o rhev -osd <export_sd> <domain>.xml
Export a VMWare ESX guest to RHEV
virt-v2v -f virt-v2v.conf -ic esx://<esx.server>/ -o rhev -osd <export_sd> <domain>
Export a local libvirt/KVM guest to RHEV
virt-v2v -f virt-v2v.conf -o rhev -osd <export_sd> <domain>

See virt-v2v.conf(5) for details of virt-v2v.conf.

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.

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.

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
 
 

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 <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 <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.

SEE ALSO

virt-v2v.conf(5), virt-manager(1), <http://libguestfs.org/>.

AUTHOR

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

Matthew Booth <mbooth@redhat.com>

Copyright (C) 2009,2010 Red Hat Inc.

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., 675 Mass Ave, Cambridge, MA 02139, USA.