vmshared

func DecrementSnapshotRefcount ¶

func DecrementSnapshotRefcount(vmName, snapName string) error

DecrementSnapshotRefcount decreases the refcount. Floors at 0.

func DeleteSnapshot ¶

func DeleteSnapshot(opts SnapshotDeleteOpts) error

DeleteSnapshot is the mode-aware deletion. Refuses while refcount > 0 unless Force is set.

func DetectRuntimeHostVendor ¶

func DetectRuntimeHostVendor() string

DetectRuntimeHostVendor reads /proc/cpuinfo to identify the host CPU vendor (GenuineIntel | AuthenticAMD | ""). Used by RenderDomain / RenderQemuArgv to auto-append the correct nested-virt feature (vmx vs svm).

func EnsurePerVmNvram ¶

func EnsurePerVmNvram(templatePath, perVmDir string) (string, error)

EnsurePerVmNvram copies the OVMF_VARS template to a per-VM NVRAM file on first use. Returns the absolute path of the per-VM NVRAM (which is what rt.NVRAMPath should be set to). Idempotent: if the per-VM file already exists, it's preserved (contains the guest's accumulated UEFI variables).

func IncrementSnapshotRefcount ¶

func IncrementSnapshotRefcount(vmName, snapName string) error

IncrementSnapshotRefcount increases the refcount on the named snapshot. Used by clone/ephemeral instantiation paths.

func IsDeviceElement ¶

func IsDeviceElement(snippet string) bool

IsDeviceElement returns true if the XML snippet's root element belongs inside <devices>.

func KeyToRootTmpfilesD ¶

func KeyToRootTmpfilesD(pubkey string) string

KeyToRootTmpfilesD converts an SSH public key to a systemd tmpfiles.d config that creates /root/.ssh/authorized_keys. Matches bcvk's key_to_root_tmpfiles_d.

func KeyToUserTmpfilesD ¶

func KeyToUserTmpfilesD(user, home, pubkey string) string

KeyToUserTmpfilesD generates a systemd tmpfiles.d config that delivers a per-VM SSH key for the named user. The user account itself must already exist in the rootfs (created at build time by the bootloader install template OR by cloud-init); this function only delivers the *key*, never bakes one into the image.

