qmp-commands.hx

   1 HXCOMM QMP dispatch table and documentation
   2 HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and
   3 HXCOMM does not show up in the other formats.
   4
   5 SQMP
   6                         QMP Supported Commands
   7                         ----------------------
   8
   9 This document describes all commands currently supported by QMP.
  10
  11 Most of the time their usage is exactly the same as in the user Monitor, this
  12 means that any other document which also describe commands (the manpage,
  13 QEMU's manual, etc) can and should be consulted.
  14
  15 QMP has two types of commands: regular and query commands. Regular commands
  16 usually change the Virtual Machine's state someway, while query commands just
  17 return information. The sections below are divided accordingly.
  18
  19 It's important to observe that all communication examples are formatted in
  20 a reader-friendly way, so that they're easier to understand. However, in real
  21 protocol usage, they're emitted as a single line.
  22
  23 Also, the following notation is used to denote data flow:
  24
  25 -> data issued by the Client
  26 <- Server data response
  27
  28 Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
  29 information on the Server command and response formats.
  30
  31 NOTE: This document is temporary and will be replaced soon.
  32
  33 1. Stability Considerations
  34 ===========================
  35
  36 The current QMP command set (described in this file) may be useful for a
  37 number of use cases, however it's limited and several commands have bad
  38 defined semantics, specially with regard to command completion.
  39
  40 These problems are going to be solved incrementally in the next QEMU releases
  41 and we're going to establish a deprecation policy for badly defined commands.
  42
  43 If you're planning to adopt QMP, please observe the following:
  44
  45     1. The deprecation policy will take efect and be documented soon, please
  46        check the documentation of each used command as soon as a new release of
  47        QEMU is available
  48
  49     2. DO NOT rely on anything which is not explicit documented
  50
  51     3. Errors, in special, are not documented. Applications should NOT check
  52        for specific errors classes or data (it's strongly recommended to only
  53        check for the "error" key)
  54
  55 2. Regular Commands
  56 ===================
  57
  58 Server's responses in the examples below are always a success response, please
  59 refer to the QMP specification for more details on error responses.
  60
  61 EQMP
  62
  63     {
  64         .name       = "quit",
  65         .args_type  = "",
  66         .params     = "",
  67         .help       = "quit the emulator",
  68         .user_print = monitor_user_noop,
  69         .mhandler.cmd_new = do_quit,
  70     },
  71
  72 SQMP
  73 quit
  74 ----
  75
  76 Quit the emulator.
  77
  78 Arguments: None.
  79
  80 Example:
  81
  82 -> { "execute": "quit" }
  83 <- { "return": {} }
  84
  85 EQMP
  86
  87     {
  88         .name       = "eject",
  89         .args_type  = "force:-f,device:B",
  90         .params     = "[-f] device",
  91         .help       = "eject a removable medium (use -f to force it)",
  92         .user_print = monitor_user_noop,
  93         .mhandler.cmd_new = do_eject,
  94     },
  95
  96 SQMP
  97 eject
  98 -----
  99
 100 Eject a removable medium.
 101
 102 Arguments:
 103
 104 - force: force ejection (json-bool, optional)
 105 - device: device name (json-string)
 106
 107 Example:
 108
 109 -> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
 110 <- { "return": {} }
 111
 112 Note: The "force" argument defaults to false.
 113
 114 EQMP
 115
 116     {
 117         .name       = "change",
 118         .args_type  = "device:B,target:F,arg:s?",
 119         .params     = "device filename [format]",
 120         .help       = "change a removable medium, optional format",
 121         .user_print = monitor_user_noop,
 122         .mhandler.cmd_new = do_change,
 123     },
 124
 125 SQMP
 126 change
 127 ------
 128
 129 Change a removable medium or VNC configuration.
 130
 131 Arguments:
 132
 133 - "device": device name (json-string)
 134 - "target": filename or item (json-string)
 135 - "arg": additional argument (json-string, optional)
 136
 137 Examples:
 138
 139 1. Change a removable medium
 140
 141 -> { "execute": "change",
 142              "arguments": { "device": "ide1-cd0",
 143                             "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
 144 <- { "return": {} }
 145
 146 2. Change VNC password
 147
 148 -> { "execute": "change",
 149              "arguments": { "device": "vnc", "target": "password",
 150                             "arg": "foobar1" } }
 151 <- { "return": {} }
 152
 153 EQMP
 154
 155     {
 156         .name       = "screendump",
 157         .args_type  = "filename:F",
 158         .params     = "filename",
 159         .help       = "save screen into PPM image 'filename'",
 160         .user_print = monitor_user_noop,
 161         .mhandler.cmd_new = do_screen_dump,
 162     },
 163
 164 SQMP
 165 screendump
 166 ----------
 167
 168 Save screen into PPM image.
 169
 170 Arguments:
 171
 172 - "filename": file path (json-string)
 173
 174 Example:
 175
 176 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
 177 <- { "return": {} }
 178
 179 EQMP
 180
 181     {
 182         .name       = "stop",
 183         .args_type  = "",
 184         .params     = "",
 185         .help       = "stop emulation",
 186         .user_print = monitor_user_noop,
 187         .mhandler.cmd_new = do_stop,
 188     },
 189
 190 SQMP
 191 stop
 192 ----
 193
 194 Stop the emulator.
 195
 196 Arguments: None.
 197
 198 Example:
 199
 200 -> { "execute": "stop" }
 201 <- { "return": {} }
 202
 203 EQMP
 204
 205     {
 206         .name       = "cont",
 207         .args_type  = "",
 208         .params     = "",
 209         .help       = "resume emulation",
 210         .user_print = monitor_user_noop,
 211         .mhandler.cmd_new = do_cont,
 212     },
 213
 214 SQMP
 215 cont
 216 ----
 217
 218 Resume emulation.
 219
 220 Arguments: None.
 221
 222 Example:
 223
 224 -> { "execute": "cont" }
 225 <- { "return": {} }
 226
 227 EQMP
 228
 229     {
 230         .name       = "system_reset",
 231         .args_type  = "",
 232         .params     = "",
 233         .help       = "reset the system",
 234         .user_print = monitor_user_noop,
 235         .mhandler.cmd_new = do_system_reset,
 236     },
 237
 238 SQMP
 239 system_reset
 240 ------------
 241
 242 Reset the system.
 243
 244 Arguments: None.
 245
 246 Example:
 247
 248 -> { "execute": "system_reset" }
 249 <- { "return": {} }
 250
 251 EQMP
 252
 253     {
 254         .name       = "system_powerdown",
 255         .args_type  = "",
 256         .params     = "",
 257         .help       = "send system power down event",
 258         .user_print = monitor_user_noop,
 259         .mhandler.cmd_new = do_system_powerdown,
 260     },
 261
 262 SQMP
 263 system_powerdown
 264 ----------------
 265
 266 Send system power down event.
 267
 268 Arguments: None.
 269
 270 Example:
 271
 272 -> { "execute": "system_powerdown" }
 273 <- { "return": {} }
 274
 275 EQMP
 276
 277     {
 278         .name       = "device_add",
 279         .args_type  = "device:O",
 280         .params     = "driver[,prop=value][,...]",
 281         .help       = "add device, like -device on the command line",
 282         .user_print = monitor_user_noop,
 283         .mhandler.cmd_new = do_device_add,
 284     },
 285
 286 SQMP
 287 device_add
 288 ----------
 289
 290 Add a device.
 291
 292 Arguments:
 293
 294 - "driver": the name of the new device's driver (json-string)
 295 - "bus": the device's parent bus (device tree path, json-string, optional)
 296 - "id": the device's ID, must be unique (json-string)
 297 - device properties
 298
 299 Example:
 300
 301 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
 302 <- { "return": {} }
 303
 304 Notes:
 305
 306 (1) For detailed information about this command, please refer to the
 307     'docs/qdev-device-use.txt' file.
 308
 309 (2) It's possible to list device properties by running QEMU with the
 310     "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
 311
 312 EQMP
 313
 314     {
 315         .name       = "device_del",
 316         .args_type  = "id:s",
 317         .params     = "device",
 318         .help       = "remove device",
 319         .user_print = monitor_user_noop,
 320         .mhandler.cmd_new = do_device_del,
 321     },
 322
 323 SQMP
 324 device_del
 325 ----------
 326
 327 Remove a device.
 328
 329 Arguments:
 330
 331 - "id": the device's ID (json-string)
 332
 333 Example:
 334
 335 -> { "execute": "device_del", "arguments": { "id": "net1" } }
 336 <- { "return": {} }
 337
 338 EQMP
 339
 340     {
 341         .name       = "cpu",
 342         .args_type  = "index:i",
 343         .params     = "index",
 344         .help       = "set the default CPU",
 345         .user_print = monitor_user_noop,
 346         .mhandler.cmd_new = do_cpu_set,
 347     },
 348
 349 SQMP
 350 cpu
 351 ---
 352
 353 Set the default CPU.
 354
 355 Arguments:
 356
 357 - "index": the CPU's index (json-int)
 358
 359 Example:
 360
 361 -> { "execute": "cpu", "arguments": { "index": 0 } }
 362 <- { "return": {} }
 363
 364 Note: CPUs' indexes are obtained with the 'query-cpus' command.
 365
 366 EQMP
 367
 368     {
 369         .name       = "memsave",
 370         .args_type  = "val:l,size:i,filename:s",
 371         .params     = "addr size file",
 372         .help       = "save to disk virtual memory dump starting at 'addr' of size 'size'",
 373         .user_print = monitor_user_noop,
 374         .mhandler.cmd_new = do_memory_save,
 375     },
 376
 377 SQMP
 378 memsave
 379 -------
 380
 381 Save to disk virtual memory dump starting at 'val' of size 'size'.
 382
 383 Arguments:
 384
 385 - "val": the starting address (json-int)
 386 - "size": the memory size, in bytes (json-int)
 387 - "filename": file path (json-string)
 388
 389 Example:
 390
 391 -> { "execute": "memsave",
 392              "arguments": { "val": 10,
 393                             "size": 100,
 394                             "filename": "/tmp/virtual-mem-dump" } }
 395 <- { "return": {} }
 396
 397 Note: Depends on the current CPU.
 398
 399 EQMP
 400
 401     {
 402         .name       = "pmemsave",
 403         .args_type  = "val:l,size:i,filename:s",
 404         .params     = "addr size file",
 405         .help       = "save to disk physical memory dump starting at 'addr' of size 'size'",
 406         .user_print = monitor_user_noop,
 407         .mhandler.cmd_new = do_physical_memory_save,
 408     },
 409
 410 SQMP
 411 pmemsave
 412 --------
 413
 414 Save to disk physical memory dump starting at 'val' of size 'size'.
 415
 416 Arguments:
 417
 418 - "val": the starting address (json-int)
 419 - "size": the memory size, in bytes (json-int)
 420 - "filename": file path (json-string)
 421
 422 Example:
 423
 424 -> { "execute": "pmemsave",
 425              "arguments": { "val": 10,
 426                             "size": 100,
 427                             "filename": "/tmp/physical-mem-dump" } }
 428 <- { "return": {} }
 429
 430 EQMP
 431
 432     {
 433         .name       = "migrate",
 434         .args_type  = "detach:-d,blk:-b,inc:-i,uri:s",
 435         .params     = "[-d] [-b] [-i] uri",
 436         .help       = "migrate to URI (using -d to not wait for completion)"
 437                       "\n\t\t\t -b for migration without shared storage with"
 438                       " full copy of disk\n\t\t\t -i for migration without "
 439                       "shared storage with incremental copy of disk "
 440                       "(base image shared between src and destination)",
 441         .user_print = monitor_user_noop,
 442         .mhandler.cmd_new = do_migrate,
 443     },
 444
 445 SQMP
 446 migrate
 447 -------
 448
 449 Migrate to URI.
 450
 451 Arguments:
 452
 453 - "blk": block migration, full disk copy (json-bool, optional)
 454 - "inc": incremental disk copy (json-bool, optional)
 455 - "uri": Destination URI (json-string)
 456
 457 Example:
 458
 459 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
 460 <- { "return": {} }
 461
 462 Notes:
 463
 464 (1) The 'query-migrate' command should be used to check migration's progress
 465     and final result (this information is provided by the 'status' member)
 466 (2) All boolean arguments default to false
 467 (3) The user Monitor's "detach" argument is invalid in QMP and should not
 468     be used
 469
 470 EQMP
 471
 472     {
 473         .name       = "migrate_cancel",
 474         .args_type  = "",
 475         .params     = "",
 476         .help       = "cancel the current VM migration",
 477         .user_print = monitor_user_noop,
 478         .mhandler.cmd_new = do_migrate_cancel,
 479     },
 480
 481 SQMP
 482 migrate_cancel
 483 --------------
 484
 485 Cancel the current migration.
 486
 487 Arguments: None.
 488
 489 Example:
 490
 491 -> { "execute": "migrate_cancel" }
 492 <- { "return": {} }
 493
 494 EQMP
 495
 496     {
 497         .name       = "migrate_set_speed",
 498         .args_type  = "value:f",
 499         .params     = "value",
 500         .help       = "set maximum speed (in bytes) for migrations",
 501         .user_print = monitor_user_noop,
 502         .mhandler.cmd_new = do_migrate_set_speed,
 503     },
 504
 505 SQMP
 506 migrate_set_speed
 507 -----------------
 508
 509 Set maximum speed for migrations.
 510
 511 Arguments:
 512
 513 - "value": maximum speed, in bytes per second (json-number)
 514
 515 Example:
 516
 517 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
 518 <- { "return": {} }
 519
 520 EQMP
 521
 522     {
 523         .name       = "migrate_set_downtime",
 524         .args_type  = "value:T",
 525         .params     = "value",
 526         .help       = "set maximum tolerated downtime (in seconds) for migrations",
 527         .user_print = monitor_user_noop,
 528         .mhandler.cmd_new = do_migrate_set_downtime,
 529     },
 530
 531 SQMP
 532 migrate_set_downtime
 533 --------------------
 534
 535 Set maximum tolerated downtime (in seconds) for migrations.
 536
 537 Arguments:
 538
 539 - "value": maximum downtime (json-number)
 540
 541 Example:
 542
 543 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
 544 <- { "return": {} }
 545
 546 EQMP
 547
 548     {
 549         .name       = "netdev_add",
 550         .args_type  = "netdev:O",
 551         .params     = "[user|tap|socket],id=str[,prop=value][,...]",
 552         .help       = "add host network device",
 553         .user_print = monitor_user_noop,
 554         .mhandler.cmd_new = do_netdev_add,
 555     },
 556
 557 SQMP
 558 netdev_add
 559 ----------
 560
 561 Add host network device.
 562
 563 Arguments:
 564
 565 - "type": the device type, "tap", "user", ... (json-string)
 566 - "id": the device's ID, must be unique (json-string)
 567 - device options
 568
 569 Example:
 570
 571 -> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
 572 <- { "return": {} }
 573
 574 Note: The supported device options are the same ones supported by the '-net'
 575       command-line argument, which are listed in the '-help' output or QEMU's
 576       manual
 577
 578 EQMP
 579
 580     {
 581         .name       = "netdev_del",
 582         .args_type  = "id:s",
 583         .params     = "id",
 584         .help       = "remove host network device",
 585         .user_print = monitor_user_noop,
 586         .mhandler.cmd_new = do_netdev_del,
 587     },
 588
 589 SQMP
 590 netdev_del
 591 ----------
 592
 593 Remove host network device.
 594
 595 Arguments:
 596
 597 - "id": the device's ID, must be unique (json-string)
 598
 599 Example:
 600
 601 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
 602 <- { "return": {} }
 603
 604 EQMP
 605
 606     {
 607         .name       = "balloon",
 608         .args_type  = "value:M",
 609         .params     = "target",
 610         .help       = "request VM to change its memory allocation (in MB)",
 611         .user_print = monitor_user_noop,
 612         .mhandler.cmd_async = do_balloon,
 613         .flags      = MONITOR_CMD_ASYNC,
 614     },
 615
 616 SQMP
 617 balloon
 618 -------
 619
 620 Request VM to change its memory allocation (in bytes).
 621
 622 Arguments:
 623
 624 - "value": New memory allocation (json-int)
 625
 626 Example:
 627
 628 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
 629 <- { "return": {} }
 630
 631 EQMP
 632
 633     {
 634         .name       = "set_link",
 635         .args_type  = "name:s,up:b",
 636         .params     = "name on|off",
 637         .help       = "change the link status of a network adapter",
 638         .user_print = monitor_user_noop,
 639         .mhandler.cmd_new = do_set_link,
 640     },
 641
 642 SQMP
 643 set_link
 644 --------
 645
 646 Change the link status of a network adapter.
 647
 648 Arguments:
 649
 650 - "name": network device name (json-string)
 651 - "up": status is up (json-bool)
 652
 653 Example:
 654
 655 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
 656 <- { "return": {} }
 657
 658 EQMP
 659
 660     {
 661         .name       = "getfd",
 662         .args_type  = "fdname:s",
 663         .params     = "getfd name",
 664         .help       = "receive a file descriptor via SCM rights and assign it a name",
 665         .user_print = monitor_user_noop,
 666         .mhandler.cmd_new = do_getfd,
 667     },
 668
 669 SQMP
 670 getfd
 671 -----
 672
 673 Receive a file descriptor via SCM rights and assign it a name.
 674
 675 Arguments:
 676
 677 - "fdname": file descriptor name (json-string)
 678
 679 Example:
 680
 681 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
 682 <- { "return": {} }
 683
 684 EQMP
 685
 686     {
 687         .name       = "closefd",
 688         .args_type  = "fdname:s",
 689         .params     = "closefd name",
 690         .help       = "close a file descriptor previously passed via SCM rights",
 691         .user_print = monitor_user_noop,
 692         .mhandler.cmd_new = do_closefd,
 693     },
 694
 695 SQMP
 696 closefd
 697 -------
 698
 699 Close a file descriptor previously passed via SCM rights.
 700
 701 Arguments:
 702
 703 - "fdname": file descriptor name (json-string)
 704
 705 Example:
 706
 707 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
 708 <- { "return": {} }
 709
 710 EQMP
 711
 712     {
 713         .name       = "block_passwd",
 714         .args_type  = "device:B,password:s",
 715         .params     = "block_passwd device password",
 716         .help       = "set the password of encrypted block devices",
 717         .user_print = monitor_user_noop,
 718         .mhandler.cmd_new = do_block_set_passwd,
 719     },
 720
 721 SQMP
 722 block_passwd
 723 ------------
 724
 725 Set the password of encrypted block devices.
 726
 727 Arguments:
 728
 729 - "device": device name (json-string)
 730 - "password": password (json-string)
 731
 732 Example:
 733
 734 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
 735                                                "password": "12345" } }
 736 <- { "return": {} }
 737
 738 EQMP
 739
 740     {
 741         .name       = "agent_viewfile",
 742         .args_type  = "filepath:s",
 743         .params     = "filepath",
 744         .help       = "Echo a file from the guest filesystem",
 745         .user_print = monitor_user_noop,
 746         .mhandler.cmd_async = do_agent_viewfile,
 747         .flags      = MONITOR_CMD_ASYNC,
 748     },
 749
 750 STEXI
 751 @item agent_viewfile @var{filepath}
 752 @findex agent_viewfile
 753 Echo the file identified by @var{filepath} on the guest filesystem
 754 ETEXI
 755 SQMP
 756 agent_viewfile
 757 --------
 758
 759 Echo the file identified by @var{filepath} from the guest filesystem.
 760
 761 Arguments:
 762
 763 - "filepath": Full guest path of the desired file
 764
 765 Example:
 766
 767 -> { "execute": "agent_viewfile",
 768                 "arguments": { "filepath": "/sys/kernel/kexec_loaded" } }
 769 <- { "return": { "contents": "0" } }
 770
 771 EQMP
 772
 773     {
 774         .name       = "agent_viewdmesg",
 775         .args_type  = "",
 776         .params     = "",
 777         .help       = "View guest dmesg output",
 778         .user_print = do_agent_viewdmesg_print,
 779         .mhandler.cmd_async = do_agent_viewdmesg,
 780         .flags      = MONITOR_CMD_ASYNC,
 781     },
 782
 783 STEXI
 784 @item agent_viewdmesg
 785 @findex agent_viewdmesg
 786 View guest dmesg output
 787 ETEXI
 788 SQMP
 789 agent_viewdmesg
 790 --------
 791
 792 View guest dmesg output
 793
 794 Arguments:
 795
 796 (none)
 797
 798 Example:
 799
 800 -> { "execute": "agent_viewdmesg" }
 801 <- { "return": {
 802        "contents": "[353487.942215] usb 1-4: USB disconnect, address 9\n..."
 803      }
 804    }
 805
 806 EQMP
 807
 808     {
 809         .name       = "agent_shutdown",
 810         .args_type  = "shutdown_type:s",
 811         .params     = "[reboot|shutdown|poweroff]",
 812         .help       = "Shutdown/reboot the guest locally",
 813         .user_print = monitor_user_noop,
 814         .mhandler.cmd_async = do_agent_shutdown,
 815         .flags      = MONITOR_CMD_ASYNC,
 816     },
 817
 818 STEXI
 819 @item agent_shutdown
 820 @findex agent_shutdown
 821 Shutdown/reboot the guest locally
 822 ETEXI
 823 SQMP
 824 agent_shutdown
 825 --------
 826
 827 Shutdown the guest locally
 828
 829 Arguments:
 830
 831 (none)
 832
 833 Example:
 834
 835 -> { "execute": "agent_shutdown" }
 836 <- { "return": {} }
 837
 838 EQMP
 839
 840     {
 841         .name       = "agent_ping",
 842         .args_type  = "",
 843         .params     = "",
 844         .help       = "Ping a guest",
 845         .user_print = do_agent_ping_print,
 846         .mhandler.cmd_async = do_agent_ping,
 847         .flags      = MONITOR_CMD_ASYNC,
 848     },
 849
 850 STEXI
 851 @item agent_ping
 852 @findex agent_ping
 853 Ping a guest
 854 ETEXI
 855 SQMP
 856 agent_ping
 857 --------
 858
 859 Ping a guest
 860
 861 Arguments:
 862
 863 (none)
 864
 865 Example:
 866
 867 -> { "execute": "agent_ping" }
 868 <- { "return": { "response":"ok" } }
 869
 870 EQMP
 871
 872     {
 873         .name       = "agent_capabilities",
 874         .args_type  = "",
 875         .params     = "",
 876         .help       = "Fetch and re-negotiate guest agent capabilities",
 877         .user_print = do_agent_capabilities_print,
 878         .mhandler.cmd_async = do_agent_capabilities,
 879         .flags      = MONITOR_CMD_ASYNC,
 880     },
 881
 882 STEXI
 883 @item agent_capabilities
 884 @findex agent_capabilities
 885 Fetch and re-negotiate guest agent capabilties
 886 ETEXI
 887 SQMP
 888 agent_capabilities
 889 --------
 890
 891 Fetch and re-negotiate guest agent capabilities
 892
 893 Arguments:
 894
 895 (none)
 896
 897 Example:
 898
 899 -> { "execute": "agent_capabilities" }
 900 <- { "return":["va.shutdown", "va.getdmesg", "va.getfile", ... ] }
 901
 902 EQMP
 903
 904     {
 905         .name       = "qmp_capabilities",
 906         .args_type  = "",
 907         .params     = "",
 908         .help       = "enable QMP capabilities",
 909         .user_print = monitor_user_noop,
 910         .mhandler.cmd_new = do_qmp_capabilities,
 911     },
 912
 913 SQMP
 914 qmp_capabilities
 915 ----------------
 916
 917 Enable QMP capabilities.
 918
 919 Arguments: None.
 920
 921 Example:
 922
 923 -> { "execute": "qmp_capabilities" }
 924 <- { "return": {} }
 925
 926 Note: This command must be issued before issuing any other command.
 927
 928 3. Query Commands
 929 =================
 930
 931 HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
 932 HXCOMM this! We will possibly move query commands definitions inside those
 933 HXCOMM sections, just like regular commands.
 934
 935 EQMP
 936
 937 SQMP
 938 query-version
 939 -------------
 940
 941 Show QEMU version.
 942
 943 Return a json-object with the following information:
 944
 945 - "qemu": A json-object containing three integer values:
 946     - "major": QEMU's major version (json-int)
 947     - "minor": QEMU's minor version (json-int)
 948     - "micro": QEMU's micro version (json-int)
 949 - "package": package's version (json-string)
 950
 951 Example:
 952
 953 -> { "execute": "query-version" }
 954 <- {
 955       "return":{
 956          "qemu":{
 957             "major":0,
 958             "minor":11,
 959             "micro":5
 960          },
 961          "package":""
 962       }
 963    }
 964
 965 EQMP
 966
 967 SQMP
 968 query-commands
 969 --------------
 970
 971 List QMP available commands.
 972
 973 Each command is represented by a json-object, the returned value is a json-array
 974 of all commands.
 975
 976 Each json-object contain:
 977
 978 - "name": command's name (json-string)
 979
 980 Example:
 981
 982 -> { "execute": "query-commands" }
 983 <- {
 984       "return":[
 985          {
 986             "name":"query-balloon"
 987          },
 988          {
 989             "name":"system_powerdown"
 990          }
 991       ]
 992    }
 993
 994 Note: This example has been shortened as the real response is too long.
 995
 996 EQMP
 997
 998 SQMP
 999 query-chardev
1000 -------------
1001
1002 Each device is represented by a json-object. The returned value is a json-array
1003 of all devices.
1004
1005 Each json-object contain the following:
1006
1007 - "label": device's label (json-string)
1008 - "filename": device's file (json-string)
1009
1010 Example:
1011
1012 -> { "execute": "query-chardev" }
1013 <- {
1014       "return":[
1015          {
1016             "label":"monitor",
1017             "filename":"stdio"
1018          },
1019          {
1020             "label":"serial0",
1021             "filename":"vc"
1022          }
1023       ]
1024    }
1025
1026 EQMP
1027
1028 SQMP
1029 query-block
1030 -----------
1031
1032 Show the block devices.
1033
1034 Each block device information is stored in a json-object and the returned value
1035 is a json-array of all devices.
1036
1037 Each json-object contain the following:
1038
1039 - "device": device name (json-string)
1040 - "type": device type (json-string)
1041          - Possible values: "hd", "cdrom", "floppy", "unknown"
1042 - "removable": true if the device is removable, false otherwise (json-bool)
1043 - "locked": true if the device is locked, false otherwise (json-bool)
1044 - "inserted": only present if the device is inserted, it is a json-object
1045    containing the following:
1046          - "file": device file name (json-string)
1047          - "ro": true if read-only, false otherwise (json-bool)
1048          - "drv": driver format name (json-string)
1049              - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
1050                                 "file", "file", "ftp", "ftps", "host_cdrom",
1051                                 "host_device", "host_floppy", "http", "https",
1052                                 "nbd", "parallels", "qcow", "qcow2", "raw",
1053                                 "tftp", "vdi", "vmdk", "vpc", "vvfat"
1054          - "backing_file": backing file name (json-string, optional)
1055          - "encrypted": true if encrypted, false otherwise (json-bool)
1056
1057 Example:
1058
1059 -> { "execute": "query-block" }
1060 <- {
1061       "return":[
1062          {
1063             "device":"ide0-hd0",
1064             "locked":false,
1065             "removable":false,
1066             "inserted":{
1067                "ro":false,
1068                "drv":"qcow2",
1069                "encrypted":false,
1070                "file":"disks/test.img"
1071             },
1072             "type":"hd"
1073          },
1074          {
1075             "device":"ide1-cd0",
1076             "locked":false,
1077             "removable":true,
1078             "type":"cdrom"
1079          },
1080          {
1081             "device":"floppy0",
1082             "locked":false,
1083             "removable":true,
1084             "type": "floppy"
1085          },
1086          {
1087             "device":"sd0",
1088             "locked":false,
1089             "removable":true,
1090             "type":"floppy"
1091          }
1092       ]
1093    }
1094
1095 EQMP
1096
1097 SQMP
1098 query-blockstats
1099 ----------------
1100
1101 Show block device statistics.
1102
1103 Each device statistic information is stored in a json-object and the returned
1104 value is a json-array of all devices.
1105
1106 Each json-object contain the following:
1107
1108 - "device": device name (json-string)
1109 - "stats": A json-object with the statistics information, it contains:
1110     - "rd_bytes": bytes read (json-int)
1111     - "wr_bytes": bytes written (json-int)
1112     - "rd_operations": read operations (json-int)
1113     - "wr_operations": write operations (json-int)
1114     - "wr_highest_offset": Highest offset of a sector written since the
1115                            BlockDriverState has been opened (json-int)
1116 - "parent": Contains recursively the statistics of the underlying
1117             protocol (e.g. the host file for a qcow2 image). If there is
1118             no underlying protocol, this field is omitted
1119             (json-object, optional)
1120
1121 Example:
1122
1123 -> { "execute": "query-blockstats" }
1124 <- {
1125       "return":[
1126          {
1127             "device":"ide0-hd0",
1128             "parent":{
1129                "stats":{
1130                   "wr_highest_offset":3686448128,
1131                   "wr_bytes":9786368,
1132                   "wr_operations":751,
1133                   "rd_bytes":122567168,
1134                   "rd_operations":36772
1135                }
1136             },
1137             "stats":{
1138                "wr_highest_offset":2821110784,
1139                "wr_bytes":9786368,
1140                "wr_operations":692,
1141                "rd_bytes":122739200,
1142                "rd_operations":36604
1143             }
1144          },
1145          {
1146             "device":"ide1-cd0",
1147             "stats":{
1148                "wr_highest_offset":0,
1149                "wr_bytes":0,
1150                "wr_operations":0,
1151                "rd_bytes":0,
1152                "rd_operations":0
1153             }
1154          },
1155          {
1156             "device":"floppy0",
1157             "stats":{
1158                "wr_highest_offset":0,
1159                "wr_bytes":0,
1160                "wr_operations":0,
1161                "rd_bytes":0,
1162                "rd_operations":0
1163             }
1164          },
1165          {
1166             "device":"sd0",
1167             "stats":{
1168                "wr_highest_offset":0,
1169                "wr_bytes":0,
1170                "wr_operations":0,
1171                "rd_bytes":0,
1172                "rd_operations":0
1173             }
1174          }
1175       ]
1176    }
1177
1178 EQMP
1179
1180 SQMP
1181 query-cpus
1182 ----------
1183
1184 Show CPU information.
1185
1186 Return a json-array. Each CPU is represented by a json-object, which contains:
1187
1188 - "CPU": CPU index (json-int)
1189 - "current": true if this is the current CPU, false otherwise (json-bool)
1190 - "halted": true if the cpu is halted, false otherwise (json-bool)
1191 - Current program counter. The key's name depends on the architecture:
1192      "pc": i386/x86_64 (json-int)
1193      "nip": PPC (json-int)
1194      "pc" and "npc": sparc (json-int)
1195      "PC": mips (json-int)
1196
1197 Example:
1198
1199 -> { "execute": "query-cpus" }
1200 <- {
1201       "return":[
1202          {
1203             "CPU":0,
1204             "current":true,
1205             "halted":false,
1206             "pc":3227107138
1207          },
1208          {
1209             "CPU":1,
1210             "current":false,
1211             "halted":true,
1212             "pc":7108165
1213          }
1214       ]
1215    }
1216
1217 EQMP
1218
1219 SQMP
1220 query-pci
1221 ---------
1222
1223 PCI buses and devices information.
1224
1225 The returned value is a json-array of all buses. Each bus is represented by
1226 a json-object, which has a key with a json-array of all PCI devices attached
1227 to it. Each device is represented by a json-object.
1228
1229 The bus json-object contains the following:
1230
1231 - "bus": bus number (json-int)
1232 - "devices": a json-array of json-objects, each json-object represents a
1233              PCI device
1234
1235 The PCI device json-object contains the following:
1236
1237 - "bus": identical to the parent's bus number (json-int)
1238 - "slot": slot number (json-int)
1239 - "function": function number (json-int)
1240 - "class_info": a json-object containing:
1241      - "desc": device class description (json-string, optional)
1242      - "class": device class number (json-int)
1243 - "id": a json-object containing:
1244      - "device": device ID (json-int)
1245      - "vendor": vendor ID (json-int)
1246 - "irq": device's IRQ if assigned (json-int, optional)
1247 - "qdev_id": qdev id string (json-string)
1248 - "pci_bridge": It's a json-object, only present if this device is a
1249                 PCI bridge, contains:
1250      - "bus": bus number (json-int)
1251      - "secondary": secondary bus number (json-int)
1252      - "subordinate": subordinate bus number (json-int)
1253      - "io_range": I/O memory range information, a json-object with the
1254                    following members:
1255                  - "base": base address, in bytes (json-int)
1256                  - "limit": limit address, in bytes (json-int)
1257      - "memory_range": memory range information, a json-object with the
1258                        following members:
1259                  - "base": base address, in bytes (json-int)
1260                  - "limit": limit address, in bytes (json-int)
1261      - "prefetchable_range": Prefetchable memory range information, a
1262                              json-object with the following members:
1263                  - "base": base address, in bytes (json-int)
1264                  - "limit": limit address, in bytes (json-int)
1265      - "devices": a json-array of PCI devices if there's any attached, each
1266                   each element is represented by a json-object, which contains
1267                   the same members of the 'PCI device json-object' described
1268                   above (optional)
1269 - "regions": a json-array of json-objects, each json-object represents a
1270              memory region of this device
1271
1272 The memory range json-object contains the following:
1273
1274 - "base": base memory address (json-int)
1275 - "limit": limit value (json-int)
1276
1277 The region json-object can be an I/O region or a memory region, an I/O region
1278 json-object contains the following:
1279
1280 - "type": "io" (json-string, fixed)
1281 - "bar": BAR number (json-int)
1282 - "address": memory address (json-int)
1283 - "size": memory size (json-int)
1284
1285 A memory region json-object contains the following:
1286
1287 - "type": "memory" (json-string, fixed)
1288 - "bar": BAR number (json-int)
1289 - "address": memory address (json-int)
1290 - "size": memory size (json-int)
1291 - "mem_type_64": true or false (json-bool)
1292 - "prefetch": true or false (json-bool)
1293
1294 Example:
1295
1296 -> { "execute": "query-pci" }
1297 <- {
1298       "return":[
1299          {
1300             "bus":0,
1301             "devices":[
1302                {
1303                   "bus":0,
1304                   "qdev_id":"",
1305                   "slot":0,
1306                   "class_info":{
1307                      "class":1536,
1308                      "desc":"Host bridge"
1309                   },
1310                   "id":{
1311                      "device":32902,
1312                      "vendor":4663
1313                   },
1314                   "function":0,
1315                   "regions":[
1316
1317                   ]
1318                },
1319                {
1320                   "bus":0,
1321                   "qdev_id":"",
1322                   "slot":1,
1323                   "class_info":{
1324                      "class":1537,
1325                      "desc":"ISA bridge"
1326                   },
1327                   "id":{
1328                      "device":32902,
1329                      "vendor":28672
1330                   },
1331                   "function":0,
1332                   "regions":[
1333
1334                   ]
1335                },
1336                {
1337                   "bus":0,
1338                   "qdev_id":"",
1339                   "slot":1,
1340                   "class_info":{
1341                      "class":257,
1342                      "desc":"IDE controller"
1343                   },
1344                   "id":{
1345                      "device":32902,
1346                      "vendor":28688
1347                   },
1348                   "function":1,
1349                   "regions":[
1350                      {
1351                         "bar":4,
1352                         "size":16,
1353                         "address":49152,
1354                         "type":"io"
1355                      }
1356                   ]
1357                },
1358                {
1359                   "bus":0,
1360                   "qdev_id":"",
1361                   "slot":2,
1362                   "class_info":{
1363                      "class":768,
1364                      "desc":"VGA controller"
1365                   },
1366                   "id":{
1367                      "device":4115,
1368                      "vendor":184
1369                   },
1370                   "function":0,
1371                   "regions":[
1372                      {
1373                         "prefetch":true,
1374                         "mem_type_64":false,
1375                         "bar":0,
1376                         "size":33554432,
1377                         "address":4026531840,
1378                         "type":"memory"
1379                      },
1380                      {
1381                         "prefetch":false,
1382                         "mem_type_64":false,
1383                         "bar":1,
1384                         "size":4096,
1385                         "address":4060086272,
1386                         "type":"memory"
1387                      },
1388                      {
1389                         "prefetch":false,
1390                         "mem_type_64":false,
1391                         "bar":6,
1392                         "size":65536,
1393                         "address":-1,
1394                         "type":"memory"
1395                      }
1396                   ]
1397                },
1398                {
1399                   "bus":0,
1400                   "qdev_id":"",
1401                   "irq":11,
1402                   "slot":4,
1403                   "class_info":{
1404                      "class":1280,
1405                      "desc":"RAM controller"
1406                   },
1407                   "id":{
1408                      "device":6900,
1409                      "vendor":4098
1410                   },
1411                   "function":0,
1412                   "regions":[
1413                      {
1414                         "bar":0,
1415                         "size":32,
1416                         "address":49280,
1417                         "type":"io"
1418                      }
1419                   ]
1420                }
1421             ]
1422          }
1423       ]
1424    }
1425
1426 Note: This example has been shortened as the real response is too long.
1427
1428 EQMP
1429
1430 SQMP
1431 query-kvm
1432 ---------
1433
1434 Show KVM information.
1435
1436 Return a json-object with the following information:
1437
1438 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
1439 - "present": true if QEMU has KVM support, false otherwise (json-bool)
1440
1441 Example:
1442
1443 -> { "execute": "query-kvm" }
1444 <- { "return": { "enabled": true, "present": true } }
1445
1446 EQMP
1447
1448 SQMP
1449 query-status
1450 ------------
1451
1452 Return a json-object with the following information:
1453
1454 - "running": true if the VM is running, or false if it is paused (json-bool)
1455 - "singlestep": true if the VM is in single step mode,
1456                 false otherwise (json-bool)
1457
1458 Example:
1459
1460 -> { "execute": "query-status" }
1461 <- { "return": { "running": true, "singlestep": false } }
1462
1463 EQMP
1464
1465 SQMP
1466 query-mice
1467 ----------
1468
1469 Show VM mice information.
1470
1471 Each mouse is represented by a json-object, the returned value is a json-array
1472 of all mice.
1473
1474 The mouse json-object contains the following:
1475
1476 - "name": mouse's name (json-string)
1477 - "index": mouse's index (json-int)
1478 - "current": true if this mouse is receiving events, false otherwise (json-bool)
1479 - "absolute": true if the mouse generates absolute input events (json-bool)
1480
1481 Example:
1482
1483 -> { "execute": "query-mice" }
1484 <- {
1485       "return":[
1486          {
1487             "name":"QEMU Microsoft Mouse",
1488             "index":0,
1489             "current":false,
1490             "absolute":false
1491          },
1492          {
1493             "name":"QEMU PS/2 Mouse",
1494             "index":1,
1495             "current":true,
1496             "absolute":true
1497          }
1498       ]
1499    }
1500
1501 EQMP
1502
1503 SQMP
1504 query-vnc
1505 ---------
1506
1507 Show VNC server information.
1508
1509 Return a json-object with server information. Connected clients are returned
1510 as a json-array of json-objects.
1511
1512 The main json-object contains the following:
1513
1514 - "enabled": true or false (json-bool)
1515 - "host": server's IP address (json-string)
1516 - "family": address family (json-string)
1517          - Possible values: "ipv4", "ipv6", "unix", "unknown"
1518 - "service": server's port number (json-string)
1519 - "auth": authentication method (json-string)
1520          - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
1521                             "tls", "ultra", "unknown", "vencrypt", "vencrypt",
1522                             "vencrypt+plain", "vencrypt+tls+none",
1523                             "vencrypt+tls+plain", "vencrypt+tls+sasl",
1524                             "vencrypt+tls+vnc", "vencrypt+x509+none",
1525                             "vencrypt+x509+plain", "vencrypt+x509+sasl",
1526                             "vencrypt+x509+vnc", "vnc"
1527 - "clients": a json-array of all connected clients
1528
1529 Clients are described by a json-object, each one contain the following:
1530
1531 - "host": client's IP address (json-string)
1532 - "family": address family (json-string)
1533          - Possible values: "ipv4", "ipv6", "unix", "unknown"
1534 - "service": client's port number (json-string)
1535 - "x509_dname": TLS dname (json-string, optional)
1536 - "sasl_username": SASL username (json-string, optional)
1537
1538 Example:
1539
1540 -> { "execute": "query-vnc" }
1541 <- {
1542       "return":{
1543          "enabled":true,
1544          "host":"0.0.0.0",
1545          "service":"50402",
1546          "auth":"vnc",
1547          "family":"ipv4",
1548          "clients":[
1549             {
1550                "host":"127.0.0.1",
1551                "service":"50401",
1552                "family":"ipv4"
1553             }
1554          ]
1555       }
1556    }
1557
1558 EQMP
1559
1560 SQMP
1561 query-name
1562 ----------
1563
1564 Show VM name.
1565
1566 Return a json-object with the following information:
1567
1568 - "name": VM's name (json-string, optional)
1569
1570 Example:
1571
1572 -> { "execute": "query-name" }
1573 <- { "return": { "name": "qemu-name" } }
1574
1575 EQMP
1576
1577 SQMP
1578 query-uuid
1579 ----------
1580
1581 Show VM UUID.
1582
1583 Return a json-object with the following information:
1584
1585 - "UUID": Universally Unique Identifier (json-string)
1586
1587 Example:
1588
1589 -> { "execute": "query-uuid" }
1590 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
1591
1592 EQMP
1593
1594 SQMP
1595 query-migrate
1596 -------------
1597
1598 Migration status.
1599
1600 Return a json-object. If migration is active there will be another json-object
1601 with RAM migration status and if block migration is active another one with
1602 block migration status.
1603
1604 The main json-object contains the following:
1605
1606 - "status": migration status (json-string)
1607      - Possible values: "active", "completed", "failed", "cancelled"
1608 - "ram": only present if "status" is "active", it is a json-object with the
1609   following RAM information (in bytes):
1610          - "transferred": amount transferred (json-int)
1611          - "remaining": amount remaining (json-int)
1612          - "total": total (json-int)
1613 - "disk": only present if "status" is "active" and it is a block migration,
1614   it is a json-object with the following disk information (in bytes):
1615          - "transferred": amount transferred (json-int)
1616          - "remaining": amount remaining (json-int)
1617          - "total": total (json-int)
1618
1619 Examples:
1620
1621 1. Before the first migration
1622
1623 -> { "execute": "query-migrate" }
1624 <- { "return": {} }
1625
1626 2. Migration is done and has succeeded
1627
1628 -> { "execute": "query-migrate" }
1629 <- { "return": { "status": "completed" } }
1630
1631 3. Migration is done and has failed
1632
1633 -> { "execute": "query-migrate" }
1634 <- { "return": { "status": "failed" } }
1635
1636 4. Migration is being performed and is not a block migration:
1637
1638 -> { "execute": "query-migrate" }
1639 <- {
1640       "return":{
1641          "status":"active",
1642          "ram":{
1643             "transferred":123,
1644             "remaining":123,
1645             "total":246
1646          }
1647       }
1648    }
1649
1650 5. Migration is being performed and is a block migration:
1651
1652 -> { "execute": "query-migrate" }
1653 <- {
1654       "return":{
1655          "status":"active",
1656          "ram":{
1657             "total":1057024,
1658             "remaining":1053304,
1659             "transferred":3720
1660          },
1661          "disk":{
1662             "total":20971520,
1663             "remaining":20880384,
1664             "transferred":91136
1665          }
1666       }
1667    }
1668
1669 EQMP
1670
1671 SQMP
1672 query-balloon
1673 -------------
1674
1675 Show balloon information.
1676
1677 Make an asynchronous request for balloon info. When the request completes a
1678 json-object will be returned containing the following data:
1679
1680 - "actual": current balloon value in bytes (json-int)
1681 - "mem_swapped_in": Amount of memory swapped in bytes (json-int, optional)
1682 - "mem_swapped_out": Amount of memory swapped out in bytes (json-int, optional)
1683 - "major_page_faults": Number of major faults (json-int, optional)
1684 - "minor_page_faults": Number of minor faults (json-int, optional)
1685 - "free_mem": Total amount of free and unused memory in
1686               bytes (json-int, optional)
1687 - "total_mem": Total amount of available memory in bytes (json-int, optional)
1688
1689 Example:
1690
1691 -> { "execute": "query-balloon" }
1692 <- {
1693       "return":{
1694          "actual":1073741824,
1695          "mem_swapped_in":0,
1696          "mem_swapped_out":0,
1697          "major_page_faults":142,
1698          "minor_page_faults":239245,
1699          "free_mem":1014185984,
1700          "total_mem":1044668416
1701       }
1702    }
1703
1704 EQMP
1705