hyper2kvm 0.2.0

Production-Grade Hypervisor to KVM/QEMU Migration Toolkit

hyper2kvm 🚀

Production-Grade Hypervisor to KVM/QEMU Migration Toolkit ⚡

hyper2kvm is a comprehensive toolkit for migrating virtual machines from multiple hypervisors and disk ecosystems (VMware, Hyper-V, cloud images, raw artifacts, physical exports) into reliable, bootable KVM/QEMU systems.

Key Differentiator: Unlike traditional migration tools that rely on "boot and hope," hyper2kvm applies deterministic offline fixes to ensure first-boot success through deep inspection, bootloader repair, driver injection, and network stabilization.

🎩 Built for the Enterprise Linux Ecosystem

hyper2kvm is designed with Fedora and Red Hat Enterprise Linux (RHEL) as first-class platforms, leveraging the powerful open-source virtualization stack that powers cloud infrastructure worldwide.

Why Fedora/RHEL? 🚀

• Native KVM Integration: Red Hat invented and maintains KVM - the Linux kernel virtualization module that powers AWS, Google Cloud, and OpenStack
• libguestfs Excellence: Deep integration with libguestfs (also Red Hat-originated) for safe, offline VM manipulation
• SELinux Security: First-class support for SELinux-enabled migrations - critical for enterprise deployments
• Dracut Framework: Advanced initramfs handling for RHEL/Fedora/CentOS systems
• Enterprise DNA: Built on the same stack that powers mission-critical workloads globally

Perfect Fit for:

• 🏢 RHEL 9/10 infrastructure migrations
• 🔄 VMware to OpenStack transitions (RH OpenStack, RDO)
• ☁️ Hybrid cloud deployments (AWS ← → On-Premises RHEL)
• 🐧 Fedora workstation/server consolidation
• 🎯 CentOS Stream development environments

Whether you're running Fedora 43, RHEL 10, CentOS Stream, or Rocky Linux, hyper2kvm speaks your language natively - from NetworkManager to systemd-networkd, from dracut to grub2-mkconfig.

---

Quick Start 🎯

Installation

From PyPI (Recommended)

# Install system dependencies (Fedora/RHEL)
sudo dnf install -y python3-libguestfs libguestfs-tools qemu-img qemu-system-x86

# Minimal installation (works on RHEL 10 without additional repos)
pip install hyper2kvm

# Or with UI enhancements (recommended, requires rich library)
pip install hyper2kvm[ui]

# With vSphere support
pip install hyper2kvm[vsphere]

# Full installation with all features
pip install hyper2kvm[full]

Note for RHEL 10: The Rich library for progress bars is not available in RHEL 10 base repositories. hyper2kvm works perfectly without it, falling back to simple progress logging. See Optional Dependencies for details.

From Source

# Install system dependencies (Fedora/RHEL)
sudo dnf install -y python3-libguestfs libguestfs-tools qemu-img qemu-system-x86

# Clone and install
git clone https://github.com/ssahani/hyper2kvm.git
cd hyper2kvm
pip install -e .

Package Locations

• PyPI: https://pypi.org/project/hyper2kvm/ (v0.1.0+)
• GitHub: https://github.com/hyper2kvm/hyper2kvm (primary development)
• GitLab: https://gitlab.com/hyper2kvm/hyper2kvm (auto-synced mirror)
• Documentation: docs/
• Examples: examples/

See docs/INSTALL.md for Ubuntu/Debian, Arch, Alpine, macOS, and Windows (WSL).

Shell Completion (Optional)

Enable intelligent tab completion for bash, zsh, or fish shells:

# Install argcomplete
pip install argcomplete

# Install completion for your shell (interactive)
./completions/install-completions.sh

# Or install for a specific shell
./completions/install-completions.sh bash
./completions/install-completions.sh zsh
./completions/install-completions.sh fish

After installation, you can use tab completion:

hyper2kvm --<TAB>              # Shows all available options
hyper2kvm --vm<TAB>            # Completes to --vmdk, --vm-name, etc.
hyper2kvm --vmdk /path/<TAB>   # Path completion

See completions/README.md for detailed installation instructions and troubleshooting.

Basic Usage

# Convert local VMDK to qcow2 with automatic fixes
sudo python -m hyper2kvm local \
  --vmdk /path/to/disk.vmdk \
  --to-output /output/disk.qcow2 \
  --flatten --compress

# Migrate from vSphere with full inspection and fixes
# (powered by hypersdk for enterprise-grade VMware API integration)
sudo python -m hyper2kvm vsphere \
  --vcenter vcenter.example.com \
  --username [e-mail] \
  --vm-name "Production-VM" \
  --vs-action export \
  --to-output /output/

# Live fix a running Linux VM via SSH
sudo python -m hyper2kvm live-fix \
  --host 192.168.1.100 \
  --user root \
  --fix-fstab --fix-grub --fix-network

For more examples, see docs/QUICKSTART.md and examples/README.md.

High-Performance vSphere Exports (Optional) ⚡

For 3-5x faster VM exports from vSphere/ESXi, install the optional hypersdk daemon:

# Install hypersdk (Fedora/RHEL)
sudo dnf install hypersdk
sudo systemctl start hypervisord
sudo systemctl enable hypervisord

# Or from source
git clone https://github.com/ssahani/hypersdk
cd hypersdk
go build -o hypervisord ./cmd/hypervisord
sudo ./install.sh

Once installed, hyper2kvm automatically detects and uses hyperctl for exports:

from hyper2kvm.vmware.transports import HYPERCTL_AVAILABLE, export_vm_hyperctl

