launch

Documentation

Overview

launch implements test harnesses for running qemu VMs from tests.

Index

• Variables
• func Fatal(f string, args ...any)
• func Log(f string, args ...any)
• func NewSocketPair() (*os.File, *os.File, error)
• func PrettyPrintQemuArgs(name string, args []string)
• func RunMicroVM(ctx context.Context, opts *MicroVMOptions) error
• type GuestServiceMap
  • func (p GuestServiceMap) ToQemuForwards() []string
• type MicroVMOptions
• type PortMap
  • func ConflictFreePortMap(ports []uint16) (PortMap, error)
  • func IdentityPortMap(ports []uint16) PortMap
  • func (p PortMap) ToQemuForwards() []string
• type QEMUError
  • func (e *QEMUError) Error() string
• type QemuValue
  • func (value QemuValue) ToOption(name string) string

Variables

var HostInterfaceMAC = net.HardwareAddr{0x02, 0x72, 0x82, 0xbf, 0xc3, 0x56}

HostInterfaceMAC is the MAC address the host SLIRP network interface has if it is not disabled (see DisableHostNetworkInterface in MicroVMOptions)

Functions

func Fatal

func Fatal(f string, args ...any)

func Log

func Log(f string, args ...any)

Log is compatible with the output of ConciseString as used in the Metropolis console log, making the output more readable in unified test logs.

func NewSocketPair

func NewSocketPair() (*os.File, *os.File, error)

NewSocketPair creates a new socket pair. By connecting both ends to different instances you can connect them with a virtual "network cable". The ends can be passed into the ConnectToSocket option.

func PrettyPrintQemuArgs

func PrettyPrintQemuArgs(name string, args []string)

PrettyPrintQemuArgs prints the given QEMU arguments to stderr.

func RunMicroVM

func RunMicroVM(ctx context.Context, opts *MicroVMOptions) error

RunMicroVM launches a tiny VM mostly intended for testing. Very quick to boot (<40ms).

Types

type GuestServiceMap

type GuestServiceMap map[*net.TCPAddr]net.TCPAddr

GuestServiceMap maps an IP/port combination inside the virtual guest network to a TCPAddr reachable by the host. If the guest connects to the virtual address/port, this connection gets forwarded to the host.

func (GuestServiceMap) ToQemuForwards

func (p GuestServiceMap) ToQemuForwards() []string

ToQemuForwards generates QEMU guestfwd values (https://qemu.weilnetz.de/doc/qemu- doc.html#:~:text=guestfwd=) for all mapped addresses.

type MicroVMOptions

type MicroVMOptions struct {
	// Name is a human-readable identifier to be used in debug output.
	Name string

	// Path to the ELF kernel binary
	KernelPath string

	// Path to the Initramfs
	InitramfsPath string

	// Cmdline contains additional kernel commandline options
	Cmdline string

	// SerialPort is a File(descriptor) over which you can communicate with the serial
	// port of the machine It can be set to an existing file descriptor (like
	// os.Stdout/os.Stderr) or you can use NewSocketPair() to get one end to talk to
	// from Go.
	SerialPort io.Writer

	// ExtraChardevs can be used similar to SerialPort, but can contain an arbitrary
	// number of additional serial ports
	ExtraChardevs []*os.File

	// ExtraNetworkInterfaces can contain an arbitrary number of file descriptors which
	// are mapped into the VM as virtio network interfaces. The first interface is
	// always a SLIRP-backed interface for communicating with the host.
	ExtraNetworkInterfaces []*os.File

	// PortMap contains ports that are mapped to the host through the built-in SLIRP
	// network interface.
	PortMap PortMap

	// GuestServiceMap contains TCP services made available in the guest virtual
	// network which are running on the host.
	GuestServiceMap GuestServiceMap

	// DisableHostNetworkInterface disables the SLIRP-backed host network interface
	// that is normally the first network interface. If this is set PortMap is ignored.
	// Mostly useful for speeding up QEMU's startup time for tests.
	DisableHostNetworkInterface bool

	// PcapDump can be used to dump all network traffic to a pcap file.
	// If unset, no dump is created.
	PcapDump string
}

MicroVMOptions contains all options to start a MicroVM

type PortMap

type PortMap map[uint16]uint16

PortMap represents where VM ports are mapped to on the host. It maps from the VM port number to the host port number.

func ConflictFreePortMap

func ConflictFreePortMap(ports []uint16) (PortMap, error)

ConflictFreePortMap returns a port map where each given port is mapped onto a random free port on the host. This is intended for automated testing where multiple instances of Metropolis nodes might be running. Please call this function for each Launch command separately and as close to it as possible since it cannot guarantee that the ports will remain free.

func IdentityPortMap

func IdentityPortMap(ports []uint16) PortMap

IdentityPortMap returns a port map where each given port is mapped onto itself on the host. This is mainly useful for development against Metropolis. The dbg command requires this mapping.

func (PortMap) ToQemuForwards

func (p PortMap) ToQemuForwards() []string

ToQemuForwards generates QEMU hostfwd values (https://qemu.weilnetz.de/doc/qemu- doc.html#:~:text=hostfwd=) for all mapped ports.

type QEMUError

type QEMUError exec.ExitError

QEMUError is a special type of ExitError used when QEMU fails. In addition to normal ExitError features it prints stderr for debugging.

func (*QEMUError) Error

func (e *QEMUError) Error() string

type QemuValue

type QemuValue map[string][]string

func (QemuValue) ToOption

func (value QemuValue) ToOption(name string) string

ToOption encodes structured data into a QEMU option. Example: "test", {"key1": {"val1"}, "key2": {"val2", "val3"}} returns "test,key1=val1,key2=val2,key2=val3"