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-snapshot-internal-sync
 173 -------------------------------
 174
 175 Synchronously take an internal snapshot of a block device when the format of
 176 image used supports it.  If the name is an empty string, or a snapshot with
 177 name already exists, the operation will fail.
 178
 179 Arguments:
 180
 181 - "device": the device name or node-name of a root node to snapshot
 182             (json-string)
 183 - "name": name of the new snapshot (json-string)
 184
 185 Example:
 186
 187 -> { "execute": "blockdev-snapshot-internal-sync",
 188                 "arguments": { "device": "ide-hd0",
 189                                "name": "snapshot0" }
 190    }
 191 <- { "return": {} }
 192
 193 blockdev-snapshot-delete-internal-sync
 194 --------------------------------------
 195
 196 Synchronously delete an internal snapshot of a block device when the format of
 197 image used supports it.  The snapshot is identified by name or id or both.  One
 198 of name or id is required.  If the snapshot is not found, the operation will
 199 fail.
 200
 201 Arguments:
 202
 203 - "device": the device name or node-name of a root node (json-string)
 204 - "id": ID of the snapshot (json-string, optional)
 205 - "name": name of the snapshot (json-string, optional)
 206
 207 Example:
 208
 209 -> { "execute": "blockdev-snapshot-delete-internal-sync",
 210                 "arguments": { "device": "ide-hd0",
 211                                "name": "snapshot0" }
 212    }
 213 <- { "return": {
 214                    "id": "1",
 215                    "name": "snapshot0",
 216                    "vm-state-size": 0,
 217                    "date-sec": 1000012,
 218                    "date-nsec": 10,
 219                    "vm-clock-sec": 100,
 220                    "vm-clock-nsec": 20
 221      }
 222    }
 223
 224 blockdev-mirror
 225 ------------
 226
 227 Start mirroring a block device's writes to another block device. target
 228 specifies the target of mirror operation.
 229
 230 Arguments:
 231
 232 - "job-id": Identifier for the newly-created block job. If omitted,
 233             the device name will be used. (json-string, optional)
 234 - "device": The device name or node-name of a root node whose writes should be
 235             mirrored (json-string)
 236 - "target": device name to mirror to (json-string)
 237 - "replaces": the block driver node name to replace when finished
 238               (json-string, optional)
 239 - "speed": maximum speed of the streaming job, in bytes per second
 240   (json-int)
 241 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
 242 - "buf_size": maximum amount of data in flight from source to target, in bytes
 243   (json-int, default 10M)
 244 - "sync": what parts of the disk image should be copied to the destination;
 245   possibilities include "full" for all the disk, "top" for only the sectors
 246   allocated in the topmost image, or "none" to only replicate new I/O
 247   (MirrorSyncMode).
 248 - "on-source-error": the action to take on an error on the source
 249   (BlockdevOnError, default 'report')
 250 - "on-target-error": the action to take on an error on the target
 251   (BlockdevOnError, default 'report')
 252
 253 The default value of the granularity is the image cluster size clamped
 254 between 4096 and 65536, if the image format defines one.  If the format
 255 does not define a cluster size, the default value of the granularity
 256 is 65536.
 257
 258 Example:
 259
 260 -> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
 261                                                   "target": "target0",
 262                                                   "sync": "full" } }
 263 <- { "return": {} }
 264
 265 qmp_capabilities
 266 ----------------
 267
 268 Enable QMP capabilities.
 269
 270 Arguments: None.
 271
 272 Example:
 273
 274 -> { "execute": "qmp_capabilities" }
 275 <- { "return": {} }
 276
 277 Note: This command must be issued before issuing any other command.
 278
 279 3. Query Commands
 280 =================
 281
 282
 283 query-version
 284 -------------
 285
 286 Show QEMU version.
 287
 288 Return a json-object with the following information:
 289
 290 - "qemu": A json-object containing three integer values:
 291     - "major": QEMU's major version (json-int)
 292     - "minor": QEMU's minor version (json-int)
 293     - "micro": QEMU's micro version (json-int)
 294 - "package": package's version (json-string)
 295
 296 Example:
 297
 298 -> { "execute": "query-version" }
 299 <- {
 300       "return":{
 301          "qemu":{
 302             "major":0,
 303             "minor":11,
 304             "micro":5
 305          },
 306          "package":""
 307       }
 308    }
 309
 310 query-commands
 311 --------------
 312
 313 List QMP available commands.
 314
 315 Each command is represented by a json-object, the returned value is a json-array
 316 of all commands.
 317
 318 Each json-object contain:
 319
 320 - "name": command's name (json-string)
 321
 322 Example:
 323
 324 -> { "execute": "query-commands" }
 325 <- {
 326       "return":[
 327          {
 328             "name":"query-balloon"
 329          },
 330          {
 331             "name":"system_powerdown"
 332          }
 333       ]
 334    }
 335
 336 Note: This example has been shortened as the real response is too long.
 337
 338 query-qmp-schema
 339 ----------------
 340
 341 Return the QMP wire schema.  The returned value is a json-array of
 342 named schema entities.  Entities are commands, events and various
 343 types.  See docs/qapi-code-gen.txt for information on their structure
 344 and intended use.
 345
 346 blockdev-close-tray
 347 -------------------
 348
 349 Closes a block device's tray. If there is a block driver state tree associated
 350 with the block device (which is currently ejected), that tree will be loaded as
 351 the medium.
 352
 353 If the tray was already closed before, this will be a no-op.
 354
 355 Arguments:
 356
 357 - "device": block device name (deprecated, use @id instead)
 358             (json-string, optional)
 359 - "id": the name or QOM path of the guest device (json-string, optional)
 360
 361 Example:
 362
 363 -> { "execute": "blockdev-close-tray",
 364      "arguments": { "id": "ide0-1-0" } }
 365
 366 <- { "timestamp": { "seconds": 1418751345,
 367                     "microseconds": 272147 },
 368      "event": "DEVICE_TRAY_MOVED",
 369      "data": { "device": "ide1-cd0",
 370                "id": "ide0-1-0",
 371                "tray-open": false } }
 372
 373 <- { "return": {} }
 374
 375 x-blockdev-remove-medium
 376 ------------------------
 377
 378 Removes a medium (a block driver state tree) from a block device. That block
 379 device's tray must currently be open (unless there is no attached guest device).
 380
 381 If the tray is open and there is no medium inserted, this will be a no-op.
 382
 383 This command is still a work in progress and is considered experimental.
 384 Stay away from it unless you want to help with its development.
 385
 386 Arguments:
 387
 388 - "device": block device name (deprecated, use @id instead)
 389             (json-string, optional)
 390 - "id": the name or QOM path of the guest device (json-string, optional)
 391
 392 Example:
 393
 394 -> { "execute": "x-blockdev-remove-medium",
 395      "arguments": { "id": "ide0-1-0" } }
 396
 397 <- { "error": { "class": "GenericError",
 398                 "desc": "Tray of device 'ide0-1-0' is not open" } }
 399
 400 -> { "execute": "blockdev-open-tray",
 401      "arguments": { "id": "ide0-1-0" } }
 402
 403 <- { "timestamp": { "seconds": 1418751627,
 404                     "microseconds": 549958 },
 405      "event": "DEVICE_TRAY_MOVED",
 406      "data": { "device": "ide1-cd0",
 407                "id": "ide0-1-0",
 408                "tray-open": true } }
 409
 410 <- { "return": {} }
 411
 412 -> { "execute": "x-blockdev-remove-medium",
 413      "arguments": { "device": "ide0-1-0" } }
 414
 415 <- { "return": {} }
 416
 417 x-blockdev-insert-medium
 418 ------------------------
 419
 420 Inserts a medium (a block driver state tree) into a block device. That block
 421 device's tray must currently be open (unless there is no attached guest device)
 422 and there must be no medium inserted already.
 423
 424 This command is still a work in progress and is considered experimental.
 425 Stay away from it unless you want to help with its development.
 426
 427 Arguments:
 428
 429 - "device": block device name (deprecated, use @id instead)
 430             (json-string, optional)
 431 - "id": the name or QOM path of the guest device (json-string, optional)
 432 - "node-name": root node of the BDS tree to insert into the block device
 433
 434 Example:
 435
 436 -> { "execute": "blockdev-add",
 437      "arguments": { { "node-name": "node0",
 438                       "driver": "raw",
 439                       "file": { "driver": "file",
 440                                 "filename": "fedora.iso" } } }
 441
 442 <- { "return": {} }
 443
 444 -> { "execute": "x-blockdev-insert-medium",
 445      "arguments": { "id": "ide0-1-0",
 446                     "node-name": "node0" } }
 447
 448 <- { "return": {} }
 449
 450 x-blockdev-change
 451 -----------------
 452
 453 Dynamically reconfigure the block driver state graph. It can be used
 454 to add, remove, insert or replace a graph node. Currently only the
 455 Quorum driver implements this feature to add or remove its child. This
 456 is useful to fix a broken quorum child.
 457
 458 If @node is specified, it will be inserted under @parent. @child
 459 may not be specified in this case. If both @parent and @child are
 460 specified but @node is not, @child will be detached from @parent.
 461
 462 Arguments:
 463 - "parent": the id or name of the parent node (json-string)
 464 - "child": the name of a child under the given parent node (json-string, optional)
 465 - "node": the name of the node that will be added (json-string, optional)
 466
 467 Note: this command is experimental, and not a stable API. It doesn't
 468 support all kinds of operations, all kinds of children, nor all block
 469 drivers.
 470
 471 Warning: The data in a new quorum child MUST be consistent with that of
 472 the rest of the array.
 473
 474 Example:
 475
 476 Add a new node to a quorum
 477 -> { "execute": "blockdev-add",
 478      "arguments": { "driver": "raw",
 479                     "node-name": "new_node",
 480                     "file": { "driver": "file",
 481                               "filename": "test.raw" } } }
 482 <- { "return": {} }
 483 -> { "execute": "x-blockdev-change",
 484      "arguments": { "parent": "disk1",
 485                     "node": "new_node" } }
 486 <- { "return": {} }
 487
 488 Delete a quorum's node
 489 -> { "execute": "x-blockdev-change",
 490      "arguments": { "parent": "disk1",
 491                     "child": "children.1" } }
 492 <- { "return": {} }
 493
 494 blockdev-change-medium
 495 ----------------------
 496
 497 Changes the medium inserted into a block device by ejecting the current medium
 498 and loading a new image file which is inserted as the new medium.
 499
 500 Arguments:
 501
 502 - "device": block device name (deprecated, use @id instead)
 503             (json-string, optional)
 504 - "id": the name or QOM path of the guest device (json-string, optional)
 505 - "filename": filename of the new image (json-string)
 506 - "format": format of the new image (json-string, optional)
 507 - "read-only-mode": new read-only mode (json-string, optional)
 508           - Possible values: "retain" (default), "read-only", "read-write"
 509
 510 Examples:
 511
 512 1. Change a removable medium
 513
 514 -> { "execute": "blockdev-change-medium",
 515              "arguments": { "id": "ide0-1-0",
 516                             "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
 517                             "format": "raw" } }
 518 <- { "return": {} }
 519
 520 2. Load a read-only medium into a writable drive
 521
 522 -> { "execute": "blockdev-change-medium",
 523              "arguments": { "id": "floppyA",
 524                             "filename": "/srv/images/ro.img",
 525                             "format": "raw",
 526                             "read-only-mode": "retain" } }
 527
 528 <- { "error":
 529      { "class": "GenericError",
 530        "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
 531
 532 -> { "execute": "blockdev-change-medium",
 533              "arguments": { "id": "floppyA",
 534                             "filename": "/srv/images/ro.img",
 535                             "format": "raw",
 536                             "read-only-mode": "read-only" } }
 537
 538 <- { "return": {} }
 539
 540 trace-event-get-state
 541 ---------------------
 542
 543 Query the state of events.
 544
 545 Arguments:
 546
 547 - "name": Event name pattern (json-string).
 548 - "vcpu": The vCPU to query, any vCPU by default (json-int, optional).
 549
 550 An event is returned if:
 551 - its name matches the "name" pattern, and
 552 - if "vcpu" is given, the event has the "vcpu" property.
 553
 554 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
 555 returning their state on the specified vCPU. Special case: if "name" is an exact
 556 match, "vcpu" is given and the event does not have the "vcpu" property, an error
 557 is returned.
 558
 559 Example:
 560
 561 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
 562 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
 563
 564 trace-event-set-state
 565 ---------------------
 566
 567 Set the state of events.
 568
 569 Arguments:
 570
 571 - "name": Event name pattern (json-string).
 572 - "enable": Whether to enable or disable the event (json-bool).
 573 - "ignore-unavailable": Whether to ignore errors for events that cannot be
 574   changed (json-bool, optional).
 575 - "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional).
 576
 577 An event's state is modified if:
 578 - its name matches the "name" pattern, and
 579 - if "vcpu" is given, the event has the "vcpu" property.
 580
 581 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
 582 setting their state on the specified vCPU. Special case: if "name" is an exact
 583 match, "vcpu" is given and the event does not have the "vcpu" property, an error
 584 is returned.
 585
 586 Example:
 587
 588 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
 589 <- { "return": {} }
 590
 591 block-set-write-threshold
 592 ------------
 593
 594 Change the write threshold for a block drive. The threshold is an offset,
 595 thus must be non-negative. Default is no write threshold.
 596 Setting the threshold to zero disables it.
 597
 598 Arguments:
 599
 600 - "node-name": the node name in the block driver state graph (json-string)
 601 - "write-threshold": the write threshold in bytes (json-int)
 602
 603 Example:
 604
 605 -> { "execute": "block-set-write-threshold",
 606   "arguments": { "node-name": "mydev",
 607                  "write-threshold": 17179869184 } }
 608 <- { "return": {} }
 609
 610 Show rocker switch
 611 ------------------
 612
 613 Arguments:
 614
 615 - "name": switch name
 616
 617 Example:
 618
 619 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
 620 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
 621
 622 Show rocker switch ports
 623 ------------------------
 624
 625 Arguments:
 626
 627 - "name": switch name
 628
 629 Example:
 630
 631 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
 632 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
 633                   "autoneg": "off", "link-up": true, "speed": 10000},
 634                  {"duplex": "full", "enabled": true, "name": "sw1.2",
 635                   "autoneg": "off", "link-up": true, "speed": 10000}
 636    ]}
 637
 638 Show rocker switch OF-DPA flow tables
 639 -------------------------------------
 640
 641 Arguments:
 642
 643 - "name": switch name
 644 - "tbl-id": (optional) flow table ID
 645
 646 Example:
 647
 648 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
 649 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
 650                   "hits": 138,
 651                   "cookie": 0,
 652                   "action": {"goto-tbl": 10},
 653                   "mask": {"in-pport": 4294901760}
 654                  },
 655                  {...more...},
 656    ]}
 657
 658 Show rocker OF-DPA group tables
 659 -------------------------------
 660
 661 Arguments:
 662
 663 - "name": switch name
 664 - "type": (optional) group type
 665
 666 Example:
 667
 668 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
 669 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
 670                   "pop-vlan": 1, "id": 251723778},
 671                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
 672                   "pop-vlan": 1, "id": 251723776},
 673                  {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
 674                   "pop-vlan": 1, "id": 251658241},
 675                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
 676                   "pop-vlan": 1, "id": 251658240}
 677    ]}
 678
 679 query-gic-capabilities
 680 ---------------
 681
 682 Return a list of GICCapability objects, describing supported GIC
 683 (Generic Interrupt Controller) versions.
 684
 685 Arguments: None
 686
 687 Example:
 688
 689 -> { "execute": "query-gic-capabilities" }
 690 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
 691                 { "version": 3, "emulated": false, "kernel": true } ] }
 692
 693 Show existing/possible CPUs
 694 ---------------------------
 695
 696 Arguments: None.
 697
 698 Example for pseries machine type started with
 699 -smp 2,cores=2,maxcpus=4 -cpu POWER8:
 700
 701 -> { "execute": "query-hotpluggable-cpus" }
 702 <- {"return": [
 703      { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
 704        "vcpus-count": 1 },
 705      { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
 706        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
 707    ]}'
 708
 709 Example for pc machine type started with
 710 -smp 1,maxcpus=2:
 711     -> { "execute": "query-hotpluggable-cpus" }
 712     <- {"return": [
 713          {
 714             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
 715             "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
 716          },
 717          {
 718             "qom-path": "/machine/unattached/device[0]",
 719             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
 720             "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
 721          }
 722        ]}