guestctl 0.3.1

Pure Rust VM disk toolkit with beautiful output, Windows registry parsing, and VM migration support - Python bindings

guestctl

A pure Rust toolkit for VM disk inspection and manipulation with beautiful emoji-enhanced output. Inspect VM disks in seconds without booting them. Designed to work seamlessly with hyper2kvm and VM migration workflows.

✨ Latest (v0.3.1):

• 🤖 AI-Powered Diagnostics - OpenAI GPT-4o integration for intelligent VM troubleshooting (optional)
• 🎮 Interactive Mode - 97+ commands across 28 categories for comprehensive VM management
• 🎯 Killer Summary View - See OS, version, architecture at a glance with color-coded output
• 🪟 Windows Registry Parsing - Full Windows version detection via registry access
• 🔄 VM Migration Support - Universal fstab/crypttab rewriter for cross-platform migration
• 💾 Smart LVM Cleanup - Automatic volume group cleanup for reliable operations
• 🔄 Loop Device Primary - Built-in support for RAW/IMG/ISO without kernel modules

🚀 Recent Enhancements (Q1 2026):

• 🔧 Systemd Analysis Suite - Comprehensive systemd inspection without running the VM
  • systemd-journal - Analyze journal logs with filtering, statistics, and error detection
  • systemd-services - Inspect services, dependencies, and generate Mermaid diagrams
  • systemd-boot - Boot performance analysis with optimization recommendations
• 📊 Enhanced Export Capabilities
  • PDF reports with professional layout and configurable paper sizes
  • HTML reports with Chart.js visualizations and dark theme support
  • Markdown reports with Mermaid diagrams (architecture, network, storage)
  • Customizable template system with 8 built-in templates
• ⚡ Performance Optimizations
  • Binary cache (bincode) - 5-10x faster serialization, 50-70% smaller files
  • Parallel batch processing - 4-8x speedup for multiple disk inspections
  • Memory optimization - Pre-allocated vectors for 2x faster allocations
  • Cache enabled by default for instant repeated inspections

🚀 Quick Start

Installation

Python Package (Recommended for Python users):

pip install guestctl

Rust Crate (Recommended for Rust developers):

cargo install guestctl

From Source:

git clone https://github.com/ssahani/guestkit
cd guestkit
cargo build --release

Usage

Inspect a VM disk:

guestctl inspect vm.qcow2

Output:

┌────────────────────────────────────────────────────────┐
│ Ubuntu 22.04.3 LTS                                      │
│ Type: linux | Arch: x86_64 | Hostname: webserver-prod │
│ Packages: deb | Init: systemd                          │
└────────────────────────────────────────────────────────┘

💾 Block Devices
────────────────────────────────────────────────────────────
  ▪ /dev/sda 8589934592 bytes (8.59 GB)

🖥️  Operating Systems
────────────────────────────────────────────────────────────
    🐧 Type:         linux
    📦 Distribution: ubuntu
    🏷️ Product:      Ubuntu 22.04.3 LTS
    🏠 Hostname:     webserver-prod
    ⚡ Init system:  systemd

    💻 Language Runtimes
    ────────────────────────────────────────────────────────
      🐍 python3
      🟢 Node.js

    🐳 Container Runtimes
    ────────────────────────────────────────────────────────
      🐳 Docker

Interactive mode with 97+ commands:

guestctl interactive vm.qcow2

AI-Powered Diagnostics (optional):

# Build with AI support
cargo build --release --features ai

# Set your OpenAI API key
export OPENAI_API_KEY='your-key-here'

# Use AI assistant in interactive mode
guestctl interactive vm.qcow2
> ai why won't this boot?
> ai what security issues do you see?
> ai analyze disk usage patterns

Interactive Mode - 97+ Commands:

The interactive shell provides comprehensive VM management capabilities organized into 28 categories:

guestctl interactive vm.qcow2

Command Categories:

• System Information (2) - info, help
• Filesystem Operations (5) - filesystems, mount, umount, mounts
• File Operations (8) - ls, cat, head, find, stat, download, upload, edit
• File Management (12) - write, copy, move, delete, mkdir, chmod, chown, symlink, large-files, disk-usage
• Package Management (5) - packages, install, remove, update, search
• System Inspection (4) - services, users, network
• User Management (5) - adduser, deluser, passwd, usermod, groups
• SSH Key Management (5) - ssh-addkey, ssh-removekey, ssh-listkeys, ssh-enable, ssh-config
• System Configuration (4) - hostname, timezone, selinux, locale
• Service Management (6) - enable, disable, restart, logs, failed, boot-time
• Firewall Management (3) - firewall-add, firewall-remove, firewall-list
• Cron/Scheduled Tasks (2) - cron-add, cron-list
• System Cleanup (4) - clean-logs, clean-cache, clean-temp, clean-kernels
• Backup & Safety (2) - backup, backups
• Boot Configuration (3) - grub show, grub set, grub update
• Network Configuration (4) - net-setip, net-setdns, net-route-add, net-dhcp
• Process Management (3) - ps, kill, top
• Security & Audit (4) - scan-ports, audit-perms, audit-suid, check-updates
• Database Operations (2) - db-list, db-backup
• Advanced File Operations (5) - grep-replace, diff, tree, compress, extract
• Git Operations (2) - git-clone, git-pull
• Performance Tuning (2) - tune-swappiness, tune-show
• Quick Setup Wizards (3) - setup-webserver, setup-database, setup-docker
• Monitoring & Metrics (2) - metrics, bandwidth
• SELinux Advanced (2) - selinux-context, selinux-audit
• Templates (1) - template-save
• AI Assistant (1) - ai (requires --features ai)
• Shell Commands (3) - clear, exit, quit

