hyper2kvm

Features Documentation

Comprehensive documentation for all Hyper2KVM features and capabilities.

🔧 Core Features

VMCraft Engine - Native VM manipulation (480+ APIs)
XFS UUID Regeneration - Fix cloned VMware VMs
fstab Stabilization - Automatic fstab repair
Enhanced Chroot - Advanced filesystem access

🔍 Inspection & Validation

VMDK Inspector - Analyze VMDK files pre-migration
VMDK Validation - Pre-migration validation checks
BusLogic Auto-Fix - Legacy SCSI controller handling

🔄 Daemon & Automation

Daemon Mode - Background daemon operation
Daemon Architecture - Design and components
Daemon Enhancements - Advanced daemon features
Daemon User Guide - Complete daemon usage

⚙️ System Integration

Systemd Integration - Service management
Configuration Injection - Dynamic configuration

☁️ Cloud & Virtualization

vSphere Export - VMware vSphere integration
vSphere Design - vSphere architecture

📦 VMCraft Specialized Guides

VMCraft Complete Guide - Full VMCraft documentation
VMCraft Advanced Features - Expert usage
VMCraft OS Detection - OS identification
VMCraft Windows Support - Windows features
VMCraft Augeas Guide - Configuration editing
VMCraft LVM Guide - Logical volume management
VMCraft Partition Management - Disk partitioning
VMCraft Performance Guide - Optimization

Features by Category

🎯 Essential Features (Start Here)

Feature	Description	Status	Difficulty
VMCraft Engine	Native Python VM manipulation	✅ Production	⭐⭐
fstab Stabilization	Automatic fstab repair	✅ Production	⭐
Enhanced Chroot	Advanced filesystem access	✅ Production	⭐⭐
VMDK Inspector	Pre-migration analysis	✅ Production	⭐

🔧 Boot & Filesystem Features

Feature	Use Case	Documentation
XFS UUID Regeneration	Fix cloned VMware VMs with duplicate UUIDs	Guide
fstab Stabilization	Auto-repair fstab, convert to UUID/LABEL	Guide
Enhanced Chroot	Safe filesystem access with full isolation	Guide
BusLogic Auto-Fix	Handle legacy BusLogic SCSI controllers	Guide

🔍 Validation & Inspection

Feature	Purpose	Documentation
VMDK Inspector	Analyze VMDK structure, detect issues	Guide
VMDK Validation	Pre-migration compatibility checks	Guide

🔄 Automation & Daemon

Feature	Capability	Documentation
Daemon Mode	Background processing, job queue	Guide
Daemon Architecture	Design patterns, components	Guide
Daemon Enhancements	Advanced features, monitoring	Guide
Daemon User Guide	Complete usage guide	Guide

⚙️ System & Configuration

Feature	Function	Documentation
Systemd Integration	Service management, auto-start	Guide
Configuration Injection	Dynamic config generation	Guide

☁️ Cloud & Virtualization Integration

Platform	Features	Documentation
vSphere	Export, fetch, integration	Export, Design

VMCraft Engine

Overview

VMCraft is Hyper2KVM’s native Python VM manipulation engine with 480+ APIs for guest filesystem operations without requiring libguestfs.

Key Capabilities:

✅ Direct filesystem access - Native Python, no C dependencies
✅ 480+ APIs - Comprehensive guest manipulation
✅ OS detection - Automatic operating system identification
✅ Package management - yum, dnf, apt, zypper support
✅ Configuration editing - Augeas integration
✅ Windows support - Registry, driver injection
✅ LVM support - Logical volume management
✅ Performance optimized - Caching, lazy loading

Documentation:

Complete Guide - Full VMCraft documentation
Advanced Features - Expert-level usage
OS Detection - OS identification system
Windows Support - Windows-specific features

Specialized Guides:

Augeas Guide - Configuration file editing
LVM Guide - Logical volume management
Partition Management - Disk partitioning
Performance Guide - Optimization techniques

Feature Highlights

1. XFS UUID Regeneration

Problem: Cloned VMware VMs often have duplicate XFS filesystem UUIDs, causing boot failures.

Solution: Automatic UUID regeneration with fstab updates.

command: local
vmdk: /vmware/cloned-vm.vmdk
output_dir: /kvm/vms
to_output: fixed-vm.qcow2

# Enable XFS UUID fix
xfs_regenerate_uuid: true
fstab_mode: stabilize-all

See: XFS UUID Regeneration Guide

2. fstab Stabilization

Problem: VMDKs use device names (/dev/sda1) which may change in KVM.

Solution: Automatic conversion to UUID or LABEL-based mounting.

Modes:

stabilize-all: Convert all entries to UUID
uuid-only: Only update UUID entries
label-fallback: Prefer UUID, fallback to LABEL
preserve: Keep original entries

fstab_mode: stabilize-all

See: fstab Stabilization Guide

3. Enhanced Chroot

Problem: Standard chroot is unsafe and can affect host system.

Solution: Isolated chroot environment with proper cleanup.

Features:

Automatic mount/unmount of /proc, /sys, /dev
Safe cleanup even on errors
Nested chroot support
Resource isolation

See: Enhanced Chroot Guide

4. VMDK Inspector

Problem: Need to analyze VMDK before migration to detect issues.

Solution: Comprehensive VMDK analysis tool.

Capabilities:

Disk geometry inspection
Partition table analysis
Filesystem detection
OS detection
Issue identification
Migration recommendations

# Inspect VMDK
./scripts/vmdk_inspect.py /path/to/vm.vmdk

