Struct Snapshot 

pub struct Snapshot { /* private fields */ }

A wrapper around a SharedMemory reference and a snapshot of the memory therein

Implementations

impl Snapshot

pub fn save(&self, path: impl AsRef<Path>, tag: &OciTag) -> Result<OciDigest>

Save this snapshot into an OCI Image Layout directory on disk. The saved snapshot can be loaded later with Snapshot::load.

Returns the OciDigest of the manifest that was written, which Snapshot::load accepts as a stable handle to this exact snapshot.

path

The OCI Image Layout directory to write to. The directory at path is created if absent. Its parent directory must exist.

If path holds no OCI layout, a new one is created. If it holds one, this snapshot is added alongside the others. If path holds something that is not a readable OCI layout, the call fails and the directory is left unchanged.

tag

A standard OCI tag that names this snapshot within the layout. Snapshot::load can load the snapshot back by this tag.

A tag points to one snapshot at a time. If the layout has a snapshot under this tag, the tag is moved to the new snapshot. The old snapshot’s data stays on disk, reachable by its digest but not by this tag. Snapshots under other tags are untouched.

Portability

Snapshot images are bound to the specific CPU architecture, hypervisor, and CPU vendor that the snapshot was created on. For example, a snapshot taken on an Intel x86_64 host with KVM can only be loaded on an Intel x86_64 host running KVM. Loading on any other host is rejected. A future version may relax this binding once a wider compatibility set is proven safe.

Compatibility

While Hyperlight is at version 0.x.y the on-disk format is not stable. A snapshot written by one Hyperlight version is not guaranteed to load on a different Hyperlight version. An incompatible snapshot is always rejected at load time with a clear error. It can never load and then misbehave once the guest is running. Any release that breaks the format is called out in the Hyperlight changelog.

Examples

let mut sandbox: MultiUseSandbox = UninitializedSandbox::new(
    GuestBinary::FilePath("guest.bin".into()),
    None,
)?.evolve()?;

// Capture the initialized state and write it to an OCI layout on disk.
let snapshot = sandbox.snapshot()?;
let tag = OciTag::new("latest")?;
let digest = snapshot.save("./guest_snapshot", &tag)?;

pub fn load( path: impl AsRef<Path>, reference: impl Into<OciReference>, ) -> Result<Self>

Load a snapshot from an OCI Image Layout directory produced by Snapshot::save.

path

The OCI Image Layout directory to read from. It must hold a readable OCI layout containing at least one Hyperlight snapshot.

reference

Determines which snapshot in the layout to load, given as either an OciTag or an OciDigest. Loading fails if no snapshot in the layout has the given tag or digest.

Portability

Snapshot images are bound to the specific CPU architecture, hypervisor, and CPU vendor that the snapshot was created on. For example, a snapshot taken on an Intel x86_64 host with KVM can only be loaded on an Intel x86_64 host running KVM. Loading on any other host is rejected. A future version may relax this binding once a wider compatibility set is proven safe.

Compatibility

While Hyperlight is at version 0.x.y the on-disk format is not stable. A snapshot written by one Hyperlight version is not guaranteed to load on a different Hyperlight version. An incompatible snapshot is always rejected at load time with a clear error. It can never load and then misbehave once the guest is running. Any release that breaks the format is called out in the Hyperlight changelog.

Verification

This method does not check the manifest, config, or snapshot blobs against their recorded sha256 digests. Load only from a layout you trust.

To check the digests on load at the expense of some performance, use Snapshot::checked_load.

File-mutation hazard

The snapshot blob stays memory-mapped while the returned Snapshot or any sandbox built from it is alive. The existing blob files in the layout at path must not be overwritten, truncated, or deleted while the mapping is live. Doing so can corrupt guest memory and can lead to undefined behavior.

Examples

let tag = OciTag::new("latest")?;
let snapshot = Arc::new(Snapshot::load("./guest_snapshot", tag)?);
let mut sandbox = MultiUseSandbox::from_snapshot(snapshot, HostFunctions::default(), None)?;
let result: String = sandbox.call("Echo", "hello".to_string())?;

pub fn checked_load( path: impl AsRef<Path>, reference: impl Into<OciReference>, ) -> Result<Self>

Loads a snapshot like Snapshot::load. See its rustdoc for path, reference, portability, and the file-mutation hazard. This method additionally checks the manifest, config, and snapshot blobs against their recorded sha256 digests before use, at the expense of some performance.

Trust

A digest check does not prove the bytes are authentic. Anyone who edits a blob can recompute its digest to match, so a hostile layout passes the check. Load only from a source you trust.

Trait Implementations

impl AsRef<Snapshot> for Snapshot

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl TableReadOps for Snapshot

type TableAddr = u64

The type of table addresses

fn entry_addr(addr: u64, offset: u64) -> u64

Offset the table address by the given offset in bytes.

unsafe fn read_entry(&self, addr: u64) -> PageTableEntry

Read a u64 from the given address, used to read existing page table entries

fn to_phys(addr: u64) -> PhysAddr

Convert an abstract table address to a concrete physical address (u64) which can be e.g. written into a page table entry

fn from_phys(addr: PhysAddr) -> u64

Convert a concrete physical address (u64) which may have been e.g. read from a page table entry back into an abstract table address

fn root_table(&self) -> u64

Return the address of the root page table