Langue: en

Version: 2010-06-21 (fedora - 01/12/10)

Section: 5 (Format de fichier)


virt-v2v.conf - configuration file for virt-v2v


"virt-v2v.conf" describes:
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.


The configuration file is an XML document whose root element is <virt-v2v>.

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 is either 'bridge', which specifies a bridge to a local interface, or 'network', which specifies a locally managed virtual network. For Xen and ESX guests the source type will typically be 'bridge'.
name specifies the name of the given network or bridge.

The mapping is specified by a nested <network> element.

The following example specifies that a guest interface which bridges to 'xenbr1' should be change to connect to the local managed network called 'default':

  <network type='bridge' name='xenbr1'>
    <network type='network' name='default'/>

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.


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:

The symbolic name of a dependency. On an rpm-based system this will be the package name. This attribute is required.
The minimum required version of the software. For rpm-based systems this must be specified as [epoch:]version[-release]. This attribute is required.
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>.

virt-v2v passes software to the guest by creating an iso image and passing it to the guest as a cd-rom drive. The path to this iso image must be specified in a top level <iso-path> element.

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'>
  <app os='linux' distro='rhel' major='5' arch='i386' name='ecryptfs-utils'>
  <app os='linux' distro='rhel' major='5' arch='i386' name='lvm2'>

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. virt-v2v will create a transfer iso image containing all paths and dependencies at /var/lib/virt-v2v/transfer.iso.


Both <capability> and <app> are matched in the same way, based on the following attributes:

The symbolic name of the software virt-v2v is looking for. name is a mandatory attribute.
The name of the guest operating system, as returned by virt-inspector. This will be a string, like 'linux' or 'windows'.
When os='linux', this is the Linux distribution as returned by virt-inspector. Possible values include 'rhel', 'debian'.
The major version name of the guest operating system, as returned by virt-inspector.
The minor version name of the guest operating system, as returned by virt-inspector.
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

If virt-v2v doesn't find a match it will quit with an error describing what it was looking for.

Copyright (C) 2009,2010 Red Hat Inc.


Example virt-v2v.conf in the documentation directory, virt-v2v(1), virt-inspector(1), <>