go-qemu: github.com/digitalocean/go-qemu/qemu Index | Examples | Files

package qemu

import "github.com/digitalocean/go-qemu/qemu"

Package qemu provides an interface for interacting with running QEMU instances.



Package Files

block.go cpu.go domain.go pci.go string.gen.go tempfile.go


var (
    // ErrBlockDeviceNotFound is returned given when a block device is not found
    ErrBlockDeviceNotFound = errors.New("block device not found")

type BlockDevice Uses

type BlockDevice struct {
    Device   string `json:"device"`
    Inserted struct {
        BackingFile      string `json:"backing_file"`
        BackingFileDepth int    `json:"backing_file_depth"`
        BPS              int    `json:"bps"`
        BPSRead          int    `json:"bps_rd"`
        BPSWrite         int    `json:"bps_wr"`
        Cache            struct {
            Direct    bool `json:"direct"`
            NoFlush   bool `json:"no-flush"`
            Writeback bool `json:"writeback"`
        }   `json:"cache"`
        DetectZeroes         string `json:"detect_zeroes"`
        Driver               string `json:"drv"`
        Encrypted            bool   `json:"encrypted"`
        EncryptionKeyMissing bool   `json:"encryption_key_missing"`
        File                 string `json:"file"`
        Image                Image  `json:"image"`
        IOPs                 int    `json:"iops"`
        IOPsRead             int    `json:"iops_rd"`
        IOPsWrite            int    `json:"iops_wr"`
        NodeName             string `json:"node-name"`
        ReadOnly             bool   `json:"ro"`
        WriteThreshold       int    `json:"write_threshold"`
    }   `json:"inserted"`
    IOStatus  string `json:"io-status"`
    Locked    bool   `json:"locked"`
    Removable bool   `json:"removable"`
    Type      string `json:"type"`

BlockDevice represents a QEMU block device.

func (BlockDevice) CancelJob Uses

func (bd BlockDevice) CancelJob(d *Domain, timeout time.Duration) error

CancelJob cancels any active block jobs on a block device. For block-mirror operations, this completes the block job.

func (BlockDevice) Commit Uses

func (bd BlockDevice) Commit(d *Domain, overlay string, timeout time.Duration) error

Commit synchronously merges an overlay image onto a block device's root backing image. Once the operation is complete, CompleteJob() must be called to pivot the domain back to the original backing image.

func (BlockDevice) CompleteJob Uses

func (bd BlockDevice) CompleteJob(d *Domain, timeout time.Duration) error

CompleteJob finalizes any running block jobs on the provided block device. For blockcommit backups, this performs the "pivot" back to the original backing image.

func (BlockDevice) Mirror Uses

func (bd BlockDevice) Mirror(d *Domain, dest string, timeout time.Duration) error

Mirror copies a block device to the given destination. The destination path specified by dest must be absolute.

func (BlockDevice) Snapshot Uses

func (bd BlockDevice) Snapshot(d *Domain, overlay string) error

Snapshot creates a point in time snapshot. The disk's image is given a new QCOW2 overlay, leaving the underlying image in a state that is considered safe for copying.

type BlockJob Uses

type BlockJob struct {
    Busy     bool   `json:"busy"`
    Device   string `json:"device"`
    IOStatus string `json:"io-status"`
    Len      int    `json:"len"`
    Offset   int    `json:"offset"`
    Paused   bool   `json:"paused"`
    Ready    bool   `json:"ready"`
    Speed    int    `json:"speed"`
    Type     string `json:"type"`

BlockJob represents a QEMU blockjob.

type BlockStats Uses

type BlockStats struct {
    // Device does not actually appear QEMU's output, but is added
    // by this package.
    Device string `json:"-"`

    AccountFailed             bool   `json:"account_failed"`
    AccountInvalid            bool   `json:"account_invalid"`
    FailedFlushOperations     int    `json:"failed_flush_operations"`
    FailedReadOperations      int    `json:"failed_rd_operations"`
    FailedWriteOperations     int    `json:"failed_wr_operations"`
    FlushOperations           int    `json:"flush_operations"`
    FlushTotalTimeNanoseconds int64  `json:"flush_total_time_ns"`
    IdleTimeNanoseconds       int64  `json:"idle_time_ns"`
    InvalidFlushOperations    int    `json:"invalid_flush_operations"`
    InvalidReadOperations     int    `json:"invalid_rd_operations"`
    InvalidWriteOperations    int    `json:"invalid_wr_operations"`
    ReadBytes                 uint64 `json:"rd_bytes"`
    ReadMerged                int    `json:"rd_merged"`
    ReadOperations            int    `json:"rd_operations"`
    ReadTotalTimeNanoseconds  int    `json:"rd_total_time_ns"`
    WriteBytes                uint64 `json:"wr_bytes"`
    WriteHighestOffset        int64  `json:"wr_highest_offset"`
    WriteMerged               int    `json:"wr_merged"`
    WriteOperations           int    `json:"wr_operations"`
    WriteTotalTimeNanoseconds int64  `json:"wr_total_time_ns"`

BlockStats represents QEMU block device statistics.

type CPU Uses

type CPU struct {
    CPU     int  `json:"cpu"`
    Current bool `json:"current"`
    Halted  bool `json:"halted"`
    PC      int  `json:"pc"`

CPU represents a QEMU CPU.

type Domain Uses

type Domain struct {
    Name string
    // contains filtered or unexported fields

Domain represents a QEMU instance.

func NewDomain Uses

func NewDomain(m qmp.Monitor, name string) (*Domain, error)

NewDomain returns a new QEMU domain identified by the given name. QMP communication is handled by the provided monitor socket.

This example demonstrates how to use qemu.NewDomain with a qmp.Monitor to perform actions on a Domain.

Typically, these actions would be performed using an actual monitor of type qmp.LibvirtRPCMonitor or qmp.SocketMonitor, instead of using qmptest.NewMonitor.


package main

import (


// This example demonstrates how to use qemu.NewDomain with a qmp.Monitor to
// perform actions on a Domain.
// Typically, these actions would be performed using an actual monitor of type
// qmp.LibvirtRPCMonitor or qmp.SocketMonitor, instead of using
// qmptest.NewMonitor.
func main() {
    // Use qmptest.NewMonitor to create an "example" qmp.Monitor, that returns
    // mock data from another function.
    // Normally, qmp.NewLibvirtRPCMonitor or qmp.NewSocketMonitor would be used
    // here instead.
    mon := qmptest.NewMonitor(func(cmd qmp.Command) (interface{}, error) {
        return exampleRun(cmd)

    // Monitor must be connected before it can be used.
    if err := mon.Connect(); err != nil {
        log.Fatalf("failed to connect monitor: %v", err)

    // Wrap monitor in a qemu.Domain to perform higher-level management actions.
    dom, err := qemu.NewDomain(mon, "example")
    if err != nil {
        log.Fatalf("failed to create domain: %v", err)

    // Return the domain's QEMU version.
    version, err := dom.Version()
    if err != nil {
        log.Fatalf("failed to check domain QEMU version: %v", err)

    // List the available QMP commands supported by the domain.
    commands, err := dom.Commands()
    if err != nil {
        log.Fatalf("failed to list domain commands: %v", err)

    // Print some information about the domain.
    fmt.Printf("%s - QEMU %s\n", dom.Name, version)
    fmt.Println("  - commands:")
    for _, c := range commands {
        fmt.Printf("    - %s\n", c)

    // Close the domain to clean up its resources and underlying monitor.
    if err := dom.Close(); err != nil {
        log.Fatalf("failed to close domain: %v", err)


func exampleRun(cmd qmp.Command) (interface{}, error) {
    switch cmd.Execute {
    case "query-commands":
        return runQueryCommands(), nil
    case "query-version":
        return runQueryVersion(), nil

    return nil, fmt.Errorf("unknown command: %q", cmd.Execute)

func runQueryCommands() interface{} {
    var response struct {
        ID     string        `json:"id"`
        Return []nameWrapper `json:"return"`

    commands := []string{

    response.Return = make([]nameWrapper, 0, len(commands))
    for _, c := range commands {
        response.Return = append(response.Return, nameWrapper{
            Name: c,

    return response

func runQueryVersion() interface{} {
    var response struct {
        ID     string      `json:"id"`
        Return qmp.Version `json:"return"`
    response.Return.QEMU.Major = 2

    return response

type nameWrapper struct {
    Name string `json:"name"`

func (*Domain) BlockDevice Uses

func (d *Domain) BlockDevice(name string) (BlockDevice, error)

BlockDevice searches a domain for the given block device. If found, a BlockDevice is returned. If the device is not found, the returned error will be ErrBlockDeviceNotFound.

func (*Domain) BlockDevices Uses

func (d *Domain) BlockDevices() ([]BlockDevice, error)

BlockDevices returns a domain's block devices.

func (*Domain) BlockJobs Uses

func (d *Domain) BlockJobs() ([]BlockJob, error)

BlockJobs returns active block job operations.

func (*Domain) BlockStats Uses

func (d *Domain) BlockStats() ([]BlockStats, error)

BlockStats returns block device statistics for a domain.

func (*Domain) CPUs Uses

func (d *Domain) CPUs() ([]CPU, error)

CPUs returns a domain's CPUs.

func (*Domain) Close Uses

func (d *Domain) Close() error

Close cleans up internal resources of a Domain and disconnects the underlying qmp.Monitor. Close must be called when done with a Domain to avoid leaking resources.

func (*Domain) Commands Uses

func (d *Domain) Commands() ([]string, error)

Commands returns all QMP commands supported by the domain.

func (*Domain) Events Uses

func (d *Domain) Events() (chan qmp.Event, chan struct{}, error)

Events streams QEMU QMP events. Two channels are returned, the first contains events emitted by the domain. The second is used to signal completion of event processing. It is the responsibility of the caller to always signal when finished.

func (*Domain) PCIDevices Uses

func (d *Domain) PCIDevices() ([]PCIDevice, error)

PCIDevices returns a domain's PCI devices.

func (*Domain) PackageVersion Uses

func (d *Domain) PackageVersion() (string, error)

PackageVersion returns the domain's QEMU package version, the full build information for QEMU.

func (*Domain) Run Uses

func (d *Domain) Run(c qmp.Command) ([]byte, error)

Run executes the given QMP command against the domain. The returned []byte is the raw output from the QMP monitor.

Run should be used with caution, as it allows the execution of arbitrary QMP commands against the domain.

func (*Domain) ScreenDump Uses

func (d *Domain) ScreenDump() (io.ReadCloser, error)

ScreenDump captures the domain's screen and creates an output PPM image stream. ScreenDump will only work if the Domain resides on a local hypervisor; not a remote one connected over SSH or TCP socket.

If needed, a PPM image can be decoded using Go's package image and a PPM decoder, such as https://godoc.org/github.com/jbuchbinder/gopnm.

func (*Domain) Status Uses

func (d *Domain) Status() (Status, error)

Status returns the current status of the domain.

func (*Domain) Supported Uses

func (d *Domain) Supported(cmd string) (bool, error)

Supported returns true if the provided command is supported by the domain.

func (*Domain) SystemPowerdown Uses

func (d *Domain) SystemPowerdown() error

SystemPowerdown sends a system power down event to the domain.

func (*Domain) SystemReset Uses

func (d *Domain) SystemReset() error

SystemReset sends a system reset event to the domain.

func (*Domain) Version Uses

func (d *Domain) Version() (string, error)

Version returns the domain's QEMU version.

type Image Uses

type Image struct {
    ActualSize            uint64 `json:"actual-size"`
    BackingFilename       string `json:"backing-filename"`
    BackingFilenameFormat string `json:"backing-filename-format"`
    BackingImage          struct {
        ActualSize  uint64 `json:"actual-size"`
        Dirty       bool   `json:"dirty-flag"`
        Filename    string `json:"filename"`
        Format      string `json:"format"`
        VirtualSize uint64 `json:"virtual-size"`
    }   `json:"backing-image"`
    ClusterSize    int    `json:"cluster-size"`
    Dirty          bool   `json:"dirty-flag"`
    Filename       string `json:"filename"`
    Format         string `json:"format"`
    FormatSpecific struct {
        Data struct {
            Compat        string `json:"compat"`
            Corrupt       bool   `json:"corrupt"`
            LazyRefcounts bool   `json:"lazy-refcounts"`
            RefcountBits  int    `json:"refcount-bits"`
        }   `json:"data"`
        Type string `json:"type"`
    }   `json:"format-specific"`
    VirtualSize uint64 `json:"virtual-size"`

Image represents a BlockDevice backing image.

type PCIDevice Uses

type PCIDevice struct {
    Bus       int    `json:"bus"`
    QdevID    string `json:"qdev_id"`
    Slot      int    `json:"slot"`
    ClassInfo struct {
        Class int    `json:"class"`
        Desc  string `json:"desc"`
    }   `json:"class_info"`
    ID  struct {
        Device int `json:"device"`
        Vendor int `json:"vendor"`
    }   `json:"id"`
    Function int `json:"function"`
    Regions  []struct {
        Prefetch  bool   `json:"prefetch"`
        MemType64 bool   `json:"mem_type_64"`
        Bar       int    `json:"bar"`
        Size      int    `json:"size"`
        Address   int64  `json:"address"`
        Type      string `json:"type"`
    }   `json:"regions"`

PCIDevice represents a QEMU PCI device.

type Status Uses

type Status int

Status represents the current status of the domain.

const (
    StatusDebug         Status = Status(raw.RunStateDebug)
    StatusFinishMigrate Status = Status(raw.RunStateFinishMigrate)
    StatusGuestPanicked Status = Status(raw.RunStateGuestPanicked)
    StatusIOError       Status = Status(raw.RunStateIOError)
    StatusInMigrate     Status = Status(raw.RunStateInmigrate)
    StatusInternalError Status = Status(raw.RunStateInternalError)
    StatusPaused        Status = Status(raw.RunStatePaused)
    StatusPostMigrate   Status = Status(raw.RunStatePostmigrate)
    StatusPreLaunch     Status = Status(raw.RunStatePrelaunch)
    StatusRestoreVM     Status = Status(raw.RunStateRestoreVM)
    StatusRunning       Status = Status(raw.RunStateRunning)
    StatusSaveVM        Status = Status(raw.RunStateSaveVM)
    StatusShutdown      Status = Status(raw.RunStateShutdown)
    StatusSuspended     Status = Status(raw.RunStateSuspended)
    StatusWatchdog      Status = Status(raw.RunStateWatchdog)

Status constants which indicate the status of a domain.

func (Status) String Uses

func (i Status) String() string

Package qemu imports 11 packages (graph) and is imported by 3 packages. Updated 2020-06-01. Refresh now. Tools for package owners.