hypersdk

hyper2kvm Systemd Daemon Integration - Implementation Complete ✅

Overview

Complete integration of HyperSDK with hyper2kvm systemd daemon for production deployments. This provides automatic VM conversion through a queue-based system with full systemd management.

Completed Features

✅ 1. Core Pipeline Integration

Files: providers/common/pipeline.go, providers/vsphere/export_options.go, providers/vsphere/export.go

✅ 2. CLI Flags

File: cmd/hyperexport/main.go

Added 6 command-line flags:

--hyper2kvm-daemon              # Enable daemon mode
--hyper2kvm-instance <name>     # Instance name
--hyper2kvm-watch-dir <path>    # Watch directory
--hyper2kvm-output-dir <path>   # Output directory
--hyper2kvm-poll-interval <sec> # Poll interval (default: 5)
--hyper2kvm-daemon-timeout <min># Timeout (default: 60)

Usage Example:

hyperexport --vm "Ubuntu-Server" \
  --output /tmp/export \
  --manifest \
  --pipeline \
  --hyper2kvm-daemon \
  --hyper2kvm-instance vsphere

✅ 3. Interactive TUI

File: cmd/hyperexport/interactive_huh.go

Features:

✅ 4. Web Dashboard UI

File: web/dashboard-react/src/components/JobSubmissionForm.tsx

JSON Example:

{
  "name": "Ubuntu Server Migration",
  "vm_path": "/DC1/vm/ubuntu-server",
  "options": {
    "enable_pipeline": true,
    "hyper2kvm_daemon": true,
    "hyper2kvm_instance": "vsphere",
    "hyper2kvm_watch_dir": "/var/lib/hyper2kvm/vsphere/queue",
    "hyper2kvm_output_dir": "/var/lib/hyper2kvm/vsphere/output",
    "hyper2kvm_poll_interval": 5,
    "hyper2kvm_daemon_timeout": 60
  }
}

✅ 5. Daemon Management Commands

Files: cmd/hyperctl/daemon_commands.go, cmd/hyperctl/main.go

New hyperctl daemon commands:

# Show status of all daemon instances
hyperctl daemon -op status

# Show specific instance status
hyperctl daemon -op status -instance vsphere

# List all daemon instances
hyperctl daemon -op list

Output Includes:

✅ 6. Systemd Unit Files

Directory: systemd/

Production-ready systemd service files with security hardening:

Service Files:

Configuration Templates:

Security Hardening:

Installation Script:

install.sh - Automated deployment:

# Install default instance
sudo systemd/install.sh

# Install named instance
sudo systemd/install.sh --instance vsphere

# Uninstall
sudo systemd/install.sh --uninstall

Features:

Documentation:

systemd/README.md - Complete deployment guide:

Architecture

┌─────────────────────────────────────────────┐
│            HyperSDK Export                  │
│    (vSphere, AWS, Azure, GCP, Hyper-V)     │
└──────────────────┬──────────────────────────┘
                   │
                   ▼
         ┌─────────────────────┐
         │ Pipeline Executor   │
         │  detectDaemonMode() │
         └──────┬──────────────┘
                │
        ┌───────┴───────┐
        │               │
        ▼               ▼
┌──────────────┐  ┌──────────────┐
│  Direct Mode │  │  Daemon Mode │
│              │  │              │
│ Execute      │  │ Submit to    │
│ hyper2kvm    │  │ watch dir    │
│ binary       │  │              │
└──────┬───────┘  └──────┬───────┘
       │                 │
       │                 ▼
       │         ┌──────────────┐
       │         │ systemd      │
       │         │ hyper2kvm    │
       │         │ daemon       │
       │         └──────┬───────┘
       │                │
       └────────┬───────┘
                ▼
        ┌──────────────┐
        │ qcow2 Output │
        │ +  Libvirt   │
        └──────────────┘

Configuration Options

Option Type Default Description
Hyper2KVMDaemon bool false Enable daemon mode
Hyper2KVMInstance string ”” Systemd instance name
Hyper2KVMWatchDir string /var/lib/hyper2kvm/queue Watch directory
Hyper2KVMOutputDir string /var/lib/hyper2kvm/output Output directory
Hyper2KVMPollInterval int 5 Poll interval (seconds)
Hyper2KVMDaemonTimeout int 60 Timeout (minutes)

