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 quit
  57 ----
  58
  59 Quit the emulator.
  60
  61 Arguments: None.
  62
  63 Example:
  64
  65 -> { "execute": "quit" }
  66 <- { "return": {} }
  67
  68 eject
  69 -----
  70
  71 Eject a removable medium.
  72
  73 Arguments:
  74
  75 - "force": force ejection (json-bool, optional)
  76 - "device": block device name (deprecated, use @id instead)
  77             (json-string, optional)
  78 - "id": the name or QOM path of the guest device (json-string, optional)
  79
  80 Example:
  81
  82 -> { "execute": "eject", "arguments": { "id": "ide0-1-0" } }
  83 <- { "return": {} }
  84
  85 Note: The "force" argument defaults to false.
  86
  87 change
  88 ------
  89
  90 Change a removable medium or VNC configuration.
  91
  92 Arguments:
  93
  94 - "device": device name (json-string)
  95 - "target": filename or item (json-string)
  96 - "arg": additional argument (json-string, optional)
  97
  98 Examples:
  99
 100 1. Change a removable medium
 101
 102 -> { "execute": "change",
 103              "arguments": { "device": "ide1-cd0",
 104                             "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
 105 <- { "return": {} }
 106
 107 2. Change VNC password
 108
 109 -> { "execute": "change",
 110              "arguments": { "device": "vnc", "target": "password",
 111                             "arg": "foobar1" } }
 112 <- { "return": {} }
 113
 114 screendump
 115 ----------
 116
 117 Save screen into PPM image.
 118
 119 Arguments:
 120
 121 - "filename": file path (json-string)
 122
 123 Example:
 124
 125 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 126 <- { "return": {} }
 127
 128 stop
 129 ----
 130
 131 Stop the emulator.
 132
 133 Arguments: None.
 134
 135 Example:
 136
 137 -> { "execute": "stop" }
 138 <- { "return": {} }
 139
 140 cont
 141 ----
 142
 143 Resume emulation.
 144
 145 Arguments: None.
 146
 147 Example:
 148
 149 -> { "execute": "cont" }
 150 <- { "return": {} }
 151
 152 system_wakeup
 153 -------------
 154
 155 Wakeup guest from suspend.
 156
 157 Arguments: None.
 158
 159 Example:
 160
 161 -> { "execute": "system_wakeup" }
 162 <- { "return": {} }
 163
 164 system_reset
 165 ------------
 166
 167 Reset the system.
 168
 169 Arguments: None.
 170
 171 Example:
 172
 173 -> { "execute": "system_reset" }
 174 <- { "return": {} }
 175
 176 system_powerdown
 177 ----------------
 178
 179 Send system power down event.
 180
 181 Arguments: None.
 182
 183 Example:
 184
 185 -> { "execute": "system_powerdown" }
 186 <- { "return": {} }
 187
 188 device_add
 189 ----------
 190
 191 Add a device.
 192
 193 Arguments:
 194
 195 - "driver": the name of the new device's driver (json-string)
 196 - "bus": the device's parent bus (device tree path, json-string, optional)
 197 - "id": the device's ID, must be unique (json-string)
 198 - device properties
 199
 200 Example:
 201
 202 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
 203 <- { "return": {} }
 204
 205 Notes:
 206
 207 (1) For detailed information about this command, please refer to the
 208     'docs/qdev-device-use.txt' file.
 209
 210 (2) It's possible to list device properties by running QEMU with the
 211     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
 212
 213 device_del
 214 ----------
 215
 216 Remove a device.
 217
 218 Arguments:
 219
 220 - "id": the device's ID or QOM path (json-string)
 221
 222 Example:
 223
 224 -> { "execute": "device_del", "arguments": { "id": "net1" } }
 225 <- { "return": {} }
 226
 227 Example:
 228
 229 -> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
 230 <- { "return": {} }
 231
 232 send-key
 233 ----------
 234
 235 Send keys to VM.
 236
 237 Arguments:
 238
 239 keys array:
 240     - "key": key sequence (a json-array of key union values,
 241              union can be number or qcode enum)
 242
 243 - hold-time: time to delay key up events, milliseconds. Defaults to 100
 244              (json-int, optional)
 245
 246 Example:
 247
 248 -> { "execute": "send-key",
 249      "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
 250                               { "type": "qcode", "data": "alt" },
 251                               { "type": "qcode", "data": "delete" } ] } }
 252 <- { "return": {} }
 253
 254 cpu
 255 ---
 256
 257 Set the default CPU.
 258
 259 Arguments:
 260
 261 - "index": the CPU's index (json-int)
 262
 263 Example:
 264
 265 -> { "execute": "cpu", "arguments": { "index": 0 } }
 266 <- { "return": {} }
 267
 268 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 269
 270 cpu-add
 271 -------
 272
 273 Adds virtual cpu
 274
 275 Arguments:
 276
 277 - "id": cpu id (json-int)
 278
 279 Example:
 280
 281 -> { "execute": "cpu-add", "arguments": { "id": 2 } }
 282 <- { "return": {} }
 283
 284 memsave
 285 -------
 286
 287 Save to disk virtual memory dump starting at 'val' of size 'size'.
 288
 289 Arguments:
 290
 291 - "val": the starting address (json-int)
 292 - "size": the memory size, in bytes (json-int)
 293 - "filename": file path (json-string)
 294 - "cpu": virtual CPU index (json-int, optional)
 295
 296 Example:
 297
 298 -> { "execute": "memsave",
 299              "arguments": { "val": 10,
 300                             "size": 100,
 301                             "filename": "/tmp/virtual-mem-dump" } }
 302 <- { "return": {} }
 303
 304 pmemsave
 305 --------
 306
 307 Save to disk physical memory dump starting at 'val' of size 'size'.
 308
 309 Arguments:
 310
 311 - "val": the starting address (json-int)
 312 - "size": the memory size, in bytes (json-int)
 313 - "filename": file path (json-string)
 314
 315 Example:
 316
 317 -> { "execute": "pmemsave",
 318              "arguments": { "val": 10,
 319                             "size": 100,
 320                             "filename": "/tmp/physical-mem-dump" } }
 321 <- { "return": {} }
 322
 323 inject-nmi
 324 ----------
 325
 326 Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64).
 327
 328 Arguments: None.
 329
 330 Example:
 331
 332 -> { "execute": "inject-nmi" }
 333 <- { "return": {} }
 334
 335 Note: inject-nmi fails when the guest doesn't support injecting.
 336
 337 ringbuf-write
 338 -------------
 339
 340 Write to a ring buffer character device.
 341
 342 Arguments:
 343
 344 - "device": ring buffer character device name (json-string)
 345 - "data": data to write (json-string)
 346 - "format": data format (json-string, optional)
 347           - Possible values: "utf8" (default), "base64"
 348
 349 Example:
 350
 351 -> { "execute": "ringbuf-write",
 352                 "arguments": { "device": "foo",
 353                                "data": "abcdefgh",
 354                                "format": "utf8" } }
 355 <- { "return": {} }
 356
 357 ringbuf-read
 358 -------------
 359
 360 Read from a ring buffer character device.
 361
 362 Arguments:
 363
 364 - "device": ring buffer character device name (json-string)
 365 - "size": how many bytes to read at most (json-int)
 366           - Number of data bytes, not number of characters in encoded data
 367 - "format": data format (json-string, optional)
 368           - Possible values: "utf8" (default), "base64"
 369           - Naturally, format "utf8" works only when the ring buffer
 370             contains valid UTF-8 text.  Invalid UTF-8 sequences get
 371             replaced.  Bug: replacement doesn't work.  Bug: can screw
 372             up on encountering NUL characters, after the ring buffer
 373             lost data, and when reading stops because the size limit
 374             is reached.
 375
 376 Example:
 377
 378 -> { "execute": "ringbuf-read",
 379                 "arguments": { "device": "foo",
 380                                "size": 1000,
 381                                "format": "utf8" } }
 382 <- {"return": "abcdefgh"}
 383
 384 xen-save-devices-state
 385 -------
 386
 387 Save the state of all devices to file. The RAM and the block devices
 388 of the VM are not saved by this command.
 389
 390 Arguments:
 391
 392 - "filename": the file to save the state of the devices to as binary
 393 data. See xen-save-devices-state.txt for a description of the binary
 394 format.
 395
 396 Example:
 397
 398 -> { "execute": "xen-save-devices-state",
 399      "arguments": { "filename": "/tmp/save" } }
 400 <- { "return": {} }
 401
 402 xen-load-devices-state
 403 ----------------------
 404
 405 Load the state of all devices from file. The RAM and the block devices
 406 of the VM are not loaded by this command.
 407
 408 Arguments:
 409
 410 - "filename": the file to load the state of the devices from as binary
 411 data. See xen-save-devices-state.txt for a description of the binary
 412 format.
 413
 414 Example:
 415
 416 -> { "execute": "xen-load-devices-state",
 417      "arguments": { "filename": "/tmp/resume" } }
 418 <- { "return": {} }
 419
 420 xen-set-global-dirty-log
 421 -------
 422
 423 Enable or disable the global dirty log mode.
 424
 425 Arguments:
 426
 427 - "enable": Enable it or disable it.
 428
 429 Example:
 430
 431 -> { "execute": "xen-set-global-dirty-log",
 432      "arguments": { "enable": true } }
 433 <- { "return": {} }
 434
 435 migrate
 436 -------
 437
 438 Migrate to URI.
 439
 440 Arguments:
 441
 442 - "blk": block migration, full disk copy (json-bool, optional)
 443 - "inc": incremental disk copy (json-bool, optional)
 444 - "uri": Destination URI (json-string)
 445
 446 Example:
 447
 448 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
 449 <- { "return": {} }
 450
 451 Notes:
 452
 453 (1) The 'query-migrate' command should be used to check migration's progress
 454     and final result (this information is provided by the 'status' member)
 455 (2) All boolean arguments default to false
 456 (3) The user Monitor's "detach" argument is invalid in QMP and should not
 457     be used
 458
 459 migrate_cancel
 460 --------------
 461
 462 Cancel the current migration.
 463
 464 Arguments: None.
 465
 466 Example:
 467
 468 -> { "execute": "migrate_cancel" }
 469 <- { "return": {} }
 470
 471 migrate-incoming
 472 ----------------
 473
 474 Continue an incoming migration
 475
 476 Arguments:
 477
 478 - "uri": Source/listening URI (json-string)
 479
 480 Example:
 481
 482 -> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } }
 483 <- { "return": {} }
 484
 485 Notes:
 486
 487 (1) QEMU must be started with -incoming defer to allow migrate-incoming to
 488     be used
 489 (2) The uri format is the same as for -incoming
 490
 491 migrate-set-cache-size
 492 ----------------------
 493
 494 Set cache size to be used by XBZRLE migration, the cache size will be rounded
 495 down to the nearest power of 2
 496
 497 Arguments:
 498
 499 - "value": cache size in bytes (json-int)
 500
 501 Example:
 502
 503 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
 504 <- { "return": {} }
 505
 506 migrate-start-postcopy
 507 ----------------------
 508
 509 Switch an in-progress migration to postcopy mode. Ignored after the end of
 510 migration (or once already in postcopy).
 511
 512 Example:
 513 -> { "execute": "migrate-start-postcopy" }
 514 <- { "return": {} }
 515
 516 query-migrate-cache-size
 517 ------------------------
 518
 519 Show cache size to be used by XBZRLE migration
 520
 521 returns a json-object with the following information:
 522 - "size" : json-int
 523
 524 Example:
 525
 526 -> { "execute": "query-migrate-cache-size" }
 527 <- { "return": 67108864 }
 528
 529 migrate_set_speed
 530 -----------------
 531
 532 Set maximum speed for migrations.
 533
 534 Arguments:
 535
 536 - "value": maximum speed, in bytes per second (json-int)
 537
 538 Example:
 539
 540 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
 541 <- { "return": {} }
 542
 543 migrate_set_downtime
 544 --------------------
 545
 546 Set maximum tolerated downtime (in seconds) for migrations.
 547
 548 Arguments:
 549
 550 - "value": maximum downtime (json-number)
 551
 552 Example:
 553
 554 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
 555 <- { "return": {} }
 556
 557 client_migrate_info
 558 -------------------
 559
 560 Set migration information for remote display.  This makes the server
 561 ask the client to automatically reconnect using the new parameters
 562 once migration finished successfully.  Only implemented for SPICE.
 563
 564 Arguments:
 565
 566 - "protocol":     must be "spice" (json-string)
 567 - "hostname":     migration target hostname (json-string)
 568 - "port":         spice tcp port for plaintext channels (json-int, optional)
 569 - "tls-port":     spice tcp port for tls-secured channels (json-int, optional)
 570 - "cert-subject": server certificate subject (json-string, optional)
 571
 572 Example:
 573
 574 -> { "execute": "client_migrate_info",
 575      "arguments": { "protocol": "spice",
 576                     "hostname": "virt42.lab.kraxel.org",
 577                     "port": 1234 } }
 578 <- { "return": {} }
 579
 580 dump
 581
 582
 583 Dump guest memory to file. The file can be processed with crash or gdb.
 584
 585 Arguments:
 586
 587 - "paging": do paging to get guest's memory mapping (json-bool)
 588 - "protocol": destination file(started with "file:") or destination file
 589               descriptor (started with "fd:") (json-string)
 590 - "detach": if specified, command will return immediately, without waiting
 591             for the dump to finish. The user can track progress using
 592             "query-dump". (json-bool)
 593 - "begin": the starting physical address. It's optional, and should be specified
 594            with length together (json-int)
 595 - "length": the memory size, in bytes. It's optional, and should be specified
 596             with begin together (json-int)
 597 - "format": the format of guest memory dump. It's optional, and can be
 598             elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will
 599             conflict with paging and filter, ie. begin and length (json-string)
 600
 601 Example:
 602
 603 -> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
 604 <- { "return": {} }
 605
 606 Notes:
 607
 608 (1) All boolean arguments default to false
 609
 610 query-dump-guest-memory-capability
 611 ----------
 612
 613 Show available formats for 'dump-guest-memory'
 614
 615 Example:
 616
 617 -> { "execute": "query-dump-guest-memory-capability" }
 618 <- { "return": { "formats":
 619                     ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
 620
 621 query-dump
 622 ----------
 623
 624 Query background dump status.
 625
 626 Arguments: None.
 627
 628 Example:
 629
 630 -> { "execute": "query-dump" }
 631 <- { "return": { "status": "active", "completed": 1024000,
 632                  "total": 2048000 } }
 633
 634 dump-skeys
 635 ----------
 636
 637 Save guest storage keys to file.
 638
 639 Arguments:
 640
 641 - "filename": file path (json-string)
 642
 643 Example:
 644
 645 -> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } }
 646 <- { "return": {} }
 647
 648 netdev_add
 649 ----------
 650
 651 Add host network device.
 652
 653 Arguments:
 654
 655 - "type": the device type, "tap", "user", ... (json-string)
 656 - "id": the device's ID, must be unique (json-string)
 657 - device options
 658
 659 Example:
 660
 661 -> { "execute": "netdev_add",
 662      "arguments": { "type": "user", "id": "netdev1",
 663                     "dnssearch": "example.org" } }
 664 <- { "return": {} }
 665
 666 Note: The supported device options are the same ones supported by the '-netdev'
 667       command-line argument, which are listed in the '-help' output or QEMU's
 668       manual
 669
 670 netdev_del
 671 ----------
 672
 673 Remove host network device.
 674
 675 Arguments:
 676
 677 - "id": the device's ID, must be unique (json-string)
 678
 679 Example:
 680
 681 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
 682 <- { "return": {} }
 683
 684
 685 object-add
 686 ----------
 687
 688 Create QOM object.
 689
 690 Arguments:
 691
 692 - "qom-type": the object's QOM type, i.e. the class name (json-string)
 693 - "id": the object's ID, must be unique (json-string)
 694 - "props": a dictionary of object property values (optional, json-dict)
 695
 696 Example:
 697
 698 -> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1",
 699      "props": { "filename": "/dev/hwrng" } } }
 700 <- { "return": {} }
 701
 702 object-del
 703 ----------
 704
 705 Remove QOM object.
 706
 707 Arguments:
 708
 709 - "id": the object's ID (json-string)
 710
 711 Example:
 712
 713 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
 714 <- { "return": {} }
 715
 716
 717 block_resize
 718 ------------
 719
 720 Resize a block image while a guest is running.
 721
 722 Arguments:
 723
 724 - "device": the device's ID, must be unique (json-string)
 725 - "node-name": the node name in the block driver state graph (json-string)
 726 - "size": new size
 727
 728 Example:
 729
 730 -> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
 731 <- { "return": {} }
 732
 733 block-stream
 734 ------------
 735
 736 Copy data from a backing file into a block device.
 737
 738 Arguments:
 739
 740 - "job-id": Identifier for the newly-created block job. If omitted,
 741             the device name will be used. (json-string, optional)
 742 - "device": The device name or node-name of a root node (json-string)
 743 - "base": The file name of the backing image above which copying starts
 744           (json-string, optional)
 745 - "backing-file": The backing file string to write into the active layer. This
 746                   filename is not validated.
 747
 748                   If a pathname string is such that it cannot be resolved by
 749                   QEMU, that means that subsequent QMP or HMP commands must use
 750                   node-names for the image in question, as filename lookup
 751                   methods will fail.
 752
 753                   If not specified, QEMU will automatically determine the
 754                   backing file string to use, or error out if there is no
 755                   obvious choice.  Care should be taken when specifying the
 756                   string, to specify a valid filename or protocol.
 757                   (json-string, optional) (Since 2.1)
 758 - "speed":  the maximum speed, in bytes per second (json-int, optional)
 759 - "on-error": the action to take on an error (default 'report').  'stop' and
 760               'enospc' can only be used if the block device supports io-status.
 761               (json-string, optional) (Since 2.1)
 762
 763 Example:
 764
 765 -> { "execute": "block-stream", "arguments": { "device": "virtio0",
 766                                                "base": "/tmp/master.qcow2" } }
 767 <- { "return": {} }
 768
 769 block-commit
 770 ------------
 771
 772 Live commit of data from overlay image nodes into backing nodes - i.e., writes
 773 data between 'top' and 'base' into 'base'.
 774
 775 Arguments:
 776
 777 - "job-id": Identifier for the newly-created block job. If omitted,
 778             the device name will be used. (json-string, optional)
 779 - "device": The device name or node-name of a root node (json-string)
 780 - "base": The file name of the backing image to write data into.
 781           If not specified, this is the deepest backing image
 782           (json-string, optional)
 783 - "top":  The file name of the backing image within the image chain,
 784           which contains the topmost data to be committed down. If
 785           not specified, this is the active layer. (json-string, optional)
 786
 787 - backing-file:     The backing file string to write into the overlay
 788                     image of 'top'.  If 'top' is the active layer,
 789                     specifying a backing file string is an error. This
 790                     filename is not validated.
 791
 792                     If a pathname string is such that it cannot be
 793                     resolved by QEMU, that means that subsequent QMP or
 794                     HMP commands must use node-names for the image in
 795                     question, as filename lookup methods will fail.
 796
 797                     If not specified, QEMU will automatically determine
 798                     the backing file string to use, or error out if
 799                     there is no obvious choice. Care should be taken
 800                     when specifying the string, to specify a valid
 801                     filename or protocol.
 802                     (json-string, optional) (Since 2.1)
 803
 804           If top == base, that is an error.
 805           If top == active, the job will not be completed by itself,
 806           user needs to complete the job with the block-job-complete
 807           command after getting the ready event. (Since 2.0)
 808
 809           If the base image is smaller than top, then the base image
 810           will be resized to be the same size as top.  If top is
 811           smaller than the base image, the base will not be
 812           truncated.  If you want the base image size to match the
 813           size of the smaller top, you can safely truncate it
 814           yourself once the commit operation successfully completes.
 815           (json-string)
 816 - "speed":  the maximum speed, in bytes per second (json-int, optional)
 817
 818
 819 Example:
 820
 821 -> { "execute": "block-commit", "arguments": { "device": "virtio0",
 822                                               "top": "/tmp/snap1.qcow2" } }
 823 <- { "return": {} }
 824
 825 drive-backup
 826 ------------
 827
 828 Start a point-in-time copy of a block device to a new destination.  The
 829 status of ongoing drive-backup operations can be checked with
 830 query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
 831 The operation can be stopped before it has completed using the
 832 block-job-cancel command.
 833
 834 Arguments:
 835
 836 - "job-id": Identifier for the newly-created block job. If omitted,
 837             the device name will be used. (json-string, optional)
 838 - "device": the device name or node-name of a root node which should be copied.
 839             (json-string)
 840 - "target": the target of the new image. If the file exists, or if it is a
 841             device, the existing file/device will be used as the new
 842             destination.  If it does not exist, a new file will be created.
 843             (json-string)
 844 - "format": the format of the new destination, default is to probe if 'mode' is
 845             'existing', else the format of the source
 846             (json-string, optional)
 847 - "sync": what parts of the disk image should be copied to the destination;
 848   possibilities include "full" for all the disk, "top" for only the sectors
 849   allocated in the topmost image, "incremental" for only the dirty sectors in
 850   the bitmap, or "none" to only replicate new I/O (MirrorSyncMode).
 851 - "bitmap": dirty bitmap name for sync==incremental. Must be present if sync
 852             is "incremental", must NOT be present otherwise.
 853 - "mode": whether and how QEMU should create a new image
 854           (NewImageMode, optional, default 'absolute-paths')
 855 - "speed": the maximum speed, in bytes per second (json-int, optional)
 856 - "compress": true to compress data, if the target format supports it.
 857               (json-bool, optional, default false)
 858 - "on-source-error": the action to take on an error on the source, default
 859                      'report'.  'stop' and 'enospc' can only be used
 860                      if the block device supports io-status.
 861                      (BlockdevOnError, optional)
 862 - "on-target-error": the action to take on an error on the target, default
 863                      'report' (no limitations, since this applies to
 864                      a different block device than device).
 865                      (BlockdevOnError, optional)
 866
 867 Example:
 868 -> { "execute": "drive-backup", "arguments": { "device": "drive0",
 869                                                "sync": "full",
 870                                                "target": "backup.img" } }
 871 <- { "return": {} }
 872
 873 blockdev-backup
 874 ---------------
 875
 876 The device version of drive-backup: this command takes an existing named device
 877 as backup target.
 878
 879 Arguments:
 880
 881 - "job-id": Identifier for the newly-created block job. If omitted,
 882             the device name will be used. (json-string, optional)
 883 - "device": the device name or node-name of a root node which should be copied.
 884             (json-string)
 885 - "target": the name of the backup target device. (json-string)
 886 - "sync": what parts of the disk image should be copied to the destination;
 887           possibilities include "full" for all the disk, "top" for only the
 888           sectors allocated in the topmost image, or "none" to only replicate
 889           new I/O (MirrorSyncMode).
 890 - "speed": the maximum speed, in bytes per second (json-int, optional)
 891 - "compress": true to compress data, if the target format supports it.
 892               (json-bool, optional, default false)
 893 - "on-source-error": the action to take on an error on the source, default
 894                      'report'.  'stop' and 'enospc' can only be used
 895                      if the block device supports io-status.
 896                      (BlockdevOnError, optional)
 897 - "on-target-error": the action to take on an error on the target, default
 898                      'report' (no limitations, since this applies to
 899                      a different block device than device).
 900                      (BlockdevOnError, optional)
 901
 902 Example:
 903 -> { "execute": "blockdev-backup", "arguments": { "device": "src-id",
 904                                                   "sync": "full",
 905                                                   "target": "tgt-id" } }
 906 <- { "return": {} }
 907
 908 transaction
 909 -----------
 910
 911 Atomically operate on one or more block devices.  Operations that are
 912 currently supported:
 913
 914     - drive-backup
 915     - blockdev-backup
 916     - blockdev-snapshot-sync
 917     - blockdev-snapshot-internal-sync
 918     - abort
 919     - block-dirty-bitmap-add
 920     - block-dirty-bitmap-clear
 921
 922 Refer to the qemu/qapi-schema.json file for minimum required QEMU
 923 versions for these operations.  A list of dictionaries is accepted,
 924 that contains the actions to be performed.  If there is any failure
 925 performing any of the operations, all operations for the group are
 926 abandoned.
 927
 928 For external snapshots, the dictionary contains the device, the file to use for
 929 the new snapshot, and the format.  The default format, if not specified, is
 930 qcow2.
 931
 932 Each new snapshot defaults to being created by QEMU (wiping any
 933 contents if the file already exists), but it is also possible to reuse
 934 an externally-created file.  In the latter case, you should ensure that
 935 the new image file has the same contents as the current one; QEMU cannot
 936 perform any meaningful check.  Typically this is achieved by using the
 937 current image file as the backing file for the new image.
 938
 939 On failure, the original disks pre-snapshot attempt will be used.
 940
 941 For internal snapshots, the dictionary contains the device and the snapshot's
 942 name.  If an internal snapshot matching name already exists, the request will
 943 be rejected.  Only some image formats support it, for example, qcow2, rbd,
 944 and sheepdog.
 945
 946 On failure, qemu will try delete the newly created internal snapshot in the
 947 transaction.  When an I/O error occurs during deletion, the user needs to fix
 948 it later with qemu-img or other command.
 949
 950 Arguments:
 951
 952 actions array:
 953     - "type": the operation to perform (json-string).  Possible
 954               values: "drive-backup", "blockdev-backup",
 955                       "blockdev-snapshot-sync",
 956                       "blockdev-snapshot-internal-sync",
 957                       "abort", "block-dirty-bitmap-add",
 958                       "block-dirty-bitmap-clear"
 959     - "data": a dictionary.  The contents depend on the value
 960       of "type".  When "type" is "blockdev-snapshot-sync":
 961       - "device": device name to snapshot (json-string)
 962       - "node-name": graph node name to snapshot (json-string)
 963       - "snapshot-file": name of new image file (json-string)
 964       - "snapshot-node-name": graph node name of the new snapshot (json-string)
 965       - "format": format of new image (json-string, optional)
 966       - "mode": whether and how QEMU should create the snapshot file
 967         (NewImageMode, optional, default "absolute-paths")
 968       When "type" is "blockdev-snapshot-internal-sync":
 969       - "device": the device name or node-name of a root node to snapshot
 970                   (json-string)
 971       - "name": name of the new snapshot (json-string)
 972
 973 Example:
 974
 975 -> { "execute": "transaction",
 976      "arguments": { "actions": [
 977          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
 978                                          "snapshot-file": "/some/place/my-image",
 979                                          "format": "qcow2" } },
 980          { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
 981                                          "snapshot-file": "/some/place/my-image2",
 982                                          "snapshot-node-name": "node3432",
 983                                          "mode": "existing",
 984                                          "format": "qcow2" } },
 985          { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
 986                                          "snapshot-file": "/some/place/my-image2",
 987                                          "mode": "existing",
 988                                          "format": "qcow2" } },
 989          { "type": "blockdev-snapshot-internal-sync", "data" : {
 990                                          "device": "ide-hd2",
 991                                          "name": "snapshot0" } } ] } }
 992 <- { "return": {} }
 993
 994 block-dirty-bitmap-add
 995 ----------------------
 996 Since 2.4
 997
 998 Create a dirty bitmap with a name on the device, and start tracking the writes.
 999
