qemu

qmp-spec.txt (15078B)

---

                       QEMU Machine Protocol Specification
 
 0. About This Document
 ======================
 
 Copyright (C) 2009-2016 Red Hat, Inc.
 
 This work is licensed under the terms of the GNU GPL, version 2 or
 later. See the COPYING file in the top-level directory.
 
 1. Introduction
 ===============
 
 This document specifies the QEMU Machine Protocol (QMP), a JSON-based
 protocol which is available for applications to operate QEMU at the
 machine-level.  It is also in use by the QEMU Guest Agent (QGA), which
 is available for host applications to interact with the guest
 operating system.
 
 2. Protocol Specification
 =========================
 
 This section details the protocol format. For the purpose of this
 document, "Server" is either QEMU or the QEMU Guest Agent, and
 "Client" is any application communicating with it via QMP.
 
 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/rfc8259.txt
 
 The server expects its input to be encoded in UTF-8, and sends its
 output encoded in ASCII.
 
 For convenience, json-object members 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. On the other
 hand, use of json-array elements presumes that preserving order is
 important unless specifically documented otherwise.  Repeating a key
 within a json-object gives unpredictable results.
 
 Also for convenience, the server will accept an extension of
 'single-quoted' strings in place of the usual "double-quoted"
 json-string, and both input forms of strings understand an additional
 escape sequence of "\'" for a single quote. The server will only use
 double quoting on output.
 
 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 greeting message 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; the order of elements in this array has no
   particular significance.
 
 2.2.1 Capabilities
 ------------------
 
 Currently supported capabilities are:
 
 - "oob": the QMP server supports "out-of-band" (OOB) command
   execution, as described in section "2.3.1 Out-of-band execution".
 
 2.3 Issuing Commands
 --------------------
 
 The format for command execution is:
 
 { "execute": json-string, "arguments": json-object, "id": json-value }
 
 or
 
 { "exec-oob": json-string, "arguments": json-object, "id": json-value }
 
  Where,
 
 - The "execute" or "exec-oob" member identifies the command to be
   executed by the server.  The latter requests out-of-band execution.
 - The "arguments" member is used to pass any arguments required for the
   execution of the command, it is optional when no arguments are
   required. Each command documents what contents will be considered
   valid when handling the json-argument
 - The "id" member is a transaction identification associated with the
   command execution, it is optional and will be part of the response
   if provided.  The "id" member can be any json-value.  A json-number
   incremented for each successive command works fine.
 
 The actual commands are documented in the QEMU QMP reference manual
 docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}.
 
 2.3.1 Out-of-band execution
 ---------------------------
 
 The server normally reads, executes and responds to one command after
 the other.  The client therefore receives command responses in issue
 order.
 
 With out-of-band execution enabled via capability negotiation (section
 4.), the server reads and queues commands as they arrive.  It executes
 commands from the queue one after the other.  Commands executed
 out-of-band jump the queue: the command get executed right away,
 possibly overtaking prior in-band commands.  The client may therefore
 receive such a command's response before responses from prior in-band
 commands.
 
 To be able to match responses back to their commands, the client needs
 to pass "id" with out-of-band commands.  Passing it with all commands
 is recommended for clients that accept capability "oob".
 
 If the client sends in-band commands faster than the server can
 execute them, the server will stop reading requests until the request
 queue length is reduced to an acceptable range.
 
 To ensure commands to be executed out-of-band get read and executed,
 the client should have at most eight in-band commands in flight.
 
 Only a few commands support out-of-band execution.  The ones that do
 have "allow-oob": true in output of query-qmp-schema.
 
 2.4 Commands Responses
 ----------------------
 
 There are two possible responses which the Server will issue as the result
 of a command execution: success or error.
 
 As long as the commands were issued with a proper "id" field, then the
 same "id" field will be attached in the corresponding response message
 so that requests and responses can match.  Clients should drop all the
 responses that have an unknown "id" field.
 
 2.4.1 success
 -------------
 
 The format of a success response is:
 
 { "return": json-value, "id": json-value }
 
  Where,
 
 - The "return" member contains the data returned by the command, which
   is defined on a per-command basis (usually a json-object or
   json-array of json-objects, but sometimes a json-number, json-string,
   or json-array of json-strings); it is 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 format of an error response is:
 
 { "error": { "class": json-string, "desc": json-string }, "id": json-value }
 
  Where,
 
 - The "class" member contains the error class name (eg. "GenericError")
 - 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, when not in the middle of any other
 response. They are called "asynchronous events".
 
 The format of asynchronous events 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 relative to the Unix Epoch (1 Jan 1970); if
   there is a failure to retrieve host time, both members of the
   timestamp will be set to -1.
 
 The actual asynchronous events are documented in the QEMU QMP
 reference manual docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}.
 
 Some events are rate-limited to at most one per second.  If additional
 "similar" events arrive within one second, all but the last one are
 dropped, and the last one is delayed.  "Similar" normally means same
 event type.
 
 2.6 Forcing the JSON parser into known-good state
 -------------------------------------------------
 
 Incomplete or invalid input can leave the server's JSON parser in a
 state where it can't parse additional commands.  To get it back into
 known-good state, the client should provoke a lexical error.
 
 The cleanest way to do that is sending an ASCII control character
 other than '\t' (horizontal tab), '\r' (carriage return), or '\n' (new
 line).
 
 Sadly, older versions of QEMU can fail to flag this as an error.  If a
 client needs to deal with them, it should send a 0xFF byte.
 
 2.7 QGA Synchronization
 -----------------------
 
 When a client connects to QGA over a transport lacking proper
 connection semantics such as virtio-serial, QGA may have read partial
 input from a previous client.  The client needs to force QGA's parser
 into known-good state using the previous section's technique.
 Moreover, the client may receive output a previous client didn't read.
 To help with skipping that output, QGA provides the
 'guest-sync-delimited' command.  Refer to its documentation for
 details.
 
 
 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": {"micro": 0, "minor": 0, "major": 3},
      "package": "v3.0.0"}, "capabilities": ["oob"] } }
 
 3.2 Capabilities negotiation
 ----------------------------
 
 C: { "execute": "qmp_capabilities", "arguments": { "enable": ["oob"] } }
 S: { "return": {}}
 
 3.3 Simple 'stop' execution
 ---------------------------
 
 C: { "execute": "stop" }
 S: { "return": {} }
 
 3.4 KVM information
 -------------------
 
 C: { "execute": "query-kvm", "id": "example" }
 S: { "return": { "enabled": true, "present": true }, "id": "example"}
 
 3.5 Parsing error
 ------------------
 
 C: { "execute": }
 S: { "error": { "class": "GenericError", "desc": "Invalid JSON syntax" } }
 
 3.6 Powerdown event
 -------------------
 
 S: { "timestamp": { "seconds": 1258551470, "microseconds": 802384 },
     "event": "POWERDOWN" }
 
 3.7 Out-of-band execution
 -------------------------
 
 C: { "exec-oob": "migrate-pause", "id": 42 }
 S: { "id": 42,
      "error": { "class": "GenericError",
       "desc": "migrate-pause is currently only supported during postcopy-active state" } }
 
 
 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.
 
 The QMP Server performs a type check on the arguments to a command.  It
 generates an error if a value does not have the expected type for its
 key, or if it does not understand a key that the Client included.  The
 strictness of the Server catches wrong assumptions of Clients about
 the Server's schema.  Clients can assume that, when such validation
 errors occur, they will be reported before the command generated any
 side effect.
 
 However, Clients must not assume any particular:
 
 - Length of json-arrays
 - Size of json-objects; in particular, future versions of QEMU may add
   new keys and Clients should be able to ignore them.
 - 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
 
 Any command or member name beginning with "x-" is deemed experimental,
 and may be withdrawn or changed in an incompatible manner in a future
 release.
 
 Of course, the Server does guarantee to send valid JSON.  But apart from
 this, a Client should be "conservative in what they send, and liberal in
 what they accept".
 
 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 downstream 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.