skystack/QUICKSTART.md

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Check cluster status
qemu-vm> cluster status

# List all nodes
qemu-vm> nodes list

# View cluster topology
qemu-vm> cluster info

Distributed VM Operations

# 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)

# 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

{
  "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

{
  "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

# 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

# Check node status
qemu-vm> cluster status

# Verify network connectivity
# Check firewall settings
# Ensure discovery ports are open

Performance Issues

# 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
• 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!