firecracker

Documentation

Index

• func EnsureVmlinux(kernelPath string) (string, error)
• func IsRelayMode() bool
• func RunRelay(ctx context.Context)
• type Config
  • func NewConfig(conf *config.Config) *Config
  • func (c *Config) BinaryName() string
  • func (c *Config) COWRawPath(vmID string) string
  • func (c *Config) PIDFileName() string
• type Firecracker
  • func New(conf *config.Config) (*Firecracker, error)
  • func (fc *Firecracker) Clone(ctx context.Context, vmID string, vmCfg *types.VMConfig, ...) (_ *types.VM, err error)
  • func (fc *Firecracker) Console(ctx context.Context, ref string) (io.ReadWriteCloser, error)
  • func (fc *Firecracker) Create(ctx context.Context, id string, vmCfg *types.VMConfig, ...) (_ *types.VM, err error)
  • func (fc *Firecracker) Delete(ctx context.Context, refs []string, force bool) ([]string, error)
  • func (fc *Firecracker) DirectClone(ctx context.Context, vmID string, vmCfg *types.VMConfig, ...) (_ *types.VM, err error)
  • func (fc *Firecracker) DirectRestore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, srcDir string) (*types.VM, error)
  • func (fc *Firecracker) GCModule() gc.Module[fcSnapshot]
  • func (fc *Firecracker) RegisterGC(orch *gc.Orchestrator)
  • func (fc *Firecracker) Restore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, snapshot io.Reader) (*types.VM, error)
  • func (fc *Firecracker) Snapshot(ctx context.Context, ref string) (*types.SnapshotConfig, io.ReadCloser, error)
  • func (fc *Firecracker) Start(ctx context.Context, refs []string) ([]string, error)
  • func (fc *Firecracker) Stop(ctx context.Context, refs []string) ([]string, error)
  • func (fc *Firecracker) WatchPath() string

Functions

func EnsureVmlinux

func EnsureVmlinux(kernelPath string) (string, error)

EnsureVmlinux returns an uncompressed ELF kernel path.

func IsRelayMode

func IsRelayMode() bool

IsRelayMode returns true when the process was started as a console relay.

func RunRelay

func RunRelay(ctx context.Context)

RunRelay runs the console relay loop. Called from main.go when IsRelayMode() returns true. The relay process inherits:

• fd 3: PTY master (bidirectional serial I/O with FC)
• fd 4: Unix listener file (console.sock)
• _COCOON_FC_PID: Firecracker PID to monitor

A single persistent goroutine reads from the PTY master for the lifetime of the relay. Each console session receives output via a broadcast mechanism — no per-session goroutine reads the PTY, so disconnecting a session never leaves stale readers competing for data.

Types

type Config

type Config struct {
	hypervisor.BaseConfig
}

Config holds Firecracker specific configuration.

func NewConfig

func NewConfig(conf *config.Config) *Config

NewConfig creates a Config from a global config.

func (*Config) BinaryName

func (c *Config) BinaryName() string

BinaryName returns the base name of the Firecracker binary.

func (*Config) COWRawPath

func (c *Config) COWRawPath(vmID string) string

COWRawPath returns the path for the OCI COW raw disk.

func (*Config) PIDFileName

func (c *Config) PIDFileName() string

PIDFileName returns the PID file name for the Firecracker backend.

type Firecracker

type Firecracker struct {
	*hypervisor.Backend
	// contains filtered or unexported fields
}

Firecracker implements hypervisor.Hypervisor using the Firecracker VMM. Only OCI images (direct kernel boot) are supported — no UEFI, no cloudimg, no Windows.

func New

func New(conf *config.Config) (*Firecracker, error)

New creates a Firecracker backend.

func (*Firecracker) Clone

func (fc *Firecracker) Clone(ctx context.Context, vmID string, vmCfg *types.VMConfig, networkConfigs []*types.NetworkConfig, snapshotConfig *types.SnapshotConfig, snapshot io.Reader) (_ *types.VM, err error)

Clone creates a new VM from a snapshot tar stream via FC snapshot/load.

func (*Firecracker) Console

func (fc *Firecracker) Console(ctx context.Context, ref string) (io.ReadWriteCloser, error)

Console connects to the FC VM's serial console via the PTY relay socket. The relay process (started alongside FC) listens on console.sock and bridges connections to the PTY master connected to FC's stdin/stdout.

func (*Firecracker) Create

func (fc *Firecracker) Create(ctx context.Context, id string, vmCfg *types.VMConfig, storageConfigs []*types.StorageConfig, networkConfigs []*types.NetworkConfig, bootCfg *types.BootConfig) (_ *types.VM, err error)

Create reserves a VM record, prepares disks, and leaves the VM in Created state.

func (*Firecracker) Delete

func (fc *Firecracker) Delete(ctx context.Context, refs []string, force bool) ([]string, error)

Delete removes VMs. Running VMs require force=true (stops them first).

func (*Firecracker) DirectClone

func (fc *Firecracker) DirectClone(ctx context.Context, vmID string, vmCfg *types.VMConfig, networkConfigs []*types.NetworkConfig, snapshotConfig *types.SnapshotConfig, srcDir string) (_ *types.VM, err error)

DirectClone creates a new VM from a local snapshot directory. Files are handled per-type: hardlink for mem, reflink/copy for the COW disk, plain copy for small metadata (vmstate).

func (*Firecracker) DirectRestore

func (fc *Firecracker) DirectRestore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, srcDir string) (*types.VM, error)

DirectRestore reverts a running VM using a local snapshot directory. Files are handled per-type: hardlink for mem, reflink/copy for the COW disk, plain copy for small metadata (vmstate).

func (*Firecracker) GCModule

func (fc *Firecracker) GCModule() gc.Module[fcSnapshot]

GCModule returns the GC module for cross-module blob pinning and orphan cleanup.

func (*Firecracker) RegisterGC

func (fc *Firecracker) RegisterGC(orch *gc.Orchestrator)

RegisterGC registers the Firecracker GC module with the given Orchestrator.

func (*Firecracker) Restore

func (fc *Firecracker) Restore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, snapshot io.Reader) (*types.VM, error)

Restore stages a snapshot tar before replacing the running VM state.

func (*Firecracker) Snapshot

func (fc *Firecracker) Snapshot(ctx context.Context, ref string) (*types.SnapshotConfig, io.ReadCloser, error)

Snapshot pauses the VM, captures its full state (CPU/device state via FC snapshot API + memory file + COW disk via reflink copy), resumes the VM, and returns a streaming tar.gz reader of the snapshot directory.

func (*Firecracker) Start

func (fc *Firecracker) Start(ctx context.Context, refs []string) ([]string, error)

Start launches the Firecracker process for each VM ref, configures it via the REST API, and issues InstanceStart.

func (*Firecracker) Stop

func (fc *Firecracker) Stop(ctx context.Context, refs []string) ([]string, error)

Stop shuts down the Firecracker process for each VM ref. Honors --force (skip SendCtrlAltDel, immediate kill) and --timeout (wait for guest to respond to SendCtrlAltDel before escalating).

func (*Firecracker) WatchPath

func (fc *Firecracker) WatchPath() string

WatchPath returns the path to the VM index file for filesystem-based change watching. Implements hypervisor.Watchable.