qmp

README

QMP

Package qmp enables interaction with QEMU instances via the QEMU Machine Protocol (QMP).

Available Drivers

Libvirt

If your environment is managed by Libvirt, QMP interaction must be proxied through the Libvirt daemon. This can be be done through two available drivers:

RPC

The RPC driver provides a pure Go implementation of Libvirt's RPC protocol.

//conn, err := net.DialTimeout("unix", "/var/run/libvirt/libvirt-sock", 2*time.Second)
conn, err := net.DialTimeout("tcp", "192.168.1.1:16509", 2*time.Second)
monitor := libvirtrpc.New("stage-lb-1", conn)

virsh

A connection to the monitor socket is provided by proxing requests through the virsh executable.

monitor, err := qmp.NewLibvirtMonitor("qemu:///system", "stage-lb-1")

Socket

If your QEMU instances are not managed by libvirt, direct communication over its UNIX socket is available.

monitor, err := qmp.NewSocketMonitor("unix", "/var/lib/qemu/example.monitor", 2*time.Second)

Examples

Using the above to establish a new qmp.Monitor, the following examples provide a brief overview of QMP usage.

error checking omitted for the sake of brevity.

Command Execution

type StatusResult struct {
	ID     string `json:"id"`
	Return struct {
		Running    bool   `json:"running"`
		Singlestep bool   `json:"singlestep"`
		Status     string `json:"status"`
	} `json:"return"`
}

monitor.Connect()
defer monitor.Disconnect()

cmd := []byte(`{ "execute": "query-status" }`)
raw, _ := monitor.Run(cmd)

var result StatusResult
json.Unmarshal(raw, &result)

fmt.Println(result.Return.Status)

running

Event Monitor

monitor.Connect()
defer monitor.Disconnect()

stream, _ := monitor.Events()
for e := range stream {
	log.Printf("EVENT: %s", e.Event)
}

$ virsh reboot example
Domain example is being rebooted

EVENT: POWERDOWN
EVENT: SHUTDOWN
EVENT: STOP
EVENT: RESET
EVENT: RESUME
EVENT: RESET
...

More information

• QEMU QMP Wiki
• QEMU QMP Intro
• QEMU QMP Events
• QEMU QMP Spec

Documentation

Overview

Package qmp enables interaction with QEMU instances via the QEMU Machine Protocol (QMP).

Index

• Variables
• type Command
• type Event
• type LibvirtRPCMonitor
  • func NewLibvirtRPCMonitor(domain string, conn net.Conn) *LibvirtRPCMonitor
  • func (rpc *LibvirtRPCMonitor) Connect() error
  • func (rpc *LibvirtRPCMonitor) Disconnect() error
  • func (rpc *LibvirtRPCMonitor) Events(ctx context.Context) (<-chan Event, error)
  • func (rpc *LibvirtRPCMonitor) Run(cmd []byte) ([]byte, error)
• type Monitor
• type SocketMonitor
  • func Listen(network, addr string) (*SocketMonitor, error)
  • func NewSocketMonitor(network, addr string, timeout time.Duration) (*SocketMonitor, error)
  • func (mon *SocketMonitor) Connect() error
  • func (mon *SocketMonitor) Disconnect() error
  • func (mon *SocketMonitor) Events(context.Context) (<-chan Event, error)
  • func (mon *SocketMonitor) Run(command []byte) ([]byte, error)
  • func (mon *SocketMonitor) RunWithFile(command []byte, file *os.File) ([]byte, error)
• type Version
  • func (v Version) String() string

Variables

var ErrEventsNotSupported = errors.New("event monitor is not supported")

ErrEventsNotSupported is returned by Events() if event streams are unsupported by either QEMU or libvirt.

Types

type Command

type Command struct {
	// Name of the command to run
	Execute string `json:"execute"`

	// Optional arguments for the above command.
	Args interface{} `json:"arguments,omitempty"`
}

Command represents a QMP command.

type Event

type Event struct {
	// Event name, e.g., BLOCK_JOB_COMPLETE
	Event string `json:"event"`

	// Arbitrary event data
	Data map[string]interface{} `json:"data"`

	// Event timestamp, provided by QEMU.
	Timestamp struct {
		Seconds      int64 `json:"seconds"`
		Microseconds int64 `json:"microseconds"`
	} `json:"timestamp"`
}

Event represents a QEMU QMP event. See http://wiki.qemu.org/QMP

type LibvirtRPCMonitor

type LibvirtRPCMonitor struct {

	// Domain name as seen by libvirt, e.g., stage-lb-1
	Domain string
	// contains filtered or unexported fields
}

A LibvirtRPCMonitor implements LibVirt's remote procedure call protocol.

