Archipelago » qemu

           QEMU Monitor Protocol Specification - Version 0.1

1. Introduction

===============

This document specifies the QEMU Monitor Protocol (QMP), a JSON-based protocol

which is available for applications to control QEMU at the machine-level.

To enable QMP support, QEMU has to be run in "control mode". This is done by

starting QEMU with the appropriate command-line options. Please, refer to the

QEMU manual page for more information.

2. Protocol Specification

=========================

This section details the protocol format. For the purpose of this document

"Client" is any application which is communicating with QEMU in control mode,

and "Server" is QEMU itself.

JSON data structures, when mentioned in this document, are always in the

following format:

    json-DATA-STRUCTURE-NAME

Where DATA-STRUCTURE-NAME is any valid JSON data structure, as defined by

the JSON standard:

http://www.ietf.org/rfc/rfc4627.txt

For convenience, json-object members and json-array elements mentioned in

this document will be in a certain order. However, in real protocol usage

they can be in ANY order, thus no particular order should be assumed.

2.1 General Definitions

-----------------------

2.1.1 All interactions transmitted by the Server are json-objects, always

      terminating with CRLF

2.1.2 All json-objects members are mandatory when not specified otherwise

2.2 Server Greeting

-------------------

Right when connected the Server will issue a greeting message, which signals

that the connection has been successfully established and that the Server is

ready for capabilities negotiation (for more information refer to section

'4. Capabilities Negotiation').

The format is:

{ "QMP": { "version": json-object, "capabilities": json-array } }

 Where,

- The "version" member contains the Server's version information (the format

  is the same of the 'query-version' command)

- The "capabilities" member specify the availability of features beyond the

  baseline specification

2.3 Issuing Commands

--------------------

The format for command execution is:

{ "execute": json-string, "arguments": json-object, "id": json-value }

 Where,

- The "execute" member identifies the command to be executed by the Server

- The "arguments" member is used to pass any arguments required for the

  execution of the command, it is optional when no arguments are required

- The "id" member is a transaction identification associated with the

  command execution, it is optional and will be part of the response if

  provided

2.4 Commands Responses

----------------------

There are two possible responses which the Server will issue as the result

of a command execution: success or error.

2.4.1 success

-------------

The success response is issued when the command execution has finished

without errors.

The format is:

{ "return": json-object, "id": json-value }

 Where,

- The "return" member contains the command returned data, which is defined

  in a per-command basis or an empty json-object if the command does not

  return data

- The "id" member contains the transaction identification associated

  with the command execution (if issued by the Client)

2.4.2 error

-----------

The error response is issued when the command execution could not be

completed because of an error condition.

The format is:

{ "error": { "class": json-string, "data": json-object, "desc": json-string },

  "id": json-value }

 Where,

- The "class" member contains the error class name (eg. "ServiceUnavailable")

- The "data" member contains specific error data and is defined in a

  per-command basis, it will be an empty json-object if the error has no data

- The "desc" member is a human-readable error message. Clients should

  not attempt to parse this message.

- The "id" member contains the transaction identification associated with

  the command execution (if issued by the Client)

NOTE: Some errors can occur before the Server is able to read the "id" member,

in these cases the "id" member will not be part of the error response, even

if provided by the client.

2.5 Asynchronous events

-----------------------

As a result of state changes, the Server may send messages unilaterally

to the Client at any time. They are called 'asynchronous events'.

The format is:

{ "event": json-string, "data": json-object,

  "timestamp": { "seconds": json-number, "microseconds": json-number } }

 Where,

- The "event" member contains the event's name

- The "data" member contains event specific data, which is defined in a

  per-event basis, it is optional

- The "timestamp" member contains the exact time of when the event occurred

  in the Server. It is a fixed json-object with time in seconds and

  microseconds

For a listing of supported asynchronous events, please, refer to the

qmp-events.txt file.

3. QMP Examples

===============

This section provides some examples of real QMP usage, in all of them