See COMMANDS_SUMMARY.md for complete command reference.

Python API:

from guestctl import Guestfs

with Guestfs() as g:
    g.add_drive("disk.qcow2")
    g.launch()

    roots = g.inspect_os()
    for root in roots:
        print(f"OS: {g.inspect_get_distro(root)}")
        users = g.inspect_users(root)
        for user in users:
            print(f"User: {user.username}")

💿 Supported Disk Formats

guestctl automatically detects your disk format and uses the optimal mounting method:

🔄 Loop Device (Primary) - Built into Linux Kernel ⚡ Default

Formats: RAW, IMG, ISO Advantages:

• ✅ No kernel modules needed - Built into Linux kernel
• ✅ Faster setup - Immediate availability
• ✅ More reliable - No QEMU dependencies
• ✅ Zero configuration - Works out of the box Use case: Cloud images, raw disks, ISO files, DD images

🌐 NBD Device (Fallback) - Advanced Format Support

Formats: QCOW2, VMDK, VDI, VHD, VHDX Advantages:

• ✅ Compressed formats - Efficient storage
• ✅ Snapshots - Copy-on-write support
• ✅ Auto-loads NBD module - Automatic setup
• ✅ QEMU integration - Native QEMU format support Use case: QEMU/KVM, VMware, VirtualBox, Hyper-V images

# Loop device used automatically (fast path)
guestctl inspect disk.raw
guestctl inspect ubuntu.img
guestctl inspect debian.iso

# NBD device used automatically (advanced formats)
guestctl inspect vm.qcow2
guestctl inspect windows.vmdk
guestctl inspect virtualbox.vdi

💡 Pro Tip: Convert QCOW2 to RAW for faster repeated inspections:

qemu-img convert -O raw vm.qcow2 vm.raw
guestctl inspect vm.raw  # Now uses loop device!

Features

Core Capabilities

• 🦀 Ergonomic Rust API - Type-safe enums, builder patterns, and fluent interfaces for modern Rust idioms
• 🔍 Comprehensive API - 578 disk image manipulation functions (563 fully implemented, 15 API-defined) - 97.4% implementation coverage
• 🦀 Pure Rust - No C dependencies for core library, memory safe, high performance
• ⚡ Compile-Time Safety - Type-safe filesystems, OS detection, and partition tables prevent runtime errors

Disk & Storage

• 💿 Disk Format Support - RAW/IMG/ISO via loop devices (default, built-in), QCOW2/VMDK/VDI/VHD via NBD (automatic fallback)
• 📊 Partition Tables - MBR and GPT parsing, partition creation/deletion/resizing
• 🗂️ Filesystem Operations - Mount/unmount, create (mkfs), check (fsck), tune, trim, resize
• 🔐 Encryption Support - LUKS encrypted volumes with full key management
• 📚 LVM Support - Logical volume management with automatic cleanup
• 🔷 Advanced Filesystems - ext2/3/4, XFS, Btrfs, NTFS, ZFS, F2FS, ReiserFS, JFS, and 10+ more
• 💾 Disk Image Management - Create, resize, convert, sparsify, snapshot disk images

OS Inspection & Detection

• 🔎 OS Inspection - Detect OS type, distro, version, architecture, hostname
• 🪟 Windows Support - Full Windows registry parsing for version detection, registry hive access
• 🐧 Linux Detection - 30+ distributions with detailed metadata
• 📦 Package Management - List and inspect dpkg/rpm/pacman packages
• 🥾 Boot Configuration - Bootloader detection, kernel management, UEFI support

System Analysis

• 🔧 Systemd Analysis Suite - Comprehensive systemd inspection without running the VM
  • Journal Analysis - Read and analyze systemd journal logs with filtering and statistics
  • Service Analysis - Inspect services, detect failures, analyze dependencies
  • Boot Performance - Boot timing analysis with optimization recommendations
  • Mermaid Diagrams - Visual dependency trees and boot timelines
• 👤 System Configuration - Timezone, locale, users, groups, systemd units
• 🌐 Network Configuration - Read hostname, DNS, interface config, DHCP status
• 🔐 SSH Configuration - Analyze SSH settings with security recommendations
• 🔧 Service Management - systemd/sysvinit service detection, timers, cron jobs
• 💻 Runtime Detection - Identify Python, Node.js, Java, Ruby, Go, Perl installations
• 🐳 Container Runtimes - Detect Docker, Podman, containerd, CRI-O

VM Migration & Preparation

• 🔄 Universal fstab/crypttab Rewriter - Modify mount configurations for cross-platform migration
• 🧹 SysPrep Operations - Remove unique identifiers for VM cloning
• 📝 Device Path Translation - Automatic translation for target systems
• 🔑 LUKS Migration - Rewrite crypttab entries for encrypted volumes

Advanced Operations

