1virt-v2v-input-vmware(1)    Virtualization Support    virt-v2v-input-vmware(1)
2
3
4

NAME

6       virt-v2v-input-vmware - Using virt-v2v to convert guests from VMware
7

SYNOPSIS

9        virt-v2v -i vmx GUEST.vmx [-o* options]
10
11        virt-v2v -i vmx
12           -it ssh
13           'ssh://root@esxi.example.com/vmfs/volumes/datastore1/guest/guest.vmx'
14           [-o* options]
15
16        virt-v2v
17           -ic 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1'
18           -it vddk
19           -io vddk-libdir=/path/to/vmware-vix-disklib-distrib
20           -io vddk-thumbprint=xx:xx:xx:...
21           "GUEST NAME"
22           [-o* options]
23
24        virt-v2v -i ova DISK.ova [-o* options]
25
26        virt-v2v
27           -ic 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1'
28           "GUEST NAME" [-o* options]
29

DESCRIPTION

31       This page documents how to use virt-v2v(1) to convert guests from
32       VMware.  There are currently five different methods to access VMware:
33
34       -i vmx GUEST.vmx
35           Full documentation: "INPUT FROM VMWARE VMX"
36
37           If you either have a GUEST.vmx file and one or more GUEST.vmdk disk
38           image files, or if you are able to NFS-mount the VMware storage,
39           then you can use the -i vmx method to read the source guest.
40
41       -i vmx -it ssh ssh://...
42           Full documentation: "INPUT FROM VMWARE VMX"
43
44           This is similar to the method above, except it uses an SSH
45           connection to ESXi to read the GUEST.vmx file and associated disks.
46           This requires that you have enabled SSH access to the VMware ESXi
47           hypervisor - in the default ESXi configuration this is turned off.
48
49       -ic vpx://... -it vddk
50       -ic esx://... -it vddk
51           Full documentation: "INPUT FROM VDDK"
52
53           This method uses the proprietary VDDK library (a.k.a. VixDiskLib)
54           to access the VMware vCenter server or VMware ESXi hypervisor.
55
56           If you have the proprietary library then this method is usually the
57           fastest and most flexible.  If you don't have or don't want to use
58           non-free software then the VMX or SSH methods above will be best.
59
60       -i ova DISK.ova
61           Full documentation: "INPUT FROM VMWARE OVA"
62
63           With this method you must first export the guest (eg. from vSphere)
64           as an .ova file, which virt-v2v can then read directly.  Note this
65           method only works with files exported from VMware, not OVA files
66           that come from other hypervisors or management systems, since OVA
67           is only a pretend standard and is not compatible or interoperable
68           between vendors.
69
70       -ic vpx://... "GUEST NAME"
71           Full documentation: "INPUT FROM VMWARE VCENTER SERVER"
72
73           If none of the above methods is available, then use this method to
74           import a guest from VMware vCenter.  This is the slowest method.
75

INPUT FROM VMWARE VMX

