Configuration Reference

Complete reference for QuantaVirt VM configuration files. VMs are defined using JSON configuration files that specify CPU topology, memory allocation, storage devices, network interfaces, PQC settings, and boot behavior. All fields are documented with types, defaults, and valid ranges.

Configuration Overview #

VM configuration files are stored in /var/lib/quantavirt/configs/ by default. The configuration is a JSON document validated against the QuantaVirt schema at VM creation time. Configuration files can be created manually, generated by the CLI wizard (quantavirt vm create --interactive), or exported from the GUI.

# Validate a config without creating the VM
quantavirt vm validate --config /path/to/vm.json

# Create VM from config
quantavirt vm create --config /path/to/vm.json

# Export running VM config
quantavirt vm export ubuntu-server --output ubuntu-server.json

VM Configuration Schema #

Top-level structure of a VM configuration document:

CPU Configuration #

Memory Configuration #

Storage Devices #

Storage devices are defined in the devices.storage array. Each entry defines a block device presented to the guest.

Network Devices #

Graphics & Console #

Boot Configuration #

PQC Configuration #

Hypervisor-Level Settings #

These settings are configured via kernel parameters (boot command line) or the global configuration file /etc/quantavirt/quantavirt.conf, not per-VM JSON.

Complete Examples #

Minimal Linux Server

{
  "name": "minimal-linux",
  "cpu": { "count": 1 },
  "memory": { "size": "512M" },
  "devices": {
    "storage": [{ "type": "virtio-blk", "path": "/var/lib/quantavirt/images/minimal.qcow2" }],
    "network": [{ "type": "virtio-net", "network": "default" }],
    "console": { "type": "virtio-console" }
  }
}

High-Performance Database Server

{
  "name": "db-server",
  "cpu": {
    "count": 16,
    "model": "host",
    "topology": { "sockets": 2, "cores": 4, "threads": 2 },
    "pin": [{"vcpu":0,"pcpu":0},{"vcpu":1,"pcpu":1}],
    "numa_node": 0
  },
  "memory": { "size": "64G", "hugepages": true, "hugepage_size": "1G", "prealloc": true },
  "devices": {
    "storage": [
      { "type": "virtio-blk", "path": "/dev/nvme0n1p4", "format": "raw", "cache": "none", "io": "native", "queues": 16 }
    ],
    "network": [
      { "type": "virtio-net", "network": "internal", "queues": 16, "vhost": true, "mtu": 9000 }
    ]
  }
}

PQC-Secured Confidential VM

{
  "name": "confidential-vm",
  "cpu": { "count": 4, "model": "EPYC" },
  "memory": { "size": "8G", "encrypted": true },
  "devices": {
    "storage": [
      { "type": "virtio-blk", "path": "/var/lib/quantavirt/images/confidential.qcow2", "encrypted": true }
    ],
    "network": [
      { "type": "virtio-net", "network": "secure", "pqc_tunnel": true }
    ]
  },
  "pqc": {
    "enabled": true,
    "backend": "quac100",
    "attestation": { "enabled": true, "algorithm": "ML-DSA-87" },
    "storage_encryption": { "enabled": true, "kem": "ML-KEM-1024", "aead": "AES-256-GCM" }
  },
  "security": {
    "type": "sev-snp",
    "policy": { "debug": false, "migrate": false, "single_socket": true }
  }
}