qnap-vm

README

qnap-vm

A command-line tool for managing virtual machines on QNAP devices with Virtualization Station.

Features

• Complete VM Lifecycle: Create, start, stop, delete, list, and monitor virtual machines
• Advanced Snapshots: Full snapshot management with create, restore, list, and delete operations
• Resource Monitoring: Real-time CPU, memory, disk I/O, and network statistics with watch mode
• VM Cloning: Full and linked VM cloning with automatic configuration inheritance
• Console Access: VNC and serial console support with connection guidance and SSH tunneling
• SSH Integration: Secure remote management with key authentication and ssh-agent support
• Smart Storage: Intelligent detection and management of QNAP storage pools (CACHEDEV, ZFS, USB)
• Cross-platform: Works on macOS, Linux, Windows, and Docker environments

Installation

Homebrew (macOS/Linux)

brew install scttfrdmn/qnap-vm/qnap-vm

From Release

Download the latest release from GitHub Releases.

From Source

go install github.com/scttfrdmn/qnap-vm/cmd/qnap-vm@latest

Quick Start

1. Configure your QNAP connection:

   qnap-vm config set --host your-qnap.local --username admin
   

2. List existing VMs:

   qnap-vm list
   

3. Create a new VM:

   qnap-vm create --name my-vm --template ubuntu-20.04
   

4. Start the VM:

   qnap-vm start my-vm
   

5. Monitor VM resources:

   qnap-vm stats my-vm
   qnap-vm stats my-vm --watch  # real-time monitoring
   

6. Manage snapshots:

   qnap-vm snapshot create my-vm backup-point --description "Before updates"
   qnap-vm snapshot list my-vm
   qnap-vm snapshot restore my-vm backup-point
   

7. Clone VMs:

   qnap-vm clone my-vm my-vm-copy
   qnap-vm clone my-vm my-vm-template --linked  # space-efficient
   

8. Access VM console:

   qnap-vm console my-vm --vnc      # Get VNC connection details
   qnap-vm console my-vm --serial   # Connect to serial console
   

System Requirements

QNAP Device Requirements

• QNAP NAS with Virtualization Station installed
• QTS 5.1.0+ or QuTS hero h5.1.0+
• CPU with Intel VT-x or AMD-V support
• Minimum 4GB RAM (varies by NAS model)

Client Requirements

• SSH access to QNAP device
• Network connectivity to QNAP device

Testing

qnap-vm follows the same rigorous testing approach as qnap-docker, with comprehensive testing against real QNAP hardware.

Unit Tests

Run standard unit tests:

make test
make test-coverage  # with coverage report

Integration Tests

Real hardware testing against actual QNAP devices:

# Required: Set your QNAP device details
export NAS_HOST=your-qnap.local
export NAS_USER=admin  # optional, defaults to 'admin'

# Run integration tests
make integration-test

# Run with coverage reporting
make integration-test-full

Integration test coverage:

• ✅ SSH connection and authentication
• ✅ Virtualization Station availability
• ✅ Storage pool detection and management
• ✅ Complete VM lifecycle (create, start, stop, delete)
• ✅ VM configuration validation
• ✅ Resource management and cleanup

Requirements:

• QNAP NAS with Virtualization Station installed
• QTS 5.1.0+ or QuTS hero h5.1.0+
• SSH access enabled
• Intel VT-x or AMD-V CPU support

See tests/integration/README.md for detailed integration testing documentation.

Development Roadmap

Phase 1: Core VM Lifecycle (v0.1.0) ✅ COMPLETED

• Project setup and basic structure
• SSH connection management with key authentication
• libvirt/virsh integration for QNAP Virtualization Station
• Basic VM operations (create, start, stop, delete, list, status)
• Configuration file support with YAML storage
• Intelligent storage pool detection (CACHEDEV, ZFS, USB)
• Cross-platform support (Linux, macOS, Windows)
• A+ Go Report Card compliance
• Comprehensive integration testing against real hardware
• Professional release infrastructure with GoReleaser

Phase 2: Advanced Features (v0.2.0) ✅ COMPLETED

• VM snapshots and restoration with full lifecycle management
• Resource monitoring and statistics with real-time watch mode
• VM cloning capabilities with configuration inheritance
• VM console access (VNC/serial) with connection guidance

Phase 3: Templates and Automation (v0.3.0)

• VM template system with marketplace integration
• Automated VM provisioning with cloud-init
• Bulk operations for multi-VM management
• Export/import VM configurations (OVF/OVA)
• Infrastructure as Code with YAML/JSON configs
• Scheduled VM operations and automation

Phase 4: Storage and Networking (v0.4.0)

• Live migration between QNAP hosts with resource validation
• Advanced storage pool management and optimization
• Network configuration management with VLAN support
• Virtual disk operations (resize, convert, migrate)
• Storage migration and performance-based placement
• Network isolation and security policies
• Enterprise-grade multi-host management

Configuration

qnap-vm uses YAML configuration files stored in ~/.qnap-vm/config.yaml.

Example configuration:

hosts:
  default:
    host: qnap.local
    username: admin
    port: 22
    keyfile: ~/.ssh/id_rsa

Commands

Command	Description
qnap-vm list	List all virtual machines
qnap-vm create	Create a new virtual machine
qnap-vm start	Start a virtual machine
qnap-vm stop	Stop a virtual machine
qnap-vm delete	Delete a virtual machine
qnap-vm status	Show VM status and resource usage
qnap-vm stats	Show VM resource statistics (CPU, memory, I/O, network)
qnap-vm snapshot	Manage VM snapshots (create, list, restore, delete, current)
qnap-vm clone	Clone virtual machines (full or linked clones)
qnap-vm console	Access VM console (VNC/serial) with connection details
qnap-vm config	Manage connection configuration

Contributing

Contributions are welcome! Please read our Contributing Guidelines and Code of Conduct.

License

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

Acknowledgments

• Inspired by qnap-docker
• Built on libvirt and QEMU technologies
• Thanks to the QNAP community for virtualization insights