Metadata-Version: 2.4
Name: guestctl
Version: 0.3.1
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: System :: Filesystems
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
License-File: LICENSE
Summary: Pure Rust VM disk toolkit with beautiful output, Windows registry parsing, and VM migration support - Python bindings
Keywords: vm,disk,qcow2,vmdk,inspection,guestfs
Author-email: Susant Sahani <ssahani@vmware.com>
License: LGPL-3.0-or-later
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/ssahani/guestctl/issues
Project-URL: Changelog, https://github.com/ssahani/guestctl/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/ssahani/guestctl/tree/main/docs
Project-URL: Homepage, https://github.com/ssahani/guestctl
Project-URL: Repository, https://github.com/ssahani/guestctl

# 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](https://github.com/ssahani/hyper2kvm) and VM migration workflows.

[![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0)
[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org/)
[![Crates.io](https://img.shields.io/crates/v/guestctl.svg)](https://crates.io/crates/guestctl)
[![PyPI](https://img.shields.io/pypi/v/guestctl.svg)](https://pypi.org/project/guestctl/)
[![Downloads](https://pepy.tech/badge/guestctl)](https://pepy.tech/project/guestctl)

**✨ 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):**
```bash
pip install guestctl
```

**Rust Crate (Recommended for Rust developers):**
```bash
cargo install guestctl
```

**From Source:**
```bash
git clone https://github.com/ssahani/guestkit
cd guestkit
cargo build --release
```

### Usage

**Inspect a VM disk:**
```bash
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:**
```bash
guestctl interactive vm.qcow2
```

**AI-Powered Diagnostics (optional):**
```bash
# 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:

```bash
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](COMMANDS_SUMMARY.md) for complete command reference.

**Python API:**
```python
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

```bash
# 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:
```bash
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

```bash
# 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):**
```bash
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:**
```bash
# 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:**

```bash
# 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`](docs/user-guides/cli-guide.md)

---

### Basic Usage

#### Library (API)

```rust
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:

```rust
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`](docs/api/ergonomic-design.md) and [`docs/api/migration-guide.md`](docs/api/migration-guide.md) for details.

#### Python Bindings

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

**Installation:**
```bash
# 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:**
```python
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`](examples/python/comprehensive_example.py) - Complete example demonstrating all features
- [`examples/python/extract_files.py`](examples/python/extract_files.py) - File extraction from disk images
- [`examples/python/archive_example.py`](examples/python/archive_example.py) - Archive operations (tar, tar.gz)
- [`examples/python/basic_inspection.py`](examples/python/basic_inspection.py) - OS detection and inspection
- [`examples/python/list_filesystems.py`](examples/python/list_filesystems.py) - Enumerate devices and partitions
- [`examples/python/mount_and_explore.py`](examples/python/mount_and_explore.py) - Mount and read files
- [`examples/python/package_inspection.py`](examples/python/package_inspection.py) - List installed packages
- [`examples/python/create_disk.py`](examples/python/create_disk.py) - Create new disk images
- [`examples/python/test_bindings.py`](examples/python/test_bindings.py) - Comprehensive test suite

**Full Documentation:**
- [`docs/user-guides/python-bindings.md`](docs/user-guides/python-bindings.md) - Comprehensive Python guide
- [`docs/api/python-reference.md`](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/`](docs/)**

**Quick Links:**
- 🚀 **[Quick Start](docs/user-guides/getting-started.md)** - Get started in minutes
- 📖 **[CLI Guide](docs/user-guides/cli-guide.md)** - Command-line usage
- 🔧 **[Systemd Analysis](docs/systemd-analysis.md)** - Deep systemd inspection guide
- 🐍 **[Python Guide](docs/user-guides/python-bindings.md)** - Python API guide
- 🔍 **[API Reference](docs/api/python-reference.md)** - Complete Python API
- 🏗️ **[Architecture](docs/architecture/overview.md)** - System architecture
- ⚡ **[Performance Baseline](docs/development/performance-baseline.md)** - Performance metrics and optimization guide
- 🚀 **[Enhancement Roadmap](docs/development/enhancement-roadmap.md)** - Future plans

See **[docs/README.md](docs/README.md)** for complete documentation index.

## Architecture

See [docs/architecture/overview.md](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](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/`](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:

```bash
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:

```rust
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](https://github.com/ssahani/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](https://github.com/ssahani/hyper2kvm):

```rust
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

```bash
# 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`](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

```bash
# 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:**
```bash
# Unit tests
cargo test

# Integration tests
cargo test --test '*'

# With coverage
cargo tarpaulin --out Html
```

**Python Tests:**
```bash
# 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:**
```bash
# 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](CONTRIBUTING.md) for complete testing documentation.

### Code Quality

```bash
# 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

```toml
[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:

```bash
# 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](GUESTFS_IMPLEMENTATION_STATUS.md) for detailed implementation status.

### Phase 0: Foundation (✅ COMPLETE)
- [x] Pure Rust architecture (no C dependencies)
- [x] Disk format detection (QCOW2, VMDK, RAW)
- [x] Partition table parsing (MBR, GPT)
- [x] Filesystem detection (ext4, NTFS, XFS, Btrfs, FAT32)
- [x] Comprehensive API structure (578 functions, 97.4% implemented)
- [x] OS inspection (30+ functions fully working)
- [x] Device operations (20+ functions fully working)
- [x] Partition operations (15+ functions fully working)
- [x] 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](CONTRIBUTING.md) for detailed guidelines.

## License

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

See [LICENSE](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](https://github.com/ssahani/guestkit/issues)
- **Documentation**: [API docs](https://docs.rs/guestctl)
- **Examples**: See [`examples/`](examples/) directory

## Related Projects

- **[hyper2kvm](https://github.com/ssahani/hyper2kvm)** - Production-grade VM migration toolkit
- **[hypersdk](https://github.com/ssahani/hypersdk)** - High-performance hypervisor SDK

---

Made with ❤️ for reliable VM operations

