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 '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
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
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
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
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
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
548 virt-v2v(1).
549
551 Richard W.M. Jones
552
554 Copyright (C) 2009-2019 Red Hat Inc.
555
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
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)