• 🗜️ Archive Operations - tar, tgz, cpio creation and extraction
• 🔑 Checksums - MD5, SHA1, SHA256, SHA384, SHA512
• 🛡️ Security Operations - SELinux, AppArmor, capabilities, ACLs
• 🔑 SSH Operations - SSH key management, certificates, authorized_keys
• ⚙️ Configuration Editing - Augeas-based config file editing
• 🌳 Btrfs Advanced - Subvolumes, snapshots, balance, scrub operations
• 📊 File Metadata - Detailed stat operations, inode info, permissions
• 💿 ISO Operations - ISO creation, inspection, mounting
• 📤 Advanced Transfer - Offset-based downloads/uploads, device copying
• 💾 MD/RAID - Software RAID creation, management, inspection
• 🔄 Rsync - rsync-based file synchronization
• 📔 Journal - systemd journal reading, export, verification
• 🦠 YARA - malware scanning with YARA rules
• 🔬 TSK - forensics with The Sleuth Kit (deleted file recovery)
• 🩺 SMART - disk health monitoring with smartctl

Developer Experience

• 🐍 Python Bindings - PyO3-based native Python bindings with 100+ methods
• ⚡ Retry Logic - Built-in exponential backoff for reliable operations
• 🔌 Extensible - Modular architecture for easy extension
• 📖 Rich Documentation - Comprehensive guides and API references

Advanced CLI Features (guestctl)

• 🤖 AI-Powered Diagnostics (optional) - OpenAI GPT-4o integration for intelligent VM troubleshooting

  • Ask natural language questions about VM issues in plain English
  • Get expert analysis of boot failures, disk problems, and configuration issues
  • Context-aware diagnostics based on query keywords (boot, LVM, security, etc.)
  • Actionable recommendations with specific commands and warnings
  • Works seamlessly with 97+ interactive commands for VM modification
  • Requires --features ai build flag and OPENAI_API_KEY environment variable
  • Example queries: "why won't this boot?", "what security issues do you see?", "analyze disk usage patterns"

• 🎮 Interactive Mode - Full-featured REPL shell for VM management

  • 97+ commands organized into 28 categories
  • Tab completion and command history (readline-style)
  • Direct VM modification: user management, SSH keys, system configuration
  • Package management: install/remove/update packages without booting
  • Network configuration: static IP, DNS, routes, DHCP setup
  • Security auditing: port scanning, permission checks, SUID detection
  • Database operations: MySQL/PostgreSQL backup and management
  • Quick setup wizards: webserver, database, Docker installation
  • Performance tuning: swappiness, system metrics, bandwidth monitoring
  • Beautiful colored output with context-aware prompts

• 🎯 Killer Summary View - Quick summary box showing OS product, architecture, hostname at a glance

  • Color-coded information: Green (OS product), Cyan (architecture), Blue (hostname)
  • Boxed display for immediate visual impact
  • All key information in one line

• 🎨 Beautiful Visual Output - Emoji-enhanced terminal output with color coding for easy scanning

  • 💾 Block devices with icons and visual hierarchy
  • 🐧 OS detection with distribution-specific icons (Linux, Windows, FreeBSD)
  • 🔴 Package manager icons (RPM, DEB, Pacman)
  • 🌐 Network configuration display
  • Smart color coding: green (secure/active), red (issues/insecure), orange (key info), gray (unknown)

• 📊 Multiple Output Formats - JSON, YAML, CSV, and beautiful plain text for automation and scripting

• 🎯 Inspection Profiles - Specialized analysis modes:

  • Security Profile - SSH hardening, firewall status, user security, SELinux/AppArmor, risk scoring
  • Migration Profile - Complete inventory for VM migration planning
  • Performance Profile - System tuning opportunities and bottleneck detection

• 🔄 VM Comparison - Diff two VMs or compare multiple VMs against a baseline

• 📤 Report Export - Professional report generation for documentation and compliance

  • HTML Reports - Interactive reports with Chart.js visualizations, responsive design, dark theme support
  • PDF Reports - Professional layout with configurable paper sizes (A4, Letter, Legal)
  • Markdown Reports - GitHub/GitLab compatible with Mermaid diagrams (architecture, network topology, storage hierarchy)
  • Template System - Customizable reports with 8 built-in templates (minimal, standard, detailed)

• 🔧 Systemd Analysis Commands - Deep systemd inspection for troubleshooting and optimization

  • systemd-journal - Journal log analysis with filtering, error detection, and statistics
  • systemd-services - Service inspection, dependency visualization, failed service detection
  • systemd-boot - Boot performance analysis with slowest services and optimization recommendations

• ⚡ Result Caching - Binary cache (bincode) for 5-10x faster repeated inspections, 50-70% smaller cache files

• 🚀 Batch Processing - Parallel inspection with 4-8x speedup, configurable worker threads

Quick Start

Installation

# Install system dependencies (Fedora/RHEL)
sudo dnf install qemu-img

# From source
git clone https://github.com/ssahani/guestkit
cd guestctl
cargo build --release
cargo install --path .

CLI Tool

GuestCtl is a powerful command-line tool for inspecting and manipulating VM disk images without mounting them. Features beautiful emoji-enhanced output with color coding for better readability.

Example - Inspect a VMware Photon OS disk (5 seconds):

sudo guestctl inspect photon.vmdk

Output:

💾 Block Devices
────────────────────────────────────────────────────────────
  ▪ /dev/sda 8589934592 bytes (8.59 GB)
    • Read-only: yes

🗂  Partitions
────────────────────────────────────────────────────────────
  📦 /dev/sda3
    • Size:   8574189056 bytes (8.57 GB)

📁 Filesystems
────────────────────────────────────────────────────────────
  🐧 /dev/sda3 ext4
    • UUID:  311182bd-f262-4081-8a2d-56624799dbad

