mirrors/libguestfs
1
0
Fork 0
mirror of https://github.com/libguestfs/libguestfs.git synced 2026-03-21 22:53:37 +00:00
Code Issues Packages Projects Releases Wiki Activity

v2v: Split up huge manual page into smaller pages.

Browse Source 
The primary virt-v2v(1) page now contains a more concise overview of
virt-v2v, along with things like detailed options documentation which
we would expect in a tool manual.

The documentation for VMware, Xen, local output, oVirt and OpenStack
has been moved to new pages where it is introduced in a more narrative
/ tutorial style.  The idea is that people who are interested in
converting from or to these sources will be able to start at
virt-v2v(1) for an overview before moving to one of these new pages
for a friendlier introduction to the topic.

The support matrix has also been moved to a new page called
virt-v2v-support(1).  The idea is that downstream packagers will be
more easily able to modify or completely replace this page according
to their support requirements.

When rewriting the VMware documentation, I dropped the section
"INPUT FROM VMWARE ESXi HYPERVISOR" which discussed using
virt-v2v-copy-to-local.  This should no longer be necessary since you
can use SSH or VDDK.  (See also previous commit).
This commit is contained in:
Richard W.M. Jones
2018-11-01 14:15:47 +00:00
parent 3dfce4b5bb
commit 6d3b9a2812
18 changed files with 1758 additions and 1406 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
.gitignore vendored
View File