77       Virt-v2v is able to import guests from VMware’s vmx files.
78
79       This is useful in two cases:
80
81       1.  VMware virtual machines are stored on a separate NFS server and you
82           are able to mount the NFS storage directly.
83
84       2.  You have enabled SSH access to the VMware ESXi hypervisor and there
85           is a "/vmfs/volumes" folder containing the virtual machines.
86
87       If you find a folder of files called guest.vmx, guest.vmxf, guest.nvram
88       and one or more .vmdk disk images, then you can use this method.
89
90   VMX: Remove VMware tools from Windows guests
91       For Windows guests, you should remove VMware tools before conversion.
92       Although this is not strictly necessary, and the guest will still be
93       able to run, if you don't do this then the converted guest will
94       complain on every boot.  The tools cannot be removed after conversion
95       because the uninstaller checks if it is running on VMware and refuses
96       to start (which is also the reason that virt-v2v cannot remove them).
97
98       This is not necessary for Linux guests, as virt-v2v is able to remove
99       VMware tools.
100
101   VMX: Guest must be shut down
102       The guest must be shut down before conversion starts.  If you don't
103       shut it down, you will end up with a corrupted VM disk on the target.
104       With other methods, virt-v2v tries to prevent concurrent access, but
105       because the -i vmx method works directly against the storage, checking
106       for concurrent access is not possible.
107
108   VMX: Access to the storage containing the VMX and VMDK files
109       If the vmx and vmdk files aren't available locally then you must either
110       mount the NFS storage on the conversion server or enable passwordless
111       SSH on the ESXi hypervisor.
112
113       VMX: Passwordless SSH using ssh-agent
114
115       You must also use ssh-agent, and add your ssh public key to
116       /etc/ssh/keys-root/authorized_keys (on the ESXi hypervisor).
117
118       After doing this, you should check that passwordless access works from
119       the virt-v2v server to the ESXi hypervisor.  For example:
120
121        $ ssh root@esxi.example.com
122        [ logs straight into the shell, no password is requested ]
123
124       Note that password-interactive and Kerberos access are not supported.
125       You have to set up ssh access using ssh-agent and authorized_keys.
126
127       VMX: Construct the SSH URI
128
129       When using the SSH input transport you must specify a remote
130       "ssh://..." URI pointing to the VMX file.  A typical URI looks like:
131
132        ssh://root@esxi.example.com/vmfs/volumes/datastore1/my%20guest/my%20guest.vmx
133
134       Any space must be escaped with %20 and other non-ASCII characters may
135       also need to be URI-escaped.
136
137       The username is not required if it is the same as your local username.
138
139       You may optionally supply a port number after the hostname if the SSH
140       server is not listening on the default port (22).
141
142   VMX: Importing a guest
143       To import a vmx file from a local file or NFS, do:
144
145        $ virt-v2v -i vmx guest.vmx -o local -os /var/tmp
146
147       To import a vmx file over SSH, add -it ssh to select the SSH transport
148       and supply a remote SSH URI:
149
150        $ virt-v2v \
151            -i vmx -it ssh \
152            "ssh://root@esxi.example.com/vmfs/volumes/datastore1/guest/guest.vmx" \
153            -o local -os /var/tmp
154
155       Virt-v2v processes the vmx file and uses it to find the location of any
156       vmdk disks.
157

INPUT FROM VDDK

159       Virt-v2v is able to import guests using VMware’s proprietary VDDK
160       library (a.k.a. VixDiskLib).
161
162   VDDK: Prerequisites
163       1.  As the VDDK library is not open source, and the license of this
164           library does not permit redistribution or commercial use, you must
165           obtain VDDK yourself and satisfy yourself that your usage of the
166           library is permitted by the license.
167
168       2.  You must also compile nbdkit, enabling the VDDK plugin.  nbdkit ≥
169           1.1.25 is recommended, but it is usually best to compile from the
170           git tree.
171
172           ·   https://github.com/libguestfs/nbdkit
173
174           ·   https://github.com/libguestfs/nbdkit/tree/master/plugins/vddk
175
176           Compile nbdkit as described in the sources (see link above).
177
178           You do not need to run "make install" because you can run nbdkit
179           from its source directory.  The source directory has a shell script
180           called nbdkit which runs the locally built copy of nbdkit and its
181           plugins.  So set $PATH to point to the nbdkit top build directory
182           (that is, the directory containing the shell script called nbdkit),
183           eg:
184
185            export PATH=/path/to/nbdkit-1.1.x:$PATH
186
187       3.  You must find the SSL "thumbprint" of your VMware server.  How to
188           do this is explained in nbdkit-vddk-plugin(1), also available at
189           the link above.
190
191       4.  VDDK imports require a feature added in libvirt ≥ 3.7.
192
193   VDDK: ESXi NFC service memory limits
194       In the verbose log you may see errors like:
195
196        nbdkit: vddk[3]: error: [NFC ERROR] NfcFssrvrProcessErrorMsg:
197        received NFC error 5 from server: Failed to allocate the
198        requested 2097176 bytes
199
200       This seems especially common when there are multiple parallel
201       connections open to the VMware server.
202
203       These can be caused by resource limits set on the VMware server.  You
204       can increase the limit for the NFC service by editing
205       /etc/vmware/hostd/config.xml and adjusting the "<maxMemory>" setting:
206
207        <nfcsvc>
208          <path>libnfcsvc.so</path>
209          <enabled>true</enabled>
210          <maxMemory>50331648</maxMemory>
211          <maxStreamMemory>10485760</maxStreamMemory>
212        </nfcsvc>
213
214       and restarting the "hostd" service:
215
216        # /etc/init.d/hostd restart
217
218       For more information see https://bugzilla.redhat.com/1614276.
219
220   VDDK: URI
221       Construct the correct "vpx://" (for vCenter) or "esx://" (for ESXi)
222       URL.  It will look something like these:
223
224        vpx://root@vcenter.example.com/Datacenter/esxi
225
226        esx://root@esxi.example.com
227
228       To verify that you have the correct URL, use the virsh(1) command to
229       list the guests on the server:
230
231        $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' list --all
232        Enter root's password for vcenter.example.com: ***
233
234         Id    Name                           State
235        ----------------------------------------------------
236         -     Fedora 20                      shut off
237         -     Windows 2003                   shut off
238
239       If you get an error "Peer certificate cannot be authenticated with
240       given CA certificates" or similar, then you can either import the
241       vCenter host’s certificate, or bypass signature verification by adding
242       the "?no_verify=1" flag:
243
244        $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' list --all
245
246       You should also try dumping the metadata from any guest on your server,
247       like this:
248
249        $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' dumpxml "Windows 2003"
250        <domain type='vmware'>
251          <name>Windows 2003</name>
252          [...]
253          <vmware:moref>vm-123</vmware:moref>
254        </domain>
255
256       If "<vmware:moref>" does not appear in the metadata, then you need to
257       upgrade libvirt.
258
259       If the above commands do not work, then virt-v2v is not going to work
260       either.  Fix your URI and/or your VMware server before continuing.
261
262   VDDK: Importing a guest
263       The -it vddk parameter selects VDDK as the input transport for disks.
264
265       To import a particular guest from vCenter server or ESXi hypervisor,
266       use a command like the following, substituting the URI, guest name and
267       SSL thumbprint:
268
269        $ export PATH=/path/to/nbdkit-1.1.x:$PATH
270        $ virt-v2v \
271            -ic 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' \
272            -it vddk \
273            -io vddk-libdir=/path/to/vmware-vix-disklib-distrib \
274            -io vddk-thumbprint=xx:xx:xx:... \
275            "Windows 2003" \
276            -o local -os /var/tmp
277
278       Other options that you might need to add in rare circumstances include
279       -io vddk-config, -io vddk-cookie, -io vddk-nfchostport, -io vddk-port,
280       -io vddk-snapshot, and -io vddk-transports, which are all explained in
281       the nbdkit-vddk-plugin(1) documentation.  Do not use these options
282       unless you know what you are doing.
283
284   VDDK: Debugging VDDK failures
285       The VDDK library can be operated in a verbose mode where it gives
286       (very) verbose messages.  Use ‘virt-v2v -v -x’ as usual to enable
287       verbose messages.
288

