VIRT-V2V(1) User Contributed Perl Documentation VIRT-V2V(1)NAMEvirt-v2v - Convert a guest to use KVM
SYNOPSISvirt-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
DESCRIPTIONvirt-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, VirtualBox, 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.
ova Guest argument is the path to a VMware-exported OVA file.
-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.
Local VirtualBox guests
The following is required when converting guests which used to run
VirtualBox and are being converted to KVM. The conversion needs a guest
XML definition file which needs to be adjusted for the guest to be
converted (at least name, uuid, image path, image type, and MAC
address):
qemu-img convert -O qcow2 /tmp/v-rhel.vdi /var/lib/libvirt/images/v-rhel.img
virsh --connect qemu:///system pool-refresh default
virt-cat /var/lib/libvirt/images/v-rhel.img \
/etc/sysconfig/network-scripts/ifcfg-eth0 | grep ^HWADDR
# Replace the MAC address in the guest XML definition file or adjust
# ifcfg-eth0 after booting up the guest to match the MAC address defined in
# XML file
virt-v2v-i libvirtxml -os default /tmp/v-rhel.xml
N.B. For the time being when converting VirtualBox Windows guests the
VirtualBox Guest Additions need to be manually uninstalled on the guest
when still running on VirtualBox.
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 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 RHEVvirt-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.
SEE ALSOvirt-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
Copyright (C) 2009-2012 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.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
perl v5.10.1 2013-11-21 VIRT-V2V(1)
