How to migrate and clone a VM

The operations on this page serve different purposes. Live migration moves a running VM's compute state—memory and CPU state—to another node without touching its data. Storage migration moves VM datasets from one pool to another through a ZFS send/receive stream. Cloning creates a copy-on-write copy of the disks on the same pool in seconds, with almost no capacity usage. Restoring from the import area recreates a VM from a stream previously received by the cluster.

This defines where each operation applies. Moving data between pools takes time proportional to disk size and requires a powered-off VM. Live migration of compute state, by contrast, works only on a running VM: the guest OS continues running, and downtime is limited to the switchover window, set by a parameter. A clone is instant, but resides on the same pool and depends on a source snapshot: while the clone exists, the source cannot be deleted, and ZFS prevents rolling it back to a snapshot older than the cloning point.

A clone inherits the entire source configuration: vCPU, RAM, disks, networks, and guest settings. These cannot be overridden at creation; only the name and description are specified. MAC addresses are generated again, and IP addresses are allocated as during normal creation, but only for the address families in which the source port had an address.

How to migrate a running VM to another node

Live migration was introduced in 3.1.0. It moves a running VM's compute state to the selected node; disks remain in their pool and are accessible to the new node over the network. The guest OS continues running and is unavailable only during switchover.

The operation is available to the Cluster master role through the Live Migrate VM privilege (1607). Assign the privilege to a custom role manually. Reading progress requires a separate privilege, View VM Migration Status (1113).

Prerequisites:

• The VM is running and its initial setup is complete.
• The target node exists and differs from the current node.
• The VM is not locked and no other migration is in progress for it.
• The cluster has an available transfer port for the memory stream.

1. Open the VM card and start migration, selecting the "to another node" type and the target node. The overall operation timeout (300 seconds) and switchover window (100 milliseconds) use their default values and cannot be configured in the interface.
2. The operation is accepted immediately, and work continues in the background.
3. Monitor migration progress: the state, phase, completion percentage, source and target nodes are reported, along with the failure reason if it fails.

Until migration finishes, operations that could interfere with it—stopping, changing configuration, and unlocking—are rejected with a clear error. Reading VM data remains available. During migration, the migration itself controls the VM state: at completion, the VM is listed as running or receives a migration error.

Progress does not survive a page reload

Migration progress is tied to the identifier of the started operation, and the API has no method to "find the active migration for a VM". If you refresh the page, the completion percentage is no longer displayed, but migration continues. You can tell that the VM is being migrated by its state in the VM list.

Failure	Reason	Workaround
-403 missing privilege	The role lacks Live Migrate VM or View VM Migration Status	Perform the operation under the Cluster master role or assign the privilege to a custom role
-1601 invalid migration type	The specified type is outside the "compute" / "storage" set	Select one of the two procedures
-1602 unsuitable parameter set	A target pool was supplied for migration to a node, or vice versa	Specify a target node to change nodes, or a target pool to change pools
-1603 VM not found	A nonexistent VM identifier was specified	Check the identifier in the VM list
-1604 VM outside access scope	The VM belongs to a VDC unavailable to the role	Work in your VDC
-1605 VM state does not allow migration	For a node change, the VM is not running or its initial setup is incomplete	Start the VM and wait for setup to finish
-1606 target node not found	No node with that number exists in the cluster	Select a node from the cluster's node list
-1607 target node is the current node	The VM is already running on this node	Select another node
-1608 live migration unavailable	The transfer port pool is exhausted	Wait for current migrations to finish
-1611 migration already in progress	The VM is locked or has an unfinished migration	Wait for completion and retry
-1612 migration not found	Status was requested for an unknown identifier	Use the identifier returned when migration was started

To migrate data between pools, the same method accepts a second procedure, with a target pool instead of a target node and a stopped VM. The legacy path through vm-migration is described below; it remains operational.

How to migrate a VM to another pool

Migration is available only to the Cluster master role and requires migration to be enabled in the cluster settings.

Prerequisites:

• The VM is powered off, or has been created but never started.
• The target pool differs from the current pool.
• The target pool is imported on a cluster node.
• An available port exists for the send/receive stream.

Start migration and specify the target pool. The operation completes a full cycle: stream transfer, re-registration of disks, snapshots, and the VM itself on the new pool, and deletion of the source datasets. The VM remains locked until the cycle finishes; the result is shown on its card and in the event history.

