Hyper2KVM Frequently Asked Questions (FAQ)

Common questions and answers about using Hyper2KVM for VM migration.

General Questions

What is Hyper2KVM?

Hyper2KVM is an enterprise-grade VM migration toolkit that converts virtual machines from VMware, Hyper-V, AWS, Azure, and other hypervisors into production-ready KVM systems.

Key Features:

Automated Fixes: Bootloader, fstab, initramfs regeneration
VMCraft Engine: 480+ native Python APIs for VM manipulation
Multi-Format Support: VMDK, OVA, OVF, VHD, AMI, raw
Windows Support: VirtIO driver injection, registry modification
Batch Processing: Parallel multi-VM migrations
Enterprise Ready: Kubernetes operator, monitoring, HA

See: Main Documentation

What makes it different from other tools?

Unlike traditional migration tools that "boot and hope," Hyper2KVM applies deterministic offline fixes to ensure first-boot success:

Feature	virt-v2v	Other Tools	Hyper2KVM
Offline Fixes	Limited	None	Comprehensive
Windows VirtIO	Manual	Manual	Automatic
fstab Repair	Basic	None	Advanced
Initramfs Rebuild	No	No	Yes
XFS UUID Fix	No	No	Yes
Batch Migration	Limited	Limited	Full
Native Python	No (C)	Varies	Yes
Kubernetes	No	No	Yes

Key Differentiator: VMCraft - Native Python VM manipulation engine with 480+ APIs.

Is it production-ready?

Yes! Hyper2KVM v2.1.0+ is production-ready:

✅ Tested:

450+ automated tests
87.5% code coverage
500+ successful migrations

✅ Platforms:

OpenShift Container Platform 4.10-4.16
Kubernetes 1.24-1.33
RHEL/CentOS, Ubuntu, SUSE, Photon OS
Windows Server 2012-2025, Windows 10/11

✅ Enterprise Features:

High availability
Monitoring (Prometheus/Grafana)
Security (SCCs, RBAC)
Audit logging

See: Test Results

Supported Platforms

Source Hypervisors:

✅ VMware ESXi 6.5-8.0
✅ VMware Workstation/Fusion
✅ Hyper-V (2012-2022)
✅ AWS EC2
✅ Azure VMs
✅ Google Cloud
✅ KVM (P2V-like scenarios)

Guest Operating Systems:

✅ Windows 7-11, Server 2008-2025
✅ RHEL/CentOS 7-10
✅ Ubuntu 18.04-24.04
✅ Debian 10-12
✅ SUSE/openSUSE 15+
✅ Oracle Linux
✅ Photon OS 3.0-5.0
✅ Rocky Linux, AlmaLinux

Output Formats:

✅ qcow2 (recommended)
✅ raw
✅ VDI (VirtualBox)

See: OS Support

VM Downtime

Short Answer: Depends on method

Methods:

Standard Migration (Recommended)
- Downtime: Full downtime during migration
- Duration: 10-30 minutes depending on size
- Best for: Most migrations
Live Fix (Advanced)
- Downtime: <5 seconds for final switchover
- Duration: Preparation + quick switchover
- Best for: Production systems
- See: Live Fix Guide
Batch Migration
- Downtime: Per VM (can stagger)
- Duration: Parallel processing
- Best for: Multiple VMs

See: Migration Playbooks

Installation & Setup

Installation

Quick Install:

# Full installation (recommended)
pip install "hyper2kvm[full]"

# Minimal installation
pip install hyper2kvm

# From source
git clone https://github.com/ssahani/hyper2kvm.git
cd hyper2kvm
pip install -e ".[full]"

Verification:

h2kvmctl --version
hyper2kvm --version

See: Installation Guide

System Requirements

Minimum:

Python 3.10+
4 GB RAM
2 CPU cores
2x VM size disk space
Linux OS

Recommended:

Python 3.11+
8+ GB RAM
4+ CPU cores
3x VM size disk space
RHEL 9 / Ubuntu 22.04+

See: System Requirements

Root Access

Yes, most operations require root/sudo.

Why:

Mount filesystems
Modify disk images
Access guest filesystems
Install bootloaders
Modify system files

Usage:

# Run with sudo
sudo h2kvmctl --config migration.yaml

