1VIRT-V2V(1) User Contributed Perl Documentation VIRT-V2V(1)
2
6 virt-v2v - Convert a guest to use KVM
7
9 virt-v2v -i libvirtxml -os imported --network default guest-domain.xml
10 virt-v2v -ic esx://esx.server/ -os imported --network default esx_guest
12 virt-v2v -ic esx://esx.server/ \
14 -o rhev -os rhev.nfs.storage:/export_domain --network rhevm \
15 esx_guest
16
18 virt-v2v converts guests from a foreign hypervisor to run on KVM,
19 managed by libvirt or Red Hat Enterprise Virtualisation (RHEV) version
20 2.2 or later. It can currently convert Red Hat Enterprise Linux and
21 Windows guests running on Xen, VirtualBox, and VMware ESX. It will
22 enable VirtIO drivers in the converted guest if possible.
23
25 -i input
26 Specifies what input method to use to obtain the guest for
27 conversion. The default is "libvirt". Supported options are:
28 libvirt
30 Guest argument is the name of a libvirt domain.
31 libvirtxml
33 Guest argument is the path to an XML file containing a libvirt
34 domain.
35 -ic URI
37 Specifies the connection to use when using the libvirt input
38 method. If omitted, this defaults to qemu:///system when virt-v2v
39 runs as root, or qemu:///session when virt-v2v runs as a regular
40 user.
41 N.B. virt-v2v can currently automatically obtain guest storage from
43 local libvirt connections, ESX connections, and connections over
44 SSH. Other types of connection are not supported.
45 -o method
47 Specifies the output method. Supported output methods are:
48 libvirt
50 Create a libvirt guest. -os must specify a libvirt storage pool
51 for the libvirt output method.
52 Also see the -oc option.
54 rhev
56 Create a guest on a RHEV 'Export' storage domain, which can
57 later be imported into RHEV using the UI. -os must specify the
58 location of a RHEV export storage domain for the RHEV output
59 method.
60 If no output type is specified, it defaults to libvirt.
62 -oc URI
64 Specifies the libvirt connection to use to create the converted
65 guest. If omitted, this defaults to qemu:///system when virt-v2v
66 runs as root, or qemu:///session when virt-v2v runs as a regular
67 user.
68 N.B. virt-v2v must be able to write directly to storage described
70 by this libvirt connection. This makes writing to a remote
71 connection impractical at present.
72 -os storage
74 The output method dependent location where new storage will be
75 created for the converted guest.
76 For the libvirt output method, this must be the name of a storage
78 pool.
79 For the rhev output method, this specifies the NFS path to a RHEV
81 Export storage domain. Note that the storage domain must have been
82 previously initialised by RHEV. The domain must be in the format
83 <host>:<path>, eg:
84 rhev-storage.example.com:/rhev/export
86 The nfs export must be mountable and writable by the machine
88 running virt-v2v.
89 -op pool
91 See -os for the libvirt output method.
92 DEPRECATED Use -os instead.
94 -osd domain
96 See -os for the rhev output method.
97 DEPRECATED Use -os instead.
99 -of format
101 Specifies the on-disk format which will be used for the converted
102 guest. Currently supported options are raw and qcow2. If not
103 specified, the converted guest will use the same format as the
104 source guest.
105 -oa allocation
107 Specifies whether the converted guest should be sparse or
108 preallocated. If not specified, the converted guest will use the
109 same allocation scheme as the source.
110 -on outputname
112 Rename the guest.
113 If this option is not given, then the output name is the same as
115 the input name.
116 --vmtype type
118 Specify the type of guest which will be created on a RHEV target.
119 Options are desktop or server. If this option is not specified, a
120 default option will be chosen based on the detected guest operating
121 system:
122 Desktop
124 · Fedora
125 · RHEL Client/Workstation/Desktop
127 · Windows XP/Vista/7
129 Server
131 · RHEL Server/AS/ES
132 · Windows 2003/2003r2/2008/2008r2
134 If the guest OS is not detected as any of the above, it will
136 default to server.
137 -f file | --config file
139 Load a virt-v2v configuration from file. Multiple configuration
140 files can be specified, which will be searched in the order they
141 are specified on the command line. If no configuration is
142 specified, defaults to /etc/virt-v2v.conf and
143 /var/lib/virt-v2v/virt-v2v.db in that order.
144 When overriding the default config file it is recommended that
146 /var/lib/virt-v2v/virt-v2v.db is also specified, as it contains
147 default configuration data required for conversions.
148 -n network | --network network
150 Map all guest bridges or networks which don't have a mapping in the
151 configuration file to network.
152 This option cannot be used in conjunction with --bridge.
154 -b bridge | --bridge bridge
156 Map all guest bridges or networks which don't have a mapping in the
157 configuration file to bridge.
158 This option cannot be used in conjunction with --network.
160 -p profile | --profile profile
162 Take default values for output method, output storage and network
163 mappings from profile in the configuration file.
164 --root=ask
166 --root=single
167 --root=first
168 --root=/dev/sdX
169 Choose the root filesystem to be converted.
170 In the case where the virtual machine is dual-boot or multi-boot,
172 or where the VM has other filesystems that look like operating
173 systems, this option can be used to select the root filesystem
174 (a.k.a. "C: drive" or "/") of the operating system that is to be
175 converted. The Windows Recovery Console, certain attached DVD
176 drives, and bugs in libguestfs inspection heuristics, can make a
177 guest look like a multi-boot operating system.
178 The default in virt-v2v X 0.7.1 was --root=single, which causes
180 virt-v2v to die if a multi-boot operating system is found.
181 Since virt-v2v X 0.7.2 the default is now --root=ask: If the VM is
183 found to be multi-boot, then virt-v2v will stop and list the
184 possible root filesystems and ask the user which to use. This
185 requires that virt-v2v is run interactively.
186 --root=first means to choose the first root device in the case of a
188 multi-boot operating system. Since this is a heuristic, it may
189 sometimes choose the wrong one.
190 You can also name a specific root device, eg. --root=/dev/sda2
192 would mean to use the second partition on the first hard drive. If
193 the named root device does not exist or was not detected as a root
194 device, then virt-v2v will fail.
195 Note that there is a bug in grub which prevents it from
197 successfully booting a multiboot system if VirtIO is enabled. Grub
198 is only able to boot an operating system from the first VirtIO
199 disk. Specifically, /boot must be on the first VirtIO disk, and it
200 cannot chainload an OS which is not in the first VirtIO disk.
201 --list-profiles
203 Display a list of target profile names specified in the
204 configuration file.
205 --help
207 Display brief help.
208 --version
210 Display version number and exit.
211
213 Local storage requirements
214 Whenever possible, virt-v2v copies a guest's storage directly from the
215 source hypervisor to the target hypervisor without using any local
216 storage. However, this is not possible in all circumstances.
217 Specifically when transferring a guest's storage over SSH and also
218 either doing a format conversion, or changing the allocation policy of
219 qcow2 storage, virt-v2v will cache a local copy of the guest's storage.
220 By default, this local cache will be created in /tmp. If /tmp does not
221 have sufficient storage space, it can be written to another directory
222 by setting the TMPDIR environment variable.
223 Local Xen guests
225 N.B. The following is required when converting guests on a host which
226 used to run Xen, but has been updated to run KVM. It is not required
227 when converting a Xen guest imported directly from a running
228 libvirt/Xen instance.
229 virt-v2v uses a libvirt domain description to determine the current
231 configuration of the guest, including the location of its storage. This
232 should be obtained from the host running the guest pre-conversion by
233 running:
234 virsh dumpxml <domain> > <domain>.xml
236 This will require a reboot if the host running Xen is the same host
238 that will run KVM. This is because libvirt needs to connect to a
239 running xen hypervisor to obtain its metadata.
240 Local VirtualBox guests
242 The following is required when converting guests which used to run
243 VirtualBox and are being converted to KVM. The conversion needs a guest
244 XML definition file which needs to be adjusted for the guest to be
245 converted (at least name, uuid, image path, image type, and MAC
246 address):
247 qemu-img convert -O qcow2 /tmp/v-rhel.vdi /var/lib/libvirt/images/v-rhel.img
249 virsh --connect qemu:///system pool-refresh default
250 virt-cat /var/lib/libvirt/images/v-rhel.img \
251 /etc/sysconfig/network-scripts/ifcfg-eth0 | grep ^HWADDR
252 # Replace the MAC address in the guest XML definition file or adjust
253 # ifcfg-eth0 after booting up the guest to match the MAC address defined in
254 # XML file
255 virt-v2v -i libvirtxml -os default /tmp/v-rhel.xml
256 N.B. For the time being when converting VirtualBox Windows guests the
258 VirtualBox Guest Additions need to be manually uninstalled on the guest
259 when still running on VirtualBox.
260 Converting to run on libvirt/KVM
262 Create a local storage pool for transferred storage
263 virt-v2v copies the guest storage to the local machine during import.
265 When converting to run on libvirt, it creates new storage in a locally
266 defined libvirt pool. This pool can be defined using any libvirt tool,
267 and can be of any type.
268 The simplest way to create a new pool is with virt-manager(1). Pools
270 can be defined from the Storage tab under Host Details.
271 Create local network interfaces
273 The local machine must have an appropriate network for the converted
275 guest to connect to. This is likely to be a bridge interface. A bridge
276 interface can be created using standard tools on the host.
277 Since version 0.8.3, virt-manager(1) can also create and manage
279 bridges.
280 Converting to run on RHEV
282 Create an NFS export domain
283 virt-v2v can convert guests to run on RHEV 2.2 or later. It does this
285 by writing the converted guest directly to an 'Export' NFS storage
286 domain. The guest can later be imported into a RHEV Data Center through
287 the UI.
288 In RHEV 2.2, a new Export storage domain is created by clicking on 'New
290 Domain' in the Storage tab. Ensure that the Domain function is 'Export'
291 and the Storage type is 'NFS'. See the RHEV documentation for details.
292 The NFS storage domain must be mountable by the machine running
293 virt-v2v.
294 N.B. When exporting to RHEV, virt-v2v must run as root.
296 Import the appropriate Guest Tools ISO
298 When converting Windows guests, it is strongly recommended that the
300 Guest Tools ISO is installed before the guest is converted. This must
301 be done using the ISO Uploader, which can be found on your RHEV-M
302 system under Start->Red Hat->RHEV Manager->ISO Uploader. This will
303 allow RHEV to automatically update the guest's drivers to the latest
304 versions and install any required agents.
305
307 The following requires that the domain XML is available locally, and
308 that the storage referred to in the domain XML is available locally at
309 the same paths.
310 To perform the conversion, run:
312 virt-v2v -i libvirtxml -os <pool> [--network <network name>] \
314 <domain>.xml
315 where "<domain>.xml" is the path to the exported guest domain's xml,
317 and "<pool>" is the local storage pool where copies of the guest's
318 disks will be created.
319 The --network option may be provided for simple network mappings. For
321 more complex mappings, see virt-v2v.conf(5).
322 If it is not possible to provide software updates over the network in
324 your environment, software will be installed as specified in
325 virt-v2v.conf. See virt-v2v.conf(5) for details.
326 It is possible to avoid specifying replacement kernels in the virt-v2v
328 config file by ensuring that the guest has an appropriate kernel
329 installed prior to conversion. If your guest uses a Xen paravirtualised
330 kernel (it would be called something like kernel-xen or kernel-xenU),
331 you can install a regular kernel, which won't reference a hypervisor in
332 its name, alongside it. You shouldn't make this newly installed kernel
333 your default kernel because Xen may not boot it. virt-v2v will make it
334 the default during conversion.
335
337 N.B. libvirt version 0.7.0 or greater is required to connect to ESX.
338 virt-v2v can convert a guest from VMware ESX, including transferring
340 its storage.
341 N.B. virt-v2v does not transfer snapshots from ESX. Only the latest
343 flat storage is transferred.
344 The guest MUST be shut down in ESX before conversion starts. virt-v2v
346 will not proceed if the guest is still running. To convert the guest,
347 run:
348 virt-v2v -ic esx://<esx.server>/ -os <pool> [--network <network name>] \
350 <domain>
351 where:
353 · <esx.server> is the hostname of the ESX server hosting the guest to
355 be converted.
356 N.B. This hostname must match the hostname reported in the ESX
358 server's SSL certificate, or verification will fail.
359 · <pool> is the name of the local storage pool where copies of the
361 guest's storage will be created.
362 · <domain> is the name of the guest on the ESX server which is to be
364 converted.
365 The --network option may be provided for simple network mappings. For
367 more complex mappings, see virt-v2v.conf(5).
368 Authenticating to the ESX server
370 Connecting to the ESX server will require authentication. virt-v2v
371 supports password authentication when connecting to ESX. It reads
372 passwords from $HOME/.netrc. The format of this file is described in
373 netrc(5). An example entry is:
374 machine esx01.example.com login root password s3cr3t
376 N.B. The permissions of .netrc MUST be set to 0600, or it will be
378 ignored.
379 Connecting to an ESX server with an invalid certificate
381 In non-production environments, the ESX server may have an invalid
382 certificate, for example a self-signed certificate. In this case,
383 certificate checking can be explicitly disabled by adding
384 '?no_verify=1' to the connection URI as shown below:
385 ... -ic esx://<esx.server>/?no_verify=1 ...
387
389 virt-v2v can export to RHEV any guest that it can convert. This
390 includes:
391 · Local Xen guests
393 · ESX guests
395 · Local libvirt/KVM guests
397 To export to RHEV, specify -o rhev on the command line, and ensure -os
399 specifies the location of a RHEV export storage domain as in the
400 following examples:
401 Exporting a local Xen guest to RHEV
403 virt-v2v -i libvirtxml -o rhev -os <export_sd> \
404 [--network <network name>] <domain>.xml
405 Export a VMware ESX guest to RHEV
407 virt-v2v -ic esx://<esx.server>/ -o rhev -os <export_sd> \
408 [--network <network name>] <domain>
409 Export a local libvirt/KVM guest to RHEV
411 virt-v2v -o rhev -os <export_sd> [--network <network name>] \
412 <domain>
413
415 Libvirt output method
416 On successful completion, virt-v2v will create a new libvirt domain for
417 the converted guest with the same name as the original guest. It can be
418 started as usual using libvirt tools, for example virt-manager(1).
419 RHEV output method
421 On successful completion virt-v2v will have written the new guest to
422 the export storage domain, but it will not yet be ready to run. It must
423 be imported into RHEV using the UI before it can be used.
424 In RHEV 2.2 this is done from the Storage tab. Select the export domain
426 the guest was written to. A pane will appear underneath the storage
427 domain list displaying several tabs, one of which is 'VM Import'. The
428 converted guest will be listed here. Select the appropriate guest an
429 click 'Import'. See the RHEV documentation for additional details.
430
432 Guest network configuration
433 virt-v2v cannot currently reconfigure a guest's network configuration.
434 If the converted guest is not connected to the same subnet as the
435 source, its network configuration may have to be updated.
436 Converting a Windows guest
438 When converting a Windows guests, the conversion process is split into
439 2 stages:
440 1. Offline conversion.
442 2. First boot.
444 The guest will be bootable after the offline conversion stage, but will
446 not yet have all necessary drivers installed to work correctly. These
447 will be installed automatically the first time the guest boots.
448 N.B. Take care not to interrupt the automatic driver installation
450 process when logging in to the guest for the first time, as this may
451 prevent the guest from subsequently booting correctly.
452 Windows Recovery Console
454 virt-v2v does not support conversion of the Windows Recovery Console.
455 If a guest has a recovery console installed and VirtIO was enabled
456 during conversion, attempting to boot the recovery console will result
457 in a BSOD.
458 Windows XP x86 does not support the Windows Recovery Console on VirtIO
460 systems, so there is no resolution to this. However, on Windows XP
461 AMD64 and Windows 2003 (x86 and AMD64), the recovery console can be re-
462 installed after conversion. The re-installation procedure is the same
463 as the initial installation procedure. It is not necessary to remove
464 the recovery console first. Following re-installation, the recovery
465 console will work as intended.
466
468 As well as configuring libvirt appropriately, virt-v2v will make
469 certain changes to a guest to enable it support running under a KVM
470 host either with or without virtio driver. These changes are guest OS
471 specific. Currently only Red Hat based Linux distributions are
472 supported.
473 Linux
475 virt-v2v will make the following changes to a Linux guest:
476 Kernel
478 Un-bootable, i.e. xen paravirtualised, kernels will be uninstalled.
479 No new kernel will be installed if there is a remaining kernel
480 which supports virtio. If no remaining kernel supports virtio and
481 the configuration file specifies a new kernel it will be installed
482 and configured as the default.
483 X reconfiguration
485 If the guest has X configured, its display driver will be updated.
486 See "GUEST DRIVERS" for which driver will be used.
487 Rename block devices
489 If changes have caused block devices to change name, these changes
490 will be reflected in /etc/fstab.
491 Configure device drivers
493 Whether virtio or non-virtio drivers are configured, virt-v2v will
494 ensure that the correct network and block drivers are specified in
495 the modprobe configuration.
496 initrd
498 virt-v2v will ensure that the initrd for the default kernel
499 supports booting the root device, whether it is using virtio or
500 not.
501 SELinux
503 virt-v2v will initiate a relabel of the guest on the next boot.
504 This ensures that any changes it has made are correctly labelled
505 according to the guest's local policy.
506
508 Virt-v2v will configure the following drivers in a Linux guest:
509 VirtIO
511 X display cirrus
512 Block virtio_blk
513 Network virtio_net
514 Additionally, initrd will preload the virtio_pci driver.
516 Non-VirtIO
518 X display cirrus
519 Block IDE
520 Network e1000
521
523 Virt-v2v will configure the following drivers in a Windows guest:
524 VirtIO
526 X display cirrus
527 Block viostor
528 Network netkvm
529 Non-VirtIO
531 X display cirrus
532 Block IDE
533 Network rtl8139
534
536 To get a list of bugs against virt-v2v use this link:
537 <https://bugzilla.redhat.com/buglist.cgi?component=virt-v2v&product=Virtualization+Tools>
539 To report a new bug against virt-v2v use this link:
541 <https://bugzilla.redhat.com/enter_bug.cgi?component=virt-v2v&product=Virtualization+Tools>
543 When reporting a bug, please check:
545 · That the bug hasn't been reported already.
547 · That you are testing a recent version.
549 · Describe the bug accurately, and give a way to reproduce it.
551
553 virt-v2v.conf(5), virt-manager(1), <http://libguestfs.org/>.
554
556 Richard W.M. Jones <http://et.redhat.com/~rjones/>
557 Matthew Booth <mbooth@redhat.com>
559
561 Copyright (C) 2009-2012 Red Hat Inc.
562 This program is free software; you can redistribute it and/or modify it
564 under the terms of the GNU General Public License as published by the
565 Free Software Foundation; either version 2 of the License, or (at your
566 option) any later version.
567 This program is distributed in the hope that it will be useful, but
569 WITHOUT ANY WARRANTY; without even the implied warranty of
570 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
571 General Public License for more details.
572 You should have received a copy of the GNU General Public License along
574 with this program; if not, write to the Free Software Foundation, Inc.,
575 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
576perl v5.10.1 2013-12-03 VIRT-V2V(1)