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 and VMware ESX. It will enable VirtIO
22 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 ommitted, this defaults to qemu:///system.
66 N.B. virt-v2v must be able to write directly to storage described
68 by this libvirt connection. This makes writing to a remote
69 connection impractical at present.
70 -os storage
72 The output method dependent location where new storage will be
73 created for the converted guest.
74 For the libvirt output method, this must be the name of a storage
76 pool.
77 For the rhev output method, this specifies the NFS path to a RHEV
79 Export storage domain. Note that the storage domain must have been
80 previously initialised by RHEV. The domain must be in the format
81 <host>:<path>, eg:
82 rhev-storage.example.com:/rhev/export
84 The nfs export must be mountable and writable by the machine
86 running virt-v2v.
87 -op pool
89 See -os for the libvirt output method.
90 DEPRECATED Use -os instead.
92 -osd domain
94 See -os for the rhev output method.
95 DEPRECATED Use -os instead.
97 -of format
99 Specifies the on-disk format which will be used for the converted
100 guest. Currently supported options are raw and qcow2. If not
101 specified, the converted guest will use the same format as the
102 source guest.
103 -oa allocation
105 Specifies whether the converted guest should be sparse or
106 preallocated. If not specified, the converted guest will use the
107 same allocation scheme as the source.
108 -on outputname
110 Rename the guest.
111 If this option is not given, then the output name is the same as
113 the input name.
114 -f file | --config file
116 Load a virt-v2v configuration from file. Multiple configuration
117 files can be specified, which will be searched in the order they
118 are specified on the command line. If no configuration is
119 specified, defaults to /etc/virt-v2v.conf and
120 /var/lib/virt-v2v/virt-v2v.db in that order.
121 When overriding the default config file it is recommended that
123 /var/lib/virt-v2v/virt-v2v.db is also specified, as it contains
124 default configuration data required for conversions.
125 -n network | --network network
127 Map all guest bridges or networks which don't have a mapping in the
128 configuration file to network.
129 This option cannot be used in conjunction with --bridge.
131 -b bridge | --bridge bridge
133 Map all guest bridges or networks which don't have a mapping in the
134 configuration file to bridge.
135 This option cannot be used in conjunction with --network.
137 -p profile | --profile profile
139 Take default values for output method, output storage and network
140 mappings from profile in the configuration file.
141 --root=ask
143 --root=single
144 --root=first
145 --root=/dev/sdX
146 Choose the root filesystem to be converted.
147 In the case where the virtual machine is dual-boot or multi-boot,
149 or where the VM has other filesystems that look like operating
150 systems, this option can be used to select the root filesystem
151 (a.k.a. "C: drive" or "/") of the operating system that is to be
152 converted. The Windows Recovery Console, certain attached DVD
153 drives, and bugs in libguestfs inspection heuristics, can make a
154 guest look like a multi-boot operating system.
155 The default in virt-v2v X 0.7.1 was --root=single, which causes
157 virt-v2v to die if a multi-boot operating system is found.
158 Since virt-v2v X 0.7.2 the default is now --root=ask: If the VM is
160 found to be multi-boot, then virt-v2v will stop and list the
161 possible root filesystems and ask the user which to use. This
162 requires that virt-v2v is run interactively.
163 --root=first means to choose the first root device in the case of a
165 multi-boot operating system. Since this is a heuristic, it may
166 sometimes choose the wrong one.
167 You can also name a specific root device, eg. --root=/dev/sda2
169 would mean to use the second partition on the first hard drive. If
170 the named root device does not exist or was not detected as a root
171 device, then virt-v2v will fail.
172 Note that there is a bug in grub which prevents it from
174 successfully booting a multiboot system if VirtIO is enabled. Grub
175 is only able to boot an operating system from the first VirtIO
176 disk. Specifically, /boot must be on the first VirtIO disk, and it
177 cannot chainload an OS which is not in the first VirtIO disk.
178 --list-profiles
180 Display a list of target profile names specified in the
181 configuration file.
182 --help
184 Display brief help.
185 --version
187 Display version number and exit.
188
190 Local storage requirements
191 Whenever possible, virt-v2v copies a guest's storage directly from the
192 source hypervisor to the target hypervisor without using any local
193 storage. However, this is not possible in all circumstances.
194 Specifically when transferring a guest's storage over SSH and also
195 either doing a format conversion, or changing the allocation policy of
196 qcow2 storage, virt-v2v will cache a local copy of the guest's storage.
197 By default, this local cache will be created in /tmp. If /tmp does not
198 have sufficient storage space, it can be written to another directory
199 by setting the TMPDIR environment variable.
200 Local Xen guests
202 N.B. The following is required when converting guests on a host which
203 used to run Xen, but has been updated to run KVM. It is not required
204 when converting a Xen guest imported directly from a running
205 libvirt/Xen instance.
206 virt-v2v uses a libvirt domain description to determine the current
208 configuration of the guest, including the location of its storage. This
209 should be obtained from the host running the guest pre-conversion by
210 running:
211 virsh dumpxml <domain> > <domain>.xml
213 This will require a reboot if the host running Xen is the same host
215 that will run KVM. This is because libvirt needs to connect to a
216 running xen hypervisor to obtain its metadata.
217 Converting to run on libvirt/KVM
219 Create a local storage pool for transferred storage
220 virt-v2v copies the guest storage to the local machine during import.
222 When converting to run on libvirt, it creates new storage in a locally
223 defined libvirt pool. This pool can be defined using any libvirt tool,
224 and can be of any type.
225 The simplest way to create a new pool is with virt-manager(1). Pools
227 can be defined from the Storage tab under Host Details.
228 Create local network interfaces
230 The local machine must have an appropriate network for the converted
232 guest to connect to. This is likely to be a bridge interface. A bridge
233 interface can be created using standard tools on the host.
234 Since version 0.8.3, virt-manager(1) can also create and manage
236 bridges.
237 Converting to run on RHEV
239 Create an NFS export domain
240 virt-v2v can convert guests to run on RHEV 2.2 or later. It does this
242 by writing the converted guest directly to an 'Export' NFS storage
243 domain. The guest can later be imported into a RHEV Data Center through
244 the UI.
245 In RHEV 2.2, a new Export storage domain is created by clicking on 'New
247 Domain' in the Storage tab. Ensure that the Domain function is 'Export'
248 and the Storage type is 'NFS'. See the RHEV documentation for details.
249 The NFS storage domain must be mountable by the machine running
250 virt-v2v.
251 N.B. When exporting to RHEV, virt-v2v must run as root.
253 Import the appropriate Guest Tools ISO
255 When converting Windows guests, it is strongly recommended that the
257 Guest Tools ISO is installed before the guest is converted. This must
258 be done using the ISO Uploader, which can be found on your RHEV-M
259 system under Start->Red Hat->RHEV Manager->ISO Uploader. This will
260 allow RHEV to automatically update the guest's drivers to the latest
261 versions and install any required agents.
262
264 The following requires that the domain XML is available locally, and
265 that the storage referred to in the domain XML is available locally at
266 the same paths.
267 To perform the conversion, run:
269 virt-v2v -i libvirtxml -os <pool> [--network <network name>] \
271 <domain>.xml
272 where "<domain>.xml" is the path to the exported guest domain's xml,
274 and "<pool>" is the local storage pool where copies of the guest's
275 disks will be created.
276 The --network option may be provided for simple network mappings. For
278 more complex mappings, see virt-v2v.conf(5).
279 If it is not possible to provide software updates over the network in
281 your environment, software will be installed as specified in
282 virt-v2v.conf. See virt-v2v.conf(5) for a details.
283 It is possible to avoid specifying replacement kernels in the virt-v2v
285 config file by ensuring that the guest has an appropriate kernel
286 installed prior to conversion. If your guest uses a Xen paravirtualised
287 kernel (it would be called something like kernel-xen or kernel-xenU),
288 you can install a regular kernel, which won't reference a hypervisor in
289 its name, alongside it. You shouldn't make this newly installed kernel
290 your default kernel because Xen may not boot it. virt-v2v will make it
291 the default during conversion.
292
294 N.B. libvirt version 0.7.0 or greater is required to connect to ESX.
295 virt-v2v can convert a guest from VMware ESX, including transferring
297 its storage.
298 N.B. virt-v2v does not transfer snapshots from ESX. Only the latest
300 flat storage is transferred.
301 The guest MUST be shut down in ESX before conversion starts. virt-v2v
303 will not proceed if the guest is still running. To convert the guest,
304 run:
305 virt-v2v -ic esx://<esx.server>/ -os <pool> [--network <network name>] \
307 <domain>
308 where:
310 · <esx.server> is the hostname of the ESX server hosting the guest to
312 be converted.
313 N.B. This hostname must match the hostname reported in the ESX
315 server's SSL certificate, or verification will fail.
316 · <pool> is the name of the local storage pool where copies of the
318 guest's storage will be created.
319 · <domain> is the name of the guest on the ESX server which is to be
321 converted.
322 The --network option may be provided for simple network mappings. For
324 more complex mappings, see virt-v2v.conf(5).
325 Authenticating to the ESX server
327 Connecting to the ESX server will require authentication. virt-v2v
328 supports password authentication when connecting to ESX. It reads
329 passwords from $HOME/.netrc. The format of this file is described in
330 netrc(5). An example entry is:
331 machine esx01.example.com login root password s3cr3t
333 N.B. The permissions of .netrc MUST be set to 0600, or it will be
335 ignored.
336 Connecting to an ESX server with an invalid certificate
338 In non-production environments, the ESX server may have an invalid
339 certificate, for example a self-signed certificate. In this case,
340 certificate checking can be explicitly disabled by adding
341 '?no_verify=1' to the connection URI as shown below:
342 ... -ic esx://<esx.server>/?no_verify=1 ...
344
346 virt-v2v can export to RHEV any guest that it can convert. This
347 includes:
348 · Local Xen guests
350 · ESX guests
352 · Local libvirt/KVM guests
354 To export to RHEV, specify -o rhev on the command line, and ensure -os
356 specifies the location of a RHEV export storage domain as in the
357 following examples:
358 Exporting a local Xen guest to RHEV
360 virt-v2v -i libvirtxml -o rhev -os <export_sd> \
361 [--network <network name>] <domain>.xml
362 Export a VMWare ESX guest to RHEV
364 virt-v2v -ic esx://<esx.server>/ -o rhev -os <export_sd> \
365 [--network <network name>] <domain>
366 Export a local libvirt/KVM guest to RHEV
368 virt-v2v -o rhev -os <export_sd> [--network <network name>] \
369 <domain>
370
372 Libvirt output method
373 On successful completion, virt-v2v will create a new libvirt domain for
374 the converted guest with the same name as the original guest. It can be
375 started as usual using libvirt tools, for example virt-manager(1).
376 RHEV output method
378 On successful completion virt-v2v will have written the new guest to
379 the export storage domain, but it will not yet be ready to run. It must
380 be imported into RHEV using the UI before it can be used.
381 In RHEV 2.2 this is done from the Storage tab. Select the export domain
383 the guest was written to. A pane will appear underneath the storage
384 domain list displaying several tabs, one of which is 'VM Import'. The
385 converted guest will be listed here. Select the appropriate guest an
386 click 'Import'. See the RHEV documentation for additional details.
387
389 Guest network configuration
390 virt-v2v cannot currently reconfigure a guest's network configuration.
391 If the converted guest is not connected to the same subnet as the
392 source, its network configuration may have to be updated.
393 Converting a Windows guest
395 When converting a Windows guests, the conversion process is split into
396 2 stages:
397 1. Offline conversion.
399 2. First boot.
401 The guest will be bootable after the offline conversion stage, but will
403 not yet have all necessary drivers installed to work correctly. These
404 will be installed automatically the first time the guest boots.
405 N.B. Take care not to interrupt the automatic driver installation
407 process when logging in to the guest for the first time, as this may
408 prevent the guest from subsequently booting correctly.
409
411 As well as configuring libvirt appropriately, virt-v2v will make
412 certain changes to a guest to enable it support running under a KVM
413 host either with or without virtio driver. These changes are guest OS
414 specific. Currently only Red Hat based Linux distributions are
415 supported.
416 Linux
418 virt-v2v will make the following changes to a Linux guest:
419 Kernel
421 Un-bootable, i.e. xen paravirtualised, kernels will be uninstalled.
422 No new kernel will be installed if there is a remaining kernel
423 which supports virtio. If no remaining kernel supports virtio and
424 the configuration file specifies a new kernel it will be installed
425 and configured as the default.
426 X reconfiguration
428 If the guest has X configured, its display driver will be updated.
429 See "GUEST DRIVERS" for which driver will be used.
430 Rename block devices
432 If changes have caused block devices to change name, these changes
433 will be reflected in /etc/fstab.
434 Configure device drivers
436 Whether virtio or non-virtio drivers are configured, virt-v2v will
437 ensure that the correct network and block drivers are specified in
438 the modprobe configuration.
439 initrd
441 virt-v2v will ensure that the initrd for the default kernel
442 supports booting the root device, whether it is using virtio or
443 not.
444 SELinux
446 virt-v2v will initiate a relabel of the guest on the next boot.
447 This ensures that any changes it has made are correctly labelled
448 according to the guest's local policy.
449
451 Virt-v2v will configure the following drivers in a Linux guest:
452 VirtIO
454 X display cirrus
455 Block virtio_blk
456 Network virtio_net
457 Additionally, initrd will preload the virtio_pci driver.
459 Non-VirtIO
461 X display cirrus
462 Block IDE
463 Network e1000
464
466 Virt-v2v will configure the following drivers in a Windows guest:
467 VirtIO
469 X display cirrus
470 Block viostor
471 Network netkvm
472 Non-VirtIO
474 X display cirrus
475 Block IDE
476 Network rtl8139
477
479 To get a list of bugs against virt-v2v use this link:
480 https://bugzilla.redhat.com/buglist.cgi?component=virt-v2v&product=Virtualization+Tools
482 <https://bugzilla.redhat.com/buglist.cgi?component=virt-
483 v2v&product=Virtualization+Tools>
484 To report a new bug against virt-v2v use this link:
486 https://bugzilla.redhat.com/enter_bug.cgi?component=virt-v2v&product=Virtualization+Tools
488 <https://bugzilla.redhat.com/enter_bug.cgi?component=virt-
489 v2v&product=Virtualization+Tools>
490 When reporting a bug, please check:
492 · That the bug hasn't been reported already.
494 · That you are testing a recent version.
496 · Describe the bug accurately, and give a way to reproduce it.
498
500 virt-v2v.conf(5), virt-manager(1), <http://libguestfs.org/>.
501
503 Richard W.M. Jones <http://et.redhat.com/~rjones/>
504 Matthew Booth <mbooth@redhat.com>
506
508 Copyright (C) 2009-2011 Red Hat Inc.
509 This program is free software; you can redistribute it and/or modify it
511 under the terms of the GNU General Public License as published by the
512 Free Software Foundation; either version 2 of the License, or (at your
513 option) any later version.
514 This program is distributed in the hope that it will be useful, but
516 WITHOUT ANY WARRANTY; without even the implied warranty of
517 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
518 General Public License for more details.
519 You should have received a copy of the GNU General Public License along
521 with this program; if not, write to the Free Software Foundation, Inc.,
522 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
523perl v5.12.3 2011-08-30 VIRT-V2V(1)