Documentation/QMP

QEMU Machine Protocol

The QEMU Machine Protocol (QMP) is a JSON-based protocol which allows applications to control a QEMU instance.

Features:

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

Please, also check the README file.

Examples

The first example explains some important details about QMP. The others are simpler and run on top of the first one.

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

Capabilities Negotiation

When a new QMP connection is established, QMP sends its greeting message and enters capabilities negotiation mode. In this mode, only the "qmp_capabilities" command works. To exit negotiation mode and enter command mode, the qmp_capabilities command must be issued.

 S: {
        "QMP": {
            "version": {
                "qemu": {
                    "micro": 0,
                    "minor": 0,
                    "major": 1
                },
                "package": ""
            },
            "capabilities": [
            ]
        }
    }
C: { "execute": "qmp_capabilities" }
S: { "return": {}}

The "{ "return": {}}" response is QMP's success response. An error response will contain the "error" keyword instead of "return".

Eject a medium

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

Query VM status

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

Asynchronous message

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

Development

Main developer in charge is Luiz Capitulino. 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

More or less in order of dependency and importance.

• Finish conversion of old QMP commands to the QAPI
  • Missing commands: add_graphics_client, device_add, screen_dump
  • Commands that possibly depend on the new QMP server: closefd, getfd, qmp_capabilities
• Improve QMP testing
• Integrate the new QMP server (from Anthony's tree)
• Add asynchronous command support
• Convert (possibly all) HMP commands to the QAPI
  • Will make them "appear" on QMP
  • Will make it possible to make HMP a QMP front-end
• Add the "event" QAPI type
• Add schema instrospection
• Improve QError errors

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 QMP's greeting banner

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

4. Issue the qmp_capabilities command, so that QMP enters command mode

{ "execute": "qmp_capabilities" }

5. You can now issue commands. For example, to get a list of QMP supported commands, issue query-commands

{ "execute": "query-commands" }

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

There's an optimization to this procedure in case you plan to use it often (eg. QMP development):

1. Install programs socat and rlwrap. If you're running Fedora, you can do

# yum install socat rlwrap

2. Add the following sections to your QEMU config file (or create a qemu-qmp.conf one):

[chardev "qmp"]
  backend = "socket"
  path = "path to the QMP unix socket"
  server = "on"
  wait = "off"
[mon "qmp"]
  mode = "control"
  chardev = "qmp"

3. Run QEMU

# qemu [...] -readconfig qemu-qmp.conf

4. Run rlwrap

# rlwrap -C qmp socat STDIO UNIX:path-to-the-QMP-unix-socket

You can now issue commands, rlwrap will give you readline support (including persistent history).

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

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

2. Run the script

# qmp-shell ./qmp-sock

3. You should get the following prompt

(QEMU)

4. You can now issue commands. For example, let's add a new device

(QEMU) device_add driver=e1000 id=net1

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.

Other information

• Luiz's QMP talk on KVM Forum 2010 can be found here
• Old QMP page can be accessed here