virt-v2v-output-rhv(1)

📦
version 2.7.1 · 6 versions
, in centos-stream 9

✨ virt-v2v-output-rhv — the girlies' guide to yeeting guests into oVirt/RHV ✨

Hey bestie 💖 so this is the virt-v2v-output-rhv(1) page, aka the one that tells you how to point virt-v2v(1) at an oVirt or RHV management instance and have it slay. There are literally three output modes you can pick from, but ngl only -o rhv-upload is the one you should be using day to day — the other two are deprecated, like, officially 💀.

🌈 SYNOPSIS 🌈

virt-v2v [-i* options] -o rhv-upload [-oc ENGINE_URL] -os STORAGE
                       [-op PASSWORD] [-of raw]
                       [-oo rhv-cafile=FILE]
                       [-oo rhv-cluster=CLUSTER]
                       [-oo rhv-proxy]
                       [-oo rhv-disk-uuid=UUID ...]
                       [-oo rhv-verifypeer]

virt-v2v [-i* options] -o rhv -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]

🎀 DESCRIPTION 🎀

This page is your map for using virt-v2v(1) to convert guests over to an oVirt or RHV management instance. Three output modes exist, but only -o rhv-upload should be used normally — the other two are deprecated, periodt.

  • -o rhv-upload -os STORAGE — full deets live in OUTPUT TO RHV up next. This is the modern, main-character method for uploading to oVirt/RHV via the REST API. It requires oVirt/RHV ≥ 4.2. 👑
  • -o rhv -os esd:/path and -o rhv -os /path — full deets in OUTPUT TO EXPORT STORAGE DOMAIN. This is the old-school method of uploading to oVirt/RHV via the Export Storage Domain (ESD). You can get at the ESD over NFS (that's the -os esd:/path form) or, if you've already NFS-mounted it somewhere, just point at the mountpoint with -os /path. The Export Storage Domain got deprecated in oVirt 4, so yeah — we fully expect this method to stop working at some point in the future 🙈.
  • -o vdsm — the old method used internally by the RHV-M user interface. It is never intended to be used directly by end users. Hands off, babe 💅.

🔥 OUTPUT TO RHV 🔥

This new method uploads guests straight to oVirt or RHV via the REST API, and it requires oVirt/RHV ≥ 4.2.

You need to pass -o rhv-upload plus these extra parameters:

  • -oc "https://ovirt-engine.example.com/ovirt-engine/api" — the URL of the REST API. It's usually the server name with "/ovirt-engine/api" appended, but it might be different if you installed oVirt Engine on a different path. You can optionally add a username and port number to the URL. If you don't specify the username, virt-v2v defaults to "admin@internal", which is the typical superuser account for oVirt instances 🫶.
  • -of raw — rn you must use -of raw, and you cannot use -oa preallocated. These restrictions will be loosened in a future version, so like, watch this space ⭐.
  • -op password-file — a file containing a password used when connecting to the oVirt engine. Note that the file should contain the whole password, without any trailing newline, and for security the file should have mode 0600 so others can't read it 🔒.
  • -os "ovirt-data" — the storage domain.
  • -oo rhv-cafile=ca.pem — the ca.pem file (Certificate Authority), copied from /etc/pki/ovirt-engine/ca.pem on the oVirt engine. If -oo rhv-verifypeer is enabled, then this option can be used to control which CA is used to verify the client's identity. If you don't use this option, then the system's global trust store is used.
  • -oo rhv-cluster="CLUSTERNAME" — set the RHV Cluster Name. If not given, it uses "Default".
  • -oo rhv-disk-uuid="UUID" — this option can be 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:
    • you must pass as many -oo rhv-disk-uuid=UUID options as the amount of disks in the guest 🧮
    • the specified UUIDs must not conflict with the UUIDs of existing disks ⚠️
  • -oo rhv-proxy — proxy the upload through oVirt Engine. This is slower than uploading directly to the oVirt node, but it may be necessary if you do not have direct network access to the nodes.
  • -oo rhv-verifypeer — verify the oVirt/RHV server's identity by checking the server's certificate against the Certificate Authority.

🦋 OUTPUT TO EXPORT STORAGE DOMAIN 🦋

This whole section only applies to the -o rhv output mode. If you use virt-v2v from the RHV-M user interface, then behind the scenes the import is managed by VDSM using the -o vdsm output mode (which end users should not try to use directly, fr).

You have to specify -o rhv and an -os option that points to the RHV-M Export Storage Domain. Either specify the NFS server and mountpoint, eg. "-os rhv-storage:/rhv/export", or mount that first and point to the directory where it's mounted, eg. "-os /tmp/mnt". Be careful not to point to the Data Storage Domain by accident, because that will not work — like, at all 😭.

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 RHV using the UI before it can be used.

In RHV ≥ 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 and click "Import". See the RHV documentation for additional details 📚.

If you export several guests, then you can import them all at the same time through the UI. Efficient, we love to see it 💅.

🌸 Testing RHV conversions 🌸

If you don't have an oVirt or RHV instance to test against, then you can test conversions by creating a directory structure which looks enough like a RHV-M Export Storage Domain to trick virt-v2v:

uuid=`uuidgen`
mkdir /tmp/rhv
mkdir /tmp/rhv/$uuid
mkdir /tmp/rhv/$uuid/images
mkdir /tmp/rhv/$uuid/master
mkdir /tmp/rhv/$uuid/master/vms
touch /tmp/rhv/$uuid/dom_md
virt-v2v [...] -o rhv -os /tmp/rhv

Fake it till you make it, bestie 🎭.

💀 Debugging RHV-M import failures 💀

When you export to the RHV-M Export Storage Domain, and then import that guest through the RHV-M UI, you may encounter an import failure. Diagnosing these failures is infuriatingly difficult, because the UI generally hides the true reason for the failure. Genuinely the worst.

There are several log files of interest:

  • /var/log/vdsm/import/ — in oVirt ≥ 4.1.0, VDSM preserves the virt-v2v log file for 30 days in this directory. 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 "Events" tab in oVirt administration.
  • /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.
  • /var/log/ovirt-engine/engine.log — this log file is stored on the RHV-M server. It contains more detail for any errors caused by the oVirt GUI.

👀 SEE ALSO 👀

virt-v2v(1).

🫶 AUTHOR 🫶

Richard W.M. Jones

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.
Ok that's the whole page, bestie — no cap, every single flag and log file made it in 💖 Go forth and upload iconically 👑✨

Later, girlies 🦋 — this was virt-v2v version 2.7.1, dated 2025-12-15. Mwah 💋

📦 where this page comes from