if HYPERCTL_AVAILABLE:
    # Use high-performance daemon (parallel downloads, resume support)
    result = export_vm_hyperctl(
        vm_path="/datacenter/vm/my-vm",
        output_path="/output/",
        parallel_downloads=8,  # Concurrent downloads
    )

Benefits:

• ⚡ 3-5x faster exports via parallel downloads
• 🔄 Resumable downloads with automatic retry
• 📊 Real-time progress tracking
• 🚀 Background daemon mode for automation
• 📦 Batch processing for multiple VMs

See docs/HYPERCTL_INTEGRATION.md and INTEGRATION_SUMMARY.md for details.

---

Features ✨

Core Capabilities 💪

• Multi-Hypervisor Support: VMware (vSphere, ESXi, Workstation), Hyper-V, AWS AMI, cloud images, raw disks 🔄
• Offline Fixing: Deterministic repairs using libguestfs without booting the VM 🛠️
• Windows VirtIO Injection: Automated driver injection with two-phase boot strategy 🪟
• Linux Bootloader Repair: GRUB/GRUB2 regeneration for BIOS and UEFI systems with enhanced chroot (bind-mounted /proc, /dev, /sys for reliable bootloader operations) 🐧
• Network Stabilization: Remove MAC pinning, clean VMware artifacts, support multiple network managers 🌐
• Snapshot Handling: Intelligent flattening of VMware snapshot chains 📸
• Format Conversion: VMDK, VHD/VHDX, QCOW2, RAW, VDI with compression support 💾
• Validation: Boot smoke tests via libvirt or direct QEMU ✅

VMCraft - Advanced VM Manipulation Platform 🚀

VMCraft v9.1 is hyper2kvm's modular disk image manipulation library - a pure Python platform for comprehensive VM analysis and automation.

• 343+ Methods across 58 specialized modules (26,500+ lines of code)
• Lightning-Fast Performance: Native Python with ~1.9s launch, 2-3x faster parallel mounts, 30-40% fewer system calls
• Enterprise Intelligence:
  • 🤖 AI/ML Analytics: Anomaly detection, behavior prediction, workload classification
  • ☁️ Cloud Optimization: Multi-cloud migration planning (AWS, Azure, GCP), cost analysis
  • 🛡️ Disaster Recovery: RTO/RPO planning, backup strategies, failover procedures
  • 📋 Audit Trail: Multi-standard compliance (SOC2, PCI-DSS, HIPAA, GDPR)
  • ⚙️ Resource Orchestration: Auto-scaling, workload balancing, maintenance scheduling
• Cross-Platform Support:
  • 🐧 Linux: 15+ distributions, package management, service control, driver analysis
  • 🪟 Windows: 20+ versions, registry operations, driver injection, user management
• Modern Architecture: Modular design with NBD, LVM, LUKS, RAID, ZFS support

See: VMCraft Documentation | VMCraft v9.0 Summary

Production-Ready Features 🏭

• YAML Configuration: Version-controlled, mergeable configuration files 📝
• Batch Processing: Parallel multi-VM migrations ⚙️
• Resume Support: Crash recovery with checkpointing 🔄
• Dry-Run Mode: Preview changes without applying them 👀
• Detailed Reporting: Comprehensive migration reports and logs 📊
• vSphere Integration: Native API support via govc, pyvmomi, and hyperctl (high-performance provider) ☁️

Batch Migration Features 🚚

Enterprise-grade batch migration capabilities for large-scale VM conversions:

• Batch Orchestration: Multi-VM parallel conversions with configurable worker limits 🔄
• Migration Profiles: 7 built-in profiles (production, testing, minimal, fast, windows, archive, debug) + custom profile support with inheritance 📋
• Pre/Post Hooks: Execute custom scripts, Python functions, or HTTP webhooks at 7 pipeline stages ⚡
  • Hook stages: pre_extraction, post_extraction, pre_fix, post_fix, pre_convert, post_convert, post_validate
  • Retry logic with exponential backoff
  • Template variable substitution (15+ variables)
• Libvirt XML Import: Parse and convert existing libvirt VMs with automatic domain creation 🔄
• Network & Storage Mapping: Transform source networks/storage to target infrastructure 🗺️
  • Source network to target bridge mapping
  • MAC address policies (preserve/regenerate/custom)
  • Per-disk storage pool mappings
• Direct Libvirt Integration: Automatic domain definition, disk import to storage pools, snapshot creation 🔗
• Checkpoint/Resume: Crash-safe batch conversions with atomic checkpoint saves 💾
• Progress Tracking: Real-time progress persistence to JSON for external monitoring 📊
• Validation Framework: Extensible validation with 4 severity levels (INFO, WARNING, ERROR, CRITICAL) ✅
• Profile Caching: Performance optimization with mtime-based invalidation 🚀

See: Batch Migration Guide | Quick Reference

Safety Mechanisms 🔒

• Automatic backups (unless explicitly disabled) 💾
• Atomic file operations ⚛️
• Validation at every pipeline stage ✓
• Rollback capability for critical operations 🔙
• Security scanning (Bandit, pip-audit) via GitHub Actions 🛡️

---

Documentation 📚

Getting Started 🚀

• Quick Start Guide - Get migrating in 5 minutes ⚡
• Installation Guide - Comprehensive installation for all platforms 🔧
• CLI Reference - Complete command-line documentation 📖
• YAML Examples - Configuration file templates 📝

Deep Dive 🔬

