thunderboot

Documentation

Overview

Package thunderboot provides VM boot testing with bcache-backed storage.

This package boots a minimal VM with:

• virtiofs for the root filesystem (shared from host)
• Two virtio-blk devices for bcache: fast cache + slow backing store
• bcache assembled in guest init, formatted, and mounted at /data

It's designed to test the bcache + NBD storage architecture described in disk-store-plan.md before deploying to real hardware.

Index

• Constants
• func DefaultInitScript() string
• func FormatBcacheBacking(path string) error
• func FormatBcacheCache(path string, bucketSizeKB int) error
• func NBDInitScript(nbdHost, nbdPort string) string
• type DiskSpec
  • func ParseDiskSpec(s string, allowNBD bool) (DiskSpec, error)
  • func (s DiskSpec) String() string
• type VMConfig
• type VMSession
  • func StartVM(cfg VMConfig) (*VMSession, error)
  • func (s *VMSession) Close() error
  • func (s *VMSession) ConnectVsh() (net.Conn, error)
  • func (s *VMSession) Done() <-chan struct{}
  • func (s *VMSession) RunCommand(user string, args ...string) ([]byte, error)
  • func (s *VMSession) VshSocketPath() string
  • func (s *VMSession) Wait() error

Constants

const (
	SB_SECTOR          = 8 // superblock is at sector 8 (4096 bytes)
	SB_START           = SB_SECTOR * 512
	SB_LABEL_SIZE      = 32
	SB_JOURNAL_BUCKETS = 256
	BDEV_DATA_START    = 16 // sectors - where actual data starts for backing devices

	// Version constants
	BCACHE_SB_VERSION_CDEV             = 0
	BCACHE_SB_VERSION_BDEV             = 1
	BCACHE_SB_VERSION_CDEV_WITH_UUID   = 3
	BCACHE_SB_VERSION_BDEV_WITH_OFFSET = 4

	// Cache modes
	CACHE_MODE_WRITETHROUGH = 0
	CACHE_MODE_WRITEBACK    = 1
	CACHE_MODE_WRITEAROUND  = 2
	CACHE_MODE_NONE         = 3

	// Backing device states
	BDEV_STATE_NONE  = 0
	BDEV_STATE_CLEAN = 1
	BDEV_STATE_DIRTY = 2
	BDEV_STATE_STALE = 3

	// Cache replacement policies
	CACHE_REPLACEMENT_LRU    = 0
	CACHE_REPLACEMENT_FIFO   = 1
	CACHE_REPLACEMENT_RANDOM = 2
)

bcache superblock constants from Linux kernel / bcache-tools See: https://github.com/koverstreet/bcache-tools/blob/master/bcache.h

const VshPort = 5222

VshPort is the vsock port used for vsh shell connections.

Functions

func DefaultInitScript

func DefaultInitScript() string

DefaultInitScript returns the default init script that sets up bcache. It expects /dev/vda as cache device and /dev/vdb as backing device. NOTE: Use semicolons to separate commands - kernel cmdline doesn't interpret \n.

func FormatBcacheBacking

func FormatBcacheBacking(path string) error

FormatBcacheBacking formats a file as a bcache backing device. This replaces the make-bcache -B command.

func FormatBcacheCache

func FormatBcacheCache(path string, bucketSizeKB int) error

FormatBcacheCache formats a file as a bcache cache device. This replaces the make-bcache -C command.

func NBDInitScript

func NBDInitScript(nbdHost, nbdPort string) string

NBDInitScript returns an init script that connects to an NBD server for the backing device. The cache device is still /dev/vda, but the backing device comes from NBD on /dev/nbd0.

Types

type DiskSpec

type DiskSpec struct {
	RAID    string
	Devices []string
	NBD     *url.URL
}

DiskSpec describes either one block device, an md RAID made from several devices, or (for backing storage only) an NBD export.

func ParseDiskSpec

func ParseDiskSpec(s string, allowNBD bool) (DiskSpec, error)

func (DiskSpec) String

func (s DiskSpec) String() string

type VMConfig

type VMConfig struct {
	// Initramfs selects appliance mode when non-empty. In appliance mode the
	// initramfs supplies PID 1, DataDisk is /dev/vda, and ConfigDir is shared
	// read-only with the guest as the "bootconfig" virtiofs tag.
	Initramfs string
	// ApplianceCache and ApplianceDisk are kernel-style storage specs. Host
	// paths are attached in declaration order and rewritten to /dev/vd[a-z].
	ApplianceCache string
	ApplianceDisk  string
	// ApplianceDiskSize is the size used when creating missing host image paths.
	ApplianceDiskSize string
	TestOnly          bool
	CPUs              int
	// RootFS is the path to the root filesystem to share via virtiofs.
	RootFS string
	// VMDir is the path to the directory containing cloud-hypervisor and vmlinux.
	VMDir string
	// CacheFile is the path to the host file used as the fast bcache cache device.
	// This appears as /dev/vda in the guest.
	CacheFile string
	// BackingFile is the path to the host file used as the slow bcache backing device.
	// This appears as /dev/vdb in the guest. Mutually exclusive with BackingNBD.
	BackingFile string
	// CacheSizeMB is the size of the cache file in megabytes.
	CacheSizeMB int
	// BackingSizeMB is the size of the backing file in megabytes.
	// Only used when BackingNBD is empty.
	BackingSizeMB int
	// BackingNBD is the host:port of an NBD server to use as the backing device.
	// When set, the guest connects to this NBD server instead of using a local file.
	// Mutually exclusive with BackingFile/BackingSizeMB.
	BackingNBD string
	// MemoryMB is the VM memory size in megabytes. Default is 512.
	MemoryMB int
	// InitScript is an optional custom init script to run instead of the default.
	// If empty, uses the default bcache setup script.
	InitScript string
}

VMConfig holds configuration for starting a thunderboot VM.

type VMSession

type VMSession struct {
	// contains filtered or unexported fields
}

VMSession represents a running thunderboot VM session.

func StartVM

func StartVM(cfg VMConfig) (*VMSession, error)

StartVM starts a new thunderboot VM session with bcache-backed storage.

func (*VMSession) Close

func (s *VMSession) Close() error

Close terminates the VM session and cleans up resources. It escalates SIGKILL -> SIGTERM-on-deadline so a wedged cloud-hypervisor (e.g. stuck in vhost teardown) cannot hang shutdown indefinitely, and always tears down passt/virtiofsd even if CHV is already gone.

func (*VMSession) ConnectVsh

func (s *VMSession) ConnectVsh() (net.Conn, error)

ConnectVsh connects to vshd in the guest and returns a connection. The caller should send the vsh protocol header before using the connection.

func (*VMSession) Done

func (s *VMSession) Done() <-chan struct{}

Done returns a channel that is closed when the VM exits.

func (*VMSession) RunCommand

func (s *VMSession) RunCommand(user string, args ...string) ([]byte, error)

RunCommand runs a command in the guest via vshd and returns the output.

func (*VMSession) VshSocketPath

func (s *VMSession) VshSocketPath() string

VshSocketPath returns the Unix socket path for connecting to vshd in the guest.

func (*VMSession) Wait

func (s *VMSession) Wait() error

Wait blocks until the VM exits.