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, 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, error)
  • func (fc *Firecracker) DirectRestore(ctx context.Context, vmRef string, vmCfg *types.VMConfig, srcDir string) (*types.VM, error)
  • 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)

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

func (*Config) COWRawPath

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

func (*Config) PIDFileName

func (c *Config) PIDFileName() string

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, 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)

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, 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) 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).