# With auto-fix recommendations
./scripts/vmdk_inspect.py /path/to/vm.vmdk --auto-fix

See: VMDK Inspector Guide

5. Daemon Mode

Problem: Need background processing and job queue for large-scale migrations.

Solution: Full-featured daemon with REST API.

Features:

Background job processing
REST API for job submission
Job queue with priorities
Progress tracking
Metrics and monitoring
Systemd integration

# Start daemon
hyper2kvm daemon start

# Submit job
hyper2kvm daemon submit migration.yaml

# Check status
hyper2kvm daemon status

See: Daemon Mode Guide, Daemon User Guide

Feature Comparison

VMCraft vs libguestfs

Feature	VMCraft	libguestfs
Language	Pure Python	C with Python bindings
Dependencies	Minimal	Heavy (C libraries)
APIs	480+	300+
Windows Support	Native	Limited
Performance	Optimized	Good
Installation	pip install	System packages
Portability	High	Medium

Migration Modes

Mode	Downtime	Use Case	Features
Standard	Full	Most migrations	Complete feature set
Live Fix	<5 seconds	Production VMs	SSH-based, minimal downtime
Daemon	Scheduled	Batch migrations	Queue, scheduling, monitoring

Common Feature Combinations

Combination 1: Safe Linux Migration

command: local
vmdk: /vmware/linux-vm.vmdk
output_dir: /kvm/vms
to_output: linux-vm.qcow2

# Essential features
fstab_mode: stabilize-all
xfs_regenerate_uuid: true
regen_initramfs: true
update_grub: true

Features Used: fstab stabilization, XFS UUID regen, enhanced chroot

Combination 2: VMware Clone Fix

command: local
vmdk: /vmware/cloned-vm.vmdk
output_dir: /kvm/vms
to_output: fixed-clone.qcow2

# Clone-specific fixes
xfs_regenerate_uuid: true
fstab_mode: stabilize-all
regen_initramfs: true

Features Used: XFS UUID regeneration, fstab stabilization

Combination 3: Production Migration with Validation

# 1. Inspect VMDK
./scripts/vmdk_inspect.py /vmware/prod-vm.vmdk --auto-fix

# 2. Run migration with all features
hyper2kvm --config << EOF
command: local
vmdk: /vmware/prod-vm.vmdk
output_dir: /kvm/vms
to_output: prod-vm.qcow2
fstab_mode: stabilize-all
xfs_regenerate_uuid: true
regen_initramfs: true
update_grub: true
compress: true
EOF

Features Used: VMDK inspector, fstab stabilization, XFS UUID, enhanced chroot

Feature Status

Production Ready ✅

Feature	Version	Status
VMCraft Engine	1.0+	✅ Stable
fstab Stabilization	1.0+	✅ Stable
XFS UUID Regen	1.0+	✅ Stable
Enhanced Chroot	1.0+	✅ Stable
VMDK Inspector	1.3+	✅ Stable
VMDK Validation	1.3+	✅ Stable
Daemon Mode	1.0+	✅ Stable
Systemd Integration	1.0+	✅ Stable
vSphere Export	1.0+	✅ Stable
BusLogic Auto-Fix	1.3+	✅ Stable

Beta Features 🔶

Feature	Version	Status
Configuration Injection	2.0+	🔶 Beta

Performance Characteristics

VMCraft Performance

Operation	Speed	Notes
OS Detection	<1 sec	Cached after first detection
Package Query	1-2 sec	Database operations
File Read	Fast	Direct filesystem access
File Write	Fast	Optimized I/O
Chroot Setup	<1 sec	One-time per session

Feature Overhead

Feature	Time Impact	When to Use
fstab Stabilization	+2-5 sec	Always (essential)
XFS UUID Regen	+5-30 sec	VMware clones only
VMDK Inspection	+10-30 sec	Pre-migration analysis
VMDK Validation	+5-15 sec	Pre-migration checks

Best Practices

Essential Features (Always Use)

✅ fstab Stabilization: Prevents boot failures from device name changes ✅ Enhanced Chroot: Safe filesystem access ✅ VMDK Inspector: Identify issues before migration

Conditional Features (Use When Needed)

🔶 XFS UUID Regeneration: Use for VMware clones 🔶 BusLogic Auto-Fix: Use for VMs with BusLogic SCSI 🔶 Daemon Mode: Use for batch migrations 🔶 vSphere Export: Use for VMware vSphere integration

Performance Features

⚡ VMCraft Caching: Enabled by default ⚡ Lazy Loading: Reduces memory usage ⚡ Parallel Processing: Use batch mode for multiple VMs

Feature Development

Contributing New Features

Identify need: Use case and user request
Design: Architecture and API design
Implement: Code with tests
Document: Feature guide and examples
Test: Integration and unit tests
Release: Version and changelog

See: Contributing Guide

Before Using Features

Getting Started - Installation and setup
Tutorials - Step-by-step learning

While Using Features

User Guides - Task-oriented guides
Recipes - Quick solutions
Troubleshooting - Fix issues

After Using Features

API Reference - Complete API docs
Testing Guide - Testing features

Feature Requests

Have an idea for a new feature?

Check existing features: Review this documentation
Search issues: GitHub Issues
Create feature request: New Feature Request
Discuss: GitHub Discussions

What’s Next?

Choose your area of interest:

Last Updated: February 2026 Total Features: 20+ Production Ready: 15+ VMCraft APIs: 480+

This site is open source. Improve this page.