skystack/README.md

# 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
```bash
# 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
```bash
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
```bash
# 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
```bash
qemu-vm> monitor start vm-name
qemu-vm> metrics vm-name
qemu-vm> monitor stop vm-name
```

### Disk Management
```bash
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
```json
{
  "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
```json
{
  "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
```bash
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
```bash
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
```bash
# 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](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](https://github.com/yourusername/qemu-vm-manager/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/qemu-vm-manager/discussions)
- **Wiki**: [Project Wiki](https://github.com/yourusername/qemu-vm-manager/wiki)

---

**Made with ❤️ by the QEMU VM Manager Community**