KVM Commands

Overview

The netapi kvm command group provides CLI access to KVM hypervisors via SSH and virsh commands. Manage virtual machines, snapshots, and backup VM definitions.

Prerequisites

Load secrets before using KVM commands:

dsource d000 dev/network

Required environment variables:

Variable Description Required

KVM_HOST

KVM hypervisor IP or hostname

Yes (or SSH alias)

KVM_SSH_ALIAS

SSH config alias (takes precedence)

No

KVM_USER

SSH username (default: root)

No

Example dsec config:

# In dev/network
KVM_HQ_01_HOST=kvm-01.inside.domusdigitalis.dev
KVM_HQ_01_IP=10.50.1.99
KVM_HQ_01_USER=root
KVM_HQ_01_SSH_ALIAS=kvm-host

# Active targets
KVM_HOST={{KVM_HQ_01_IP}}
KVM_USER={{KVM_HQ_01_USER}}
KVM_SSH_ALIAS={{KVM_HQ_01_SSH_ALIAS}}

VM Listing

list

List all VMs on the KVM host:

netapi kvm list

With state information:

netapi kvm list --state
Sample Output
     Virtual Machines
┏━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Name         ┃ State    ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ pfSense-FW01 │ running  │
│ 9800-CL-WLC  │ running  │
│ ipsk-manager │ running  │
│ ise-02       │ running  │
│ home-dc01    │ running  │
│ certmgr-01   │ running  │
│ keycloak-01  │ running  │
│ ise-01       │ shut off │
└──────────────┴──────────┘

JSON output:

netapi kvm list --state -f json

info

Get detailed VM information:

netapi kvm info myvm

Returns:

  • State (running, shut off)

  • Memory allocation

  • vCPU count

  • UUID

VM Control

start

Start a VM:

netapi kvm start myvm

stop

Gracefully shutdown a VM:

netapi kvm stop myvm

Force stop (like pulling the power):

netapi kvm stop myvm --force

reboot

Reboot a VM:

netapi kvm reboot myvm

Snapshots

snapshots

List snapshots for a VM:

netapi kvm snapshots myvm

snapshot

Create a snapshot:

# Auto-generated name (timestamp)
netapi kvm snapshot myvm

# Named snapshot
netapi kvm snapshot myvm --name before-update

revert

Revert to a snapshot:

netapi kvm revert myvm before-update

Backup

backup

Backup VM definitions (XML) to local storage or NAS.

# Backup single VM
netapi kvm backup --name myvm

# Backup all VMs
netapi kvm backup --all

# Backup all VMs and upload to NAS
netapi kvm backup --all --upload-nas

# Specify output directory
netapi kvm backup --all --output /custom/backup/path

# Specify NAS destination
netapi kvm backup --all --upload-nas --nas-folder /Backups/kvm
Sample Output
╭──────────────────────────────────────────────────╮
│             KVM VM Definition Backup             │
╰──────────────────────────────────────────────────╯
  Host: kvm-host
  VMs: 8
  Output: /home/user/backups/kvm/kvm-host

  ✓ pfSense-FW01 → pfSense-FW01-20260124-191735.xml
  ✓ 9800-CL-WLC → 9800-CL-WLC-20260124-191735.xml
  ✓ ipsk-manager → ipsk-manager-20260124-191735.xml
  ✓ ise-02 → ise-02-20260124-191735.xml
  ✓ home-dc01 → home-dc01-20260124-191736.xml
  ✓ certmgr-01 → certmgr-01-20260124-191736.xml
  ✓ keycloak-01 → keycloak-01-20260124-191736.xml
  ✓ ise-01 → ise-01-20260124-191736.xml

✓ Backed up 8/8 VMs
  Timestamp: 2026-01-24T19:17:36.167251

Uploading to Synology NAS...
  ✓ pfSense-FW01-20260124-191735.xml
  ✓ 9800-CL-WLC-20260124-191735.xml
  ...
✓ Uploaded 8 files to /kvm_backups

Options:

Option Short Description

--name

-n

Specific VM to backup

--all

-a

Backup all VMs

--output

-o

Output directory

--upload-nas

-u

Upload to Synology NAS

--nas-folder

NAS destination folder

NAS Upload Requirements

For --upload-nas to work, load storage secrets:

dsource d000 dev/storage

Required variables in dev/storage:

Variable Description

SYNOLOGY_IP

NAS IP address

SYNOLOGY_USER

API username

SYNOLOGY_PASS

API password

KVM_BACKUP_PATH

Destination folder (default: /kvm_backups)

Use Cases

Daily VM Backup Script

#!/bin/bash
# Daily KVM backup with NAS upload
eval "$(dsec source d000 dev/network)"
eval "$(dsec source d000 dev/storage)"

netapi kvm backup --all --upload-nas

Pre-Update Snapshot

# Create snapshot before system update
netapi kvm snapshot keycloak-01 --name pre-update-2026-01-24

# Perform update...

# If something goes wrong, revert
netapi kvm revert keycloak-01 pre-update-2026-01-24

Disaster Recovery

The XML backup contains the full VM definition needed to recreate the VM:

# On recovery host
virsh define /backup/myvm-20260124-191735.xml
virsh start myvm
XML backups contain VM definitions only, not disk images. For full disaster recovery, combine with disk-level backups (e.g., Borg, rsync).