Importing a VM or a physical machine with incus-migrate

Read this page in French

The incus-migrate tool imports an existing machine (a virtual machine from another hypervisor, a disk, or even a physical server) into Incus, as an instance. It works interactively: you tell it the target Incus server, the source to import and a few options, and it does the rest. This guide walks the procedure, the accepted formats and the UEFI and NVRAM trap that so often stops an imported machine from booting. For people migrating from VMware, Proxmox or a physical server.

What you will learn

• Fetch and run incus-migrate.
• The interactive flow of the import.
• The accepted disk formats.
• The UEFI trap that prevents boot, and how to work around it.

Prerequisites

• A target Incus server with its API exposed on the network (core.https_address).
• rsync installed on the source machine.
• An access token for the Incus server (incus config trust add) or a certificate.

Fetching the tool

On a system installed from the Zabbly repositories, incus-migrate ships in the incus-extra package:

sudo apt install incus-extra
which incus-migrate   # /usr/bin/incus-migrate

Failing that, it is also a standalone binary published in the assets of the Incus releases, which is handy on a source machine that does not carry the repository:

wget https://github.com/lxc/incus/releases/download/<version>/bin.linux.incus-migrate.x86_64
chmod u+x bin.linux.incus-migrate.x86_64
sudo ./bin.linux.incus-migrate.x86_64

The interactive flow

The tool asks a series of questions; there is no long command line to memorise.

1. Local or remote target: "The local Incus server is the target". Answer no to import into a remote Incus server, then give its URL and validate the certificate fingerprint.

2. Authentication: three choices, including the token generated with incus config trust add. The tool then prints the name and version of the remote server.

3. Type: container, virtual machine, a VM from an .ova, or a custom volume.

4. Target within the cluster: if the target is a cluster, an extra question asks whether to aim at a specific node, otherwise placement is automatic.

5. Name and source: the instance name, then the path to the rootfs (container) or to the disk or bootable image (VM), plus any additional mounts.

6. UEFI Secure Boot (VM only): the question "Does the VM support UEFI Secure Boot?" sets security.secureboot on the created instance.

7. Overrides (optional): profiles, storage pool, size, network, disks, before launching with "Begin the migration".

Here is the real end of a container import into an Incus 7.0 cluster (source: the / of a machine, target: the cluster):

Remote server:
  Hostname: node1
  Version: 7.0.0

Instance to be created:
  Name: imported-box
  Project: default
  Type: container
  Source: /

Additional overrides can be applied at this stage:
1) Begin the migration with the above configuration
...
Please pick one of the options above [default=1]:
Transferring instance: imported-box: 1.08GB (35.90MB/s)
Instance imported-box successfully created

The transfer runs over rsync, hence the prerequisite. The instance is then created, stopped, ready to start. On a cluster it is placed automatically (here on node3) unless you targeted a node:

+--------------+---------+-----------+----------+
|     NAME     |  STATE  |   TYPE    | LOCATION |
+--------------+---------+-----------+----------+
| imported-box | STOPPED | CONTAINER | node3    |
+--------------+---------+-----------+----------+

The accepted formats

For a virtual machine, incus-migrate consumes the common formats directly: raw, qcow2, ova and vmdk. The qcow2 and vmdk support arrived together in Incus 6.6, so no manual conversion is needed for any of them.

For an image coming from VMware or VirtualBox, preprocessing with virt-v2v is often necessary to inject the virtio drivers, without which the disk is not detected at boot:

virt-v2v -i disk source.vmdk -o local -of raw --block-driver virtio-scsi

The UEFI and NVRAM trap

This is the classic headache: the imported machine does not boot, showing a black screen or a UEFI shell.

The EFI boot configuration is not in the disk image

The UEFI boot configuration lives in the NVRAM of the original machine, not in the disk image. Converting the disk therefore does not restore the boot entry: the imported machine cannot find its bootloader (the typical VirtualBox to Incus case, whereas QEMU to Incus goes through). The workaround, applied before the migration, creates a standard fallback boot path:

grub-install /dev/sdX --removable

That writes \EFI\BOOT\bootx64.efi, which firmware always finds.

One more thing to watch: without the virtio drivers in the image (VMware or VirtualBox), the disk is not seen at boot, which is what virt-v2v is for.

Key points

• incus-migrate imports a virtual or physical machine into Incus, interactively; it ships in the incus-extra package, or as a standalone binary.
• Answer no to "local server is the target" to aim at a remote server; on a cluster, placement is automatic unless a node is targeted.
• Prerequisites: the API exposed (core.https_address), rsync on the source, and an access token (incus config trust add).
• Direct formats: raw, qcow2, ova and vmdk (qcow2 and vmdk since Incus 6.6).
• UEFI trap: the boot configuration lives in NVRAM, not on the disk, so prepare a fallback with grub-install --removable.
• VMware and VirtualBox images: inject the virtio drivers with virt-v2v.

FAQ: common questions about incus-migrate

How do you import an existing VM into Incus?

With the incus-migrate tool, a standalone binary from the Incus releases. You download it, make it executable and run it as root. It asks questions interactively: target Incus server, token authentication, instance type, source disk path, UEFI support, then overrides.

Which disk formats does incus-migrate accept?

For a virtual machine, incus-migrate consumes raw, qcow2, ova and vmdk directly, with no manual conversion. qcow2 and vmdk support was added in Incus 6.6.

Why does my VM imported into Incus fail to boot?

Most often because of UEFI. The EFI boot configuration lives in the NVRAM of the original machine, not in the disk image: converting the disk does not restore the boot entry, so the virtual machine cannot find its bootloader.

How do you migrate a VMware or VirtualBox VM to Incus?

You import the disk with incus-migrate, but you often have to prepare the image with virt-v2v to inject the virtio drivers, otherwise Incus does not detect the disk at boot. You also have to handle the UEFI trap by creating a boot fallback with grub-install --removable before migrating.

Next steps

• Debugging an Incus VM stuck at boot: the exact procedure for an imported machine stuck in emergency mode.
• Migration Manager: the batch tool when a whole VMware estate has to move.
• Automating Incus image builds: build your own images rather than importing legacy machines indefinitely.

×

📖 Voir la documentation →