INPUT FROM VMWARE OVA

290       Virt-v2v is able to import guests from VMware’s OVA (Open
291       Virtualization Appliance) files.  Only OVAs exported from VMware
292       vSphere will work.
293
294   OVA: Remove VMware tools from Windows guests
295       For Windows guests, you should remove VMware tools before conversion.
296       Although this is not strictly necessary, and the guest will still be
297       able to run, if you don't do this then the converted guest will
298       complain on every boot.  The tools cannot be removed after conversion
299       because the uninstaller checks if it is running on VMware and refuses
300       to start (which is also the reason that virt-v2v cannot remove them).
301
302       This is not necessary for Linux guests, as virt-v2v is able to remove
303       VMware tools.
304
305   OVA: Create OVA
306       To create an OVA in vSphere, use the "Export OVF Template" option (from
307       the VM context menu, or from the File menu).  Either "Folder of files"
308       (OVF) or "Single file" (OVA) will work, but OVA is probably easier to
309       deal with.  OVA files are really just uncompressed tar files, so you
310       can use commands like "tar tf VM.ova" to view their contents.
311
312       Create OVA with ovftool
313
314       You can also use VMware’s proprietary "ovftool":
315
316        ovftool --noSSLVerify \
317          vi://USER:PASSWORD@esxi.example.com/VM \
318          VM.ova
319
320       To connect to vCenter:
321
322        ovftool  --noSSLVerify \
323          vi://USER:PASSWORD@vcenter.example.com/DATACENTER-NAME/vm/VM \
324          VM.ova
325
326       For Active Directory-aware authentication, you have to express the "@"
327       character in the form of its ascii hex-code (%5c):
328
329        vi://DOMAIN%5cUSER:PASSWORD@...
330
331   OVA: Importing a guest
332       To import an OVA file called VM.ova, do:
333
334        $ virt-v2v -i ova VM.ova -o local -os /var/tmp
335
336       If you exported the guest as a "Folder of files", or if you unpacked
337       the OVA tarball yourself, then you can point virt-v2v at the directory
338       containing the files:
339
340        $ virt-v2v -i ova /path/to/files -o local -os /var/tmp
341

