hiperiso/config/README.md

hiperiso configuration

hiperiso is configured through a single JSON file placed on the data partition of the USB at /hiperiso/hiperiso.json. The format is Ventoy-compatible so existing Ventoy configs need only minor changes. Start from hiperiso.json.example.

JSON cannot contain comments, so every option is described here.

Location

<data partition>/
└── hiperiso/
    └── hiperiso.json      ← global config (copied from hiperiso.json.example)

Top-level sections

Section	Purpose
control	Default hypervisor/guest settings applied to every boot.
theme	GRUB2 menu theme.
menu_alias	Rename ISO entries in the menu.
menu_tip	Show a one-line tip under a menu entry.
iso_overrides	Per-ISO settings keyed by glob pattern.

control

Key	Type	Default	Meaning
default_ram	number	2048	Guest RAM in MB.
default_cpus	number	2	Guest vCPUs.
default_trace_level	string	standard	none | standard | detailed | full.
default_display	string	none	QEMU display: none | gtk | vnc.
default_vga	string	none	QEMU VGA: none | std | virtio.
fallback_no_kvm	boolean	true	Fall back to direct boot if /dev/kvm is missing.
net_dump	boolean	false	Capture guest network traffic to network.pcap.
timeout	number	10	GRUB2 menu auto-boot timeout in seconds.

These map directly to the kernel command-line parameters defined in INTERFACES.sh (HIPERISO_GUEST_RAM, HIPERISO_GUEST_CPUS, HIPERISO_TRACE_LEVEL, HIPERISO_DISPLAY, HIPERISO_VGA, HIPERISO_FALLBACK).

theme

Key	Type	Meaning
file	string	Path to a GRUB2 theme.txt.
gfxmode	string	GRUB2 graphics resolution.
gfxpayload	string	keep to preserve resolution for guest.

menu_alias / menu_tip

Both are arrays of objects with an iso path (relative to the data partition) and a value:

[
  { "iso": "/ISOs/ubuntu-24.04.iso", "alias": "Ubuntu 24.04 LTS" }
]

iso_overrides

A map of glob pattern → override object. The first matching pattern wins. Glob syntax matches Ventoy (anchored at the filename).

Key	Type	Meaning
ram	number	Override guest RAM (MB).
cpus	number	Override guest vCPUs.
tpm	boolean	Attach a virtual TPM (swtpm) for Windows 11.
secure_boot	boolean	Use Secure-Boot-enabled OVMF vars.
cpu_features	string[]	Extra CPU flags, e.g. ["vmx"] for nested virt.
trace_level	string	Override trace tier for this ISO.
display	string	Override display mode.
net_dump	boolean	Capture network traffic for this ISO.
qemu_extra_args	string[]	Raw extra arguments appended to the QEMU command line.

{
  "*./windows11*.iso": { "ram": 4096, "tpm": true, "cpu_features": ["vmx"] }
}

Standalone override files

config/iso_overrides/<name>.json holds a single override (see windows11.json). These are intended as reusable templates you can merge into iso_overrides or ship alongside a curated ISO set.

Trace tiers (recap)

Tier	Events	Overhead
standard	serial + basic disk/CD-ROM I/O	~0%
detailed	+ PCI config-space + port I/O	low
full	+ every MMIO access	10–100×
none	serial only (no trace)	0%

The corresponding event lists live in logging/trace-*.events and are copied to the ESP at /EFI/hiperiso/trace/ during install.