Deployment Scenarios

Scenario 1: Single Server (Auto-Detect)

# Start daemon
sudo systemctl enable --now hyper2kvm.service

# HyperSDK auto-detects and uses daemon
hyperexport --vm test-vm --output /tmp/test \
  --pipeline --hyper2kvm-daemon

Scenario 2: Multi-Instance (Provider-Specific)

# Start instances
sudo systemctl start hyper2kvm@vsphere.service
sudo systemctl start hyper2kvm@aws.service
sudo systemctl start hyper2kvm@azure.service

# Route to specific instance
hyperexport --provider vsphere --vm test-vm \
  --pipeline --hyper2kvm-daemon \
  --hyper2kvm-instance vsphere

Scenario 3: Dedicated Conversion Server

# Server 1: Export only (no daemon)
hyperexport --vm test-vm \
  --output /mnt/nfs/queue \
  --manifest \
  --pipeline=false

# Server 2: Daemon watches NFS-mounted queue
sudo systemctl start hyper2kvm.service
# Config: watch_dir=/mnt/nfs/queue, output_dir=/mnt/nfs/output

Benefits

  1. Reliability: systemd auto-restart on failure
  2. Resource Management: Memory/CPU limits via systemd
  3. Monitoring: systemctl status, journalctl integration
  4. Multi-Tenant: Multiple instances with different configs
  5. Security: Runs as dedicated hyper2kvm user with restricted permissions
  6. Batch Processing: Queue-based processing of multiple VMs
  7. Separation of Concerns: Export and conversion can run on different servers
  8. High Availability: Automatic failover to direct execution if daemon unavailable

Testing

Test Direct Mode

hyperexport --vm test-vm --output /tmp/test --pipeline

Test Daemon Mode

# With daemon running
hyperexport --vm test-vm --output /tmp/test \
  --pipeline --hyper2kvm-daemon

# Without daemon (should auto-fallback)
sudo systemctl stop hyper2kvm.service
hyperexport --vm test-vm --output /tmp/test \
  --pipeline --hyper2kvm-daemon

Monitor Daemon

# Check status
hyperctl daemon -op status
sudo systemctl status hyper2kvm.service

# View logs
sudo journalctl -u hyper2kvm.service -f

# Check queue and output
ls -lh /var/lib/hyper2kvm/queue/
ls -lh /var/lib/hyper2kvm/output/

Commits

All work has been committed to git:

  1. Add systemd daemon integration documentation (d587621)
    • Initial architecture and integration plan
  2. Add hyper2kvm systemd daemon integration (WIP) (773ffc1)
    • Core pipeline integration
    • Daemon detection and routing
    • API models
  3. Add hyper2kvm daemon configuration to CLI, TUI, and web dashboard (da3ce6c)
    • CLI flags for hyperexport
    • Interactive TUI with daemon options
    • Web dashboard UI components
  4. Add daemon management commands to hyperctl (1e6e127)
    • hyperctl daemon status/list commands
    • Systemctl integration
    • Pretty-printed output
  5. Add systemd unit files and deployment tooling for hyper2kvm (f5b2a2a)
    • Production systemd service files
    • Security hardening
    • Configuration templates
    • Installation script
    • Comprehensive documentation

Files Changed/Created

Modified Files (10):

New Files (13):

Implementation Statistics

Next Steps (Optional)

Remaining Low Priority Tasks:

Future Enhancements:

Conclusion

The hyper2kvm systemd daemon integration is feature-complete for production use. All high and medium priority tasks have been implemented:

✅ Core pipeline integration with auto-detection ✅ CLI flags for daemon configuration ✅ Interactive TUI with daemon options ✅ Web dashboard UI components ✅ Daemon management commands (hyperctl) ✅ Production systemd unit files ✅ Automated installation script ✅ Comprehensive documentation

The implementation provides a robust, secure, and scalable solution for deploying hyper2kvm as a system daemon, with full integration across all HyperSDK interfaces (CLI, TUI, and Web).

Date: 2026-01-24 Version: 1.0.0 Status: ✅ Complete

This site is open source. Improve this page.