INPUT FROM VMWARE VCENTER SERVER

343       Virt-v2v is able to import guests from VMware vCenter Server.
344
345       vCenter ≥ 5.0 is required.  If you don’t have vCenter, using OVA or VMX
346       is recommended instead (see "INPUT FROM VMWARE OVA" and/or "INPUT FROM
347       VMWARE VMX").
348
349       Virt-v2v uses libvirt for access to vCenter, and therefore the input
350       mode should be -i libvirt.  As this is the default, you don't need to
351       specify it on the command line.
352
353   vCenter: Remove VMware tools from Windows guests
354       For Windows guests, you should remove VMware tools before conversion.
355       Although this is not strictly necessary, and the guest will still be
356       able to run, if you don't do this then the converted guest will
357       complain on every boot.  The tools cannot be removed after conversion
358       because the uninstaller checks if it is running on VMware and refuses
359       to start (which is also the reason that virt-v2v cannot remove them).
360
361       This is not necessary for Linux guests, as virt-v2v is able to remove
362       VMware tools.
363
364   vCenter: URI
365       The libvirt URI of a vCenter server looks something like this:
366
367        vpx://user@server/Datacenter/esxi
368
369       where:
370
371       "user@"
372           is the (optional, but recommended) user to connect as.
373
374           If the username contains a backslash (eg. "DOMAIN\USER") then you
375           will need to URI-escape that character using %5c: "DOMAIN%5cUSER"
376           (5c is the hexadecimal ASCII code for backslash.)  Other
377           punctuation may also have to be escaped.
378
379       "server"
380           is the vCenter Server (not hypervisor).
381
382       "Datacenter"
383           is the name of the datacenter.
384
385           If the name contains a space, replace it with the URI-escape code
386           %20.
387
388       "esxi"
389           is the name of the ESXi hypervisor running the guest.
390
391       If the VMware deployment is using folders, then these may need to be
392       added to the URI, eg:
393
394        vpx://user@server/Folder/Datacenter/esxi
395
396       For full details of libvirt URIs, see: http://libvirt.org/drvesx.html
397
398       Typical errors from libvirt / virsh when the URI is wrong include:
399
400       ·   Could not find datacenter specified in [...]
401
402       ·   Could not find compute resource specified in [...]
403
404       ·   Path [...] does not specify a compute resource
405
406       ·   Path [...] does not specify a host system
407
408       ·   Could not find host system specified in [...]
409
410   vCenter: Test libvirt connection to vCenter
411       Use the virsh(1) command to list the guests on the vCenter Server like
412       this:
413
414        $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' list --all
415        Enter root's password for vcenter.example.com: ***
416
417         Id    Name                           State
418        ----------------------------------------------------
419         -     Fedora 20                      shut off
420         -     Windows 2003                   shut off
421
422       If you get an error "Peer certificate cannot be authenticated with
423       given CA certificates" or similar, then you can either import the
424       vCenter host’s certificate, or bypass signature verification by adding
425       the "?no_verify=1" flag:
426
427        $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' list --all
428
429       You should also try dumping the metadata from any guest on your server,
430       like this:
431
432        $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' dumpxml "Windows 2003"
433        <domain type='vmware'>
434          <name>Windows 2003</name>
435          [...]
436        </domain>
437
438       If the above commands do not work, then virt-v2v is not going to work
439       either.  Fix your libvirt configuration and/or your VMware vCenter
440       Server before continuing.
441
442   vCenter: Importing a guest
443       To import a particular guest from vCenter Server, do:
444
445        $ virt-v2v -ic 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' \
446          "Windows 2003" \
447          -o local -os /var/tmp
448
449       where "Windows 2003" is the name of the guest (which must be shut
450       down).
451
452       Note that you may be asked for the vCenter password twice.  This
453       happens once because libvirt needs it, and a second time because
454       virt-v2v itself connects directly to the server.  Use -ip filename to
455       supply a password via a file.
456
457       In this case the output flags are set to write the converted guest to a
458       temporary directory as this is just an example, but you can also write
459       to libvirt or any other supported target.
460
461   vCenter: Non-administrator role
462       Instead of using the vCenter Administrator role, you can create a
463       custom non-administrator role to perform the conversion.  You will
464       however need to give it a minimum set of permissions as follows (using
465       VMware vCenter 6.5):
466
467       1.  Create a custom role in vCenter.
468
469       2.  Enable (check) the following objects:
470
471            Datastore:
472             - Browse datastore
473             - Low level file operations
474
475            Sessions:
476             - Validate session
477
478            Virtual Machine:
479              Interaction:
480                - Guest operating system management by VIX API
481              Provisioning:
482                - Allow disk access
483                - Allow read-only disk access
484
485   vCenter: Firewall and proxy settings
486       vCenter: Ports
487
488       If there is a firewall between the virt-v2v conversion server and the
489       vCenter server, then you will need to open port 443 (https) and port
490       5480.
491
492       Port 443 is used to copy the guest disk image(s).  Port 5480 is used to
493       query vCenter for guest metadata.
494
495       These port numbers are only the defaults.  It is possible to
496       reconfigure vCenter to use other port numbers.  In that case you would
497       need to specify those ports in the "vpx://" URI.  See "vCenter: URI"
498       above.
499
500       These ports only apply to virt-v2v conversions.  You may have to open
501       other ports for other vCenter functionality, for example the web user
502       interface.  VMware documents the required ports for vCenter in their
503       online documentation.
504
505        ┌────────────┐   port 443 ┌────────────┐        ┌────────────┐
506        │ virt-v2v   │────────────▶ vCenter    │────────▶ ESXi       │
507        │ conversion │────────────▶ server     │        │ hypervisor │
508        │ server     │  port 5480 │            │        │   ┌─────┐  │
509        └────────────┘            └────────────┘        │   │guest│  │
510                                                        └───┴─────┴──┘
511
512       (In the diagram above the arrows show the direction in which the TCP
513       connection is initiated, not necessarily the direction of data
514       transfer.)
515
516       Virt-v2v itself does not connect directly to the ESXi hypervisor
517       containing the guest.  However vCenter connects to the hypervisor and
518       forwards the information, so if you have a firewall between vCenter and
519       its hypervisors you may need to open additional ports (consult VMware
520       documentation).
521
522       The proxy environment variables ("https_proxy", "all_proxy",
523       "no_proxy", "HTTPS_PROXY", "ALL_PROXY" and "NO_PROXY") are ignored when
524       doing vCenter conversions.
525
526   vCenter: SSL/TLS certificate problems
527       You may see this error:
528
529         CURL: Error opening file: SSL: no alternative certificate subject
530         name matches target host name
531
532       (You may need to enable debugging with ‘virt-v2v -v -x’ to see this
533       message).
534
535       This can be caused by using an IP address instead of the fully-
536       qualified DNS domain name of the vCenter server, ie.  use
537       "vpx://vcenter.example.com/..." instead of "vpx://11.22.33.44/..."
538
539       Another certificate problem can be caused by the vCenter server having
540       a mismatching FQDN and IP address, for example if the server acquired a
541       new IP address from DHCP.  To fix this you need to change your DHCP
542       server or network configuration so that the vCenter server always gets
543       a stable IP address.  After that log in to the vCenter server’s admin
544       console at "https://vcenter:5480/".  Under the "Admin" tab, select
545       "Certificate regeneration enabled" and then reboot it.
546

SEE ALSO

548       virt-v2v(1).
549

AUTHOR

551       Richard W.M. Jones
552
554       Copyright (C) 2009-2019 Red Hat Inc.
555

LICENSE

557       This program is free software; you can redistribute it and/or modify it
558       under the terms of the GNU General Public License as published by the
559       Free Software Foundation; either version 2 of the License, or (at your
560       option) any later version.
561
562       This program is distributed in the hope that it will be useful, but
563       WITHOUT ANY WARRANTY; without even the implied warranty of
564       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
565       General Public License for more details.
566
567       You should have received a copy of the GNU General Public License along
568       with this program; if not, write to the Free Software Foundation, Inc.,
569       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
570

BUGS

572       To get a list of bugs against libguestfs, use this link:
573       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
574
575       To report a new bug against libguestfs, use this link:
576       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
577
578       When reporting a bug, please supply:
579
580       ·   The version of libguestfs.
581
582       ·   Where you got libguestfs (eg. which Linux distro, compiled from
583           source, etc)
584
585       ·   Describe the bug accurately and give a way to reproduce it.
586
587       ·   Run libguestfs-test-tool(1) and paste the complete, unedited output
588           into the bug report.
589
590
591
592libguestfs-1.40.2                 2019-02-07          virt-v2v-input-vmware(1)
Impressum