🖥️  Operating Systems
────────────────────────────────────────────────────────────
    🐧 Type:         linux
    📦 Distribution: photon
    🏷️ Product:      VMware Photon OS/Linux 5.0
    🏠 Hostname:     photon-2e2948360ed5
    🔴 Packages:     rpm
    ⚡ Init system:  systemd
    💾 Disk usage:   15.1% (5.15 TB used / 34.14 TB total)
    🐧 Kernel:       vmlinuz-6.1.10-11.ph5

Key Features:

• 🎨 Color-coded output - Visual hierarchy with emojis and colors
• ⚡ Fast - Complete OS detection in ~5 seconds
• 🔒 Safe - Read-only by default
• 🌐 Network detection - Automatic network config parsing
• 📊 Multiple formats - Pretty terminal, JSON, HTML, YAML

Basic Operations:

# Inspect with beautiful output
sudo guestctl inspect photon.vmdk

# JSON output for scripting
sudo guestctl inspect --json ubuntu.qcow2 | jq '.operating_systems[0].distro'

# List filesystems
sudo guestctl filesystems ubuntu.qcow2

# List installed packages
sudo guestctl packages ubuntu.qcow2

# Read a file
sudo guestctl cat ubuntu.qcow2 /etc/hostname

# List directory contents
sudo guestctl list ubuntu.qcow2 /etc

# Extract a file
sudo guestctl extract ubuntu.qcow2 /etc/passwd ./passwd

Advanced Features:

# Basic inspection
guestctl inspect vm.qcow2

# JSON output for automation
guestctl inspect vm.qcow2 --output json | jq '.os.hostname'

# Security audit profile
guestctl inspect vm.qcow2 --profile security

# Migration planning profile
guestctl inspect vm.qcow2 --profile migration --output json

# Performance tuning profile
guestctl inspect vm.qcow2 --profile performance

# Compare two VMs
guestctl diff vm-before.qcow2 vm-after.qcow2

# Compare multiple VMs against baseline
guestctl compare baseline.qcow2 vm1.qcow2 vm2.qcow2 vm3.qcow2

# Export HTML report with Chart.js visualizations
guestctl inspect vm.qcow2 --export html --export-output report.html

# Export PDF report with professional layout
guestctl inspect vm.qcow2 --export pdf --export-output report.pdf

# Export Markdown inventory with Mermaid diagrams
guestctl inspect vm.qcow2 --export markdown --export-output inventory.md

# Use custom template for export
guestctl inspect vm.qcow2 --export markdown --template detailed --export-output full-report.md

# Systemd journal analysis
guestctl systemd-journal vm.qcow2                     # View all journal entries
guestctl systemd-journal vm.qcow2 --errors            # Show only errors
guestctl systemd-journal vm.qcow2 --warnings          # Show only warnings
guestctl systemd-journal vm.qcow2 --stats             # Display statistics
guestctl systemd-journal vm.qcow2 --unit sshd.service  # Filter by unit
guestctl systemd-journal vm.qcow2 --priority 3 --limit 50  # Error level, max 50

# Systemd service analysis
guestctl systemd-services vm.qcow2                        # List all services
guestctl systemd-services vm.qcow2 --failed               # Show only failed services
guestctl systemd-services vm.qcow2 --service nginx.service  # Dependency tree
guestctl systemd-services vm.qcow2 --service sshd.service --diagram  # Mermaid diagram
guestctl systemd-services vm.qcow2 --output json         # JSON output

# Systemd boot performance analysis
guestctl systemd-boot vm.qcow2                      # Show boot timing and slowest services
guestctl systemd-boot vm.qcow2 --recommendations    # Get optimization recommendations
guestctl systemd-boot vm.qcow2 --summary            # Boot metrics summary
guestctl systemd-boot vm.qcow2 --timeline > boot.md  # Generate boot timeline Mermaid diagram
guestctl systemd-boot vm.qcow2 --top 20             # Show top 20 slowest services

# Use caching for faster repeated inspections (enabled by default)
guestctl inspect vm.qcow2  # First run: ~30s, subsequent: <0.5s with binary cache
guestctl inspect vm.qcow2 --no-cache  # Disable cache
guestctl inspect vm.qcow2 --cache-refresh  # Force refresh cache

# Batch inspect multiple VMs in parallel (4-8x speedup)
guestctl inspect-batch *.qcow2 --parallel 4

# Cache management
guestctl cache-stats
guestctl cache-clear

Available Commands:

• inspect - Comprehensive VM inspection with profiles
• interactive - Full-featured REPL shell with 97+ commands for VM management
• diff - Compare two disk images
• compare - Compare multiple VMs against baseline
• inspect-batch - Parallel batch inspection
• systemd-journal - Analyze systemd journal logs
• systemd-services - Inspect systemd services and dependencies
• systemd-boot - Analyze boot performance and optimization
• list - List files in disk image
• extract - Extract files from disk image
• execute - Execute commands in guest
• backup - Create tar backup from guest
• convert - Convert disk image formats
• create - Create new disk image
• check - Filesystem check
• usage - Disk usage statistics
• detect - Detect disk image format
• info - Disk image information
• cache-stats - View cache statistics
• cache-clear - Clear inspection cache
• version - Show version information

Full Documentation: docs/user-guides/cli-guide.md

---

Basic Usage

Library (API)

