.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 2.10.0 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "virt-v2v-output-ovirt 1"
.TH virt-v2v-output-ovirt 1 2026-03-28 virt-v2v-2.10.0 "Virtualization Support"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
virt\-v2v\-output\-ovirt \- Using virt\-v2v to convert guests to oVirt
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 7
\& virt\-v2v [\-i* options] \-o ovirt\-upload [\-oc ENGINE_URL] \-os STORAGE
\&                        [\-op PASSWORD] [\-of raw]
\&                        [\-oo ovirt\-cafile=FILE]
\&                        [\-oo ovirt\-cluster=CLUSTER]
\&                        [\-oo ovirt\-proxy]
\&                        [\-oo ovirt\-disk\-uuid=UUID ...]
\&                        [\-oo ovirt\-verifypeer]
\&
\& virt\-v2v [\-i* options] \-o ovirt \-os [esd:/path|/path]
\&
\& virt\-v2v [\-i* options] \-o vdsm
\&                        [\-oo vdsm\-image\-uuid=UUID]
\&                        [\-oo vdsm\-vol\-uuid=UUID]
\&                        [\-oo vdsm\-vm\-uuid=UUID]
\&                        [\-oo vdsm\-ovf\-output=DIR]
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This page documents how to use \fBvirt\-v2v\fR\|(1) to convert guests to an
oVirt management instance.  There are three output modes that you can
select, but only \fI\-o ovirt-upload\fR should be used normally, the other
two are deprecated:
.IP "\fB\-o ovirt-upload\fR \fB\-os\fR STORAGE" 4
.IX Item "-o ovirt-upload -os STORAGE"
Full description: "OUTPUT TO OVIRT"
.Sp
This is the modern method for uploading to oVirt via the REST API.  It
requires oVirt ≥ 4.2.
.IP "\fB\-o ovirt\fR \fB\-os\fR esd:/path" 4
.IX Item "-o ovirt -os esd:/path"
.PD 0
.IP "\fB\-o ovirt\fR \fB\-os\fR /path" 4
.IX Item "-o ovirt -os /path"
.PD
Full description: "OUTPUT TO EXPORT STORAGE DOMAIN"
.Sp
This is the old method for uploading to oVirt via the Export Storage
Domain (ESD).  The ESD can either be accessed over NFS (using the
\&\fI\-os esd:/path\fR form) or if you have already NFS-mounted it somewhere
specify the path to the mountpoint as \fI\-os /path\fR.
.Sp
The Export Storage Domain was deprecated in oVirt 4, and so we expect
that this method will stop working at some point in the future.
.IP "\fB\-o vdsm\fR" 4
.IX Item "-o vdsm"
This is the old method used internally by the oVirt user interface.
It is never intended to be used directly by end users.
.SH "OUTPUT TO OVIRT"
.IX Header "OUTPUT TO OVIRT"
This new method to upload guests to oVirt directly via the REST API
requires oVirt ≥ 4.2.
.PP
You need to specify \fI\-o ovirt-upload\fR as well as the following extra
parameters:
.ie n .IP "\fI\-oc\fR ""https://ovirt\-engine.example.com/ovirt\-engine/api""" 4
.el .IP "\fI\-oc\fR \f(CWhttps://ovirt\-engine.example.com/ovirt\-engine/api\fR" 4
.IX Item "-oc https://ovirt-engine.example.com/ovirt-engine/api"
The URL of the REST API which is usually the server name with
\&\f(CW\*(C`/ovirt\-engine/api\*(C'\fR appended, but might be different if you installed
oVirt Engine on a different path.
.Sp
You can optionally add a username and port number to the URL.  If the
username is not specified then virt\-v2v defaults to using
\&\f(CW\*(C`admin@internal\*(C'\fR which is the typical superuser account for oVirt
instances.
.IP "\fI\-of raw\fR" 4
.IX Item "-of raw"
Currently you must use \fI\-of raw\fR and you cannot use \fI\-oa preallocated\fR.
.Sp
These restrictions will be loosened in a future version.
.IP "\fI\-op\fR \fIpassword-file\fR" 4
.IX Item "-op password-file"
A file containing a password to be used when connecting to the oVirt
engine.  Note the file should contain the whole password, \fBwithout
any trailing newline\fR, and for security the file should have mode
\&\f(CW0600\fR so that others cannot read it.
.ie n .IP "\fI\-os\fR ""ovirt\-data""" 4
.el .IP "\fI\-os\fR \f(CWovirt\-data\fR" 4
.IX Item "-os ovirt-data"
The storage domain.
.IP "\fI\-oo ovirt\-cafile=\fR\fIca.pem\fR" 4
.IX Item "-oo ovirt-cafile=ca.pem"
The \fIca.pem\fR file (Certificate Authority), copied from
\&\fI/etc/pki/ovirt\-engine/ca.pem\fR on the oVirt engine.
.Sp
If \fI\-oo ovirt-verifypeer\fR is enabled then this option can
be used to control which CA is used to verify the client’s
identity.  If this option is not used then the system’s
global trust store is used.
.ie n .IP "\fI\-oo ovirt\-cluster=\fR""CLUSTERNAME""" 4
.el .IP "\fI\-oo ovirt\-cluster=\fR\f(CWCLUSTERNAME\fR" 4
.IX Item "-oo ovirt-cluster=CLUSTERNAME"
Set the oVirt Cluster Name.  If not given it uses \f(CW\*(C`Default\*(C'\fR.
.ie n .IP "\fI\-oo ovirt\-disk\-uuid=\fR""UUID""" 4
.el .IP "\fI\-oo ovirt\-disk\-uuid=\fR\f(CWUUID\fR" 4
.IX Item "-oo ovirt-disk-uuid=UUID"
This option can used to manually specify UUIDs for the disks when
creating the virtual machine.  If not specified, the oVirt engine will
generate random UUIDs for the disks.  Please note that:
.RS 4
.IP \(bu 4
you \fBmust\fR pass as many \fI\-oo ovirt\-disk\-uuid=UUID\fR options as the
amount of disks in the guest
.IP \(bu 4
the specified UUIDs must not conflict with the UUIDs of existing disks
.RE
.RS 4
.RE
.IP "\fI\-oo ovirt-proxy\fR" 4
.IX Item "-oo ovirt-proxy"
Proxy the upload through oVirt Engine.  This is slower than uploading
directly to the oVirt node but may be necessary if you do not have
direct network access to the nodes.
.IP "\fI\-oo ovirt-verifypeer\fR" 4
.IX Item "-oo ovirt-verifypeer"
Verify the oVirt server’s identity by checking the server‘s
certificate against the Certificate Authority.
.SH "OUTPUT TO EXPORT STORAGE DOMAIN"
.IX Header "OUTPUT TO EXPORT STORAGE DOMAIN"
This section only applies to the \fI\-o ovirt\fR output mode.  If you use
virt\-v2v from the oVirt user interface, then behind the scenes the
import is managed by VDSM using the \fI\-o vdsm\fR output mode (which end
users should not try to use directly).
.PP
You have to specify \fI\-o ovirt\fR and an \fI\-os\fR option that points to the
oVirt Export Storage Domain.  You can either specify the NFS server
and mountpoint, eg. \f(CW\*(C`\-os\ ovirt\-storage:/ovirt/export\*(C'\fR, or you can
mount that first and point to the directory where it is mounted,
eg. \f(CW\*(C`\-os\ /tmp/mnt\*(C'\fR.  Be careful not to point to the Data Storage
Domain by accident as that will not work.
.PP
On successful completion virt\-v2v will have written the new guest to
the Export Storage Domain, but it will not yet be ready to run.  It
must be imported into oVirt using the UI before it can be used.
.PP
In oVirt ≥ 2.2 this is done from the Storage tab.  Select the
export domain the guest was written to.  A pane will appear underneath
the storage domain list displaying several tabs, one of which is "VM
Import".  The converted guest will be listed here.  Select the
appropriate guest an click "Import".  See the oVirt documentation for
additional details.
.PP
If you export several guests, then you can import them all at the same
time through the UI.
.SS "Testing oVirt conversions"
.IX Subsection "Testing oVirt conversions"
If you do not have an oVirt instance to test against, then you can
test conversions by creating a directory structure which looks enough
like a oVirt Export Storage Domain to trick virt\-v2v:
.PP
.Vb 8
\& uuid=\`uuidgen\`
\& mkdir /tmp/ovirt
\& mkdir /tmp/ovirt/$uuid
\& mkdir /tmp/ovirt/$uuid/images
\& mkdir /tmp/ovirt/$uuid/master
\& mkdir /tmp/ovirt/$uuid/master/vms
\& touch /tmp/ovirt/$uuid/dom_md
\& virt\-v2v [...] \-o ovirt \-os /tmp/ovirt
.Ve
.SS "Debugging oVirt import failures"
.IX Subsection "Debugging oVirt import failures"
When you export to the oVirt Export Storage Domain, and then import
that guest through the oVirt UI, you may encounter an import failure.
Diagnosing these failures is infuriatingly difficult as the UI
generally hides the true reason for the failure.
.PP
There are several log files of interest:
.IP \fI/var/log/vdsm/import/\fR 4
.IX Item "/var/log/vdsm/import/"
In oVirt ≥ 4.1.0, VDSM preserves the virt\-v2v log file for
30 days in this directory.
.Sp
This directory is found on the host which performed the conversion.
The host can be selected in the import dialog, or can be found under
the \f(CW\*(C`Events\*(C'\fR tab in oVirt administration.
.IP \fI/var/log/vdsm/vdsm.log\fR 4
.IX Item "/var/log/vdsm/vdsm.log"
As above, this file is present on the host which performed the
conversion.  It contains detailed error messages from low-level
operations executed by VDSM, and is useful if the error was not caused
by virt\-v2v, but by VDSM.
.IP \fI/var/log/ovirt\-engine/engine.log\fR 4
.IX Item "/var/log/ovirt-engine/engine.log"
This log file is stored on the oVirt server.  It contains more detail
for any errors caused by the oVirt GUI.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBvirt\-v2v\fR\|(1).
.SH AUTHOR
.IX Header "AUTHOR"
Richard W.M. Jones
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2009\-2025 Red Hat Inc.
.SH LICENSE
.IX Header "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.
.PP
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.
.PP
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.
.SH BUGS
.IX Header "BUGS"
To get a list of bugs against libguestfs, use this link:
https://bugzilla.redhat.com/buglist.cgi?component=libguestfs&product=Virtualization+Tools
.PP
To report a new bug against libguestfs, use this link:
https://bugzilla.redhat.com/enter_bug.cgi?component=libguestfs&product=Virtualization+Tools
.PP
When reporting a bug, please supply:
.IP \(bu 4
The version of libguestfs.
.IP \(bu 4
Where you got libguestfs (eg. which Linux distro, compiled from source, etc)
.IP \(bu 4
Describe the bug accurately and give a way to reproduce it.
.IP \(bu 4
Run \fBlibguestfs\-test\-tool\fR\|(1) and paste the \fBcomplete, unedited\fR
output into the bug report.