Documentation/QMP: Difference between revisions

From QEMU
(Use wait=off instead of the obsolete nowait parameter)
 
(82 intermediate revisions by 8 users not shown)
Line 1: Line 1:
= QEMU Monitor Protocol =
= QEMU Machine Protocol =


The QEMU Monitor Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to communicate with QEMU's Monitor the right way.
The QEMU Machine Protocol (QMP) is a [http://www.json.org/ JSON]-based protocol which allows applications to control a QEMU instance.


QMP's main features are:
Features:


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


Please, check the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] file for more information.
Please, also check the [http://git.qemu.org/?p=qemu.git;a=blob_plain;f=docs/interop/qmp-intro.txt;hb=HEAD QMP intro] file for more information.


== General Status ==
== Examples ==


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.
The first example explains some important details about QMP. The others are simpler and run on top of the first one.


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.
In all examples "C" stands for "Client" and "S" stands for "Server".


== Examples ==
=== Capabilities Negotiation ===


In the following examples, 'C' stands for 'Client' and 'S' stands for 'Server'.
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 ''capabilities negotiation'' mode and enter ''command mode'', the qmp_capabilities command must be issued:


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


S: { "QMP": { "version": { "qemu": { "micro": 50, "minor": 13, "major": 0 }, "package": "" }, "capabilities": []}}
The ''{ "return": {} }'' response is QMP's success response. An error response will contain the "error" keyword instead of "return".


=== Query version ===
=== Eject a medium ===


  C: { "execute": "query-status" }
  C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
  S: { "return": { "singlestep": false, "running": true } }
  S: { "return": {}}


=== Eject a medium ===
=== Query VM status ===


  C: { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
  C: { "execute": "query-status" }
S: {"return": {}}
S: {
        "return": {
            "status": "running",
            "singlestep": false,
            "running": true
        }
    }


=== Asynchronous message ===
=== Asynchronous message ===
Line 43: Line 64:
                 "action": "stop" },
                 "action": "stop" },
       "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
       "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }


== Development ==
== Development ==


