QEMU VM Manager

A powerful, cross-platform .NET 8.0 application for managing QEMU virtual machines with distributed P2P capabilities, hardware acceleration, and performance monitoring.

🚀 Features

Core VM Management

• Create, start, stop, pause, resume, and delete VMs with comprehensive JSON configuration
• Automatic hardware acceleration detection (KVM, Hyper-V, WHPX, HAXM, HVF) with TCG fallback
• Cross-platform support for Windows, Linux, and macOS
• Disk image management with qemu-img integration (create, resize, convert, info)
• Performance monitoring with real-time CPU, memory, thread, and handle metrics

Distributed P2P Architecture

• Master node election using Raft-like consensus algorithm
• Automatic node discovery via UDP broadcast
• Distributed VM management across multiple hosts
• VM migration between nodes for load balancing
• Cluster state synchronization with heartbeat monitoring

Network & UPnP Integration

• UPnP device discovery and external IP detection
• Port forwarding from master node to VM instances
• Automatic network configuration for distributed deployments
• SSDP protocol support for device discovery

Advanced QEMU Features

• VirtIO drivers for optimal performance (when supported)
• Multiple machine types (q35, pc-i440fx, pc) with automatic selection
• Flexible storage interfaces (virtio-blk-pci, ide-hd, scsi)
• Network backends (bridge, user) with automatic fallback
• Audio support with intel-hda and hda-duplex devices

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Master Node   │    │  Follower Node  │    │  Follower Node  │
│                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │P2P Node    │ │    │ │P2P Node    │ │    │ │P2P Node    │ │
│ │+ UPnP      │ │    │ │             │ │    │ │             │ │
│ │+ Port Fwd  │ │    │ │             │ │    │ │             │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │QEMU Manager│ │    │ │QEMU Manager│ │    │ │QEMU Manager│ │
│ │+ Perf Mon  │ │    │ │+ Perf Mon  │ │    │ │+ Perf Mon  │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────┴─────────────┐
                    │      UDP Discovery        │
                    │   TCP Communication       │
                    │   Heartbeat Messages      │
                    └───────────────────────────┘

📋 Prerequisites

• .NET 8.0 Runtime or SDK
• QEMU installed and accessible via PATH
• Hardware virtualization enabled in BIOS (VT-x/AMD-V)
• Windows: Hyper-V or WHPX support
• Linux: KVM support
• macOS: HVF support

🛠️ Installation

Quick Start

# Clone the repository
git clone https://github.com/yourusername/qemu-vm-manager.git
cd qemu-vm-manager

# Build the solution
dotnet build

# Run the application
dotnet run --project QemuVmManager.Console

Build Scripts

• Windows: build.bat or build.ps1
• Linux/macOS: ./build.sh

🎯 Usage

Single Node Mode

qemu-vm> create my-vm
qemu-vm> start my-vm
qemu-vm> status
qemu-vm> stop my-vm
qemu-vm> delete my-vm

P2P Distributed Mode

# Choose P2P mode when starting
qemu-vm> cluster status
qemu-vm> nodes list
qemu-vm> vms list
qemu-vm> start vm-name --node target-node
qemu-vm> migrate vm-name target-node
qemu-vm> forward vm-name 8080 80

Performance Monitoring

qemu-vm> monitor start vm-name
qemu-vm> metrics vm-name
qemu-vm> monitor stop vm-name

Disk Management

qemu-vm> disk create ubuntu.qcow2 20GB
qemu-vm> disk info ubuntu.qcow2
qemu-vm> disk resize ubuntu.qcow2 40GB
qemu-vm> disk convert ubuntu.img ubuntu.qcow2

⚙️ Configuration

VM Configuration Example

{
  "name": "ubuntu-desktop",
  "description": "Ubuntu Desktop VM for development",
  "cpu": {
    "cores": 4,
    "model": "host",
    "sockets": 1
  },
  "memory": {
    "sizeGB": 8
  },
  "storage": {
    "disks": [
      {
        "path": "ubuntu-desktop.qcow2",
        "format": "qcow2",
        "sizeGB": 50,
        "isBoot": true
      }
    ],
    "cdrom": {
      "path": "ubuntu-24.04.3-desktop-amd64.iso",
      "isBoot": true
    }
  },
  "network": {
    "backend": "user",
    "device": "e1000"
  },
  "display": {
    "type": "gtk",
    "vga": "virtio"
  }
}

P2P Configuration

{
  "nodeId": "node-001",
  "port": 8080,
  "discoveryPort": 8081,
  "heartbeatInterval": 5000,
  "electionTimeout": 10000
}

🔧 Advanced Features

Hardware Acceleration Detection

The system automatically detects and prioritizes available virtualization technologies:

1. KVM (Linux) - Native virtualization
2. Hyper-V/WHPX (Windows) - Hardware acceleration
3. HAXM (Windows/macOS) - Intel acceleration
4. HVF (macOS) - Apple Hypervisor
5. TCG - Software emulation (fallback)

Performance Monitoring

Real-time metrics collection including:

• CPU usage (VM and system)
• Memory consumption (private, virtual, working set)
• Thread count and handle count
• Historical performance data

UPnP Integration

• Automatic router discovery
• External IP address detection
• Port mapping management
• NAT traversal support

🚨 Troubleshooting

Common Issues

VM Won't Start

qemu-vm> diagnose

Check for:

• Hardware virtualization enabled in BIOS
• QEMU installation and PATH
• Disk image existence and permissions
• Available memory and CPU resources

P2P Connection Issues

• Verify firewall settings
• Check network connectivity between nodes
• Ensure discovery ports are open
• Review node configuration

Performance Issues

• Enable hardware acceleration
• Use virtio drivers when available
• Monitor resource usage
• Consider VM migration to less loaded nodes

Debug Commands

qemu-vm> diagnose          # System health check
qemu-vm> logs             # View detailed logs
qemu-vm> config show      # Display current configuration

📊 Performance Benchmarks

Virtualization	CPU Performance	Memory Performance	I/O Performance
KVM	95-98%	98-99%	90-95%
Hyper-V/WHPX	85-90%	90-95%	80-85%
TCG	20-30%	70-80%	40-50%

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Development Setup

# Install .NET 8.0 SDK
# Clone and build
git clone <repo>
cd qemu-vm-manager
dotnet restore
dotnet build
dotnet test

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• QEMU Team for the excellent virtualization platform
• .NET Community for the robust framework
• Open Source Contributors who made this possible

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Wiki: Project Wiki

---

Made with ❤️ by the QEMU VM Manager Community