taskcluster-worker: github.com/taskcluster/taskcluster-worker/engines/qemu/vm Index | Files

package vm

import "github.com/taskcluster/taskcluster-worker/engines/qemu/vm"

Package vm provides virtual machine abstractions using QEMU.


Package Files

doc.go image.go limits.go machine.go migrate.go network.go vm.go


var MachineLimitsSchema = schematypes.Object{
    Title: "Machine Limits",
    Description: util.Markdown("" /* 184 byte string literal not displayed */,
    Properties: schematypes.Properties{
        "maxMemory": schematypes.Integer{
            Title: "Max Memory",
            Description: util.Markdown("" /* 239 byte string literal not displayed */,
            Minimum: 0,
            Maximum: 1024 * 1024,
        "maxCPUs": schematypes.Integer{
            Title: "Max CPUs",
            Description: util.Markdown("" /* 327 byte string literal not displayed */,
            Minimum: 1,
            Maximum: 255,
        "defaultThreads": schematypes.Integer{
            Title: "Default CPU Threads",
            Description: util.Markdown("" /* 243 byte string literal not displayed */,
            Minimum: 1,
            Maximum: 255,
    Required: []string{

MachineLimitsSchema is the schema for MachineOptions.

var MachineSchema schematypes.Schema = schematypes.Object{
    Title:       "Machine Configuration",
    Description: `Hardware definition for a virtual machine`,
    Properties: schematypes.Properties{
        "version": schematypes.IntegerEnum{
            Title:   "Format Version",
            Options: []int{machineFormatVersion},
        "uuid": schematypes.String{
            Title:       "System UUID",
            Description: `System UUID for the virtual machine`,
            Pattern:     `^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`,
        "chipset": schematypes.StringEnum{
            Title:   "Chipset",
            Options: []string{"pc-i440fx-2.8"},
        "cpu": schematypes.StringEnum{
            Title: "CPU",
            Description: util.Markdown("" /* 172 byte string literal not displayed */,
            Options: []string{"host"},
        "flags": schematypes.Array{
            Items: schematypes.StringEnum{},
        "threads": schematypes.Integer{
            Description: "Threads per CPU core, leave undefined to get maximum available",
            Minimum:     1,
            Maximum:     255,
        "cores": schematypes.Integer{
            Description: "CPU cores per socket, leave undefined to get maximum available",
            Minimum:     1,
            Maximum:     255,
        "sockets": schematypes.Integer{
            Description: "CPU sockets in machine, leave undefined to get maximum available",
            Minimum:     1,
            Maximum:     255,
        "memory": schematypes.Integer{
            Title:       "Memory",
            Description: `Memory in MiB, defaults to maximum available, if not specified.`,
            Minimum:     1,
            Maximum:     1024 * 1024,
        "usb": schematypes.StringEnum{
            Title:   "Host Controller Interface",
            Options: []string{"piix3-usb-uhci", "piix4-usb-uhci", "nec-usb-xhci"},
        "network": schematypes.StringEnum{
            Title:   "Network Interface Controller",
            Options: []string{"rtl8139", "e1000"},
        "mac": schematypes.String{
            Title:       "MAC Address",
            Description: `Local unicast MAC Address`,
            Pattern:     `^[0-9a-f][26ae](:[0-9a-f]{2}){5}$`,
        "storage": schematypes.StringEnum{
            Title:       "Storage Device",
            Description: `Block device to use for attaching storage`,
            Options:     []string{"virtio-blk-pci"},
        "graphics": schematypes.StringEnum{
            Options: []string{"VGA", "vmware-svga", "qxl-vga", "virtio-vga"},
        "sound": schematypes.StringEnum{
            Options: []string{
                "AC97", "ES1370",
                "hda-duplex/intel-hda", "hda-micro/intel-hda", "hda-output/intel-hda",
                "hda-duplex/ich9-intel-hda", "hda-micro/ich9-intel-hda", "hda-output/ich9-intel-hda",
        "keyboard": schematypes.StringEnum{
            Options: []string{"usb-kbd", "PS/2"},
        "keyboardLayout": schematypes.StringEnum{
            Options: []string{
                "ar", "da", "de", "de-ch", "en-gb", "en-us", "es", "et", "fi", "fo",
                "fr", "fr-be", "fr-ca", "fr-ch", "hr", "hu", "is", "it", "ja", "lt",
                "lv", "mk", "nl", "nl-be", "no", "pl", "pt", "pt-br", "ru", "sl",
                "sv", "th", "tr",
        "mouse": schematypes.StringEnum{
            Options: []string{"usb-mouse", "PS/2"},
        "tablet": schematypes.StringEnum{
            Options: []string{"usb-tablet", "none"},
    Required: []string{"version"},

MachineSchema must be satisfied by config passed to NewMachine

func MigrateMachineDefinition Uses

func MigrateMachineDefinition(definition interface{}) interface{}

MigrateMachineDefinition takes a machine definition and migrates it to the latest format version, and returns nil, if format is not supported.

type Image Uses

type Image interface {
    DiskFile() string // Primary disk file to be used as boot disk.
    Format() string   // Image format 'qcow2', 'raw', etc.
    Machine() Machine // Machine configuration.
    Release()         // Free resources held by this image instance.

An Image provides an instance of a virtual machine image that a virtual machine can be started from.

func OverwriteMachine Uses

func OverwriteMachine(image Image, machine Machine) Image

OverwriteMachine returns an image with a machine definition whose properties is overwritten by machine given here.

type LinuxBootOptions Uses

type LinuxBootOptions struct {
    Kernel string // -kernel <bzImage>
    Append string // -append <cmdline>
    Initrd string // -initrd <file>

LinuxBootOptions holds optionals boot options for Linux. These are exclusively useful for building images and should not be used in production when running per-task VMs. But they can greatly simplify image building by facilitating injection of arguments for the Linux kernel.

type Machine Uses

type Machine struct {
    // contains filtered or unexported fields

Machine specifies arguments for various QEMU options.

Machine objects can be combined using the WithDefaults() method which creates a new Machine from two Machine objects, merging the machine definitions. The empty Machine value specifies nothing and will be fully overwritten with defaults if used as target of WithDefaults(). Effectively, the empty Machine definition will assume whatever default values are given.

func NewMachine Uses

func NewMachine(definition interface{}) Machine

NewMachine returns a new machine from definition matching MachineSchema

func (Machine) ApplyLimits Uses

func (m Machine) ApplyLimits(limits MachineLimits) (Machine, error)

ApplyLimits returns an Machine with defaults extracted from the limits, or a MalformedPayloadError if limits were violated.

func (Machine) DeriveLimits Uses

func (m Machine) DeriveLimits() MachineLimits

DeriveLimits constructs sane MachineLimits that permits the machine.

func (Machine) MarshalJSON Uses

func (m Machine) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler

func (Machine) WithDefaults Uses

func (m Machine) WithDefaults(defaults Machine) Machine

WithDefaults creates a new Machine with empty-values in c defaulting to defaults.

type MachineLimits Uses

type MachineLimits struct {
    MaxMemory      int `json:"maxMemory"`
    MaxCPUs        int `json:"maxCPUs"`
    DefaultThreads int `json:"defaultThreads"`

MachineLimits imposes limits on a virtual machine definition.

type MutableImage Uses

type MutableImage interface {
    Package(targetFile string) error // Package the as zstd compressed tar archive

A MutableImage is an instance of a virtual machine image similar to to Image, except that it can also be packaged into a compressed image tar archive as used for input by image manager.

type Network Uses

type Network interface {
    NetDev(ID string) string         // Argument for the QEMU -netdev option
    SetHandler(handler http.Handler) // Set http.Handler for
    Release()                        // Release the network after use

A Network provides a -netdev argument for QEMU, isolation and an HTTP server that will handle requests for Ensuring that the requests orignates from the virtual machine wit hthe -netdev argument.

type VirtualMachine Uses

type VirtualMachine struct {
    Done  <-chan struct{} // Closed when the virtual machine is done
    Error error           // Error, to be read after Done is closed
    // contains filtered or unexported fields

VirtualMachine holds the QEMU process and associated resources. This is useful as the VM remains alive in the ResultSet stage, as we use guest tools to copy files from the virtual machine.

func NewVirtualMachine Uses

func NewVirtualMachine(
    limits MachineLimits,
    image Image, network Network, socketFolder, cdrom1, cdrom2 string,
    bootOptions LinuxBootOptions,
    monitor runtime.Monitor,
) (*VirtualMachine, error)

NewVirtualMachine constructs a new virtual machine using the given machineOptions, image, network and cdroms.

Returns engines.MalformedPayloadError if machineOptions and image definition are conflicting. If this returns an error, caller is responsible for releasing all resources, otherwise, they will be held by the VirtualMachine object.

func (*VirtualMachine) Kill Uses

func (vm *VirtualMachine) Kill()

Kill the virtual machine, can only be called after Start()

func (*VirtualMachine) Screenshot Uses

func (vm *VirtualMachine) Screenshot() (image.Image, error)

Screenshot takes a screenshot of the virtual machine screen as is running.

func (*VirtualMachine) SetHTTPHandler Uses

func (vm *VirtualMachine) SetHTTPHandler(handler http.Handler)

SetHTTPHandler sets the HTTP handler for the meta-data service.

func (*VirtualMachine) Start Uses

func (vm *VirtualMachine) Start()

Start the virtual machine.

func (*VirtualMachine) VNCSocket Uses

func (vm *VirtualMachine) VNCSocket() string

VNCSocket returns the path to VNC socket, empty-string if closed.

Package vm imports 24 packages (graph) and is imported by 4 packages. Updated 2018-04-10. Refresh now. Tools for package owners.