Migrating a Proxmox VM Between Unclustered Hosts

Migrating virtual machines (VMs) between Proxmox hosts usually requires them to be in the same cluster. But what if you need to move a VM between completely separate hosts, without clustering them first? Maybe you’re shifting workloads to a new Proxmox environment or just performing a one-off transfer. Whatever your reason, there’s a way to get it done smoothly. Since v7.3, Proxmox has implemented a method of doing this, without using clustering!

What You’ll Need

• Two Proxmox hosts running on the same or compatible versions
• Administrative access to both hosts
• An API token generated on the destination host
• Enough storage space on the target host for the migrated VM

Generating the API Token

Before the migration can begin, you’ll have to create an API token on the target Proxmox host. This token allows authentication for the migration process without requiring full user credentials.

1. Open the Proxmox web interface on the destination host.
2. Navigate to Datacenter > API Tokens > Add.
3. Select your administrative user (e.g., root@pam) and click Add.
4. Name the token ID something relevant, like migrate_token, and generate a secret by clicking Add. Turn off Privilege Separation. This will give your API key full access!
5. Copy both the token ID and the secret key – they will not be visible again.

Performing the Migration

The qm remote-migrate command handles VM transfers between Proxmox hosts that are not in the same cluster. This method can move storage and compute workloads, all while keeping the VM running if necessary.

The general syntax for the migration command is:

qm remote-migrate <source_vmid> <destination_vmid> 'apitoken=PVEAPIToken=<username>@<realm>!<token_name>=<secret>,host=<destination_host>,fingerprint=<destination_fingerprint>' --target-bridge <bridge_name> --target-storage <storage_name> --online

Here’s a breakdown of the parameters:

• <source_vmid>: The ID of the VM on the source host
• <destination_vmid>: The desired ID on the destination host (can often be the same as the source)
• apitoken=PVEAPIToken=<username>@<realm>!<token_name>=<secret>: The API token generated earlier
• host=<destination_host>: The hostname or IP of the target Proxmox machine
• fingerprint=<destination_fingerprint>: The fingerprint of the target host’s certificate (can be omitted initially, but Proxmox will display it and specify you need to include it while showing you what the fingerprint is)
• --target-bridge <bridge_name>: Ensures network connectivity remains the same
• --target-storage <storage_name>: Specifies where the VM disk should be stored on the new host
• --online: Performs a live migration while keeping the VM running (optional)

For example, if migrating VM ID 134 to 205 on a destination Proxmox node called pve-dest, using an API token tied to root@pam with storage set to nvme-storage, the command would look like this:

qm remote-migrate 134 205 'apitoken=PVEAPIToken=root@pam!migrate_token=abc123,host=pve-dest,fingerprint=D4:9A:3F:B7:62:E1:88:AC:45:7D:C2:14:F0:38:9E:6B:71:A5:5D:8F:92:CE:4B:DF:29:76:13:E8:FA:07:B4:CD' --target-bridge vmbr0 --target-storage local-lvm --online

Understanding the Migration Process

When the command is executed, the following happens:

1. The source VM begins transferring its storage to the destination.
2. If --online is included, downtime is minimized to just a few seconds.
3. The VM gets stopped on the source and finalized on the destination.
4. The source machine retains a copy of the VM (turned off).

With my test environment, a VM with a 64GB data drive was migrated between two local NVMe drives over gigabit networking, and took about 10 minutes to complete. The process dropped only 1 packet, and my active terminal session remained uninterrupted.

Cleaning Up the Old VM

By default, the source Proxmox host retains the old VM even after migration. To remove it, use:

qm destroy <source_vmid>

Replace <source_vmid> with the original VM ID from the source Proxmox machine.

Finally, you will want to remove your API key when you’ve completed migrating. This will prevent potential unauthorized access to your server via token at a later date.

Migrating a Proxmox VM between unclustered hosts without clustering is not only possible, its incredibly easy using qm remote-migrate. This method preserves networking, keeps downtime minimal with supporting live migrations, and doesn’t require complex workarounds.

For those needing to shift workloads between Proxmox hosts, this command could save hours of manual work. Now go forth and migrate with confidence!