firecracker

Documentation

Index

• func EnsureVmlinux(kernelPath string) (string, error)
• func IsRelayMode() bool
• func RunRelay(ctx context.Context)
• type Config
  • func (c *Config) BinaryName() string
  • func (c *Config) COWRawPath(vmID string) string
  • func (c *Config) EnsureDirs() error
  • func (c *Config) IndexFile() string
  • func (c *Config) IndexLock() string
  • func (c *Config) LogDir() string
  • func (c *Config) PIDFileName() string
  • func (c *Config) RunDir() string
  • func (c *Config) SocketWaitTimeout() time.Duration
  • func (c *Config) TerminateGracePeriod() time.Duration
  • func (c *Config) VMLogDir(vmID string) string
  • func (c *Config) VMRunDir(vmID string) 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 the path to an uncompressed ELF kernel. If the kernel at path is already ELF, returns path as-is. Otherwise, extracts the uncompressed kernel from the compressed vmlinuz and caches it as "vmlinux" in the same directory.

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 {
	*config.Config
}

Config holds Firecracker specific configuration, embedding the 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) EnsureDirs

func (c *Config) EnsureDirs() error

EnsureDirs creates all static directories required by the Firecracker backend.

func (*Config) IndexFile

func (c *Config) IndexFile() string

IndexFile returns the VM index store path.

func (*Config) IndexLock

func (c *Config) IndexLock() string

IndexLock returns the VM index lock path.

func (*Config) LogDir

func (c *Config) LogDir() string

LogDir returns the top-level FC log directory.

func (*Config) PIDFileName

func (c *Config) PIDFileName() string

PIDFileName returns the PID file name for the Firecracker backend.

func (*Config) RunDir

func (c *Config) RunDir() string

RunDir returns the top-level FC runtime directory.

func (*Config) SocketWaitTimeout

func (c *Config) SocketWaitTimeout() time.Duration

SocketWaitTimeout returns the configured socket wait timeout or the default.

func (*Config) TerminateGracePeriod

func (c *Config) TerminateGracePeriod() time.Duration

TerminateGracePeriod returns the configured SIGTERM→SIGKILL grace period or the default.

func (*Config) VMLogDir

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

VMLogDir returns the per-VM log directory.

func (*Config) VMRunDir

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

VMRunDir returns the per-VM runtime directory.

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 registers a new VM, prepares the COW disk, and persists the record. The VM is left in Created state — call Start to launch it. FC only supports OCI images (direct kernel boot).

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 reverts a running VM to a previous snapshot's state.

The FC process is killed and restarted with the snapshot's memory and disk state. Network is preserved -- same netns, same tap, same MAC/IP. vmCfg carries the final resource config (already validated >= snapshot values).

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.