• Architecture - System design and internal structure 🏗️
• Cookbook - Common migration scenarios and solutions 👨‍🍳
• Failure Modes - Troubleshooting guide 🔧

Platform-Specific 🖥️

• Windows Migrations - Windows-specific guide and VirtIO driver injection 🪟
• PhotonOS - VMware PhotonOS specific notes 🐧
• RHEL 10 - RHEL 10 migration guide 🎩

Examples 💡

• Example Configurations - 40+ working examples 📦

---

Table of Contents

1. Scope and Non-Goals
2. Design Principles
3. Codebase Architecture
4. VMCraft - libguestfs Replacement
5. Supported Inputs and Execution Modes
6. Pipeline Model
7. Control-Plane vs Data-Plane
8. Linux Fixes
9. Windows Handling
10. Snapshots and Flattening
11. Output Formats and Validation
12. YAML Configuration Model
13. Multi-VM and Batch Processing
14. Live-Fix Mode (SSH)
15. ESXi and vSphere Integration
16. Safety Mechanisms
17. Daemon Mode and Automation
18. Testing and Verification
19. Failure Modes and Troubleshooting
20. When Not to Use This Tool
21. Documentation Index and References

---

1. Scope and Non-Goals

What This Tool Does

• Converts hypervisor disks into KVM-usable formats
• Repairs Linux and Windows guests offline
• Applies selected Linux fixes live over SSH
• Stabilizes storage and network identifiers across hypervisors
• Injects Windows VirtIO drivers safely (storage first, always)
• Uses a two-phase Windows boot strategy (SATA bootstrap → VirtIO final) to guarantee driver activation
• Flattens snapshot chains deterministically
• Enables repeatable, automatable migrations via mergeable YAML
• Validates results using libvirt / QEMU smoke tests

While VMware remains the deepest and most battle-tested integration,
hyper2kvm is intentionally disk-centric, not platform-centric.

If it can be reduced to disks + metadata, it can enter the pipeline.

---

2. Installation 🔧

Quick Install ⚡

# 1. Install system dependencies (Fedora/RHEL/CentOS)
sudo dnf install -y python3-libguestfs libguestfs-tools qemu-img

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Install hyper2kvm
pip install -e .

Important: libguestfs and hivex are system packages, NOT pip packages. They must be installed via your OS package manager (dnf, apt, zypper).

See docs/INSTALL.md for detailed installation instructions for all Linux distributions, macOS, and Windows (WSL).

---

3. Design Principles

hyper2kvm is built around a small set of non-negotiable principles:

• Determinism over luck
  Every action should be repeatable, inspectable, and explainable.
  If a migration “just happens to boot,” something is missing.

• Disk-centric, not platform-centric
  Hypervisors are treated as sources of disks and metadata, not as sacred systems.

• Control-plane separated from data-plane
  Decisions are made before bytes move.
  Byte movers never guess.

• Offline-first repairs
  Guests should boot correctly on first power-on in KVM, without emergency console work.

• Explicit plans over implicit behavior
  Snapshot flattening, driver injection, and boot strategy are always planned, never inferred mid-flight.

• Safety by default
  Backups, atomic writes, and reversible changes are standard—not optional.

These principles are enforced structurally, not by convention.

---

3. Codebase Architecture

hyper2kvm is organized into 14 logical packages with clear separation of concerns, making it easy to navigate, extend, and maintain.

Package Structure