use guestctl::guestfs::Guestfs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create handle
    let mut g = Guestfs::new()?;

    // Add disk image (read-only)
    g.add_drive_ro("/path/to/disk.qcow2")?;

    // Launch (analyzes disk)
    g.launch()?;

    // Inspect OS
    let roots = g.inspect_os()?;
    for root in roots {
        println!("Found OS root: {}", root);
        println!("  Type: {}", g.inspect_get_type(&root)?);
        println!("  Distro: {}", g.inspect_get_distro(&root)?);
        println!("  Version: {}.{}",
            g.inspect_get_major_version(&root)?,
            g.inspect_get_minor_version(&root)?);
        println!("  Hostname: {}", g.inspect_get_hostname(&root)?);
    }

    // List partitions
    let partitions = g.list_partitions()?;
    for part in partitions {
        println!("Partition: {}", part);
        println!("  Filesystem: {}", g.vfs_type(&part)?);
        println!("  Label: {}", g.vfs_label(&part).unwrap_or_default());
    }

    // Cleanup
    g.shutdown()?;

    Ok(())
}

Ergonomic Rust API (Recommended)

GuestCtl provides modern Rust patterns for better type safety and ergonomics:

use guestctl::guestfs::{Guestfs, FilesystemType, OsType, Distro};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Builder pattern for configuration
    let mut g = Guestfs::builder()
        .add_drive_ro("/path/to/disk.qcow2")
        .verbose(true)
        .build_and_launch()?;

    // Type-safe filesystem creation
    g.mkfs("/dev/sda1")
        .ext4()              // Type-safe enum, not string!
        .label("rootfs")
        .blocksize(4096)
        .create()?;

    // Type-safe OS detection with pattern matching
    for root in g.inspect_os()? {
        let os_type = OsType::from_str(&g.inspect_get_type(&root)?);

        match os_type {
            OsType::Linux => {
                let distro = Distro::from_str(&g.inspect_get_distro(&root)?);

                // Smart methods on enums
                if let Some(pkg_mgr) = distro.package_manager() {
                    println!("Package manager: {}", pkg_mgr);  // "deb", "rpm", "pacman", etc.
                }

                // Exhaustive pattern matching
                match distro {
                    Distro::Ubuntu | Distro::Debian => println!("Debian-based"),
                    Distro::Fedora | Distro::Rhel => println!("RPM-based"),
                    Distro::Archlinux => println!("Arch Linux"),
                    _ => println!("Other Linux"),
                }
            }
            OsType::Windows => println!("Windows detected"),
            _ => println!("Other OS"),
        }
    }

    g.shutdown()?;
    Ok(())
}

See docs/api/ergonomic-design.md and docs/api/migration-guide.md for details.

Python Bindings

GuestCtl provides native Python bindings via PyO3 for seamless integration with Python workflows.

Installation:

# Quick build (recommended)
./build_python.sh

# Or manual build
python3 -m venv .venv
source .venv/bin/activate
pip install maturin
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 maturin develop --features python-bindings

# Verify installation
python3 -c "import guestctl; print(guestctl.__version__)"

Basic Example:

from guestctl import Guestfs

# Create handle and configure
g = Guestfs()
g.add_drive_ro("/path/to/disk.qcow2")
g.launch()

# Inspect operating system
roots = g.inspect_os()
for root in roots:
    print(f"OS Type: {g.inspect_get_type(root)}")
    print(f"Distro: {g.inspect_get_distro(root)}")
    print(f"Version: {g.inspect_get_major_version(root)}.{g.inspect_get_minor_version(root)}")
    print(f"Hostname: {g.inspect_get_hostname(root)}")

# Mount and read files
mountpoints = g.inspect_get_mountpoints(root)
for mount_path, device in sorted(mountpoints, key=lambda x: len(x[0])):
    g.mount_ro(device, mount_path)

if g.is_file("/etc/hostname"):
    content = g.read_file("/etc/hostname")
    print(f"Hostname from file: {content.decode('utf-8').strip()}")

# List installed packages
apps = g.inspect_list_applications(root)
print(f"Total packages: {len(apps)}")

# Cleanup
g.umount_all()
g.shutdown()

More Examples:

• examples/python/comprehensive_example.py - Complete example demonstrating all features
• examples/python/extract_files.py - File extraction from disk images
• examples/python/archive_example.py - Archive operations (tar, tar.gz)
• examples/python/basic_inspection.py - OS detection and inspection
• examples/python/list_filesystems.py - Enumerate devices and partitions
• examples/python/mount_and_explore.py - Mount and read files
• examples/python/package_inspection.py - List installed packages
• examples/python/create_disk.py - Create new disk images
• examples/python/test_bindings.py - Comprehensive test suite

Full Documentation:

• docs/user-guides/python-bindings.md - Comprehensive Python guide
• docs/api/python-reference.md - Complete API reference with 100+ methods

Python API Coverage:

• 58 Guestfs methods covering OS inspection, file operations, device management, LVM, archives, and more
• 3 DiskConverter methods for format conversion and detection
• Comprehensive error handling with Python exceptions
• Full type conversion between Rust and Python types

Project Structure

