hyper2kvm

VMCraft: Comprehensive OS Detection

Overview

VMCraft now includes comprehensive operating system detection for all major Linux distributions and all Windows versions, matching the detection capabilities found in the existing Windows virtio driver injection code.

Enhanced Features

Linux Distribution Detection

VMCraft now detects all major Linux distributions through multiple fallback methods:

Detection Methods (Priority Order)

  1. /etc/os-release - Modern standard (systemd-based distributions)
  2. /etc/lsb-release - LSB standard
  3. Distribution-specific files - Legacy detection
  4. /etc/issue - Final fallback

Supported Linux Distributions

Red Hat Family:

SUSE Family:

Debian Family:

Other Distributions:

Extracted Linux Metadata

Windows Version Detection

VMCraft now detects all Windows versions from NT 4.0 to Windows 12, including all Server editions.

Detection Methods (Priority Order)

  1. ProductName matching - Most reliable (registry key)
  2. Build number - For Windows 10/11 distinction (>=22000 = Win11)
  3. Major/minor version - Legacy Windows (7, Vista, XP)

Supported Windows Versions

Client Editions:

Server Editions:

Extracted Windows Metadata

Windows Version Detection Logic

Registry Key: Microsoft\Windows NT\CurrentVersion

Registry Values Read:

Build Number Ranges:

Implementation Details

Code Location

VMCraft has been refactored into a modular directory structure:

Directory: hyper2kvm/core/vmcraft/

Key Modules:

Key Classes:

Detection Workflow

  1. Launch: Connect disk via qemu-nbd
  2. Inspection: Scan all partitions for root filesystem indicators
  3. Mount: Mount candidate root filesystem read-only
  4. Detection: Parse OS-specific files (os-release, registry hives)
  5. Cache: Store detection results in _inspect_cache
  6. Logging: Display comprehensive OS information

Logging Output

Linux Example:

🐧 Detected Linux OS on /dev/nbd0p3
   Product: Fedora Linux 43 (Forty Three)
   Distribution: fedora
   Variant: Workstation
   Version: 43.
   Architecture: x86_64

Windows Example:

🪟 Detected Windows OS on /dev/nbd0p2
   Product: Windows 11 Pro
   OS Name: Windows 11
   Edition: Professional
   Build: 22631
   Display Version: 23H2
   Version: 10.0
   Architecture: x86_64

System Requirements

For Linux Detection:

For Windows Detection:

API Usage

from hyper2kvm.core.vmcraft import VMCraft

# Create VMCraft instance
g = VMCraft(python_return_dict=True)

# Launch and inspect
g.add_drive_opts("/path/to/disk.vmdk", readonly=1, format="vmdk")
g.launch()

# Detect operating systems
roots = g.inspect_os()  # Returns: ['/dev/nbd0p2']

# Get OS information
for root in roots:
    os_type = g.inspect_get_type(root)        # "windows" or "linux"
    distro = g.inspect_get_distro(root)       # "windows", "fedora", "ubuntu", etc.
    product = g.inspect_get_product_name(root)  # "Windows 11 Pro", "Fedora Linux 43"
    arch = g.inspect_get_arch(root)           # "x86_64", "i686", etc.
    major = g.inspect_get_major_version(root)  # 10 (Windows 11), 43 (Fedora)
    minor = g.inspect_get_minor_version(root)  # 0, etc.

# Cleanup
g.shutdown()
g.close()

References

Existing Code Used as Reference

  1. Windows Detection:
    • hyper2kvm/fixers/windows/virtio/detection.py
      • _detect_windows_release() - Windows version mapping logic
      • _windows_version_info() - Registry parsing
      • Build number ranges and version detection
  2. Linux Detection:
    • hyper2kvm/core/guest_identity.py
      • collect_linux_identity() - OS-release parsing
      • parse_os_release() - Key-value parsing
  3. Guest Inspection:
    • hyper2kvm/core/guest_inspector.py
      • Comprehensive guest inspection patterns
      • Filesystem detection methods

Modular Architecture

VMCraft has been refactored into a modular directory structure:

hyper2kvm/core/vmcraft/
├── __init__.py              # Public API exports
├── main.py                  # Main VMCraft class (orchestrator)
├── _utils.py                # Shared utilities
│
├── nbd.py                   # NBD device management (307 lines)
├── storage.py               # Storage stack activation (428 lines)
├── mount.py                 # Mount operations (213 lines)
├── file_ops.py              # File operations (363 lines)
│
├── inspection.py            # OS detection orchestration (242 lines)
├── linux_detection.py       # Linux-specific detection (383 lines)
├── windows_detection.py     # Windows-specific detection (397 lines)
│
├── windows_registry.py      # Registry operations (310 lines)
├── windows_drivers.py       # Driver injection (240 lines)
│
├── backup.py                # Backup/restore operations (124 lines)
├── security.py              # Security auditing (90 lines)
└── optimization.py          # Disk optimization (248 lines)

Total: 15 modules, 4,158 lines (previously: 1 file, 2,795 lines)

Benefits:

Testing

# Test with a Linux VM
sudo python3 -c "
from hyper2kvm.core.vmcraft import VMCraft
g = VMCraft()
g.add_drive_opts('/path/to/linux.vmdk', readonly=1, format='vmdk')
g.launch()
roots = g.inspect_os()
for root in roots:
    print(f'Type: {g.inspect_get_type(root)}')
    print(f'Distro: {g.inspect_get_distro(root)}')
    print(f'Product: {g.inspect_get_product_name(root)}')
g.shutdown()
"

# Test with a Windows VM
sudo python3 -c "
from hyper2kvm.core.vmcraft import VMCraft
g = VMCraft()
g.add_drive_opts('/path/to/windows.vmdk', readonly=1, format='vmdk')
g.launch()
roots = g.inspect_os()
for root in roots:
    print(f'Type: {g.inspect_get_type(root)}')
    print(f'Product: {g.inspect_get_product_name(root)}')
    print(f'Major: {g.inspect_get_major_version(root)}')
g.shutdown()
"

Compatibility

Performance

OS detection is fast (< 2 seconds typical):

Note: This comprehensive OS detection ensures VMCraft can handle VM migrations from any major Linux distribution or Windows version, making it production-ready for enterprise hypervisor-to-KVM migrations.

This site is open source. Improve this page.