hyper2kvm/
├── cli/
│   └── args/              # CLI argument parsing (6 modules)
│       ├── builder.py     # HelpFormatter + epilog builder
│       ├── groups.py      # 21 argument group builders
│       ├── validators.py  # 18 validation functions
│       ├── helpers.py     # Helper functions (_merged_*, _require, etc.)
│       ├── parser.py      # Main parser orchestration
│       └── __init__.py    # Package exports
│
├── config/                # YAML configuration loading and merging
│
├── converters/            # Format conversion
│   ├── extractors/        # Disk format extractors (4 modules)
│   │   ├── ami.py         # AWS AMI extraction (1,019 lines)
│   │   ├── ovf.py         # OVF/OVA handling (567 lines)
│   │   ├── raw.py         # RAW disk processing (646 lines)
│   │   └── vhd.py         # VHD/VHDX handling (669 lines)
│   └── qemu/              # QEMU conversion (1 module)
│       └── converter.py   # qemu-img wrapper (879 lines)
│
├── core/                  # Core utilities and logging
│
├── fixers/                # Guest OS repair modules
│   ├── bootloader/        # Bootloader fixes (2 modules)
│   │   ├── fixer.py       # Generic bootloader fixer (641 lines)
│   │   └── grub.py        # GRUB-specific fixes (1,102 lines)
│   ├── filesystem/        # Filesystem fixes (2 modules)
│   │   ├── fixer.py       # Filesystem repair (923 lines)
│   │   └── fstab.py       # /etc/fstab rewriting (178 lines)
│   ├── live/              # Live migration (SSH) (2 modules)
│   │   ├── mode.py        # Live-fix orchestrator
│   │   └── ssh_client.py  # SSH connection handling
│   ├── network/           # Network configuration fixes (6 modules)
│   │   ├── model.py       # Data models and enums (434 lines)
│   │   ├── discovery.py   # Config file discovery (362 lines)
│   │   ├── topology.py    # Topology graph building (417 lines)
│   │   ├── validation.py  # Post-fix validation (131 lines)
│   │   ├── backend.py     # Backend-specific fixers (859 lines)
│   │   └── core.py        # Main orchestrator (418 lines)
│   ├── offline/           # Offline helper utilities (5 modules)
│   │   ├── mount.py       # Disk mounting (566 lines)
│   │   ├── vmware_tools_remover.py  # VMware Tools cleanup (454 lines)
│   │   ├── fstab_crypttab_rewriter.py
│   │   ├── spec_converter.py
│   │   └── validation_manager.py
│   └── windows/           # Windows fixes (3-tier structure, 18 modules)
│       ├── registry/      # Registry manipulation (6 modules)
│       │   ├── base.py    # Base registry operations
│       │   ├── driver.py  # Driver registry edits
│       │   ├── bcd.py     # BCD handling
│       │   └── ...
│       └── virtio/        # VirtIO driver injection (7 modules)
│           ├── injector.py  # Driver injection orchestrator
│           ├── scanner.py   # Driver file discovery
│           └── ...
│
├── modes/                 # Operational modes
│   ├── inventory_mode.py  # VM inventory scanning (318 lines)
│   └── plan_mode.py       # Migration planning (161 lines)
│
├── orchestrator/          # Pipeline orchestration
│   ├── orchestrator.py    # Main pipeline coordinator (358 lines)
│   ├── disk_processor.py  # Disk processing (335 lines)
│   ├── vsphere_exporter.py # vSphere export (264 lines)
│   └── disk_discovery.py  # Disk discovery (247 lines)
│
└── vmware/                # VMware integration
    ├── clients/           # VMware API clients (3 modules)
    │   ├── client.py      # VMwareClient (vSphere API)
    │   ├── vddk_client.py # VDDK client (1,245 lines)
    │   └── govc_client.py # govc wrapper
    ├── transports/        # Download/export methods (8 modules)
    │   ├── http_client.py # HTTPS download with progress
    │   ├── ssh_client.py  # SSH/SCP fallback
    │   ├── ovftool_client.py  # ovftool wrapper
    │   ├── session_cookie.py  # vSphere session management
    │   └── ...
    ├── vsphere/           # vSphere-specific implementations (4 modules)
    │   ├── mode.py        # Main vSphere orchestrator (1,470 lines)
    │   ├── command.py     # vSphere CLI commands
    │   └── ...
    └── utils/             # VMware utilities (4 modules)
        ├── vmdk_parser.py # VMDK descriptor parsing
        ├── vmx_parser.py  # VMX file parsing
        └── ...

Package Descriptions

cli/args/

Purpose: CLI argument parsing split into focused modules

• builder.py - Custom HelpFormatter and epilog generation
• groups.py - 21 functions adding argument groups (vsphere, OVF, AMI, etc.)
• validators.py - 18 validation functions for command-line arguments
• helpers.py - Utility functions for config merging and resolution
• parser.py - Main build_parser() and parse_args_with_config() orchestration

Key Pattern: Backward compatibility maintained via __init__.py re-exports

converters/

Purpose: Disk format conversion and extraction

extractors/ - Format-specific extraction logic:

• ami.py - AWS AMI extraction with partition handling
• ovf.py - OVF/OVA parsing and disk extraction
• raw.py - RAW disk format processing
• vhd.py - VHD/VHDX extraction (Hyper-V disks)

qemu/ - QEMU-based conversion:

• converter.py - qemu-img wrapper for format conversion (vmdk → qcow2, etc.)

fixers/

Purpose: Guest OS repair modules (Linux and Windows)

bootloader/ - Bootloader repair:

• fixer.py - Generic bootloader detection and fixing
• grub.py - GRUB-specific fixes (BIOS and UEFI)

filesystem/ - Filesystem repairs:

• fixer.py - Filesystem check and repair (fsck, etc.)
• fstab.py - /etc/fstab rewriting with UUID stabilization

network/ - Network configuration fixes (7 backends supported):

• model.py - Data models (NetworkConfig, FixLevel, enums)
• discovery.py - Config file discovery across distros
• topology.py - Dependency graph building for interface renames
• validation.py - Post-fix validation
• backend.py - Backend-specific fixers (netplan, systemd-networkd, ifcfg-rh, etc.)
• core.py - Main NetworkFixer orchestrator

offline/ - Offline repair utilities:

• mount.py - Disk mounting and inspection via libguestfs
• vmware_tools_remover.py - VMware Tools cleanup
• fstab_crypttab_rewriter.py - fstab/crypttab rewriting
• spec_converter.py - Device specifier conversion (LABEL → UUID)
• validation_manager.py - Validation orchestration

windows/ - Windows-specific fixes (3-tier structure):

• registry/ - Windows registry manipulation (6 modules)
  • base.py - Base registry operations
  • driver.py - Driver registry edits
  • bcd.py - BCD (Boot Configuration Database) handling
• virtio/ - VirtIO driver injection (7 modules)
  • injector.py - Main driver injection orchestrator
  • scanner.py - Driver file discovery and validation

live/ - Live migration over SSH:

• mode.py - Live-fix orchestrator (apply fixes to running VMs)
• ssh_client.py - SSH connection and command execution

modes/

Purpose: Operational modes (inventory, planning)

• inventory_mode.py - VM inventory scanning and risk assessment (318 lines)
• plan_mode.py - Migration planning and preview (161 lines)

Note: Both files are small, focused, and require no further refactoring.

orchestrator/

Purpose: Pipeline orchestration (FETCH → FLATTEN → FIX → CONVERT → VALIDATE)

• orchestrator.py - Main pipeline coordinator (358 lines)
• disk_processor.py - Disk processing logic (335 lines)
• vsphere_exporter.py - vSphere export coordination (264 lines)
• disk_discovery.py - Disk discovery and metadata extraction (247 lines)

