easyqemu/PROJECT.md

EasyQEMU Project Structure

easyqemu/
│
├── easyqemu                 # Main executable script
├── install.sh               # Installation script
├── test.sh                  # Automated test suite
├── EXAMPLES.sh              # Usage examples with colored output
│
├── README.md                # Comprehensive documentation
├── QUICKSTART.md            # Quick start guide
├── CONTRIBUTING.md          # Contribution guidelines
├── CHANGELOG.md             # Version history and changes
├── LICENSE                  # MIT License
│
├── .easyqemu.conf          # Default configuration template
└── .gitignore              # Git ignore rules

Runtime Directory Structure (~/.easyqemu/):
├── vms/                    # VM runtime data
├── volumes/                # Disk images (.qcow2, .raw, etc.)
├── configs/                # VM configurations (JSON files)
├── repository/             # Saved VMs (like Docker images)
├── locks/                  # Lock files for running VMs
└── easyqemu.log           # Log file

Features Overview

✅ VM Management

• Create, start, stop, delete virtual machines
• Modify VM configurations (memory, CPUs, display, network)
• List all VMs with details
• Show detailed VM information
• Support for multiple display modes (GTK, SDL, VNC, headless)
• Network configuration (user, bridge, tap)
• Boot device selection (CD, HDD)

✅ Volume Management

• Create volumes in multiple formats:
  • qcow2 (QEMU Copy-On-Write)
  • raw (Raw disk image)
  • vmdk (VMware)
  • vdi (VirtualBox)
  • vhdx (Hyper-V)
• Convert between formats
• Import/export volumes
• List volumes with size information
• Show detailed volume information

✅ Snapshot Management

• Create disk snapshots
• List all snapshots for a VM
• Apply/restore snapshots
• Delete snapshots
• Timestamp-based snapshot names

✅ Repository System

• Save VMs to repository (like Docker images)
• Load VMs from repository (create clones)
• List repository entries
• Delete repository entries
• Includes disk and configuration

✅ User Experience

• Colored terminal output
• Clear error messages
• Interactive confirmations for destructive operations
• Force flags for scripting (-f, --force)
• Comprehensive help system
• Example commands and workflows

✅ Technical Features

• JSON-based configuration storage
• Automatic KVM acceleration detection
• Modular Bash function design
• Comprehensive error handling
• Directory structure initialization
• Version management

Command Summary

Category	Command	Description
VM	vm create	Create a new VM
	vm list	List all VMs
	vm start	Start a VM
	vm info	Show VM details
	vm modify	Modify VM configuration
	vm delete	Delete a VM
Volume	volume create	Create a new volume
	volume list	List all volumes
	volume info	Show volume details
	volume convert	Convert format
	volume import	Import external volume
	volume export	Export volume
	volume delete	Delete a volume
Snapshot	snapshot create	Create snapshot
	snapshot list	List snapshots
	snapshot apply	Restore snapshot
	snapshot delete	Delete snapshot
Repository	repo save	Save VM to repo
	repo load	Load VM from repo
	repo list	List saved VMs
	repo delete	Delete saved VM
Other	version	Show version
	help	Show help

Testing Status

✅ All 18 automated tests pass:

1. Help command
2. Version command
3. Create VM
4. List VMs
5. VM Info
6. Modify VM
7. Create volume
8. List volumes
9. Volume info
10. Convert volume
11. Create snapshot
12. List snapshots
13. Delete snapshot
14. Save to repository
15. List repository
16. Load from repository
17. Delete volume
18. Delete VM

Requirements

• QEMU/KVM: qemu-system-x86_64, qemu-img
• Bash: 4.0 or later
• OS: Linux (tested on Debian-based systems)

Installation Methods

1. System-wide: /usr/local/bin/easyqemu (requires sudo)
2. User-only: ~/.local/bin/easyqemu
3. Portable: Run from current directory ./easyqemu

Usage Examples

# Create and start a VM
easyqemu vm create --name ubuntu --memory 4096 --cpus 4 --disk-size 50G
easyqemu vm start ubuntu_<timestamp>

# Create a snapshot before updates
easyqemu snapshot create <vm_id> before_update

# Clone a VM
easyqemu repo save <vm_id> my_template
easyqemu repo load my_template cloned_vm

# Convert disk format
easyqemu volume convert --source disk.qcow2 --target disk.vmdk --format vmdk

Documentation

• README.md: Full documentation with examples
• QUICKSTART.md: Get started in 5 minutes
• EXAMPLES.sh: Interactive examples with colored output
• CONTRIBUTING.md: How to contribute
• CHANGELOG.md: Version history

License

MIT License - Free to use, modify, and distribute

Project Goals

Make QEMU/KVM virtual machine management as easy as Docker container management, with an intuitive command-line interface and repository system for managing VM templates.

---

Status: ✅ Production Ready v1.0.0 Last Updated: 2026-01-07