SMBIOS-vs-cloud-init priority: the key is written to a ROOT-owned, sshd- checked file at /etc/ssh/authorized_keys.d/<user>, and a sshd_config.d drop-in widens AuthorizedKeysFile to check BOTH ~/.ssh/authorized_keys (cloud-init's domain) AND that file. systemd-tmpfiles applies this BEFORE sshd starts, so the SMBIOS key is ALWAYS accepted even if cloud-init later rewrites the user's own authorized_keys — SMBIOS owns the drop-in location, cloud-init owns ~/.ssh, and sshd honors both. The key is ALSO written to ~/.ssh/authorized_keys as a fallback for any guest sshd that ignores the drop-in (so the key works whether or not the widened path takes effect).

The home path defaults to /home/<user> when empty.

func KillQemuByPID ¶

func KillQemuByPID(stateDir string)

KillQemuByPID force-kills a direct-QEMU VM by the PID recorded in its state dir (the last-resort path when QMP graceful/force shutdown is unavailable). Pure OS process kill — no govmm.

func LibvirtSessionSocket ¶

func LibvirtSessionSocket() string

LibvirtSessionSocket returns the path to the user's libvirt session socket. Modern libvirt (≥ 8.0) uses per-driver modular daemons (virtqemud-sock); legacy libvirt (< 8.0) uses the monolithic libvirt-sock. Probe the modular socket first (every current distro), then the monolithic one. Returns "" when neither exists — never a path that was not found.

func LibvirtSessionSocketWithProbes ¶

func LibvirtSessionSocketWithProbes() (picked string, probed []string)

func QemuAlive ¶ added in v0.2026226.1201

func QemuAlive(stateDir string) bool

QemuAlive reports whether the QEMU process recorded in <stateDir>/qemu.pid is still running AND is the process that pidfile belongs to.

A pidfile alone is not liveness, and neither is a bare Signal(0) probe: PIDs are recycled, so a dead VM's stale pidfile can name a PID that now belongs to something else entirely. Two checks close that:

1. Signal(0) — the PID exists and is signalable.
2. /proc/<pid>/cmdline contains "-pidfile <stateDir>/qemu.pid" — the running process is not merely SOME qemu, it is the qemu started for THIS state dir. Matching the bare "qemu-system" substring is not enough: a PID recycled onto a DIFFERENT VM's qemu would satisfy it, and the caller would treat a stopped VM as running.

The second check rests on a CALLER invariant, not a renderer guarantee, and the distinction matters to anyone adding a launch path. RenderQemuArgv appends `-pidfile` CONDITIONALLY — `if paths.PidFile != ""` (qemu_render.go) — so an empty PidFile is explicitly permitted there. What makes the argv reliable is that every production launch sets it: VmRuntimePaths.PidFile is always `<vmStateDir>/qemu.pid`, byte-identical to what this function computes, and `vm start` relaunches from the persisted command file rendered with that same argv. A future caller that leaves PidFile empty would make QemuAlive report its VMs DEAD — the worse failure direction, since callers act on "not running" by starting a second qemu. Set PidFile, or teach this predicate the new launch shape.

/proc/<pid>/cmdline is NUL-separated, so the flag and its value are two adjacent NUL-terminated entries rather than one space-joined string.

Shared by `vm start` (the idempotent already-running guard), `vm list` (the state scan), and the preempt arbiter's holder probe — one liveness predicate, R3. A weaker copy in any of them means one caller can believe a stopped VM is running (or the reverse) while another does not.

func QemuSystemBinary ¶

func QemuSystemBinary() string

QemuSystemBinary returns the architecture-appropriate QEMU binary name.

func RenderCloudInit ¶

func RenderCloudInit(spec *VmSpec, rt CloudInitRuntimeParams) (userData, metaData, networkConfig string, err error)

RenderCloudInit produces the three NoCloud seed ISO payloads from a VmSpec plus runtime parameters. Pure function — no filesystem or network calls.

- userData → written to cidata/user-data (prefixed with #cloud-config) - metaData → written to cidata/meta-data (instance-id + hostname) - networkCfg → written to cidata/network-config (optional; empty if unset)

Defaults applied automatically (D15):

1. VmSsh.User added to users: with sudo + ssh_authorized_keys (if the key-injection channel is enabled AND SSHPublicKey != "")

2. Minimum packages: {<ssh-pkg>, curl, tar} unioned with the user's Packages, where <ssh-pkg> is `openssh-server` on debian/ubuntu and `openssh` elsewhere. Delivered via the `packages:` cloud-config key on every distro EXCEPT pacman-family (arch/archarm/manjaro/endeavouros/cachyos), where it is instead PREPENDED to runcmd as `pacman -Sy --needed --noconfirm <union>` (db refresh + install-only; a bare -S 404s on rotated mirrors, and a full -Syu destabilizes the live guest — see the runcmd comment) and the `packages:` key is omitted entirely. Why: cloud-init's own package-install module invokes `pacman -S` without `--needed`, so on an image that already ships the minimum set it REINSTALLS them, and reinstalling openssh re-triggers its host-key-regen hook while the base image's socket-activated sshd is already listening — racing a live key-file rewrite against new connections. apt/dnf installs are naturally no-op-idempotent when the package is present, so only the pacman-family path needs the rewrite.

   The branch reads Source.Distro DIRECTLY. That field is REQUIRED and closed to #DistroID (schema/vm.cue), so there is nothing to infer: an omitted or misspelled distro is a validation error at author time. An earlier revision left it optional and inferred `arch`/`alpine` from base_user, defaulting everything else to Arch/Fedora conventions — which rendered `openssh` and `enable --now sshd` onto Debian-family guests and left them unreachable. That inference is DELETED, not narrowed — the renderer no longer guesses a distro.

3. Minimum runcmd: the sshd START prepended (after the pacman install command on pacman-family distros, per #2). On systemd it is `systemctl enable --now <unit>` — `ssh` on debian/ubuntu, `sshd` elsewhere, chosen by sshUnitForDistro from the required Source.Distro. On OpenRC (Alpine) it is `rc-update add sshd default && rc-service sshd start`.

4. charly_install: NOT a cloud-init concern — the vm deploy's PrepareVenue delivers charly post-boot (auto/scp stage it; skip verifies). No charly download runcmd.

5. VmCloudInit.Extra: raw cloud-config YAML appended as a second document (separated by ---) if non-empty

func RenderInstallerSeed ¶ added in v0.2026242.940

func RenderInstallerSeed(inst *spec.DistroInstaller, ctx spec.InstallerSeedContext) (map[string]string, error)

RenderInstallerSeed renders a distro's unattended-installer answers volume.

The split is deliberate and is the whole design: the DISTRO owns the FORMAT (which files, with what names, in what syntax — archinstall JSON, kickstart, preseed, Subiquity autoinstall), and the VM ENTITY owns the DATA (this username, this disk, these SSH keys). A renderer that guessed the format from the distro name is the failure mode validateSourceDistro's own comment records as having burned this codebase already.

Pure: no filesystem, no network, no crypt(). The caller hashes the password before building ctx, so a PLAINTEXT password never reaches a template, a log, or a temp file.

Returns path-inside-the-volume -> rendered content, ready for WriteLabeledISO.

func RenderQemuArgv ¶

func RenderQemuArgv(spec *VmSpec, rt VmRuntimeParams, paths QemuRuntimePaths) []string

RenderQemuArgv produces the full argv for `qemu-system-<arch>` from a VmSpec + VmRuntimeParams + QemuRuntimePaths. Pure function — no filesystem or process state side effects.

Covers the intersection of libvirt schema features that map cleanly to QEMU: machine, cpu (D16 defaults), firmware (D17 pflash), disks (root + seed iso D5 + additional), network (user-mode hostfwd), SMBIOS credentials (D13), RNG, balloon, qemu-guest-agent channel.

Structured libvirt features without a QEMU mapping (virtiofs, launch_security beyond SEV, PCI hostdev, graphics/spice, TPM) are skipped with a warning comment inserted via the caller's log output — this function only returns argv.

func ResolveKeyInjectionChannels ¶

func ResolveKeyInjectionChannels(spec *VmSpec) (smbios, cloudInit bool)

ResolveKeyInjectionChannels applies the D13 auto-defaults and explicit-wins merging to produce the effective (smbios, cloudInit) toggle state for a VmSpec. Returns the booleans persisted into VmDeployState.KeyInjectionResolved.

func ResolveOvmfForSpec ¶

func ResolveOvmfForSpec(spec *VmSpec, vmStateDir string) (codePath, nvramPath string, err error)

ResolveOvmfForSpec is a convenience wrapper: detects the host distro, picks the correct OVMF_CODE/OVMF_VARS pair for the VmSpec's firmware setting, and provisions the per-VM NVRAM file. Returns (CodePath, NVRAMPath) — the two values needed to populate VmRuntimeParams.

Returns ("", "", nil) when firmware == "bios" (BIOS boot needs no firmware images).

func ResolveVmCpus ¶

func ResolveVmCpus(spec *VmSpec) int

ResolveVmCpus picks the spec-declared CPU count or falls back to 2.

func ResolveVmRam ¶

func ResolveVmRam(spec *VmSpec) string

ResolveVmRam picks the spec-declared RAM or falls back to "4G".

func RevertSnapshot ¶

func RevertSnapshot(vmName, snapName string) error

RevertSnapshot is the mode-aware revert.

func SeedFileNames ¶ added in v0.2026242.940

func SeedFileNames(files map[string]string) []string

SeedFileNames returns the rendered file paths in sorted order. Only for diagnostics and tests — the ISO writer sorts internally so its output is reproducible.

func SmbiosCredForSSH ¶

func SmbiosCredForSSH(user, home, pubkey string) string

SmbiosCredForSSH generates the SMBIOS type 11 credential string that delivers a per-VM SSH key to the named user via systemd-tmpfiles. When user == "" or user == "root", the key is delivered to /root/.ssh. Returns: "io.systemd.credential.binary:tmpfiles.extra=<base64>"

func SnapshotBackingStalePath ¶ added in v0.2026258.1713

func SnapshotBackingStalePath(entry *SnapshotEntry) (string, error)

SnapshotBackingStalePath reports whether an external snapshot's backing chain has been REBUILT after the snapshot was captured, returning the offending backing file path. A non-empty return means the snapshot is STALE.

Why a snapshot goes stale: the guest filesystem captured inside the snapshot (btrfs, ext4) references inodes in the BASE disks of its backing chain. When a later `vm build` rewrites one of those base disks (a re-provision, a disk-root change), the snapshot's superblock still points at the OLD data, so any clone backed by it boots into a broken/grub-rescue guest. The mtime ordering — a backing file newer than the snapshot's `Created` — is the detectable proxy.

This is the ONE staleness definition (R3). The clone path (candy/plugin-vm) and the capture path (CreateSnapshot below) MUST agree on it: the clone guard already refuses a stale snapshot with an actionable error, so if capture did not also treat the same snapshot as stale it would refuse to refresh it (`already exists`), making the clone guard's promised recovery impossible.

Second-precision comparison: the registry stores `Created` at RFC3339 second precision while a capture-finalization write can land sub-second later, so a same-second mtime is NOT stale (a false STALE would force needless re-captures).

func VmDiskDir ¶

func VmDiskDir(vmName string) (string, error)

VmDiskDir returns the per-VM directory holding a built disk image (disk.qcow2) and, for cloud_image/bootstrap/clone sources, its NoCloud seed.iso. The path is namespaced by the DISK SOURCE (the kind:vm ENTITY), so it is the shared read-only BASE every per-deploy overlay backs onto — building or creating one entity never reuses a SIBLING entity's disk or — critically — its stale seed.iso, whose embedded SSH key would mismatch this VM's own id_ed25519 and silently break the deploy's authentication.

The root is CONFIGURABLE (vm.image_dir setting / CHARLY_VM_IMAGE_DIR env, default "image") — never a hardcoded literal (the former "output" default was a footgun: it read as disposable build scratch, so it got deleted as such while live VMs' backing chains still pointed into it). The (string, error) shape mirrors VmStateRoot: a root-resolution failure is PROPAGATED, never silently substituted with a different root (which would point a live VM at a path its backing chain does not use — the exact failure mode this replaces).

func VmDiskRoot ¶ added in v0.2026258.154

func VmDiskRoot() (string, error)

VmDiskRoot resolves the root directory for built VM disk images. Precedence: the CHARLY_VM_IMAGE_DIR env var > the `vm.image_dir` config setting > the built-in default "image". A relative result is intentionally returned as-is: call sites resolve it against the working project (the disk is a build product of the project's own VMs), exactly like the former hardcoded relative path.

A MISSING config is not an error (LoadRuntimeConfig returns a zero config, nil) — the "image" default applies. A non-nil error means the config file exists but could not be read; that is PROPAGATED (never masked by substituting a root).

func VmStateRoot ¶ added in v0.2026203.730

func VmStateRoot() (string, error)

VmStateRoot resolves the root directory for per-VM host state. Honors CHARLY_VM_STATE_DIR when set (trimmed, must be non-empty, must be absolute — a relative override would resolve against whatever cwd happens to be active at each call site, defeating the whole point of a stable per-worktree pin); otherwise falls back to the default ~/.local/share/charly/vm.

func WriteJSON ¶

func WriteJSON(w io.Writer, v any) error

WriteJSON encodes v as indented JSON to w (the `--json` output helper; the `charly vm snapshot list --json` path uses it).

func WriteLabeledISO ¶ added in v0.2026242.940

func WriteLabeledISO(outPath, volumeID string, files map[string]string) error

WriteLabeledISO packs files into an ISO9660+Joliet+RockRidge image at outPath, labelled volumeID. The map is path-inside-the-volume -> content; keys must be plain names or relative paths, and content is written verbatim.

The LABEL is what an unattended installer discovers the volume by — "CIDATA" for cloud-init NoCloud, "OEMDRV" for Anaconda kickstart — so it is a parameter rather than a constant. Case is preserved exactly as given: xorriso's -volid writes what it is handed, verified both ways, which is why a distro's #DistroInstaller.volume_id can be matched case-sensitively without needing a vfat fallback.

func WriteSeedISO ¶

func WriteSeedISO(outPath, userData, metaData, networkConfig string) error

WriteSeedISO builds a NoCloud cidata ISO at outPath. Takes the three rendered strings from RenderCloudInit (user-data, meta-data, and optional network-config) and shells out to xorriso to pack them into an ISO9660+Joliet+RockRidge image labeled cloudInitVolumeID.

The guest's cloud-init scans for a filesystem labeled "CIDATA" or "cidata" (it tries both cases) on first boot. Files inside:

user-data       — the #cloud-config YAML (required)
meta-data       — instance-id + hostname (required, can be empty)
network-config  — v2 network schema (optional)

Returns an error if xorriso isn't installed or the ISO write fails. charly doctor checks for xorriso and suggests the install package.

This is a thin convenience over WriteLabeledISO: cloud-init's NoCloud datasource is one answers-volume format among several, and an unattended distro installer (archinstall, kickstart, preseed, autoinstall) wants the same ISO writer with a different label and a different file set. There is exactly ONE ISO writer here, and this is its NoCloud face.