config

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 27, 2024 License: Apache-2.0 Imports: 12 Imported by: 9

Documentation

Overview

Package config provides native go data types to describe a VM configuration (memory, CPUs, bootloader, devices, ...). It's used by vfkit which generates a VirtualMachine instance after parsing its command line using FromOptions(). It can also be used by application writers who want to start a VM with vfkit. After creating a VirtualMachine instance with the needed devices, calling VirtualMachine.Cmd() will return an exec.Cmd which can be used to start the virtual machine.

This package does not use Code-Hex/vz directly as it must possible to cross-compile code using it.

Index

Constants

View Source 
const (
	// Possible values for VirtioInput.InputType
	VirtioInputPointingDevice = "pointing"
	VirtioInputKeyboardDevice = "keyboard"

	// Options for VirtioGPUResolution
	VirtioGPUResolutionWidth  = "width"
	VirtioGPUResolutionHeight = "height"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Bootloader 

type Bootloader interface {
	FromOptions(options []option) error
	ToCmdLine() ([]string, error)
}

Bootloader is the base interface for all bootloader classes. It specifies how to boot the virtual machine. It is mandatory to set a Bootloader or the virtual machine won't start.

func BootloaderFromCmdLine added in v0.1.0 

func BootloaderFromCmdLine(optsStrv []string) (Bootloader, error)

type DirectorySharingConfig added in v0.5.0 

type DirectorySharingConfig struct {
	MountTag string `json:"mountTag"`
}

type EFIBootloader added in v0.1.0 

type EFIBootloader struct {
	EFIVariableStorePath string `json:"efiVariableStorePath"`
	// TODO: virtualization framework allow both create and overwrite
	CreateVariableStore bool `json:"createVariableStore"`
}

EFIBootloader allows to set a few options related to EFI variable storage

func NewEFIBootloader added in v0.1.0 

func NewEFIBootloader(efiVariableStorePath string, createVariableStore bool) *EFIBootloader

NewEFIBootloader creates a new bootloader to start a VM using EFI efiVariableStorePath is the path to a file for EFI storage create is a boolean indicating if the file for the store should be created or not

func (*EFIBootloader) FromOptions added in v0.1.0 

func (bootloader *EFIBootloader) FromOptions(options []option) error

func (*EFIBootloader) MarshalJSON added in v0.1.0 

func (bootloader *EFIBootloader) MarshalJSON() ([]byte, error)

func (*EFIBootloader) ToCmdLine added in v0.1.0 

func (bootloader *EFIBootloader) ToCmdLine() ([]string, error)

type Ignition added in v0.6.0 

type Ignition struct {
	ConfigPath string `json:"configPath"`
	SocketPath string `json:"socketPath"`
}

func IgnitionNew added in v0.6.0 

func IgnitionNew(configPath string, socketPath string) (*Ignition, error)

func (*Ignition) MarshalJSON added in v0.6.0 

func (ign *Ignition) MarshalJSON() ([]byte, error)

type LinuxBootloader added in v0.1.0 

type LinuxBootloader struct {
	VmlinuzPath   string `json:"vmlinuzPath"`
	KernelCmdLine string `json:"kernelCmdLine"`
	InitrdPath    string `json:"initrdPath"`
}

LinuxBootloader determines which kernel/initrd/kernel args to use when starting the virtual machine.

func NewLinuxBootloader added in v0.1.0 

func NewLinuxBootloader(vmlinuzPath, kernelCmdLine, initrdPath string) *LinuxBootloader

NewLinuxBootloader creates a new bootloader to start a VM with the file at vmlinuzPath as the kernel, kernelCmdLine as the kernel command line, and the file at initrdPath as the initrd. On ARM64, the kernel must be uncompressed otherwise the VM will fail to boot.

func (*LinuxBootloader) FromOptions added in v0.1.0 

func (bootloader *LinuxBootloader) FromOptions(options []option) error

func (*LinuxBootloader) MarshalJSON added in v0.1.0 

func (bootloader *LinuxBootloader) MarshalJSON() ([]byte, error)

func (*LinuxBootloader) ToCmdLine added in v0.1.0 

func (bootloader *LinuxBootloader) ToCmdLine() ([]string, error)

type MacOSBootloader added in v0.6.0 

type MacOSBootloader struct {
	MachineIdentifierPath string `json:"machineIdentifierPath"`
	HardwareModelPath     string `json:"hardwareModelPath"`
	AuxImagePath          string `json:"auxImagePath"`
}

MacOSBootloader provides necessary objects for booting macOS guests

func (*MacOSBootloader) FromOptions added in v0.6.0 

func (bootloader *MacOSBootloader) FromOptions(options []option) error

func (*MacOSBootloader) ToCmdLine added in v0.6.0 

func (bootloader *MacOSBootloader) ToCmdLine() ([]string, error)

type NBDSynchronizationMode added in v0.6.0 

type NBDSynchronizationMode string
const (
	SynchronizationFullMode NBDSynchronizationMode = "full"
	SynchronizationNoneMode NBDSynchronizationMode = "none"
)

type NVMExpressController added in v0.6.0 

type NVMExpressController struct {
	StorageConfig
}

NVMExpressController configures a NVMe controller in the guest

func NVMExpressControllerNew added in v0.6.0 

func NVMExpressControllerNew(imagePath string) (*NVMExpressController, error)

NVMExpressControllerNew creates a new NVMExpress controller to use in the virtual machine. It will use the file at imagePath as the disk image. This image must be in raw format.

func (*NVMExpressController) MarshalJSON added in v0.6.0 

func (dev *NVMExpressController) MarshalJSON() ([]byte, error)

type NetworkBlockDevice added in v0.6.0 

type NetworkBlockDevice struct {
	VirtioBlk
	Timeout             time.Duration
	SynchronizationMode NBDSynchronizationMode
}

func NetworkBlockDeviceNew added in v0.6.0 

func NetworkBlockDeviceNew(uri string, timeout uint32, synchronization NBDSynchronizationMode) (*NetworkBlockDevice, error)

NetworkBlockDeviceNew creates a new disk by connecting to a remote Network Block Device (NBD) server. The provided uri must be in the format <scheme>://<address>/<export-name> where scheme could have any of these value: nbd, nbds, nbd+unix and nbds+unix. More info can be found at https://github.com/NetworkBlockDevice/nbd/blob/master/doc/uri.md This allows the virtual machine to access and use the remote storage as if it were a local disk.

func (*NetworkBlockDevice) FromOptions added in v0.6.0 

func (nbd *NetworkBlockDevice) FromOptions(options []option) error

func (*NetworkBlockDevice) MarshalJSON added in v0.6.0 

func (dev *NetworkBlockDevice) MarshalJSON() ([]byte, error)

func (*NetworkBlockDevice) ToCmdLine added in v0.6.0 

func (nbd *NetworkBlockDevice) ToCmdLine() ([]string, error)

type RosettaShare added in v0.5.0 

type RosettaShare struct {
	DirectorySharingConfig
	InstallRosetta  bool `json:"installRosetta"`
	IgnoreIfMissing bool `json:"ignoreIfMissing"`
}

RosettaShare configures rosetta support in the guest to run Intel binaries on Apple CPUs

func (*RosettaShare) FromOptions added in v0.5.0 

func (dev *RosettaShare) FromOptions(options []option) error

func (*RosettaShare) MarshalJSON added in v0.5.0 

func (dev *RosettaShare) MarshalJSON() ([]byte, error)

func (*RosettaShare) ToCmdLine added in v0.5.0 

func (dev *RosettaShare) ToCmdLine() ([]string, error)

type StorageConfig added in v0.1.0 

type StorageConfig struct {
	DevName   string `json:"devName"`
	ImagePath string `json:"imagePath,omitempty"`
	URI       string `json:"uri,omitempty"`
	ReadOnly  bool   `json:"readOnly,omitempty"`
}

StorageConfig configures a disk device.

func (*StorageConfig) FromOptions added in v0.1.0 

func (config *StorageConfig) FromOptions(options []option) error

func (*StorageConfig) ToCmdLine added in v0.1.0 

func (config *StorageConfig) ToCmdLine() ([]string, error)

type TimeSync 

type TimeSync struct {
	VsockPort uint32 `json:"vsockPort"`
}

TimeSync enables synchronization of the host time to the linux guest after the host was suspended. This requires qemu-guest-agent to be running in the guest, and to be listening on a vsock socket

func (*TimeSync) FromOptions added in v0.1.0 

func (ts *TimeSync) FromOptions(options []option) error

func (*TimeSync) ToCmdLine added in v0.1.0 

func (ts *TimeSync) ToCmdLine() ([]string, error)

type USBMassStorage added in v0.1.0 

type USBMassStorage struct {
	StorageConfig
}

func USBMassStorageNew added in v0.1.0 

func USBMassStorageNew(imagePath string) (*USBMassStorage, error)

USBMassStorageNew creates a new USB disk to use in the virtual machine. It will use the file at imagePath as the disk image. This image must be in raw or ISO format.

func (*USBMassStorage) MarshalJSON added in v0.1.0 

func (dev *USBMassStorage) MarshalJSON() ([]byte, error)

func (*USBMassStorage) SetReadOnly added in v0.6.0 

func (dev *USBMassStorage) SetReadOnly(readOnly bool)

type VMComponent added in v0.1.0 

type VMComponent interface {
	FromOptions([]option) error
	ToCmdLine() ([]string, error)
}

The VMComponent interface represents a VM element (device, bootloader, ...) which can be converted from/to commandline parameters

func TimeSyncNew added in v0.1.0 

func TimeSyncNew(vsockPort uint) (VMComponent, error)

type VirtioBlk added in v0.1.0 

type VirtioBlk struct {
	StorageConfig
	DeviceIdentifier string `json:"deviceIdentifier,omitempty"`
}

VirtioBlk configures a disk device.

func VirtioBlkNew added in v0.1.0 

func VirtioBlkNew(imagePath string) (*VirtioBlk, error)

VirtioBlkNew creates a new disk to use in the virtual machine. It will use the file at imagePath as the disk image. This image must be in raw format.

func (*VirtioBlk) FromOptions added in v0.1.0 

func (dev *VirtioBlk) FromOptions(options []option) error

func (*VirtioBlk) MarshalJSON added in v0.1.0 

func (dev *VirtioBlk) MarshalJSON() ([]byte, error)

func (*VirtioBlk) SetDeviceIdentifier added in v0.1.0 

func (dev *VirtioBlk) SetDeviceIdentifier(devID string)

func (*VirtioBlk) ToCmdLine added in v0.1.0 

func (dev *VirtioBlk) ToCmdLine() ([]string, error)

type VirtioDevice 

type VirtioDevice VMComponent

The VirtioDevice interface is an interface which is implemented by all virtio devices.

func RosettaShareNew added in v0.5.0 

func RosettaShareNew(mountTag string) (VirtioDevice, error)

RosettaShareNew RosettaShare creates a new rosetta share for running x86_64 binaries on M1 machines. It will share a directory containing the linux rosetta binaries with the virtual machine. This directory can be mounted in the VM using `mount -t virtiofs mountTag /some/dir`

func VirtioFsNew added in v0.1.0 

func VirtioFsNew(sharedDir string, mountTag string) (VirtioDevice, error)

VirtioFsNew creates a new virtio-fs device for file sharing. It will share the directory at sharedDir with the virtual machine. This directory can be mounted in the VM using `mount -t virtiofs mountTag /some/dir`

func VirtioGPUNew added in v0.1.0 

func VirtioGPUNew() (VirtioDevice, error)

VirtioGPUNew creates a new gpu device for the virtual machine. The usesGUI parameter determines whether a graphical application window will be displayed

func VirtioInputNew added in v0.1.0 

func VirtioInputNew(inputType string) (VirtioDevice, error)

VirtioInputNew creates a new input device for the virtual machine. The inputType parameter is the type of virtio-input device that will be added to the machine.

func VirtioRngNew added in v0.1.0 

func VirtioRngNew() (VirtioDevice, error)

VirtioRngNew creates a new random number generator device to feed entropy into the virtual machine.

func VirtioSerialNew added in v0.1.0 

func VirtioSerialNew(logFilePath string) (VirtioDevice, error)

VirtioSerialNew creates a new serial device for the virtual machine. The output the virtual machine sent to the serial port will be written to the file at logFilePath.

func VirtioSerialNewStdio added in v0.1.0 

func VirtioSerialNewStdio() (VirtioDevice, error)

func VirtioVsockNew added in v0.1.0 

func VirtioVsockNew(port uint, socketURL string, listen bool) (VirtioDevice, error)

VirtioVsockNew creates a new virtio-vsock device for 2-way communication between the host and the virtual machine. The communication will happen on vsock port, and on the host it will use the unix socket at socketURL. When listen is true, the host will be listening for connections over vsock. When listen is false, the guest will be listening for connections over vsock.

type VirtioFs added in v0.1.0 

type VirtioFs struct {
	DirectorySharingConfig
	SharedDir string `json:"sharedDir"`
}

VirtioFs configures directory sharing between the guest and the host.

func (*VirtioFs) FromOptions added in v0.1.0 

func (dev *VirtioFs) FromOptions(options []option) error

func (*VirtioFs) MarshalJSON added in v0.1.0 

func (dev *VirtioFs) MarshalJSON() ([]byte, error)

func (*VirtioFs) ToCmdLine added in v0.1.0 

func (dev *VirtioFs) ToCmdLine() ([]string, error)

type VirtioGPU added in v0.1.0 

type VirtioGPU struct {
	UsesGUI bool `json:"usesGUI"`
	VirtioGPUResolution
}

VirtioGPU configures a GPU device, such as the host computer's display

func (*VirtioGPU) FromOptions added in v0.1.0 

func (dev *VirtioGPU) FromOptions(options []option) error

func (*VirtioGPU) MarshalJSON added in v0.1.0 

func (dev *VirtioGPU) MarshalJSON() ([]byte, error)

func (*VirtioGPU) ToCmdLine added in v0.1.0 

func (dev *VirtioGPU) ToCmdLine() ([]string, error)

type VirtioGPUResolution added in v0.1.0 

type VirtioGPUResolution struct {
	Width  int `json:"width"`
	Height int `json:"height"`
}

type VirtioInput added in v0.1.0 

type VirtioInput struct {
	InputType string `json:"inputType"` // currently supports "pointing" and "keyboard" input types
}

VirtioInput configures an input device, such as a keyboard or pointing device (mouse) that the virtual machine can use

func (*VirtioInput) FromOptions added in v0.1.0 

func (dev *VirtioInput) FromOptions(options []option) error

func (*VirtioInput) MarshalJSON added in v0.1.0 

func (dev *VirtioInput) MarshalJSON() ([]byte, error)

func (*VirtioInput) ToCmdLine added in v0.1.0 

func (dev *VirtioInput) ToCmdLine() ([]string, error)

type VirtioNet added in v0.1.0 

type VirtioNet struct {
	Nat        bool             `json:"nat"`
	MacAddress net.HardwareAddr `json:"-"` // custom marshaller in json.go
	// file parameter is holding a connected datagram socket.
	// see https://github.com/Code-Hex/vz/blob/7f648b6fb9205d6f11792263d79876e3042c33ec/network.go#L113-L155
	Socket *os.File `json:"socket,omitempty"`

	UnixSocketPath string `json:"unixSocketPath,omitempty"`
}

VirtioNet configures the virtual machine networking.

func VirtioNetNew added in v0.1.0 

func VirtioNetNew(macAddress string) (*VirtioNet, error)

VirtioNetNew creates a new network device for the virtual machine. It will use macAddress as its MAC address.

func (*VirtioNet) FromOptions added in v0.1.0 

func (dev *VirtioNet) FromOptions(options []option) error

func (*VirtioNet) MarshalJSON added in v0.1.0 

func (dev *VirtioNet) MarshalJSON() ([]byte, error)

func (*VirtioNet) SetSocket added in v0.1.0 

func (dev *VirtioNet) SetSocket(file *os.File)

SetSocket Set the socket to use for the network communication

This maps the virtual machine network interface to a connected datagram socket. This means all network traffic on this interface will go through file. file must be a connected datagram (SOCK_DGRAM) socket.

func (*VirtioNet) SetUnixSocketPath added in v0.1.0 

func (dev *VirtioNet) SetUnixSocketPath(path string)

func (*VirtioNet) ToCmdLine added in v0.1.0 

func (dev *VirtioNet) ToCmdLine() ([]string, error)

type VirtioRng added in v0.1.0 

type VirtioRng struct {
}

VirtioRng configures a random number generator (RNG) device.

func (*VirtioRng) FromOptions added in v0.1.0 

func (dev *VirtioRng) FromOptions(options []option) error

func (*VirtioRng) MarshalJSON added in v0.1.0 

func (dev *VirtioRng) MarshalJSON() ([]byte, error)

func (*VirtioRng) ToCmdLine added in v0.1.0 

func (dev *VirtioRng) ToCmdLine() ([]string, error)

type VirtioSerial added in v0.1.0 

type VirtioSerial struct {
	LogFile   string `json:"logFile,omitempty"`
	UsesStdio bool   `json:"usesStdio,omitempty"`
}

VirtioSerial configures the virtual machine serial ports.

func (*VirtioSerial) FromOptions added in v0.1.0 

func (dev *VirtioSerial) FromOptions(options []option) error

func (*VirtioSerial) MarshalJSON added in v0.1.0 

func (dev *VirtioSerial) MarshalJSON() ([]byte, error)

func (*VirtioSerial) ToCmdLine added in v0.1.0 

func (dev *VirtioSerial) ToCmdLine() ([]string, error)

type VirtioVsock 

type VirtioVsock struct {
	// Port is the virtio-vsock port used for this device, see `man vsock` for more
	// details.
	Port uint32 `json:"port"`
	// SocketURL is the path to a unix socket on the host to use for the virtio-vsock communication with the guest.
	SocketURL string `json:"socketURL"`
	// If true, vsock connections will have to be done from guest to host. If false, vsock connections will only be possible
	// from host to guest
	Listen bool `json:"listen,omitempty"`
}

VirtioVsock configures of a virtio-vsock device allowing 2-way communication between the host and the virtual machine type

func (*VirtioVsock) FromOptions 

func (dev *VirtioVsock) FromOptions(options []option) error

func (*VirtioVsock) MarshalJSON added in v0.1.0 

func (dev *VirtioVsock) MarshalJSON() ([]byte, error)

func (*VirtioVsock) ToCmdLine added in v0.1.0 

func (dev *VirtioVsock) ToCmdLine() ([]string, error)

type VirtualMachine 

type VirtualMachine struct {
	Vcpus      uint           `json:"vcpus"`
	Memory     strongunits.B  `json:"memoryBytes"`
	Bootloader Bootloader     `json:"bootloader"`
	Devices    []VirtioDevice `json:"devices,omitempty"`
	Timesync   *TimeSync      `json:"timesync,omitempty"`
	Ignition   *Ignition      `json:"ignition,omitempty"`
}

VirtualMachine is the top-level type. It describes the virtual machine configuration (bootloader, devices, ...).

func NewVirtualMachine 

func NewVirtualMachine(vcpus uint, memoryMiB uint64, bootloader Bootloader) *VirtualMachine

NewVirtualMachine creates a new VirtualMachine instance. The virtual machine will use vcpus virtual CPUs and it will be allocated memoryMiB mibibytes (1024*1024 bytes) of RAM. bootloader specifies how the virtual machine will be booted (UEFI or with the specified kernel/initrd/commandline)

func (*VirtualMachine) AddDevice added in v0.1.0 

func (vm *VirtualMachine) AddDevice(dev VirtioDevice) error

AddDevice adds a dev to vm. This device can be created with one of the VirtioXXXNew methods.

func (*VirtualMachine) AddDevices added in v0.6.0 

func (vm *VirtualMachine) AddDevices(dev ...VirtioDevice) error

AddDevices adds a list of devices to vm.

func (*VirtualMachine) AddDevicesFromCmdLine 

func (vm *VirtualMachine) AddDevicesFromCmdLine(cmdlineOpts []string) error

func (*VirtualMachine) AddIgnitionFileFromCmdLine added in v0.6.0 

func (vm *VirtualMachine) AddIgnitionFileFromCmdLine(cmdlineOpts string) error

func (*VirtualMachine) AddTimeSyncFromCmdLine 

func (vm *VirtualMachine) AddTimeSyncFromCmdLine(cmdlineOpts string) error

func (*VirtualMachine) Cmd added in v0.1.0 

func (vm *VirtualMachine) Cmd(vfkitPath string) (*exec.Cmd, error)

Cmd creates an exec.Cmd to start vfkit with the configured devices. In particular it will set ExtraFiles appropriately when mapping a file with a network interface.

func (*VirtualMachine) NetworkBlockDevice added in v0.6.0 

func (vm *VirtualMachine) NetworkBlockDevice(deviceID string) *NetworkBlockDevice

func (*VirtualMachine) TimeSync 

func (vm *VirtualMachine) TimeSync() *TimeSync

func (*VirtualMachine) ToCmdLine added in v0.1.0 

func (vm *VirtualMachine) ToCmdLine() ([]string, error)

ToCmdLine generates a list of arguments for use with the os/exec package. These arguments will start a virtual machine with the devices/bootloader/... described by vm If the virtual machine configuration described by vm is invalid, an error will be returned.

func (*VirtualMachine) UnmarshalJSON added in v0.1.0 

func (vm *VirtualMachine) UnmarshalJSON(b []byte) error

UnmarshalJSON is a custom deserializer for VirtualMachine. The custom work is needed because VirtualMachine uses interfaces in its struct and JSON cannot determine which implementation of the interface to deserialize to.

func (*VirtualMachine) VirtioGPUDevices added in v0.1.0 

func (vm *VirtualMachine) VirtioGPUDevices() []*VirtioGPU

func (*VirtualMachine) VirtioVsockDevices 

func (vm *VirtualMachine) VirtioVsockDevices() []*VirtioVsock

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.