Ozone VM Configuration JSON Schema Field Reference

Complete JSON field reference for Ozone VM config files. Covers all VMInfo, CPU, Memory, Network, and Disk fields with Go types and JSON keys.

Every Ozone VM is described by a single JSON document stored at vms/<vmname>.json. The document has five top-level objects, each mapping one-to-one to a typed Go struct in the vmparser package. The sections below document every field, its JSON key, its Go type, and its meaning.

Complete example

{
  "vm": {
    "name": "web-01",
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-06-01T12:00:00Z"
  },
  "cpu": {
    "cores": 4,
    "type": "host"
  },
  "memory": {
    "size_mb": 2048
  },
  "network": {
    "interface": "eth0",
    "type": "virtio",
    "mac": "52:54:00:ab:cd:ef"
  },
  "disk": {
    "name": "web-01-disk",
    "path": "/var/lib/ozone/images/web-01.qcow2",
    "size_gb": 20.0,
    "format": "qcow2"
  }
}

---

vm — VMInfo

Identity fields that uniquely describe the virtual machine.

name · string · required

Human-readable name of the VM. Must match the filename (vms/<name>.json). Used as the primary key for all vmparser functions.

uuid · string · required

Universally unique identifier for the VM in standard UUID v4 format (e.g. 550e8400-e29b-41d4-a716-446655440000). Passed to QEMU as the machine UUID.

created_at · string · required

ISO 8601 timestamp recording when the VM was first created (e.g. 2024-06-01T12:00:00Z). Informational only — not used at runtime.

---

cpu — CPU

CPU resource allocation for the virtual machine.

cores · int · required

Number of virtual CPU cores to expose to the guest OS. Maps to QEMU’s -smp argument.

type · string · required

CPU model string passed to QEMU’s -cpu flag. Common values include host (pass-through the host CPU) or specific model names such as qemu64.

---

memory — Memory

Memory allocation for the virtual machine.

size_mb · int · required

Amount of RAM in megabytes to allocate to the guest. Maps to QEMU’s -m argument. For example, 2048 allocates 2 GiB.

---

network — Network

Network interface configuration for the virtual machine.

interface · string · required

Name of the host network interface or TAP device the VM is attached to (e.g. eth0, virbr0).

type · string · required

Network device model presented to the guest. Common values are virtio (paravirtualised, highest performance) and e1000 (emulated Intel NIC for broad guest compatibility).

mac · string · required

MAC address assigned to the guest network interface in colon-separated hex notation (e.g. 52:54:00:ab:cd:ef). The 52:54:00 prefix is the QEMU vendor OUI by convention.

---

disk — Disk

Primary block device configuration for the virtual machine.

name · string · required

Logical name for the disk, used for identification within Ozone (e.g. web-01-disk). Not passed directly to QEMU.

path · string · required

Absolute path to the disk image file on the host filesystem (e.g. /var/lib/ozone/images/web-01.qcow2). Passed to QEMU as the drive file.

size_gb · float64 · required

Logical size of the disk in gigabytes. Stored as a JSON number with decimal precision (e.g. 20.0). Used when provisioning the image; QEMU itself reads the actual size from the image file.

format · string · required

Disk image format string passed to QEMU’s -drive format= option. Typical values are qcow2 (copy-on-write, supports snapshots) and raw (flat binary, maximum compatibility).