func NewLibvirtRPCMonitor

func NewLibvirtRPCMonitor(domain string, conn net.Conn) *LibvirtRPCMonitor

NewLibvirtRPCMonitor configures a new Libvirt RPC Monitor connection. The provided domain should be the name of the domain as seen by libvirt, e.g., stage-lb-1.

func (*LibvirtRPCMonitor) Connect

func (rpc *LibvirtRPCMonitor) Connect() error

Connect establishes communication with the libvirt server. The underlying libvirt socket connection must be previously established.

func (*LibvirtRPCMonitor) Disconnect

func (rpc *LibvirtRPCMonitor) Disconnect() error

Disconnect shuts down communication with the libvirt server and closes the underlying net.Conn.

func (*LibvirtRPCMonitor) Events

func (rpc *LibvirtRPCMonitor) Events(ctx context.Context) (<-chan Event, error)

Events streams QEMU QMP Events until the provided context is cancelled. If a problem is encountered setting up the event monitor connection an error will be returned. Errors encountered during streaming will cause the returned event channel to be closed.

func (*LibvirtRPCMonitor) Run

func (rpc *LibvirtRPCMonitor) Run(cmd []byte) ([]byte, error)

Run executes the given QAPI command against a domain's QEMU instance. For a list of available QAPI commands, see:

http://git.qemu.org/?p=qemu.git;a=blob;f=qapi-schema.json;hb=HEAD

type Monitor

type Monitor interface {
	Connect() error
	Disconnect() error
	Run(command []byte) (out []byte, err error)
	Events(context.Context) (events <-chan Event, err error)
}

Monitor represents a QEMU Machine Protocol socket. See: http://wiki.qemu.org/QMP

type SocketMonitor

type SocketMonitor struct {
	// QEMU version reported by a connected monitor socket.
	Version *Version

	// QEMU QMP capabiltiies reported by a connected monitor socket.
	Capabilities []string
	// contains filtered or unexported fields
}

A SocketMonitor is a Monitor which speaks directly to a QEMU Machine Protocol (QMP) socket. Communication is performed directly using a QEMU monitor socket, typically using a UNIX socket or TCP connection. Multiple connections to the same domain are not permitted, and will result in the monitor blocking until the existing connection is closed.

func Listen

func Listen(network, addr string) (*SocketMonitor, error)

Listen creates a new SocketMonitor listening for a single connection to the provided socket file or address. An error is returned if unable to listen at the specified file path or port.

Listen will wait for a QEMU socket connection using a variety connection types:

Listen("unix", "/var/lib/qemu/example.monitor")
Listen("tcp", "0.0.0.0:4444")

func NewSocketMonitor

func NewSocketMonitor(network, addr string, timeout time.Duration) (*SocketMonitor, error)

NewSocketMonitor configures a connection to the provided QEMU monitor socket. An error is returned if the socket cannot be successfully dialed, or the dial attempt times out.

NewSocketMonitor may dial the QEMU socket using a variety of connection types:

NewSocketMonitor("unix", "/var/lib/qemu/example.monitor", 2 * time.Second)
NewSocketMonitor("tcp", "8.8.8.8:4444", 2 * time.Second)

func (*SocketMonitor) Connect

func (mon *SocketMonitor) Connect() error

Connect sets up a QEMU QMP connection by connecting directly to the QEMU monitor socket. An error is returned if the capabilities handshake does not succeed.

func (*SocketMonitor) Disconnect

func (mon *SocketMonitor) Disconnect() error

Disconnect closes the QEMU monitor socket connection.

func (*SocketMonitor) Events

func (mon *SocketMonitor) Events(context.Context) (<-chan Event, error)

Events streams QEMU QMP Events. Events should only be called once per Socket. If used with a qemu.Domain, qemu.Domain.Events should be called to retrieve events instead.

func (*SocketMonitor) Run

func (mon *SocketMonitor) Run(command []byte) ([]byte, error)

Run executes the given QAPI command against a domain's QEMU instance. For a list of available QAPI commands, see:

http://git.qemu.org/?p=qemu.git;a=blob;f=qapi-schema.json;hb=HEAD

func (*SocketMonitor) RunWithFile

func (mon *SocketMonitor) RunWithFile(command []byte, file *os.File) ([]byte, error)

RunWithFile behaves like Run but allows for passing a file through out-of-band data.

type Version

type Version struct {
	Package string `json:"package"`
	QEMU    struct {
		Major int `json:"major"`
		Micro int `json:"micro"`
		Minor int `json:"minor"`
	} `json:"qemu"`
}

Version is the QEMU version structure returned when a QMP connection is initiated.

func (Version) String

func (v Version) String() string