Scroll to navigation

virt-v2v-output-local(1) Virtualization Support virt-v2v-output-local(1)

NAME

virt-v2v-output-local - Using virt-v2v to convert guests to local files or libvirt

SYNOPSIS

 virt-v2v [-i* options] [-o libvirt] -os POOL
 virt-v2v [-i* options] -o local -os DIRECTORY
 virt-v2v [-i* options] -o qemu -os DIRECTORY [--qemu-boot]
 virt-v2v [-i* options] -o json -os DIRECTORY
                        [-oo json-disks-pattern=PATTERN]
 virt-v2v [-i* options] -o null

DESCRIPTION

This page documents how to use virt-v2v(1) to convert guests to local files or to a locally running libvirt instance. There are four output modes you can select on the virt-v2v command line:

This converts the guest to a libvirt directory pool call "POOL", and instantiates the guest in libvirt (but does not start it running). See "OUTPUT TO LIBVIRT" below.

-o libvirt is the default if no -o option is given, so you can omit it.

This converts the guest to files in "DIRECTORY". A libvirt XML file is also created, but unlike -o libvirt the guest is not instantiated in libvirt, only files are created.

The files will be called:

 NAME-sda, NAME-sdb, etc.      Guest disk(s).
 NAME.xml                      Libvirt XML.

where "NAME" is the guest name.

This converts the guest to files in "DIRECTORY". Unlike -o local above, a shell script is created which contains the raw qemu command you would need to boot the guest. However the shell script is not run, unless you also add the --qemu-boot option.
This converts the guest to files in "DIRECTORY". The metadata produced is a JSON file containing the majority of the data virt-v2v gathers during the conversion. See "OUTPUT TO JSON" below.
The guest is converted, but the final result is thrown away and no metadata is created. This is mainly useful for testing.

OUTPUT TO LIBVIRT

The -o libvirt option lets you upload the converted guest to a libvirt-managed host. There are several limitations:

  • You can only use a local libvirt connection [see below for how to workaround this].
  • The -os pool option must specify a directory pool, not anything more exotic such as iSCSI [but see below].
  • You can only upload to a KVM hypervisor.

Workaround for output to a remote libvirt instance and/or a non-directory storage pool

1.
Use virt-v2v in -o local mode to convert the guest disks and metadata into a local temporary directory: 

 virt-v2v [...] -o local -os /var/tmp

This creates two (or more) files in /var/tmp called:

 /var/tmp/NAME.xml     # the libvirt XML (metadata)
 /var/tmp/NAME-sda     # the guest’s first disk

(for "NAME" substitute the guest’s name).

2.
Upload the converted disk(s) into the storage pool called "POOL": 

 size=$(stat -c%s /var/tmp/NAME-sda)
 virsh vol-create-as POOL NAME-sda $size --format raw
 virsh vol-upload --pool POOL NAME-sda /var/tmp/NAME-sda
3.
Edit /var/tmp/NAME.xml to change /var/tmp/NAME-sda to the pool name. In other words, locate the following bit of XML: 

 <disk type='file' device='disk'>
   <driver name='qemu' type='raw' />
   <source file='/var/tmp/NAME-sda' />
   <target dev='hda' bus='ide' />
 </disk>

and change two things: The "type='file'" attribute must be changed to "type='volume'", and the "<source>" element must be changed to include "pool" and "volume" attributes:

 <disk type='volume' device='disk'>
   ...
   <source pool='POOL' volume='NAME-sda' />
   ...
 </disk>
4.
Define the final guest in libvirt: 

 virsh define /var/tmp/NAME.xml

OUTPUT TO JSON

The -o json option produces the following files by default:

 NAME.json                     JSON metadata.
 NAME-sda, NAME-sdb, etc.      Guest disk(s).

where "NAME" is the guest name.

It is possible to change the pattern of the disks using the -oo json-disks-pattern=... option: it allows parameters in form of "%{...}" variables, for example:

 -oo json-disks-pattern=disk%{DiskNo}.img

Recognized variables are:

"%{DiskNo}"
The index of the disk, starting from 1.
"%{DiskDeviceName}"
The destination device of the disk, e.g. "sda", "sdb", etc.
"%{GuestName}"
The name of the guest.

Using a pattern it is possible use subdirectories for the disks, even with names depending on variables; for example:

 -oo json-disks-pattern=%{GuestName}-%{DiskNo}/disk.img

The default pattern is "%{GuestName}-%{DiskDeviceName}".

If the literal "%{...}" text is needed, it is possible to avoid the escape it with a leading "%"; for example, "%%{GuestName}-%{DiskNo}.img" will create file names for the disks like "%%{GuestName}-1.img", "%%{GuestName}-2.img", etc.

SEE ALSO

virt-v2v(1).

AUTHOR

Richard W.M. Jones

COPYRIGHT

Copyright (C) 2009-2020 Red Hat Inc.

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

BUGS

To get a list of bugs against libguestfs, use this link: https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools

To report a new bug against libguestfs, use this link: https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools

When reporting a bug, please supply:

  • The version of libguestfs.
  • Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
  • Describe the bug accurately and give a way to reproduce it.
  • Run libguestfs-test-tool(1) and paste the complete, unedited output into the bug report.
2022-01-01 virt-v2v-1.44.2