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 block_resize
 173 ------------
 174
 175 Resize a block image while a guest is running.
 176
 177 Arguments:
 178
 179 - "device": the device's ID, must be unique (json-string)
 180 - "node-name": the node name in the block driver state graph (json-string)
 181 - "size": new size
 182
 183 Example:
 184
 185 -> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
 186 <- { "return": {} }
 187
 188 block-stream
 189 ------------
 190
 191 Copy data from a backing file into a block device.
 192
 193 Arguments:
 194
 195 - "job-id": Identifier for the newly-created block job. If omitted,
 196             the device name will be used. (json-string, optional)
 197 - "device": The device name or node-name of a root node (json-string)
 198 - "base": The file name of the backing image above which copying starts.
 199           It cannot be set if 'base-node' is also set (json-string, optional)
 200 - "base-node": the node name of the backing image above which copying starts.
 201                It cannot be set if 'base' is also set.
 202                (json-string, optional) (Since 2.8)
 203 - "backing-file": The backing file string to write into the active layer. This
 204                   filename is not validated.
 205
 206                   If a pathname string is such that it cannot be resolved by
 207                   QEMU, that means that subsequent QMP or HMP commands must use
 208                   node-names for the image in question, as filename lookup
 209                   methods will fail.
 210
 211                   If not specified, QEMU will automatically determine the
 212                   backing file string to use, or error out if there is no
 213                   obvious choice.  Care should be taken when specifying the
 214                   string, to specify a valid filename or protocol.
 215                   (json-string, optional) (Since 2.1)
 216 - "speed":  the maximum speed, in bytes per second (json-int, optional)
 217 - "on-error": the action to take on an error (default 'report').  'stop' and
 218               'enospc' can only be used if the block device supports io-status.
 219               (json-string, optional) (Since 2.1)
 220
 221 Example:
 222
 223 -> { "execute": "block-stream", "arguments": { "device": "virtio0",
 224                                                "base": "/tmp/master.qcow2" } }
 225 <- { "return": {} }
 226
 227 block-commit
 228 ------------
 229
 230 Live commit of data from overlay image nodes into backing nodes - i.e., writes
 231 data between 'top' and 'base' into 'base'.
 232
 233 Arguments:
 234
 235 - "job-id": Identifier for the newly-created block job. If omitted,
 236             the device name will be used. (json-string, optional)
 237 - "device": The device name or node-name of a root node (json-string)
 238 - "base": The file name of the backing image to write data into.
 239           If not specified, this is the deepest backing image
 240           (json-string, optional)
 241 - "top":  The file name of the backing image within the image chain,
 242           which contains the topmost data to be committed down. If
 243           not specified, this is the active layer. (json-string, optional)
 244
 245 - backing-file:     The backing file string to write into the overlay
 246                     image of 'top'.  If 'top' is the active layer,
 247                     specifying a backing file string is an error. This
 248                     filename is not validated.
 249
 250                     If a pathname string is such that it cannot be
 251                     resolved by QEMU, that means that subsequent QMP or
 252                     HMP commands must use node-names for the image in
 253                     question, as filename lookup methods will fail.
 254
 255                     If not specified, QEMU will automatically determine
 256                     the backing file string to use, or error out if
 257                     there is no obvious choice. Care should be taken
 258                     when specifying the string, to specify a valid
 259                     filename or protocol.
 260                     (json-string, optional) (Since 2.1)
 261
 262           If top == base, that is an error.
 263           If top == active, the job will not be completed by itself,
 264           user needs to complete the job with the block-job-complete
 265           command after getting the ready event. (Since 2.0)
 266
 267           If the base image is smaller than top, then the base image
 268           will be resized to be the same size as top.  If top is
 269           smaller than the base image, the base will not be
 270           truncated.  If you want the base image size to match the
 271           size of the smaller top, you can safely truncate it
 272           yourself once the commit operation successfully completes.
 273           (json-string)
 274 - "speed":  the maximum speed, in bytes per second (json-int, optional)
 275
 276
 277 Example:
 278
 279 -> { "execute": "block-commit", "arguments": { "device": "virtio0",
 280                                               "top": "/tmp/snap1.qcow2" } }
 281 <- { "return": {} }
 282
 283 drive-backup
 284 ------------
 285
 286 Start a point-in-time copy of a block device to a new destination.  The
 287 status of ongoing drive-backup operations can be checked with
 288 query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
 289 The operation can be stopped before it has completed using the
 290 block-job-cancel command.
 291
 292 Arguments:
 293
 294 - "job-id": Identifier for the newly-created block job. If omitted,
 295             the device name will be used. (json-string, optional)
 296 - "device": the device name or node-name of a root node which should be copied.
 297             (json-string)
 298 - "target": the target of the new image. If the file exists, or if it is a
 299             device, the existing file/device will be used as the new
 300             destination.  If it does not exist, a new file will be created.
 301             (json-string)
 302 - "format": the format of the new destination, default is to probe if 'mode' is
 303             'existing', else the format of the source
 304             (json-string, optional)
 305 - "sync": what parts of the disk image should be copied to the destination;
 306   possibilities include "full" for all the disk, "top" for only the sectors
 307   allocated in the topmost image, "incremental" for only the dirty sectors in
 308   the bitmap, or "none" to only replicate new I/O (MirrorSyncMode).
 309 - "bitmap": dirty bitmap name for sync==incremental. Must be present if sync
 310             is "incremental", must NOT be present otherwise.
 311 - "mode": whether and how QEMU should create a new image
 312           (NewImageMode, optional, default 'absolute-paths')
 313 - "speed": the maximum speed, in bytes per second (json-int, optional)
 314 - "compress": true to compress data, if the target format supports it.
 315               (json-bool, optional, default false)
 316 - "on-source-error": the action to take on an error on the source, default
 317                      'report'.  'stop' and 'enospc' can only be used
 318                      if the block device supports io-status.
 319                      (BlockdevOnError, optional)
 320 - "on-target-error": the action to take on an error on the target, default
 321                      'report' (no limitations, since this applies to
 322                      a different block device than device).
 323                      (BlockdevOnError, optional)
 324
 325 Example:
 326 -> { "execute": "drive-backup", "arguments": { "device": "drive0",
 327                                                "sync": "full",
 328                                                "target": "backup.img" } }
 329 <- { "return": {} }
 330
 331 blockdev-backup
 332 ---------------
 333
 334 The device version of drive-backup: this command takes an existing named device
 335 as backup target.
 336
 337 Arguments:
 338
 339 - "job-id": Identifier for the newly-created block job. If omitted,
 340             the device name will be used. (json-string, optional)
 341 - "device": the device name or node-name of a root node which should be copied.
 342             (json-string)
 343 - "target": the name of the backup target device. (json-string)
 344 - "sync": what parts of the disk image should be copied to the destination;
 345           possibilities include "full" for all the disk, "top" for only the
 346           sectors allocated in the topmost image, or "none" to only replicate
 347           new I/O (MirrorSyncMode).
 348 - "speed": the maximum speed, in bytes per second (json-int, optional)
 349 - "compress": true to compress data, if the target format supports it.
 350               (json-bool, optional, default false)
 351 - "on-source-error": the action to take on an error on the source, default
 352                      'report'.  'stop' and 'enospc' can only be used
 353                      if the block device supports io-status.
 354                      (BlockdevOnError, optional)
 355 - "on-target-error": the action to take on an error on the target, default
 356                      'report' (no limitations, since this applies to
 357                      a different block device than device).
 358                      (BlockdevOnError, optional)
 359
 360 Example:
 361 -> { "execute": "blockdev-backup", "arguments": { "device": "src-id",
 362                                                   "sync": "full",
 363                                                   "target": "tgt-id" } }
 364 <- { "return": {} }
 365
 366 block-dirty-bitmap-add
 367 ----------------------
 368 Since 2.4
 369
 370 Create a dirty bitmap with a name on the device, and start tracking the writes.
 371
 372 Arguments:
 373
 374 - "node": device/node on which to create dirty bitmap (json-string)
 375 - "name": name of the new dirty bitmap (json-string)
 376 - "granularity": granularity to track writes with (int, optional)
 377
 378 Example:
 379
 380 -> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0",
 381                                                    "name": "bitmap0" } }
 382 <- { "return": {} }
 383
 384 block-dirty-bitmap-remove
 385 -------------------------
 386 Since 2.4
 387
 388 Stop write tracking and remove the dirty bitmap that was created with
 389 block-dirty-bitmap-add.
 390
 391 Arguments:
 392
 393 - "node": device/node on which to remove dirty bitmap (json-string)
 394 - "name": name of the dirty bitmap to remove (json-string)
 395
 396 Example:
 397
 398 -> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0",
 399                                                       "name": "bitmap0" } }
 400 <- { "return": {} }
 401
 402 block-dirty-bitmap-clear
 403 ------------------------
 404 Since 2.4
 405
 406 Reset the dirty bitmap associated with a node so that an incremental backup
 407 from this point in time forward will only backup clusters modified after this
 408 clear operation.
 409
 410 Arguments:
 411
 412 - "node": device/node on which to remove dirty bitmap (json-string)
 413 - "name": name of the dirty bitmap to remove (json-string)
 414
 415 Example:
 416
 417 -> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0",
 418                                                            "name": "bitmap0" } }
 419 <- { "return": {} }
 420
 421 blockdev-snapshot-sync
 422 ----------------------
 423
 424 Synchronous snapshot of a block device. snapshot-file specifies the
 425 target of the new image. If the file exists, or if it is a device, the
 426 snapshot will be created in the existing file/device. If does not
 427 exist, a new file will be created. format specifies the format of the
 428 snapshot image, default is qcow2.
 429
 430 Arguments:
 431
 432 - "device": device name to snapshot (json-string)
 433 - "node-name": graph node name to snapshot (json-string)
 434 - "snapshot-file": name of new image file (json-string)
 435 - "snapshot-node-name": graph node name of the new snapshot (json-string)
 436 - "mode": whether and how QEMU should create the snapshot file
 437   (NewImageMode, optional, default "absolute-paths")
 438 - "format": format of new image (json-string, optional)
 439
 440 Example:
 441
 442 -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
 443                                                          "snapshot-file":
 444                                                         "/some/place/my-image",
 445                                                         "format": "qcow2" } }
 446 <- { "return": {} }
 447
 448 blockdev-snapshot
 449 -----------------
 450 Since 2.5
 451
 452 Create a snapshot, by installing 'node' as the backing image of
 453 'overlay'. Additionally, if 'node' is associated with a block
 454 device, the block device changes to using 'overlay' as its new active
 455 image.
 456
 457 Arguments:
 458
 459 - "node": device that will have a snapshot created (json-string)
 460 - "overlay": device that will have 'node' as its backing image (json-string)
 461
 462 Example:
 463
 464 -> { "execute": "blockdev-add",
 465                 "arguments": { "driver": "qcow2",
 466                                "node-name": "node1534",
 467                                "file": { "driver": "file",
 468                                          "filename": "hd1.qcow2" },
 469                                "backing": "" } }
 470
 471 <- { "return": {} }
 472
 473 -> { "execute": "blockdev-snapshot", "arguments": { "node": "ide-hd0",
 474                                                     "overlay": "node1534" } }
 475 <- { "return": {} }
 476
 477 blockdev-snapshot-internal-sync
 478 -------------------------------
 479
 480 Synchronously take an internal snapshot of a block device when the format of
 481 image used supports it.  If the name is an empty string, or a snapshot with
 482 name already exists, the operation will fail.
 483
 484 Arguments:
 485
 486 - "device": the device name or node-name of a root node to snapshot
 487             (json-string)
 488 - "name": name of the new snapshot (json-string)
 489
 490 Example:
 491
 492 -> { "execute": "blockdev-snapshot-internal-sync",
 493                 "arguments": { "device": "ide-hd0",
 494                                "name": "snapshot0" }
 495    }
 496 <- { "return": {} }
 497
 498 blockdev-snapshot-delete-internal-sync
 499 --------------------------------------
 500
 501 Synchronously delete an internal snapshot of a block device when the format of
 502 image used supports it.  The snapshot is identified by name or id or both.  One
 503 of name or id is required.  If the snapshot is not found, the operation will
 504 fail.
 505
 506 Arguments:
 507
 508 - "device": the device name or node-name of a root node (json-string)
 509 - "id": ID of the snapshot (json-string, optional)
 510 - "name": name of the snapshot (json-string, optional)
 511
 512 Example:
 513
 514 -> { "execute": "blockdev-snapshot-delete-internal-sync",
 515                 "arguments": { "device": "ide-hd0",
 516                                "name": "snapshot0" }
 517    }
 518 <- { "return": {
 519                    "id": "1",
 520                    "name": "snapshot0",
 521                    "vm-state-size": 0,
 522                    "date-sec": 1000012,
 523                    "date-nsec": 10,
 524                    "vm-clock-sec": 100,
 525                    "vm-clock-nsec": 20
 526      }
 527    }
 528
 529 drive-mirror
 530 ------------
 531
 532 Start mirroring a block device's writes to a new destination. target
 533 specifies the target of the new image. If the file exists, or if it is
 534 a device, it will be used as the new destination for writes. If it does not
 535 exist, a new file will be created. format specifies the format of the
 536 mirror image, default is to probe if mode='existing', else the format
 537 of the source.
 538
 539 Arguments:
 540
 541 - "job-id": Identifier for the newly-created block job. If omitted,
 542             the device name will be used. (json-string, optional)
 543 - "device": the device name or node-name of a root node whose writes should be
 544             mirrored. (json-string)
 545 - "target": name of new image file (json-string)
 546 - "format": format of new image (json-string, optional)
 547 - "node-name": the name of the new block driver state in the node graph
 548                (json-string, optional)
 549 - "replaces": the block driver node name to replace when finished
 550               (json-string, optional)
 551 - "mode": how an image file should be created into the target
 552   file/device (NewImageMode, optional, default 'absolute-paths')
 553 - "speed": maximum speed of the streaming job, in bytes per second
 554   (json-int)
 555 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
 556 - "buf-size": maximum amount of data in flight from source to target, in bytes
 557   (json-int, default 10M)
 558 - "sync": what parts of the disk image should be copied to the destination;
 559   possibilities include "full" for all the disk, "top" for only the sectors
 560   allocated in the topmost image, or "none" to only replicate new I/O
 561   (MirrorSyncMode).
 562 - "on-source-error": the action to take on an error on the source
 563   (BlockdevOnError, default 'report')
 564 - "on-target-error": the action to take on an error on the target
 565   (BlockdevOnError, default 'report')
 566 - "unmap": whether the target sectors should be discarded where source has only
 567   zeroes. (json-bool, optional, default true)
 568
 569 The default value of the granularity is the image cluster size clamped
 570 between 4096 and 65536, if the image format defines one.  If the format
 571 does not define a cluster size, the default value of the granularity
 572 is 65536.
 573
 574
 575 Example:
 576
 577 -> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
 578                                                "target": "/some/place/my-image",
 579                                                "sync": "full",
 580                                                "format": "qcow2" } }
 581 <- { "return": {} }
 582
 583 blockdev-mirror
 584 ------------
 585
 586 Start mirroring a block device's writes to another block device. target
 587 specifies the target of mirror operation.
 588
 589 Arguments:
 590
 591 - "job-id": Identifier for the newly-created block job. If omitted,
 592             the device name will be used. (json-string, optional)
 593 - "device": The device name or node-name of a root node whose writes should be
 594             mirrored (json-string)
 595 - "target": device name to mirror to (json-string)
 596 - "replaces": the block driver node name to replace when finished
 597               (json-string, optional)
 598 - "speed": maximum speed of the streaming job, in bytes per second
 599   (json-int)
 600 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
 601 - "buf_size": maximum amount of data in flight from source to target, in bytes
 602   (json-int, default 10M)
 603 - "sync": what parts of the disk image should be copied to the destination;
 604   possibilities include "full" for all the disk, "top" for only the sectors
 605   allocated in the topmost image, or "none" to only replicate new I/O
 606   (MirrorSyncMode).
 607 - "on-source-error": the action to take on an error on the source
 608   (BlockdevOnError, default 'report')
 609 - "on-target-error": the action to take on an error on the target
 610   (BlockdevOnError, default 'report')
 611
 612 The default value of the granularity is the image cluster size clamped
 613 between 4096 and 65536, if the image format defines one.  If the format
 614 does not define a cluster size, the default value of the granularity
 615 is 65536.
 616
 617 Example:
 618
 619 -> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
 620                                                   "target": "target0",
 621                                                   "sync": "full" } }
 622 <- { "return": {} }
 623
 624 change-backing-file
 625 -------------------
 626 Since: 2.1
 627
 628 Change the backing file in the image file metadata.  This does not cause
 629 QEMU to reopen the image file to reparse the backing filename (it may,
 630 however, perform a reopen to change permissions from r/o -> r/w -> r/o,
 631 if needed). The new backing file string is written into the image file
 632 metadata, and the QEMU internal strings are updated.
 633
 634 Arguments:
 635
 636 - "image-node-name":    The name of the block driver state node of the
 637                         image to modify.  The "device" is argument is used to
 638                         verify "image-node-name" is in the chain described by
 639                         "device".
 640                         (json-string, optional)
 641
 642 - "device":             The device name or node-name of the root node that owns
 643                         image-node-name.
 644                         (json-string)
 645
 646 - "backing-file":       The string to write as the backing file.  This string is
 647                         not validated, so care should be taken when specifying
 648                         the string or the image chain may not be able to be
 649                         reopened again.
 650                         (json-string)
 651
 652 Returns: Nothing on success
 653          If "device" does not exist or cannot be determined, DeviceNotFound
 654
 655 block_passwd
 656 ------------
 657
 658 Set the password of encrypted block devices.
 659
 660 Arguments:
 661
 662 - "device": device name (json-string)
 663 - "node-name": name in the block driver state graph (json-string)
 664 - "password": password (json-string)
 665
 666 Example:
 667
 668 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
 669                                                "password": "12345" } }
 670 <- { "return": {} }
 671
 672 block_set_io_throttle
 673 ------------
 674
 675 Change I/O throttle limits for a block drive.
 676
 677 Arguments:
 678
 679 - "device": block device name (deprecated, use @id instead)
 680             (json-string, optional)
 681 - "id": the name or QOM path of the guest device (json-string, optional)
 682 - "bps": total throughput limit in bytes per second (json-int)
 683 - "bps_rd": read throughput limit in bytes per second (json-int)
 684 - "bps_wr": write throughput limit in bytes per second (json-int)
 685 - "iops": total I/O operations per second (json-int)
 686 - "iops_rd": read I/O operations per second (json-int)
 687 - "iops_wr": write I/O operations per second (json-int)
 688 - "bps_max": total throughput limit during bursts, in bytes (json-int, optional)
 689 - "bps_rd_max": read throughput limit during bursts, in bytes (json-int, optional)
 690 - "bps_wr_max": write throughput limit during bursts, in bytes (json-int, optional)
 691 - "iops_max": total I/O operations per second during bursts (json-int, optional)
 692 - "iops_rd_max": read I/O operations per second during bursts (json-int, optional)
 693 - "iops_wr_max": write I/O operations per second during bursts (json-int, optional)
 694 - "bps_max_length": maximum length of the @bps_max burst period, in seconds (json-int, optional)
 695 - "bps_rd_max_length": maximum length of the @bps_rd_max burst period, in seconds (json-int, optional)
 696 - "bps_wr_max_length": maximum length of the @bps_wr_max burst period, in seconds (json-int, optional)
 697 - "iops_max_length": maximum length of the @iops_max burst period, in seconds (json-int, optional)
 698 - "iops_rd_max_length": maximum length of the @iops_rd_max burst period, in seconds (json-int, optional)
 699 - "iops_wr_max_length": maximum length of the @iops_wr_max burst period, in seconds (json-int, optional)
 700 - "iops_size":  I/O size in bytes when limiting (json-int, optional)
 701 - "group": throttle group name (json-string, optional)
 702
 703 Example:
 704
 705 -> { "execute": "block_set_io_throttle", "arguments": { "id": "ide0-1-0",
 706                                                "bps": 1000000,
 707                                                "bps_rd": 0,
 708                                                "bps_wr": 0,
 709                                                "iops": 0,
 710                                                "iops_rd": 0,
 711                                                "iops_wr": 0,
 712                                                "bps_max": 8000000,
 713                                                "bps_rd_max": 0,
 714                                                "bps_wr_max": 0,
 715                                                "iops_max": 0,
 716                                                "iops_rd_max": 0,
 717                                                "iops_wr_max": 0,
 718                                                "bps_max_length": 60,
 719                                                "iops_size": 0 } }
 720 <- { "return": {} }
 721
 722 qmp_capabilities
 723 ----------------
 724
 725 Enable QMP capabilities.
 726
 727 Arguments: None.
 728
 729 Example:
 730
 731 -> { "execute": "qmp_capabilities" }
 732 <- { "return": {} }
 733
 734 Note: This command must be issued before issuing any other command.
 735
 736 3. Query Commands
 737 =================
 738
 739
 740 query-version
 741 -------------
 742
 743 Show QEMU version.
 744
 745 Return a json-object with the following information:
 746
 747 - "qemu": A json-object containing three integer values:
 748     - "major": QEMU's major version (json-int)
 749     - "minor": QEMU's minor version (json-int)
 750     - "micro": QEMU's micro version (json-int)
 751 - "package": package's version (json-string)
 752
 753 Example:
 754
 755 -> { "execute": "query-version" }
 756 <- {
 757       "return":{
 758          "qemu":{
 759             "major":0,
 760             "minor":11,
 761             "micro":5
 762          },
 763          "package":""
 764       }
 765    }
 766
 767 query-commands
 768 --------------
 769
 770 List QMP available commands.
 771
 772 Each command is represented by a json-object, the returned value is a json-array
 773 of all commands.
 774
 775 Each json-object contain:
 776
 777 - "name": command's name (json-string)
 778
 779 Example:
 780
 781 -> { "execute": "query-commands" }
 782 <- {
 783       "return":[
 784          {
 785             "name":"query-balloon"
 786          },
 787          {
 788             "name":"system_powerdown"
 789          }
 790       ]
 791    }
 792
 793 Note: This example has been shortened as the real response is too long.
 794
 795 query-qmp-schema
 796 ----------------
 797
 798 Return the QMP wire schema.  The returned value is a json-array of
 799 named schema entities.  Entities are commands, events and various
 800 types.  See docs/qapi-code-gen.txt for information on their structure
 801 and intended use.
 802
 803 blockdev-add
 804 ------------
 805
 806 Add a block device.
 807
 808 This command is still a work in progress.  It doesn't support all
 809 block drivers among other things.  Stay away from it unless you want
 810 to help with its development.
 811
 812 For the arguments, see the QAPI schema documentation of BlockdevOptions.
 813
 814 Example (1):
 815
 816 -> { "execute": "blockdev-add",
 817     "arguments": { "driver": "qcow2",
 818                    "file": { "driver": "file",
 819                              "filename": "test.qcow2" } } }
 820 <- { "return": {} }
 821
 822 Example (2):
 823
 824 -> { "execute": "blockdev-add",
 825      "arguments": {
 826          "driver": "qcow2",
 827          "node-name": "my_disk",
 828          "discard": "unmap",
 829          "cache": {
 830              "direct": true,
 831              "writeback": true
 832          },
 833          "file": {
 834              "driver": "file",
 835              "filename": "/tmp/test.qcow2"
 836          },
 837          "backing": {
 838              "driver": "raw",
 839              "file": {
 840                  "driver": "file",
 841                  "filename": "/dev/fdset/4"
 842              }
 843          }
 844        }
 845      }
 846
 847 <- { "return": {} }
 848
 849 x-blockdev-del
 850 ------------
 851 Since 2.5
 852
 853 Deletes a block device that has been added using blockdev-add.
 854 The command will fail if the node is attached to a device or is
 855 otherwise being used.
 856
 857 This command is still a work in progress and is considered
 858 experimental. Stay away from it unless you want to help with its
 859 development.
 860
 861 Arguments:
 862
 863 - "node-name": Name of the graph node to delete (json-string)
 864
 865 Example:
 866
 867 -> { "execute": "blockdev-add",
 868      "arguments": {
 869          "driver": "qcow2",
 870          "node-name": "node0",
 871          "file": {
 872              "driver": "file",
 873              "filename": "test.qcow2"
 874          }
 875      }
 876    }
 877
 878 <- { "return": {} }
 879
 880 -> { "execute": "x-blockdev-del",
 881      "arguments": { "node-name": "node0" }
 882    }
 883 <- { "return": {} }
 884
 885 blockdev-open-tray
 886 ------------------
 887
 888 Opens a block device's tray. If there is a block driver state tree inserted as a
 889 medium, it will become inaccessible to the guest (but it will remain associated
 890 to the block device, so closing the tray will make it accessible again).
 891
 892 If the tray was already open before, this will be a no-op.
 893
 894 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
 895 which no such event will be generated, these include:
 896 - if the guest has locked the tray, @force is false and the guest does not
 897   respond to the eject request
 898 - if the BlockBackend denoted by @device does not have a guest device attached
 899   to it
 900 - if the guest device does not have an actual tray and is empty, for instance
 901   for floppy disk drives
 902
 903 Arguments:
 904
 905 - "device": block device name (deprecated, use @id instead)
 906             (json-string, optional)
 907 - "id": the name or QOM path of the guest device (json-string, optional)
 908 - "force": if false (the default), an eject request will be sent to the guest if
 909            it has locked the tray (and the tray will not be opened immediately);
 910            if true, the tray will be opened regardless of whether it is locked
 911            (json-bool, optional)
 912
 913 Example:
 914
 915 -> { "execute": "blockdev-open-tray",
 916      "arguments": { "id": "ide0-1-0" } }
 917
 918 <- { "timestamp": { "seconds": 1418751016,
 919                     "microseconds": 716996 },
 920      "event": "DEVICE_TRAY_MOVED",
 921      "data": { "device": "ide1-cd0",
 922                "id": "ide0-1-0",
 923                "tray-open": true } }
 924
 925 <- { "return": {} }
 926
 927 blockdev-close-tray
 928 -------------------
 929
 930 Closes a block device's tray. If there is a block driver state tree associated
 931 with the block device (which is currently ejected), that tree will be loaded as
 932 the medium.
 933
 934 If the tray was already closed before, this will be a no-op.
 935
 936 Arguments:
 937
 938 - "device": block device name (deprecated, use @id instead)
 939             (json-string, optional)
 940 - "id": the name or QOM path of the guest device (json-string, optional)
 941
 942 Example:
 943
 944 -> { "execute": "blockdev-close-tray",
 945      "arguments": { "id": "ide0-1-0" } }
 946
 947 <- { "timestamp": { "seconds": 1418751345,
 948                     "microseconds": 272147 },
 949      "event": "DEVICE_TRAY_MOVED",
 950      "data": { "device": "ide1-cd0",
 951                "id": "ide0-1-0",
 952                "tray-open": false } }
 953
 954 <- { "return": {} }
 955
 956 x-blockdev-remove-medium
 957 ------------------------
 958
 959 Removes a medium (a block driver state tree) from a block device. That block
 960 device's tray must currently be open (unless there is no attached guest device).
 961
 962 If the tray is open and there is no medium inserted, this will be a no-op.
 963
 964 This command is still a work in progress and is considered experimental.
 965 Stay away from it unless you want to help with its development.
 966
 967 Arguments:
 968
 969 - "device": block device name (deprecated, use @id instead)
 970             (json-string, optional)
 971 - "id": the name or QOM path of the guest device (json-string, optional)
 972
 973 Example:
 974
 975 -> { "execute": "x-blockdev-remove-medium",
 976      "arguments": { "id": "ide0-1-0" } }
 977
 978 <- { "error": { "class": "GenericError",
 979                 "desc": "Tray of device 'ide0-1-0' is not open" } }
 980
 981 -> { "execute": "blockdev-open-tray",
 982      "arguments": { "id": "ide0-1-0" } }
 983
 984 <- { "timestamp": { "seconds": 1418751627,
 985                     "microseconds": 549958 },
 986      "event": "DEVICE_TRAY_MOVED",
 987      "data": { "device": "ide1-cd0",
 988                "id": "ide0-1-0",
 989                "tray-open": true } }
 990
 991 <- { "return": {} }
 992
 993 -> { "execute": "x-blockdev-remove-medium",
 994      "arguments": { "device": "ide0-1-0" } }
 995
 996 <- { "return": {} }
 997
 998 x-blockdev-insert-medium
 999 ------------------------
