# hiperiso configuration

hiperiso is configured through a single JSON file placed on the **data
partition** of the USB at `/hiperiso/hiperiso.json`. 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:

```json
[
  { "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.
Patterns are matched against 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.|

```json
{
  "*./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.