guestctl/
├── Cargo.toml
├── README.md
├── ARCHITECTURE.md                    # Architecture documentation
├── GUESTFS_IMPLEMENTATION_STATUS.md   # Implementation status (578 functions)
├── src/
│   ├── lib.rs                         # Library entry point
│   ├── core/                          # Core utilities
│   │   ├── error.rs                   # Error types
│   │   ├── retry.rs                   # Retry logic
│   │   └── types.rs                   # Common types
│   ├── disk/                          # Disk operations (Pure Rust)
│   │   ├── reader.rs                  # Disk image reader (magic byte detection)
│   │   ├── partition.rs               # MBR/GPT parser
│   │   └── filesystem.rs              # Filesystem detection (ext4, NTFS, etc.)
│   ├── guestfs/                       # GuestFS-compatible API (486 functions)
│   │   ├── handle.rs                  # Main handle (new/launch/shutdown)
│   │   ├── inspect.rs                 # OS inspection (12 functions)
│   │   ├── device.rs                  # Device operations (9 functions)
│   │   ├── partition.rs               # Partition operations (6 functions)
│   │   ├── mount.rs                   # Mount operations (11 functions)
│   │   ├── file_ops.rs                # File operations (35+ functions)
│   │   ├── lvm.rs                     # LVM operations (9 functions)
│   │   ├── command.rs                 # Command execution (4 functions)
│   │   ├── archive.rs                 # Archive operations (7 functions)
│   │   ├── luks.rs                    # LUKS encryption (6 functions)
│   │   ├── checksum.rs                # Checksums and file content (9 functions)
│   │   ├── filesystem.rs              # Filesystem operations (8 functions)
│   │   ├── utils.rs                   # File utilities (11 functions)
│   │   ├── network.rs                 # Network configuration (7 functions)
│   │   ├── package.rs                 # Package management (5 functions)
│   │   ├── system.rs                  # System configuration (13 functions)
│   │   ├── security.rs                # Security operations (10 functions)
│   │   ├── boot.rs                    # Boot configuration (10 functions)
│   │   ├── disk_ops.rs                # Advanced disk operations (12 functions)
│   │   ├── service.rs                 # Service management (8 functions)
│   │   ├── ssh.rs                     # SSH operations (10 functions)
│   │   ├── part_mgmt.rs               # Partition management (9 functions)
│   │   ├── augeas.rs                  # Configuration editing (11 functions)
│   │   ├── resize.rs                  # Filesystem resize (7 functions)
│   │   ├── windows.rs                 # Windows operations (12 functions)
│   │   ├── btrfs.rs                   # Btrfs operations (12 functions)
│   │   ├── metadata.rs                # File metadata (17 functions)
│   │   ├── misc.rs                    # Miscellaneous utilities (22 functions)
│   │   ├── xfs.rs                     # XFS operations (4 functions)
│   │   ├── iso.rs                     # ISO operations (4 functions)
│   │   ├── transfer.rs                # Advanced file transfer (8 functions)
│   │   ├── disk_mgmt.rs               # Disk image management (10 functions)
│   │   ├── internal.rs                # Internal operations (16 functions)
│   │   ├── ntfs.rs                    # NTFS operations (5 functions)
│   │   ├── ext_ops.rs                 # Extended filesystem ops (11 functions)
│   │   ├── glob_ops.rs                # Glob operations (7 functions)
│   │   ├── node_ops.rs                # Node operations (10 functions)
│   │   ├── md_ops.rs                  # MD/RAID operations (5 functions)
│   │   ├── selinux_ops.rs             # SELinux extended (4 functions)
│   │   ├── cap_ops.rs                 # Capabilities (4 functions)
│   │   ├── acl_ops.rs                 # ACL operations (8 functions)
│   │   ├── hivex_ops.rs               # Hivex operations (16 functions)
│   │   ├── rsync_ops.rs               # Rsync operations (2 functions)
│   │   ├── syslinux_ops.rs            # Syslinux operations (2 functions)
│   │   ├── journal_ops.rs             # Journal operations (11 functions)
│   │   ├── inotify_ops.rs             # Inotify operations (6 functions)
│   │   ├── squashfs_ops.rs            # SquashFS operations (3 functions)
│   │   ├── yara_ops.rs                # YARA operations (4 functions)
│   │   ├── tsk_ops.rs                 # TSK operations (4 functions)
│   │   ├── zfs_ops.rs                 # ZFS operations (10 functions)
│   │   ├── ldm_ops.rs                 # LDM operations (8 functions)
│   │   ├── mpath_ops.rs               # Multipath operations (5 functions)
│   │   ├── grub_ops.rs                # GRUB operations (7 functions)
│   │   ├── f2fs_ops.rs                # F2FS operations (4 functions)
│   │   ├── bcache_ops.rs              # Bcache operations (5 functions)
│   │   ├── dosfs_ops.rs               # DOSFS operations (5 functions)
│   │   ├── cpio_ops.rs                # CPIO operations (3 functions)
│   │   ├── nilfs_ops.rs               # NILFS operations (4 functions)
│   │   ├── ufs_ops.rs                 # UFS operations (3 functions)
│   │   ├── inspect_enhanced.rs        # Enhanced inspection with profiles
│   │   └── windows_registry.rs        # Windows registry parsing
│   ├── python.rs                      # Python bindings (PyO3, 100+ methods)
│   ├── converters/                    # Disk format converters
│   │   └── disk_converter.rs          # qemu-img wrapper
│   └── cli/                           # CLI implementation
│       ├── commands.rs                # CLI commands
│       ├── profiles/                  # Inspection profiles
│       ├── exporters/                 # HTML/Markdown exporters
│       ├── formatters.rs              # Output formatters
│       ├── templates/                 # Askama templates
│       ├── diff.rs                    # VM comparison
│       └── cache.rs                   # Result caching
├── examples/                          # Example programs
│   ├── rust/
│   │   ├── inspect_disk.rs
│   │   └── list_partitions.rs
│   └── python/                        # Python examples
│       ├── test_bindings.py           # Comprehensive test suite
│       ├── comprehensive_example.py   # Full-featured example
│       ├── archive_example.py         # Archive operations
│       ├── extract_files.py           # File extraction
│       └── README.md                  # Python examples guide
├── docs/                              # Documentation (organized)
│   ├── README.md                      # Documentation index
│   ├── guides/                        # User guides
│   ├── api/                           # API documentation
│   ├── architecture/                  # Architecture docs
│   ├── development/                   # Contributor docs
│   ├── testing/                       # Testing docs
│   ├── status/                        # Implementation status
│   └── archive/                       # Historical docs
├── pyproject.toml                     # Python package config
├── build_python.sh                    # Python build script
└── tests/                             # Integration tests