vmware/

Purpose: VMware integration (vSphere, ESXi, govc, VDDK)

clients/ - VMware API clients:

• client.py - Main VMwareClient (pyvmomi/pyVim wrapper)
• vddk_client.py - VDDK (VMware Virtual Disk Development Kit) client
• govc_client.py - govc CLI wrapper

transports/ - Data-plane download/export methods:

• http_client.py - HTTPS download with progress and resume support
• hyperctl_common.py - hyperctl CLI wrapper (hypersdk daemon, 3-5x faster than govc)
• ssh_client.py - SSH/SCP fallback transport
• ovftool_client.py - ovftool wrapper for OVF/OVA export
• session_cookie.py - vSphere session cookie management
• vddk_transport.py - VDDK-based disk export

vsphere/ - vSphere-specific orchestration:

• mode.py - Main vSphere mode orchestrator (1,470 lines)
• command.py - vSphere CLI command implementations

utils/ - VMware utilities:

• vmdk_parser.py - VMDK descriptor parsing
• vmx_parser.py - VMX configuration file parsing

Import Patterns

Package-Level Imports (Recommended)

# Network fixer
from hyper2kvm.fixers.network import NetworkFixer

# Converters
from hyper2kvm.converters.extractors import AMI, OVF, RAW, VHD
from hyper2kvm.converters.qemu import Convert

# VMware clients
from hyper2kvm.vmware.clients import VMwareClient
from hyper2kvm.vmware.transports import HTTPDownloadClient

# CLI args
from hyper2kvm.cli.args import build_parser, validate_args

Backward Compatibility (Still Works)

# Old-style imports still work via wrapper modules
from hyper2kvm.fixers.network_fixer import NetworkFixer
from hyper2kvm.vmware.vmware_client import VMwareClient
from hyper2kvm.cli.argument_parser import build_parser

All modules maintain backward compatibility via wrapper files in original locations.

---

4. VMCraft - Advanced VM Manipulation Platform

Overview

VMCraft v9.1 is hyper2kvm's pure Python disk image manipulation library designed for production-grade VM analysis and automation. With 343+ methods across 58 specialized modules and 26,500+ lines of code, VMCraft provides comprehensive VM inspection, modification, and intelligence capabilities with enterprise-grade performance optimizations.

Performance Characteristics

VMCraft delivers exceptional performance through native Python implementation:

Operation	Time	Notes
Launch	~1.9s	NBD connection + storage activation
NBD Connection	~1.4s	Attach disk via qemu-nbd
OS Inspection	~0.3s	Detect OS type, version, distribution
File Operations	<100ms	Read/write files, directory operations
Registry Operations	~200ms	Windows registry read/write

Architecture

VMCraft uses a modular architecture with specialized components:

hyper2kvm/core/vmcraft/
├── Core Infrastructure
│   ├── main.py                    # VMCraft orchestrator
│   ├── nbd.py                     # NBD device management
│   ├── storage.py                 # LVM, LUKS, RAID, ZFS activation
│   ├── mount.py                   # Filesystem mounting
│   └── file_ops.py                # File operations (70+ methods)
│
├── OS Detection
│   ├── inspection.py              # OS inspection orchestration
│   ├── linux_detection.py         # Linux distro detection
│   └── windows_detection.py       # Windows version detection
│
├── Windows Support
│   ├── windows_registry.py        # Registry operations
│   ├── windows_drivers.py         # Driver injection
│   ├── windows_users.py           # User management
│   ├── windows_services.py        # Service control
│   └── windows_applications.py    # App detection
│
├── Linux Support
│   ├── linux_services.py          # Systemd/init service control
│   └── [Package managers, SELinux, etc.]
│
├── Enterprise Features (v9.0)
│   ├── ml_analyzer.py             # AI/ML analytics (7 methods)
│   ├── cloud_optimizer.py         # Cloud migration (6 methods)
│   ├── disaster_recovery.py       # DR planning (6 methods)
│   ├── audit_trail.py             # Compliance logging (7 methods)
│   └── resource_orchestrator.py   # Auto-scaling (7 methods)
│
└── Operational Tools
    ├── backup.py                  # Backup and restore
    ├── security.py                # Security auditing
    ├── optimization.py            # Disk optimization
    ├── advanced_analysis.py       # Forensic analysis
    └── export.py                  # VM export

Key Capabilities

Cross-Platform OS Support

Linux Detection (15+ distributions):

• Red Hat family: RHEL, Fedora, CentOS, Rocky, AlmaLinux, Oracle Linux
• SUSE family: SLES, openSUSE (Leap, Tumbleweed)
• Debian family: Debian, Ubuntu
• Others: Arch, Gentoo, Alpine, Slackware, Photon OS

Windows Detection (20+ versions):

• Client: Windows 12, 11, 10, 8.1, 8, 7, Vista, XP, 2000, NT
• Server: Server 2025, 2022, 2019, 2016, 2012 R2, 2012, 2008 R2, 2008, 2003

AI/ML Analytics (v9.0)

• Anomaly Detection: Statistical anomaly detection using z-scores
• Behavior Prediction: Predictive modeling with linear regression
• Workload Classification: AI-powered workload categorization
• Baseline Training: Train from normal operations
• Optimization Recommendations: AI-powered tuning suggestions

Cloud Optimization (v9.0)

• Multi-Cloud Support: AWS, Azure, GCP instance recommendations
• Readiness Assessment: Cloud migration scoring
• Cost Calculation: TCO analysis and optimization
• Migration Planning: 5-phase migration workflows
• Cloud-Native Optimization: Platform-specific tuning

