Migration from ESXi and XCP-ng

ProxCenter provides automated migration pipelines to move virtual machines from VMware ESXi and XCP-ng (Xen) to Proxmox VE. This is designed for organizations transitioning away from VMware or consolidating heterogeneous virtualization environments onto Proxmox.

Overview

The migration feature handles the entire workflow: connecting to the source hypervisor, downloading VM disks, converting disk formats, importing into Proxmox, and configuring the resulting VM. All progress is tracked in real time through the ProxCenter interface.

Two migration pipelines are available:

• ESXi to Proxmox -- Migrates VMs from VMware ESXi hosts, including VMs on vSAN datastores
• XCP-ng to Proxmox -- Migrates VMs from XCP-ng / Xen hosts via the XAPI interface

Migration Modes

ProxCenter offers two migration modes, selectable in the Migrate to Proxmox VE dialog.

Offline migration (cold). The source VM is powered off and its disks are copied in full, converted with qemu-img, then imported into Proxmox. This works for any source (ESXi, vCenter, XCP-ng). The open-source tooling the conversion needs on the Proxmox node (nbdkit, libnbd-bin) is installed automatically during the migration if it is missing, so the offline path needs no manual node preparation.

Warm migration (CBT). The source VMware VM stays online while ProxCenter copies its disks using VMware Changed Block Tracking. A short cutover then performs a clean guest shutdown and a final delta sync, so there is no data loss on large or busy disks. The online behavior requires CBT to be usable on the source VM: when it is not (most commonly because the VM carries a pre-existing snapshot), the migration falls back to a checksum mode with very different downtime characteristics, see CBT requirements and the checksum fallback. Warm migration needs a block-storage target (LVM, ZFS or Ceph) and the VMware VDDK runtime installed on the Proxmox node.

Warm migration requires manual node preparation

Unlike offline migration, the warm path cannot install its runtime automatically, and ProxCenter has never installed it for you. The VMware VDDK is a proprietary Broadcom SDK that cannot be redistributed, and the nbdkit VDDK plugin ships in the Debian non-free repository, which a stock Proxmox node does not enable. You must prepare each target node once, as described in Warm migration node setup, before a warm migration can start. ProxCenter runs a readiness check in the dialog and blocks the migration until the node is ready.

CBT Requirements and the Checksum Fallback

Warm migration keeps the source VM online only when VMware Changed Block Tracking (CBT) can actually be used. CBT is available when all of the following are true:

• The VM has no pre-existing snapshots. ProxCenter needs to establish the initial CBT baseline, and VMware only provides a reliable one on a snapshot-free VM.
• The virtual hardware version is vmx-07 or newer.
• No disk is in independent mode and no disk uses multi-writer sharing.

ProxCenter enables CBT on the source VM when needed. This is a standard VMware configuration flag, the same one backup products use, and it stays enabled after the migration.

When any of these conditions is not met, the migration automatically falls back to a checksum block-diff. The fallback is lossless, but its behavior differs from the CBT path in two important ways:

• The source VM is shut down at the very start of the copy, not at cutover, and stays powered off until the migration completes. Downtime therefore scales with total disk size, instead of the short final-delta cutover of the CBT path.
• Before any data is copied, ProxCenter reads each disk in full on both the source and the target to compute block checksums. On large disks this scan phase alone can take a long time.

The job log states which mode is in use: when the fallback is selected, a warning line reading CBT unavailable (pre-existing snapshot) - using checksum block-diff fallback appears at the start of the migration.

Keep the VM online: remove snapshots first

If minimizing downtime is the goal, delete or consolidate all VMware snapshots on the VM before starting the warm migration. With a snapshot-free VM, CBT is used, the bulk of the data is copied while the VM keeps running, and the VM is only shut down for the short final delta sync at cutover.

Prerequisites

• Source hypervisor credentials with permission to read VM metadata and export disks. See Source hypervisor privileges for the exact vCenter and ESXi role to grant.
• Target Proxmox API credentials with permission to create VMs and write to the target storage.
• SSH access to the target Proxmox node for import and conversion operations.
• Enough temporary storage and network bandwidth for full disk transfers.
• VirtIO drivers available for Windows guests when using VirtIO disk or network devices.
• For warm migration, the target Proxmox node also needs the VMware VDDK runtime installed once. See Warm migration node setup.

For large migrations, validate one representative VM before scheduling a bulk migration window.

Source hypervisor privileges

