guestctl

Crates.io	guestctl
lib.rs	guestctl
version	0.3.0
created_at	2026-01-24 21:54:20.884178+00
updated_at	2026-01-24 21:54:20.884178+00
description	Guest VM toolkit for disk inspection and manipulation
homepage
repository	https://github.com/ssahani/guestctl
max_upload_size
id	2067581
size	2,570,038

Susant Sahani (ssahani)

documentation

README

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.

🎨 New: Beautiful terminal output with emojis and color coding makes VM inspection actually enjoyable!

🚀 Quick Start

Installation

Python Package (Recommended):

pip 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:

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

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

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

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

Interactive mode:

guestctl interactive vm.qcow2

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}")

Features

🦀 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 Format Support - QCOW2, VMDK, RAW detection via magic bytes
📊 Partition Tables - MBR and GPT parsing, partition creation/deletion/resizing
🗂️ Filesystem Operations - Mount/unmount, create (mkfs), check (fsck), tune, trim, resize
🔎 OS Inspection - Detect OS type, distro, version, architecture, hostname
📦 Package Management - List and inspect dpkg/rpm packages
🌐 Network Configuration - Read hostname, DNS, interface config
👤 System Configuration - Timezone, locale, users, groups, systemd units
🔐 Encryption Support - LUKS encrypted volumes
📚 LVM Support - Logical volume management
🗜️ Archive Operations - tar, tgz, cpio creation and extraction
🔑 Checksums - MD5, SHA1, SHA256, SHA384, SHA512
🛡️ Security Operations - SELinux, AppArmor, capabilities, ACLs
🥾 Boot Configuration - Bootloader detection, kernel management, UEFI support
💾 Advanced Disk Operations - Swap management, hexdump, strings, secure scrubbing
🔧 Service Management - systemd/sysvinit service detection, cron jobs
🔑 SSH Operations - SSH key management, certificates, authorized_keys
⚙️ Configuration Editing - Augeas-based config file editing
🪟 Windows Support - Registry hive access, Windows-specific inspection
🌳 Btrfs Advanced - Subvolumes, snapshots, balance, scrub operations
📊 File Metadata - Detailed stat operations, inode info, permissions
🛠️ Utility Functions - Feature detection, settings management, debug tools
🔷 XFS Support - XFS repair, administration, info, database operations
💿 ISO Operations - ISO creation, inspection, mounting
📤 Advanced Transfer - Offset-based downloads/uploads, device copying
💾 Disk Image Management - Create, resize, convert, sparsify, snapshot disk images
🔧 Internal API - State management, environment parsing, debug functions
💿 NTFS Operations - ntfsclone, ntfsfix, label management
🔷 Extended Filesystem - ext2/3/4 UUID, label, dump/restore operations
🔍 Glob Operations - Pattern matching, ls0, find0, case-insensitive search
🔧 Node Operations - mknod, mkfifo, mktemp, truncate, utimens
💾 MD/RAID - Software RAID creation, management, inspection
🛡️ SELinux Extended - SELinux inspection, restorecon
🔐 Capabilities - Linux capabilities management
🔒 ACL Operations - POSIX ACL management
🪟 Hivex - Windows registry hive manipulation (16 functions)
🔄 Rsync - rsync-based file synchronization
🥾 Syslinux - syslinux/extlinux bootloader installation
📔 Journal - systemd journal reading, export, verification
👁️ Inotify - file monitoring with inotify
🗜️ SquashFS - SquashFS creation and extraction
🦠 YARA - malware scanning with YARA rules
🔬 TSK - forensics with The Sleuth Kit (deleted file recovery)
💽 ZFS - ZFS filesystem management (10 functions)
🪟 LDM - Windows dynamic disk support (8 functions)
🔀 Multipath - multipath device management
🥾 GRUB - GRUB bootloader installation and configuration
⚡ F2FS - Flash-Friendly File System support
💾 Bcache - block cache management
📁 DOSFS - FAT12/16/32 filesystem tools
📦 CPIO - CPIO archive format support
🗂️ NILFS - log-structured filesystem support
🔧 UFS - Unix File System support
🌲 ReiserFS - ReiserFS filesystem management
📝 JFS - Journaled File System support
🔹 Minix - Minix filesystem support
🩺 SMART - disk health monitoring with smartctl
🧹 SysPrep - VM preparation operations (remove unique data)
🛠️ Utilities - version info, QEMU detection, umask, device stats
🔧 Block Device Ops - setro/setrw, flush, reread partition table, block/sector size
📝 Base64 - Base64 encoding/decoding for file content
🔄 Extended Swap - swap label/UUID management operations
💾 DD Operations - dd-style copy, zero device operations
📍 Positional I/O - pread/pwrite with offset support
🔍 Virt Tools - virt-inspector, virt-convert, virt-resize, virt-sparsify info
🗜️ Compression - gzip, bzip2, xz compression/decompression for files and devices
🏷️ Label Operations - generic filesystem label/UUID management (auto-detect fs type)
🔄 Sync Operations - sync, drop_caches, flush for data consistency
🔖 Attributes - extended attributes (xattr) and file flags management
🧩 Partition Types - GPT type GUID, attributes, expand partition tables
🔗 Link Management - symbolic and hard link operations
🐍 Python Bindings - PyO3-based native Python bindings
⚡ Retry Logic - Built-in exponential backoff for reliable operations
🔌 Extensible - Modular architecture for easy extension

