VM Edit Settings

Synced read-only from /home/synnet/mirrors/synvirt-product/docs/EDIT_SETTINGS.md. Edit at the source, not here.

VM Edit Settings

Three top-level tabs, one canonical PATCH endpoint, one batch task per save.

Endpoints

• GET /api/v1/vms/{uuid}/settings — current settings.
• GET /api/v1/vms/{uuid}/settings/editability — per-field editability matrix { editable: bool, reason: string|null }.
• PATCH /api/v1/vms/{uuid}/settings — apply a partial diff.

PATCH semantics:

1. Daemon validates each touched field against the editability matrix. Locked fields surface as E_OBS_EDITABILITY with the reason.
2. Each field change becomes one task (vm.edit.cpu, vm.edit.memory, vm.edit.disk_add, …) under a parent vm.edit.batch task — visible in /monitor/tasks and the VM detail view.
3. The libvirt domain is updated through synvirt-libvirt deltas, never by regenerating the XML from scratch.
4. Each successful field write lands in edit_settings_audit with (old, new, user, task_id, success=1). Failures land with success=0 and the curated error_code / error_msg.
5. If a partial apply hits an error mid-batch, the daemon attempts a rollback on the already-applied subtasks. If rollback is not possible, an error event is recorded and surfaced in the audit row.

Tabs

Virtual Hardware

• CPU — total cores, cores per socket (sockets derived), CPU hot-add, reservation / limit / shares (collapsed by default).
• Memory — size MiB, hot-add, ballooning, reservation / limit / shares.
• Hard disks — list of (size_gib, bus, cache_mode, discard, iothread, datastore) rows. Add / remove via per-row buttons. Bus options: virtio-blk, virtio-scsi, sata, ide.
• Controllers — SCSI / SATA / IDE model selectors (next iteration).
• Network adapters — virtswitch + virtlan + model + MAC + connected.
• CD/DVD drives — source (datastore_iso / client_iso / host_device / none), iso_path, connected.
• Video — type, vram_kib.
• USB controller — xhci, ehci, or none.
• TPM — none or swtpm.
• Serial port — file / tcp / pty / none.

VM Options

• Boot order (drag-and-drop list).
• Firmware (bios / uefi), secure_boot (UEFI only).
• VM debugging / troubleshooting toggles.
• Power management actions on shutdown / reboot / suspend.
• Latency sensitivity (normal / high).

Advanced Parameters

Free-form key / value table validated against the configured whitelist. Whitelist patterns live in /etc/synvirt/observability.yaml → edit_settings.advanced_parameters_whitelist. Each segment supports * as a wildcard. Defaults shipped:

- cpu.feature.*
- clock.timer.*
- memorybacking.hugepages

Whitelist violations surface as E_OBS_WHITELIST and the field is not applied.

Hot-plug rules

Field group	Powered off	Running, hot-add ON	Running, hot-add OFF
CPU cores	✅ any value	✅ increase only	🔒
CPU hot-add toggle	✅	🔒	🔒
Memory size	✅ any value	✅ increase only	🔒
Memory hot-add toggle	✅	🔒	🔒
Disk add (virtio)	✅	✅	✅
Disk remove (virtio)	✅	✅	✅
Disk resize	✅	depends on bus	depends on bus
Disk bus change	✅	🔒	🔒
NIC add / remove (virtio-net / e1000)	✅	✅	✅
NIC model change	✅	🔒	🔒
CD/DVD media swap	✅	✅	✅
Controllers, firmware, BIOS	✅	🔒	🔒
Video card type	✅	🔒	🔒
Boot order	✅	🔒	🔒
Advanced parameters (whitelisted)	✅	🔒	🔒

Locked-field UI: input renders read-only with a tooltip carrying the reason from the editability matrix (typically “Power off the VM to change ”).

Audit

edit_settings_audit rows are queryable via GET /api/v1/vms/{uuid}/audit/edit-settings (next iteration). Today the rows are visible by SQL on /var/lib/synvirt/observability.db for forensic review.

Every row carries:

• timestamp — RFC 3339 / millisecond UTC.
• vm_uuid, vm_name — denormalised so audit rows survive renames.
• user — operator id from PAM.
• section, field — where the change landed.
• old_value, new_value — JSON-encoded scalars or short objects.
• task_id — link to the parent batch task.
• success, error_code, error_msg — terminal outcome.