@@ -683,8 +683,7 @@ Makefile.in
/v2v/real-*.d/
/v2v/real-*.img
/v2v/real-*.xml
/v2v/stamp-virt-v2v.pod
/v2v/stamp-virt-v2v-copy-to-local.pod
/v2v/stamp-virt-v2v*.pod
/v2v/test-harness/.depend
/v2v/test-harness/META
/v2v/test-harness/stamp-virt-v2v-test-harness.pod
@@ -697,6 +696,12 @@ Makefile.in
/v2v/virt-v2v.1
/v2v/virt-v2v-copy-to-local
/v2v/virt-v2v-copy-to-local.1
/v2v/virt-v2v-input-vmware.1
/v2v/virt-v2v-input-xen.1
/v2v/virt-v2v-output-local.1
/v2v/virt-v2v-output-openstack.1
/v2v/virt-v2v-output-rhv.1
/v2v/virt-v2v-support.1
/v2v/windows.vmdk
/website/*.html
/website/README.txt

4
p2v/virt-p2v.pod
View File

@@ -63,7 +63,7 @@ The conversion server does not need to be a physical machine. It
could be a virtual machine, as long as it has sufficient memory and
disk space to do the conversion, and as long as the physical machine
can connect directly to its SSH port. (See also
L<virt-v2v(1)/RESOURCE REQUIREMENTS>).
L<virt-v2v(1)/Resource requirements>).
Because all of the data on the physical server’s hard drive(s) has to
be copied over the network, the speed of conversion is largely
@@ -230,7 +230,7 @@ the drives are I<not> copied over.
In the Network interfaces panel, select the network interfaces that
should be created in the guest after conversion. You can also connect
these to target hypervisor networks (for further information about
this feature, see L<virt-v2v(1)/NETWORKS AND BRIDGES>).
this feature, see L<virt-v2v(1)/Networks and bridges>).
On supported hardware, left-clicking on the device name (eg. C<em1>)
causes a light to start flashing on the physical interface, allowing

7
po-docs/language.mk
View File

@@ -82,6 +82,13 @@ MANPAGES = \
virt-tar-in.1 \
virt-tar-out.1 \
virt-v2v.1 \
virt-v2v-copy-to-local.1 \
virt-v2v-input-vmware.1 \
virt-v2v-input-xen.1 \
virt-v2v-output-local.1 \
virt-v2v-output-openstack.1 \
virt-v2v-output-rhv.1 \
virt-v2v-support.1 \
virt-v2v-test-harness.1 \
virt-win-reg.1

6
po-docs/podfiles
View File

@@ -76,4 +76,10 @@
../utils/boot-benchmark/boot-benchmark.pod
../v2v/test-harness/virt-v2v-test-harness.pod
../v2v/virt-v2v-copy-to-local.pod
../v2v/virt-v2v-input-vmware.pod
../v2v/virt-v2v-input-xen.pod
../v2v/virt-v2v-output-local.pod
../v2v/virt-v2v-output-openstack.pod
../v2v/virt-v2v-output-rhv.pod
../v2v/virt-v2v-support.pod
../v2v/virt-v2v.pod

92
v2v/Makefile.am
View File

@@ -37,7 +37,13 @@ EXTRA_DIST = \
rhv-upload-precheck.py \
v2v_unit_tests.ml \
virt-v2v.pod \
virt-v2v-copy-to-local.pod
virt-v2v-copy-to-local.pod \
virt-v2v-input-vmware.pod \
virt-v2v-input-xen.pod \
virt-v2v-output-local.pod \
virt-v2v-output-openstack.pod \
virt-v2v-output-rhv.pod \
virt-v2v-support.pod
SOURCES_MLI = \
changeuid.mli \
@@ -281,11 +287,25 @@ virttoolsdatadir = $(datadir)/virt-tools
# Manual pages and HTML files for the website.
man_MANS = virt-v2v.1 virt-v2v-copy-to-local.1
man_MANS = \
virt-v2v.1 \
virt-v2v-copy-to-local.1 \
virt-v2v-input-vmware.1 \
virt-v2v-input-xen.1 \
virt-v2v-output-local.1 \
virt-v2v-output-openstack.1 \
virt-v2v-output-rhv.1 \
virt-v2v-support.1
noinst_DATA = \
$(top_builddir)/website/virt-v2v.1.html \
$(top_builddir)/website/virt-v2v-copy-to-local.1.html
$(top_builddir)/website/virt-v2v-copy-to-local.1.html \
$(top_builddir)/website/virt-v2v-input-vmware.1.html \
$(top_builddir)/website/virt-v2v-input-xen.1.html \
$(top_builddir)/website/virt-v2v-output-local.1.html \
$(top_builddir)/website/virt-v2v-output-openstack.1.html \
$(top_builddir)/website/virt-v2v-output-rhv.1.html \
$(top_builddir)/website/virt-v2v-support.1.html
virt-v2v.1 $(top_builddir)/website/virt-v2v.1.html: stamp-virt-v2v.pod
@@ -309,6 +329,72 @@ stamp-virt-v2v-copy-to-local.pod: virt-v2v-copy-to-local.pod
$<
touch $@
virt-v2v-input-vmware.1 $(top_builddir)/website/virt-v2v-input-vmware.1.html: stamp-virt-v2v-input-vmware.pod
stamp-virt-v2v-input-vmware.pod: virt-v2v-input-vmware.pod
$(PODWRAPPER) \
--man virt-v2v-input-vmware.1 \
--html $(top_builddir)/website/virt-v2v-input-vmware.1.html \
--license GPLv2+ \
--warning safe \
$<
touch $@
virt-v2v-input-xen.1 $(top_builddir)/website/virt-v2v-input-xen.1.html: stamp-virt-v2v-input-xen.pod
stamp-virt-v2v-input-xen.pod: virt-v2v-input-xen.pod
$(PODWRAPPER) \
--man virt-v2v-input-xen.1 \
--html $(top_builddir)/website/virt-v2v-input-xen.1.html \
--license GPLv2+ \
--warning safe \
$<
touch $@
virt-v2v-output-local.1 $(top_builddir)/website/virt-v2v-output-local.1.html: stamp-virt-v2v-output-local.pod
stamp-virt-v2v-output-local.pod: virt-v2v-output-local.pod
$(PODWRAPPER) \
--man virt-v2v-output-local.1 \
--html $(top_builddir)/website/virt-v2v-output-local.1.html \
--license GPLv2+ \
--warning safe \
$<
touch $@
virt-v2v-output-openstack.1 $(top_builddir)/website/virt-v2v-output-openstack.1.html: stamp-virt-v2v-output-openstack.pod
stamp-virt-v2v-output-openstack.pod: virt-v2v-output-openstack.pod
$(PODWRAPPER) \
--man virt-v2v-output-openstack.1 \
--html $(top_builddir)/website/virt-v2v-output-openstack.1.html \
--license GPLv2+ \
--warning safe \
$<
touch $@
virt-v2v-output-rhv.1 $(top_builddir)/website/virt-v2v-output-rhv.1.html: stamp-virt-v2v-output-rhv.pod
stamp-virt-v2v-output-rhv.pod: virt-v2v-output-rhv.pod
$(PODWRAPPER) \
--man virt-v2v-output-rhv.1 \
--html $(top_builddir)/website/virt-v2v-output-rhv.1.html \
--license GPLv2+ \
--warning safe \
$<
touch $@
virt-v2v-support.1 $(top_builddir)/website/virt-v2v-support.1.html: stamp-virt-v2v-support.pod
stamp-virt-v2v-support.pod: virt-v2v-support.pod
$(PODWRAPPER) \
--man virt-v2v-support.1 \
--html $(top_builddir)/website/virt-v2v-support.1.html \
--license GPLv2+ \
--warning safe \
$<
touch $@
# Tests.
# The virt-v2v tests here are not meant to be thorough tests of guest

2
v2v/convert_linux.ml
View File

@@ -490,7 +490,7 @@ let convert (g : G.guestfs) inspect source output rcaps =
fun { ki_is_xen_pv_only_kernel = pv_only } -> pv_only
) bootloader_kernels in
if only_xen_kernels then
error (f_"only Xen kernels are installed in this guest.\n\nRead the %s(1) manual, section \"XEN PARAVIRTUALIZED GUESTS\", to see what to do.") prog;
error (f_"only Xen kernels are installed in this guest.\n\nRead the %s(1) manual, section \"Xen paravirtualized guests\", to see what to do.") prog;
(* Enable the best non-Xen kernel, where "best" means the one with
* the highest version, preferring non-debug kernels which support

14
v2v/input_libvirt_vddk.ml
View File

@@ -118,21 +118,21 @@ class input_libvirt_vddk input_conn input_password vddk_options parsed_uri
| None -> ()
| Some libdir ->
if not (is_directory libdir) then
error (f_"‘-io vddk-libdir=%s’ does not point to a directory. See \"INPUT FROM VDDK\" in the virt-v2v(1) manual.") libdir
error (f_"‘-io vddk-libdir=%s’ does not point to a directory. See the virt-v2v-input-vmware(1) manual.") libdir
);
(match library_path with
| None -> ()
| Some library_path ->
if not (is_directory library_path) then
error (f_"VDDK library path %s not found or not a directory. See \"INPUT FROM VDDK\" in the virt-v2v(1) manual.") library_path
error (f_"VDDK library path %s not found or not a directory. See the virt-v2v-input-vmware(1) manual.") library_path
)
in
(* Check that nbdkit is available and new enough. *)
let error_unless_nbdkit_working () =
if 0 <> Sys.command "nbdkit --version >/dev/null" then
error (f_"nbdkit is not installed or not working. It is required to use ‘-it vddk’. See \"INPUT FROM VDDK\" in the virt-v2v(1) manual.");
error (f_"nbdkit is not installed or not working. It is required to use ‘-it vddk’. See the virt-v2v-input-vmware(1) manual.");
(* Check it's a new enough version. The latest features we
* require are ‘--exit-with-parent’ and ‘--selinux-label’, both
@@ -169,19 +169,19 @@ class input_libvirt_vddk input_conn input_password vddk_options parsed_uri
The VDDK plugin is not enabled by default when you compile nbdkit. You have to read the instructions in the nbdkit sources under ‘plugins/vddk/README.VDDK’ to find out how to enable the VDDK plugin.
See also \"INPUT FROM VDDK\" in the virt-v2v(1) manual.")
See also the virt-v2v-input-vmware(1) manual.")
else
error (f_"nbdkit VDDK plugin is not installed or not working. It is required if you want to use VDDK.
It looks like you did not set the right path in the ‘-io vddk-libdir’ option, or your copy of the VDDK directory is incomplete. There should be a library called ’<libdir>/%s/libvixDiskLib.so.?’.
See also \"INPUT FROM VDDK\" in the virt-v2v(1) manual.") libNN
See also the virt-v2v-input-vmware(1) manual.") libNN
)
in
let error_unless_thumbprint () =
if not (List.mem_assoc "thumbprint" vddk_options) then
error (f_"You must pass the ‘-io vddk-thumbprint’ option with the SSL thumbprint of the VMware server. To find the thumbprint, see the nbdkit-vddk-plugin(1) manual. See also \"INPUT FROM VDDK\" in the virt-v2v(1) manual.")
error (f_"You must pass the ‘-io vddk-thumbprint’ option with the SSL thumbprint of the VMware server. To find the thumbprint, see the nbdkit-vddk-plugin(1) manual. See also the virt-v2v-input-vmware(1) manual.")
in
(* Check that nbdkit was compiled with SELinux support (for the
@@ -274,7 +274,7 @@ object
error (f_"‘-ic %s’ URL does not contain a host name field")
input_conn
| None ->
error (f_"you must use the ‘-ic’ parameter. See \"INPUT FROM VDDK\" in the virt-v2v(1) manual.") in
error (f_"you must use the ‘-ic’ parameter. See the virt-v2v-input-vmware(1) manual.") in
(* Similar to above, we also need a username to pass. *)
let user =

8
v2v/output_libvirt.ml
View File

@@ -106,13 +106,13 @@ class output_libvirt oc output_pool = object
(* We can only output to a pool of type 'dir' (directory). *)
if xpath_string "/pool/@type" <> Some "dir" then
error (f_"-o libvirt: output pool ‘%s’ is not a directory (type='dir'). See virt-v2v(1) section \"OUTPUT TO LIBVIRT\"") output_pool;
error (f_"-o libvirt: output pool ‘%s’ is not a directory (type='dir'). See virt-v2v-output-local(1)") output_pool;
let target_path =
match xpath_string "/pool/target/path/text()" with
| None ->
error (f_"-o libvirt: output pool ‘%s’ does not have /pool/target/path element. See virt-v2v(1) section \"OUTPUT TO LIBVIRT\"") output_pool
error (f_"-o libvirt: output pool ‘%s’ does not have /pool/target/path element. See virt-v2v-output-local(1)") output_pool
| Some dir when not (is_directory dir) ->
error (f_"-o libvirt: output pool ‘%s’ has type='dir' but the /pool/target/path element is not a local directory. See virt-v2v(1) section \"OUTPUT TO LIBVIRT\"") output_pool
error (f_"-o libvirt: output pool ‘%s’ has type='dir' but the /pool/target/path element is not a local directory. See virt-v2v-output-local(1)") output_pool
| Some dir -> dir in
(* Get the name of the pool, since we have to use that
* (and not the UUID) in the XML of the guest.
@@ -120,7 +120,7 @@ class output_libvirt oc output_pool = object
let name =
match xpath_string "/pool/name/text()" with
| None ->
error (f_"-o libvirt: output pool ‘%s’ does not have /pool/name element. See virt-v2v(1) section \"OUTPUT TO LIBVIRT\"") output_pool
error (f_"-o libvirt: output pool ‘%s’ does not have /pool/name element. See virt-v2v-output-local(1)") output_pool
| Some name -> name in
pool_name <- Some name;

4
v2v/output_rhv_upload.ml
View File

@@ -120,7 +120,7 @@ class output_rhv_upload output_alloc output_conn
let cmd = "nbdkit --version >/dev/null" in
debug "%s" cmd;
if 0 <> Sys.command "nbdkit --version >/dev/null" then
error (f_"nbdkit is not installed or not working. It is required to use ‘-o rhv-upload’. See \"OUTPUT TO RHV\" in the virt-v2v(1) manual.");
error (f_"nbdkit is not installed or not working. It is required to use ‘-o rhv-upload’. See the virt-v2v-output-rhv(1) manual.");
(* Check it's a new enough version. The latest features we
* require are ‘--exit-with-parent’ and ‘--selinux-label’, both
@@ -145,7 +145,7 @@ class output_rhv_upload output_alloc output_conn
if Sys.command cmd <> 0 then
error (f_"nbdkit %s plugin is not installed or not working. It is required if you want to use ‘-o rhv-upload’.
See also \"OUTPUT TO RHV\" in the virt-v2v(1) manual.")
See also the virt-v2v-output-rhv(1) manual.")
Python_script.python
in

2
v2v/v2v.ml
View File

@@ -321,7 +321,7 @@ and create_overlays src_disks =
* It could be RHBZ#1283588 or some other problem with qemu.
*)
if vsize = 0L then
error (f_"guest disk %s appears to be zero bytes in size.\n\nThere could be several reasons for this:\n\nCheck that the guest doesn't really have a zero-sized disk. virt-v2v cannot convert such a guest.\n\nIf you are converting a guest from an ssh source and the guest has a disk on a block device (eg. on a host partition or host LVM LV), then conversions of this type are not supported. See \"XEN OR SSH CONVERSIONS FROM BLOCK DEVICES\" in the virt-v2v(1) manual for a workaround.")
error (f_"guest disk %s appears to be zero bytes in size.\n\nThere could be several reasons for this:\n\nCheck that the guest doesn't really have a zero-sized disk. virt-v2v cannot convert such a guest.\n\nIf you are converting a guest from an ssh source and the guest has a disk on a block device (eg. on a host partition or host LVM LV), then conversions of this type are not supported. See the virt-v2v-input-xen(1) manual for a workaround.")
sd;
(* Function 'estimate_target_size' replaces the

5
v2v/virt-v2v-copy-to-local.pod
View File

@@ -31,7 +31,7 @@ unused parts of the guest disk.
You have a Xen guest using host block devices. Virt-v2v cannot
convert such guests directly.
See L<virt-v2v(1)/XEN OR SSH CONVERSIONS FROM BLOCK DEVICES>.
See L<virt-v2v-input-xen(1)>.
=back
@@ -61,8 +61,7 @@ Virt-v2v finds the local copies of the disks by looking in the XML.
=head2 Copy and convert from Xen hypervisor that uses host block devices
For full instructions, see
L<virt-v2v(1)/XEN OR SSH CONVERSIONS FROM BLOCK DEVICES>.
For full instructions, see L<virt-v2v-input-xen(1)>.
virt-v2v-copy-to-local -ic xen+ssh://root@xen.example.com xen_guest
virt-v2v -i libvirtxml xen_guest.xml -o local -os /var/tmp

650
v2v/virt-v2v-input-vmware.pod Normal file
View File

@@ -0,0 +1,650 @@
=head1 NAME
virt-v2v-input-vmware - Using virt-v2v to convert guests from VMware
=head1 SYNOPSIS
virt-v2v -i vmx GUEST.vmx [-o* options]
virt-v2v -i vmx
-it ssh
'ssh://root@esxi.example.com/vmfs/volumes/datastore1/guest/guest.vmx'
[-o* options]
virt-v2v
-ic 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1'
-it vddk
-io vddk-libdir=/path/to/vmware-vix-disklib-distrib
-io vddk-thumbprint=xx:xx:xx:...
"GUEST NAME"
[-o* options]
virt-v2v -i ova DISK.ova [-o* options]
virt-v2v
-ic 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1'
"GUEST NAME" [-o* options]
=head1 DESCRIPTION
This page documents how to use L<virt-v2v(1)> to convert guests from
VMware. There are currently five different methods to access VMware:
=over 4
=item B<-i vmx> GUESTB<.vmx>
Full documentation: L</INPUT FROM VMWARE VMX>
If you either have a F<GUEST.vmx> file and one or more F<GUEST.vmdk>
disk image files, or if you are able to NFS-mount the VMware storage,
then you can use the I<-i vmx> method to read the source guest.
=item B<-i vmx> B<-it ssh> ssh://...
Full documentation: L</INPUT FROM VMWARE VMX>
This is similar to the method above, except it uses an SSH connection
to ESXi to read the F<GUEST.vmx> file and associated disks. This
requires that you have enabled SSH access to the VMware ESXi
hypervisor - in the default ESXi configuration this is turned off.
=item B<-ic vpx://...> B<-it vddk>
=item B<-ic esx://...> B<-it vddk>
Full documentation: L</INPUT FROM VDDK>
This method uses the proprietary VDDK library (a.k.a. VixDiskLib) to
access the VMware vCenter server or VMware ESXi hypervisor.
If you have the proprietary library then this method is usually the
fastest and most flexible. If you don't have or don't want to use
non-free software then the VMX or SSH methods above will be best.
=item B<-i ova> DISKB<.ova>
Full documentation: L</INPUT FROM VMWARE OVA>
With this method you must first export the guest (eg. from vSphere) as
an F<.ova> file, which virt-v2v can then read directly. Note this
method only works with files exported from VMware, not OVA files that
come from other hypervisors or management systems, since OVA is only a
pretend standard and is not compatible or interoperable between
vendors.
=item B<-ic vpx://...> "GUEST NAME"
Full documentation: L</INPUT FROM VMWARE VCENTER SERVER>
If none of the above methods is available, then use this method to
import a guest from VMware vCenter. This is the slowest method.
=back
=head1 INPUT FROM VMWARE VMX
Virt-v2v is able to import guests from VMware’s vmx files.
This is useful in two cases:
=over 4
=item 1.
VMware virtual machines are stored on a separate NFS server and you
are able to mount the NFS storage directly.
=item 2.
You have enabled SSH access to the VMware ESXi hypervisor and there is
a C</vmfs/volumes> folder containing the virtual machines.
=back
If you find a folder of files called F<I<guest>.vmx>,
F<I<guest>.vmxf>, F<I<guest>.nvram> and one or more F<.vmdk> disk
images, then you can use this method.
=head2 VMX: Remove VMware tools from Windows guests
For Windows guests, you should remove VMware tools before conversion.
Although this is not strictly necessary, and the guest will still be
able to run, if you don't do this then the converted guest will
complain on every boot. The tools cannot be removed after conversion
because the uninstaller checks if it is running on VMware and refuses
to start (which is also the reason that virt-v2v cannot remove them).
This is not necessary for Linux guests, as virt-v2v is able to remove
VMware tools.
=head2 VMX: Guest must be shut down
B<The guest must be shut down before conversion starts>. If you don't
shut it down, you will end up with a corrupted VM disk on the target.
With other methods, virt-v2v tries to prevent concurrent access, but
because the I<-i vmx> method works directly against the storage,
checking for concurrent access is not possible.
=head2 VMX: Access to the storage containing the VMX and VMDK files
If the vmx and vmdk files aren't available locally then you must
I<either> mount the NFS storage on the conversion server I<or> enable
passwordless SSH on the ESXi hypervisor.
=head3 VMX: Passwordless SSH using ssh-agent
You must also use ssh-agent, and add your ssh public key to
F</etc/ssh/keys-root/authorized_keys> (on the ESXi hypervisor).
After doing this, you should check that passwordless access works from
the virt-v2v server to the ESXi hypervisor. For example:
$ ssh root@esxi.example.com
[ logs straight into the shell, no password is requested ]
Note that password-interactive and Kerberos access are B<not>
supported. You B<have> to set up ssh access using ssh-agent and
authorized_keys.
=head3 VMX: Construct the SSH URI
When using the SSH input transport you must specify a remote
C<ssh://...> URI pointing to the VMX file. A typical URI looks like:
ssh://root@esxi.example.com/vmfs/volumes/datastore1/my%20guest/my%20guest.vmx
Any space must be escaped with C<%20> and other non-ASCII characters
may also need to be URI-escaped.
The username is not required if it is the same as your local username.
You may optionally supply a port number after the hostname if the SSH
server is not listening on the default port (22).
=head2 VMX: Importing a guest
To import a vmx file from a local file or NFS, do:
$ virt-v2v -i vmx guest.vmx -o local -os /var/tmp
To import a vmx file over SSH, add I<-it ssh> to select the SSH
transport and supply a remote SSH URI:
$ virt-v2v \
-i vmx -it ssh \
"ssh://root@esxi.example.com/vmfs/volumes/datastore1/guest/guest.vmx" \
-o local -os /var/tmp
Virt-v2v processes the vmx file and uses it to find the location of
any vmdk disks.
=head1 INPUT FROM VDDK
Virt-v2v is able to import guests using VMware’s proprietary VDDK
library (a.k.a. VixDiskLib).
=head2 VDDK: Prerequisites
=over 4
=item 1.
As the VDDK library is not open source, and the license of this
library does not permit redistribution or commercial use, you must
obtain VDDK yourself and satisfy yourself that your usage of the
library is permitted by the license.
=item 2.
You must also compile nbdkit, enabling the VDDK plugin. nbdkit E<ge>
1.1.25 is recommended, but it is usually best to compile from the git
tree.
=over 4
=item *
L<https://github.com/libguestfs/nbdkit>
=item *
L<https://github.com/libguestfs/nbdkit/tree/master/plugins/vddk>
=back
Compile nbdkit as described in the sources (see link above).
You do B<not> need to run C<make install> because you can run nbdkit
from its source directory. The source directory has a shell script
called F<nbdkit> which runs the locally built copy of nbdkit and its
plugins. So set C<$PATH> to point to the nbdkit top build directory
(that is, the directory containing the shell script called F<nbdkit>),
eg:
export PATH=/path/to/nbdkit-1.1.x:$PATH
=item 3.
You must find the SSL "thumbprint" of your VMware server. How to do
this is explained in L<nbdkit-vddk-plugin(1)>, also available at the
link above.
=item 4.
VDDK imports require a feature added in libvirt E<ge> 3.7.
=back
=head2 VDDK: ESXi NFC service memory limits
In the verbose log you may see errors like:
nbdkit: vddk[3]: error: [NFC ERROR] NfcFssrvrProcessErrorMsg:
received NFC error 5 from server: Failed to allocate the
requested 2097176 bytes
This seems especially common when there are multiple parallel
connections open to the VMware server.
These can be caused by resource limits set on the VMware server. You
can increase the limit for the NFC service by editing
F</etc/vmware/hostd/config.xml> and adjusting the
C<E<lt>maxMemoryE<gt>> setting:
<nfcsvc>
<path>libnfcsvc.so</path>
<enabled>true</enabled>
<maxMemory>50331648</maxMemory>
<maxStreamMemory>10485760</maxStreamMemory>
</nfcsvc>
and restarting the C<hostd> service:
# /etc/init.d/hostd restart
For more information see L<https://bugzilla.redhat.com/1614276>.
=head2 VDDK: URI
Construct the correct C<vpx://> (for vCenter) or C<esx://> (for ESXi)
URL. It will look something like these:
vpx://root@vcenter.example.com/Datacenter/esxi
esx://root@esxi.example.com
To verify that you have the correct URL, use the L<virsh(1)> command
to list the guests on the server:
$ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' list --all
Enter root's password for vcenter.example.com: ***
Id Name State
----------------------------------------------------
- Fedora 20 shut off
- Windows 2003 shut off
If you get an error "Peer certificate cannot be authenticated with
given CA certificates" or similar, then you can either import the
vCenter host’s certificate, or bypass signature verification by adding
the C<?no_verify=1> flag:
$ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' list --all
You should also try dumping the metadata from any guest on your
server, like this:
$ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' dumpxml "Windows 2003"
<domain type='vmware'>
<name>Windows 2003</name>
[...]
<vmware:moref>vm-123</vmware:moref>
</domain>
If C<E<lt>vmware:morefE<gt>> does not appear in the metadata, then you
need to upgrade libvirt.
B<If the above commands do not work, then virt-v2v is not going to
work either>. Fix your URI and/or your VMware server before
continuing.
=head2 VDDK: Importing a guest
The I<-it vddk> parameter selects VDDK as the input transport for disks.
To import a particular guest from vCenter server or ESXi hypervisor,
use a command like the following, substituting the URI, guest name and
SSL thumbprint:
$ export PATH=/path/to/nbdkit-1.1.x:$PATH
$ virt-v2v \
-ic 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' \
-it vddk \
-io vddk-libdir=/path/to/vmware-vix-disklib-distrib \
-io vddk-thumbprint=xx:xx:xx:... \
"Windows 2003" \
-o local -os /var/tmp
Other options that you might need to add in rare circumstances include
I<-io vddk-config>, I<-io vddk-cookie>, I<-io vddk-nfchostport>,
I<-io vddk-port>, I<-io vddk-snapshot>, and I<-io vddk-transports>,
which are all explained in the L<nbdkit-vddk-plugin(1)> documentation.
Do not use these options unless you know what you are doing.
=head2 VDDK: Debugging VDDK failures
The VDDK library can be operated in a verbose mode where it gives
(very) verbose messages. Use ‘virt-v2v -v -x’ as usual to enable
verbose messages.
=head1 INPUT FROM VMWARE OVA
Virt-v2v is able to import guests from VMware’s OVA (Open
Virtualization Appliance) files. Only OVAs exported from VMware
vSphere will work.
=head2 OVA: Remove VMware tools from Windows guests
For Windows guests, you should remove VMware tools before conversion.
Although this is not strictly necessary, and the guest will still be
able to run, if you don't do this then the converted guest will
complain on every boot. The tools cannot be removed after conversion
because the uninstaller checks if it is running on VMware and refuses
to start (which is also the reason that virt-v2v cannot remove them).
This is not necessary for Linux guests, as virt-v2v is able to remove
VMware tools.
=head2 OVA: Create OVA
To create an OVA in vSphere, use the "Export OVF Template" option
(from the VM context menu, or from the File menu). Either "Folder of
files" (OVF) or "Single file" (OVA) will work, but OVA is probably
easier to deal with. OVA files are really just uncompressed tar
files, so you can use commands like C<tar tf VM.ova> to view their
contents.
=head3 Create OVA with ovftool
You can also use VMware’s proprietary C<ovftool>:
ovftool --noSSLVerify \
vi://USER:PASSWORD@esxi.example.com/VM \
VM.ova
To connect to vCenter:
ovftool --noSSLVerify \
vi://USER:PASSWORD@vcenter.example.com/DATACENTER-NAME/vm/VM \
VM.ova
For Active Directory-aware authentication, you have to express the
C<@> character in the form of its ascii hex-code (C<%5c>):
vi://DOMAIN%5cUSER:PASSWORD@...
=head2 OVA: Importing a guest
To import an OVA file called F<VM.ova>, do:
$ virt-v2v -i ova VM.ova -o local -os /var/tmp
If you exported the guest as a "Folder of files", I<or> if you
unpacked the OVA tarball yourself, then you can point virt-v2v at the
directory containing the files:
$ virt-v2v -i ova /path/to/files -o local -os /var/tmp
=head1 INPUT FROM VMWARE VCENTER SERVER
Virt-v2v is able to import guests from VMware vCenter Server.
vCenter E<ge> 5.0 is required. If you don’t have vCenter, using OVA
or VMX is recommended instead (see L</INPUT FROM VMWARE OVA> and/or
L</INPUT FROM VMWARE VMX>).
Virt-v2v uses libvirt for access to vCenter, and therefore the input
mode should be I<-i libvirt>. As this is the default, you don't need
to specify it on the command line.
=head2 vCenter: Remove VMware tools from Windows guests
For Windows guests, you should remove VMware tools before conversion.
Although this is not strictly necessary, and the guest will still be
able to run, if you don't do this then the converted guest will
complain on every boot. The tools cannot be removed after conversion
because the uninstaller checks if it is running on VMware and refuses
to start (which is also the reason that virt-v2v cannot remove them).
This is not necessary for Linux guests, as virt-v2v is able to remove
VMware tools.
=head2 vCenter: URI
The libvirt URI of a vCenter server looks something like this:
vpx://user@server/Datacenter/esxi
where:
=over 4
=item C<user@>
is the (optional, but recommended) user to connect as.
If the username contains a backslash (eg. C<DOMAIN\USER>) then you
will need to URI-escape that character using C<%5c>: C<DOMAIN%5cUSER>
(5c is the hexadecimal ASCII code for backslash.) Other punctuation
may also have to be escaped.
=item C<server>
is the vCenter Server (I<not> hypervisor).
=item C<Datacenter>
is the name of the datacenter.
If the name contains a space, replace it with the URI-escape code
C<%20>.
=item C<esxi>
is the name of the ESXi hypervisor running the guest.
=back
If the VMware deployment is using folders, then these may need to be
added to the URI, eg:
vpx://user@server/Folder/Datacenter/esxi
For full details of libvirt URIs, see: L<http://libvirt.org/drvesx.html>
Typical errors from libvirt / virsh when the URI is wrong include:
=over 4
=item *
Could not find datacenter specified in [...]
=item *
Could not find compute resource specified in [...]
=item *
Path [...] does not specify a compute resource
=item *
Path [...] does not specify a host system
=item *
Could not find host system specified in [...]
=back
=head2 vCenter: Test libvirt connection to vCenter
Use the L<virsh(1)> command to list the guests on the vCenter Server
like this:
$ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' list --all
Enter root's password for vcenter.example.com: ***
Id Name State
----------------------------------------------------
- Fedora 20 shut off
- Windows 2003 shut off
If you get an error "Peer certificate cannot be authenticated with
given CA certificates" or similar, then you can either import the
vCenter host’s certificate, or bypass signature verification by adding
the C<?no_verify=1> flag:
$ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' list --all
You should also try dumping the metadata from any guest on your
server, like this:
$ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' dumpxml "Windows 2003"
<domain type='vmware'>
<name>Windows 2003</name>
[...]
</domain>
B<If the above commands do not work, then virt-v2v is not going to
work either>. Fix your libvirt configuration and/or your VMware
vCenter Server before continuing.
=head2 vCenter: Importing a guest
To import a particular guest from vCenter Server, do:
$ virt-v2v -ic 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' \
"Windows 2003" \
-o local -os /var/tmp
where C<Windows 2003> is the name of the guest (which must be shut
down).
Note that you may be asked for the vCenter password I<twice>. This
happens once because libvirt needs it, and a second time because
virt-v2v itself connects directly to the server. Use I<-ip>
F<filename> to supply a password via a file.
In this case the output flags are set to write the converted guest to
a temporary directory as this is just an example, but you can also
write to libvirt or any other supported target.
=head2 vCenter: Non-administrator role
Instead of using the vCenter Administrator role, you can create a
custom non-administrator role to perform the conversion. You will
however need to give it a minimum set of permissions as follows:
=over 4
=item 1.
Create a custom role in vCenter.
=item 2.
Enable (check) the following objects:
Datastore:
- Browse datastore
- Low level file operations
Sessions:
- Validate session
Virtual Machine:
Provisioning:
- Allow disk access
- Allow read-only disk access
- Guest Operating system management by VIX API
=back
=head2 vCenter: Firewall and proxy settings
=head3 vCenter: Ports
If there is a firewall between the virt-v2v conversion server and the
vCenter server, then you will need to open port 443 (https) and port
5480.
Port 443 is used to copy the guest disk image(s). Port 5480 is used
to query vCenter for guest metadata.
These port numbers are only the defaults. It is possible to
reconfigure vCenter to use other port numbers. In that case you would
need to specify those ports in the C<vpx://> URI.
See L</vCenter: URI> above.
These ports only apply to virt-v2v conversions. You may have to open
other ports for other vCenter functionality, for example the web user
interface. VMware documents the required ports for vCenter in their
online documentation.
┌────────────┐ port 443 ┌────────────┐ ┌────────────┐
│ virt-v2v │────────────▶ vCenter │────────▶ ESXi │
│ conversion │────────────▶ server │ │ hypervisor │
│ server │ port 5480 │ │ │ ┌─────┐ │
└────────────┘ └────────────┘ │ │guest│ │
└───┴─────┴──┘
(In the diagram above the arrows show the direction in which the TCP
connection is initiated, I<not> necessarily the direction of data
transfer.)
Virt-v2v itself does not connect directly to the ESXi hypervisor
containing the guest. However vCenter connects to the hypervisor and
forwards the information, so if you have a firewall between vCenter
and its hypervisors you may need to open additional ports (consult
VMware documentation).
The proxy environment variables (C<https_proxy>, C<all_proxy>,
C<no_proxy>, C<HTTPS_PROXY>, C<ALL_PROXY> and C<NO_PROXY>) are
B<ignored> when doing vCenter conversions.
=head2 vCenter: SSL/TLS certificate problems
You may see this error:
CURL: Error opening file: SSL: no alternative certificate subject
name matches target host name
(You may need to enable debugging with ‘virt-v2v -v -x’ to see this
message).
This can be caused by using an IP address instead of the
fully-qualified DNS domain name of the vCenter server, ie. use
C<vpx://vcenter.example.com/...> instead of C<vpx://11.22.33.44/...>
Another certificate problem can be caused by the vCenter server having
a mismatching FQDN and IP address, for example if the server acquired
a new IP address from DHCP. To fix this you need to change your DHCP
server or network configuration so that the vCenter server always gets
a stable IP address. After that log in to the vCenter server’s admin
console at C<https://vcenter:5480/>. Under the C<Admin> tab, select
C<Certificate regeneration enabled> and then reboot it.
=head1 SEE ALSO
L<virt-v2v(1)>.
=head1 AUTHOR
Richard W.M. Jones
=head1 COPYRIGHT
Copyright (C) 2009-2018 Red Hat Inc.

128
v2v/virt-v2v-input-xen.pod Normal file
View File

@@ -0,0 +1,128 @@
=head1 NAME
virt-v2v-input-xen - Using virt-v2v to convert guests from Xen
=head1 SYNOPSIS
export LIBGUESTFS_BACKEND=direct
virt-v2v -ic 'xen+ssh://root@xen.example.com' GUEST_NAME [-o* options]
=head1 DESCRIPTION
This page documents how to use L<virt-v2v(1)> to convert guests from
RHEL 5 Xen, or SLES and OpenSUSE Xen hosts.
=head1 INPUT FROM XEN
=head2 Set up ssh-agent access to Xen host
Currently you must enable passwordless SSH access to the remote Xen host
from the virt-v2v conversion server.
You must also use ssh-agent, and add your ssh public key to
F</root/.ssh/authorized_keys> (on the Xen host).
After doing this, you should check that passwordless access works
from the virt-v2v server to the Xen host. For example:
$ ssh root@xen.example.com
[ logs straight into the shell, no password is requested ]
Note that password-interactive and Kerberos access are B<not>
supported. You B<have> to set up ssh access using ssh-agent and
authorized_keys.
With some modern ssh implementations, legacy crypto policies required
to interoperate with RHEL 5 sshd are disabled. To enable them you may
need to run this command on the conversion server (ie. ssh client),
but read L<update-crypto-policies(8)> first:
# update-crypto-policies LEGACY
=head2 Test libvirt connection to remote Xen host
Use the L<virsh(1)> command to list the guests on the remote Xen host:
$ virsh -c xen+ssh://root@xen.example.com list --all
Id Name State
----------------------------------------------------
0 Domain-0 running
- rhel49-x86_64-pv shut off
You should also try dumping the metadata from any guest on your
server, like this:
$ virsh -c xen+ssh://root@xen.example.com dumpxml rhel49-x86_64-pv
<domain type='xen'>
<name>rhel49-x86_64-pv</name>
[...]
</domain>
B<If the above commands do not work, then virt-v2v is not going to
work either>. Fix your libvirt configuration or the remote server
before continuing.
B<If the guest disks are located on a host block device>, then the
conversion will fail. See L</Xen or ssh conversions from block devices>
below for a workaround.
=head2 Importing a guest
To import a particular guest from a Xen server, do:
$ LIBGUESTFS_BACKEND=direct \
virt-v2v -ic 'xen+ssh://root@xen.example.com' \
rhel49-x86_64-pv \
-o local -os /var/tmp
where C<rhel49-x86_64-pv> is the name of the guest (which must be shut
down).
In this case the output flags are set to write the converted guest to
a temporary directory as this is just an example, but you can also
write to libvirt or any other supported target.
Setting the L<backend|guestfs(3)/BACKEND> to C<direct> is a temporary
workaround until
L<libvirt bug 1140166|https://bugzilla.redhat.com/1140166> is fixed.
=head2 Xen or ssh conversions from block devices
Currently virt-v2v cannot directly access a Xen guest (or any guest
located remotely over ssh) if that guest’s disks are located on host
block devices.
To tell if a Xen guest uses host block devices, look at the guest XML.
You will see:
<disk type='block' device='disk'>
...
<source dev='/dev/VG/guest'/>
where C<type='block'>, C<source dev=> and C</dev/...> are all
indications that the disk is located on a host block device.
This happens because the qemu ssh block driver that we use to access
remote disks uses the ssh sftp protocol, and this protocol cannot
correctly detect the size of host block devices.
The workaround is to copy the guest over to the conversion server,
using the separate L<virt-v2v-copy-to-local(1)> tool, followed by
running virt-v2v. You will need sufficient space on the conversion
server to store a full copy of the guest.
virt-v2v-copy-to-local -ic xen+ssh://root@xen.example.com guest
virt-v2v -i libvirtxml guest.xml -o local -os /var/tmp
rm guest.xml guest-disk*
=head1 SEE ALSO
L<virt-v2v(1)>.
=head1 AUTHOR
Richard W.M. Jones
=head1 COPYRIGHT
Copyright (C) 2009-2018 Red Hat Inc.

153
v2v/virt-v2v-output-local.pod Normal file
View File

@@ -0,0 +1,153 @@
=head1 NAME
virt-v2v-output-local - Using virt-v2v to convert guests to local files
or libvirt
=head1 SYNOPSIS
virt-v2v [-i* options] [-o libvirt] -os POOL
virt-v2v [-i* options] -o local -os DIRECTORY
virt-v2v [-i* options] -o qemu -os DIRECTORY [--qemu-boot]
virt-v2v [-i* options] -o null
=head1 DESCRIPTION
This page documents how to use L<virt-v2v(1)> to convert guests to
local files or to a locally running libvirt instance. There are four
output modes you can select on the virt-v2v command line:
=over 4
=item B<-o libvirt -os> C<POOL>
=item B<-os> C<POOL>
This converts the guest to a libvirt directory pool call C<POOL>, and
instantiates the guest in libvirt (but does not start it running).
See L</OUTPUT TO LIBVIRT> below.
I<-o libvirt> is the default if no I<-o> option is given, so you can
omit it.
=item B<-o local -os> C<DIRECTORY>
This converts the guest to files in C<DIRECTORY>. A libvirt XML file
is also created, but unlike I<-o libvirt> the guest is not
instantiated in libvirt, only files are created.
The files will be called:
NAME-sda, NAME-sdb, etc. Guest disk(s).
NAME.xml Libvirt XML.
where C<NAME> is the guest name.
=item B<-o qemu -os> C<DIRECTORY>
=item B<-o qemu -os> C<DIRECTORY> B<--qemu-boot>
This converts the guest to files in C<DIRECTORY>. Unlike I<-o local>
above, a shell script is created which contains the raw qemu command
you would need to boot the guest. However the shell script is not
run, I<unless> you also add the I<--qemu-boot> option.
=item B<-o null>
The guest is converted, but the final result is thrown away and no
metadata is created. This is mainly useful for testing.
=back
=head1 OUTPUT TO LIBVIRT
The I<-o libvirt> option lets you upload the converted guest to
a libvirt-managed host. There are several limitations:
=over 4
=item *
You can only use a local libvirt connection [see below for how to
workaround this].
=item *
The I<-os pool> option must specify a directory pool, not anything
more exotic such as iSCSI [but see below].
=item *
You can only upload to a KVM hypervisor.
=back
=head2 Workaround for output to a remote libvirt instance and/or a
non-directory storage pool
=over 4
=item 1.
Use virt-v2v in I<-o local> mode to convert the guest disks and
metadata into a local temporary directory:
virt-v2v [...] -o local -os /var/tmp
This creates two (or more) files in F</var/tmp> called:
/var/tmp/NAME.xml # the libvirt XML (metadata)
/var/tmp/NAME-sda # the guest’s first disk
(for C<NAME> substitute the guest’s name).
=item 2.
Upload the converted disk(s) into the storage pool called C<POOL>:
size=$(stat -c%s /var/tmp/NAME-sda)
virsh vol-create-as POOL NAME-sda $size --format raw
virsh vol-upload --pool POOL NAME-sda /var/tmp/NAME-sda
=item 3.
Edit F</var/tmp/NAME.xml> to change F</var/tmp/NAME-sda> to the pool
name. In other words, locate the following bit of XML:
<disk type='file' device='disk'>
<driver name='qemu' type='raw' cache='none' />
<source file='/var/tmp/NAME-sda' />
<target dev='hda' bus='ide' />
</disk>
and change two things: The C<type='file'> attribute must be changed to
C<type='volume'>, and the C<E<lt>sourceE<gt>> element must be changed
to include C<pool> and C<volume> attributes:
<disk type='volume' device='disk'>
...
<source pool='POOL' volume='NAME-sda' />
...
</disk>
=item 4.
Define the final guest in libvirt:
virsh define /var/tmp/NAME.xml
=back
=head1 SEE ALSO
L<virt-v2v(1)>.
=head1 AUTHOR
Richard W.M. Jones
=head1 COPYRIGHT
Copyright (C) 2009-2018 Red Hat Inc.

209
v2v/virt-v2v-output-openstack.pod Normal file
View File

@@ -0,0 +1,209 @@
=head1 NAME
virt-v2v-output-openstack - Using virt-v2v to convert guests to OpenStack
=head1 SYNOPSIS
virt-v2v [-i* options] -o openstack
-oo server-id=SERVER
[-oo guest-id=GUEST]
[-oo os-username=admin] [-oo os-*=*]
virt-v2v [-i* options] -o glance
=head1 DESCRIPTION
This page documents how to use L<virt-v2v(1)> to convert guests to run
on OpenStack. There are two output modes you can select, but only
I<-o openstack> should be used normally.
=over 4
=item B<-o openstack> B<-oo server-id=>SERVER [...]
Full description: L</OUTPUT TO OPENSTACK>
This is the modern method for uploading to OpenStack via the REST API.
Guests can be directly converted into Cinder volumes.
=item B<-o glance>
Full description: L</OUTPUT TO GLANCE>
This is the old method for uploading to Glance. Unfortunately Glance
is not well suited to storing converted guests (since virt-v2v deals
with "pets" not templated "cattle"), so this method is not recommended
unless you really know what you are doing.
=back
=head1 OUTPUT TO OPENSTACK
To output to OpenStack, use the I<-o openstack> option.
=head2 OpenStack: Setting up a conversion appliance
When virt-v2v is converting to OpenStack, it is unusual in that
virt-v2v B<must> be running inside a virtual machine running on top of
the OpenStack overcloud. This virtual machine is called the
"conversion appliance". Note this virtual machine is unrelated to the
guest which is being converted.
The reason for this is because to create Cinder volumes that will
contain the guest data (for the converted guest) we must attach those
Cinder volumes to an OpenStack virtual machine.
When virt-v2v is running in the conversion appliance, you must supply
the name or UUID of the conversion appliance to virt-v2v, eg:
$ openstack server list
+--------------------------------------+-----------+--------+
| ID | Name | Status |
+--------------------------------------+-----------+--------+
| bbb0147a-44b9-4d19-9a9d-10ca9a984744 | test1 | ACTIVE |
+--------------------------------------+-----------+--------+
# virt-v2v [...] \
-o openstack -oo server-id=bbb0147a-44b9-4d19-9a9d-10ca9a984744
or:
# virt-v2v [...] -o openstack -oo server-id=test1
You can run many parallel conversions inside a single conversion
appliance if you want, subject to having enough resources available.
However OpenStack itself imposes a limit that you should be aware of:
OpenStack cannot attach more than around 25 disks [the exact number
varies with configuration] to a single appliance, and that limits the
number of guests which can be converted in parallel, because each
guest's disk must be attached to the appliance while being copied.
=head2 OpenStack: Authentication
Converting to OpenStack requires access to the tenant (non-admin) API
endpoints. You will need to either set up your C<$OS_*> environment
variables or use output options on the virt-v2v command line to
authenticate with OpenStack.
Normally there is a file called something like C<stackrc>,
C<overcloudrc> etc which you can simply C<source> to set everything up.
For example:
export OS_USERNAME=admin
or:
virt-v2v [...] -o openstack -oo os-username=admin
are equivalent, and have the same effect as using I<--os-username> on
the command line of OpenStack tools.
=head2 OpenStack: Running as root
Because virt-v2v must access Cinder volumes which are presented as
F</dev> devices to the conversion appliance, virt-v2v must usually run
as root in I<-o openstack> mode.
If you use C<sudo> to start virt-v2v and you are using environment
variables for authentication, remember to use the C<sudo -E> option to
preserve the environment.
=head2 OpenStack: Guest ID
virt-v2v [...] -o openstack -oo guest-id=123-456-7890
You may optionally specify I<-oo guest-id=...> on the command line.
The ID (which can be any string) is saved on each Cinder volume in the
C<virt_v2v_guest_id> volume property.
This can be used to find disks associated with a guest, or to
associate which disks are related to which guests when converting many
guests.
=head2 OpenStack: Converting a guest
The final command to convert the guest, running as root, will be:
# virt-v2v [-i options ...] \
-o openstack -oo server-id=NAME|UUID [-oo guest-id=ID]
If you include authentication options on the command line then:
# virt-v2v [-i options ...] \
-o openstack -oo server-id=NAME|UUID -oo os-username=admin [etc]
=head2 OpenStack: Booting the guest
Guests are converted as Cinder volume(s) (one volume per disk in the
original guest). To boot them use the
C<openstack server create --volume> option:
$ openstack volume list
+--------------------------------------+---------------+-----------+
| ID | Name | Status |
+--------------------------------------+---------------+-----------+
| c4d06d15-22ef-462e-9eff-ab54ab285a1f | fedora-27-sda | available |
+--------------------------------------+---------------+-----------+
$ openstack server create \
--flavor x1.small \
--volume c4d06d15-22ef-462e-9eff-ab54ab285a1f \
myguest
$ openstack console url show myguest
=head2 OpenStack: Other conversion options
To specify the Cinder volume type, use I<-os>. If not specified then
no Cinder volume type is used.
The following options are B<not> supported with OpenStack: I<-oa>,
I<-of>.
=head1 OUTPUT TO GLANCE
Note this is a legacy option. In most cases you should use
L</OUTPUT TO OPENSTACK> instead.
To output to OpenStack Glance, use the I<-o glance> option.
This runs the L<glance(1)> CLI program which must be installed on the
virt-v2v conversion host. For authentication to work, you will need
to set C<OS_*> environment variables. In most cases you can do this
by sourcing a file called something like F<keystonerc_admin>.
Virt-v2v adds metadata for the guest to Glance, describing such things
as the guest operating system and what drivers it requires. The
command C<glance image-show> will display the metadata as "Property"
fields such as C<os_type> and C<hw_disk_bus>.
=head2 Glance and sparseness
Glance image upload doesn't appear to correctly handle sparseness.
For this reason, using qcow2 will be faster and use less space on the
Glance server. Use the virt-v2v S<I<-of qcow2>> option.
=head2 Glance and multiple disks
If the guest has a single disk, then the name of the disk in Glance
will be the name of the guest. You can control this using the I<-on>
option.
Glance doesn't have a concept of associating multiple disks with a
single guest, and Nova doesn't allow you to boot a guest from multiple
Glance disks either. If the guest has multiple disks, then the first
(assumed to be the system disk) will have the name of the guest, and
the second and subsequent data disks will be called
C<I<guestname>-disk2>, C<I<guestname>-disk3> etc. It may be best to
leave the system disk in Glance, and import the data disks to Cinder.
=head1 SEE ALSO
L<virt-v2v(1)>.
=head1 AUTHOR
Richard W.M. Jones
=head1 COPYRIGHT
Copyright (C) 2009-2018 Red Hat Inc.

209
v2v/virt-v2v-output-rhv.pod Normal file
View File

@@ -0,0 +1,209 @@
=head1 NAME
virt-v2v-output-rhv - Using virt-v2v to convert guests to oVirt or RHV
=head1 SYNOPSIS
virt-v2v [-i* options] -o rhv-upload [-oc ENGINE_URL] -os STORAGE
[-op PASSWORD] [-of raw]
[-oo rhv-cafile=FILE]
[-oo rhv-cluster=CLUSTER]
[-oo rhv-direct]
[-oo rhv-verifypeer]
virt-v2v [-i* options] -o rhv -os [esd:/path|/path]
virt-v2v [-i* options] -o vdsm
[-oo vdsm-image-uuid=UUID]
[-oo vdsm-vol-uuid=UUID]
[-oo vdsm-vm-uuid=UUID]
[-oo vdsm-ovf-output=DIR]
=head1 DESCRIPTION
This page documents how to use L<virt-v2v(1)> to convert guests to an
oVirt or RHV management instance. There are three output modes that
you can select, but only I<-o rhv-upload> should be used normally, the
other two are deprecated:
=over 4
=item B<-o rhv-upload> B<-os> STORAGE
Full description: L</OUTPUT TO RHV>
This is the modern method for uploading to oVirt/RHV via the REST API.
It requires oVirt/RHV E<ge> 4.2.
=item B<-o rhv> B<-os> esd:/path
=item B<-o rhv> B<-os> /path
Full description: L</OUTPUT TO EXPORT STORAGE DOMAIN>
This is the old method for uploading to oVirt/RHV via the
Export Storage Domain (ESD). The ESD can either be accessed
over NFS (using the I<-os esd:/path> form) or if you have
already NFS-mounted it somewhere specify the path to the mountpoint
as I<-os /path>.
The Export Storage Domain was deprecated in oVirt 4, and so we expect
that this method will stop working at some point in the future.
=item B<-o vdsm>
This is the old method used internally by the RHV-M user interface.
It is never intended to be used directly by end users.
=back
=head1 OUTPUT TO RHV
This new method to upload guests to oVirt or RHV directly via the REST
API requires oVirt/RHV E<ge> 4.2.
You need to specify I<-o rhv-upload> as well as the following extra
parameters:
=over 4
=item I<-oc> C<https://ovirt-engine.example.com/ovirt-engine/api>
The URL of the REST API which is usually the server name with
C</ovirt-engine/api> appended, but might be different if you installed
oVirt Engine on a different path.
You can optionally add a username and port number to the URL. If the
username is not specified then virt-v2v defaults to using
C<admin@internal> which is the typical superuser account for oVirt
instances.
=item I<-of raw>
Currently you must use I<-of raw> and you cannot use I<-oa preallocated>.
These restrictions will be loosened in a future version.
=item I<-op> F<password-file>
A file containing a password to be used when connecting to the oVirt
engine. Note the file should contain the whole password, B<without
any trailing newline>, and for security the file should have mode
C<0600> so that others cannot read it.
=item I<-os> C<ovirt-data>
The storage domain.
=item I<-oo rhv-cafile=>F<ca.pem>
The F<ca.pem> file (Certificate Authority), copied from
F</etc/pki/ovirt-engine/ca.pem> on the oVirt engine.
=item I<-oo rhv-cluster=>C<CLUSTERNAME>
Set the RHV Cluster Name. If not given it uses C<Default>.
=item I<-oo rhv-direct>
If this option is given then virt-v2v will attempt to directly upload
the disk to the oVirt node, otherwise it will proxy the upload through
the oVirt engine. Direct upload requires that you have network access
to the oVirt nodes. Non-direct upload is slightly slower but should
work in all situations.
=item I<-oo rhv-verifypeer>
Verify the oVirt/RHV server’s identity by checking the server‘s
certificate against the Certificate Authority.
=back
=head1 OUTPUT TO EXPORT STORAGE DOMAIN
This section only applies to the I<-o rhv> output mode. If you use
virt-v2v from the RHV-M user interface, then behind the scenes the
import is managed by VDSM using the I<-o vdsm> output mode (which end
users should not try to use directly).
You have to specify I<-o rhv> and an I<-os> option that points to the
RHV-M Export Storage Domain. You can either specify the NFS server
and mountpoint, eg. S<C<-os rhv-storage:/rhv/export>>, or you can
mount that first and point to the directory where it is mounted,
eg. S<C<-os /tmp/mnt>>. Be careful not to point to the Data Storage
Domain by accident as that will not work.
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 RHV using the UI before it can be used.
In RHV E<ge> 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 RHV documentation for
additional details.
If you export several guests, then you can import them all at the same
time through the UI.
=head2 Testing RHV conversions
If you do not have an oVirt or RHV instance to test against, then you
can test conversions by creating a directory structure which looks
enough like a RHV-M Export Storage Domain to trick virt-v2v:
uuid=`uuidgen`
mkdir /tmp/rhv
mkdir /tmp/rhv/$uuid
mkdir /tmp/rhv/$uuid/images
mkdir /tmp/rhv/$uuid/master
mkdir /tmp/rhv/$uuid/master/vms
touch /tmp/rhv/$uuid/dom_md
virt-v2v [...] -o rhv -os /tmp/rhv
=head2 Debugging RHV-M import failures
When you export to the RHV-M Export Storage Domain, and then import
that guest through the RHV-M UI, you may encounter an import failure.
Diagnosing these failures is infuriatingly difficult as the UI
generally hides the true reason for the failure.
There are several log files of interest:
=over 4
=item F</var/log/vdsm/import/>
In oVirt E<ge> 4.1.0, VDSM preserves the virt-v2v log file for
30 days in this directory.
This directory is found on the host which performed the conversion.
The host can be selected in the import dialog, or can be found under
the C<Events> tab in oVirt administration.
=item F</var/log/vdsm/vdsm.log>
As above, this file is present on the host which performed the
conversion. It contains detailed error messages from low-level
operations executed by VDSM, and is useful if the error was not caused
by virt-v2v, but by VDSM.
=item F</var/log/ovirt-engine/engine.log>
This log file is stored on the RHV-M server. It contains more detail
for any errors caused by the oVirt GUI.
=back
=head1 SEE ALSO
L<virt-v2v(1)>.
=head1 AUTHOR
Richard W.M. Jones
=head1 COPYRIGHT
Copyright (C) 2009-2018 Red Hat Inc.

156
v2v/virt-v2v-support.pod Normal file
View File

@@ -0,0 +1,156 @@
=head1 NAME
virt-v2v-support - Supported hypervisors, virtualization management
systems and guests in virt-v2v
=head1 DESCRIPTION
This page documents which foreign hypervisors, virtualization
management systems and guest types that L<virt-v2v(1)> can support.
Note this page applies to upstream virt-v2v from
L<http://libguestfs.org> and in downstream distributions of virt-v2v
sometimes features are intentionally removed, or are present but not
supported.
=head2 Hypervisors (Input)
=over 4
=item VMware ESXi
Must be managed by VMware vCenter E<ge> 5.0 unless VDDK is available.
=item OVA exported from VMware
OVAs from other hypervisors will not work.
=item VMX from VMware
VMX files generated by other hypervisors will not work.
=item RHEL 5 Xen
=item SUSE Xen
=item Citrix Xen
Citrix Xen has not been recently tested.
=item Hyper-V
Not recently tested. Requires that you export the disk or use
L<virt-p2v(1)> on Hyper-V.
=item Direct from disk images
Only disk images exported from supported hypervisors, and using
container formats supported by qemu.
=item Physical machines
Using the L<virt-p2v(1)> tool.
=back
=head2 Hypervisors (Output)
QEMU and KVM only.
=head2 Virtualization management systems (Output)
=over 4
=item OpenStack
=item Red Hat Virtualization (RHV) 4.1 and up
=item Local libvirt
And hence L<virsh(1)>, L<virt-manager(1)>, and similar tools.
=item Local disk
=back
=head2 Guests
=over 4
=item Red Hat Enterprise Linux 3, 4, 5, 6, 7
=item CentOS 3, 4, 5, 6, 7
=item Scientific Linux 3, 4, 5, 6, 7
=item Oracle Linux
=item Fedora
=item SLES 10 and up
=item OpenSUSE 10 and up
=item Debian 6 and up
=item Ubuntu 10.04, 12.04, 14.04, 16.04, and up
=item Windows XP to Windows 10 / Windows Server 2016
We use Windows internal version numbers, see
L<https://en.wikipedia.org/wiki/List_of_Microsoft_Windows_versions>
Currently NT 5.2 to NT 6.3 are supported.
See L</WINDOWS> below for additional notes on converting Windows
guests.
=back
=head2 Guest firmware
BIOS is supported for all guest types and hypervisors.
VMware allows you to present UEFI firmware to guests (instead of the
ordinary PC BIOS). Virt-v2v can convert these guests, but requires
that UEFI is supported by the target hypervisor.
Currently KVM supports OVMF, an open source UEFI firmware, and can run
these guests.
Since OVMF support was only recently added to KVM (in 2014/2015), not
all target environments support UEFI guests yet:
=over 4
=item UEFI on libvirt, qemu
Supported. Virt-v2v will generate the correct libvirt XML (metadata)
automatically, but note that the same version of OVMF must be
installed on the conversion host as is installed on the target
hypervisor, else you will have to adjust paths in the metadata.
On RHEL E<ge> 7.3, only qemu-kvm-rhev (not qemu-kvm) is supported.
=item UEFI on OpenStack
Not supported.
=item UEFI on oVirt or RHV
Supported since oVirt/RHV E<ge> 4.2 and virt-v2v E<ge> 1.39.12.
=back
=head1 SEE ALSO
L<virt-v2v(1)>,
L<http://libguestfs.org>.
=head1 AUTHOR
Richard W.M. Jones
=head1 COPYRIGHT
Copyright (C) 2009-2018 Red Hat Inc.

1506
v2v/virt-v2v.pod
View File

File diff suppressed because it is too large Load Diff