1virt-v2v-input-vmware(1) Virtualization Support virt-v2v-input-vmware(1)
2
3
4
6 virt-v2v-input-vmware - Using virt-v2v to convert guests from VMware
7
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 -ip passwordfile
30 "GUEST NAME" [-o* options]
31
33 This page documents how to use virt-v2v(1) to convert guests from
34 VMware. There are currently five different methods to access VMware:
35
36 -i vmx GUEST.vmx
37 Full documentation: "INPUT FROM VMWARE VMX"
38
39 If you either have a GUEST.vmx file and one or more GUEST.vmdk disk
40 image files, or if you are able to NFS-mount the VMware storage,
41 then you can use the -i vmx method to read the source guest.
42
43 -i vmx -it ssh ssh://...
44 Full documentation: "INPUT FROM VMWARE VMX"
45
46 This is similar to the method above, except it uses an SSH
47 connection to ESXi to read the GUEST.vmx file and associated disks.
48 This requires that you have enabled SSH access to the VMware ESXi
49 hypervisor - in the default ESXi configuration this is turned off.
50
51 This transport is incompatible with guests that have snapshots;
52 refer to "NOTES".
53
54 -ic vpx://... -it vddk
55 -ic esx://... -it vddk
56 Full documentation: "INPUT FROM VDDK"
57
58 This method uses the proprietary VDDK library (a.k.a. VixDiskLib)
59 to access the VMware vCenter server or VMware ESXi hypervisor.
60
61 If you have the proprietary library then this method is usually the
62 fastest and most flexible. If you don't have or don't want to use
63 non-free software then the VMX or SSH methods above will be best.
64
65 -i ova DISK.ova
66 Full documentation: "INPUT FROM VMWARE OVA"
67
68 With this method you must first export the guest (eg. from vSphere)
69 as an .ova file, which virt-v2v can then read directly. Note this
70 method only works with files exported from VMware, not OVA files
71 that come from other hypervisors or management systems, since OVA
72 is only a pretend standard and is not compatible or interoperable
73 between vendors.
74
75 -ic vpx://... "GUEST NAME"
76 Full documentation: "INPUT FROM VMWARE VCENTER SERVER"
77
78 If none of the above methods is available, then use this method to
79 import a guest from VMware vCenter. This is the slowest method.
80
82 When accessing the guest.vmx file on ESXi over an SSH connection (that
83 is, when using the -i vmx -it ssh options), the conversion will not
84 work if the guest has snapshots (files called guest-000001.vmdk and
85 similar). Either collapse the snapshots for the guest and retry the
86 conversion with the same -i vmx -it ssh options, or leave the snapshots
87 intact and use a transport different from SSH: just -i vmx, or -ic
88 vpx://... -it vddk or -ic esx://... -it vddk. Refer to
89 https://bugzilla.redhat.com/1774386.
90
92 Virt-v2v is able to import guests from VMware’s vmx files.
93
94 This is useful in two cases:
95
96 1. VMware virtual machines are stored on a separate NFS server and you
97 are able to mount the NFS storage directly.
98
99 2. You have enabled SSH access to the VMware ESXi hypervisor and there
100 is a "/vmfs/volumes" folder containing the virtual machines.
101
102 If you find a folder of files called guest.vmx, guest.vmxf, guest.nvram
103 and one or more .vmdk disk images, then you can use this method. The
104 SSH transport is not usable if the guest has snapshots; refer to
105 "NOTES".
106
107 VMX: Guest must be shut down
108 The guest must be shut down before conversion starts. If you don't
109 shut it down, you will end up with a corrupted VM disk on the target.
110 With other methods, virt-v2v tries to prevent concurrent access, but
111 because the -i vmx method works directly against the storage, checking
112 for concurrent access is not possible.
113
114 VMX: Access to the storage containing the VMX and VMDK files
115 If the vmx and vmdk files aren't available locally then you must either
116 mount the NFS storage on the conversion server or enable passwordless
117 SSH on the ESXi hypervisor.
118
119 VMX: SSH authentication
120
121 You can use SSH password authentication, by supplying the name of a
122 file containing the password to the -ip option (note this option does
123 not take the password directly). You may need to adjust
124 /etc/ssh/sshd_config on the VMware server to set
125 "PasswordAuthentication yes".
126
127 If you are not using password authentication, an alternative is to use
128 ssh-agent, and add your ssh public key to
129 /etc/ssh/keys-root/authorized_keys (on the ESXi hypervisor). After
130 doing this, you should check that passwordless access works from the
131 virt-v2v server to the ESXi hypervisor. For example:
132
133 $ ssh root@esxi.example.com
134 [ logs straight into the shell, no password is requested ]
135
136 Note that support for non-interactive authentication via the -ip option
137 is incomplete. Some operations remain that still require the user to
138 enter the password manually. Therefore ssh-agent is recommended over
139 the -ip option. See https://bugzilla.redhat.com/1854275.
140
141 VMX: Construct the SSH URI
142
143 When using the SSH input transport you must specify a remote
144 "ssh://..." URI pointing to the VMX file. A typical URI looks like:
145
146 ssh://root@esxi.example.com/vmfs/volumes/datastore1/my%20guest/my%20guest.vmx
147
148 The username is not required if it is the same as your local username.
149
150 You may optionally supply a port number after the hostname if the SSH
151 server is not listening on the default port (22).
152
153 For determining the pathname component of the URI, log in to the ESXi
154 server via SSH interactively, and identify the absolute pathname of the
155 VMX file on the ESXi server, such as:
156
157 /vmfs/volumes/datastore1/my guest/my guest.vmx
158
159 Subsequently, on the virt-v2v command line, percent-encode any reserved
160 characters that you find in the individual pathname components. For
161 example, space characters must be specified as %20:
162
163 /vmfs/volumes/datastore1/my%20guest/my%20guest.vmx
164
165 Refer to https://bugzilla.redhat.com/1938954.
166
167 VMX: Importing a guest
168 To import a vmx file from a local file or NFS, do:
169
170 $ virt-v2v -i vmx guest.vmx -o local -os /var/tmp
171
172 To import a vmx file over SSH, add -it ssh to select the SSH transport
173 and supply a remote SSH URI:
174
175 $ virt-v2v \
176 -i vmx -it ssh \
177 "ssh://root@esxi.example.com/vmfs/volumes/datastore1/guest/guest.vmx" \
178 -o local -os /var/tmp
179
180 Virt-v2v processes the vmx file and uses it to find the location of any
181 vmdk disks.
182
184 Virt-v2v is able to import guests using VMware’s proprietary VDDK
185 library (a.k.a. VixDiskLib).
186
187 VDDK: Prerequisites
188 1. As the VDDK library is not open source, and the license of this
189 library does not permit redistribution or commercial use, you must
190 obtain VDDK yourself and satisfy yourself that your usage of the
191 library is permitted by the license.
192
193 2. nbdkit ≥ 1.6 is recommended, as it ships with the VDDK plugin
194 enabled unconditionally.
195
196 3. You must find the SSL "thumbprint" of your VMware server. How to
197 do this is explained in nbdkit-vddk-plugin(1), also available at
198 the link above.
199
200 4. VDDK imports require a feature added in libvirt ≥ 3.7.
201
202 VDDK: ESXi NFC service memory limits
203 In the verbose log you may see errors like:
204
205 nbdkit: vddk[3]: error: [NFC ERROR] NfcFssrvrProcessErrorMsg:
206 received NFC error 5 from server: Failed to allocate the
207 requested 2097176 bytes
208
209 This seems especially common when there are multiple parallel
210 connections open to the VMware server.
211
212 These can be caused by resource limits set on the VMware server. You
213 can increase the limit for the NFC service by editing
214 /etc/vmware/hostd/config.xml and adjusting the "<maxMemory>" setting:
215
216 <nfcsvc>
217 <path>libnfcsvc.so</path>
218 <enabled>true</enabled>
219 <maxMemory>50331648</maxMemory>
220 <maxStreamMemory>10485760</maxStreamMemory>
221 </nfcsvc>
222
223 and restarting the "hostd" service:
224
225 # /etc/init.d/hostd restart
226
227 For more information see https://bugzilla.redhat.com/1614276.
228
229 VDDK: "error: VixDiskLibVim: Failed to open disk using NFC. VixError 1"
230 If you see an error similar to:
231
232 nbdkit: vddk[2]: error: VixDiskLibVim: Failed to open disk using NFC. VixError 1 at 1166.
233
234 then it is caused by a bug in VDDK ≤ 6.7. The suggested solution it to
235 upgrade to the latest VDDK. See also
236 https://bugzilla.redhat.com/1684075
237
238 VDDK: URI
239 Construct the correct "vpx://" (for vCenter) or "esx://" (for ESXi)
240 URL. It will look something like these:
241
242 vpx://root@vcenter.example.com/Datacenter/esxi
243
244 esx://root@esxi.example.com
245
246 To verify that you have the correct URL, use the virsh(1) command to
247 list the guests on the server:
248
249 $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' list --all
250 Enter root's password for vcenter.example.com: ***
251
252 Id Name State
253 ----------------------------------------------------
254 - Fedora 20 shut off
255 - Windows 2003 shut off
256
257 If you get an error "Peer certificate cannot be authenticated with
258 given CA certificates" or similar, then you can either import the
259 vCenter host’s certificate, or bypass signature verification by adding
260 the "?no_verify=1" flag:
261
262 $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' list --all
263
264 You should also try dumping the metadata from any guest on your server,
265 like this:
266
267 $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' dumpxml "Windows 2003"
268 <domain type='vmware'>
269 <name>Windows 2003</name>
270 [...]
271 <vmware:moref>vm-123</vmware:moref>
272 </domain>
273
274 If "<vmware:moref>" does not appear in the metadata, then you need to
275 upgrade libvirt.
276
277 If the above commands do not work, then virt-v2v is not going to work
278 either. Fix your URI and/or your VMware server before continuing.
279
280 VDDK: Importing a guest
281 The -it vddk parameter selects VDDK as the input transport for disks.
282
283 To import a particular guest from vCenter server or ESXi hypervisor,
284 use a command like the following, substituting the URI, guest name and
285 SSL thumbprint:
286
287 $ virt-v2v \
288 -ic 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' \
289 -it vddk \
290 -io vddk-libdir=/path/to/vmware-vix-disklib-distrib \
291 -io vddk-thumbprint=xx:xx:xx:... \
292 "Windows 2003" \
293 -o local -os /var/tmp
294
295 Other options that you might need to add in rare circumstances include
296 -io vddk-config, -io vddk-cookie, -io vddk-nfchostport, -io vddk-port,
297 -io vddk-snapshot, and -io vddk-transports, which are all explained in
298 the nbdkit-vddk-plugin(1) documentation. Do not use these options
299 unless you know what you are doing.
300
301 VDDK: Debugging VDDK failures
302 The VDDK library can be operated in a verbose mode where it gives
303 (very) verbose messages. Use ‘virt-v2v -v -x’ as usual to enable
304 verbose messages.
305
306 VDDK: Slow imports and repeated NBD_ClientOpen messages
307 If imports over VDDK are slow, and ‘virt-v2v -v -x’ shows many
308 "NBD_ClientOpen" messages, then you are hitting an apparent bug in
309 VDDK 6.7 (https://bugzilla.redhat.com/1901489). Upgrade to at least
310 VDDK 7 to resolve the issue.
311
313 Virt-v2v is able to import guests from VMware’s OVA (Open
314 Virtualization Appliance) files. Only OVAs exported from VMware
315 vSphere will work.
316
317 OVA: Create OVA
318 To create an OVA in vSphere, use the "Export OVF Template" option (from
319 the VM context menu, or from the File menu). Either "Folder of files"
320 (OVF) or "Single file" (OVA) will work, but OVA is probably easier to
321 deal with. OVA files are really just uncompressed tar files, so you
322 can use commands like "tar tf VM.ova" to view their contents.
323
324 Create OVA with ovftool
325
326 You can also use VMware’s proprietary "ovftool":
327
328 ovftool --noSSLVerify \
329 vi://USER:PASSWORD@esxi.example.com/VM \
330 VM.ova
331
332 To connect to vCenter:
333
334 ovftool --noSSLVerify \
335 vi://USER:PASSWORD@vcenter.example.com/DATACENTER-NAME/vm/VM \
336 VM.ova
337
338 For Active Directory-aware authentication using down-level logon names
339 ("DOMAIN\USER"), you have to express the "\" character in the form of
340 its ascii hex-code (%5c):
341
342 vi://DOMAIN%5cUSER:PASSWORD@...
343
344 OVA: Importing a guest
345 To import an OVA file called VM.ova, do:
346
347 $ virt-v2v -i ova VM.ova -o local -os /var/tmp
348
349 If you exported the guest as a "Folder of files", or if you unpacked
350 the OVA tarball yourself, then you can point virt-v2v at the directory
351 containing the files:
352
353 $ virt-v2v -i ova /path/to/files -o local -os /var/tmp
354
355 OVA: Permissions issues with oVirt/RHV import
356 oVirt/RHV provides a graphical user interface for importing from OVA
357 files which uses this method. It requires that RHV is able to access
358 the OVA file which can be a problem if the file is owned by root (RHV
359 runs as a non-root user).
360
361 The suggested workaround is to copy the OVA to a public directory such
362 as /var/tmp before doing the import and perhaps change the user and
363 group ownership of the file.
364
365 For more information see these links:
366
367 • https://access.redhat.com/documentation/en-us/red_hat_virtualization/4.4/html-single/virtual_machine_management_guide/index#Importing_a_virtual_machine_from_a_host
368
369 • https://bugzilla.redhat.com/show_bug.cgi?id=2039597
370
372 Virt-v2v is able to import guests from VMware vCenter Server.
373
374 vCenter ≥ 5.0 is required. If you don’t have vCenter, using OVA or VMX
375 is recommended instead (see "INPUT FROM VMWARE OVA" and/or "INPUT FROM
376 VMWARE VMX").
377
378 Virt-v2v uses libvirt for access to vCenter, and therefore the input
379 mode should be -i libvirt. As this is the default, you don't need to
380 specify it on the command line.
381
382 vCenter: URI
383 The libvirt URI of a vCenter server looks something like this:
384
385 vpx://user@server/Datacenter/esxi
386
387 where:
388
389 "user@"
390 is the (optional, but recommended) user to connect as.
391
392 If the username contains a backslash (eg. "DOMAIN\USER") then you
393 will need to URI-escape that character using %5c: "DOMAIN%5cUSER"
394 (5c is the hexadecimal ASCII code for backslash.) Other
395 punctuation may also have to be escaped.
396
397 The user's password must be supplied in a local file using the
398 separate -ip parameter.
399
400 "server"
401 is the vCenter Server (not hypervisor).
402
403 "Datacenter"
404 is the name of the datacenter.
405
406 If the name contains a space, replace it with the URI-escape code
407 %20.
408
409 "esxi"
410 is the name of the ESXi hypervisor running the guest.
411
412 If the VMware deployment is using folders, then these may need to be
413 added to the URI, eg:
414
415 vpx://user@server/Folder/Datacenter/esxi
416
417 For full details of libvirt URIs, see: http://libvirt.org/drvesx.html
418
419 Typical errors from libvirt / virsh when the URI is wrong include:
420
421 • Could not find datacenter specified in [...]
422
423 • Could not find compute resource specified in [...]
424
425 • Path [...] does not specify a compute resource
426
427 • Path [...] does not specify a host system
428
429 • Could not find host system specified in [...]
430
431 vCenter: Test libvirt connection to vCenter
432 Use the virsh(1) command to list the guests on the vCenter Server like
433 this:
434
435 $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' list --all
436 Enter root's password for vcenter.example.com: ***
437
438 Id Name State
439 ----------------------------------------------------
440 - Fedora 20 shut off
441 - Windows 2003 shut off
442
443 If you get an error "Peer certificate cannot be authenticated with
444 given CA certificates" or similar, then you can either import the
445 vCenter host’s certificate, or bypass signature verification by adding
446 the "?no_verify=1" flag:
447
448 $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' list --all
449
450 You should also try dumping the metadata from any guest on your server,
451 like this:
452
453 $ virsh -c 'vpx://root@vcenter.example.com/Datacenter/esxi' dumpxml "Windows 2003"
454 <domain type='vmware'>
455 <name>Windows 2003</name>
456 [...]
457 </domain>
458
459 If the above commands do not work, then virt-v2v is not going to work
460 either. Fix your libvirt configuration and/or your VMware vCenter
461 Server before continuing.
462
463 vCenter: Supplying the password
464 The vCenter password (usually for the root account, or the account
465 specified by "user@" in the vpx URL) has to be written to a local file,
466 and the name of that file specified on the virt-v2v command line using
467 -ip passwordfile.
468
469 vCenter: Importing a guest
470 To import a particular guest from vCenter Server, do:
471
472 $ virt-v2v -ic 'vpx://root@vcenter.example.com/Datacenter/esxi?no_verify=1' \
473 -ip passwordfile \
474 "Windows 2003" \
475 -o local -os /var/tmp
476
477 where "Windows 2003" is the name of the guest (which must be shut
478 down).
479
480 In this case the output flags are set to write the converted guest to a
481 temporary directory as this is just an example, but you can also write
482 to libvirt or any other supported target.
483
484 vCenter: Non-administrator role
485 Instead of using the vCenter Administrator role, you can create a
486 custom non-administrator role to perform the conversion. You will
487 however need enable the following permissions (or as many as are
488 available, older versions of VMware were missing some of these
489 settings):
490
491 1. Create a custom role in vCenter.
492
493 2. Enable (check) the following objects:
494
495 Datastore:
496 - Browse datastore
497 - Low level file operations
498
499 Sessions:
500 - Validate session
501
502 Virtual Machine:
503 Interaction:
504 - Guest operating system management by VIX API
505 Provisioning:
506 - Allow disk access
507 - Allow read-only disk access
508 - Allow virtual machine download
509
510 Cryptographic operations:
511 - Decrypt
512 - Direct Access
513
514 vCenter: Firewall and proxy settings
515 vCenter: Ports
516
517 If there is a firewall between the virt-v2v conversion server and the
518 vCenter server, then you will need to open port 443 (https) and port
519 5480.
520
521 Port 443 is used to copy the guest disk image(s). Port 5480 is used to
522 query vCenter for guest metadata.
523
524 These port numbers are only the defaults. It is possible to
525 reconfigure vCenter to use other port numbers. In that case you would
526 need to specify those ports in the "vpx://" URI. See "vCenter: URI"
527 above.
528
529 These ports only apply to virt-v2v conversions. You may have to open
530 other ports for other vCenter functionality, for example the web user
531 interface. VMware documents the required ports for vCenter in their
532 online documentation.
533
534 ┌────────────┐ port 443 ┌────────────┐ ┌────────────┐
535 │ virt-v2v │────────────▶ vCenter │────────▶ ESXi │
536 │ conversion │────────────▶ server │ │ hypervisor │
537 │ server │ port 5480 │ │ │ ┌─────┐ │
538 └────────────┘ └────────────┘ │ │guest│ │
539 └───┴─────┴──┘
540
541 (In the diagram above the arrows show the direction in which the TCP
542 connection is initiated, not necessarily the direction of data
543 transfer.)
544
545 Virt-v2v itself does not connect directly to the ESXi hypervisor
546 containing the guest. However vCenter connects to the hypervisor and
547 forwards the information, so if you have a firewall between vCenter and
548 its hypervisors you may need to open additional ports (consult VMware
549 documentation).
550
551 The proxy environment variables ("https_proxy", "all_proxy",
552 "no_proxy", "HTTPS_PROXY", "ALL_PROXY" and "NO_PROXY") are ignored when
553 doing vCenter conversions.
554
555 vCenter: SSL/TLS certificate problems
556 You may see this error:
557
558 CURL: Error opening file: SSL: no alternative certificate subject
559 name matches target host name
560
561 (You may need to enable debugging with ‘virt-v2v -v -x’ to see this
562 message).
563
564 This can be caused by using an IP address instead of the fully-
565 qualified DNS domain name of the vCenter server, ie. use
566 "vpx://vcenter.example.com/..." instead of "vpx://11.22.33.44/..."
567
568 Another certificate problem can be caused by the vCenter server having
569 a mismatching FQDN and IP address, for example if the server acquired a
570 new IP address from DHCP. To fix this you need to change your DHCP
571 server or network configuration so that the vCenter server always gets
572 a stable IP address. After that log in to the vCenter server’s admin
573 console at "https://vcenter:5480/". Under the "Admin" tab, select
574 "Certificate regeneration enabled" and then reboot it.
575
576 vCenter: "Out of HTTP sessions: Limited to ..."
577 VMware vCenter appears to limit HTTP sessions and in some circumstances
578 virt-v2v may exceed this number. You can adjust or remove the limit by
579 editing /etc/vmware-vpx/vpxd.cfg on the vCenter server. Increase the
580 "<maxSessionCount>" field, or set it to 0 which makes it unlimited:
581
582 <soap>
583 <maxSessionCount>0</maxSessionCount>
584 </soap>
585
587 virt-v2v(1).
588
590 Richard W.M. Jones
591
593 Copyright (C) 2009-2020 Red Hat Inc.
594
596 This program is free software; you can redistribute it and/or modify it
597 under the terms of the GNU General Public License as published by the
598 Free Software Foundation; either version 2 of the License, or (at your
599 option) any later version.
600
601 This program is distributed in the hope that it will be useful, but
602 WITHOUT ANY WARRANTY; without even the implied warranty of
603 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
604 General Public License for more details.
605
606 You should have received a copy of the GNU General Public License along
607 with this program; if not, write to the Free Software Foundation, Inc.,
608 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
609
611 To get a list of bugs against libguestfs, use this link:
612 https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
613
614 To report a new bug against libguestfs, use this link:
615 https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
616
617 When reporting a bug, please supply:
618
619 • The version of libguestfs.
620
621 • Where you got libguestfs (eg. which Linux distro, compiled from
622 source, etc)
623
624 • Describe the bug accurately and give a way to reproduce it.
625
626 • Run libguestfs-test-tool(1) and paste the complete, unedited output
627 into the bug report.
628
629
630
631virt-v2v-2.2.0 2023-01-10 virt-v2v-input-vmware(1)