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 ¶
- Variables
- type Command
- type Event
- type LibvirtRPCMonitor
- type Monitor
- type SocketMonitor
- 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
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(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.
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 ¶
RunWithFile behaves like Run but allows for passing a file through out-of-band data.
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. |