# Or use sudo -i
sudo -i
h2kvmctl --config migration.yaml

Security: See Security Best Practices

Container Deployment

Yes! Multiple options:

Docker/Podman

podman run -d -v /data:/data \
  ghcr.io/ssahani/hyper2kvm:2.1.0-worker

Kubernetes

helm install hyper2kvm-operator ./helm/hyper2kvm-operator

OpenShift
```
# Via OperatorHub or Helm
```

See: Container Deployment Guide

Migration Questions

Migration Time

Typical Times:

VM Size	OS Type	Time
<20 GB	Linux	3-5 min
<20 GB	Windows	5-8 min
20-50 GB	Linux	8-15 min
20-50 GB	Windows	12-20 min
>50 GB	Linux	20-40 min
>50 GB	Windows	30-60 min

Factors:

Disk size
Compression level
Network speed (remote fetch)
Fixes enabled
System performance

See: Performance Metrics

Windows Support

Yes! Full Windows support including:

✅ VirtIO Driver Injection

Automatic driver installation
Registry modification
Network adapter configuration

✅ Supported Versions:

Windows 7-11
Windows Server 2008 R2 - 2025

✅ Features:

Boot sector fixes
Driver injection
Registry updates
Network configuration

Example:

command: local
vmdk: /vmware/windows-server-2019.vmdk
output_dir: /kvm/vms
to_output: windows-server.qcow2

# Windows-specific
windows_drivers: true

See: Windows Migration Guide

Multi-Disk VMs

Yes, but requires multiple migrations:

# Disk 1 (boot disk with fixes)
sudo hyper2kvm --config << EOF
command: local
vmdk: /vmware/vm-disk1.vmdk
output_dir: /kvm/vms
to_output: vm-disk1.qcow2
fstab_mode: stabilize-all
regen_initramfs: true
update_grub: true
EOF

# Disk 2 (data disk, no fixes needed)
sudo hyper2kvm --config << EOF
command: local
vmdk: /vmware/vm-disk2.vmdk
output_dir: /kvm/vms
to_output: vm-disk2.qcow2
compress: true
EOF

Then update libvirt XML to include both disks.

See: Recipe #10

Live Migration

Yes, using live-fix method:

command: live-fix
host: esxi-host.example.com
user: root
identity: ~/.ssh/id_rsa

# Fixes
fstab_mode: stabilize-all
regen_initramfs: true
update_grub: true

Process:

Connect to running VM via SSH
Apply fixes while running
Quick switchover (<5s downtime)

See: Migration Playbooks

Batch Migration

Yes! Multiple methods:

Method 1: JSON Manifest

command: local
batch_manifest: migrations.json
batch_parallel: 3
output_dir: /kvm/batch

{
  "migrations": [
    {"vmdk": "/vmware/vm1.vmdk", "to_output": "vm1.qcow2"},
    {"vmdk": "/vmware/vm2.vmdk", "to_output": "vm2.qcow2"},
    {"vmdk": "/vmware/vm3.vmdk", "to_output": "vm3.qcow2"}
  ]
}

Method 2: Kubernetes Operator

Submit multiple MigrationJob CRDs.

See: Batch Migration Guide

Technical Questions

Supported Formats

Input Formats:

✅ VMDK (all types: monolithic, split, sparse, streamOptimized)
✅ OVA (VMware export archive)
✅ OVF (VMware export descriptor)
✅ VHD/VHDX (Hyper-V)
✅ AMI (AWS EC2 tarball)
✅ raw disk images
✅ Azure VHD

Output Formats:

✅ qcow2 (recommended)
✅ raw
✅ VDI (VirtualBox)

See: CLI Reference

Encrypted Disks

Partial Support:

BitLocker (Windows):

❌ Cannot migrate while encrypted
✅ Decrypt before migration
✅ Re-encrypt after migration

LUKS (Linux):

❌ Cannot modify while encrypted
✅ Decrypt before migration
✅ Re-encrypt after migration

Workaround:

# 1. Decrypt on source
# Windows: Disable BitLocker
# Linux: cryptsetup luksClose

# 2. Migrate
sudo hyper2kvm --config migration.yaml

# 3. Re-encrypt on target
# Windows: Enable BitLocker
# Linux: cryptsetup luksFormat

