A data-only representation of a Firecracker snapshot.

This module creates and manages snapshot configurations for Firecracker VMs, allowing you to save and restore the state of virtual machines. Snapshots include both the VM state (CPU registers, VM configuration) and optionally the guest memory content.

Snapshot Types

Firecracker supports two types of snapshots:

• :full - Contains both VM state and guest memory
• :diff - Contains only incremental changes from a previous snapshot

Memory Management

Firecracker snapshots can manage guest memory content through:

• Memory files (.mem files) that store the raw memory contents
• Memory backends that provide alternative memory storage mechanisms

The snapshot configuration can be created with either a direct path to a memory file or by associating it with a memory backend later.

Network Overrides

When loading a snapshot, you can override the network interface configurations to change which host devices back the virtual machine's network interfaces. This is useful when restoring VM snapshots in different network environments or when the original host device is no longer available.

Network overrides are configured by interface ID and allow you to map a VM's virtual network interface to a different host device without modifying the underlying snapshot. See network_override/3 for details.

Example Usage

# Create a basic snapshot configuration
snapshot = Firecracker.Snapshot.new(
  path: "/path/to/snapshot.json",
  type: :full,
  mem_file_path: "/path/to/memory.mem"
)

# Or create with a memory backend
snapshot = Firecracker.Snapshot.new(path: "/path/to/snapshot.json", type: :diff)
|> Firecracker.Snapshot.memory_backend(custom_backend)

@spec memory_backend(
  t(),
  keyword()
) :: t()

Creates a snapshot memory backend.

Memory backends can be used in place of the memory file path when loading a snapshot.

Setting the memory backend overrides the existing :mem_file_path if one is set.

Options

• :backend_type - the type of memory backend to use. One of "File" or "Uffd"

• :backend_path - if the backend type is File, this must be the path to the file that contains the guest memory. If if is Uffd, it must be the path to the UDS where a process is listening for a UFFD initialization control payload.

@spec network_override(t(), String.t(), String.t()) :: t()

Creates a network override for the given interface with the given host device name.

The id must be an existing iface_id on the virutal machine and the given host_dev_name will be the new backing host device.

@spec new(keyword()) :: t()

Creates a %Firecracker.Snapshot{} struct with the given configuration options.

You must pass a :path which is a valid path to a valid Firecracker snapshot, as well as a :type which is the type of Firecracker snapshot.

You may optionall pass a :mem_file_path which is a pass to a file containing the guest memory. If you do not configure :mem_file_path here, you must configure a memory backend using Firecracker.Snapshot.memory_backend/2.

Options

• :path - snapshot path. Required

• :type - snapshot type. Required

• :resume_vm - whether or not to resume the VM after loading the snapshot. Defaults to true

• :track_dirty_pages - whether or not to enable KVM dirty page tracking. Defaults to true

• :mem_file_path - path to a file which contains guest memory. You must configure this or a memory backend before loading the snapshot.

@spec set_options(
  t(),
  keyword()
) :: t()

Sets the given snapshot options.

This can be used to modify snapshot configuration options after creating a snapshot via Firecracker.snapshot/2.

Options

• :path - snapshot path

• :type - snapshot type

• :track_dirty_pages - whether or not to enable KVM dirty page tracking. Defaults to true

• :mem_file_path - path to a file which contains guest memory. You must configure this or a memory backend before loading the snapshot.