Disaster Recovery (v9.0)

• RTO/RPO Planning: Calculate achievable recovery targets
• 4-Tier Classification: Tier 0-3 recovery requirements
• Backup Strategies: Automated backup planning
• Failover Procedures: Documented runbooks
• DR Testing: Simulation and validation

Compliance & Audit (v9.0)

• Event Logging: Comprehensive audit trail with SHA256 checksums
• Multi-Standard Compliance: SOC2, PCI-DSS, HIPAA, GDPR
• Change Tracking: Configuration version control
• Integrity Verification: Tamper detection
• Export Formats: JSON, CSV, Syslog

Resource Orchestration (v9.0)

• Auto-Scaling: Policy-based scaling (aggressive, moderate, conservative)
• Workload Balancing: Intelligent resource distribution
• Resource Optimization: Allocation efficiency analysis
• Maintenance Scheduling: Automated maintenance windows
• Scaling History: Track all scaling events

Usage Example

from hyper2kvm.core.vmcraft import VMCraft

# Context manager for automatic cleanup
with VMCraft() as g:
    # Add disk image
    g.add_drive_opts("/path/to/disk.vmdk", readonly=True, format="vmdk")

    # Launch (NBD connect + storage activation)
    g.launch()  # ~1.9s vs libguestfs ~10-13s

    # Inspect OS
    roots = g.inspect_os()
    for root in roots:
        os_type = g.inspect_get_type(root)        # "linux" or "windows"
        product = g.inspect_get_product_name(root) # "Ubuntu 24.04"
        version = g.inspect_get_major_version(root)

    # Mount filesystem
    mounts = g.inspect_get_mountpoints(roots[0])
    for mp, dev in mounts.items():
        g.mount(dev, mp)

    # File operations
    content = g.cat("/etc/hostname")
    g.write("/etc/motd", "Welcome!\n")

    # Windows registry (if Windows)
    if os_type == "windows":
        product_name = g.win_registry_read(
            "SOFTWARE",
            r"Microsoft\Windows NT\CurrentVersion",
            "ProductName"
        )

    # AI/ML Analytics (v9.0)
    metrics = {
        "cpu_usage": [45, 50, 48, 52, 49],
        "memory_usage": [60, 62, 61, 63, 59],
        "disk_io": [100, 105, 102, 108, 103]
    }
    anomalies = g.ml_detect_anomalies(metrics, "cpu_usage")
    workload = g.ml_classify_workload(metrics)

    # Cloud optimization (v9.0)
    readiness = g.cloud_analyze_readiness(system_info)
    instances = g.cloud_recommend_instance_type(requirements, "aws")
    costs = g.cloud_calculate_costs(usage_profile, "azure")

    # DR planning (v9.0)
    dr_plan = g.dr_create_backup_strategy(requirements)
    rto_rpo = g.dr_calculate_rto_rpo(backup_config)

    # Automatic cleanup on context exit

Integration with hyper2kvm

VMCraft is fully integrated into hyper2kvm's pipeline:

from hyper2kvm.core.vmcraft import VMCraft

# Direct instantiation
g = VMCraft(python_return_dict=True)

# Or use factory pattern for flexibility
from hyper2kvm.core.guestfs_factory import create_guestfs
g = create_guestfs(backend='vmcraft')

System Dependencies

Required:

• qemu-utils (qemu-nbd)
• util-linux (mount, lsblk, blkid)
• lvm2 (LVM support)
• cryptsetup (LUKS encryption)

Windows Support:

• ntfs-3g (NTFS write support)
• libhivex-bin (Registry tools)

Optional:

• mdadm (Software RAID)
• zfsutils-linux (ZFS support)
• exfat-fuse (exFAT support)

Version History

Version	Methods	Modules	Key Features
v6.0	203	42	Advanced security & migration
v7.0	237	47	Forensic & infrastructure
v8.0	275	52	Automation & intelligence
v9.0	307	57	AI/ML & orchestration

See: VMCraft README | v9.0 Summary

---

Developer Guide

Where to Add New Functionality

New network backend (e.g., Alpine Linux interfaces format): → fixers/network/backend.py - Add new fix_alpine_interfaces() method

New disk format extractor (e.g., Parallels .pvm): → converters/extractors/parallels.py - Create new extractor class → converters/extractors/__init__.py - Export new class

New VMware transport method (e.g., NFS datastore access): → vmware/transports/nfs_client.py - Implement new transport → Update vmware/vsphere/mode.py to use new transport

New Windows driver injection strategy: → fixers/windows/virtio/ - Add new injection module → Update fixers/windows/virtio/injector.py to orchestrate

New CLI validation: → cli/args/validators.py - Add new _validate_*() function → Update cli/args/validators.py:validate_args() to call it

Code Quality Standards

All modules follow these standards:

• Type annotations: 100% coverage in new code (network package standard)
• Imports: from __future__ import annotations for forward references
• Dependencies: Zero circular dependencies (enforced)
• Docstrings: Comprehensive module and function docstrings
• Single Responsibility: Each module has one clear purpose
• Size limit: Modules over 1,000 lines should be considered for splitting

Architecture Highlights

Zero Circular Dependencies: All packages have clean dependency graphs. The refactoring specifically eliminated circular dependencies by:

• Separating data models from business logic
• Using composition over inheritance
• Keeping interfaces in base modules

Composition Over Inheritance: Rather than deep class hierarchies, modules use composition:

# NetworkFixer composes specialized components
class NetworkFixer:
    def __init__(self):
        self.discovery = NetworkDiscovery()
        self.topology = NetworkTopology()
        self.validation = NetworkValidation()
        self.backend = NetworkFixersBackend()

Backward Compatibility: All reorganizations maintain 100% backward compatibility via wrapper modules that re-export from new locations.

Package Exports: Each package has an __init__.py that exports public APIs, allowing clean imports:

# fixers/network/__init__.py
from .core import NetworkFixer
from .model import FixLevel, NetworkConfig, InterfaceType

__all__ = ["NetworkFixer", "FixLevel", "NetworkConfig", "InterfaceType"]

---

4. Supported Inputs and Execution Modes

Hypervisor-Agnostic by Design

hyper2kvm is not a VMware-only tool.

VMware happens to be the most deeply integrated source today because it is:

• Common in enterprises
• Snapshot-heavy
• Full of sharp edges

Architecturally, hyper2kvm does not care about hypervisors.
It cares about:

• Disks
• Firmware assumptions
• Boot chains
• Drivers
• Metadata quality

Any platform that can ultimately produce block devices + minimal metadata can be migrated.

flowchart LR
  HV1[VMware]
  HV2[Hyper-V]
  HV3[Cloud / AMI]
  HV4[Physical / Raw]
  HV5[Other Hypervisors]

  HV1 --> D[Disks + Metadata]
  HV2 --> D
  HV3 --> D
  HV4 --> D
  HV5 --> D

  D --> P[hyper2kvm Pipeline]
  P --> K[KVM / QEMU]

  style HV1 fill:#FF9800,stroke:#E65100,color:#fff
  style HV2 fill:#FF9800,stroke:#E65100,color:#fff
  style HV3 fill:#FF9800,stroke:#E65100,color:#fff
  style HV4 fill:#FF9800,stroke:#E65100,color:#fff
  style HV5 fill:#FF9800,stroke:#E65100,color:#fff
  style D fill:#9C27B0,stroke:#6A1B9A,color:#fff
  style P fill:#4CAF50,stroke:#2E7D32,color:#fff
  style K fill:#2196F3,stroke:#1565C0,color:#fff

The moment disks are available, all inputs converge.

---

Primary: VMware (Deep Integration)

• Descriptor VMDK

• Monolithic VMDK

• Multi-extent snapshot chains

• OVA

• OVF + extracted disks

• ESXi over SSH / SCP

• vCenter / ESXi via:

  • govc (primary control-plane)
  • pyvmomi / pyVim (fallback and deep inspection)

Used for:

• Inventory
• Snapshot planning
• CBT discovery
• Datastore browsing
• Artifact resolution

This is the most mature path in hyper2kvm.

---

Hyper-V / Microsoft Disk Formats (Disk-Level)

Supported as artifact inputs, without Hyper-V APIs:

• VHD
• VHDX

Handled via offline inspection, repair, and deterministic driver transitions.

---

Cloud Images / AMIs (Artifact-Level)

Supported once reduced to disks:

• AWS AMI / EBS snapshots (exported to raw / qcow2)
• Generic cloud images

Fixes include:

• NVMe vs virtio assumptions
• initramfs completeness
• Network configs bound to cloud metadata
• Bootloader defaults that fail off-cloud

No cloud lifecycle or IAM handling is included.

---

Generic Disk Artifacts

Any block-attachable format:

• raw
• qcow2
• vdi
• vmdk
• vhd / vhdx

Once inside, all inputs are treated equally.

---

5. Pipeline Model

All execution modes map to a single internal pipeline:

FETCH → FLATTEN → INSPECT → FIX → CONVERT → VALIDATE

Stages are optional. Order is not.

Stage	Purpose
FETCH	Obtain disks and metadata
FLATTEN	Collapse snapshot chains
INSPECT	Detect OS, layout, firmware
FIX	Apply deterministic repairs
CONVERT	Produce qcow2 / raw / etc
VALIDATE	Boot-test and verify

The pipeline is explicit, inspectable, and restart-safe.

---

6. Control-Plane vs Data-Plane (Architecture)

This separation is the spine of hyper2kvm.

• Control-Plane decides what exists and what should happen
• Data-Plane moves bytes and produces artifacts

If you mix them, you get “it worked once” migrations. If you separate them, you get repeatable ones.

