279 lines
8.6 KiB
Markdown
279 lines
8.6 KiB
Markdown
# 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**
|