Migrating VMs with OneSwap

OpenNebula provides OneSwap, a command-line tool designed to simplify migrating Virtual Machines from vCenter to OpenNebula. OneSwap has been used in the field with a 96% success rate in converting VMs automatically, greatly simplifying and speeding up the migration process.

OneSwap supports importing Open Virtual Appliances (OVAs) previously exported from vCenter/ESXi environments. The Managing OVAs and VMDKs guide provides instructions, with complete examples.

Architecture and Requirements

OneSwap can be run directly on the OpenNebula frontend or on a dedicated server. Running it on a separate server is recommended for production environments as it isolates the migration workload and avoids impacting the OpenNebula frontend during large or concurrent migrations.

The OneSwap server must have network access to:

• OpenNebula Front-end: to execute CLI commands (onevm, onedatastore, etc.) and transfer converted images to the datastores.
• vCenter/ESXi endpoint: to connect to the vCenter API and export virtual machine disks.

Run oneswap on a dedicated server with sufficient disk space to buffer VM images during conversion. This server should have high-bandwidth connectivity to both the vCenter environment and the OpenNebula image datastores to minimize migration time.

vCenter Permissions Requirements

OneSwap requires specific vCenter permissions depending on the conversion mode used. Below are the required privileges for vCenter 8.

Minimum Permissions (All Conversion Modes)

Datastore:

• Browse datastore - Required to discover VMDK files and VM storage configuration
• Used by: All conversion modes (standard virt-v2v, custom, hybrid, clone)

Network:

• Assign network - Required to read VM NIC configuration and network mappings
• Used by: All conversion modes

Resource:

• Assign virtual machine to resource pool - Required to read VM placement and resource allocation
• Used by: All conversion modes

Virtual machine > Change Configuration:

• Change Settings - Required to read VM hardware configuration (CPU, RAM, disks)
• Query unowned files - Required to access VM configuration files
• Used by: All conversion modes

Virtual machine > Edit Inventory:

• Create from existing - Required to read VM metadata and state
• Used by: All conversion modes

Virtual machine > Guest operations:

• Guest operation queries - Required to read guest OS information, IP addresses, and installed tools
• Used by: All conversion modes

Additional Permissions for Clone Mode (--clone)

Datastore:

• Allocate space - Required to provision storage for the cloned VM (thin provisioning)
• Used by: --clone mode only

Folder:

• Create folder - CRITICAL - Required to create the cloned VM in the same folder as the original
  • Without this permission, clone operations will fail with FileLocked: Unable to access file since it is locked
• Used by: --clone mode only

Virtual machine > Edit Inventory:

• Create new - Required to create the cloned VM
• Remove - Required to delete the clone after successful conversion
• Used by: --clone mode only

Virtual machine > Provisioning:

• Clone virtual machine - Required to execute the CloneVM_Task operation
• Customize guest - Required for VM customization during cloning
• Used by: --clone mode only

Additional Permissions for Custom/Fallback/Hybrid Modes

Datastore:

• Low level file operations - Required to download VMDK files directly from datastores
• Used by: --custom, --fallback, --hybrid modes

Permission Setup Example

Create a custom role in vCenter 8:

Role Name: OneSwap-Standard
Description: Minimum permissions for standard virt-v2v conversions

Permissions:
  - Datastore > Browse datastore
  - Network > Assign network
  - Resource > Assign virtual machine to resource pool
  - Virtual machine > Change Configuration > Change Settings
  - Virtual machine > Change Configuration > Query unowned files
  - Virtual machine > Edit Inventory > Create from existing
  - Virtual machine > Guest operations > Guest operation queries

For clone mode support, create an extended role:

Role Name: OneSwap-Clone
Description: Permissions for clone-based conversions (zero production impact)

Includes all permissions from OneSwap-Standard, plus:
  - Datastore > Allocate space
  - Folder > Create folder
  - Virtual machine > Edit Inventory > Create new
  - Virtual machine > Edit Inventory > Remove
  - Virtual machine > Provisioning > Clone virtual machine
  - Virtual machine > Provisioning > Customize guest
  - Virtual machine > Interaction > Power on
  - Virtual machine > Interaction > Power off

For download-based conversions (custom/fallback/hybrid):

Role Name: OneSwap-Download
Description: Permissions for custom conversion modes

Includes all permissions from OneSwap-Standard, plus:
  - Datastore > Low level file operations

Important Notes:

• Assign roles at vCenter root level with “Propagate to children” enabled
• For --clone mode, the VM must NOT have any snapshots (remove all snapshots before cloning)
• For --delta and --esxi modes, vCenter permissions are minimal as operations run via direct ESXi SSH

Installation

The package opennebula-swap, provided on the official repositories, provides the command oneswap.

It can be installed in Ubuntu with

apt install opennebula-swap

And in AlmaLinux and RHEL with

dnf install opennebula-swap

Requirements and recommended settings

OneSwap requirements for virtual conversion from VMWare to OpenNebula are the following:

