QEMU Machine Protocol

Introduction

The QEMU Machine Protocol (QMP) allows applications to operate a QEMU instance.

QMP is JSON based and features the following:

  • Lightweight, text-based, easy to parse data format
  • Asynchronous messages support (ie. events)
  • Capabilities Negotiation

For detailed information on QMP’s usage, please, refer to the following files:

  • qmp-spec.txt QEMU Machine Protocol current specification
  • qemu-qmp-ref.html QEMU QMP commands and events (auto-generated at build-time)

Usage

You can use the -qmp option to enable QMP. For example, the following makes QMP available on localhost port 4444:

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

However, for more flexibility and to make use of more options, the -mon command-line option should be used. For instance, the following example creates one HMP instance (human monitor) on stdio and one QMP instance on localhost port 4444:

$ qemu [...] -chardev stdio,id=mon0 -mon chardev=mon0,mode=readline \
   -chardev socket,id=mon1,host=localhost,port=4444,server,nowait \
   -mon chardev=mon1,mode=control,pretty=on

Please, refer to QEMU’s manpage for more information.

Simple Testing

To manually test QMP one can connect with telnet and issue commands by hand:

$ telnet localhost 4444 Trying 127.0.0.1... Connected to localhost.
Escape character is '^]'. { "QMP": { "version": { "qemu": { "micro": 50,
"minor": 6, "major": 1 }, "package": "" }, "capabilities": [ ] } }

{ "execute": "qmp\_capabilities" } { "return": { } }

{ "execute": "query-status" } { "return": { "status": "prelaunch",
"singlestep": false, "running": false } }

Please, refer to the qapi-schema.json file for a complete command reference.