Updated readmes
This commit is contained in:
369
QUICKSTART.md
369
QUICKSTART.md
@@ -1,95 +1,312 @@
|
||||
# Quick Start Guide
|
||||
# QEMU VM Manager - Quick Start Guide
|
||||
|
||||
## Prerequisites
|
||||
Get up and running with QEMU VM Manager in minutes! This guide covers both single-node and distributed P2P modes.
|
||||
|
||||
1. **Install .NET 8.0 SDK**
|
||||
- Download from: https://dotnet.microsoft.com/download
|
||||
- Verify installation: `dotnet --version`
|
||||
## 🚀 Quick Start (5 minutes)
|
||||
|
||||
2. **Install QEMU**
|
||||
- **Windows**: Download from https://qemu.weilnetz.de/
|
||||
- **Linux**: `sudo apt install qemu-system-x86` (Ubuntu/Debian)
|
||||
- **macOS**: `brew install qemu`
|
||||
### 1. Prerequisites Check
|
||||
```bash
|
||||
# Check .NET version (requires 8.0+)
|
||||
dotnet --version
|
||||
|
||||
3. **For KVM acceleration (Linux only)**:
|
||||
```bash
|
||||
sudo apt install qemu-kvm libvirt-daemon-system libvirt-clients bridge-utils
|
||||
sudo usermod -aG kvm $USER
|
||||
sudo usermod -aG libvirt $USER
|
||||
```
|
||||
# Check QEMU installation
|
||||
qemu-system-x86_64 --version
|
||||
|
||||
## Quick Start
|
||||
# Check virtualization support
|
||||
# Windows: Enable Hyper-V in Windows Features
|
||||
# Linux: Check KVM support with 'lsmod | grep kvm'
|
||||
# macOS: Check HVF support
|
||||
```
|
||||
|
||||
1. **Clone and build**:
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd skystack
|
||||
dotnet build
|
||||
```
|
||||
### 2. Build and Run
|
||||
```bash
|
||||
# Clone and build
|
||||
git clone https://github.com/yourusername/qemu-vm-manager.git
|
||||
cd qemu-vm-manager
|
||||
dotnet build
|
||||
|
||||
2. **Run the application**:
|
||||
```bash
|
||||
dotnet run --project QemuVmManager.Console
|
||||
```
|
||||
# Run the application
|
||||
dotnet run --project QemuVmManager.Console
|
||||
```
|
||||
|
||||
3. **Create your first VM**:
|
||||
```
|
||||
qemu-vm> create my-first-vm
|
||||
Enter VM name: my-first-vm
|
||||
Description (optional): My first VM
|
||||
CPU cores (2): 2
|
||||
CPU model (qemu64): qemu64
|
||||
Memory size in MB (2048): 2048
|
||||
Disk path: /path/to/your/disk.qcow2
|
||||
Disk size in GB (10): 10
|
||||
Disk format (qcow2): qcow2
|
||||
Disk interface (virtio): virtio
|
||||
Network bridge (virbr0): virbr0
|
||||
Display type (gtk): gtk
|
||||
VGA type (virtio): virtio
|
||||
```
|
||||
### 3. Choose Your Mode
|
||||
```
|
||||
=== QEMU VM Manager ===
|
||||
Choose mode:
|
||||
1. Single Node Mode (original)
|
||||
2. P2P Distributed Mode (new)
|
||||
Enter choice (1 or 2):
|
||||
```
|
||||
|
||||
4. **Start the VM**:
|
||||
```
|
||||
qemu-vm> start my-first-vm
|
||||
```
|
||||
## 🎯 Single Node Mode
|
||||
|
||||
5. **Check status**:
|
||||
```
|
||||
qemu-vm> status my-first-vm
|
||||
```
|
||||
### Basic VM Operations
|
||||
```bash
|
||||
# Create a VM
|
||||
qemu-vm> create my-first-vm
|
||||
# Follow the interactive prompts
|
||||
|
||||
## Common Commands
|
||||
# Start the VM
|
||||
qemu-vm> start my-first-vm
|
||||
|
||||
- `list` - Show all VMs
|
||||
- `start <name>` - Start a VM
|
||||
- `stop <name>` - Stop a VM
|
||||
- `pause <name>` - Pause a VM
|
||||
- `resume <name>` - Resume a VM
|
||||
- `delete <name>` - Delete a VM
|
||||
- `help` - Show all commands
|
||||
# Check status
|
||||
qemu-vm> status
|
||||
|
||||
## Troubleshooting
|
||||
# Stop the VM
|
||||
qemu-vm> stop my-first-vm
|
||||
```
|
||||
|
||||
### QEMU not found
|
||||
- Ensure QEMU is installed and in your PATH
|
||||
- Windows: Add QEMU installation directory to PATH
|
||||
### Performance Monitoring
|
||||
```bash
|
||||
# Start monitoring
|
||||
qemu-vm> monitor start my-first-vm
|
||||
|
||||
### Permission denied (Linux)
|
||||
- Add your user to kvm and libvirt groups
|
||||
- Restart your session after adding groups
|
||||
# View metrics
|
||||
qemu-vm> metrics my-first-vm
|
||||
|
||||
### Network bridge not found
|
||||
- Create the bridge: `sudo virsh net-start default`
|
||||
- Or use user networking: change bridge to "user" in VM config
|
||||
# Stop monitoring
|
||||
qemu-vm> monitor stop my-first-vm
|
||||
```
|
||||
|
||||
### Build issues
|
||||
- Ensure .NET 8.0 SDK is installed
|
||||
- Run `dotnet --version` to verify
|
||||
- Try `dotnet restore` before building
|
||||
### Disk Management
|
||||
```bash
|
||||
# Create a new disk
|
||||
qemu-vm> disk create ubuntu.qcow2 20GB
|
||||
|
||||
## Next Steps
|
||||
# Get disk information
|
||||
qemu-vm> disk info ubuntu.qcow2
|
||||
|
||||
1. Read the full [README.md](README.md) for detailed documentation
|
||||
2. Check the [examples/](examples/) directory for sample configurations
|
||||
3. Explore advanced features like SPICE remote desktop and shared folders
|
||||
# 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` |
|
||||
| `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!**
|
||||
|
||||
Reference in New Issue
Block a user