• OneSwap is only supported on Ubuntu 24.04 LTS and Alma Linux/RHEL 9/10 servers. On previous versions of Ubuntu and Alma/RHEL some dependencies are outdated.
• A working OpenNebula environment with capacity enough to store imported images and VMs and a user with permissions on the destination datastores. Alternatively, conversion can be done with user oneadmin and set the right permissions in a posterior step.
• A vCenter endpoint with valid credentials to export the VMs.
  • The parameters vcenter, vuser, vpass and port must be specified.
  • If Delta conversion mode is being used, the user running oneswap command must have ssh passwordless access to the ESXi host where the VMs to convert are running.
• If oneswap is ran on a different machine than OpenNebula frontend, then the following components must also be configured:
  • Set up the transfer method options (oneswap parameters http_transfer, http_host and http_port).

Optional requirements and required tools

• VDDK library is recommended to improve disk transfer speeds. As of the moment of writing, the library can be downloaded from Broadcom developer portal. VDDK version MUST match the vCenter version.
• It is recommended to increase the vCenter API timeout to avoid request timeouts while converting big VMs. By default this value is 120 minutes and can be changed in vCenter at “Administration -> Deployment -> Client Configuration”, allowing values up to 1440 minutes (24 hours).
• The following libraries/programs must be installed
  • libguestfs library, version must be >= 1.50
  • libvirt library, version should be >= 8.7.0
  • virt-v2v, stable version

Ubuntu 24.04 and AlmaLinux/RHEL 9/10 provide up to date versions of the packages

Required software for migrating Windows Virtual machines

There are two requirements to convert Windows Virtual Machines:

• VirtIO ISO drivers must be stored in the /usr/local/share/virtio-win directory.
• RHsrvany, an Open Source srvany implementation to create the needed Windows services during the migration.
  • In AlmaLinux and RHEL this package is a dependency of OneSwap and will be installed automatically
  • In Ubuntu the package can be downloaded from fedoraproject.org.
    For compatibility with older versions of virt2v the following symlinks are needed

ln -s /usr/share/virt-tools /usr/local/share/virt-tools
ln -s /usr/share/virtio-win /usr/local/share/virtio-win

apt install -y rpm2cpio

wget -nd -O srvany.rpm https://kojipkgs.fedoraproject.org/packages/mingw-srvany/1.1/11.eln153/noarch/mingw-srvany-redistributable-1.1-11.eln153.noarch.rpm

rpm2cpio srvany.rpm | cpio -idmv \
  && mkdir /usr/share/virt-tools \
  && mv ./usr/i686-w64-mingw32/sys-root/mingw/bin/*exe /usr/share/virt-tools/

Migrating Virtual Machines

OneSwap supports two different modes for the migration of Virtual machines:

• Regular mode (non-delta)
  • Requires VMs to be powered-off (neither suspended or hibernating)
  • VMs to convert must not have any snapshot
• Delta mode is intended for low-downtime migrations (slower)
  • VMs must be powered on

On Linux VMs

• The virtual machine must have the kernel headers installed. The name of the package may differ on each distribution, for instance, in Ubuntu the package to install is linux-headers and in AlmaLinux is kernel-headers.
• The guest kernel version must support virtio drivers (kernel 2.6.30 or greater, which was issued on 2009-07-09).
• virt-v2v tool does not support updating GRUB2, if the following message is shown during the conversion process:

WARNING: could not determine a way to update the configuration of Grub2

booting the VM from a rescue CD and fixing grub may be necessary.

On Windows VMs

• Fast startup must be disabled (Control Panel -> Power Options -> Advanced power settings)
• Installing VirtIO Storage and Network drivers available at their github before the conversion will improve conversion times. If not, they will be injected later.
• Officially, Windows 2016 and onwards require UEFI boot.
• Windows VMs can only be converted with virt-v2v style transfer (custom and fallback styles will fail)

Virtual machines with UEFI BIOS

OneSwap normally detects if the VM boots in UEFI mode and sets up OpenNebula template accordingly, but in some strange cases autodetection may fail. In these cases, modify the following options on the OpenNebula template:

• CPU architecture: x86_64
• Machine type: q35
• UEFI firmware: UEFI (for secure firmware the box must be checked)

oneswap usage

Transfer methods

There are four methods to transfer the images from ESXi to OpenNebula. Ordered from faster to slowest:

• Hybrid
  • Use RbVmomi2 library to download locally the image before importing to OpenNebula.
  • Fast, but requires extra disk space as it copies the image.
• VDDK Library
  • Use VMWare Virtual Disk Development Kit library.
  • The parameter --vddk /path/to/lib must be defined.
• ESXi Direct SSH transfer
  • Copy the disk via SSH from the ESXi host. Incompatible with VDDK.
  • Requires defining the options --esxi, --esxi_user and --esxi_pass
• vCenter API
  • The slowest option (vCenter API is used to download the image).

A custom conversion option is also provided, which is only recommended as a fallback, that does not use virt-v2v. It relies on RbVmomi2, using qemu-img and virt-customize/guestfish to prepare the image for OpenNebula.

Importing VMs

Before migrations, oneswap can query ESXi VMs and datacenters

For convenience, it is a good practice to populate the /etc/one/oneswap.yaml file with the values that will be applied for the most migrated VMs. If the user running oneswap has no permissions to edit the file, it can be copied, modified and oneswap be executed with the parameter --config-file NEW_CONFIG_FILE.yaml

< Previous page Next page >