Documentation

📚 Complete documentation is organized in docs/

Quick Links:

• 🚀 Quick Start - Get started in minutes
• 📖 CLI Guide - Command-line usage
• 🔧 Systemd Analysis - Deep systemd inspection guide
• 🐍 Python Guide - Python API guide
• 🔍 API Reference - Complete Python API
• 🏗️ Architecture - System architecture
• ⚡ Performance Baseline - Performance metrics and optimization guide
• 🚀 Enhancement Roadmap - Future plans

See docs/README.md for complete documentation index.

Architecture

See docs/architecture/overview.md for detailed architecture documentation.

Core Modules

guestfs - GuestFS-Compatible API (115 functions)

• handle.rs - Main GuestFS handle (lifecycle management)
• inspect.rs - OS inspection (12 functions, fully working)
• device.rs - Device operations (9 functions, fully working)
• partition.rs - Partition operations (6 functions, fully working)
• mount.rs - Mount operations (11 functions, API-defined, needs NBD)
• file_ops.rs - File operations (35+ functions, API-defined, needs FS parser or NBD)
• lvm.rs - LVM operations (5 functions, API-defined)
• command.rs - Command execution (4 functions, API-defined)
• archive.rs - Archive operations (8 functions, API-defined)

disk - Pure Rust Disk Operations

• reader.rs - Disk image reader with format detection via magic bytes
• partition.rs - MBR and GPT partition table parser
• filesystem.rs - Filesystem detection (ext4, NTFS, XFS, Btrfs, FAT32)

core - Core Utilities

• error.rs - Error types using thiserror
• retry.rs - Exponential backoff retry logic
• types.rs - Common types (DiskFormat, GuestType, etc.)

Implementation Status

Category	Functions	Status
Total APIs	115	35 working, 80 API-defined
Lifecycle	8	✅ Fully working
Inspection	12	✅ Fully working
Device Ops	9	✅ Fully working
Partition Ops	6	✅ Fully working
Mount Ops	11	⚠️ API-only (needs NBD)
File Ops	35+	⚠️ API-only (needs FS parser)
LVM	5	⚠️ API-only
Commands	4	⚠️ API-only
Archives	8	⚠️ API-only

See GUESTFS_IMPLEMENTATION_STATUS.md for complete function implementation status.

Design Principles

1. Pure Rust - No C dependencies (except qemu-img tool)
2. Memory Safety - Leveraging Rust's ownership system
3. Zero-cost Abstractions - High-level APIs with no runtime overhead
4. Clean API Design - Intuitive function signatures and error handling
5. Modularity - Clean separation of concerns
6. Testability - Comprehensive test coverage (33 tests passing)

Examples

See the examples/ directory for complete examples:

• convert_disk.rs - Convert disk image formats
• detect_format.rs - Detect and inspect disk images
• retry_example.rs - Using retry logic with exponential backoff

Run examples with:

cargo run --example convert_disk
cargo run --example detect_format

Implementation Details

Pure Rust: No C dependencies, memory safe

Working Features:

• ✅ Disk format detection and conversion
• ✅ Partition table parsing (MBR, GPT)
• ✅ Filesystem detection and mounting
• ✅ OS inspection (Linux and Windows)
• ✅ LVM support
• ✅ Windows registry parsing

VM Migration Support

guestctl provides comprehensive VM migration capabilities for cross-platform migrations:

Universal fstab/crypttab Rewriter

Modify disk images to work in different environments:

use guestctl::guestfs::Guestfs;

let mut g = Guestfs::new()?;
g.add_drive("/path/to/disk.qcow2")?;
g.launch()?;

// Rewrite fstab for new environment
g.rewrite_fstab(root, old_device_mapping, new_device_mapping)?;

// Rewrite crypttab for encrypted volumes
g.rewrite_crypttab(root, luks_device_mapping)?;

Migration Features

• Device Path Translation - Automatically translate device paths (e.g., /dev/sda → /dev/vda)
• LUKS Support - Rewrite encrypted volume configurations
• Cross-Platform - Migrate between different hypervisors (Hyper-V → KVM, VMware → KVM)
• Network Configuration - Update network interface names and configurations
• Boot Configuration - Modify bootloader settings for new environment

Use Cases

• Hyper-V to KVM migration (via hyper2kvm)
• VMware to KVM migration
• Physical to virtual (P2V) conversions
• Cloud migrations (AWS → Azure, etc.)

Integration with hyper2kvm

guestctl is designed to work seamlessly with hyper2kvm:

use guestctl::guestfs::Guestfs;

// Simple, intuitive API
let mut g = Guestfs::new()?;
g.add_drive_ro("/path/to/disk.qcow2")?;
g.launch()?;

