VIRT-V2V.CONF(5) User Contributed Perl Documentation VIRT-V2V.CONF(5)NAMEvirt-v2v.conf - configuration file for virt-v2v
DESCRIPTION
"virt-v2v.conf" describes:
· a set of target profiles which pre-define a set of output options.
· how to map virtual network interface connections when importing
them from another environment.
· software which can be installed by virt-v2v during the conversion
process.
FORMAT
The configuration file is an XML document whose root element is
<virt-v2v>.
Target Profiles
A target profile is used to group a set of configuration options
defining a specific destination for a conversion. A user can specify a
target profile in place of the equivalent command line options.
A target profile is defined by an element in virt-v2v.conf which is a
child of the top-level virt-v2v element. For example:
<profile name='kvm1'>
<method>libvirt</method>
<storage format='raw' allocation='sparse'>default</storage>
<network type='default'>
<network type='network' name='red'/>
</network>
<network type='bridge' name='xenbr1'>
<network type='network' name='green'/>
</network>
</profile>
A target profile is identified by its name attribute. Allowed elements
are:
method
The output method, equivalent to the -o command line option. This
element is required.
storage
The output storage location, equivalent to the -os command line
option. This element is required.
storage can optionally have format and allocation attributes. If
specified, these are equivalent to the -of and -oa command line
options respectively.
network
A set of network mappings specific to this profile. See "Mapping
network interface connections" for detail of the format of this
element.
Network mappings specified in the selected profile will be used in
preference to top-level network mappings. A specific, matching top-
level mapping will still be used in preference to a default
specified in a profile.
Mapping network interface connections
When importing a guest from a different machine and/or hypervisor, it
is likely that the name of the virtual interface its network devices
were connected to will change. For example, a typical Xen guest will be
connected to a bridge device called xenbrN. This bridge is created by
Xen and will not exist locally by default.
virt-v2v can change these on import to connect to an appropriate local
interface. The mapping is specified by the <network> element, which is
a child of the root element. The configuration can specify any number
of <network> elements. <network> has 2 attributes:
type
type can be:
bridge
A bridge to a host network interface.
network
A managed virtual network.
default
A type which will match any network if there is no specific
match.
For Xen and ESX guests the source type will typically be 'bridge'.
A configuration may only contain a single default mapping.
name
name specifies the name of the given network or bridge. A default
mapping does not have a name.
The mapping is specified by a nested <network> element.
The following example specifies that a guest interface which bridged to
'xenbr1' before conversion should be changed to connect to the local
bridge called 'br0'. Any other network interface should be changed to
connect to the local managed network called 'default':
<network type='bridge' name='xenbr1'>
<network type='bridge' name='br0'/>
</network>
<network type='default'>
<network type='network' name='default'/>
</network>
Specifying software to be installed
virt-v2v may have to install software in a guest during the conversion
process to ensure it boots. An example is replacing a Xen
paravirtualised kernel with a normal kernel. This software will be
specific to the guest operating system.
Capabilities
A capability describes the set of software required for a specific
goal, for example VirtIO support. A capability describes only direct
dependencies. Transitive dependencies will be resolved by the
installation method, for example yum or "Local Installation".
<capability> is a child of the root element. There can be any number of
<capability> elements. See "Searching" for a description of the
attributes of <capability> and how they are matched.
Dependencies are specified in the <dep> element, which has the
following attributes:
name
The symbolic name of a dependency. On an rpm-based system this will
be the package name. This attribute is required.
minversion
The minimum required version of the software. For rpm-based systems
this must be specified as [epoch:]version[-release]. This attribute
is required.
ifinstalled
A dependency must normally be installed if it is not present, or
upgraded if it present but too old. If ifinstalled is 'yes', the
dependency will be upgraded if is present but too old, but not
installed if it is not already present.
Local Installation
If it is not possible to install required software using the guest's
update agent, the software can be installed from the conversion host.
In this case, it must be specified in the <app> element. <app> is a
child of the root element. The configuration can specify any number of
<app> elements. See "Searching" for a description of the attribute of
<app> and how they are matched.
The <app> element must contain a <path> element, which specifies the
path to the software. It may also contain any number of <dep> elements,
which specify the names of additional applications which may need to be
installed. Each dependency will be resolved in the same way as its
parent, by looking for a match based on os, distro, major, minor and
arch.
virt-v2v will attempt to install dependencies first. A dependency will
only be installed if it is not already installed, or the installed
version is older than the specified version. On x86_64, virt-v2v will
additionally check if an i386 version need to by updated, but only if
any i386 version of the package is already installed.
Paths given in <path> must be absolute, unless there is a top level
<path-root> element. If it exists, all <path> elements will be relative
to <path-root>.
The following example specifies the location of 'kernel' for RHEL 5,
all minor versions, on i686:
<app os='linux' distro='rhel' major='5' arch='i686' name='kernel'>
<path>rhel/5/kernel-2.6.18-128.el5.i686.rpm</path>
<dep>ecryptfs-utils</dep>
<dep>lvm2</dep>
</app>
<app os='linux' distro='rhel' major='5' arch='i386' name='ecryptfs-utils'>
<path>rhel/5/ecryptfs-utils-56-8.el5.i386.rpm</path>
</app>
<app os='linux' distro='rhel' major='5' arch='i386' name='lvm2'>
<path>rhel/5/lvm2-2.02.40-6.el5.i386.rpm</path>
<dep>device-mapper</dep>
<dep>device-mapper-event</dep>
</app>
<path-root>/var/lib/virt-v2v/software</path-root>
The kernel can be found at
/var/lib/virt-v2v/software/rhel/5/kernel-2.6.18-128.el5.i686.rpm. It
has 2 direct dependencies: ecryptfs and lvm2. ecryptfs-utils has no
additional dependencies, but lvm2 has 2 further dependencies (not shown
for brevity). All dependencies will also be installed if they are not
present, or are too old. All dependency paths are also relative to
/var/lib/virt-v2v/software.
Searching
Both <capability> and <app> are matched in the same way, based on the
following attributes:
name
The symbolic name of the software virt-v2v is looking for. name is
a mandatory attribute.
os The name of the guest operating system, as returned by virt-
inspector. This will be a string, like 'linux' or 'windows'.
distro
When os='linux', this is the Linux distribution as returned by
virt-inspector. Possible values include 'rhel', 'debian'.
major
The major version name of the guest operating system, as returned
by virt-inspector.
minor
The minor version name of the guest operating system, as returned
by virt-inspector.
arch
The guest architecture, as returned by virt-inspector.
virt-v2v searches for an <app> or <capability> by symbolic name,
matching based on its additional attributes. If an attribute is missing
it will match any value. If multiple elements would match a given
search, virt-v2v will choose the most specific match. Specifically, it
searches in the following order:
· os, distro, major, minor, arch
· os, distro, major, minor
· os, distro, major, arch
· os, distro, major
· os, distro
· os
If virt-v2v doesn't find a match it will quit with an error describing
what it was looking for.
Installing custom software during conversion
The 'Red Hat' converter, which converts RHEL and Fedora guests,
includes a hook which allows custom software to be installed during
conversion. The user can define a capability with the name
'user-custom'. The dependencies of this capability will be installed
during conversion in the same way as the dependencies of other
capabilities.
It is recommended that custom configuration changes are added to
/etc/virt-v2v.conf rather than /var/lib/virt-v2v/virt-v2v.db.
COPYRIGHT
Copyright (C) 2009-2012 Red Hat Inc.
SEE ALSO
Example virt-v2v.conf in the documentation directory, virt-v2v(1),
virt-inspector(1), <http://libguestfs.org/>
perl v5.10.1 2013-06-12 VIRT-V2V.CONF(5)