Advanced CLI Features (guestctl)

🎨 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 (active), red (issues), 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 - HTML and Markdown report generation for documentation
⚡ Result Caching - SHA256-based caching for instant repeated inspections (60x speedup)
🚀 Batch Processing - Multi-threaded parallel inspection of multiple disk images

Quick Start

Installation

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

# From source
git clone https://github.com/ssahani/guestctl
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
guestctl inspect vm.qcow2 --export html --export-output report.html

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

# Use caching for faster repeated inspections
guestctl inspect vm.qcow2 --cache  # First run: ~30s, subsequent: <0.5s

# Batch inspect multiple VMs in parallel
guestctl inspect-batch *.qcow2 --parallel 4 --cache

# Cache management
guestctl cache-stats
guestctl cache-clear

Available Commands:

inspect - Comprehensive VM inspection with profiles
diff - Compare two disk images
compare - Compare multiple VMs against baseline
inspect-batch - Parallel batch inspection
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/CLI_GUIDE.md

Basic Usage

Library (GuestFS 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/ERGONOMIC_API.md and docs/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/guides/PYTHON_BINDINGS.md - Comprehensive Python guide
docs/api/PYTHON_API_REFERENCE.md - Complete API reference with 100+ methods
docs/status/PYTHON_BINDINGS_STATUS.md - Implementation status and build instructions

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
🐍 Python Guide - Python API guide
🔍 API Reference - Complete Python API
🏗️ Architecture - System architecture
🧪 Testing Guide - How to test
📊 Project Status - Implementation status
🚀 Enhancement Roadmap - Future plans

See docs/README.md for complete documentation index.

Architecture

See docs/architecture/ARCHITECTURE.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

Pure Rust - No C dependencies (except qemu-img tool)
Memory Safety - Leveraging Rust's ownership system
Zero-cost Abstractions - High-level APIs with no runtime overhead
Clean API Design - Intuitive function signatures and error handling
Modularity - Clean separation of concerns
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

API Coverage

Statistics

Metric	Count	Percentage
LibGuestFS functions	733	100%
GuestCtl APIs defined	364	49.7%
Fully working	349	47.6%
API-only (needs impl)	15	2.0%

Comparison with LibGuestFS

See LIBGUESTFS_COMPARISON.md for:

Complete function-by-function comparison
What's implemented vs what's missing
Implementation phases and timeline
Recommendations for full compatibility

Implementation Strategy

Current: Pure Rust implementation without C dependencies

Working:

✅ Disk format detection (magic bytes)
✅ Partition table parsing (MBR, GPT)
✅ Filesystem detection (superblock analysis)
✅ OS inspection (35 functions)

Planned (Phase 1):

🔄 NBD mounting (qemu-nbd integration)
🔄 File I/O via NBD mount
🔄 Command execution via chroot
🔄 Archive operations (tar, tgz)

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:

✅ No root required for read-only operations
✅ Faster - Pure Rust implementation
✅ Simpler - No C dependencies
✅ Safer - Rust memory safety
✅ 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 docs/testing/TESTING.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

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

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

Build with Python bindings:

cargo build --features python-bindings

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:

Fork the repository
Create a feature branch
Write tests for new functionality
Ensure all tests pass
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

Commit count: 0

guestctl

documentation

README

guestctl

🚀 Quick Start

Installation

Usage

Features

Advanced CLI Features (guestctl)

Quick Start

Installation

CLI Tool

Basic Usage

Library (GuestFS API)

Ergonomic Rust API (Recommended)

Python Bindings

Project Structure

Documentation

Architecture

Core Modules

guestfs - GuestFS-Compatible API (115 functions)

disk - Pure Rust Disk Operations

core - Core Utilities

Implementation Status

Design Principles

Examples

API Coverage

Statistics

Comparison with LibGuestFS

Implementation Strategy

Integration with hyper2kvm

Dependencies

System Dependencies

Rust Dependencies

Development

Building

Running Tests

Code Quality

Cargo Features

Roadmap

Phase 0: Foundation (✅ COMPLETE)

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

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

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

Phase 4: Specialized (📅 OPTIONAL)

Contributing

License

Acknowledgments

Support

Related Projects

cargo fmt

`guestfs` - GuestFS-Compatible API (115 functions)

`disk` - Pure Rust Disk Operations

`core` - Core Utilities