Main developers are [mailto:lcapitulino@redhat.com Luiz Capitulino] and [mailto:armbru@redhat.com Markus Armbruster], but all QMP-related discussions happen on the [http://lists.nongnu.org/mailman/listinfo/qemu-devel qemu-devel] mailing list.
QMP being a core part of QEMU, all discussions happen on the [http://lists.nongnu.org/mailman/listinfo/qemu-devel qemu-devel] mailing list.


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


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


'''IMPORTANT''': all branches in this repository are constantly ''rebased'' (master inclusive).
1. Start QMP on a TCP socket, so that telnet can be used


== TODO ==
# qemu [...] -qmp tcp:localhost:4444,server,wait=off


=== short term ===
2. Run telnet


* Decouple HMP and QMP
$ telnet localhost 4444
* Re-work the error infrastructure
* HMP passthrough via QMP
* Improve QMP testing (unit-tests, kvm-autoest and libvirt-TCK)


=== medium/long term ===
3. You should see QMP's greeting banner


* Self-description & improved user documentation
{"QMP": {"version": {"qemu": {"micro": 0, "minor": 6, "major": 1}, "package": ""}, "capabilities": []}}
* Begin adding sane commands
* Asynchronous commands support


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


This section describes four ways of testing QMP:
{ "execute": "qmp_capabilities" }


* By hand (difficult, only worth it if you're chasing a specific bug)
5. You can now issue commands. For example, to get a list of QMP supported commands, issue ''query-commands''
* qmp-shell script (automates part of the job)
* Libvirt integration (assumes familiarity with [http://libvirt.org libvirt])
* kvm-autotest


Please, note that it's very recommended to read the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/README README] and [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP/qmp-spec.txt spec] files, as some of the testing procedures below may require knowledge about the protocol format.
{ "execute": "query-commands" }


=== By hand ===
There's an optimization to this procedure in case you plan to use it often:


1. Start QMP on a TCP socket, so that telnet can be used
1. Install programs ''socat'' and ''rlwrap''. If you're running Fedora, you can do


  # qemu [...] -qmp tcp:localhost:4444,server
  # yum install socat rlwrap


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


  $ telnet localhost 4444
  [chardev "qmp"]
 
  backend = "socket"
3. You should see the following prompt
  path = "path to the QMP unix socket"
  server = "on"
  wait = "off"
[mon "qmp"]
  mode = "control"
  chardev = "qmp"
  pretty = "on"


{"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}
3. Run QEMU


4. Now you can issue commands. For example, to get a list of QMP supported commands, run ''query-commands''
# qemu [...] -readconfig qemu-qmp.conf


{ "execute": "query-commands" }
4. Run rlwrap


'''NOTE (1):''' all "info" commands are available under QMP as "query-", for example "info vnc" is "query-vnc".
# rlwrap -C qmp socat STDIO UNIX:path-to-the-QMP-unix-socket


'''NOTE (2):''' QMP doesn't have user documentation yet, this means that, to find out which arguments a command accepts or what's its output, you will have to either check the [http://git.savannah.gnu.org/cgit/qemu.git/tree/qemu-monitor.hx qemu-monitor.hx] file and/or the function which implements the command.
You can now issue commands, rlwrap will give you readline support (including persistent history).


=== qmp-shell script ===
=== qmp-shell script ===


This script is available under the [http://git.savannah.gnu.org/cgit/qemu.git/tree/QMP QMP] directory in QEMU's source-tree. It automates a bit the testing work, as it can construct commands.
This script is available under the [http://git.qemu.org/?p=qemu.git;a=tree;f=scripts/qmp;hb=HEAD scripts/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:
1. Start QMP on a unix socket


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


2. Run the script
2. Run the script
Line 119: Line 137:
  (QEMU)
  (QEMU)


4. Now you can run commands. For example, let's change the VNC password:
4. You can now issue commands. For example, let's add a new device
 
(QEMU) change device=vnc target=password arg='1234'
 
'''NOTE''': To find out what arguments a command accepts, you have to either check the [http://git.savannah.gnu.org/cgit/qemu.git/tree/qemu-monitor.hx qemu-monitor.hx] file and/or the function which implements the command.
 
=== Libvirt ===
 
Libvirt already has QMP support, but it's currently disable. This test procedure explains how to enable it and put libvirt to run on top of QMP.
 
1. Install [http://lloyd.github.com/yajl yajl-devel] (If you're running Fedora 12 or above just do 'yum install yajl-devel')
 
2. From a fresh checkout of [http://libvirt.org/git/?p=libvirt.git;a=summary 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
(QEMU) device_add driver=e1000 id=net1


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


6. As root you can use the newly built virsh too
* Luiz's QMP talk on KVM Forum 2010 can be found [http://www.linux-kvm.org/images/1/17/2010-forum-qmp-status-talk.pp.pdf here]
* Old QMP page can be accessed [http://www.linux-kvm.org/index.php?title=MonitorProtocol&oldid=3100 here]


cd $HOME/your/git/checkout/of/libvirt/src
[[Category:User documentation]]
./virsh <BLAH>

Latest revision as of 12:35, 22 March 2022

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 QMP intro file for more information.

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 capabilities negotiation mode and enter command mode, the qmp_capabilities command must be issued:

 S: {
        "QMP": {
            "version": {
                "qemu": {
                    "micro": 0,
                    "minor": 6,
                    "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

QMP being a core part of QEMU, all discussions happen on the qemu-devel mailing list.

Trying it

By hand

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

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

2. Run telnet

$ telnet localhost 4444

3. You should see QMP's greeting banner

{"QMP": {"version": {"qemu": {"micro": 0, "minor": 6, "major": 1}, "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" }

There's an optimization to this procedure in case you plan to use it often:

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"
  pretty = "on"

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 scripts/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,wait=off

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

Historic information

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