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
Documentation
¶
Overview ¶
Package qmp enables interaction with QEMU instances via the QEMU Machine Protocol (QMP).
Index ¶
Constants ¶
This section is empty.
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.
Functions ¶
This section is empty.
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() (<-chan Event, error)
Events streams QEMU QMP Events. 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.
type LibvirtShellMonitor ¶
type LibvirtShellMonitor struct {
// contains filtered or unexported fields
}
A LibvirtShellMonitor is a Monitor which shells out to virsh to communicate with a QEMU Machine Protocol (QMP) socket. Communication is proxied via the libvirtd daemon. Multiple connections to the same hypervisor and domain are permitted.
func NewLibvirtShellMonitor ¶
func NewLibvirtShellMonitor(uri, domain string) (*LibvirtShellMonitor, error)
NewLibvirtShellMonitor configures a connection to the provided hypervisor and domain. An error is returned if the provided libvirt connection URI is invalid.
Hypervisor URIs may be local or remote, e.g.,
qemu:///system qemu+ssh://libvirt@example.com/system
func (LibvirtShellMonitor) Connect ¶
func (mon LibvirtShellMonitor) Connect() error
Connect sets up a QEMU QMP connection via libvirt's QEMU monitor socket. An error is returned if the libvirt daemon is unreachable.
func (*LibvirtShellMonitor) Disconnect ¶
func (mon *LibvirtShellMonitor) Disconnect() error
Disconnect tears down open QMP socket connections.
func (*LibvirtShellMonitor) Events ¶
func (mon *LibvirtShellMonitor) Events() (<-chan Event, error)
Events streams QEMU QMP Events. 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.
type Monitor ¶
type Monitor interface {
Connect() error
Disconnect() error
Run(command []byte) (out []byte, err error)
Events() (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
// 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 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() (<-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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package qmptest provides types which assist in testing interactions with package qmp.
|
Package qmptest provides types which assist in testing interactions with package qmp. |
|
Package raw provides automatically generated QMP types based on the QMP schema.
|
Package raw provides automatically generated QMP types based on the QMP schema. |