skystack/README.md

QEMU VM Manager

A comprehensive .NET application for managing QEMU virtual machines with an intuitive console interface.

Features

• VM Lifecycle Management: Create, start, stop, pause, resume, and delete VMs
• Configuration Management: Store and manage VM configurations in JSON format
• VM Cloning: Clone existing VMs with automatic disk path management
• Import/Export: Export and import VM configurations
• Status Monitoring: Real-time VM status and resource usage tracking
• Interactive Console: User-friendly command-line interface
• Cross-Platform: Works on Windows, Linux, and macOS

Prerequisites

• .NET 8.0 SDK or Runtime
• QEMU installed and available in PATH
• For KVM acceleration: KVM support (Linux) or Hyper-V (Windows)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd skystack
   

2. Build the solution:

   dotnet build
   

3. Run the application:

   dotnet run --project QemuVmManager.Console
   

Usage

Starting the Application

dotnet run --project QemuVmManager.Console

You'll see the interactive prompt:

=== QEMU VM Manager ===
Type 'help' for available commands

qemu-vm>

Available Commands

help

Display all available commands and their usage.

list

List all configured VMs with their status, CPU, memory, and description.

create [name]

Create a new VM configuration interactively. If no name is provided, you'll be prompted for one.

Example:

qemu-vm> create my-vm
Enter VM name: my-vm
Description (optional): My test VM
CPU cores (2): 4
CPU model (qemu64): qemu64
Memory size in MB (2048): 4096
Disk path: /path/to/disk.qcow2
Disk size in GB (10): 20
Disk format (qcow2): qcow2
Disk interface (virtio): virtio
Network bridge (virbr0): virbr0
Display type (gtk): gtk
VGA type (virtio): virtio

start <name>

Start a VM by name.

Example:

qemu-vm> start my-vm

stop <name> [--force]

Stop a VM gracefully. Use --force for immediate termination.

Example:

qemu-vm> stop my-vm
qemu-vm> stop my-vm --force

pause <name>

Pause a running VM.

Example:

qemu-vm> pause my-vm

resume <name>

Resume a paused VM.

Example:

qemu-vm> resume my-vm

delete <name>

Delete a VM configuration and stop it if running.

Example:

qemu-vm> delete my-vm
Are you sure you want to delete VM 'my-vm'? (y/N): y

clone <source> <target>

Clone an existing VM configuration.

Example:

qemu-vm> clone my-vm my-vm-clone

export <name> <path>

Export a VM configuration to a JSON file.

Example:

qemu-vm> export my-vm /tmp/my-vm-config.json

import <path> [name]

Import a VM configuration from a JSON file.

Example:

qemu-vm> import /tmp/my-vm-config.json my-imported-vm

status [name]

Show VM status. Without a name, shows all VMs.

Example:

qemu-vm> status
qemu-vm> status my-vm

config <name>

Display detailed VM configuration.

Example:

qemu-vm> config my-vm

exit or quit

Exit the application.

Configuration

VM configurations are stored in JSON format in the vm-configs directory. Each VM has its own configuration file named <vm-name>.json.

Configuration Structure

{
  "name": "my-vm",
  "description": "My test VM",
  "cpu": {
    "cores": 4,
    "sockets": 1,
    "threads": 1,
    "model": "qemu64",
    "enableKvm": true
  },
  "memory": {
    "size": 4096,
    "unit": "M"
  },
  "storage": {
    "disks": [
      {
        "path": "/path/to/disk.qcow2",
        "size": 20,
        "format": "qcow2",
        "interface": "virtio",
        "cache": "writeback",
        "isBoot": true
      }
    ],
    "cdrom": null
  },
  "network": {
    "interfaces": [
      {
        "type": "bridge",
        "model": "virtio-net-pci",
        "mac": null,
        "bridge": "virbr0"
      }
    ],
    "bridge": "virbr0"
  },
  "display": {
    "type": "gtk",
    "vga": "virtio",
    "resolution": "1024x768",
    "enableSpice": false,
    "spicePort": 5930
  },
  "boot": {
    "order": ["c", "d", "n"],
    "kernel": null,
    "initrd": null,
    "cmdline": null
  },
  "advanced": {
    "enableAudio": false,
    "enableUsb": false,
    "enableBalloon": true,
    "enableVirtioRng": true,
    "enableVirtioFs": false,
    "sharedFolders": [],
    "extraArgs": []
  },
  "created": "2024-01-01T00:00:00Z",
  "lastModified": "2024-01-01T00:00:00Z"
}

Project Structure

skystack/
├── QemuVmManager.sln              # Solution file
├── QemuVmManager.Models/          # Data models and DTOs
│   ├── VmConfiguration.cs         # Main VM configuration model
│   └── VmStatus.cs               # VM status and resource usage
├── QemuVmManager.Core/            # Core QEMU operations
│   ├── QemuCommandBuilder.cs     # QEMU command generation
│   └── QemuProcessManager.cs     # VM process management
├── QemuVmManager.Services/        # High-level services
│   └── VmManagementService.cs    # Main VM management service
├── QemuVmManager.Console/         # Console application
│   └── Program.cs                # Main program and UI
└── README.md                     # This file

Architecture

The application follows a layered architecture:

1. Models Layer (QemuVmManager.Models): Contains data structures for VM configuration and status
2. Core Layer (QemuVmManager.Core): Handles QEMU command generation and process management
3. Services Layer (QemuVmManager.Services): Provides high-level VM management operations
4. Console Layer (QemuVmManager.Console): User interface and command processing

QEMU Integration

The application generates QEMU command-line arguments based on VM configurations. Key features:

• KVM Acceleration: Automatically enables KVM when available
• VirtIO Support: Uses VirtIO devices for better performance
• Network Bridging: Supports bridge networking
• SPICE Support: Optional SPICE remote desktop
• Shared Folders: 9P filesystem sharing
• Advanced Features: Audio, USB, balloon driver, RNG

Troubleshooting

Common Issues

1. QEMU not found: Ensure QEMU is installed and in your PATH
2. Permission denied: Run with appropriate permissions for KVM/bridge access
3. Network bridge not found: Create the bridge interface (e.g., virbr0)
4. Disk file not found: Ensure disk paths are correct and accessible

Debug Mode

To see the generated QEMU commands, you can modify the QemuProcessManager.cs to log the command before execution.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• QEMU team for the excellent virtualization platform
• .NET community for the robust framework
• Contributors and users of this project