ProxCenter never modifies the source VM. It authenticates to the source hypervisor, reads the VM configuration and inventory, and exports the disks. The account you use therefore needs read access plus the right to export a VM. The exact requirements differ slightly between a standalone ESXi host and a vCenter.

vCenter

vCenter migrations use the canonical NFC transport: ProxCenter asks vCenter to open an export lease (the ExportVm and ExportSnapshot API) and streams the disks over it. This requires the vApp > Export privilege. When it is missing, vCenter rejects the export with SOAP error 500: Permission to perform this operation was denied, and the migration stops at the "Initiating NFC export lease" step.

The simplest least-privilege setup is to clone the built-in Read-only role, add the privileges below, then assign the resulting role to your migration user at the datacenter level, propagated to child objects so it covers both the VMs and their datastores.

Privilege	Required for
vApp > Export	Opening the NFC export lease. Mandatory, this is the privilege that triggers the SOAP 500 above when absent.
Virtual machine > Provisioning > Allow read-only disk access	Reading the disk data over the lease
Virtual machine > Provisioning > Allow virtual machine download	Downloading the disk and descriptor files
Virtual machine > Interaction > Power Off	Offline migration powers the source VM off before export
Virtual machine > Snapshot management > Create snapshot	Warm migration creates a transfer snapshot
Virtual machine > Snapshot management > Remove snapshot	Warm migration removes the transfer snapshot after cutover
Read-only (built-in role, used as the base)	Authentication and reading VM configuration and inventory

The built-in Administrator role already includes all of these, so an administrator account works without any extra configuration. The table above is only needed when you want a dedicated, least-privilege migration account.

Standalone ESXi

A direct ESXi migration downloads the disks over the host datastore API rather than through an NFC lease. A user in the host Administrator role works out of the box. For a restricted account, grant read access to the VM and its datastore, plus Virtual machine > Interaction > Power Off for offline migration.

Pipeline Stages

Each migration goes through these sequential stages:

1. Download

The VM disk is downloaded from the source hypervisor. For ESXi, this uses the VMware VDDK / HTTP file access. For XCP-ng, the disk is exported via the XAPI export interface.

2. Convert

The downloaded disk is converted to a Proxmox-compatible format using qemu-img convert. VMDK files (ESXi) and VHD files (XCP-ng) are converted to qcow2 or raw format depending on the target storage type.

3. Import

The converted disk is imported into Proxmox using qm disk import, which uploads the disk to the selected target storage and associates it with a new or existing VM.

4. Configure

The imported VM is configured with the original settings: CPU count, memory, network interfaces, and boot order. The boot disk is set automatically so the VM is ready to start.

info

For EFI-based VMs, ProxCenter automatically handles the EFI disk allocation. The data disk may be assigned to disk-1 instead of disk-0 since disk-0 is used for the EFI disk.

Warm Migration Node Setup

Before the first warm migration to a Proxmox node, install the VDDK runtime on that node. The dialog probes the selected node and shows "Target node is not ready for warm migration" with the list of missing components until all of them are present. This is a one-time setup per node.

The warm path needs four components on the Proxmox node:

Component	Source	Notes
nbdkit	Debian main	Available on a stock Proxmox node.
nbd-client	Debian main	Available on a stock Proxmox node.
nbdkit-plugin-vddk	Debian contrib / non-free	Not enabled by default on Proxmox. Enable the repositories first.
Broadcom VDDK (libvixDiskLib.so*)	Broadcom download	Proprietary SDK. Requires a Broadcom account and acceptance of the license.

Network access to the ESXi hosts (TCP 443 and 902)

Warm migration copies disk data with the VMware VDDK in NBD transport mode, which uses the NFC (Network File Copy) protocol. The target Proxmox node must reach each source ESXi host on both TCP 443 (authentication and management) and TCP 902 (the NFC data channel that carries the disk blocks).

Port 443 alone is not enough. Authentication and the node readiness check will pass, the target disks will be allocated, and the migration will only fail later at the VixDiskLib_Open step against the ESXi host, when VDDK opens the NFC data channel. Open TCP 902 from the Proxmox node to every ESXi host before starting a warm migration.

1. Install nbdkit and nbd-client

These are in the standard Debian repositories:

apt update
apt install nbdkit nbd-client

2. Install the nbdkit VDDK plugin

The plugin lives in Debian non-free. Enable contrib and non-free in the node's apt sources, then install it:

# Proxmox VE 8 (Debian 12): add contrib and non-free to the apt sources, e.g.
#   deb http://deb.debian.org/debian bookworm main contrib non-free non-free-firmware
apt update
apt install nbdkit-plugin-vddk

3. Install the Broadcom VDDK

The VMware Virtual Disk Development Kit (VDDK) is a proprietary Broadcom SDK and is not available from any package repository. Download it from the Broadcom developer portal (a Broadcom account and acceptance of the license are required):

https://developer.broadcom.com/sdks/vmware-virtual-disk-development-kit-vddk/latest/

Install the runtime libraries under /usr/lib/vmware-vix-disklib so that libvixDiskLib.so* ends up in /usr/lib/vmware-vix-disklib/lib64/:

# After downloading VMware-vix-disklib-<version>.x86_64.tar.gz from Broadcom:
mkdir -p /usr/lib/vmware-vix-disklib
tar xzf VMware-vix-disklib-*.tar.gz -C /usr/lib/vmware-vix-disklib --strip-components=1
ldconfig

VDDK 9.x library name

The nbdkit version shipped with Proxmox loads the libvixDiskLib.so.8 library name. If you installed VDDK 9.x, create the matching symlink (or install VDDK 8.0.x instead):

cd /usr/lib/vmware-vix-disklib/lib64
ln -sf libvixDiskLib.so.9 libvixDiskLib.so.8
ldconfig

4. Prevent LVM from auto-activating guest volume groups

Required when migrating Linux guests that use LVM (most enterprise Linux templates). During a warm migration the guest disk is attached to the Proxmox node as an NBD device. If the node's LVM scans it, it auto-activates the guest's volume group on the host and pins the NBD device: the migration can no longer release it afterwards, nbd-client -d and rmmod nbd both fail, and the device stays wedged until the node is rebooted.

Tell LVM to ignore NBD devices on the target node. Edit /etc/lvm/lvm.conf and, in the devices { } section, set:

global_filter = [ "r|/dev/nbd.*|", "a|.*|" ]

Then reboot the node. The reboot both applies the filter and clears any device that is already wedged. If you prefer not to reboot, run vgchange -an <guest-vg> for the activated guest volume group and pvscan --cache after editing the file.

Why this is safe on Proxmox

Proxmox's own LVM and LVM-Thin storage lives on physical disks, never on /dev/nbd*, and warm migration reads the guest disk as a raw device rather than through LVM. The filter only stops LVM from touching the transient NBD devices used during migration.

5. Reselect the node

Back in the Migrate to Proxmox VE dialog, reselect the target node. The readiness check runs again and, once every component is detected, shows "Target node is ready for warm migration" and enables the migration button.

What the readiness check verifies

ProxCenter confirms nbdkit and nbd-client are on PATH, that nbdkit-vddk-plugin.so exists under /usr/lib or /usr/lib64, and that libvixDiskLib.so* exists under the VDDK library directory (/usr/lib/vmware-vix-disklib/lib64 by default).

Starting a Migration

1. Navigate to Automation > Migration
2. Select the source type (ESXi or XCP-ng)
3. Enter the source hypervisor connection details (host, credentials)
4. ProxCenter connects and lists all VMs available on the source
5. Select one or more VMs to migrate
6. Choose the target Proxmox connection, node, and storage
7. Configure options (VM name, VMID, network bridge, etc.)
8. Start the migration

Bulk Migration

You can select multiple VMs and migrate them in a single batch. Migrations run sequentially to avoid overloading the network and storage. The Task Center shows progress for each VM individually.

tip

For large migrations, consider running them during off-peak hours. Each VM migration involves downloading the full disk image, which can take significant time depending on disk size and network bandwidth.

Cross-Cluster Migration

ProxCenter tracks progress for offline cross-cluster VM moves between Proxmox environments. Progress updates are reported in the UI so operators can distinguish long-running disk transfer from stalled operations.

When migrating to another cluster, you can target a specific VMID on the destination. VLAN tags on migrated network interfaces are preserved when the target bridge supports the same network design.

vSAN Support

ProxCenter supports migrating VMs from ESXi hosts that use VMware vSAN storage. The migration pipeline handles the vSAN object retrieval transparently -- no special configuration is needed beyond providing valid ESXi credentials with read access to the datastore.

Storage Considerations

The target storage type affects the import behavior:

Storage Type	Disk Format	Volume Naming
Local (directory)	qcow2	local:VMID/vm-VMID-disk-N.qcow2
NFS	qcow2	nfs-storage:VMID/vm-VMID-disk-N.qcow2
LVM / LVM-Thin	raw	lvm-thin:vm-VMID-disk-N
ZFS	raw	zfs-pool:vm-VMID-disk-N
Ceph RBD	raw	ceph:vm-VMID-disk-N

Troubleshooting

Migration stuck at "Import" stage The qm disk import command can take a long time for large disks. Check the Task Center for the detailed log output.

VM does not boot after migration Verify the boot order is set correctly. For EFI VMs, ensure the OVMF BIOS is selected in the VM hardware settings. You may need to change the disk controller from VirtIO to IDE/SATA if the guest OS does not have VirtIO drivers.

Network not working after migration (interface renamed, no IP) After migration a Linux guest often renames its network interface, for example from ens192 to enp6s18, and comes up without an IP. This is expected behavior, not a ProxCenter bug: systemd derives "predictable" interface names from the PCI address and card model, not from the MAC address. VMware presents a VMXNET3 card, which the guest names ens192. Proxmox has no VMXNET3, so ProxCenter converts the card to VirtIO on a q35 machine; the card lands at a different PCI address and the guest names it enp6s18. The guest's existing configuration still refers to the old name, so nothing binds to the new interface.

ProxCenter preserves the source NIC's MAC address on the migrated VM, so both fixes below are reliable and any DHCP reservation keyed on the MAC keeps working.

Option A, point the config at the new name (simplest for a single VM). Run ip -br link in the guest to find the new name, then update the network configuration:

• Debian / Ubuntu (ifupdown): edit /etc/network/interfaces, replace ens192 with the new name, then systemctl restart networking.
• Netplan: edit /etc/netplan/*.yaml, replace the interface name, then netplan apply.
• RHEL / NetworkManager: rename /etc/sysconfig/network-scripts/ifcfg-ens192 to match the new device and set DEVICE=, or use nmcli con mod.

Option B, keep the old name (good for a fleet or scripted configs). Pin the name to the preserved MAC with a systemd link file. Create /etc/systemd/network/10-net-persist.link:

[Match]
MACAddress=aa:bb:cc:dd:ee:ff

[Link]
Name=ens192

Rebuild the initramfs (Debian / Ubuntu: update-initramfs -u, RHEL: dracut -f) and reboot. The interface comes back as ens192 and the original configuration applies unchanged.

Static IP after migration

A migrated VM keeps its own in-guest network configuration; ProxCenter does not push a static IP into the guest after migration. Set static addressing inside the guest using either option above.

For Windows guests, the VirtIO network driver may need to be installed before the VirtIO NIC works. Make sure the VirtIO driver media is available as described in Prerequisites.

"Target node is not ready for warm migration" The selected node is missing one or more warm-migration components (nbdkit, nbd-client, nbdkit-plugin-vddk, or the Broadcom VDDK). Prepare the node as described in Warm migration node setup, then reselect the node in the dialog. This requirement applies to warm migration only: offline migration installs its open-source tooling automatically and does not need the VDDK.

Warm migration fails with VixDiskLib_Open ... Unknown error returned by server The target Proxmox node cannot reach the source ESXi host on TCP 902. Warm migration authenticates to vCenter over 443, but the VDDK reads the disk blocks directly from the ESXi host over the NFC protocol on TCP 902. When 902 is blocked, authentication, the node readiness check and target disk allocation all succeed, and the migration fails only at the full-copy step with VixDiskLib_Open naming the ESXi host rather than vCenter. Open TCP 443 and 902 from the Proxmox node to every source ESXi host, as described in Warm migration node setup.

Warm migration fails with "nbd: nbd0 already in use" or a wedged NBD device A previous warm migration of a Linux/LVM guest left an NBD device pinned on the target node: the host auto-activated the guest's LVM volume group on it, so nbd-client -d returns success without freeing it and rmmod nbd reports the module is in use (lsof shows nothing, because the holders are LVM / device-mapper, not open files). Prevent this by setting the LVM global_filter described in step 4 of Warm migration node setup; reboot the node to clear a device that is already wedged.

warning

Migration requires SSH access to the target Proxmox node for disk import operations. Make sure the SSH connection is configured in Settings > Connections.

Enterprise Feature

The Migration feature is available in the Enterprise edition.

Permissions

Permission	Description
vm.create	Required to create the target VM on Proxmox
storage.write	Required to import disks to the target storage
migration.manage	Required to initiate and manage migration jobs