NAME

OpenHVF::ImageCache - cache of installed OpenBSD disk images

SYNOPSIS

    use OpenHVF::ImageCache;
    my $cache = OpenHVF::ImageCache->new('~/.cache/openhvf');
    my $key   = $cache->key($vm_config);
    # Boot from a previous installation
    if (my $hit = $cache->lookup($key)) {
        $disk->create($name, undef, $hit->{base}, 'qcow2');
        $state->set_root_password($hit->{meta}{root_password});
    }
    # Publish a freshly installed disk
    $cache->store($key, $disk_path, { root_password => $password });
    for my $entry (@{ $cache->list }) {
        printf "%s %d bytes\n", $entry->{key}, $entry->{size};
    }

DESCRIPTION

Installing OpenBSD under TCG emulation costs tens of minutes. This module keeps the result so later runs skip it: a pristine, compacted copy of the disk taken the moment the installer finished, which subsequent VMs use as the backing image of a throwaway qcow2 overlay.

Entries live under the configured "cache_dir", beside the proxy cache that holds the miniroot and install sets:

    <cache_dir>/installed/<key>/base.qcow2              mode 0400
    <cache_dir>/installed/<key>/meta.json               mode 0600
    <cache_dir>/installed/<key>/snapshots/<name>.qcow2  mode 0400
    <cache_dir>/installed/<key>/snapshots/<name>.json   mode 0600

Entries are immutable and write-once. "store" builds one whole in a sibling ".tmp.*" directory and publishes it by renaming that directory, so a reader never sees one installation's base image beside another installation's metadata - a mismatch that looks live and then wedges every later boot with a root password that does not open the image.

    base.qcow2  <-  <name>.qcow2  <-  disk.qcow2

METHODS

new($cache_dir)

Construct a cache over $cache_dir, expanding a leading "~".

cache_dir

installed_dir

entry_dir($key)

base_path($key)

Locations, whether or not they exist.

key($vm_config)

Derive the cache key for a VM configuration hash, or "undef" when an input cannot be read - which leaves the caller with no key, and therefore no caching.

lookup($key)

Return "{ key, dir, base, meta }" for a complete entry, "undef" otherwise. A half-written entry is a miss, not an error.

store($key, $disk_path, $meta)

Compact $disk_path into the cache as the base image for $key and write $meta - which should carry the guest "root_password" - alongside it. Returns the base image path, or "undef" on any failure, including an attempt to overwrite a populated key. The caller degrades to a standalone disk.

list

Every complete entry, newest first, as "{ key, dir, base, meta, size, created_at, snapshots }".

remove($key)

Delete an entry and everything under it. True when the entry is gone.

sweep_temp

Remove ".tmp.*" trees left behind by an interrupted "store", including those of earlier processes. Returns the count removed.

key_for_path($path)

The key of the entry containing $path - a base image or a snapshot - or "undef" when $path lies outside the cache. Answers "which cached image is this working disk built on?".

snapshot_dir($key)

snapshot_path($key, $name)

Locations, whether or not they exist.

valid_snapshot_name($name)

Whether $name is usable. Names become file names inside the cache, so they must start with an alphanumeric and hold to word characters, dots and dashes, within a bounded length.

snapshot_store($key, $name, $disk_path, $meta)

Flatten the stopped working disk at $disk_path onto $key's base image and publish it as the named layer. $meta should carry the state fields the disk embodies - "installed" and the installed SSH public key - so a restore can reseed OpenHVF::State; the root password is copied from the base's own metadata rather than trusted from the caller. Returns the snapshot path, or "undef" on failure.

Re-saving an existing name replaces it, which is the normal second run of a provisioning script.

snapshot_lookup($key, $name)

Return "{ key, name, path, base, meta }" for a snapshot whose image, its metadata, and its backing chain all resolve; "undef" otherwise. A snapshot whose base has been removed is a miss, not an error, so a caller can fall back to provisioning from scratch instead of failing hard.

snapshot_list($key)

Sorted snapshots of an entry, as "{ name, path, size, created_at, meta }".

snapshot_remove($key, $name)

Delete a snapshot and its metadata. Safe in any order: snapshots are always direct children of the base, never of each other.

SECURITY

meta.json is mode 0600 and holds the generated guest root password, the same secret the VM state directory already keeps. Caching lengthens its life: it survives "openhvf destroy" and rotates only when the base key does. The guest permits password root login and QEMU forwards its SSH and serial console ports on every host interface, so the password is not a localhost-only secret. See openhvf(1).

SEE ALSO

OpenHVF::Disk, OpenHVF::Expect, OpenHVF::Image, OpenHVF::VM, openhvf(1)