Documentation/QMP

QEMU Monitor Protocol

The QEMU Monitor Protocol (QMP) is a JSON-based protocol which allows applications to communicate with QEMU's Monitor the right way.

QMP's main features are:

• Lightweight, text-based, easy to parse data format
• Asynchronous messages support (ie. events)
• Capabilities negotiation
• API/ABI stability guarantees

Please, check the README file for more information.

Status

A supported version of QMP is available since QEMU 0.13 (and a "feature preview" version was available in QEMU 0.12), however several commands in the current API have badly defined semantics.

This means that we will be introducing a deprecation policy soon. Users should always check QMP's documentation as soon as a new release of QEMU is out, so that they don't run in the risk of using a deprecated command which may be removed in a future release.

Examples

In the following examples, 'C' stands for 'Client' and 'S' stands for 'Server'.

Server Greeting

S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 13, "major": 0 }, "package": "" }, "capabilities": []}}

Query VM status

C: { "execute": "query-status" }
S: { "return": { "singlestep": false, "running": true } }

Eject a medium

C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
S: { "return": {}}

Asynchronous message

S: { "event": "BLOCK_IO_ERROR",
     "data": { "device": "ide0-hd1",
               "operation": "write",
               "action": "stop" },
     "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }

Development

Main developers are Luiz Capitulino and Markus Armbruster, but all QMP-related discussions happen on the qemu-devel mailing list.

Next features, hot fixes and other patches are stored in the QMP unstable repository:

http://repo.or.cz/w/qemu/qmp-unstable.git

IMPORTANT: all branches in this repository are constantly rebased (master inclusive).

TODO

short term

• Decouple HMP and QMP
• Re-work the error infrastructure
• HMP passthrough via QMP
• Improve QMP testing (unit-tests, kvm-autoest and libvirt-TCK)

medium/long term

• Self-description & improved user documentation
• Asynchronous commands support
• Keep adding well defined commands

Testing

This section describes the following ways of testing QMP:

• By hand (cumbersome, only worth it if you're chasing a specific bug)
• qmp-shell script (automates part of the job)
• Libvirt integration (assumes familiarity with libvirt)
• libvirt-TCK
• kvm-autotest

Please, note that it's very recommended to read the README and spec files, as some of the testing procedures may require knowledge about the protocol format.

By hand

1. Start QMP on a TCP socket, so that telnet can be used

# qemu [...] -qmp tcp:localhost:4444,server

2. Run telnet

$ telnet localhost 4444

3. You should see the following prompt

{"QMP": {"version": {"qemu": {"micro": 50, "minor": 13, "major": 0}, "package": ""}, "capabilities": []}}

4. Now you can issue commands. For example, to get a list of QMP supported commands, type query-commands

{ "execute": "query-commands" }

NOTE: all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".

qmp-shell script

This script is available under the QMP directory in QEMU's source-tree. It automates a bit the testing work, as it can construct commands objects for you.

1. Start QMP on a unix socket, like:

# qemu [...] -qmp unix:./qmp-sock,server

2. Run the script

# qmp-shell ./qmp-sock

3. You should get the following prompt

(QEMU)

4. Now you can run commands. For example, let's change the VNC password:

(QEMU) change device=vnc target=password arg='1234'

Libvirt

Libvirt already got QMP support, but it's currently disabled. This test procedure explains how to enable it, so that you can have libvirt running on top of QMP.

1. Install yajl-devel (If you're running Fedora 12 or above just do 'yum install yajl-devel')

2. From a fresh checkout of libvirt master branch run the following:

./autogen.sh --system --enable-compile-warnings=error

NOTE (1): The '--system' flag is a shortcut for compiling with the --prefix and other directories matching a system RPM build.

NOTE (2): Make sure the final summary of autogen.sh tells you that it found the yajl library

3. To enable QMP support, edit src/qemu/qemu_conf.c and find:

#if 0
   if (version >= 13000)
       flags |= QEMUD_CMD_FLAG_MONITOR_JSON;
#endif

Change to '#if 1', and change the version to 12000 so it detects your GIT build of QEMU

4. Run 'make' to build. There is no need to 'make install' anything especially since that would overwrite your RPM based install

5. As root simply stop the current daemon & start the one you built

/etc/init.d/libvirtd stop
$HOME/your/git/checkout/of/libvirt/daemon/libvirtd

6. As root you can use the newly built virsh too

cd $HOME/your/git/checkout/of/libvirt/src
./virsh <BLAH>

Libvirt-TCK

TODO: describe libvirt's testing tool.

kvm-autotest

TODO: describe kvm-autotest QMP support.