'C' stands for 'Client' and 'S' stands for 'Server'.

3.1 Server greeting

-------------------

S: {"QMP": {"version": {"qemu": "0.12.50", "package": ""}, "capabilities": []}}

3.2 Simple 'stop' execution

---------------------------

C: { "execute": "stop" }

S: {"return": {}}

3.3 KVM information

-------------------

C: { "execute": "query-kvm", "id": "example" }

S: {"return": {"enabled": true, "present": true}, "id": "example"}

3.4 Parsing error

------------------

C: { "execute": }

S: {"error": {"class": "JSONParsing", "desc": "Invalid JSON syntax", "data":

{}}}

3.5 Powerdown event

-------------------

S: {"timestamp": {"seconds": 1258551470, "microseconds": 802384}, "event":

"POWERDOWN"}

4. Capabilities Negotiation

----------------------------

When a Client successfully establishes a connection, the Server is in

Capabilities Negotiation mode.

In this mode only the 'qmp_capabilities' command is allowed to run, all

other commands will return the CommandNotFound error. Asynchronous messages

are not delivered either.

Clients should use the 'qmp_capabilities' command to enable capabilities

advertised in the Server's greeting (section '2.2 Server Greeting') they

support.

When the 'qmp_capabilities' command is issued, and if it does not return an

error, the Server enters in Command mode where capabilities changes take

effect, all commands (except 'qmp_capabilities') are allowed and asynchronous

messages are delivered.

5 Compatibility Considerations

------------------------------

All protocol changes or new features which modify the protocol format in an

incompatible way are disabled by default and will be advertised by the

capabilities array (section '2.2 Server Greeting'). Thus, Clients can check

that array and enable the capabilities they support.

Additionally, Clients must not assume any particular:

- Size of json-objects or length of json-arrays

- Order of json-object members or json-array elements

- Amount of errors generated by a command, that is, new errors can be added

  to any existing command in newer versions of the Server

6. Downstream extension of QMP

------------------------------

We recommend that downstream consumers of QEMU do *not* modify QMP.

Management tools should be able to support both upstream and downstream

versions of QMP without special logic, and downstream extensions are

inherently at odds with that.

However, we recognize that it is sometimes impossible for downstreams to

avoid modifying QMP.  Both upstream and downstream need to take care to

preserve long-term compatibility and interoperability.

To help with that, QMP reserves JSON object member names beginning with

'__' (double underscore) for downstream use ("downstream names").  This

means upstream will never use any downstream names for its commands,

arguments, errors, asynchronous events, and so forth.

Any new names downstream wishes to add must begin with '__'.  To

ensure compatibility with other downstreams, it is strongly

recommended that you prefix your downstram names with '__RFQDN_' where

RFQDN is a valid, reverse fully qualified domain name which you

control.  For example, a qemu-kvm specific monitor command would be:

    (qemu) __org.linux-kvm_enable_irqchip

Downstream must not change the server greeting (section 2.2) other than

to offer additional capabilities.  But see below for why even that is

discouraged.

Section '5 Compatibility Considerations' applies to downstream as well

as to upstream, obviously.  It follows that downstream must behave

exactly like upstream for any input not containing members with

downstream names ("downstream members"), except it may add members

with downstream names to its output.

Thus, a client should not be able to distinguish downstream from

upstream as long as it doesn't send input with downstream members, and

properly ignores any downstream members in the output it receives.

Advice on downstream modifications:

1. Introducing new commands is okay.  If you want to extend an existing

   command, consider introducing a new one with the new behaviour

   instead.

2. Introducing new asynchronous messages is okay.  If you want to extend

   an existing message, consider adding a new one instead.

3. Introducing new errors for use in new commands is okay.  Adding new

   errors to existing commands counts as extension, so 1. applies.

4. New capabilities are strongly discouraged.  Capabilities are for

   evolving the basic protocol, and multiple diverging basic protocol

   dialects are most undesirable.