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.

General Status

A supported version of QMP is available since QEMU 0.13 (and a "feature preview" version 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 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 version

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
• Begin adding sane commands
• Asynchronous commands support