1000 Arguments:
1001
1002 - "node": device/node on which to create dirty bitmap (json-string)
1003 - "name": name of the new dirty bitmap (json-string)
1004 - "granularity": granularity to track writes with (int, optional)
1005
1006 Example:
1007
1008 -> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0",
1009                                                    "name": "bitmap0" } }
1010 <- { "return": {} }
1011
1012 block-dirty-bitmap-remove
1013 -------------------------
1014 Since 2.4
1015
1016 Stop write tracking and remove the dirty bitmap that was created with
1017 block-dirty-bitmap-add.
1018
1019 Arguments:
1020
1021 - "node": device/node on which to remove dirty bitmap (json-string)
1022 - "name": name of the dirty bitmap to remove (json-string)
1023
1024 Example:
1025
1026 -> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0",
1027                                                       "name": "bitmap0" } }
1028 <- { "return": {} }
1029
1030 block-dirty-bitmap-clear
1031 ------------------------
1032 Since 2.4
1033
1034 Reset the dirty bitmap associated with a node so that an incremental backup
1035 from this point in time forward will only backup clusters modified after this
1036 clear operation.
1037
1038 Arguments:
1039
1040 - "node": device/node on which to remove dirty bitmap (json-string)
1041 - "name": name of the dirty bitmap to remove (json-string)
1042
1043 Example:
1044
1045 -> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0",
1046                                                            "name": "bitmap0" } }
1047 <- { "return": {} }
1048
1049 blockdev-snapshot-sync
1050 ----------------------
1051
1052 Synchronous snapshot of a block device. snapshot-file specifies the
1053 target of the new image. If the file exists, or if it is a device, the
1054 snapshot will be created in the existing file/device. If does not
1055 exist, a new file will be created. format specifies the format of the
1056 snapshot image, default is qcow2.
1057
1058 Arguments:
1059
1060 - "device": device name to snapshot (json-string)
1061 - "node-name": graph node name to snapshot (json-string)
1062 - "snapshot-file": name of new image file (json-string)
1063 - "snapshot-node-name": graph node name of the new snapshot (json-string)
1064 - "mode": whether and how QEMU should create the snapshot file
1065   (NewImageMode, optional, default "absolute-paths")
1066 - "format": format of new image (json-string, optional)
1067
1068 Example:
1069
1070 -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
1071                                                          "snapshot-file":
1072                                                         "/some/place/my-image",
1073                                                         "format": "qcow2" } }
1074 <- { "return": {} }
1075
1076 blockdev-snapshot
1077 -----------------
1078 Since 2.5
1079
1080 Create a snapshot, by installing 'node' as the backing image of
1081 'overlay'. Additionally, if 'node' is associated with a block
1082 device, the block device changes to using 'overlay' as its new active
1083 image.
1084
1085 Arguments:
1086
1087 - "node": device that will have a snapshot created (json-string)
1088 - "overlay": device that will have 'node' as its backing image (json-string)
1089
1090 Example:
1091
1092 -> { "execute": "blockdev-add",
1093                 "arguments": { "options": { "driver": "qcow2",
1094                                             "node-name": "node1534",
1095                                             "file": { "driver": "file",
1096                                                       "filename": "hd1.qcow2" },
1097                                             "backing": "" } } }
1098
1099 <- { "return": {} }
1100
1101 -> { "execute": "blockdev-snapshot", "arguments": { "node": "ide-hd0",
1102                                                     "overlay": "node1534" } }
1103 <- { "return": {} }
1104
1105 blockdev-snapshot-internal-sync
1106 -------------------------------
1107
1108 Synchronously take an internal snapshot of a block device when the format of
1109 image used supports it.  If the name is an empty string, or a snapshot with
1110 name already exists, the operation will fail.
1111
1112 Arguments:
1113
1114 - "device": the device name or node-name of a root node to snapshot
1115             (json-string)
1116 - "name": name of the new snapshot (json-string)
1117
1118 Example:
1119
1120 -> { "execute": "blockdev-snapshot-internal-sync",
1121                 "arguments": { "device": "ide-hd0",
1122                                "name": "snapshot0" }
1123    }
1124 <- { "return": {} }
1125
1126 blockdev-snapshot-delete-internal-sync
1127 --------------------------------------
1128
1129 Synchronously delete an internal snapshot of a block device when the format of
1130 image used supports it.  The snapshot is identified by name or id or both.  One
1131 of name or id is required.  If the snapshot is not found, the operation will
1132 fail.
1133
1134 Arguments:
1135
1136 - "device": the device name or node-name of a root node (json-string)
1137 - "id": ID of the snapshot (json-string, optional)
1138 - "name": name of the snapshot (json-string, optional)
1139
1140 Example:
1141
1142 -> { "execute": "blockdev-snapshot-delete-internal-sync",
1143                 "arguments": { "device": "ide-hd0",
1144                                "name": "snapshot0" }
1145    }
1146 <- { "return": {
1147                    "id": "1",
1148                    "name": "snapshot0",
1149                    "vm-state-size": 0,
1150                    "date-sec": 1000012,
1151                    "date-nsec": 10,
1152                    "vm-clock-sec": 100,
1153                    "vm-clock-nsec": 20
1154      }
1155    }
1156
1157 drive-mirror
1158 ------------
1159
1160 Start mirroring a block device's writes to a new destination. target
1161 specifies the target of the new image. If the file exists, or if it is
1162 a device, it will be used as the new destination for writes. If it does not
1163 exist, a new file will be created. format specifies the format of the
1164 mirror image, default is to probe if mode='existing', else the format
1165 of the source.
1166
1167 Arguments:
1168
1169 - "job-id": Identifier for the newly-created block job. If omitted,
1170             the device name will be used. (json-string, optional)
1171 - "device": the device name or node-name of a root node whose writes should be
1172             mirrored. (json-string)
1173 - "target": name of new image file (json-string)
1174 - "format": format of new image (json-string, optional)
1175 - "node-name": the name of the new block driver state in the node graph
1176                (json-string, optional)
1177 - "replaces": the block driver node name to replace when finished
1178               (json-string, optional)
1179 - "mode": how an image file should be created into the target
1180   file/device (NewImageMode, optional, default 'absolute-paths')
1181 - "speed": maximum speed of the streaming job, in bytes per second
1182   (json-int)
1183 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1184 - "buf-size": maximum amount of data in flight from source to target, in bytes
1185   (json-int, default 10M)
1186 - "sync": what parts of the disk image should be copied to the destination;
1187   possibilities include "full" for all the disk, "top" for only the sectors
1188   allocated in the topmost image, or "none" to only replicate new I/O
1189   (MirrorSyncMode).
1190 - "on-source-error": the action to take on an error on the source
1191   (BlockdevOnError, default 'report')
1192 - "on-target-error": the action to take on an error on the target
1193   (BlockdevOnError, default 'report')
1194 - "unmap": whether the target sectors should be discarded where source has only
1195   zeroes. (json-bool, optional, default true)
1196
1197 The default value of the granularity is the image cluster size clamped
1198 between 4096 and 65536, if the image format defines one.  If the format
1199 does not define a cluster size, the default value of the granularity
1200 is 65536.
1201
1202
1203 Example:
1204
1205 -> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
1206                                                "target": "/some/place/my-image",
1207                                                "sync": "full",
1208                                                "format": "qcow2" } }
1209 <- { "return": {} }
1210
1211 blockdev-mirror
1212 ------------
1213
1214 Start mirroring a block device's writes to another block device. target
1215 specifies the target of mirror operation.
1216
1217 Arguments:
1218
1219 - "job-id": Identifier for the newly-created block job. If omitted,
1220             the device name will be used. (json-string, optional)
1221 - "device": The device name or node-name of a root node whose writes should be
1222             mirrored (json-string)
1223 - "target": device name to mirror to (json-string)
1224 - "replaces": the block driver node name to replace when finished
1225               (json-string, optional)
1226 - "speed": maximum speed of the streaming job, in bytes per second
1227   (json-int)
1228 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1229 - "buf_size": maximum amount of data in flight from source to target, in bytes
1230   (json-int, default 10M)
1231 - "sync": what parts of the disk image should be copied to the destination;
1232   possibilities include "full" for all the disk, "top" for only the sectors
1233   allocated in the topmost image, or "none" to only replicate new I/O
1234   (MirrorSyncMode).
1235 - "on-source-error": the action to take on an error on the source
1236   (BlockdevOnError, default 'report')
1237 - "on-target-error": the action to take on an error on the target
1238   (BlockdevOnError, default 'report')
1239
1240 The default value of the granularity is the image cluster size clamped
1241 between 4096 and 65536, if the image format defines one.  If the format
1242 does not define a cluster size, the default value of the granularity
1243 is 65536.
1244
1245 Example:
1246
1247 -> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0",
1248                                                   "target": "target0",
1249                                                   "sync": "full" } }
1250 <- { "return": {} }
1251
1252 change-backing-file
1253 -------------------
1254 Since: 2.1
1255
1256 Change the backing file in the image file metadata.  This does not cause
1257 QEMU to reopen the image file to reparse the backing filename (it may,
1258 however, perform a reopen to change permissions from r/o -> r/w -> r/o,
1259 if needed). The new backing file string is written into the image file
1260 metadata, and the QEMU internal strings are updated.
1261
1262 Arguments:
1263
1264 - "image-node-name":    The name of the block driver state node of the
1265                         image to modify.  The "device" is argument is used to
1266                         verify "image-node-name" is in the chain described by
1267                         "device".
1268                         (json-string, optional)
1269
1270 - "device":             The device name or node-name of the root node that owns
1271                         image-node-name.
1272                         (json-string)
1273
1274 - "backing-file":       The string to write as the backing file.  This string is
1275                         not validated, so care should be taken when specifying
1276                         the string or the image chain may not be able to be
1277                         reopened again.
1278                         (json-string)
1279
1280 Returns: Nothing on success
1281          If "device" does not exist or cannot be determined, DeviceNotFound
1282
1283 balloon
1284 -------
1285
1286 Request VM to change its memory allocation (in bytes).
1287
1288 Arguments:
1289
1290 - "value": New memory allocation (json-int)
1291
1292 Example:
1293
1294 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1295 <- { "return": {} }
1296
1297 set_link
1298 --------
1299
1300 Change the link status of a network adapter.
1301
1302 Arguments:
1303
1304 - "name": network device name (json-string)
1305 - "up": status is up (json-bool)
1306
1307 Example:
1308
1309 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1310 <- { "return": {} }
1311
1312 getfd
1313 -----
1314
1315 Receive a file descriptor via SCM rights and assign it a name.
1316
1317 Arguments:
1318
1319 - "fdname": file descriptor name (json-string)
1320
1321 Example:
1322
1323 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1324 <- { "return": {} }
1325
1326 Notes:
1327
1328 (1) If the name specified by the "fdname" argument already exists,
1329     the file descriptor assigned to it will be closed and replaced
1330     by the received file descriptor.
1331 (2) The 'closefd' command can be used to explicitly close the file
1332     descriptor when it is no longer needed.
1333
1334 closefd
1335 -------
1336
1337 Close a file descriptor previously passed via SCM rights.
1338
1339 Arguments:
1340
1341 - "fdname": file descriptor name (json-string)
1342
1343 Example:
1344
1345 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1346 <- { "return": {} }
1347
1348 add-fd
1349 -------
1350
1351 Add a file descriptor, that was passed via SCM rights, to an fd set.
1352
1353 Arguments:
1354
1355 - "fdset-id": The ID of the fd set to add the file descriptor to.
1356               (json-int, optional)
1357 - "opaque": A free-form string that can be used to describe the fd.
1358             (json-string, optional)
1359
1360 Return a json-object with the following information:
1361
1362 - "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1363 - "fd": The file descriptor that was received via SCM rights and added to the
1364         fd set. (json-int)
1365
1366 Example:
1367
1368 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1369 <- { "return": { "fdset-id": 1, "fd": 3 } }
1370
1371 Notes:
1372
1373 (1) The list of fd sets is shared by all monitor connections.
1374 (2) If "fdset-id" is not specified, a new fd set will be created.
1375
1376 remove-fd
1377 ---------
1378
1379 Remove a file descriptor from an fd set.
1380
1381 Arguments:
1382
1383 - "fdset-id": The ID of the fd set that the file descriptor belongs to.
1384               (json-int)
1385 - "fd": The file descriptor that is to be removed. (json-int, optional)
1386
1387 Example:
1388
1389 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1390 <- { "return": {} }
1391
1392 Notes:
1393
1394 (1) The list of fd sets is shared by all monitor connections.
1395 (2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1396     removed.
1397
1398 query-fdsets
1399 -------------
1400
1401 Return information describing all fd sets.
1402
1403 Arguments: None
1404
1405 Example:
1406
1407 -> { "execute": "query-fdsets" }
1408 <- { "return": [
1409        {
1410          "fds": [
1411            {
1412              "fd": 30,
1413              "opaque": "rdonly:/path/to/file"
1414            },
1415            {
1416              "fd": 24,
1417              "opaque": "rdwr:/path/to/file"
1418            }
1419          ],
1420          "fdset-id": 1
1421        },
1422        {
1423          "fds": [
1424            {
1425              "fd": 28
1426            },
1427            {
1428              "fd": 29
1429            }
1430          ],
1431          "fdset-id": 0
1432        }
1433      ]
1434    }
1435
1436 Note: The list of fd sets is shared by all monitor connections.
1437
1438 block_passwd
1439 ------------
1440
1441 Set the password of encrypted block devices.
1442
1443 Arguments:
1444
1445 - "device": device name (json-string)
1446 - "node-name": name in the block driver state graph (json-string)
1447 - "password": password (json-string)
1448
1449 Example:
1450
1451 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1452                                                "password": "12345" } }
1453 <- { "return": {} }
1454
1455 block_set_io_throttle
1456 ------------
1457
1458 Change I/O throttle limits for a block drive.
1459
1460 Arguments:
1461
1462 - "device": block device name (deprecated, use @id instead)
1463             (json-string, optional)
1464 - "id": the name or QOM path of the guest device (json-string, optional)
1465 - "bps": total throughput limit in bytes per second (json-int)
1466 - "bps_rd": read throughput limit in bytes per second (json-int)
1467 - "bps_wr": write throughput limit in bytes per second (json-int)
1468 - "iops": total I/O operations per second (json-int)
1469 - "iops_rd": read I/O operations per second (json-int)
1470 - "iops_wr": write I/O operations per second (json-int)
1471 - "bps_max": total throughput limit during bursts, in bytes (json-int, optional)
1472 - "bps_rd_max": read throughput limit during bursts, in bytes (json-int, optional)
1473 - "bps_wr_max": write throughput limit during bursts, in bytes (json-int, optional)
1474 - "iops_max": total I/O operations per second during bursts (json-int, optional)
1475 - "iops_rd_max": read I/O operations per second during bursts (json-int, optional)
1476 - "iops_wr_max": write I/O operations per second during bursts (json-int, optional)
1477 - "bps_max_length": maximum length of the @bps_max burst period, in seconds (json-int, optional)
1478 - "bps_rd_max_length": maximum length of the @bps_rd_max burst period, in seconds (json-int, optional)
1479 - "bps_wr_max_length": maximum length of the @bps_wr_max burst period, in seconds (json-int, optional)
1480 - "iops_max_length": maximum length of the @iops_max burst period, in seconds (json-int, optional)
1481 - "iops_rd_max_length": maximum length of the @iops_rd_max burst period, in seconds (json-int, optional)
1482 - "iops_wr_max_length": maximum length of the @iops_wr_max burst period, in seconds (json-int, optional)
1483 - "iops_size":  I/O size in bytes when limiting (json-int, optional)
1484 - "group": throttle group name (json-string, optional)
1485
1486 Example:
1487
1488 -> { "execute": "block_set_io_throttle", "arguments": { "id": "ide0-1-0",
1489                                                "bps": 1000000,
1490                                                "bps_rd": 0,
1491                                                "bps_wr": 0,
1492                                                "iops": 0,
1493                                                "iops_rd": 0,
1494                                                "iops_wr": 0,
1495                                                "bps_max": 8000000,
1496                                                "bps_rd_max": 0,
1497                                                "bps_wr_max": 0,
1498                                                "iops_max": 0,
1499                                                "iops_rd_max": 0,
1500                                                "iops_wr_max": 0,
1501                                                "bps_max_length": 60,
1502                                                "iops_size": 0 } }
1503 <- { "return": {} }
1504
1505 set_password
1506 ------------
1507
1508 Set the password for vnc/spice protocols.
1509
1510 Arguments:
1511
1512 - "protocol": protocol name (json-string)
1513 - "password": password (json-string)
1514 - "connected": [ keep | disconnect | fail ] (json-string, optional)
1515
1516 Example:
1517
1518 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
1519                                                "password": "secret" } }
1520 <- { "return": {} }
1521
1522 expire_password
1523 ---------------
1524
1525 Set the password expire time for vnc/spice protocols.
1526
1527 Arguments:
1528
1529 - "protocol": protocol name (json-string)
1530 - "time": [ now | never | +secs | secs ] (json-string)
1531
1532 Example:
1533
1534 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
1535                                                   "time": "+60" } }
1536 <- { "return": {} }
1537
1538 add_client
1539 ----------
1540
1541 Add a graphics client
1542
1543 Arguments:
1544
1545 - "protocol": protocol name (json-string)
1546 - "fdname": file descriptor name (json-string)
1547 - "skipauth": whether to skip authentication (json-bool, optional)
1548 - "tls": whether to perform TLS (json-bool, optional)
1549
1550 Example:
1551
1552 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
1553                                              "fdname": "myclient" } }
1554 <- { "return": {} }
1555
1556 qmp_capabilities
1557 ----------------
1558
1559 Enable QMP capabilities.
1560
1561 Arguments: None.
1562
1563 Example:
1564
1565 -> { "execute": "qmp_capabilities" }
1566 <- { "return": {} }
1567
1568 Note: This command must be issued before issuing any other command.
1569
1570 human-monitor-command
1571 ---------------------
1572
1573 Execute a Human Monitor command.
1574
1575 Arguments:
1576
1577 - command-line: the command name and its arguments, just like the
1578                 Human Monitor's shell (json-string)
1579 - cpu-index: select the CPU number to be used by commands which access CPU
1580              data, like 'info registers'. The Monitor selects CPU 0 if this
1581              argument is not provided (json-int, optional)
1582
1583 Example:
1584
1585 -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
1586 <- { "return": "kvm support: enabled\r\n" }
1587
1588 Notes:
1589
1590 (1) The Human Monitor is NOT an stable interface, this means that command
1591     names, arguments and responses can change or be removed at ANY time.
1592     Applications that rely on long term stability guarantees should NOT
1593     use this command
1594
1595 (2) Limitations:
1596
1597     o This command is stateless, this means that commands that depend
1598       on state information (such as getfd) might not work
1599
1600     o Commands that prompt the user for data (eg. 'cont' when the block
1601       device is encrypted) don't currently work
1602
1603 3. Query Commands
1604 =================
1605
1606
1607 query-version
1608 -------------
1609
1610 Show QEMU version.
1611
1612 Return a json-object with the following information:
1613
1614 - "qemu": A json-object containing three integer values:
1615     - "major": QEMU's major version (json-int)
1616     - "minor": QEMU's minor version (json-int)
1617     - "micro": QEMU's micro version (json-int)
1618 - "package": package's version (json-string)
1619
1620 Example:
1621
1622 -> { "execute": "query-version" }
1623 <- {
1624       "return":{
1625          "qemu":{
1626             "major":0,
1627             "minor":11,
1628             "micro":5
1629          },
1630          "package":""
1631       }
1632    }
1633
1634 query-commands
1635 --------------
1636
1637 List QMP available commands.
1638
1639 Each command is represented by a json-object, the returned value is a json-array
1640 of all commands.
1641
1642 Each json-object contain:
1643
1644 - "name": command's name (json-string)
1645
1646 Example:
1647
1648 -> { "execute": "query-commands" }
1649 <- {
1650       "return":[
1651          {
1652             "name":"query-balloon"
1653          },
1654          {
1655             "name":"system_powerdown"
1656          }
1657       ]
1658    }
1659
1660 Note: This example has been shortened as the real response is too long.
1661
1662 query-events
1663 --------------
1664
1665 List QMP available events.
1666
1667 Each event is represented by a json-object, the returned value is a json-array
1668 of all events.
1669
1670 Each json-object contains:
1671
1672 - "name": event's name (json-string)
1673
1674 Example:
1675
1676 -> { "execute": "query-events" }
1677 <- {
1678       "return":[
1679          {
1680             "name":"SHUTDOWN"
1681          },
1682          {
1683             "name":"RESET"
1684          }
1685       ]
1686    }
1687
1688 Note: This example has been shortened as the real response is too long.
1689
1690 query-qmp-schema
1691 ----------------
1692
1693 Return the QMP wire schema.  The returned value is a json-array of
1694 named schema entities.  Entities are commands, events and various
1695 types.  See docs/qapi-code-gen.txt for information on their structure
1696 and intended use.
1697
1698 query-chardev
1699 -------------
1700
1701 Each device is represented by a json-object. The returned value is a json-array
1702 of all devices.
1703
1704 Each json-object contain the following:
1705
1706 - "label": device's label (json-string)
1707 - "filename": device's file (json-string)
1708 - "frontend-open": open/closed state of the frontend device attached to this
1709                    backend (json-bool)
1710
1711 Example:
1712
1713 -> { "execute": "query-chardev" }
1714 <- {
1715       "return": [
1716          {
1717             "label": "charchannel0",
1718             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
1719             "frontend-open": false
1720          },
1721          {
1722             "label": "charmonitor",
1723             "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
1724             "frontend-open": true
1725          },
1726          {
1727             "label": "charserial0",
1728             "filename": "pty:/dev/pts/2",
1729             "frontend-open": true
1730          }
1731       ]
1732    }
1733
1734 query-chardev-backends
1735 -------------
1736
1737 List available character device backends.
1738
1739 Each backend is represented by a json-object, the returned value is a json-array
1740 of all backends.
1741
1742 Each json-object contains:
1743
1744 - "name": backend name (json-string)
1745
1746 Example:
1747
1748 -> { "execute": "query-chardev-backends" }
1749 <- {
1750       "return":[
1751          {
1752             "name":"udp"
1753          },
1754          {
1755             "name":"tcp"
1756          },
1757          {
1758             "name":"unix"
1759          },
1760          {
1761             "name":"spiceport"
1762          }
1763       ]
1764    }
1765
1766 query-block
1767 -----------
1768
1769 Show the block devices.
1770
1771 Each block device information is stored in a json-object and the returned value
1772 is a json-array of all devices.
1773
1774 Each json-object contain the following:
1775
1776 - "device": device name (json-string)
1777 - "type": device type (json-string)
1778          - deprecated, retained for backward compatibility
1779          - Possible values: "unknown"
1780 - "removable": true if the device is removable, false otherwise (json-bool)
1781 - "locked": true if the device is locked, false otherwise (json-bool)
1782 - "tray_open": only present if removable, true if the device has a tray,
1783                and it is open (json-bool)
1784 - "inserted": only present if the device is inserted, it is a json-object
1785    containing the following:
1786          - "file": device file name (json-string)
1787          - "ro": true if read-only, false otherwise (json-bool)
1788          - "drv": driver format name (json-string)
1789              - Possible values: "blkdebug", "bochs", "cloop", "dmg",
1790                                 "file", "file", "ftp", "ftps", "host_cdrom",
1791                                 "host_device", "http", "https",
1792                                 "nbd", "parallels", "qcow", "qcow2", "raw",
1793                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1794          - "backing_file": backing file name (json-string, optional)
1795          - "backing_file_depth": number of files in the backing file chain (json-int)
1796          - "encrypted": true if encrypted, false otherwise (json-bool)
1797          - "bps": limit total bytes per second (json-int)
1798          - "bps_rd": limit read bytes per second (json-int)
1799          - "bps_wr": limit write bytes per second (json-int)
1800          - "iops": limit total I/O operations per second (json-int)
1801          - "iops_rd": limit read operations per second (json-int)
1802          - "iops_wr": limit write operations per second (json-int)
1803          - "bps_max":  total max in bytes (json-int)
1804          - "bps_rd_max":  read max in bytes (json-int)
1805          - "bps_wr_max":  write max in bytes (json-int)
1806          - "iops_max":  total I/O operations max (json-int)
1807          - "iops_rd_max":  read I/O operations max (json-int)
1808          - "iops_wr_max":  write I/O operations max (json-int)
1809          - "iops_size": I/O size when limiting by iops (json-int)
1810          - "detect_zeroes": detect and optimize zero writing (json-string)
1811              - Possible values: "off", "on", "unmap"
1812          - "write_threshold": write offset threshold in bytes, a event will be
1813                               emitted if crossed. Zero if disabled (json-int)
1814          - "image": the detail of the image, it is a json-object containing
1815             the following:
1816              - "filename": image file name (json-string)
1817              - "format": image format (json-string)
1818              - "virtual-size": image capacity in bytes (json-int)
1819              - "dirty-flag": true if image is not cleanly closed, not present
1820                              means clean (json-bool, optional)
1821              - "actual-size": actual size on disk in bytes of the image, not
1822                               present when image does not support thin
1823                               provision (json-int, optional)
1824              - "cluster-size": size of a cluster in bytes, not present if image
1825                                format does not support it (json-int, optional)
1826              - "encrypted": true if the image is encrypted, not present means
1827                             false or the image format does not support
1828                             encryption (json-bool, optional)
1829              - "backing_file": backing file name, not present means no backing
1830                                file is used or the image format does not
1831                                support backing file chain
1832                                (json-string, optional)
1833              - "full-backing-filename": full path of the backing file, not
1834                                         present if it equals backing_file or no
1835                                         backing file is used
1836                                         (json-string, optional)
1837              - "backing-filename-format": the format of the backing file, not
1838                                           present means unknown or no backing
1839                                           file (json-string, optional)
1840              - "snapshots": the internal snapshot info, it is an optional list
1841                 of json-object containing the following:
1842                  - "id": unique snapshot id (json-string)
1843                  - "name": snapshot name (json-string)
1844                  - "vm-state-size": size of the VM state in bytes (json-int)
1845                  - "date-sec": UTC date of the snapshot in seconds (json-int)
1846                  - "date-nsec": fractional part in nanoseconds to be used with
1847                                 date-sec (json-int)
1848                  - "vm-clock-sec": VM clock relative to boot in seconds
1849                                    (json-int)
1850                  - "vm-clock-nsec": fractional part in nanoseconds to be used
1851                                     with vm-clock-sec (json-int)
1852              - "backing-image": the detail of the backing image, it is an
1853                                 optional json-object only present when a
1854                                 backing image present for this image
1855
1856 - "io-status": I/O operation status, only present if the device supports it
1857                and the VM is configured to stop on errors. It's always reset
1858                to "ok" when the "cont" command is issued (json_string, optional)
1859              - Possible values: "ok", "failed", "nospace"
1860
1861 Example:
1862
1863 -> { "execute": "query-block" }
1864 <- {
1865       "return":[
1866          {
1867             "io-status": "ok",
1868             "device":"ide0-hd0",
1869             "locked":false,
1870             "removable":false,
1871             "inserted":{
1872                "ro":false,
1873                "drv":"qcow2",
1874                "encrypted":false,
1875                "file":"disks/test.qcow2",
1876                "backing_file_depth":1,
1877                "bps":1000000,
1878                "bps_rd":0,
1879                "bps_wr":0,
1880                "iops":1000000,
1881                "iops_rd":0,
1882                "iops_wr":0,
1883                "bps_max": 8000000,
1884                "bps_rd_max": 0,
1885                "bps_wr_max": 0,
1886                "iops_max": 0,
1887                "iops_rd_max": 0,
1888                "iops_wr_max": 0,
1889                "iops_size": 0,
1890                "detect_zeroes": "on",
1891                "write_threshold": 0,
1892                "image":{
1893                   "filename":"disks/test.qcow2",
1894                   "format":"qcow2",
1895                   "virtual-size":2048000,
1896                   "backing_file":"base.qcow2",
1897                   "full-backing-filename":"disks/base.qcow2",
1898                   "backing-filename-format":"qcow2",
1899                   "snapshots":[
1900                      {
1901                         "id": "1",
1902                         "name": "snapshot1",
1903                         "vm-state-size": 0,
1904                         "date-sec": 10000200,
1905                         "date-nsec": 12,
1906                         "vm-clock-sec": 206,
1907                         "vm-clock-nsec": 30
1908                      }
1909                   ],
1910                   "backing-image":{
1911                       "filename":"disks/base.qcow2",
1912                       "format":"qcow2",
1913                       "virtual-size":2048000
1914                   }
1915                }
1916             },
1917             "type":"unknown"
1918          },
1919          {
1920             "io-status": "ok",
1921             "device":"ide1-cd0",
1922             "locked":false,
1923             "removable":true,
1924             "type":"unknown"
1925          },
1926          {
1927             "device":"floppy0",
1928             "locked":false,
1929             "removable":true,
1930             "type":"unknown"
1931          },
1932          {
1933             "device":"sd0",
1934             "locked":false,
1935             "removable":true,
1936             "type":"unknown"
1937          }
1938       ]
1939    }
1940
1941 query-blockstats
1942 ----------------
1943
1944 Show block device statistics.
1945
1946 Each device statistic information is stored in a json-object and the returned
1947 value is a json-array of all devices.
1948
1949 Each json-object contain the following:
1950
1951 - "device": device name (json-string)
1952 - "stats": A json-object with the statistics information, it contains:
1953     - "rd_bytes": bytes read (json-int)
1954     - "wr_bytes": bytes written (json-int)
1955     - "rd_operations": read operations (json-int)
1956     - "wr_operations": write operations (json-int)
1957     - "flush_operations": cache flush operations (json-int)
1958     - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
1959     - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
1960     - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
1961     - "wr_highest_offset": The offset after the greatest byte written to the
1962                            BlockDriverState since it has been opened (json-int)
1963     - "rd_merged": number of read requests that have been merged into
1964                    another request (json-int)
1965     - "wr_merged": number of write requests that have been merged into
1966                    another request (json-int)
1967     - "idle_time_ns": time since the last I/O operation, in
1968                       nanoseconds. If the field is absent it means
1969                       that there haven't been any operations yet
1970                       (json-int, optional)
1971     - "failed_rd_operations": number of failed read operations
1972                               (json-int)
1973     - "failed_wr_operations": number of failed write operations
1974                               (json-int)
1975     - "failed_flush_operations": number of failed flush operations
1976                                (json-int)
1977     - "invalid_rd_operations": number of invalid read operations
1978                                (json-int)
1979     - "invalid_wr_operations": number of invalid write operations
1980                                (json-int)
1981     - "invalid_flush_operations": number of invalid flush operations
1982                                   (json-int)
1983     - "account_invalid": whether invalid operations are included in
1984                          the last access statistics (json-bool)
1985     - "account_failed": whether failed operations are included in the
1986                          latency and last access statistics
1987                          (json-bool)
1988     - "timed_stats": A json-array containing statistics collected in
1989                      specific intervals, with the following members:
1990         - "interval_length": interval used for calculating the
1991                              statistics, in seconds (json-int)
1992         - "min_rd_latency_ns": minimum latency of read operations in
1993                                the defined interval, in nanoseconds
1994                                (json-int)
1995         - "min_wr_latency_ns": minimum latency of write operations in
1996                                the defined interval, in nanoseconds
1997                                (json-int)
1998         - "min_flush_latency_ns": minimum latency of flush operations
1999                                   in the defined interval, in
2000                                   nanoseconds (json-int)
2001         - "max_rd_latency_ns": maximum latency of read operations in
2002                                the defined interval, in nanoseconds
2003                                (json-int)
2004         - "max_wr_latency_ns": maximum latency of write operations in
2005                                the defined interval, in nanoseconds
2006                                (json-int)
2007         - "max_flush_latency_ns": maximum latency of flush operations
2008                                   in the defined interval, in
2009                                   nanoseconds (json-int)
2010         - "avg_rd_latency_ns": average latency of read operations in
2011                                the defined interval, in nanoseconds
2012                                (json-int)
2013         - "avg_wr_latency_ns": average latency of write operations in
2014                                the defined interval, in nanoseconds
2015                                (json-int)
2016         - "avg_flush_latency_ns": average latency of flush operations
2017                                   in the defined interval, in
2018                                   nanoseconds (json-int)
2019         - "avg_rd_queue_depth": average number of pending read
2020                                 operations in the defined interval
2021                                 (json-number)
2022         - "avg_wr_queue_depth": average number of pending write
2023                                 operations in the defined interval
2024                                 (json-number).
2025 - "parent": Contains recursively the statistics of the underlying
2026             protocol (e.g. the host file for a qcow2 image). If there is
2027             no underlying protocol, this field is omitted
2028             (json-object, optional)
2029
2030 Example:
2031
2032 -> { "execute": "query-blockstats" }
2033 <- {
2034       "return":[
2035          {
2036             "device":"ide0-hd0",
2037             "parent":{
2038                "stats":{
2039                   "wr_highest_offset":3686448128,
2040                   "wr_bytes":9786368,
2041                   "wr_operations":751,
2042                   "rd_bytes":122567168,
2043                   "rd_operations":36772
2044                   "wr_total_times_ns":313253456
2045                   "rd_total_times_ns":3465673657
2046                   "flush_total_times_ns":49653
2047                   "flush_operations":61,
2048                   "rd_merged":0,
2049                   "wr_merged":0,
2050                   "idle_time_ns":2953431879,
2051                   "account_invalid":true,
2052                   "account_failed":false
2053                }
2054             },
2055             "stats":{
2056                "wr_highest_offset":2821110784,
2057                "wr_bytes":9786368,
2058                "wr_operations":692,
2059                "rd_bytes":122739200,
2060                "rd_operations":36604
2061                "flush_operations":51,
2062                "wr_total_times_ns":313253456
2063                "rd_total_times_ns":3465673657
2064                "flush_total_times_ns":49653,
2065                "rd_merged":0,
2066                "wr_merged":0,
2067                "idle_time_ns":2953431879,
2068                "account_invalid":true,
2069                "account_failed":false
2070             }
2071          },
2072          {
2073             "device":"ide1-cd0",
2074             "stats":{
2075                "wr_highest_offset":0,
2076                "wr_bytes":0,
2077                "wr_operations":0,
2078                "rd_bytes":0,
2079                "rd_operations":0
2080                "flush_operations":0,
2081                "wr_total_times_ns":0
2082                "rd_total_times_ns":0
2083                "flush_total_times_ns":0,
2084                "rd_merged":0,
2085                "wr_merged":0,
2086                "account_invalid":false,
2087                "account_failed":false
2088             }
2089          },
2090          {
2091             "device":"floppy0",
2092             "stats":{
2093                "wr_highest_offset":0,
2094                "wr_bytes":0,
2095                "wr_operations":0,
2096                "rd_bytes":0,
2097                "rd_operations":0
2098                "flush_operations":0,
2099                "wr_total_times_ns":0
2100                "rd_total_times_ns":0
2101                "flush_total_times_ns":0,
2102                "rd_merged":0,
2103                "wr_merged":0,
2104                "account_invalid":false,
2105                "account_failed":false
2106             }
2107          },
2108          {
2109             "device":"sd0",
2110             "stats":{
2111                "wr_highest_offset":0,
2112                "wr_bytes":0,
2113                "wr_operations":0,
2114                "rd_bytes":0,
2115                "rd_operations":0
2116                "flush_operations":0,
2117                "wr_total_times_ns":0
2118                "rd_total_times_ns":0
2119                "flush_total_times_ns":0,
2120                "rd_merged":0,
2121                "wr_merged":0,
2122                "account_invalid":false,
2123                "account_failed":false
2124             }
2125          }
2126       ]
2127    }
2128
2129 query-cpus
2130 ----------
2131
2132 Show CPU information.
2133
2134 Return a json-array. Each CPU is represented by a json-object, which contains:
2135
2136 - "CPU": CPU index (json-int)
2137 - "current": true if this is the current CPU, false otherwise (json-bool)
2138 - "halted": true if the cpu is halted, false otherwise (json-bool)
2139 - "qom_path": path to the CPU object in the QOM tree (json-str)
2140 - "arch": architecture of the cpu, which determines what additional
2141           keys will be present (json-str)
2142 - Current program counter. The key's name depends on the architecture:
2143      "pc": i386/x86_64 (json-int)
2144      "nip": PPC (json-int)
2145      "pc" and "npc": sparc (json-int)
2146      "PC": mips (json-int)
2147 - "thread_id": ID of the underlying host thread (json-int)
2148
2149 Example:
2150
2151 -> { "execute": "query-cpus" }
2152 <- {
2153       "return":[
2154          {
2155             "CPU":0,
2156             "current":true,
2157             "halted":false,
2158             "qom_path":"/machine/unattached/device[0]",
2159             "arch":"x86",
2160             "pc":3227107138,
2161             "thread_id":3134
2162          },
2163          {
2164             "CPU":1,
2165             "current":false,
2166             "halted":true,
2167             "qom_path":"/machine/unattached/device[2]",
2168             "arch":"x86",
2169             "pc":7108165,
2170             "thread_id":3135
2171          }
2172       ]
2173    }
2174
2175 query-iothreads
2176 ---------------
2177
2178 Returns a list of information about each iothread.
2179
2180 Note this list excludes the QEMU main loop thread, which is not declared
2181 using the -object iothread command-line option.  It is always the main thread
2182 of the process.
2183
2184 Return a json-array. Each iothread is represented by a json-object, which contains:
2185
2186 - "id": name of iothread (json-str)
2187 - "thread-id": ID of the underlying host thread (json-int)
2188
2189 Example:
2190
2191 -> { "execute": "query-iothreads" }
2192 <- {
2193       "return":[
2194          {
2195             "id":"iothread0",
2196             "thread-id":3134
2197          },
2198          {
2199             "id":"iothread1",
2200             "thread-id":3135
2201          }
2202       ]
2203    }
2204
2205 query-pci
2206 ---------
2207
2208 PCI buses and devices information.
2209
2210 The returned value is a json-array of all buses. Each bus is represented by
2211 a json-object, which has a key with a json-array of all PCI devices attached
2212 to it. Each device is represented by a json-object.
2213
2214 The bus json-object contains the following:
2215
2216 - "bus": bus number (json-int)
2217 - "devices": a json-array of json-objects, each json-object represents a
2218              PCI device
2219
2220 The PCI device json-object contains the following:
2221
2222 - "bus": identical to the parent's bus number (json-int)
2223 - "slot": slot number (json-int)
2224 - "function": function number (json-int)
2225 - "class_info": a json-object containing:
2226      - "desc": device class description (json-string, optional)
2227      - "class": device class number (json-int)
2228 - "id": a json-object containing:
2229      - "device": device ID (json-int)
2230      - "vendor": vendor ID (json-int)
2231 - "irq": device's IRQ if assigned (json-int, optional)
2232 - "qdev_id": qdev id string (json-string)
2233 - "pci_bridge": It's a json-object, only present if this device is a
2234                 PCI bridge, contains:
2235      - "bus": bus number (json-int)
2236      - "secondary": secondary bus number (json-int)
2237      - "subordinate": subordinate bus number (json-int)
2238      - "io_range": I/O memory range information, a json-object with the
2239                    following members:
2240                  - "base": base address, in bytes (json-int)
2241                  - "limit": limit address, in bytes (json-int)
2242      - "memory_range": memory range information, a json-object with the
2243                        following members:
2244                  - "base": base address, in bytes (json-int)
2245                  - "limit": limit address, in bytes (json-int)
2246      - "prefetchable_range": Prefetchable memory range information, a
2247                              json-object with the following members:
2248                  - "base": base address, in bytes (json-int)
2249                  - "limit": limit address, in bytes (json-int)
2250      - "devices": a json-array of PCI devices if there's any attached, each
2251                   each element is represented by a json-object, which contains
2252                   the same members of the 'PCI device json-object' described
2253                   above (optional)
2254 - "regions": a json-array of json-objects, each json-object represents a
2255              memory region of this device
2256
2257 The memory range json-object contains the following:
2258
2259 - "base": base memory address (json-int)
2260 - "limit": limit value (json-int)
2261
2262 The region json-object can be an I/O region or a memory region, an I/O region
2263 json-object contains the following:
2264
2265 - "type": "io" (json-string, fixed)
2266 - "bar": BAR number (json-int)
2267 - "address": memory address (json-int)
2268 - "size": memory size (json-int)
2269
2270 A memory region json-object contains the following:
2271
2272 - "type": "memory" (json-string, fixed)
2273 - "bar": BAR number (json-int)
2274 - "address": memory address (json-int)
2275 - "size": memory size (json-int)
2276 - "mem_type_64": true or false (json-bool)
2277 - "prefetch": true or false (json-bool)
2278
2279 Example:
2280
2281 -> { "execute": "query-pci" }
2282 <- {
2283       "return":[
2284          {
2285             "bus":0,
2286             "devices":[
2287                {
2288                   "bus":0,
2289                   "qdev_id":"",
2290                   "slot":0,
2291                   "class_info":{
2292                      "class":1536,
2293                      "desc":"Host bridge"
2294                   },
2295                   "id":{
2296                      "device":32902,
2297                      "vendor":4663
2298                   },
2299                   "function":0,
2300                   "regions":[
2301
2302                   ]
2303                },
2304                {
2305                   "bus":0,
2306                   "qdev_id":"",
2307                   "slot":1,
2308                   "class_info":{
2309                      "class":1537,
2310                      "desc":"ISA bridge"
2311                   },
2312                   "id":{
2313                      "device":32902,
2314                      "vendor":28672
2315                   },
2316                   "function":0,
2317                   "regions":[
2318
2319                   ]
2320                },
2321                {
2322                   "bus":0,
2323                   "qdev_id":"",
2324                   "slot":1,
2325                   "class_info":{
2326                      "class":257,
2327                      "desc":"IDE controller"
2328                   },
2329                   "id":{
2330                      "device":32902,
2331                      "vendor":28688
2332                   },
2333                   "function":1,
2334                   "regions":[
2335                      {
2336                         "bar":4,
2337                         "size":16,
2338                         "address":49152,
2339                         "type":"io"
2340                      }
2341                   ]
2342                },
2343                {
2344                   "bus":0,
2345                   "qdev_id":"",
2346                   "slot":2,
2347                   "class_info":{
2348                      "class":768,
2349                      "desc":"VGA controller"
2350                   },
2351                   "id":{
2352                      "device":4115,
2353                      "vendor":184
2354                   },
2355                   "function":0,
2356                   "regions":[
2357                      {
2358                         "prefetch":true,
2359                         "mem_type_64":false,
2360                         "bar":0,
2361                         "size":33554432,
2362                         "address":4026531840,
2363                         "type":"memory"
2364                      },
2365                      {
2366                         "prefetch":false,
2367                         "mem_type_64":false,
2368                         "bar":1,
2369                         "size":4096,
2370                         "address":4060086272,
2371                         "type":"memory"
2372                      },
2373                      {
2374                         "prefetch":false,
2375                         "mem_type_64":false,
2376                         "bar":6,
2377                         "size":65536,
2378                         "address":-1,
2379                         "type":"memory"
2380                      }
2381                   ]
2382                },
2383                {
2384                   "bus":0,
2385                   "qdev_id":"",
2386                   "irq":11,
2387                   "slot":4,
2388                   "class_info":{
2389                      "class":1280,
2390                      "desc":"RAM controller"
2391                   },
2392                   "id":{
2393                      "device":6900,
2394                      "vendor":4098
2395                   },
2396                   "function":0,
2397                   "regions":[
2398                      {
2399                         "bar":0,
2400                         "size":32,
2401                         "address":49280,
2402                         "type":"io"
2403                      }
2404                   ]
2405                }
2406             ]
2407          }
2408       ]
2409    }
2410
2411 Note: This example has been shortened as the real response is too long.
2412
2413 query-kvm
2414 ---------
2415
2416 Show KVM information.
2417
2418 Return a json-object with the following information:
2419
2420 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
2421 - "present": true if QEMU has KVM support, false otherwise (json-bool)
2422
2423 Example:
2424
2425 -> { "execute": "query-kvm" }
2426 <- { "return": { "enabled": true, "present": true } }
2427
2428 query-status
2429 ------------
2430
2431 Return a json-object with the following information:
2432
2433 - "running": true if the VM is running, or false if it is paused (json-bool)
2434 - "singlestep": true if the VM is in single step mode,
2435                 false otherwise (json-bool)
2436 - "status": one of the following values (json-string)
2437     "debug" - QEMU is running on a debugger
2438     "inmigrate" - guest is paused waiting for an incoming migration
2439     "internal-error" - An internal error that prevents further guest
2440     execution has occurred
2441     "io-error" - the last IOP has failed and the device is configured
2442     to pause on I/O errors
2443     "paused" - guest has been paused via the 'stop' command
2444     "postmigrate" - guest is paused following a successful 'migrate'
2445     "prelaunch" - QEMU was started with -S and guest has not started
2446     "finish-migrate" - guest is paused to finish the migration process
2447     "restore-vm" - guest is paused to restore VM state
2448     "running" - guest is actively running
2449     "save-vm" - guest is paused to save the VM state
2450     "shutdown" - guest is shut down (and -no-shutdown is in use)
2451     "watchdog" - the watchdog action is configured to pause and
2452      has been triggered
2453
2454 Example:
2455
2456 -> { "execute": "query-status" }
2457 <- { "return": { "running": true, "singlestep": false, "status": "running" } }
2458
2459 query-mice
2460 ----------
2461
2462 Show VM mice information.
2463
2464 Each mouse is represented by a json-object, the returned value is a json-array
2465 of all mice.
2466
2467 The mouse json-object contains the following:
2468
2469 - "name": mouse's name (json-string)
2470 - "index": mouse's index (json-int)
2471 - "current": true if this mouse is receiving events, false otherwise (json-bool)
2472 - "absolute": true if the mouse generates absolute input events (json-bool)
2473
2474 Example:
2475
2476 -> { "execute": "query-mice" }
2477 <- {
2478       "return":[
2479          {
2480             "name":"QEMU Microsoft Mouse",
2481             "index":0,
2482             "current":false,
2483             "absolute":false
2484          },
2485          {
2486             "name":"QEMU PS/2 Mouse",
2487             "index":1,
2488             "current":true,
2489             "absolute":true
2490          }
2491       ]
2492    }
2493
2494 query-vnc
2495 ---------
2496
2497 Show VNC server information.
2498
2499 Return a json-object with server information. Connected clients are returned
2500 as a json-array of json-objects.
2501
2502 The main json-object contains the following:
2503
2504 - "enabled": true or false (json-bool)
2505 - "host": server's IP address (json-string)
2506 - "family": address family (json-string)
2507          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2508 - "service": server's port number (json-string)
2509 - "auth": authentication method (json-string)
2510          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2511                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2512                             "vencrypt+plain", "vencrypt+tls+none",
2513                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
2514                             "vencrypt+tls+vnc", "vencrypt+x509+none",
2515                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
2516                             "vencrypt+x509+vnc", "vnc"
2517 - "clients": a json-array of all connected clients
2518
2519 Clients are described by a json-object, each one contain the following:
2520
2521 - "host": client's IP address (json-string)
2522 - "family": address family (json-string)
2523          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2524 - "service": client's port number (json-string)
2525 - "x509_dname": TLS dname (json-string, optional)
2526 - "sasl_username": SASL username (json-string, optional)
2527
2528 Example:
2529
2530 -> { "execute": "query-vnc" }
2531 <- {
2532       "return":{
2533          "enabled":true,
2534          "host":"0.0.0.0",
2535          "service":"50402",
2536          "auth":"vnc",
2537          "family":"ipv4",
2538          "clients":[
2539             {
2540                "host":"127.0.0.1",
2541                "service":"50401",
2542                "family":"ipv4"
2543             }
2544          ]
2545       }
2546    }
2547
2548 query-spice
2549 -----------
2550
2551 Show SPICE server information.
2552
2553 Return a json-object with server information. Connected clients are returned
2554 as a json-array of json-objects.
2555
2556 The main json-object contains the following:
2557
2558 - "enabled": true or false (json-bool)
2559 - "host": server's IP address (json-string)
2560 - "port": server's port number (json-int, optional)
2561 - "tls-port": server's port number (json-int, optional)
2562 - "auth": authentication method (json-string)
2563          - Possible values: "none", "spice"
2564 - "channels": a json-array of all active channels clients
2565
2566 Channels are described by a json-object, each one contain the following:
2567
2568 - "host": client's IP address (json-string)
2569 - "family": address family (json-string)
2570          - Possible values: "ipv4", "ipv6", "unix", "unknown"
2571 - "port": client's port number (json-string)
2572 - "connection-id": spice connection id.  All channels with the same id
2573                    belong to the same spice session (json-int)
2574 - "channel-type": channel type.  "1" is the main control channel, filter for
2575                   this one if you want track spice sessions only (json-int)
2576 - "channel-id": channel id.  Usually "0", might be different needed when
2577                 multiple channels of the same type exist, such as multiple
2578                 display channels in a multihead setup (json-int)
2579 - "tls": whether the channel is encrypted (json-bool)
2580
2581 Example:
2582
2583 -> { "execute": "query-spice" }
2584 <- {
2585       "return": {
2586          "enabled": true,
2587          "auth": "spice",
2588          "port": 5920,
2589          "tls-port": 5921,
2590          "host": "0.0.0.0",
2591          "channels": [
2592             {
2593                "port": "54924",
2594                "family": "ipv4",
2595                "channel-type": 1,
2596                "connection-id": 1804289383,
2597                "host": "127.0.0.1",
2598                "channel-id": 0,
2599                "tls": true
2600             },
2601             {
2602                "port": "36710",
2603                "family": "ipv4",
2604                "channel-type": 4,
2605                "connection-id": 1804289383,
2606                "host": "127.0.0.1",
2607                "channel-id": 0,
2608                "tls": false
2609             },
2610             [ ... more channels follow ... ]
2611          ]
2612       }
2613    }
2614
2615 query-name
2616 ----------
2617
2618 Show VM name.
2619
2620 Return a json-object with the following information:
2621
2622 - "name": VM's name (json-string, optional)
2623
2624 Example:
2625
2626 -> { "execute": "query-name" }
2627 <- { "return": { "name": "qemu-name" } }
2628
2629 query-uuid
2630 ----------
2631
2632 Show VM UUID.
2633
2634 Return a json-object with the following information:
2635
2636 - "UUID": Universally Unique Identifier (json-string)
2637
2638 Example:
2639
2640 -> { "execute": "query-uuid" }
2641 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2642
2643 query-command-line-options
2644 --------------------------
2645
2646 Show command line option schema.
2647
2648 Return a json-array of command line option schema for all options (or for
2649 the given option), returning an error if the given option doesn't exist.
2650
2651 Each array entry contains the following:
2652
2653 - "option": option name (json-string)
2654 - "parameters": a json-array describes all parameters of the option:
2655     - "name": parameter name (json-string)
2656     - "type": parameter type (one of 'string', 'boolean', 'number',
2657               or 'size')
2658     - "help": human readable description of the parameter
2659               (json-string, optional)
2660     - "default": default value string for the parameter
2661                  (json-string, optional)
2662
2663 Example:
2664
2665 -> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } }
2666 <- { "return": [
2667         {
2668             "parameters": [
2669                 {
2670                     "name": "romfile",
2671                     "type": "string"
2672                 },
2673                 {
2674                     "name": "bootindex",
2675                     "type": "number"
2676                 }
2677             ],
2678             "option": "option-rom"
2679         }
2680      ]
2681    }
2682
2683 query-migrate
2684 -------------
2685
2686 Migration status.
2687
2688 Return a json-object. If migration is active there will be another json-object
2689 with RAM migration status and if block migration is active another one with
2690 block migration status.
2691
2692 The main json-object contains the following:
2693
2694 - "status": migration status (json-string)
2695      - Possible values: "setup", "active", "completed", "failed", "cancelled"
2696 - "total-time": total amount of ms since migration started.  If
2697                 migration has ended, it returns the total migration
2698                 time (json-int)
2699 - "setup-time" amount of setup time in milliseconds _before_ the
2700                iterations begin but _after_ the QMP command is issued.
2701                This is designed to provide an accounting of any activities
2702                (such as RDMA pinning) which may be expensive, but do not
2703                actually occur during the iterative migration rounds
2704                themselves. (json-int)
2705 - "downtime": only present when migration has finished correctly
2706               total amount in ms for downtime that happened (json-int)
2707 - "expected-downtime": only present while migration is active
2708                 total amount in ms for downtime that was calculated on
2709                 the last bitmap round (json-int)
2710 - "ram": only present if "status" is "active", it is a json-object with the
2711   following RAM information:
2712          - "transferred": amount transferred in bytes (json-int)
2713          - "remaining": amount remaining to transfer in bytes (json-int)
2714          - "total": total amount of memory in bytes (json-int)
2715          - "duplicate": number of pages filled entirely with the same
2716             byte (json-int)
2717             These are sent over the wire much more efficiently.
2718          - "skipped": number of skipped zero pages (json-int)
2719          - "normal" : number of whole pages transferred.  I.e. they
2720             were not sent as duplicate or xbzrle pages (json-int)
2721          - "normal-bytes" : number of bytes transferred in whole
2722             pages. This is just normal pages times size of one page,
2723             but this way upper levels don't need to care about page
2724             size (json-int)
2725          - "dirty-sync-count": times that dirty ram was synchronized (json-int)
2726 - "disk": only present if "status" is "active" and it is a block migration,
2727   it is a json-object with the following disk information:
2728          - "transferred": amount transferred in bytes (json-int)
2729          - "remaining": amount remaining to transfer in bytes json-int)
2730          - "total": total disk size in bytes (json-int)
2731 - "xbzrle-cache": only present if XBZRLE is active.
2732   It is a json-object with the following XBZRLE information:
2733          - "cache-size": XBZRLE cache size in bytes
2734          - "bytes": number of bytes transferred for XBZRLE compressed pages
2735          - "pages": number of XBZRLE compressed pages
2736          - "cache-miss": number of XBRZRLE page cache misses
2737          - "cache-miss-rate": rate of XBRZRLE page cache misses
2738          - "overflow": number of times XBZRLE overflows.  This means
2739            that the XBZRLE encoding was bigger than just sent the
2740            whole page, and then we sent the whole page instead (as as
2741            normal page).
2742
2743 Examples:
2744
2745 1. Before the first migration
2746
2747 -> { "execute": "query-migrate" }
2748 <- { "return": {} }
2749
2750 2. Migration is done and has succeeded
2751
2752 -> { "execute": "query-migrate" }
2753 <- { "return": {
2754         "status": "completed",
2755         "ram":{
2756           "transferred":123,
2757           "remaining":123,
2758           "total":246,
2759           "total-time":12345,
2760           "setup-time":12345,
2761           "downtime":12345,
2762           "duplicate":123,
2763           "normal":123,
2764           "normal-bytes":123456,
2765           "dirty-sync-count":15
2766         }
2767      }
2768    }
2769
2770 3. Migration is done and has failed
2771
2772 -> { "execute": "query-migrate" }
2773 <- { "return": { "status": "failed" } }
2774
2775 4. Migration is being performed and is not a block migration:
2776
2777 -> { "execute": "query-migrate" }
2778 <- {
2779       "return":{
2780          "status":"active",
2781          "ram":{
2782             "transferred":123,
2783             "remaining":123,
2784             "total":246,
2785             "total-time":12345,
2786             "setup-time":12345,
2787             "expected-downtime":12345,
2788             "duplicate":123,
2789             "normal":123,
2790             "normal-bytes":123456,
2791             "dirty-sync-count":15
2792          }
2793       }
2794    }
2795
2796 5. Migration is being performed and is a block migration:
2797
2798 -> { "execute": "query-migrate" }
2799 <- {
2800       "return":{
2801          "status":"active",
2802          "ram":{
2803             "total":1057024,
2804             "remaining":1053304,
2805             "transferred":3720,
2806             "total-time":12345,
2807             "setup-time":12345,
2808             "expected-downtime":12345,
2809             "duplicate":123,
2810             "normal":123,
2811             "normal-bytes":123456,
2812             "dirty-sync-count":15
2813          },
2814          "disk":{
2815             "total":20971520,
2816             "remaining":20880384,
2817             "transferred":91136
2818          }
2819       }
2820    }
2821
2822 6. Migration is being performed and XBZRLE is active:
2823
2824 -> { "execute": "query-migrate" }
2825 <- {
2826       "return":{
2827          "status":"active",
2828          "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
2829          "ram":{
2830             "total":1057024,
2831             "remaining":1053304,
2832             "transferred":3720,
2833             "total-time":12345,
2834             "setup-time":12345,
2835             "expected-downtime":12345,
2836             "duplicate":10,
2837             "normal":3333,
2838             "normal-bytes":3412992,
2839             "dirty-sync-count":15
2840          },
2841          "xbzrle-cache":{
2842             "cache-size":67108864,
2843             "bytes":20971520,
2844             "pages":2444343,
2845             "cache-miss":2244,
2846             "cache-miss-rate":0.123,
2847             "overflow":34434
2848          }
2849       }
2850    }
2851
2852 migrate-set-capabilities
2853 ------------------------
2854
2855 Enable/Disable migration capabilities
2856
2857 - "xbzrle": XBZRLE support
2858 - "rdma-pin-all": pin all pages when using RDMA during migration
2859 - "auto-converge": throttle down guest to help convergence of migration
2860 - "zero-blocks": compress zero blocks during block migration
2861 - "compress": use multiple compression threads to accelerate live migration
2862 - "events": generate events for each migration state change
2863 - "postcopy-ram": postcopy mode for live migration
2864
2865 Arguments:
2866
2867 Example:
2868
2869 -> { "execute": "migrate-set-capabilities" , "arguments":
2870      { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
2871
2872 query-migrate-capabilities
2873 --------------------------
2874
2875 Query current migration capabilities
2876
2877 - "capabilities": migration capabilities state
2878          - "xbzrle" : XBZRLE state (json-bool)
2879          - "rdma-pin-all" : RDMA Pin Page state (json-bool)
2880          - "auto-converge" : Auto Converge state (json-bool)
2881          - "zero-blocks" : Zero Blocks state (json-bool)
2882          - "compress": Multiple compression threads state (json-bool)
2883          - "events": Migration state change event state (json-bool)
2884          - "postcopy-ram": postcopy ram state (json-bool)
2885
2886 Arguments:
2887
2888 Example:
2889
2890 -> { "execute": "query-migrate-capabilities" }
2891 <- {"return": [
2892      {"state": false, "capability": "xbzrle"},
2893      {"state": false, "capability": "rdma-pin-all"},
2894      {"state": false, "capability": "auto-converge"},
2895      {"state": false, "capability": "zero-blocks"},
2896      {"state": false, "capability": "compress"},
2897      {"state": true, "capability": "events"},
2898      {"state": false, "capability": "postcopy-ram"}
2899    ]}
2900
2901 migrate-set-parameters
2902 ----------------------
2903
2904 Set migration parameters
2905
2906 - "compress-level": set compression level during migration (json-int)
2907 - "compress-threads": set compression thread count for migration (json-int)
2908 - "decompress-threads": set decompression thread count for migration (json-int)
2909 - "cpu-throttle-initial": set initial percentage of time guest cpus are
2910                           throttled for auto-converge (json-int)
2911 - "cpu-throttle-increment": set throttle increasing percentage for
2912                             auto-converge (json-int)
2913
2914 Arguments:
2915
2916 Example:
2917
2918 -> { "execute": "migrate-set-parameters" , "arguments":
2919       { "compress-level": 1 } }
2920
2921 query-migrate-parameters
2922 ------------------------
2923
2924 Query current migration parameters
2925
2926 - "parameters": migration parameters value
2927          - "compress-level" : compression level value (json-int)
2928          - "compress-threads" : compression thread count value (json-int)
2929          - "decompress-threads" : decompression thread count value (json-int)
2930          - "cpu-throttle-initial" : initial percentage of time guest cpus are
2931                                     throttled (json-int)
2932          - "cpu-throttle-increment" : throttle increasing percentage for
2933                                       auto-converge (json-int)
2934
2935 Arguments:
2936
2937 Example:
2938
2939 -> { "execute": "query-migrate-parameters" }
2940 <- {
2941       "return": {
2942          "decompress-threads": 2,
2943          "cpu-throttle-increment": 10,
2944          "compress-threads": 8,
2945          "compress-level": 1,
2946          "cpu-throttle-initial": 20
2947       }
2948    }
2949
2950 query-balloon
2951 -------------
2952
2953 Show balloon information.
2954
2955 Make an asynchronous request for balloon info. When the request completes a
2956 json-object will be returned containing the following data:
2957
2958 - "actual": current balloon value in bytes (json-int)
2959
2960 Example:
2961
2962 -> { "execute": "query-balloon" }
2963 <- {
2964       "return":{
2965          "actual":1073741824,
2966       }
2967    }
2968
2969 query-tpm
2970 ---------
2971
2972 Return information about the TPM device.
2973
2974 Arguments: None
2975
2976 Example:
2977
2978 -> { "execute": "query-tpm" }
2979 <- { "return":
2980      [
2981        { "model": "tpm-tis",
2982          "options":
2983            { "type": "passthrough",
2984              "data":
2985                { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
2986                  "path": "/dev/tpm0"
2987                }
2988            },
2989          "id": "tpm0"
2990        }
2991      ]
2992    }
2993
2994 query-tpm-models
2995 ----------------
2996
2997 Return a list of supported TPM models.
2998
2999 Arguments: None
3000
3001 Example:
3002
3003 -> { "execute": "query-tpm-models" }
3004 <- { "return": [ "tpm-tis" ] }
3005
3006 query-tpm-types
3007 ---------------
3008
3009 Return a list of supported TPM types.
3010
3011 Arguments: None
3012
3013 Example:
3014
3015 -> { "execute": "query-tpm-types" }
3016 <- { "return": [ "passthrough" ] }
3017
3018 chardev-add
3019 ----------------
3020
3021 Add a chardev.
3022
3023 Arguments:
3024
3025 - "id": the chardev's ID, must be unique (json-string)
3026 - "backend": chardev backend type + parameters
3027
3028 Examples:
3029
3030 -> { "execute" : "chardev-add",
3031      "arguments" : { "id" : "foo",
3032                      "backend" : { "type" : "null", "data" : {} } } }
3033 <- { "return": {} }
3034
3035 -> { "execute" : "chardev-add",
3036      "arguments" : { "id" : "bar",
3037                      "backend" : { "type" : "file",
3038                                    "data" : { "out" : "/tmp/bar.log" } } } }
3039 <- { "return": {} }
3040
3041 -> { "execute" : "chardev-add",
3042      "arguments" : { "id" : "baz",
3043                      "backend" : { "type" : "pty", "data" : {} } } }
3044 <- { "return": { "pty" : "/dev/pty/42" } }
3045
3046 chardev-remove
3047 --------------
3048
3049 Remove a chardev.
3050
3051 Arguments:
3052
3053 - "id": the chardev's ID, must exist and not be in use (json-string)
3054
3055 Example:
3056
3057 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
3058 <- { "return": {} }
3059
3060 query-rx-filter
3061 ---------------
3062
3063 Show rx-filter information.
3064
3065 Returns a json-array of rx-filter information for all NICs (or for the
3066 given NIC), returning an error if the given NIC doesn't exist, or
3067 given NIC doesn't support rx-filter querying, or given net client
3068 isn't a NIC.
3069
3070 The query will clear the event notification flag of each NIC, then qemu
3071 will start to emit event to QMP monitor.
3072
3073 Each array entry contains the following:
3074
3075 - "name": net client name (json-string)
3076 - "promiscuous": promiscuous mode is enabled (json-bool)
3077 - "multicast": multicast receive state (one of 'normal', 'none', 'all')
3078 - "unicast": unicast receive state  (one of 'normal', 'none', 'all')
3079 - "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0)
3080 - "broadcast-allowed": allow to receive broadcast (json-bool)
3081 - "multicast-overflow": multicast table is overflowed (json-bool)
3082 - "unicast-overflow": unicast table is overflowed (json-bool)
3083 - "main-mac": main macaddr string (json-string)
3084 - "vlan-table": a json-array of active vlan id
3085 - "unicast-table": a json-array of unicast macaddr string
3086 - "multicast-table": a json-array of multicast macaddr string
3087
3088 Example:
3089
3090 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
3091 <- { "return": [
3092         {
3093             "promiscuous": true,
3094             "name": "vnet0",
3095             "main-mac": "52:54:00:12:34:56",
3096             "unicast": "normal",
3097             "vlan": "normal",
3098             "vlan-table": [
3099                 4,
3100                 0
3101             ],
3102             "unicast-table": [
3103             ],
3104             "multicast": "normal",
3105             "multicast-overflow": false,
3106             "unicast-overflow": false,
3107             "multicast-table": [
3108                 "01:00:5e:00:00:01",
3109                 "33:33:00:00:00:01",
3110                 "33:33:ff:12:34:56"
3111             ],
3112             "broadcast-allowed": false
3113         }
3114       ]
3115    }
3116
3117 blockdev-add
3118 ------------
3119
3120 Add a block device.
3121
3122 This command is still a work in progress.  It doesn't support all
3123 block drivers among other things.  Stay away from it unless you want
3124 to help with its development.
3125
3126 Arguments:
3127
3128 - "options": block driver options
3129
3130 Example (1):
3131
3132 -> { "execute": "blockdev-add",
3133     "arguments": { "options" : { "driver": "qcow2",
3134                                  "file": { "driver": "file",
3135                                            "filename": "test.qcow2" } } } }
3136 <- { "return": {} }
3137
3138 Example (2):
3139
3140 -> { "execute": "blockdev-add",
3141      "arguments": {
3142          "options": {
3143            "driver": "qcow2",
3144            "node-name": "my_disk",
3145            "discard": "unmap",
3146            "cache": {
3147                "direct": true,
3148                "writeback": true
3149            },
3150            "file": {
3151                "driver": "file",
3152                "filename": "/tmp/test.qcow2"
3153            },
3154            "backing": {
3155                "driver": "raw",
3156                "file": {
3157                    "driver": "file",
3158                    "filename": "/dev/fdset/4"
3159                }
3160            }
3161          }
3162        }
3163      }
3164
3165 <- { "return": {} }
3166
3167 x-blockdev-del
3168 ------------
3169 Since 2.5
3170
3171 Deletes a block device that has been added using blockdev-add.
3172 The command will fail if the node is attached to a device or is
3173 otherwise being used.
3174
3175 This command is still a work in progress and is considered
3176 experimental. Stay away from it unless you want to help with its
3177 development.
3178
3179 Arguments:
3180
3181 - "node-name": Name of the graph node to delete (json-string)
3182
3183 Example:
3184
3185 -> { "execute": "blockdev-add",
3186      "arguments": {
3187          "options": {
3188              "driver": "qcow2",
3189              "node-name": "node0",
3190              "file": {
3191                  "driver": "file",
3192                  "filename": "test.qcow2"
3193              }
3194          }
3195      }
3196    }
3197
3198 <- { "return": {} }
3199
3200 -> { "execute": "x-blockdev-del",
3201      "arguments": { "node-name": "node0" }
3202    }
3203 <- { "return": {} }
3204
3205 blockdev-open-tray
3206 ------------------
3207
3208 Opens a block device's tray. If there is a block driver state tree inserted as a
3209 medium, it will become inaccessible to the guest (but it will remain associated
3210 to the block device, so closing the tray will make it accessible again).
3211
3212 If the tray was already open before, this will be a no-op.
3213
3214 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in
3215 which no such event will be generated, these include:
3216 - if the guest has locked the tray, @force is false and the guest does not
3217   respond to the eject request
3218 - if the BlockBackend denoted by @device does not have a guest device attached
3219   to it
3220 - if the guest device does not have an actual tray and is empty, for instance
3221   for floppy disk drives
3222
3223 Arguments:
3224
3225 - "device": block device name (deprecated, use @id instead)
3226             (json-string, optional)
3227 - "id": the name or QOM path of the guest device (json-string, optional)
3228 - "force": if false (the default), an eject request will be sent to the guest if
3229            it has locked the tray (and the tray will not be opened immediately);
3230            if true, the tray will be opened regardless of whether it is locked
3231            (json-bool, optional)
3232
3233 Example:
3234
3235 -> { "execute": "blockdev-open-tray",
3236      "arguments": { "id": "ide0-1-0" } }
3237
3238 <- { "timestamp": { "seconds": 1418751016,
3239                     "microseconds": 716996 },
3240      "event": "DEVICE_TRAY_MOVED",
3241      "data": { "device": "ide1-cd0",
3242                "tray-open": true } }
3243
3244 <- { "return": {} }
3245
3246 blockdev-close-tray
3247 -------------------
3248
3249 Closes a block device's tray. If there is a block driver state tree associated
3250 with the block device (which is currently ejected), that tree will be loaded as
3251 the medium.
3252
3253 If the tray was already closed before, this will be a no-op.
3254
3255 Arguments:
3256
3257 - "device": block device name (deprecated, use @id instead)
3258             (json-string, optional)
3259 - "id": the name or QOM path of the guest device (json-string, optional)
3260
3261 Example:
3262
3263 -> { "execute": "blockdev-close-tray",
3264      "arguments": { "id": "ide0-1-0" } }
3265
3266 <- { "timestamp": { "seconds": 1418751345,
3267                     "microseconds": 272147 },
3268      "event": "DEVICE_TRAY_MOVED",
3269      "data": { "device": "ide1-cd0",
3270                "tray-open": false } }
3271
3272 <- { "return": {} }
3273
3274 x-blockdev-remove-medium
3275 ------------------------
3276
3277 Removes a medium (a block driver state tree) from a block device. That block
3278 device's tray must currently be open (unless there is no attached guest device).
3279
3280 If the tray is open and there is no medium inserted, this will be a no-op.
3281
3282 This command is still a work in progress and is considered experimental.
3283 Stay away from it unless you want to help with its development.
3284
3285 Arguments:
3286
3287 - "device": block device name (deprecated, use @id instead)
3288             (json-string, optional)
3289 - "id": the name or QOM path of the guest device (json-string, optional)
3290
3291 Example:
3292
3293 -> { "execute": "x-blockdev-remove-medium",
3294      "arguments": { "id": "ide0-1-0" } }
3295
3296 <- { "error": { "class": "GenericError",
3297                 "desc": "Tray of device 'ide0-1-0' is not open" } }
3298
3299 -> { "execute": "blockdev-open-tray",
3300      "arguments": { "id": "ide0-1-0" } }
3301
3302 <- { "timestamp": { "seconds": 1418751627,
3303                     "microseconds": 549958 },
3304      "event": "DEVICE_TRAY_MOVED",
3305      "data": { "device": "ide1-cd0",
3306                "tray-open": true } }
3307
3308 <- { "return": {} }
3309
3310 -> { "execute": "x-blockdev-remove-medium",
3311      "arguments": { "device": "ide0-1-0" } }
3312
3313 <- { "return": {} }
3314
3315 x-blockdev-insert-medium
3316 ------------------------
3317
3318 Inserts a medium (a block driver state tree) into a block device. That block
3319 device's tray must currently be open (unless there is no attached guest device)
3320 and there must be no medium inserted already.
3321
3322 This command is still a work in progress and is considered experimental.
3323 Stay away from it unless you want to help with its development.
3324
3325 Arguments:
3326
3327 - "device": block device name (deprecated, use @id instead)
3328             (json-string, optional)
3329 - "id": the name or QOM path of the guest device (json-string, optional)
3330 - "node-name": root node of the BDS tree to insert into the block device
3331
3332 Example:
3333
3334 -> { "execute": "blockdev-add",
3335      "arguments": { "options": { "node-name": "node0",
3336                                  "driver": "raw",
3337                                  "file": { "driver": "file",
3338                                            "filename": "fedora.iso" } } } }
3339
3340 <- { "return": {} }
3341
3342 -> { "execute": "x-blockdev-insert-medium",
3343      "arguments": { "id": "ide0-1-0",
3344                     "node-name": "node0" } }
3345
3346 <- { "return": {} }
3347
3348 x-blockdev-change
3349 -----------------
3350
3351 Dynamically reconfigure the block driver state graph. It can be used
3352 to add, remove, insert or replace a graph node. Currently only the
3353 Quorum driver implements this feature to add or remove its child. This
3354 is useful to fix a broken quorum child.
3355
3356 If @node is specified, it will be inserted under @parent. @child
3357 may not be specified in this case. If both @parent and @child are
3358 specified but @node is not, @child will be detached from @parent.
3359
3360 Arguments:
3361 - "parent": the id or name of the parent node (json-string)
3362 - "child": the name of a child under the given parent node (json-string, optional)
3363 - "node": the name of the node that will be added (json-string, optional)
3364
3365 Note: this command is experimental, and not a stable API. It doesn't
3366 support all kinds of operations, all kinds of children, nor all block
3367 drivers.
3368
3369 Warning: The data in a new quorum child MUST be consistent with that of
3370 the rest of the array.
3371
3372 Example:
3373
3374 Add a new node to a quorum
3375 -> { "execute": "blockdev-add",
3376      "arguments": { "options": { "driver": "raw",
3377                                  "node-name": "new_node",
3378                                  "file": { "driver": "file",
3379                                            "filename": "test.raw" } } } }
3380 <- { "return": {} }
3381 -> { "execute": "x-blockdev-change",
3382      "arguments": { "parent": "disk1",
3383                     "node": "new_node" } }
3384 <- { "return": {} }
3385
3386 Delete a quorum's node
3387 -> { "execute": "x-blockdev-change",
3388      "arguments": { "parent": "disk1",
3389                     "child": "children.1" } }
3390 <- { "return": {} }
3391
3392 query-named-block-nodes
3393 -----------------------
3394
3395 Return a list of BlockDeviceInfo for all the named block driver nodes
3396
3397 Example:
3398
3399 -> { "execute": "query-named-block-nodes" }
3400 <- { "return": [ { "ro":false,
3401                    "drv":"qcow2",
3402                    "encrypted":false,
3403                    "file":"disks/test.qcow2",
3404                    "node-name": "my-node",
3405                    "backing_file_depth":1,
3406                    "bps":1000000,
3407                    "bps_rd":0,
3408                    "bps_wr":0,
3409                    "iops":1000000,
3410                    "iops_rd":0,
3411                    "iops_wr":0,
3412                    "bps_max": 8000000,
3413                    "bps_rd_max": 0,
3414                    "bps_wr_max": 0,
3415                    "iops_max": 0,
3416                    "iops_rd_max": 0,
3417                    "iops_wr_max": 0,
3418                    "iops_size": 0,
3419                    "write_threshold": 0,
3420                    "image":{
3421                       "filename":"disks/test.qcow2",
3422                       "format":"qcow2",
3423                       "virtual-size":2048000,
3424                       "backing_file":"base.qcow2",
3425                       "full-backing-filename":"disks/base.qcow2",
3426                       "backing-filename-format":"qcow2",
3427                       "snapshots":[
3428                          {
3429                             "id": "1",
3430                             "name": "snapshot1",
3431                             "vm-state-size": 0,
3432                             "date-sec": 10000200,
3433                             "date-nsec": 12,
3434                             "vm-clock-sec": 206,
3435                             "vm-clock-nsec": 30
3436                          }
3437                       ],
3438                       "backing-image":{
3439                           "filename":"disks/base.qcow2",
3440                           "format":"qcow2",
3441                           "virtual-size":2048000
3442                       }
3443                    } } ] }
3444
3445 blockdev-change-medium
3446 ----------------------
3447
3448 Changes the medium inserted into a block device by ejecting the current medium
3449 and loading a new image file which is inserted as the new medium.
3450
3451 Arguments:
3452
3453 - "device": block device name (deprecated, use @id instead)
3454             (json-string, optional)
3455 - "id": the name or QOM path of the guest device (json-string, optional)
3456 - "filename": filename of the new image (json-string)
3457 - "format": format of the new image (json-string, optional)
3458 - "read-only-mode": new read-only mode (json-string, optional)
3459           - Possible values: "retain" (default), "read-only", "read-write"
3460
3461 Examples:
3462
3463 1. Change a removable medium
3464
3465 -> { "execute": "blockdev-change-medium",
3466              "arguments": { "id": "ide0-1-0",
3467                             "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
3468                             "format": "raw" } }
3469 <- { "return": {} }
3470
3471 2. Load a read-only medium into a writable drive
3472
3473 -> { "execute": "blockdev-change-medium",
3474              "arguments": { "id": "floppyA",
3475                             "filename": "/srv/images/ro.img",
3476                             "format": "raw",
3477                             "read-only-mode": "retain" } }
3478
3479 <- { "error":
3480      { "class": "GenericError",
3481        "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
3482
3483 -> { "execute": "blockdev-change-medium",
3484              "arguments": { "id": "floppyA",
3485                             "filename": "/srv/images/ro.img",
3486                             "format": "raw",
3487                             "read-only-mode": "read-only" } }
3488
3489 <- { "return": {} }
3490
3491 query-memdev
3492 ------------
3493
3494 Show memory devices information.
3495
3496
3497 Example (1):
3498
3499 -> { "execute": "query-memdev" }
3500 <- { "return": [
3501        {
3502          "size": 536870912,
3503          "merge": false,
3504          "dump": true,
3505          "prealloc": false,
3506          "host-nodes": [0, 1],
3507          "policy": "bind"
3508        },
3509        {
3510          "size": 536870912,
3511          "merge": false,
3512          "dump": true,
3513          "prealloc": true,
3514          "host-nodes": [2, 3],
3515          "policy": "preferred"
3516        }
3517      ]
3518    }
3519
3520 query-memory-devices
3521 --------------------
3522
3523 Return a list of memory devices.
3524
3525 Example:
3526 -> { "execute": "query-memory-devices" }
3527 <- { "return": [ { "data":
3528                       { "addr": 5368709120,
3529                         "hotpluggable": true,
3530                         "hotplugged": true,
3531                         "id": "d1",
3532                         "memdev": "/objects/memX",
3533                         "node": 0,
3534                         "size": 1073741824,
3535                         "slot": 0},
3536                    "type": "dimm"
3537                  } ] }
3538
3539 query-acpi-ospm-status
3540 ----------------------
3541
3542 Return list of ACPIOSTInfo for devices that support status reporting
3543 via ACPI _OST method.
3544
3545 Example:
3546 -> { "execute": "query-acpi-ospm-status" }
3547 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
3548                  { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
3549                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
3550                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
3551    ]}
3552
3553 rtc-reset-reinjection
3554 ---------------------
3555
3556 Reset the RTC interrupt reinjection backlog.
3557
3558 Arguments: None.
3559
3560 Example:
3561
3562 -> { "execute": "rtc-reset-reinjection" }
3563 <- { "return": {} }
3564
3565 trace-event-get-state
3566 ---------------------
3567
3568 Query the state of events.
3569
3570 Arguments:
3571
3572 - "name": Event name pattern (json-string).
3573 - "vcpu": The vCPU to query, any vCPU by default (json-int, optional).
3574
3575 An event is returned if:
3576 - its name matches the "name" pattern, and
3577 - if "vcpu" is given, the event has the "vcpu" property.
3578
3579 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
3580 returning their state on the specified vCPU. Special case: if "name" is an exact
3581 match, "vcpu" is given and the event does not have the "vcpu" property, an error
3582 is returned.
3583
3584 Example:
3585
3586 -> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } }
3587 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
3588
3589 trace-event-set-state
3590 ---------------------
3591
3592 Set the state of events.
3593
3594 Arguments:
3595
3596 - "name": Event name pattern (json-string).
3597 - "enable": Whether to enable or disable the event (json-bool).
3598 - "ignore-unavailable": Whether to ignore errors for events that cannot be
3599   changed (json-bool, optional).
3600 - "vcpu": The vCPU to act upon, all vCPUs by default (json-int, optional).
3601
3602 An event's state is modified if:
3603 - its name matches the "name" pattern, and
3604 - if "vcpu" is given, the event has the "vcpu" property.
3605
3606 Therefore, if "vcpu" is given, the operation will only match per-vCPU events,
3607 setting their state on the specified vCPU. Special case: if "name" is an exact
3608 match, "vcpu" is given and the event does not have the "vcpu" property, an error
3609 is returned.
3610
3611 Example:
3612
3613 -> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } }
3614 <- { "return": {} }
3615
3616 input-send-event
3617 ----------------
3618
3619 Send input event to guest.
3620
3621 Arguments:
3622
3623 - "device": display device (json-string, optional)
3624 - "head": display head (json-int, optional)
3625 - "events": list of input events
3626
3627 The consoles are visible in the qom tree, under
3628 /backend/console[$index]. They have a device link and head property, so
3629 it is possible to map which console belongs to which device and display.
3630
3631 Example (1):
3632
3633 Press left mouse button.
3634
3635 -> { "execute": "input-send-event",
3636     "arguments": { "device": "video0",
3637                    "events": [ { "type": "btn",
3638                    "data" : { "down": true, "button": "left" } } ] } }
3639 <- { "return": {} }
3640
3641 -> { "execute": "input-send-event",
3642     "arguments": { "device": "video0",
3643                    "events": [ { "type": "btn",
3644                    "data" : { "down": false, "button": "left" } } ] } }
3645 <- { "return": {} }
3646
3647 Example (2):
3648
3649 Press ctrl-alt-del.
3650
3651 -> { "execute": "input-send-event",
3652      "arguments": { "events": [
3653         { "type": "key", "data" : { "down": true,
3654           "key": {"type": "qcode", "data": "ctrl" } } },
3655         { "type": "key", "data" : { "down": true,
3656           "key": {"type": "qcode", "data": "alt" } } },
3657         { "type": "key", "data" : { "down": true,
3658           "key": {"type": "qcode", "data": "delete" } } } ] } }
3659 <- { "return": {} }
3660
3661 Example (3):
3662
3663 Move mouse pointer to absolute coordinates (20000, 400).
3664
3665 -> { "execute": "input-send-event" ,
3666   "arguments": { "events": [
3667                { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
3668                { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
3669 <- { "return": {} }
3670
3671 block-set-write-threshold
3672 ------------
3673
3674 Change the write threshold for a block drive. The threshold is an offset,
3675 thus must be non-negative. Default is no write threshold.
3676 Setting the threshold to zero disables it.
3677
3678 Arguments:
3679
3680 - "node-name": the node name in the block driver state graph (json-string)
3681 - "write-threshold": the write threshold in bytes (json-int)
3682
3683 Example:
3684
3685 -> { "execute": "block-set-write-threshold",
3686   "arguments": { "node-name": "mydev",
3687                  "write-threshold": 17179869184 } }
3688 <- { "return": {} }
3689
3690 Show rocker switch
3691 ------------------
3692
3693 Arguments:
3694
3695 - "name": switch name
3696
3697 Example:
3698
3699 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
3700 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
3701
3702 Show rocker switch ports
3703 ------------------------
3704
3705 Arguments:
3706
3707 - "name": switch name
3708
3709 Example:
3710
3711 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
3712 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
3713                   "autoneg": "off", "link-up": true, "speed": 10000},
3714                  {"duplex": "full", "enabled": true, "name": "sw1.2",
3715                   "autoneg": "off", "link-up": true, "speed": 10000}
3716    ]}
3717
3718 Show rocker switch OF-DPA flow tables
3719 -------------------------------------
3720
3721 Arguments:
3722
3723 - "name": switch name
3724 - "tbl-id": (optional) flow table ID
3725
3726 Example:
3727
3728 -> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } }
3729 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
3730                   "hits": 138,
3731                   "cookie": 0,
3732                   "action": {"goto-tbl": 10},
3733                   "mask": {"in-pport": 4294901760}
3734                  },
3735                  {...more...},
3736    ]}
3737
3738 Show rocker OF-DPA group tables
3739 -------------------------------
3740
3741 Arguments:
3742
3743 - "name": switch name
3744 - "type": (optional) group type
3745
3746 Example:
3747
3748 -> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } }
3749 <- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841,
3750                   "pop-vlan": 1, "id": 251723778},
3751                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841,
3752                   "pop-vlan": 1, "id": 251723776},
3753                  {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840,
3754                   "pop-vlan": 1, "id": 251658241},
3755                  {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840,
3756                   "pop-vlan": 1, "id": 251658240}
3757    ]}
3758
3759 query-gic-capabilities
3760 ---------------
3761
3762 Return a list of GICCapability objects, describing supported GIC
3763 (Generic Interrupt Controller) versions.
3764
3765 Arguments: None
3766
3767 Example:
3768
3769 -> { "execute": "query-gic-capabilities" }
3770 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
3771                 { "version": 3, "emulated": false, "kernel": true } ] }
3772
3773 Show existing/possible CPUs
3774 ---------------------------
3775
3776 Arguments: None.
3777
3778 Example for pseries machine type started with
3779 -smp 2,cores=2,maxcpus=4 -cpu POWER8:
3780
3781 -> { "execute": "query-hotpluggable-cpus" }
3782 <- {"return": [
3783      { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
3784        "vcpus-count": 1 },
3785      { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
3786        "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
3787    ]}'
3788
3789 Example for pc machine type started with
3790 -smp 1,maxcpus=2:
3791     -> { "execute": "query-hotpluggable-cpus" }
3792     <- {"return": [
3793          {
3794             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
3795             "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
3796          },
3797          {
3798             "qom-path": "/machine/unattached/device[0]",
3799             "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
3800             "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
3801          }
3802        ]}