flowchart TB
  subgraph CP["CONTROL PLANE (decide)"]
    GOVC["govc (primary)"]
    HYPERCTL["hyperctl → hypervisord
high-performance daemon"]
    PYVM["pyvmomi / pyVim
fallback / deep inspection"]
    INV["Inventory: VM, disks,
firmware, snapshots"]
    PLAN["Plans: snapshot flatten,
disk map, export intent"]
    DS["Datastore browsing &
artifact resolution"]
    CBT["CBT discovery +
changed ranges planning"]

    GOVC --> INV
    HYPERCTL --> INV
    GOVC --> DS
    GOVC --> CBT
    HYPERCTL --> CBT
    PYVM --> INV
    PYVM --> CBT
    INV --> PLAN
    DS --> PLAN
    CBT --> PLAN
  end

  META["plans + metadata
explicit, auditable"]

  subgraph DP["DATA PLANE (move bytes)"]
    GOVCEXP["govc export.ovf /
export.ova"]
    HYPEREXP["hypervisord export
parallel downloads
3-5x faster, resumable"]
    OVFTOOL["ovftool
OVF/OVA export/import"]
    HTTP["HTTP /folder +
Range requests"]
    VDDK["VDDK
high-throughput disk reads"]
    SSH["SSH / SCP
fallback"]
    RESUME["resume + verify +
atomic publish"]
  end

  CP --> META --> DP
  GOVCEXP --> RESUME
  HYPEREXP --> RESUME
  OVFTOOL --> RESUME
  HTTP --> RESUME
  VDDK --> RESUME
  SSH --> RESUME

  style CP fill:#2196F3,stroke:#1565C0,color:#fff
  style DP fill:#4CAF50,stroke:#2E7D32,color:#fff
  style META fill:#9C27B0,stroke:#6A1B9A,color:#fff
  style GOVC fill:#FF9800,stroke:#E65100,color:#fff
  style HYPERCTL fill:#F44336,stroke:#C62828,color:#fff
  style HYPEREXP fill:#F44336,stroke:#C62828,color:#fff
  style PYVM fill:#FFC107,stroke:#F57C00,color:#000
  style RESUME fill:#00BCD4,stroke:#006064,color:#fff

Rule

• Control-plane never moves bulk data
• Data-plane never makes inventory decisions

The bridge is always explicit plans + metadata.

---

7. Linux Fixes

• /etc/fstab rewrite (UUID= / PARTUUID= preferred)
• GRUB root stabilization (BIOS + UEFI)
• initramfs regeneration (distro-aware)
• Network cleanup (MAC pinning, hypervisor artifacts)

---

8. Windows Handling

Windows is a first-class citizen.

• VirtIO storage injected as BOOT_START
• Offline registry and hive edits
• CriticalDeviceDatabase fixes
• BCD handling with backups
• Two-phase boot: SATA bootstrap → VirtIO final
• Driver plans are data-driven (JSON/YAML)

No blind binary patching. Everything is logged and reversible.

---

9. Snapshots and Flattening

• Recursive descriptor resolution
• Parent-chain verification
• Flatten before conversion
• Atomic outputs

---

10. Output Formats and Validation

Formats

• qcow2 (recommended)
• raw
• vdi

Validation

• Checksums
• libvirt smoke boots
• Direct QEMU boots
• BIOS and UEFI
• Headless supported

---

11. YAML Configuration Model

YAML is treated as code:

• Mergeable
• Reviewable
• Rerunnable

--config base.yaml --config vm.yaml --config overrides.yaml

---

12–20. Advanced Topics

• Batch processing
• Live-fix mode (SSH)
• ESXi and vSphere integration
• Safety mechanisms
• Daemon and automation modes
• Testing and failure analysis
• Explicit non-goals

---

21. Documentation Index and References

Complete documentation is available in the docs/ directory:

• Getting Started: QUICKSTART.md, INSTALL.md
• Reference: CLI_REFERENCE.md, YAML-EXAMPLES.md
• Architecture: ARCHITECTURE.md, orchestrator/README.md
• Platform Guides: WINDOWS.md, PHOTONOS.md, RHEL10.md
• Troubleshooting: FAILURE_MODES.md, cookbook.md
• Development: BUILDING.md - Build, test, and development guide

---

Contributing

We welcome contributions! Here's how to get started:

Development Setup

# Clone the repository
git clone https://github.com/ssahani/hyper2kvm.git
cd hyper2kvm

# Quick start (recommended)
make quickstart

# Or manually
pip install hatch
pip install -e .[dev,full]

# Run tests
make test          # Using Make
hatch run test     # Using Hatch

# Run linting and security checks
make lint          # Using Make
make security      # Security scans
hatch run ci       # Full CI pipeline using Hatch

See BUILDING.md for complete build and testing documentation.

Contribution Guidelines

1. Fork and Branch: Create a feature branch from main
2. Code Standards:
   • Follow PEP 8 style guidelines
   • Add type annotations for all new code
   • Write comprehensive docstrings
   • Keep modules under 1,000 lines when possible
3. Testing:
   • Add unit tests for new features
   • Ensure all tests pass (pytest tests/)
   • Run security scans (bandit -r hyper2kvm/)
4. Documentation:
   • Update relevant documentation in docs/
   • Add examples to examples/README.md if applicable
   • Update ARCHITECTURE.md for structural changes
5. Pull Requests:
   • Write clear commit messages
   • Reference related issues
   • Ensure CI passes (tests, linting, security)

See ARCHITECTURE.md for detailed architecture guidelines.

Reporting Issues

• Bugs: Use the bug report template
• Features: Use the feature request template
• Security: Email security issues privately (see SECURITY.md if available)

---

License

This project is licensed under the GNU Lesser General Public License v3.0 (LGPL-3.0).

See LICENSE for full license text.

Key Points:

• You can use hyper2kvm in proprietary software without making your code open source
• Modifications to hyper2kvm itself must be released under LGPL-3.0
• No warranty provided (see license for details)

---

Support

Community Support

• GitHub Discussions: Ask questions and share experiences
• Issue Tracker: Report bugs and request features
• Documentation: Comprehensive guides in docs/

Professional Support

For enterprise support, consulting, or custom development:

• Open a support request issue
• Contact the maintainers directly

---

Acknowledgments

hyper2kvm builds on excellent open-source projects:

• libguestfs - Offline disk inspection and modification
• QEMU - Disk format conversion and virtualization
• govc - vSphere CLI
• pyvmomi - VMware vSphere API Python SDK
• hypersdk - High-performance multi-cloud provider daemon (optional, 3-5x faster exports)
• libvirt - Virtualization management

Special thanks to all contributors.

---

Project Status

Current Status: Active development

• Latest Release: Check releases
• Build Status:
• Security:

---

Made with ❤️ for reliable VM migrations