docs/qmp-commands.txt

   1                         QMP Supported Commands
   2                         ----------------------
   3
   4 This document describes all commands currently supported by QMP.
   5
   6 Most of the time their usage is exactly the same as in the user Monitor, this
   7 means that any other document which also describe commands (the manpage,
   8 QEMU's manual, etc) can and should be consulted.
   9
  10 QMP has two types of commands: regular and query commands. Regular commands
  11 usually change the Virtual Machine's state someway, while query commands just
  12 return information. The sections below are divided accordingly.
  13
  14 It's important to observe that all communication examples are formatted in
  15 a reader-friendly way, so that they're easier to understand. However, in real
  16 protocol usage, they're emitted as a single line.
  17
  18 Also, the following notation is used to denote data flow:
  19
  20 -> data issued by the Client
  21 <- Server data response
  22
  23 Please, refer to the QMP specification (docs/qmp-spec.txt) for detailed
  24 information on the Server command and response formats.
  25
  26 NOTE: This document is temporary and will be replaced soon.
  27
  28 1. Stability Considerations
  29 ===========================
  30
  31 The current QMP command set (described in this file) may be useful for a
  32 number of use cases, however it's limited and several commands have bad
  33 defined semantics, specially with regard to command completion.
  34
  35 These problems are going to be solved incrementally in the next QEMU releases
  36 and we're going to establish a deprecation policy for badly defined commands.
  37
  38 If you're planning to adopt QMP, please observe the following:
  39
  40     1. The deprecation policy will take effect and be documented soon, please
  41        check the documentation of each used command as soon as a new release of
  42        QEMU is available
  43
  44     2. DO NOT rely on anything which is not explicit documented
  45
  46     3. Errors, in special, are not documented. Applications should NOT check
  47        for specific errors classes or data (it's strongly recommended to only
  48        check for the "error" key)
  49
  50 2. Regular Commands
  51 ===================
  52
  53 Server's responses in the examples below are always a success response, please
  54 refer to the QMP specification for more details on error responses.
  55
  56 eject
  57 -----
  58
  59 Eject a removable medium.
  60
  61 Arguments:
  62
  63 - "force": force ejection (json-bool, optional)
  64 - "device": block device name (deprecated, use @id instead)
  65             (json-string, optional)
  66 - "id": the name or QOM path of the guest device (json-string, optional)
  67
  68 Example:
  69
  70 -> { "execute": "eject", "arguments": { "id": "ide0-1-0" } }
  71 <- { "return": {} }
  72
  73 Note: The "force" argument defaults to false.
  74
  75 device_add
  76 ----------
  77
  78 Add a device.
  79
  80 Arguments:
  81
  82 - "driver": the name of the new device's driver (json-string)
  83 - "bus": the device's parent bus (device tree path, json-string, optional)
  84 - "id": the device's ID, must be unique (json-string)
  85 - device properties
  86
  87 Example:
  88
  89 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
  90 <- { "return": {} }
  91
  92 Notes:
  93
  94 (1) For detailed information about this command, please refer to the
  95     'docs/qdev-device-use.txt' file.
  96
  97 (2) It's possible to list device properties by running QEMU with the
  98     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
  99
 100 cpu
 101 ---
 102
 103 Set the default CPU.
 104
 105 Arguments:
 106
 107 - "index": the CPU's index (json-int)
 108
 109 Example:
 110
 111 -> { "execute": "cpu", "arguments": { "index": 0 } }
 112 <- { "return": {} }
 113
 114 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 115
 116 xen-load-devices-state
 117 ----------------------
 118
 119 Load the state of all devices from file. The RAM and the block devices
 120 of the VM are not loaded by this command.
 121
 122 Arguments:
 123
 124 - "filename": the file to load the state of the devices from as binary
 125 data. See xen-save-devices-state.txt for a description of the binary
 126 format.
 127
 128 Example:
 129
 130 -> { "execute": "xen-load-devices-state",
 131      "arguments": { "filename": "/tmp/resume" } }
 132 <- { "return": {} }
 133
 134 migrate-set-cache-size
 135 ----------------------
 136
 137 Set cache size to be used by XBZRLE migration, the cache size will be rounded
 138 down to the nearest power of 2
 139
 140 Arguments:
 141
 142 - "value": cache size in bytes (json-int)
 143
 144 Example:
 145
 146 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 147 <- { "return": {} }
 148
 149 x-colo-lost-heartbeat
 150 --------------------
 151
 152 Tell COLO that heartbeat is lost, a failover or takeover is needed.
 153
 154 Example:
 155
 156 -> { "execute": "x-colo-lost-heartbeat" }
 157 <- { "return": {} }
 158
 159 query-dump
 160 ----------
 161
 162 Query background dump status.
 163
 164 Arguments: None.
 165
 166 Example:
 167
 168 -> { "execute": "query-dump" }
 169 <- { "return": { "status": "active", "completed": 1024000,
 170                  "total": 2048000 } }
 171
 172 blockdev-mirror
 173 ------------
 174
 175 Start mirroring a block device's writes to another block device. target
 176 specifies the target of mirror operation.
 177
 178 Arguments:
 179
 180 - "job-id": Identifier for the newly-created block job. If omitted,
 181             the device name will be used. (json-string, optional)
 182 - "device": The device name or node-name of a root node whose writes should be
 183             mirrored (json-string)
 184 - "target": device name to mirror to (json-string)
 185 - "replaces": the block driver node name to replace when finished
 186               (json-string, optional)
 187 - "speed": maximum speed of the streaming job, in bytes per second
 188   (json-int)
 189 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
 190 - "buf_size": maximum amount of data in flight from source to target, in bytes
 191   (json-int, default 10M)
 192 - "sync": what parts of the disk image should be copied to the destination;
 193   possibilities include "full" for all the disk, "top" for only the sectors
 194   allocated in the topmost image, or "none" to only replicate new I/O
 195   (MirrorSyncMode).
 196 - "on-source-error": the action to take on an error on the source
 197   (BlockdevOnError, default 'report')
 198 - "on-target-error": the action to take on an error on the target
 199   (BlockdevOnError, default 'report')
 200
 201 The default value of the granularity is the image cluster size clamped
 202 between 4096 and 65536, if the image format defines one.  If the format
 203 does not define a cluster size, the default value of the granularity
 204 is 65536.
 205
 206 Example:
 207
 208 -> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
 209                                                   "target": "target0",
 210                                                   "sync": "full" } }
 211 <- { "return": {} }
 212
 213 qmp_capabilities
 214 ----------------
 215
 216 Enable QMP capabilities.
 217
 218 Arguments: None.
 219
 220 Example:
 221
 222 -> { "execute": "qmp_capabilities" }
 223 <- { "return": {} }
 224
 225 Note: This command must be issued before issuing any other command.
 226
 227 3. Query Commands
 228 =================
 229
 230
 231 query-version
 232 -------------
 233
 234 Show QEMU version.
 235
 236 Return a json-object with the following information:
 237
 238 - "qemu": A json-object containing three integer values:
 239     - "major": QEMU's major version (json-int)
 240     - "minor": QEMU's minor version (json-int)
 241     - "micro": QEMU's micro version (json-int)
 242 - "package": package's version (json-string)
 243
 244 Example:
 245
 246 -> { "execute": "query-version" }
 247 <- {
 248       "return":{
 249          "qemu":{
 250             "major":0,
 251             "minor":11,
 252             "micro":5
 253          },
 254          "package":""
 255       }
 256    }
 257
 258 query-commands
 259 --------------
 260
 261 List QMP available commands.
 262
 263 Each command is represented by a json-object, the returned value is a json-array
 264 of all commands.
 265
 266 Each json-object contain:
 267
 268 - "name": command's name (json-string)
 269
 270 Example:
 271
 272 -> { "execute": "query-commands" }
 273 <- {
 274       "return":[
 275          {
 276             "name":"query-balloon"
 277          },
 278          {
 279             "name":"system_powerdown"
 280          }
 281       ]
 282    }
 283
 284 Note: This example has been shortened as the real response is too long.
 285
 286 query-qmp-schema
 287 ----------------
 288
 289 Return the QMP wire schema.  The returned value is a json-array of
 290 named schema entities.  Entities are commands, events and various
 291 types.  See docs/qapi-code-gen.txt for information on their structure
 292 and intended use.
 293
 294 x-blockdev-change
 295 -----------------
 296
 297 Dynamically reconfigure the block driver state graph. It can be used
 298 to add, remove, insert or replace a graph node. Currently only the
 299 Quorum driver implements this feature to add or remove its child. This
 300 is useful to fix a broken quorum child.
 301
 302 If @node is specified, it will be inserted under @parent. @child
 303 may not be specified in this case. If both @parent and @child are
 304 specified but @node is not, @child will be detached from @parent.
 305
 306 Arguments:
 307 - "parent": the id or name of the parent node (json-string)
 308 - "child": the name of a child under the given parent node (json-string, optional)
 309 - "node": the name of the node that will be added (json-string, optional)
 310
 311 Note: this command is experimental, and not a stable API. It doesn't
 312 support all kinds of operations, all kinds of children, nor all block
 313 drivers.
 314
 315 Warning: The data in a new quorum child MUST be consistent with that of
 316 the rest of the array.
 317
 318 Example:
 319
 320 Add a new node to a quorum
 321 -> { "execute": "blockdev-add",
 322      "arguments": { "driver": "raw",
 323                     "node-name": "new_node",
 324                     "file": { "driver": "file",
 325                               "filename": "test.raw" } } }
 326 <- { "return": {} }
 327 -> { "execute": "x-blockdev-change",
 328      "arguments": { "parent": "disk1",
 329                     "node": "new_node" } }
 330 <- { "return": {} }
 331
 332 Delete a quorum's node
 333 -> { "execute": "x-blockdev-change",
 334      "arguments": { "parent": "disk1",
 335                     "child": "children.1" } }
 336 <- { "return": {} }
 337
 338 trace-event-get-state
 339 ---------------------
 340
 341 Query the state of events.
 342
 343 Arguments:
 344
 345 - "name": Event name pattern (json-string).
 346 - "vcpu": The vCPU to query, any vCPU by default (json-int, optional).
 347
 348 An event is returned if:
 349 - its name matches the "name" pattern, and
 350 - if "vcpu" is given, the event has the "vcpu" property.
 351
 352 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
 353 returning their state on the specified vCPU. Special case: if "name" is an exact
 354 match, "vcpu" is given and the event does not have the "vcpu" property, an error
 355 is returned.
 356
 357 Example:
 358
 359 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
 360 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
 361
 362 trace-event-set-state
 363 ---------------------
 364
 365 Set the state of events.
 366
 367 Arguments:
 368
 369 - "name": Event name pattern (json-string).
 370 - "enable": Whether to enable or disable the event (json-bool).
 371 - "ignore-unavailable": Whether to ignore errors for events that cannot be
 372   changed (json-bool, optional).
 373 - "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional).
 374
 375 An event's state is modified if:
 376 - its name matches the "name" pattern, and
 377 - if "vcpu" is given, the event has the "vcpu" property.
 378
 379 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
 380 setting their state on the specified vCPU. Special case: if "name" is an exact
 381 match, "vcpu" is given and the event does not have the "vcpu" property, an error
 382 is returned.
 383
 384 Example:
 385
 386 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
 387 <- { "return": {} }
 388
 389 Show rocker switch
 390 ------------------
 391
 392 Arguments:
 393
 394 - "name": switch name
 395
 396 Example:
 397
 398 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
 399 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
 400
 401 Show rocker switch ports
 402 ------------------------
 403
 404 Arguments:
 405
 406 - "name": switch name
 407
 408 Example:
 409
 410 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
 411 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
 412                   "autoneg": "off", "link-up": true, "speed": 10000},
 413                  {"duplex": "full", "enabled": true, "name": "sw1.2",
 414                   "autoneg": "off", "link-up": true, "speed": 10000}
 415    ]}
 416
 417 Show rocker switch OF-DPA flow tables
 418 -------------------------------------
 419
 420 Arguments:
 421
 422 - "name": switch name
 423 - "tbl-id": (optional) flow table ID
 424
 425 Example:
 426
 427 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
 428 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
 429                   "hits": 138,
 430                   "cookie": 0,
 431                   "action": {"goto-tbl": 10},
 432                   "mask": {"in-pport": 4294901760}
 433                  },
 434                  {...more...},
 435    ]}
 436
 437 Show rocker OF-DPA group tables
 438 -------------------------------
 439
 440 Arguments:
 441
 442 - "name": switch name
 443 - "type": (optional) group type
 444
 445 Example:
 446
 447 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
 448 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
 449                   "pop-vlan": 1, "id": 251723778},
 450                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
 451                   "pop-vlan": 1, "id": 251723776},
 452                  {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
 453                   "pop-vlan": 1, "id": 251658241},
 454                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
 455                   "pop-vlan": 1, "id": 251658240}
 456    ]}
 457
 458 query-gic-capabilities
 459 ---------------
 460
 461 Return a list of GICCapability objects, describing supported GIC
 462 (Generic Interrupt Controller) versions.
 463
 464 Arguments: None
 465
 466 Example:
 467
 468 -> { "execute": "query-gic-capabilities" }
 469 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
 470                 { "version": 3, "emulated": false, "kernel": true } ] }
 471
 472 Show existing/possible CPUs
 473 ---------------------------
 474
 475 Arguments: None.
 476
 477 Example for pseries machine type started with
 478 -smp 2,cores=2,maxcpus=4 -cpu POWER8:
 479
 480 -> { "execute": "query-hotpluggable-cpus" }
 481 <- {"return": [
 482      { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
 483        "vcpus-count": 1 },
 484      { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
 485        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
 486    ]}'
 487
 488 Example for pc machine type started with
 489 -smp 1,maxcpus=2:
 490     -> { "execute": "query-hotpluggable-cpus" }
 491     <- {"return": [
 492          {
 493             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
 494             "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
 495          },
 496          {
 497             "qom-path": "/machine/unattached/device[0]",
 498             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
 499             "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
 500          }
 501        ]}