1000
1001 Inserts a medium (a block driver state tree) into a block device. That block
1002 device's tray must currently be open (unless there is no attached guest device)
1003 and there must be no medium inserted already.
1004
1005 This command is still a work in progress and is considered experimental.
1006 Stay away from it unless you want to help with its development.
1007
1008 Arguments:
1009
1010 - "device": block device name (deprecated, use @id instead)
1011             (json-string, optional)
1012 - "id": the name or QOM path of the guest device (json-string, optional)
1013 - "node-name": root node of the BDS tree to insert into the block device
1014
1015 Example:
1016
1017 -> { "execute": "blockdev-add",
1018      "arguments": { { "node-name": "node0",
1019                       "driver": "raw",
1020                       "file": { "driver": "file",
1021                                 "filename": "fedora.iso" } } }
1022
1023 <- { "return": {} }
1024
1025 -> { "execute": "x-blockdev-insert-medium",
1026      "arguments": { "id": "ide0-1-0",
1027                     "node-name": "node0" } }
1028
1029 <- { "return": {} }
1030
1031 x-blockdev-change
1032 -----------------
1033
1034 Dynamically reconfigure the block driver state graph. It can be used
1035 to add, remove, insert or replace a graph node. Currently only the
1036 Quorum driver implements this feature to add or remove its child. This
1037 is useful to fix a broken quorum child.
1038
1039 If @node is specified, it will be inserted under @parent. @child
1040 may not be specified in this case. If both @parent and @child are
1041 specified but @node is not, @child will be detached from @parent.
1042
1043 Arguments:
1044 - "parent": the id or name of the parent node (json-string)
1045 - "child": the name of a child under the given parent node (json-string, optional)
1046 - "node": the name of the node that will be added (json-string, optional)
1047
1048 Note: this command is experimental, and not a stable API. It doesn't
1049 support all kinds of operations, all kinds of children, nor all block
1050 drivers.
1051
1052 Warning: The data in a new quorum child MUST be consistent with that of
1053 the rest of the array.
1054
1055 Example:
1056
1057 Add a new node to a quorum
1058 -> { "execute": "blockdev-add",
1059      "arguments": { "driver": "raw",
1060                     "node-name": "new_node",
1061                     "file": { "driver": "file",
1062                               "filename": "test.raw" } } }
1063 <- { "return": {} }
1064 -> { "execute": "x-blockdev-change",
1065      "arguments": { "parent": "disk1",
1066                     "node": "new_node" } }
1067 <- { "return": {} }
1068
1069 Delete a quorum's node
1070 -> { "execute": "x-blockdev-change",
1071      "arguments": { "parent": "disk1",
1072                     "child": "children.1" } }
1073 <- { "return": {} }
1074
1075 query-named-block-nodes
1076 -----------------------
1077
1078 Return a list of BlockDeviceInfo for all the named block driver nodes
1079
1080 Example:
1081
1082 -> { "execute": "query-named-block-nodes" }
1083 <- { "return": [ { "ro":false,
1084                    "drv":"qcow2",
1085                    "encrypted":false,
1086                    "file":"disks/test.qcow2",
1087                    "node-name": "my-node",
1088                    "backing_file_depth":1,
1089                    "bps":1000000,
1090                    "bps_rd":0,
1091                    "bps_wr":0,
1092                    "iops":1000000,
1093                    "iops_rd":0,
1094                    "iops_wr":0,
1095                    "bps_max": 8000000,
1096                    "bps_rd_max": 0,
1097                    "bps_wr_max": 0,
1098                    "iops_max": 0,
1099                    "iops_rd_max": 0,
1100                    "iops_wr_max": 0,
1101                    "iops_size": 0,
1102                    "write_threshold": 0,
1103                    "image":{
1104                       "filename":"disks/test.qcow2",
1105                       "format":"qcow2",
1106                       "virtual-size":2048000,
1107                       "backing_file":"base.qcow2",
1108                       "full-backing-filename":"disks/base.qcow2",
1109                       "backing-filename-format":"qcow2",
1110                       "snapshots":[
1111                          {
1112                             "id": "1",
1113                             "name": "snapshot1",
1114                             "vm-state-size": 0,
1115                             "date-sec": 10000200,
1116                             "date-nsec": 12,
1117                             "vm-clock-sec": 206,
1118                             "vm-clock-nsec": 30
1119                          }
1120                       ],
1121                       "backing-image":{
1122                           "filename":"disks/base.qcow2",
1123                           "format":"qcow2",
1124                           "virtual-size":2048000
1125                       }
1126                    } } ] }
1127
1128 blockdev-change-medium
1129 ----------------------
1130
1131 Changes the medium inserted into a block device by ejecting the current medium
1132 and loading a new image file which is inserted as the new medium.
1133
1134 Arguments:
1135
1136 - "device": block device name (deprecated, use @id instead)
1137             (json-string, optional)
1138 - "id": the name or QOM path of the guest device (json-string, optional)
1139 - "filename": filename of the new image (json-string)
1140 - "format": format of the new image (json-string, optional)
1141 - "read-only-mode": new read-only mode (json-string, optional)
1142           - Possible values: "retain" (default), "read-only", "read-write"
1143
1144 Examples:
1145
1146 1. Change a removable medium
1147
1148 -> { "execute": "blockdev-change-medium",
1149              "arguments": { "id": "ide0-1-0",
1150                             "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
1151                             "format": "raw" } }
1152 <- { "return": {} }
1153
1154 2. Load a read-only medium into a writable drive
1155
1156 -> { "execute": "blockdev-change-medium",
1157              "arguments": { "id": "floppyA",
1158                             "filename": "/srv/images/ro.img",
1159                             "format": "raw",
1160                             "read-only-mode": "retain" } }
1161
1162 <- { "error":
1163      { "class": "GenericError",
1164        "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
1165
1166 -> { "execute": "blockdev-change-medium",
1167              "arguments": { "id": "floppyA",
1168                             "filename": "/srv/images/ro.img",
1169                             "format": "raw",
1170                             "read-only-mode": "read-only" } }
1171
1172 <- { "return": {} }
1173
1174 trace-event-get-state
1175 ---------------------
1176
1177 Query the state of events.
1178
1179 Arguments:
1180
1181 - "name": Event name pattern (json-string).
1182 - "vcpu": The vCPU to query, any vCPU by default (json-int, optional).
1183
1184 An event is returned if:
1185 - its name matches the "name" pattern, and
1186 - if "vcpu" is given, the event has the "vcpu" property.
1187
1188 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
1189 returning their state on the specified vCPU. Special case: if "name" is an exact
1190 match, "vcpu" is given and the event does not have the "vcpu" property, an error
1191 is returned.
1192
1193 Example:
1194
1195 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
1196 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
1197
1198 trace-event-set-state
1199 ---------------------
1200
1201 Set the state of events.
1202
1203 Arguments:
1204
1205 - "name": Event name pattern (json-string).
1206 - "enable": Whether to enable or disable the event (json-bool).
1207 - "ignore-unavailable": Whether to ignore errors for events that cannot be
1208   changed (json-bool, optional).
1209 - "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional).
1210
1211 An event's state is modified if:
1212 - its name matches the "name" pattern, and
1213 - if "vcpu" is given, the event has the "vcpu" property.
1214
1215 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
1216 setting their state on the specified vCPU. Special case: if "name" is an exact
1217 match, "vcpu" is given and the event does not have the "vcpu" property, an error
1218 is returned.
1219
1220 Example:
1221
1222 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
1223 <- { "return": {} }
1224
1225 block-set-write-threshold
1226 ------------
1227
1228 Change the write threshold for a block drive. The threshold is an offset,
1229 thus must be non-negative. Default is no write threshold.
1230 Setting the threshold to zero disables it.
1231
1232 Arguments:
1233
1234 - "node-name": the node name in the block driver state graph (json-string)
1235 - "write-threshold": the write threshold in bytes (json-int)
1236
1237 Example:
1238
1239 -> { "execute": "block-set-write-threshold",
1240   "arguments": { "node-name": "mydev",
1241                  "write-threshold": 17179869184 } }
1242 <- { "return": {} }
1243
1244 Show rocker switch
1245 ------------------
1246
1247 Arguments:
1248
1249 - "name": switch name
1250
1251 Example:
1252
1253 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
1254 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
1255
1256 Show rocker switch ports
1257 ------------------------
1258
1259 Arguments:
1260
1261 - "name": switch name
1262
1263 Example:
1264
1265 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
1266 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
1267                   "autoneg": "off", "link-up": true, "speed": 10000},
1268                  {"duplex": "full", "enabled": true, "name": "sw1.2",
1269                   "autoneg": "off", "link-up": true, "speed": 10000}
1270    ]}
1271
1272 Show rocker switch OF-DPA flow tables
1273 -------------------------------------
1274
1275 Arguments:
1276
1277 - "name": switch name
1278 - "tbl-id": (optional) flow table ID
1279
1280 Example:
1281
1282 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
1283 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
1284                   "hits": 138,
1285                   "cookie": 0,
1286                   "action": {"goto-tbl": 10},
1287                   "mask": {"in-pport": 4294901760}
1288                  },
1289                  {...more...},
1290    ]}
1291
1292 Show rocker OF-DPA group tables
1293 -------------------------------
1294
1295 Arguments:
1296
1297 - "name": switch name
1298 - "type": (optional) group type
1299
1300 Example:
1301
1302 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
1303 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
1304                   "pop-vlan": 1, "id": 251723778},
1305                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
1306                   "pop-vlan": 1, "id": 251723776},
1307                  {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
1308                   "pop-vlan": 1, "id": 251658241},
1309                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
1310                   "pop-vlan": 1, "id": 251658240}
1311    ]}
1312
1313 query-gic-capabilities
1314 ---------------
1315
1316 Return a list of GICCapability objects, describing supported GIC
1317 (Generic Interrupt Controller) versions.
1318
1319 Arguments: None
1320
1321 Example:
1322
1323 -> { "execute": "query-gic-capabilities" }
1324 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
1325                 { "version": 3, "emulated": false, "kernel": true } ] }
1326
1327 Show existing/possible CPUs
1328 ---------------------------
1329
1330 Arguments: None.
1331
1332 Example for pseries machine type started with
1333 -smp 2,cores=2,maxcpus=4 -cpu POWER8:
1334
1335 -> { "execute": "query-hotpluggable-cpus" }
1336 <- {"return": [
1337      { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
1338        "vcpus-count": 1 },
1339      { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
1340        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
1341    ]}'
1342
1343 Example for pc machine type started with
1344 -smp 1,maxcpus=2:
1345     -> { "execute": "query-hotpluggable-cpus" }
1346     <- {"return": [
1347          {
1348             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
1349             "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
1350          },
1351          {
1352             "qom-path": "/machine/unattached/device[0]",
1353             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
1354             "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
1355          }
1356        ]}