{"id":1836,"date":"2026-09-15T10:19:53","date_gmt":"2026-09-15T10:19:53","guid":{"rendered":"https:\/\/www.blackrack.pl\/?p=1836"},"modified":"2026-09-15T12:49:14","modified_gmt":"2026-09-15T12:49:14","slug":"new-version-of-hv2pve-1-0-3","status":"publish","type":"post","link":"https:\/\/www.blackrack.eu\/en\/new-version-of-hv2pve-1-0-3\/","title":{"rendered":"New version of hv2pve – 1.0.3"},"content":{"rendered":"\n

In older versions of hv2pve<\/code>, migration required the virtual machine to be shut down on the Hyper-V side before the process could begin. The result? Every migration involved system downtime, which made the process difficult to use in production environments. The length of the downtime depended on the size of the virtual machine’s disks.<\/p>\n\n\n\n

The biggest new feature in the current version<\/h2>\n\n\n\n

Thanks to the AVHDX Migrate Chain technology (hd2raw<\/code>) , it is now possible to migrate a virtual machine without shutting it down, significantly reducing service downtime. The entire process takes place online, while the final synchronization of the last snapshot and starting the system on the destination side takes from a few to several dozen seconds in our tests, depending on the current VM workload. The hd2raw<\/code> tool enables direct synchronization of AVHDX<\/code> files to the raw<\/code> format and streams them directly to a disk in the Proxmox environment. This eliminates the need to merge the AVHDX<\/code> chain beforehand on the Windows side, simplifying the entire migration process and reducing the overall operation time.<\/p>\n\n\n\n

What it looks like without our tool<\/h2>\n\n\n\n

Without using our tool, the migration process from Hyper-V to Proxmox is performed entirely manually. The administrator must first export the VHDX<\/code>\/AVHDX<\/code> disks and merge the snapshot chain on the Hyper-V side. The disks then need to be converted to a format supported by Proxmox – most commonly raw<\/code> or qcow2<\/code>. The next step is to manually create a virtual machine in the Proxmox environment, attach the converted disks, and recreate the hardware configuration (CPU, RAM, network, controllers).<\/p>\n\n\n\n

Each of these steps is a separate operation that requires attention and time. As the number of virtual machines being migrated increases, so does the risk of configuration errors. More importantly, the downtime covers the entire time required to copy and convert the data, which in practice can mean several hours of downtime for larger disk volumes.<\/p>\n\n\n\n

How it works under the hood (in brief)<\/h2>\n\n\n\n

The migration process was designed to be predictable, repeatable, and safe – especially when using AVHDX Migrate Chain (AMC). Below is a simplified description of how it works, based on one key assumption: we work with exactly three snapshots.<\/p>\n\n\n\n

The migration starts with an inventory on the Hyper-V side. The tool verifies whether the machine meets the migration requirements and whether its state matches the selected mode. In standard mode, the VM must be shut down, while in AMC (AVHDX Migrate Chain) mode it can remain running. The tool also checks whether sufficient storage space is available on Proxmox and whether a machine with the given ID has already been migrated. This helps prevent simple migration errors.<\/p>\n\n\n\n

On the Proxmox VE side, a complete virtual machine definition is created, including the disks and their correct attachment to the configuration. The machine is then started and immediately paused, which makes it possible to minimize the subsequent downtime during the actual switchover. This preparation is crucial because the actual import is performed on an already prepared structure. At this stage, the init<\/code> tag is also assigned, allowing the process to be safely resumed if it is interrupted (e.g. due to network errors).<\/p>\n\n\n\n

In AVHDX Migrate Chain (AMC) mode, the actual migration takes place in three snapshot stages:<\/p>\n\n\n\n

Snapshot 1<\/strong> – once it is created, migration of the base VHDX<\/code>\/VHD<\/code> file begins. The snapshot captures all changes made while the large base disk is being copied, allowing the machine to continue operating normally.<\/p>\n\n\n\n

Snapshot 2<\/strong> – created after the base transfer has completed. It contains the changes generated during the migration of the first layer. The first differencing file is then migrated and merged on both sides – on Hyper-V using the native mechanism and on Proxmox using hd2raw<\/code>.<\/p>\n\n\n\n

Only after the second snapshot has been migrated and merged does the virtual machine shutdown process begin. At this point, the migrator executes the following PowerShell command on the Microsoft Hyper-V host:<\/p>\n\n\n\n

Stop-VM -VMName {vmid}<\/code><\/pre>\n\n\n\n
This is the point at which the process enters a short, controlled downtime phase.<\/p>\n\n\n\n
Snapshot 3<\/strong> – created immediately before the VM is shut down and containing the system’s final changes. Once the machine is powered off, the third differencing file is migrated, followed by a merge on both sides – Hyper-V and Proxmox. The machine is then started in the destination environment.<\/p>\n\n\n\n
This approach means that most of the data is transferred while the VM is running, with downtime limited to migrating and merging the third snapshot and restarting the system. At the same time, data integrity on the Hyper-V side is preserved, allowing for a quick rollback to the source environment if necessary.<\/p>\n\n\n\n
At the end of the process, the machine is assigned the imported<\/code> tag, clearly confirming that the migration completed successfully and preventing it from being selected again by the hv2pve<\/code> migrator.<\/p>\n\n\n\n
What are the benefits of using AVHDX Migrate Chain?<\/h2>\n\n\n\n
The biggest benefit of using AVHDX Migrate Chain (AMC) is a dramatic reduction in perceived downtime and better control over migration time.<\/p>\n\n\n\n
For example, the difference is clear when migrating a 100 GB virtual machine.<\/p>\n\n\n\n
Without AVHDX Migrate Chain<\/strong> – the entire process is performed in the traditional way, meaning that the VM must be shut down while the entire disk is copied and converted. As a result, the downtime spans practically the entire duration of the data transfer:<\/p>\n\n\n\n
\"\"\n\t\t\t\n\t\t\t\t\n\t\t\t<\/svg>\n\t\t<\/button>
Start: 2026-03-03 10:02:04 – End: 2026-03-03 10:23:06<\/figcaption><\/figure>\n\n\n\n
The migration takes from a few to several dozen minutes, and the downtime covers almost the entire period.<\/p>\n\n\n\n
With AVHDX Migrate Chain<\/strong> – most of the data (the base disk and the first two snapshots) is transferred while the machine is running. The VM is shut down only before the third, final snapshot is migrated. The synchronization of the final changes and starting the system in the Proxmox environment usually takes several dozen seconds, depending on the workload:<\/p>\n\n\n\n
\"\"\n\t\t\t\n\t\t\t\t\n\t\t\t<\/svg>\n\t\t<\/button>
Start: 2026-03-03 09:24:08 – End: 2026-03-03 09:55:55<\/figcaption><\/figure>\n\n\n\n
Although the total operation time may be similar or even longer, the key difference is that downtime is limited exclusively to the final synchronization phase.<\/p>\n\n\n\n
The Grafana charts clearly show the shorter service outage when using AVHDX Migrate Chain – the workload is spread over time, and end users experience only a short, controlled restart instead of a long service interruption.<\/p>\n\n\n\n
How we tested it<\/h2>\n\n\n\n
The testing process for the hv2pve<\/code> migrator was designed to verify not only the correctness of the operation itself, but above all the integrity of the data after migration.<\/p>\n\n\n\n
We implemented an additional module in the tool responsible for generating checksum files together with the checksum (sha1sum<\/code>) recorded in the registry. After the migration was completed, the calculated values were compared with the checksums of files already present in the destination location. This approach allowed us to unambiguously confirm that the data had been transferred completely and had not been corrupted during the transfer or the snapshot synchronization process.<\/p>\n\n\n\n
The entire testing process was fully automated using Jenkins. The pipelines ran various migration scenarios – both in standard mode and in AVHDX Migrate Chain (AMC) mode – allowing the tool to be tested repeatedly, consistently, and deterministically. This allowed us to verify both typical migration scenarios and edge cases in a controlled manner, ensuring that hv2pve<\/code> and hd2raw<\/code> operate correctly and safely.<\/p>\n\n\n\n
\"\"\n\t\t\t\n\t\t\t\t\n\t\t\t<\/svg>\n\t\t<\/button><\/figure>\n\n\n\n
What to do if the migration is interrupted<\/h2>\n\n\n\n
During the migration of a virtual machine to Proxmox VE, situations may occur in which the process does not complete successfully. These issues most commonly concern the state of the machine on the destination side and the snapshots created during the migration.<\/p>\n\n\n\n
If the migration is interrupted after all disks have been initialized, the machine on the Proxmox side will receive the init<\/code> status. This means that the VM structure was created correctly and all disks exist. In this situation, the migration can be safely retried.<\/p>\n\n\n\n
However, if the process ends before the disks are fully initialized, the migrator will not assign the init<\/code> tag and the machine will be marked as corrupted<\/code>. This status blocks another migration attempt. In practice, this means that the virtual machine and its disks must be manually removed from the Proxmox side, after which the migration needs to be started again from scratch.<\/p>\n\n\n\n
A separate case occurs when snapshots are created during migration and the process is interrupted after they have already been created. In such a scenario, the snapshots remain in the environment and prevent another migration attempt – the VM receives the snapshot<\/code> status. At the moment, removing or “cleaning up” these snapshots remains the user’s responsibility. Migration can only be restarted after the snapshots have been manually removed.<\/p>\n\n\n\n
Next steps<\/h2>\n\n\n\n
Development of the migrator is currently focused on improving its resilience to errors. The key goal is to reduce situations in which the administrator has to manually clean up the environment after an interrupted migration.<\/p>\n\n\n\n
We plan to improve exception handling and introduce mechanisms for automatically cleaning up snapshots on the Microsoft Hyper-V side – both during migration (if the state of the process allows it) and when restarting a migration. This will allow the source environment to remain in a consistent state even after an unsuccessful import attempt.<\/p>\n\n\n\n
At the same time, we are working on the ability to resume an import after an error without having to manually remove the machine on the Proxmox VE side. This will be complemented by automatic cleanup of the VM and storage resources after a failed import.<\/p>\n\n\n\n
The roadmap also includes:<\/p>\n\n\n\n