317 lines
6.9 KiB
Markdown
317 lines
6.9 KiB
Markdown
# QEMU VM Manager - Quick Start Guide
|
|
|
|
Get up and running with QEMU VM Manager in minutes! This guide covers both single-node and distributed P2P modes.
|
|
|
|
## 🚀 Quick Start (5 minutes)
|
|
|
|
### 1. Prerequisites Check
|
|
```bash
|
|
# Check .NET version (requires 8.0+)
|
|
dotnet --version
|
|
|
|
# Check QEMU installation
|
|
qemu-system-x86_64 --version
|
|
|
|
# Check virtualization support
|
|
# Windows: Enable Hyper-V in Windows Features
|
|
# Linux: Check KVM support with 'lsmod | grep kvm'
|
|
# macOS: Check HVF support
|
|
```
|
|
|
|
### 2. Build and Run
|
|
```bash
|
|
# Clone and build
|
|
git clone https://github.com/yourusername/qemu-vm-manager.git
|
|
cd qemu-vm-manager
|
|
dotnet build
|
|
|
|
# Run the application
|
|
dotnet run --project QemuVmManager.Console
|
|
```
|
|
|
|
### 3. Choose Your Mode
|
|
```
|
|
=== QEMU VM Manager ===
|
|
Choose mode:
|
|
1. Single Node Mode (original)
|
|
2. P2P Distributed Mode (new)
|
|
Enter choice (1 or 2):
|
|
```
|
|
|
|
## 🎯 Single Node Mode
|
|
|
|
### Basic VM Operations
|
|
```bash
|
|
# Create a VM
|
|
qemu-vm> create my-first-vm
|
|
# Follow the interactive prompts
|
|
|
|
# Import a VM from configuration file
|
|
qemu-vm> import examples/sample-vm-config.json my-imported-vm
|
|
|
|
# Start the VM
|
|
qemu-vm> start my-first-vm
|
|
|
|
# Check status
|
|
qemu-vm> status
|
|
|
|
# Stop the VM
|
|
qemu-vm> stop my-first-vm
|
|
```
|
|
|
|
### Performance Monitoring
|
|
```bash
|
|
# Start monitoring
|
|
qemu-vm> monitor start my-first-vm
|
|
|
|
# View metrics
|
|
qemu-vm> metrics my-first-vm
|
|
|
|
# Stop monitoring
|
|
qemu-vm> monitor stop my-first-vm
|
|
```
|
|
|
|
### Disk Management
|
|
```bash
|
|
# Create a new disk
|
|
qemu-vm> disk create ubuntu.qcow2 20GB
|
|
|
|
# Get disk information
|
|
qemu-vm> disk info ubuntu.qcow2
|
|
|
|
# Resize disk
|
|
qemu-vm> disk resize ubuntu.qcow2 40GB
|
|
```
|
|
|
|
### System Diagnostics
|
|
```bash
|
|
# Run system diagnosis
|
|
qemu-vm> diagnose
|
|
|
|
# View VM configurations
|
|
qemu-vm> list
|
|
|
|
# Get detailed VM info
|
|
qemu-vm> status my-first-vm
|
|
```
|
|
|
|
## 🌐 P2P Distributed Mode
|
|
|
|
### Starting a P2P Node
|
|
```bash
|
|
# Choose P2P mode (option 2)
|
|
# Enter node ID and port
|
|
Node ID: node-001
|
|
Port: 8080
|
|
|
|
# Wait for node to start
|
|
Starting P2P node...
|
|
Node started successfully!
|
|
```
|
|
|
|
### Cluster Management
|
|
```bash
|
|
# Check cluster status
|
|
qemu-vm> cluster status
|
|
|
|
# List all nodes
|
|
qemu-vm> nodes list
|
|
|
|
# View cluster topology
|
|
qemu-vm> cluster info
|
|
```
|
|
|
|
### Distributed VM Operations
|
|
```bash
|
|
# List VMs across cluster
|
|
qemu-vm> vms list
|
|
|
|
# Start VM on specific node
|
|
qemu-vm> start ubuntu-vm --node node-002
|
|
|
|
# Migrate VM between nodes
|
|
qemu-vm> migrate ubuntu-vm node-003
|
|
|
|
# Stop VM remotely
|
|
qemu-vm> stop ubuntu-vm --node node-002
|
|
```
|
|
|
|
### Port Forwarding (Master Node Only)
|
|
```bash
|
|
# Forward port from external to VM
|
|
qemu-vm> forward ubuntu-vm 8080 80
|
|
|
|
# Check UPnP status
|
|
qemu-vm> upnp status
|
|
|
|
# List active port mappings
|
|
qemu-vm> upnp mappings
|
|
```
|
|
|
|
## ⚙️ Configuration Examples
|
|
|
|
### Basic VM Configuration
|
|
```json
|
|
{
|
|
"name": "ubuntu-desktop",
|
|
"description": "Ubuntu Desktop VM",
|
|
"cpu": {
|
|
"cores": 4,
|
|
"model": "host"
|
|
},
|
|
"memory": {
|
|
"sizeGB": 8
|
|
},
|
|
"storage": {
|
|
"disks": [
|
|
{
|
|
"path": "ubuntu.qcow2",
|
|
"format": "qcow2",
|
|
"sizeGB": 50,
|
|
"isBoot": true
|
|
}
|
|
]
|
|
},
|
|
"network": {
|
|
"backend": "user",
|
|
"device": "e1000"
|
|
},
|
|
"display": {
|
|
"type": "gtk",
|
|
"vga": "virtio"
|
|
}
|
|
}
|
|
```
|
|
|
|
### P2P Node Configuration
|
|
```json
|
|
{
|
|
"nodeId": "node-001",
|
|
"port": 8080,
|
|
"discoveryPort": 8081,
|
|
"heartbeatInterval": 5000,
|
|
"electionTimeout": 10000
|
|
}
|
|
```
|
|
|
|
## 🔧 Common Commands Reference
|
|
|
|
### Single Node Commands
|
|
| Command | Description | Example |
|
|
|---------|-------------|---------|
|
|
| `help` | Show all commands | `help` |
|
|
| `create` | Create new VM | `create my-vm` |
|
|
| `import` | Import VM from config | `import config.json my-vm` |
|
|
| `start` | Start VM | `start my-vm` |
|
|
| `stop` | Stop VM | `stop my-vm` |
|
|
| `status` | Show VM status | `status my-vm` |
|
|
| `list` | List all VMs | `list` |
|
|
| `delete` | Delete VM | `delete my-vm` |
|
|
| `monitor` | Performance monitoring | `monitor start my-vm` |
|
|
| `metrics` | Show performance data | `metrics my-vm` |
|
|
| `diagnose` | System diagnosis | `diagnose` |
|
|
|
|
### P2P Commands
|
|
| Command | Description | Example |
|
|
|---------|-------------|---------|
|
|
| `cluster` | Cluster operations | `cluster status` |
|
|
| `nodes` | Node management | `nodes list` |
|
|
| `vms` | Distributed VM ops | `vms list` |
|
|
| `migrate` | Move VM between nodes | `migrate vm-name node-id` |
|
|
| `forward` | Port forwarding | `forward vm-name 8080 80` |
|
|
| `upnp` | UPnP operations | `upnp status` |
|
|
|
|
### Disk Commands
|
|
| Command | Description | Example |
|
|
|---------|-------------|---------|
|
|
| `disk create` | Create disk image | `disk create disk.qcow2 20GB` |
|
|
| `disk info` | Show disk info | `disk info disk.qcow2` |
|
|
| `disk resize` | Resize disk | `disk resize disk.qcow2 40GB` |
|
|
| `disk convert` | Convert format | `disk convert disk.img disk.qcow2` |
|
|
|
|
## 🚨 Troubleshooting
|
|
|
|
### VM Won't Start
|
|
```bash
|
|
# Run diagnosis
|
|
qemu-vm> diagnose
|
|
|
|
# Check common issues:
|
|
# 1. Hardware virtualization enabled in BIOS
|
|
# 2. QEMU in PATH
|
|
# 3. Disk images exist
|
|
# 4. Sufficient memory/CPU
|
|
```
|
|
|
|
### P2P Connection Issues
|
|
```bash
|
|
# Check node status
|
|
qemu-vm> cluster status
|
|
|
|
# Verify network connectivity
|
|
# Check firewall settings
|
|
# Ensure discovery ports are open
|
|
```
|
|
|
|
### Performance Issues
|
|
```bash
|
|
# Check virtualization type
|
|
qemu-vm> diagnose
|
|
|
|
# Monitor resource usage
|
|
qemu-vm> monitor start vm-name
|
|
qemu-vm> metrics vm-name
|
|
|
|
# Consider migration to less loaded node
|
|
qemu-vm> migrate vm-name target-node
|
|
```
|
|
|
|
## 📊 Performance Tips
|
|
|
|
### Hardware Acceleration
|
|
- **Enable virtualization in BIOS** (VT-x/AMD-V)
|
|
- **Use virtio drivers** when available
|
|
- **Monitor performance metrics** regularly
|
|
|
|
### Network Optimization
|
|
- **Use bridge networking** on Linux (when available)
|
|
- **Enable UPnP** for automatic port forwarding
|
|
- **Monitor network performance** across nodes
|
|
|
|
### Storage Optimization
|
|
- **Use qcow2 format** for better performance
|
|
- **Enable disk caching** when appropriate
|
|
- **Monitor I/O performance** with metrics
|
|
|
|
## 🔄 Next Steps
|
|
|
|
### Advanced Features
|
|
1. **Custom VM configurations** - Edit JSON files directly
|
|
2. **Performance tuning** - Adjust CPU/memory allocation
|
|
3. **Network configuration** - Set up custom network topologies
|
|
4. **Backup strategies** - Implement VM backup procedures
|
|
|
|
### Scaling Your Cluster
|
|
1. **Add more nodes** - Expand your P2P network
|
|
2. **Load balancing** - Distribute VMs across nodes
|
|
3. **High availability** - Set up redundant master nodes
|
|
4. **Monitoring** - Implement cluster-wide monitoring
|
|
|
|
### Integration
|
|
1. **CI/CD pipelines** - Automate VM deployment
|
|
2. **Monitoring tools** - Integrate with Prometheus/Grafana
|
|
3. **Orchestration** - Use with Kubernetes/Docker
|
|
4. **API access** - Build custom management tools
|
|
|
|
## 📚 Additional Resources
|
|
|
|
- **Full Documentation**: [README.md](README.md)
|
|
- **API Reference**: Check source code for detailed API documentation
|
|
- **Examples**: See `examples/` directory for sample configurations
|
|
- **Issues**: Report bugs on GitHub Issues
|
|
- **Discussions**: Join community discussions on GitHub
|
|
|
|
---
|
|
|
|
**Need help? Run `diagnose` for system health check or check the troubleshooting section above!**
|