// Inspect VM
let roots = g.inspect_os()?;
for root in &roots {
    println!("OS: {}", g.inspect_get_distro(root)?);
    println!("Version: {}.{}",
        g.inspect_get_major_version(root)?,
        g.inspect_get_minor_version(root)?);
}

Benefits for hyper2kvm and VM migration:

• ✅ No root required for read-only operations
• ✅ Faster - Pure Rust implementation
• ✅ Simpler - No C dependencies
• ✅ Safer - Rust memory safety
• ✅ VM Migration - Universal fstab/crypttab rewriter
• ✅ Windows Support - Full registry parsing for version detection
• ✅ Comprehensive - 578 functions, 97.4% implementation coverage

Dependencies

System Dependencies

• qemu-img - Disk image manipulation (QEMU tools) - Optional, for format conversion

# Fedora/RHEL
sudo dnf install qemu-img

# Ubuntu/Debian
sudo apt install qemu-utils

# Arch Linux
sudo pacman -S qemu

Note: guestctl is a pure Rust implementation with no C library dependencies!

Rust Dependencies

See Cargo.toml for complete list:

• thiserror - Custom error types
• byteorder - Binary parsing
• memmap2 - Memory-mapped I/O
• regex - Pattern matching
• pyo3 (optional) - Python bindings
• serde / serde_json - Serialization

Development

Building

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- convert --source test.vmdk --output test.qcow2

Running Tests

Rust Tests:

# Unit tests
cargo test

# Integration tests
cargo test --test '*'

# With coverage
cargo tarpaulin --out Html

Python Tests:

# Install pytest (if not already installed)
pip install pytest

# Run Python bindings tests
pytest tests/test_python_bindings.py -v

# Run with test disk image
export GUESTKIT_TEST_IMAGE=/path/to/test.qcow2
pytest tests/test_python_bindings.py -v

Comprehensive Testing:

# Run all tests (Rust + Python)
cargo test --all-features
pytest tests/test_python_bindings.py -v

# Example Python integration test
cd examples/python
sudo python3 test_bindings.py /path/to/disk.img

Note on Permissions: Some tests require root access for mounting disk images.

See CONTRIBUTING.md for complete testing documentation.

Code Quality

# Format code
cargo fmt

# Lint
cargo clippy

# Check documentation
cargo doc --no-deps --open

Cargo Features

guestctl uses Cargo features for optional functionality:

• disk-ops (default) - Disk operation utilities
• guest-inspect (default) - Guest OS inspection
• python-bindings (optional) - PyO3 Python bindings
• ai (optional) - AI-powered diagnostics with OpenAI GPT-4o integration

[dependencies]
guestctl = { version = "0.3", features = ["guest-inspect"] }

# With Python bindings
guestctl = { version = "0.3", features = ["python-bindings"] }

# With AI diagnostics
guestctl = { version = "0.3", features = ["ai"] }

Build with optional features:

# Python bindings
cargo build --features python-bindings

# AI diagnostics (requires OPENAI_API_KEY environment variable)
cargo build --features ai

# All features
cargo build --all-features

Roadmap

See GUESTFS_IMPLEMENTATION_STATUS.md for detailed implementation status.

Phase 0: Foundation (✅ COMPLETE)

• Pure Rust architecture (no C dependencies)
• Disk format detection (QCOW2, VMDK, RAW)
• Partition table parsing (MBR, GPT)
• Filesystem detection (ext4, NTFS, XFS, Btrfs, FAT32)
• Comprehensive API structure (578 functions, 97.4% implemented)
• OS inspection (30+ functions fully working)
• Device operations (20+ functions fully working)
• Partition operations (15+ functions fully working)
• Python bindings foundation (PyO3)

Phase 1: Essential Operations (🔄 PLANNED - 3 weeks)

Implement for 90% hyper2kvm compatibility:

• NBD mounting - qemu-nbd integration for filesystem access
• Command execution (4 functions) - command, sh, sh_lines
• Archive operations (8 functions) - tar_in, tar_out, tgz_in, tgz_out
• File operations (10 functions) - cp, mv, download, upload, grep, find
• LUKS operations (6 functions) - luks_open, luks_close, luks_format
• LVM activation (4 functions) - vg_activate_all, lvcreate, lvremove

Total: 30+ critical functions

Phase 2: Filesystem Operations (📅 FUTURE - 2 weeks)

• Filesystem creation (mkfs, mke2fs, mkfs_btrfs)
• Filesystem repair (fsck, e2fsck, ntfsfix, xfs_repair)
• Extended attributes (getxattr, setxattr)
• Resize operations (resize2fs, ntfsresize)

Phase 3: Advanced Features (📅 FUTURE - 4 weeks)

• Augeas (config file editing)
• Windows registry (Hivex operations)
• Partition management (add/delete/resize)
• SELinux relabeling

Phase 4: Specialized (📅 OPTIONAL)

• Btrfs advanced features (subvolumes, snapshots)
• ZFS support
• YARA malware scanning
• File recovery (TSK)

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Write tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

License

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

See LICENSE for full license text.

Acknowledgments

• hyper2kvm - Primary use case and integration target
• QEMU - Disk format conversion tools
• Rust Community - For excellent crates and tooling

Support

• GitHub Issues: Report bugs
• Documentation: API docs
• Examples: See examples/ directory

Related Projects

• hyper2kvm - Production-grade VM migration toolkit
• hypersdk - High-performance hypervisor SDK

---

Made with ❤️ for reliable VM operations