See: Security Best Practices

Snapshots

VMware Snapshots:

❌ Not supported (linked clones)
✅ Consolidate snapshots first
✅ Export as standalone VM

Process:

# In VMware
1. Right-click VM → Snapshots → Consolidate
2. Wait for consolidation
3. Export VM or migrate VMDK

See: VMDK Inspector

Thin Provisioning

Yes, supported:

Source:

✅ Thin-provisioned VMDKs
✅ Thick-provisioned VMDKs

Output:

✅ Sparse qcow2 (default, space-efficient)
✅ Preallocated qcow2 (for performance)
✅ raw (full size)

Example:

# Sparse output (saves space)
compress: true
keep_sparse: true

# Preallocated output (better performance)
preallocate: true
compress: false

Troubleshooting

Boot Failure

Problem: VM doesn't boot after migration

Common Causes:

Missing virtio drivers in initramfs
Wrong fstab entries
GRUB configuration issues
Wrong disk controller

Solution:

command: offline-fix
qcow2: /kvm/vms/failed-boot.qcow2

# Comprehensive fixes
fstab_mode: stabilize-all
regen_initramfs: true
initramfs_add_drivers:
  - virtio
  - virtio_blk
  - virtio_scsi
  - virtio_net
update_grub: true

See: Troubleshooting Guide

Network Failure

Problem: No network connectivity after migration

Common Causes:

Missing virtio_net driver
MAC address change
Network interface name change
NetworkManager issues

Solution:

command: offline-fix
qcow2: /kvm/vms/no-network.qcow2

# Network fixes
regen_initramfs: true
initramfs_add_drivers:
  - virtio_net
  - e1000
fstab_mode: stabilize-all

Manual Fix:

# Inside VM after boot
ip link  # Check interface name
nmcli device  # Check NetworkManager

See: Troubleshooting Guide

Migration Errors

Problem: Migration fails with error

Common Errors:

Permission Denied

# Solution: Run with sudo
sudo hyper2kvm --config migration.yaml

Disk Space

# Check available space (need 3x VM size)
df -h /output/directory

Missing Dependencies

# Install required tools
sudo dnf install -y qemu-img qemu-system-x86  # RHEL/Fedora
sudo apt-get install -y qemu-utils  # Ubuntu

Corrupt VMDK

# Validate VMDK first
./scripts/vmdk_inspect.py /path/to/vm.vmdk

See: Troubleshooting Guide

Rollback

If migration fails or VM doesn't work:

Option 1: Keep Original

Original VM is never modified
Simply don't delete source
Start original VM if needed

Option 2: Use Snapshots

# Before migration
qemu-img snapshot -c before_migration vm.qcow2

# Rollback if needed
qemu-img snapshot -a before_migration vm.qcow2

Option 3: Backup

# Before migration
cp /vmware/original.vmdk /backup/original.vmdk.backup

See: Migration Playbooks

Additional Resources

Documentation

Main Documentation Hub - Complete documentation
Getting Started - Installation and setup
Tutorials - Step-by-step learning
Recipes - Quick solutions
Troubleshooting - Fix common issues

Support

GitHub Issues: Report bugs
GitHub Discussions: Ask questions

Examples

Migration Recipes - Real-world examples
Config Examples - Sample configurations

Can't find your question? Ask on GitHub Discussions

Last Updated: February 2026
Total Questions: 25+
Coverage: Installation, Migration, Troubleshooting, Technical

FilesExpand file tree

FAQ.md

Latest commit

History

FAQ.md

File metadata and controls

Hyper2KVM Frequently Asked Questions (FAQ)

Table of Contents

General Questions

Installation & Setup

Migration Questions

Technical Questions

Troubleshooting

General Questions

What is Hyper2KVM?

What makes it different from other tools?

Is it production-ready?

Supported Platforms

VM Downtime

Installation & Setup

Installation

System Requirements

Root Access

Container Deployment

Migration Questions

Migration Time

Windows Support

Multi-Disk VMs

Live Migration

Batch Migration

Technical Questions

Supported Formats

Encrypted Disks

Snapshots

Thin Provisioning

Troubleshooting

Boot Failure

Network Failure

Migration Errors

Rollback

Additional Resources

Documentation

Support

Examples