=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
    -ip passwordfile
    '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'
    -ip passwordfile
    "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: 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: SSH authentication

You can use SSH password authentication, by supplying the name of a
file containing the password to the I<-ip> option (note this option
does I<not> take the password directly).  You may need to adjust
F</etc/ssh/sshd_config> on the VMware server to set
C<PasswordAuthentication yes>.

If you are not using password authentication, an alternative is to 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 ]

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

nbdkit E<ge> 1.6 is recommended, as it ships with the VDDK plugin
enabled unconditionally.

=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:

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

=head2 VDDK: Slow imports and repeated NBD_ClientOpen messages

If imports over VDDK are slow, and ‘virt-v2v -v -x’ shows many
C<NBD_ClientOpen> messages, then you are hitting an apparent bug in
S<VDDK 6.7> (https://bugzilla.redhat.com/1901489).  Upgrade to at
least S<VDDK 7> to resolve the issue.

=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: 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 using down-level logon names
(C<DOMAIN\USER>), 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: 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.

The user's password must be supplied in a local file using the
separate I<-ip> parameter.

=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: Supplying the password

The vCenter password (usually for the root account, or the account
specified by C<user@> in the vpx URL) has to be written to a local
file, and the name of that file specified on the virt-v2v command line
using I<-ip passwordfile>.

=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' \
   -ip passwordfile \
   "Windows 2003" \
   -o local -os /var/tmp

where C<Windows 2003> 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.

=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
(using VMware vCenter 6.5):

=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:
   Interaction:
     - Guest operating system management by VIX API
   Provisioning:
     - Allow disk access
     - Allow read-only disk access
 
 Cryptographic operations:
  - Decrypt
  - Direct Access

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

=head2 vCenter: "Out of HTTP sessions: Limited to ..."

VMware vCenter appears to limit HTTP sessions and in some
circumstances virt-v2v may exceed this number.  You can adjust or
remove the limit by editing F</etc/vmware-vpx/vpxd.cfg> on the vCenter
server.  Increase the C<E<lt>maxSessionCountE<gt>> field, or set it to
C<0> which makes it unlimited:

 <soap>
   <maxSessionCount>0</maxSessionCount>
 </soap>

=head1 SEE ALSO

L<virt-v2v(1)>.

=head1 AUTHOR

Richard W.M. Jones

=head1 COPYRIGHT

Copyright (C) 2009-2020 Red Hat Inc.
