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

DESCRIPTION

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

INPUT FROM VMWARE VMX

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

INPUT FROM VDDK

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

INPUT FROM VMWARE OVA

272       Virt-v2v is able to import guests from VMware’s OVA (Open
273       Virtualization Appliance) files.  Only OVAs exported from VMware
274       vSphere will work.
275
276   OVA: Create OVA
277       To create an OVA in vSphere, use the "Export OVF Template" option (from
278       the VM context menu, or from the File menu).  Either "Folder of files"
279       (OVF) or "Single file" (OVA) will work, but OVA is probably easier to
280       deal with.  OVA files are really just uncompressed tar files, so you
281       can use commands like "tar tf VM.ova" to view their contents.
282
283       Create OVA with ovftool
284
285       You can also use VMware’s proprietary "ovftool":
286
287        ovftool --noSSLVerify \
288          vi://USER:PASSWORD@esxi.example.com/VM \
289          VM.ova
290
291       To connect to vCenter:
292
293        ovftool  --noSSLVerify \
294          vi://USER:PASSWORD@vcenter.example.com/DATACENTER-NAME/vm/VM \
295          VM.ova
296
297       For Active Directory-aware authentication using down-level logon names
298       ("DOMAIN\USER"), you have to express the "\" character in the form of
299       its ascii hex-code (%5c):
300
301        vi://DOMAIN%5cUSER:PASSWORD@...
302
303   OVA: Importing a guest
304       To import an OVA file called VM.ova, do:
305
306        $ virt-v2v -i ova VM.ova -o local -os /var/tmp
307
308       If you exported the guest as a "Folder of files", or if you unpacked
309       the OVA tarball yourself, then you can point virt-v2v at the directory
310       containing the files:
311
312        $ virt-v2v -i ova /path/to/files -o local -os /var/tmp
313

INPUT FROM VMWARE VCENTER SERVER

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

SEE ALSO

523       virt-v2v(1).
524

AUTHOR

526       Richard W.M. Jones
527
529       Copyright (C) 2009-2020 Red Hat Inc.
530

LICENSE

532       This program is free software; you can redistribute it and/or modify it
533       under the terms of the GNU General Public License as published by the
534       Free Software Foundation; either version 2 of the License, or (at your
535       option) any later version.
536
537       This program is distributed in the hope that it will be useful, but
538       WITHOUT ANY WARRANTY; without even the implied warranty of
539       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
540       General Public License for more details.
541
542       You should have received a copy of the GNU General Public License along
543       with this program; if not, write to the Free Software Foundation, Inc.,
544       51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
545

BUGS

547       To get a list of bugs against libguestfs, use this link:
548       https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
549
550       To report a new bug against libguestfs, use this link:
551       https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
552
553       When reporting a bug, please supply:
554
555       •   The version of libguestfs.
556
557       •   Where you got libguestfs (eg. which Linux distro, compiled from
558           source, etc)
559
560       •   Describe the bug accurately and give a way to reproduce it.
561
562       •   Run libguestfs-test-tool(1) and paste the complete, unedited output
563           into the bug report.
564
565
566
567virt-v2v-1.45.91                  2021-11-23          virt-v2v-input-vmware(1)
Impressum