Failure	Reason	Workaround
-25300 operation available only to the Cluster master role	Another role requested migration	Perform the operation under a cluster-level role
-25306 VM not in Offline/Created state	The VM is running or suspended	Stop the VM
-25305 migration to the same pool is impossible	The target pool is the current pool	Specify another pool
-25307 unable to determine the node for the migration pool	The pool is not imported	Check the target pool state
-25304 unable to determine the node for the VM	The VM's placement is unknown	Check the VM's node and pool states
-25308 no available send-receive ports	All transfer ports are occupied	Wait for current transfers to finish
-25310 migration failed	Re-registration failed after transfer	Check the VM state on both pools and retry

Account for clones separately: if the VM being migrated has existing CoW clones, migration encounters a dependency when deleting the source datasets. This is a known limitation. Delete the clones before migration.

How to clone a VM

A clone is a new VM with the same configuration in the same VDC (virtual data center) and on the same pool. You need the VM creation privilege with scope for the source VDC.

1. Stop the source VM. Cloning a running VM is rejected with error -2603.

2. Start cloning the source and enter the clone's name and, optionally, a description. Other parameters are inherited and cannot be edited at this point.

3. Wait for the clone to appear in the VM list. It is created through the same sequence as a new VM: first the record, then assembly on the node.

Cloning restrictions

Restriction	Reason	Action
The clone always resides on the source pool	This is how zfs clone works	If you need a copy on another pool, clone first, then migrate
The configuration cannot be overridden	The clone inherits the source's entire vCPU, RAM, disk, and network configuration	Edit parameters on the clone's card after creation
One invocation creates one clone	No batch mode is available	Repeat the operation as many times as needed
The source cannot be deleted while a clone exists	The clone depends on a source snapshot	Delete the clones, then the source; otherwise, deletion returns -2604 with a list of clones
Service VMs cannot be cloned	The clone would inherit the service binding without the supporting setup: error -2605	Create the service VM through the standard procedure
A clone cannot be cloned	A clone of a clone would create a chain of dependent ZFS clones. Error -2606 is returned before the source's lock and state checks	Clone the original VM again. The VM retains its clone marker permanently, including after the source is deleted
Two clones of one source in the same second	Both operations use the same snapshot-point name	Usually, the second operation reuses the first operation's snapshot; if a race occurs, retry the operation

Other failures: -2601 means the source was not found, -2602 means the source is locked, -2610 means clone creation failed, -255 means the source pool does not accept data, -256 means the source OS profile was not found, and -403 means insufficient privileges or the VM is outside the role's scope.

How to restore a VM from the import area

The import area is where the cluster receives VM streams from outside. Restoring from it is a separate operator step: the VM is not recreated automatically.

The import area opens on the Import area tab: a table with Dataset Id, VM name, and Progress columns. Cluster master sees all records; an ordinary user sees records for VDCs where they have an administrator role.

1. Find the required record and make sure reception is complete: the Progress column shows transfer progress, and only fully received records can be restored.

2. Decide which identifiers to use for restoring the VM. By default, restore uses the original identifiers. In that case, no VM with the same identifier can exist in the cluster; otherwise, error -25208 is returned. In the second mode, vStack Center assigns new identifiers and does not perform this check. Also check whether the original pool and VDC still exist.

3. Start restore for the selected record and wait for the VM to appear in the VM list.

By default, restore recreates the VM with its original identifiers: VM, disk, and network port records, console ports, and, if present, the snapshot registered with the stream.

The second mode assigns new identifiers. vStack Center creates the VM as new: its own identifier, disks in a new dataset, new console ports, and new network ports in the same networks. The ports receive new addresses and MAC addresses, with IP guard enabled. A snapshot received with the stream is registered in both modes.

Failure	Reason	Workaround
-25206 Import area item is not finished	Stream reception is incomplete	Wait for reception to finish
-25208 Specified VM id exists already	A VM with the original identifier already exists in the cluster	Delete the conflicting VM or restore with new identifiers. Renaming does not free the identifier
-25205 VM item is not defined, -25207 Import area item has no VM id	The import area record is incomplete	Receive the stream again
-25209 Can't retrieve pool map	The record's pool is unavailable	Check the pool state
-25210, -25211 console port allocation failed	Console ports could not be allocated	Retry later
-25220–-25223 MAC or port address conflict	The address or MAC address from the record is already in use	Free the address or delete the conflicting port
-25224 Can't parse dataset name	The dataset name cannot be parsed	Select the record from the import area list again

See also

• How to take VM snapshots and roll back to them — what cannot be rolled back while a clone exists
• How to create, delete, and move a virtual machine — creating a VM from scratch and deleting the source

API methods

The API operations for this page are vm-migrate, vm-migrate-status, vm-migration, vms-clone, vm-import-area-list, and vm-import-area-process—see the API reference.