1HXCOMM QMP dispatch table and documentation 2HXCOMM Text between SQMP and EQMP is copied to the QMP documentation file and 3HXCOMM does not show up in the other formats. 4 5SQMP 6 QMP Supported Commands 7 ---------------------- 8 9This document describes all commands currently supported by QMP. 10 11Most of the time their usage is exactly the same as in the user Monitor, this 12means that any other document which also describe commands (the manpage, 13QEMU's manual, etc) can and should be consulted. 14 15QMP has two types of commands: regular and query commands. Regular commands 16usually change the Virtual Machine's state someway, while query commands just 17return information. The sections below are divided accordingly. 18 19It's important to observe that all communication examples are formatted in 20a reader-friendly way, so that they're easier to understand. However, in real 21protocol usage, they're emitted as a single line. 22 23Also, the following notation is used to denote data flow: 24 25-> data issued by the Client 26<- Server data response 27 28Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed 29information on the Server command and response formats. 30 31NOTE: This document is temporary and will be replaced soon. 32 331. Stability Considerations 34=========================== 35 36The current QMP command set (described in this file) may be useful for a 37number of use cases, however it's limited and several commands have bad 38defined semantics, specially with regard to command completion. 39 40These problems are going to be solved incrementally in the next QEMU releases 41and we're going to establish a deprecation policy for badly defined commands. 42 43If you're planning to adopt QMP, please observe the following: 44 45 1. The deprecation policy will take effect 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 552. Regular Commands 56=================== 57 58Server's responses in the examples below are always a success response, please 59refer to the QMP specification for more details on error responses. 60 61EQMP 62 63 { 64 .name = "quit", 65 .args_type = "", 66 .mhandler.cmd_new = qmp_marshal_quit, 67 }, 68 69SQMP 70quit 71---- 72 73Quit the emulator. 74 75Arguments: None. 76 77Example: 78 79-> { "execute": "quit" } 80<- { "return": {} } 81 82EQMP 83 84 { 85 .name = "eject", 86 .args_type = "force:-f,device:B", 87 .mhandler.cmd_new = qmp_marshal_eject, 88 }, 89 90SQMP 91eject 92----- 93 94Eject a removable medium. 95 96Arguments: 97 98- force: force ejection (json-bool, optional) 99- device: device name (json-string) 100 101Example: 102 103-> { "execute": "eject", "arguments": { "device": "ide1-cd0" } } 104<- { "return": {} } 105 106Note: The "force" argument defaults to false. 107 108EQMP 109 110 { 111 .name = "change", 112 .args_type = "device:B,target:F,arg:s?", 113 .mhandler.cmd_new = qmp_marshal_change, 114 }, 115 116SQMP 117change 118------ 119 120Change a removable medium or VNC configuration. 121 122Arguments: 123 124- "device": device name (json-string) 125- "target": filename or item (json-string) 126- "arg": additional argument (json-string, optional) 127 128Examples: 129 1301. Change a removable medium 131 132-> { "execute": "change", 133 "arguments": { "device": "ide1-cd0", 134 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } } 135<- { "return": {} } 136 1372. Change VNC password 138 139-> { "execute": "change", 140 "arguments": { "device": "vnc", "target": "password", 141 "arg": "foobar1" } } 142<- { "return": {} } 143 144EQMP 145 146 { 147 .name = "screendump", 148 .args_type = "filename:F", 149 .mhandler.cmd_new = qmp_marshal_screendump, 150 }, 151 152SQMP 153screendump 154---------- 155 156Save screen into PPM image. 157 158Arguments: 159 160- "filename": file path (json-string) 161 162Example: 163 164-> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } } 165<- { "return": {} } 166 167EQMP 168 169 { 170 .name = "stop", 171 .args_type = "", 172 .mhandler.cmd_new = qmp_marshal_stop, 173 }, 174 175SQMP 176stop 177---- 178 179Stop the emulator. 180 181Arguments: None. 182 183Example: 184 185-> { "execute": "stop" } 186<- { "return": {} } 187 188EQMP 189 190 { 191 .name = "cont", 192 .args_type = "", 193 .mhandler.cmd_new = qmp_marshal_cont, 194 }, 195 196SQMP 197cont 198---- 199 200Resume emulation. 201 202Arguments: None. 203 204Example: 205 206-> { "execute": "cont" } 207<- { "return": {} } 208 209EQMP 210 211 { 212 .name = "system_wakeup", 213 .args_type = "", 214 .mhandler.cmd_new = qmp_marshal_system_wakeup, 215 }, 216 217SQMP 218system_wakeup 219------------- 220 221Wakeup guest from suspend. 222 223Arguments: None. 224 225Example: 226 227-> { "execute": "system_wakeup" } 228<- { "return": {} } 229 230EQMP 231 232 { 233 .name = "system_reset", 234 .args_type = "", 235 .mhandler.cmd_new = qmp_marshal_system_reset, 236 }, 237 238SQMP 239system_reset 240------------ 241 242Reset the system. 243 244Arguments: None. 245 246Example: 247 248-> { "execute": "system_reset" } 249<- { "return": {} } 250 251EQMP 252 253 { 254 .name = "system_powerdown", 255 .args_type = "", 256 .mhandler.cmd_new = qmp_marshal_system_powerdown, 257 }, 258 259SQMP 260system_powerdown 261---------------- 262 263Send system power down event. 264 265Arguments: None. 266 267Example: 268 269-> { "execute": "system_powerdown" } 270<- { "return": {} } 271 272EQMP 273 274 { 275 .name = "device_add", 276 .args_type = "device:O", 277 .params = "driver[,prop=value][,...]", 278 .help = "add device, like -device on the command line", 279 .mhandler.cmd_new = qmp_device_add, 280 }, 281 282SQMP 283device_add 284---------- 285 286Add a device. 287 288Arguments: 289 290- "driver": the name of the new device's driver (json-string) 291- "bus": the device's parent bus (device tree path, json-string, optional) 292- "id": the device's ID, must be unique (json-string) 293- device properties 294 295Example: 296 297-> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } } 298<- { "return": {} } 299 300Notes: 301 302(1) For detailed information about this command, please refer to the 303 'docs/qdev-device-use.txt' file. 304 305(2) It's possible to list device properties by running QEMU with the 306 "-device DEVICE,\?" command-line argument, where DEVICE is the device's name 307 308EQMP 309 310 { 311 .name = "device_del", 312 .args_type = "id:s", 313 .mhandler.cmd_new = qmp_marshal_device_del, 314 }, 315 316SQMP 317device_del 318---------- 319 320Remove a device. 321 322Arguments: 323 324- "id": the device's ID or QOM path (json-string) 325 326Example: 327 328-> { "execute": "device_del", "arguments": { "id": "net1" } } 329<- { "return": {} } 330 331Example: 332 333-> { "execute": "device_del", "arguments": { "id": "/machine/peripheral-anon/device[0]" } } 334<- { "return": {} } 335 336EQMP 337 338 { 339 .name = "send-key", 340 .args_type = "keys:q,hold-time:i?", 341 .mhandler.cmd_new = qmp_marshal_send_key, 342 }, 343 344SQMP 345send-key 346---------- 347 348Send keys to VM. 349 350Arguments: 351 352keys array: 353 - "key": key sequence (a json-array of key union values, 354 union can be number or qcode enum) 355 356- hold-time: time to delay key up events, milliseconds. Defaults to 100 357 (json-int, optional) 358 359Example: 360 361-> { "execute": "send-key", 362 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, 363 { "type": "qcode", "data": "alt" }, 364 { "type": "qcode", "data": "delete" } ] } } 365<- { "return": {} } 366 367EQMP 368 369 { 370 .name = "cpu", 371 .args_type = "index:i", 372 .mhandler.cmd_new = qmp_marshal_cpu, 373 }, 374 375SQMP 376cpu 377--- 378 379Set the default CPU. 380 381Arguments: 382 383- "index": the CPU's index (json-int) 384 385Example: 386 387-> { "execute": "cpu", "arguments": { "index": 0 } } 388<- { "return": {} } 389 390Note: CPUs' indexes are obtained with the 'query-cpus' command. 391 392EQMP 393 394 { 395 .name = "cpu-add", 396 .args_type = "id:i", 397 .mhandler.cmd_new = qmp_marshal_cpu_add, 398 }, 399 400SQMP 401cpu-add 402------- 403 404Adds virtual cpu 405 406Arguments: 407 408- "id": cpu id (json-int) 409 410Example: 411 412-> { "execute": "cpu-add", "arguments": { "id": 2 } } 413<- { "return": {} } 414 415EQMP 416 417 { 418 .name = "memsave", 419 .args_type = "val:l,size:i,filename:s,cpu:i?", 420 .mhandler.cmd_new = qmp_marshal_memsave, 421 }, 422 423SQMP 424memsave 425------- 426 427Save to disk virtual memory dump starting at 'val' of size 'size'. 428 429Arguments: 430 431- "val": the starting address (json-int) 432- "size": the memory size, in bytes (json-int) 433- "filename": file path (json-string) 434- "cpu": virtual CPU index (json-int, optional) 435 436Example: 437 438-> { "execute": "memsave", 439 "arguments": { "val": 10, 440 "size": 100, 441 "filename": "/tmp/virtual-mem-dump" } } 442<- { "return": {} } 443 444EQMP 445 446 { 447 .name = "pmemsave", 448 .args_type = "val:l,size:i,filename:s", 449 .mhandler.cmd_new = qmp_marshal_pmemsave, 450 }, 451 452SQMP 453pmemsave 454-------- 455 456Save to disk physical memory dump starting at 'val' of size 'size'. 457 458Arguments: 459 460- "val": the starting address (json-int) 461- "size": the memory size, in bytes (json-int) 462- "filename": file path (json-string) 463 464Example: 465 466-> { "execute": "pmemsave", 467 "arguments": { "val": 10, 468 "size": 100, 469 "filename": "/tmp/physical-mem-dump" } } 470<- { "return": {} } 471 472EQMP 473 474 { 475 .name = "inject-nmi", 476 .args_type = "", 477 .mhandler.cmd_new = qmp_marshal_inject_nmi, 478 }, 479 480SQMP 481inject-nmi 482---------- 483 484Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64). 485 486Arguments: None. 487 488Example: 489 490-> { "execute": "inject-nmi" } 491<- { "return": {} } 492 493Note: inject-nmi fails when the guest doesn't support injecting. 494 495EQMP 496 497 { 498 .name = "ringbuf-write", 499 .args_type = "device:s,data:s,format:s?", 500 .mhandler.cmd_new = qmp_marshal_ringbuf_write, 501 }, 502 503SQMP 504ringbuf-write 505------------- 506 507Write to a ring buffer character device. 508 509Arguments: 510 511- "device": ring buffer character device name (json-string) 512- "data": data to write (json-string) 513- "format": data format (json-string, optional) 514 - Possible values: "utf8" (default), "base64" 515 516Example: 517 518-> { "execute": "ringbuf-write", 519 "arguments": { "device": "foo", 520 "data": "abcdefgh", 521 "format": "utf8" } } 522<- { "return": {} } 523 524EQMP 525 526 { 527 .name = "ringbuf-read", 528 .args_type = "device:s,size:i,format:s?", 529 .mhandler.cmd_new = qmp_marshal_ringbuf_read, 530 }, 531 532SQMP 533ringbuf-read 534------------- 535 536Read from a ring buffer character device. 537 538Arguments: 539 540- "device": ring buffer character device name (json-string) 541- "size": how many bytes to read at most (json-int) 542 - Number of data bytes, not number of characters in encoded data 543- "format": data format (json-string, optional) 544 - Possible values: "utf8" (default), "base64" 545 - Naturally, format "utf8" works only when the ring buffer 546 contains valid UTF-8 text. Invalid UTF-8 sequences get 547 replaced. Bug: replacement doesn't work. Bug: can screw 548 up on encountering NUL characters, after the ring buffer 549 lost data, and when reading stops because the size limit 550 is reached. 551 552Example: 553 554-> { "execute": "ringbuf-read", 555 "arguments": { "device": "foo", 556 "size": 1000, 557 "format": "utf8" } } 558<- {"return": "abcdefgh"} 559 560EQMP 561 562 { 563 .name = "xen-save-devices-state", 564 .args_type = "filename:F", 565 .mhandler.cmd_new = qmp_marshal_xen_save_devices_state, 566 }, 567 568SQMP 569xen-save-devices-state 570------- 571 572Save the state of all devices to file. The RAM and the block devices 573of the VM are not saved by this command. 574 575Arguments: 576 577- "filename": the file to save the state of the devices to as binary 578data. See xen-save-devices-state.txt for a description of the binary 579format. 580 581Example: 582 583-> { "execute": "xen-save-devices-state", 584 "arguments": { "filename": "/tmp/save" } } 585<- { "return": {} } 586 587EQMP 588 589 { 590 .name = "xen-set-global-dirty-log", 591 .args_type = "enable:b", 592 .mhandler.cmd_new = qmp_marshal_xen_set_global_dirty_log, 593 }, 594 595SQMP 596xen-set-global-dirty-log 597------- 598 599Enable or disable the global dirty log mode. 600 601Arguments: 602 603- "enable": Enable it or disable it. 604 605Example: 606 607-> { "execute": "xen-set-global-dirty-log", 608 "arguments": { "enable": true } } 609<- { "return": {} } 610 611EQMP 612 613 { 614 .name = "migrate", 615 .args_type = "detach:-d,blk:-b,inc:-i,uri:s", 616 .mhandler.cmd_new = qmp_marshal_migrate, 617 }, 618 619SQMP 620migrate 621------- 622 623Migrate to URI. 624 625Arguments: 626 627- "blk": block migration, full disk copy (json-bool, optional) 628- "inc": incremental disk copy (json-bool, optional) 629- "uri": Destination URI (json-string) 630 631Example: 632 633-> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } 634<- { "return": {} } 635 636Notes: 637 638(1) The 'query-migrate' command should be used to check migration's progress 639 and final result (this information is provided by the 'status' member) 640(2) All boolean arguments default to false 641(3) The user Monitor's "detach" argument is invalid in QMP and should not 642 be used 643 644EQMP 645 646 { 647 .name = "migrate_cancel", 648 .args_type = "", 649 .mhandler.cmd_new = qmp_marshal_migrate_cancel, 650 }, 651 652SQMP 653migrate_cancel 654-------------- 655 656Cancel the current migration. 657 658Arguments: None. 659 660Example: 661 662-> { "execute": "migrate_cancel" } 663<- { "return": {} } 664 665EQMP 666 667 { 668 .name = "migrate-incoming", 669 .args_type = "uri:s", 670 .mhandler.cmd_new = qmp_marshal_migrate_incoming, 671 }, 672 673SQMP 674migrate-incoming 675---------------- 676 677Continue an incoming migration 678 679Arguments: 680 681- "uri": Source/listening URI (json-string) 682 683Example: 684 685-> { "execute": "migrate-incoming", "arguments": { "uri": "tcp::4446" } } 686<- { "return": {} } 687 688Notes: 689 690(1) QEMU must be started with -incoming defer to allow migrate-incoming to 691 be used 692(2) The uri format is the same as for -incoming 693 694EQMP 695 { 696 .name = "migrate-set-cache-size", 697 .args_type = "value:o", 698 .mhandler.cmd_new = qmp_marshal_migrate_set_cache_size, 699 }, 700 701SQMP 702migrate-set-cache-size 703---------------------- 704 705Set cache size to be used by XBZRLE migration, the cache size will be rounded 706down to the nearest power of 2 707 708Arguments: 709 710- "value": cache size in bytes (json-int) 711 712Example: 713 714-> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } } 715<- { "return": {} } 716 717EQMP 718 { 719 .name = "migrate-start-postcopy", 720 .args_type = "", 721 .mhandler.cmd_new = qmp_marshal_migrate_start_postcopy, 722 }, 723 724SQMP 725migrate-start-postcopy 726---------------------- 727 728Switch an in-progress migration to postcopy mode. Ignored after the end of 729migration (or once already in postcopy). 730 731Example: 732-> { "execute": "migrate-start-postcopy" } 733<- { "return": {} } 734 735EQMP 736 737 { 738 .name = "query-migrate-cache-size", 739 .args_type = "", 740 .mhandler.cmd_new = qmp_marshal_query_migrate_cache_size, 741 }, 742 743SQMP 744query-migrate-cache-size 745------------------------ 746 747Show cache size to be used by XBZRLE migration 748 749returns a json-object with the following information: 750- "size" : json-int 751 752Example: 753 754-> { "execute": "query-migrate-cache-size" } 755<- { "return": 67108864 } 756 757EQMP 758 759 { 760 .name = "migrate_set_speed", 761 .args_type = "value:o", 762 .mhandler.cmd_new = qmp_marshal_migrate_set_speed, 763 }, 764 765SQMP 766migrate_set_speed 767----------------- 768 769Set maximum speed for migrations. 770 771Arguments: 772 773- "value": maximum speed, in bytes per second (json-int) 774 775Example: 776 777-> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } } 778<- { "return": {} } 779 780EQMP 781 782 { 783 .name = "migrate_set_downtime", 784 .args_type = "value:T", 785 .mhandler.cmd_new = qmp_marshal_migrate_set_downtime, 786 }, 787 788SQMP 789migrate_set_downtime 790-------------------- 791 792Set maximum tolerated downtime (in seconds) for migrations. 793 794Arguments: 795 796- "value": maximum downtime (json-number) 797 798Example: 799 800-> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } } 801<- { "return": {} } 802 803EQMP 804 805 { 806 .name = "client_migrate_info", 807 .args_type = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?", 808 .params = "protocol hostname port tls-port cert-subject", 809 .help = "set migration information for remote display", 810 .mhandler.cmd_new = qmp_marshal_client_migrate_info, 811 }, 812 813SQMP 814client_migrate_info 815------------------- 816 817Set migration information for remote display. This makes the server 818ask the client to automatically reconnect using the new parameters 819once migration finished successfully. Only implemented for SPICE. 820 821Arguments: 822 823- "protocol": must be "spice" (json-string) 824- "hostname": migration target hostname (json-string) 825- "port": spice tcp port for plaintext channels (json-int, optional) 826- "tls-port": spice tcp port for tls-secured channels (json-int, optional) 827- "cert-subject": server certificate subject (json-string, optional) 828 829Example: 830 831-> { "execute": "client_migrate_info", 832 "arguments": { "protocol": "spice", 833 "hostname": "virt42.lab.kraxel.org", 834 "port": 1234 } } 835<- { "return": {} } 836 837EQMP 838 839 { 840 .name = "dump-guest-memory", 841 .args_type = "paging:b,protocol:s,detach:b?,begin:i?,end:i?,format:s?", 842 .params = "-p protocol [-d] [begin] [length] [format]", 843 .help = "dump guest memory to file", 844 .mhandler.cmd_new = qmp_marshal_dump_guest_memory, 845 }, 846 847SQMP 848dump 849 850 851Dump guest memory to file. The file can be processed with crash or gdb. 852 853Arguments: 854 855- "paging": do paging to get guest's memory mapping (json-bool) 856- "protocol": destination file(started with "file:") or destination file 857 descriptor (started with "fd:") (json-string) 858- "detach": if specified, command will return immediately, without waiting 859 for the dump to finish. The user can track progress using 860 "query-dump". (json-bool) 861- "begin": the starting physical address. It's optional, and should be specified 862 with length together (json-int) 863- "length": the memory size, in bytes. It's optional, and should be specified 864 with begin together (json-int) 865- "format": the format of guest memory dump. It's optional, and can be 866 elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will 867 conflict with paging and filter, ie. begin and length (json-string) 868 869Example: 870 871-> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } } 872<- { "return": {} } 873 874Notes: 875 876(1) All boolean arguments default to false 877 878EQMP 879 880 { 881 .name = "query-dump-guest-memory-capability", 882 .args_type = "", 883 .mhandler.cmd_new = qmp_marshal_query_dump_guest_memory_capability, 884 }, 885 886SQMP 887query-dump-guest-memory-capability 888---------- 889 890Show available formats for 'dump-guest-memory' 891 892Example: 893 894-> { "execute": "query-dump-guest-memory-capability" } 895<- { "return": { "formats": 896 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } 897 898EQMP 899 900 { 901 .name = "query-dump", 902 .args_type = "", 903 .params = "", 904 .help = "query background dump status", 905 .mhandler.cmd_new = qmp_marshal_query_dump, 906 }, 907 908SQMP 909query-dump 910---------- 911 912Query background dump status. 913 914Arguments: None. 915 916Example: 917 918-> { "execute": "query-dump" } 919<- { "return": { "status": "active", "completed": 1024000, 920 "total": 2048000 } } 921 922EQMP 923 924#if defined TARGET_S390X 925 { 926 .name = "dump-skeys", 927 .args_type = "filename:F", 928 .mhandler.cmd_new = qmp_marshal_dump_skeys, 929 }, 930#endif 931 932SQMP 933dump-skeys 934---------- 935 936Save guest storage keys to file. 937 938Arguments: 939 940- "filename": file path (json-string) 941 942Example: 943 944-> { "execute": "dump-skeys", "arguments": { "filename": "/tmp/skeys" } } 945<- { "return": {} } 946 947EQMP 948 949 { 950 .name = "netdev_add", 951 .args_type = "netdev:O", 952 .mhandler.cmd_new = qmp_netdev_add, 953 }, 954 955SQMP 956netdev_add 957---------- 958 959Add host network device. 960 961Arguments: 962 963- "type": the device type, "tap", "user", ... (json-string) 964- "id": the device's ID, must be unique (json-string) 965- device options 966 967Example: 968 969-> { "execute": "netdev_add", 970 "arguments": { "type": "user", "id": "netdev1", 971 "dnssearch": "example.org" } } 972<- { "return": {} } 973 974Note: The supported device options are the same ones supported by the '-netdev' 975 command-line argument, which are listed in the '-help' output or QEMU's 976 manual 977 978EQMP 979 980 { 981 .name = "netdev_del", 982 .args_type = "id:s", 983 .mhandler.cmd_new = qmp_marshal_netdev_del, 984 }, 985 986SQMP 987netdev_del 988---------- 989 990Remove host network device. 991 992Arguments: 993 994- "id": the device's ID, must be unique (json-string) 995 996Example: 997 998-> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } 999<- { "return": {} } 1000
1001 1002EQMP 1003 1004 { 1005 .name = "object-add", 1006 .args_type = "qom-type:s,id:s,props:q?", 1007 .mhandler.cmd_new = qmp_marshal_object_add, 1008 }, 1009 1010SQMP 1011object-add 1012---------- 1013 1014Create QOM object. 1015 1016Arguments: 1017 1018- "qom-type": the object's QOM type, i.e. the class name (json-string) 1019- "id": the object's ID, must be unique (json-string) 1020- "props": a dictionary of object property values (optional, json-dict) 1021 1022Example: 1023 1024-> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1", 1025 "props": { "filename": "/dev/hwrng" } } } 1026<- { "return": {} } 1027 1028EQMP 1029 1030 { 1031 .name = "object-del", 1032 .args_type = "id:s", 1033 .mhandler.cmd_new = qmp_marshal_object_del, 1034 }, 1035 1036SQMP 1037object-del 1038---------- 1039 1040Remove QOM object. 1041 1042Arguments: 1043 1044- "id": the object's ID (json-string) 1045 1046Example: 1047 1048-> { "execute": "object-del", "arguments": { "id": "rng1" } } 1049<- { "return": {} } 1050 1051 1052EQMP 1053 1054 1055 { 1056 .name = "block_resize", 1057 .args_type = "device:s?,node-name:s?,size:o", 1058 .mhandler.cmd_new = qmp_marshal_block_resize, 1059 }, 1060 1061SQMP 1062block_resize 1063------------ 1064 1065Resize a block image while a guest is running. 1066 1067Arguments: 1068 1069- "device": the device's ID, must be unique (json-string) 1070- "node-name": the node name in the block driver state graph (json-string) 1071- "size": new size 1072 1073Example: 1074 1075-> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } } 1076<- { "return": {} } 1077 1078EQMP 1079 1080 { 1081 .name = "block-stream", 1082 .args_type = "device:B,base:s?,speed:o?,backing-file:s?,on-error:s?", 1083 .mhandler.cmd_new = qmp_marshal_block_stream, 1084 }, 1085 1086SQMP 1087block-stream 1088------------ 1089 1090Copy data from a backing file into a block device. 1091 1092Arguments: 1093 1094- "device": The device's ID, must be unique (json-string) 1095- "base": The file name of the backing image above which copying starts 1096 (json-string, optional) 1097- "backing-file": The backing file string to write into the active layer. This 1098 filename is not validated. 1099 1100 If a pathname string is such that it cannot be resolved by 1101 QEMU, that means that subsequent QMP or HMP commands must use 1102 node-names for the image in question, as filename lookup 1103 methods will fail. 1104 1105 If not specified, QEMU will automatically determine the 1106 backing file string to use, or error out if there is no 1107 obvious choice. Care should be taken when specifying the 1108 string, to specify a valid filename or protocol. 1109 (json-string, optional) (Since 2.1) 1110- "speed": the maximum speed, in bytes per second (json-int, optional) 1111- "on-error": the action to take on an error (default 'report'). 'stop' and 1112 'enospc' can only be used if the block device supports io-status. 1113 (json-string, optional) (Since 2.1) 1114 1115Example: 1116 1117-> { "execute": "block-stream", "arguments": { "device": "virtio0", 1118 "base": "/tmp/master.qcow2" } } 1119<- { "return": {} } 1120 1121EQMP 1122 1123 { 1124 .name = "block-commit", 1125 .args_type = "device:B,base:s?,top:s?,backing-file:s?,speed:o?", 1126 .mhandler.cmd_new = qmp_marshal_block_commit, 1127 }, 1128 1129SQMP 1130block-commit 1131------------ 1132 1133Live commit of data from overlay image nodes into backing nodes - i.e., writes 1134data between 'top' and 'base' into 'base'. 1135 1136Arguments: 1137 1138- "device": The device's ID, must be unique (json-string) 1139- "base": The file name of the backing image to write data into. 1140 If not specified, this is the deepest backing image 1141 (json-string, optional) 1142- "top": The file name of the backing image within the image chain, 1143 which contains the topmost data to be committed down. If 1144 not specified, this is the active layer. (json-string, optional) 1145 1146- backing-file: The backing file string to write into the overlay 1147 image of 'top'. If 'top' is the active layer, 1148 specifying a backing file string is an error. This 1149 filename is not validated. 1150 1151 If a pathname string is such that it cannot be 1152 resolved by QEMU, that means that subsequent QMP or 1153 HMP commands must use node-names for the image in 1154 question, as filename lookup methods will fail. 1155 1156 If not specified, QEMU will automatically determine 1157 the backing file string to use, or error out if 1158 there is no obvious choice. Care should be taken 1159 when specifying the string, to specify a valid 1160 filename or protocol. 1161 (json-string, optional) (Since 2.1) 1162 1163 If top == base, that is an error. 1164 If top == active, the job will not be completed by itself, 1165 user needs to complete the job with the block-job-complete 1166 command after getting the ready event. (Since 2.0) 1167 1168 If the base image is smaller than top, then the base image 1169 will be resized to be the same size as top. If top is 1170 smaller than the base image, the base will not be 1171 truncated. If you want the base image size to match the 1172 size of the smaller top, you can safely truncate it 1173 yourself once the commit operation successfully completes. 1174 (json-string) 1175- "speed": the maximum speed, in bytes per second (json-int, optional) 1176 1177 1178Example: 1179 1180-> { "execute": "block-commit", "arguments": { "device": "virtio0", 1181 "top": "/tmp/snap1.qcow2" } } 1182<- { "return": {} } 1183 1184EQMP 1185 1186 { 1187 .name = "drive-backup", 1188 .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?," 1189 "bitmap:s?,on-source-error:s?,on-target-error:s?", 1190 .mhandler.cmd_new = qmp_marshal_drive_backup, 1191 }, 1192 1193SQMP 1194drive-backup 1195------------ 1196 1197Start a point-in-time copy of a block device to a new destination. The 1198status of ongoing drive-backup operations can be checked with 1199query-block-jobs where the BlockJobInfo.type field has the value 'backup'. 1200The operation can be stopped before it has completed using the 1201block-job-cancel command. 1202 1203Arguments: 1204 1205- "device": the name of the device which should be copied. 1206 (json-string) 1207- "target": the target of the new image. If the file exists, or if it is a 1208 device, the existing file/device will be used as the new 1209 destination. If it does not exist, a new file will be created. 1210 (json-string) 1211- "format": the format of the new destination, default is to probe if 'mode' is 1212 'existing', else the format of the source 1213 (json-string, optional) 1214- "sync": what parts of the disk image should be copied to the destination; 1215 possibilities include "full" for all the disk, "top" for only the sectors 1216 allocated in the topmost image, "incremental" for only the dirty sectors in 1217 the bitmap, or "none" to only replicate new I/O (MirrorSyncMode). 1218- "bitmap": dirty bitmap name for sync==incremental. Must be present if sync 1219 is "incremental", must NOT be present otherwise. 1220- "mode": whether and how QEMU should create a new image 1221 (NewImageMode, optional, default 'absolute-paths') 1222- "speed": the maximum speed, in bytes per second (json-int, optional) 1223- "on-source-error": the action to take on an error on the source, default 1224 'report'. 'stop' and 'enospc' can only be used 1225 if the block device supports io-status. 1226 (BlockdevOnError, optional) 1227- "on-target-error": the action to take on an error on the target, default 1228 'report' (no limitations, since this applies to 1229 a different block device than device). 1230 (BlockdevOnError, optional) 1231 1232Example: 1233-> { "execute": "drive-backup", "arguments": { "device": "drive0", 1234 "sync": "full", 1235 "target": "backup.img" } } 1236<- { "return": {} } 1237 1238EQMP 1239 1240 { 1241 .name = "blockdev-backup", 1242 .args_type = "sync:s,device:B,target:B,speed:i?," 1243 "on-source-error:s?,on-target-error:s?", 1244 .mhandler.cmd_new = qmp_marshal_blockdev_backup, 1245 }, 1246 1247SQMP 1248blockdev-backup 1249--------------- 1250 1251The device version of drive-backup: this command takes an existing named device 1252as backup target. 1253 1254Arguments: 1255 1256- "device": the name of the device which should be copied. 1257 (json-string) 1258- "target": the name of the backup target device. (json-string) 1259- "sync": what parts of the disk image should be copied to the destination; 1260 possibilities include "full" for all the disk, "top" for only the 1261 sectors allocated in the topmost image, or "none" to only replicate 1262 new I/O (MirrorSyncMode). 1263- "speed": the maximum speed, in bytes per second (json-int, optional) 1264- "on-source-error": the action to take on an error on the source, default 1265 'report'. 'stop' and 'enospc' can only be used 1266 if the block device supports io-status. 1267 (BlockdevOnError, optional) 1268- "on-target-error": the action to take on an error on the target, default 1269 'report' (no limitations, since this applies to 1270 a different block device than device). 1271 (BlockdevOnError, optional) 1272 1273Example: 1274-> { "execute": "blockdev-backup", "arguments": { "device": "src-id", 1275 "sync": "full", 1276 "target": "tgt-id" } } 1277<- { "return": {} } 1278 1279EQMP 1280 1281 { 1282 .name = "block-job-set-speed", 1283 .args_type = "device:B,speed:o", 1284 .mhandler.cmd_new = qmp_marshal_block_job_set_speed, 1285 }, 1286 1287 { 1288 .name = "block-job-cancel", 1289 .args_type = "device:B,force:b?", 1290 .mhandler.cmd_new = qmp_marshal_block_job_cancel, 1291 }, 1292 { 1293 .name = "block-job-pause", 1294 .args_type = "device:B", 1295 .mhandler.cmd_new = qmp_marshal_block_job_pause, 1296 }, 1297 { 1298 .name = "block-job-resume", 1299 .args_type = "device:B", 1300 .mhandler.cmd_new = qmp_marshal_block_job_resume, 1301 }, 1302 { 1303 .name = "block-job-complete", 1304 .args_type = "device:B", 1305 .mhandler.cmd_new = qmp_marshal_block_job_complete, 1306 }, 1307 { 1308 .name = "transaction", 1309 .args_type = "actions:q,properties:q?", 1310 .mhandler.cmd_new = qmp_marshal_transaction, 1311 }, 1312 1313SQMP 1314transaction 1315----------- 1316 1317Atomically operate on one or more block devices. Operations that are 1318currently supported: 1319 1320 - drive-backup 1321 - blockdev-backup 1322 - blockdev-snapshot-sync 1323 - blockdev-snapshot-internal-sync 1324 - abort 1325 - block-dirty-bitmap-add 1326 - block-dirty-bitmap-clear 1327 1328Refer to the qemu/qapi-schema.json file for minimum required QEMU 1329versions for these operations. A list of dictionaries is accepted, 1330that contains the actions to be performed. If there is any failure 1331performing any of the operations, all operations for the group are 1332abandoned. 1333 1334For external snapshots, the dictionary contains the device, the file to use for 1335the new snapshot, and the format. The default format, if not specified, is 1336qcow2. 1337 1338Each new snapshot defaults to being created by QEMU (wiping any 1339contents if the file already exists), but it is also possible to reuse 1340an externally-created file. In the latter case, you should ensure that 1341the new image file has the same contents as the current one; QEMU cannot 1342perform any meaningful check. Typically this is achieved by using the 1343current image file as the backing file for the new image. 1344 1345On failure, the original disks pre-snapshot attempt will be used. 1346 1347For internal snapshots, the dictionary contains the device and the snapshot's 1348name. If an internal snapshot matching name already exists, the request will 1349be rejected. Only some image formats support it, for example, qcow2, rbd, 1350and sheepdog. 1351 1352On failure, qemu will try delete the newly created internal snapshot in the 1353transaction. When an I/O error occurs during deletion, the user needs to fix 1354it later with qemu-img or other command. 1355 1356Arguments: 1357 1358actions array: 1359 - "type": the operation to perform (json-string). Possible 1360 values: "drive-backup", "blockdev-backup", 1361 "blockdev-snapshot-sync", 1362 "blockdev-snapshot-internal-sync", 1363 "abort", "block-dirty-bitmap-add", 1364 "block-dirty-bitmap-clear" 1365 - "data": a dictionary. The contents depend on the value 1366 of "type". When "type" is "blockdev-snapshot-sync": 1367 - "device": device name to snapshot (json-string) 1368 - "node-name": graph node name to snapshot (json-string) 1369 - "snapshot-file": name of new image file (json-string) 1370 - "snapshot-node-name": graph node name of the new snapshot (json-string) 1371 - "format": format of new image (json-string, optional) 1372 - "mode": whether and how QEMU should create the snapshot file 1373 (NewImageMode, optional, default "absolute-paths") 1374 When "type" is "blockdev-snapshot-internal-sync": 1375 - "device": device name to snapshot (json-string) 1376 - "name": name of the new snapshot (json-string) 1377 1378Example: 1379 1380-> { "execute": "transaction", 1381 "arguments": { "actions": [ 1382 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0", 1383 "snapshot-file": "/some/place/my-image", 1384 "format": "qcow2" } }, 1385 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile", 1386 "snapshot-file": "/some/place/my-image2", 1387 "snapshot-node-name": "node3432", 1388 "mode": "existing", 1389 "format": "qcow2" } }, 1390 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1", 1391 "snapshot-file": "/some/place/my-image2", 1392 "mode": "existing", 1393 "format": "qcow2" } }, 1394 { "type": "blockdev-snapshot-internal-sync", "data" : { 1395 "device": "ide-hd2", 1396 "name": "snapshot0" } } ] } } 1397<- { "return": {} } 1398 1399EQMP 1400 1401 { 1402 .name = "block-dirty-bitmap-add", 1403 .args_type = "node:B,name:s,granularity:i?", 1404 .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_add, 1405 }, 1406 1407SQMP 1408 1409block-dirty-bitmap-add 1410---------------------- 1411Since 2.4 1412 1413Create a dirty bitmap with a name on the device, and start tracking the writes. 1414 1415Arguments: 1416 1417- "node": device/node on which to create dirty bitmap (json-string) 1418- "name": name of the new dirty bitmap (json-string) 1419- "granularity": granularity to track writes with (int, optional) 1420 1421Example: 1422 1423-> { "execute": "block-dirty-bitmap-add", "arguments": { "node": "drive0", 1424 "name": "bitmap0" } } 1425<- { "return": {} } 1426 1427EQMP 1428 1429 { 1430 .name = "block-dirty-bitmap-remove", 1431 .args_type = "node:B,name:s", 1432 .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_remove, 1433 }, 1434 1435SQMP 1436 1437block-dirty-bitmap-remove 1438------------------------- 1439Since 2.4 1440 1441Stop write tracking and remove the dirty bitmap that was created with 1442block-dirty-bitmap-add. 1443 1444Arguments: 1445 1446- "node": device/node on which to remove dirty bitmap (json-string) 1447- "name": name of the dirty bitmap to remove (json-string) 1448 1449Example: 1450 1451-> { "execute": "block-dirty-bitmap-remove", "arguments": { "node": "drive0", 1452 "name": "bitmap0" } } 1453<- { "return": {} } 1454 1455EQMP 1456 1457 { 1458 .name = "block-dirty-bitmap-clear", 1459 .args_type = "node:B,name:s", 1460 .mhandler.cmd_new = qmp_marshal_block_dirty_bitmap_clear, 1461 }, 1462 1463SQMP 1464 1465block-dirty-bitmap-clear 1466------------------------ 1467Since 2.4 1468 1469Reset the dirty bitmap associated with a node so that an incremental backup 1470from this point in time forward will only backup clusters modified after this 1471clear operation. 1472 1473Arguments: 1474 1475- "node": device/node on which to remove dirty bitmap (json-string) 1476- "name": name of the dirty bitmap to remove (json-string) 1477 1478Example: 1479 1480-> { "execute": "block-dirty-bitmap-clear", "arguments": { "node": "drive0", 1481 "name": "bitmap0" } } 1482<- { "return": {} } 1483 1484EQMP 1485 1486 { 1487 .name = "blockdev-snapshot-sync", 1488 .args_type = "device:s?,node-name:s?,snapshot-file:s,snapshot-node-name:s?,format:s?,mode:s?", 1489 .mhandler.cmd_new = qmp_marshal_blockdev_snapshot_sync, 1490 }, 1491 1492SQMP 1493blockdev-snapshot-sync 1494---------------------- 1495 1496Synchronous snapshot of a block device. snapshot-file specifies the 1497target of the new image. If the file exists, or if it is a device, the 1498snapshot will be created in the existing file/device. If does not 1499exist, a new file will be created. format specifies the format of the 1500snapshot image, default is qcow2. 1501 1502Arguments: 1503 1504- "device": device name to snapshot (json-string) 1505- "node-name": graph node name to snapshot (json-string) 1506- "snapshot-file": name of new image file (json-string) 1507- "snapshot-node-name": graph node name of the new snapshot (json-string) 1508- "mode": whether and how QEMU should create the snapshot file 1509 (NewImageMode, optional, default "absolute-paths") 1510- "format": format of new image (json-string, optional) 1511 1512Example: 1513 1514-> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0", 1515 "snapshot-file": 1516 "/some/place/my-image", 1517 "format": "qcow2" } } 1518<- { "return": {} } 1519 1520EQMP 1521 1522 { 1523 .name = "blockdev-snapshot", 1524 .args_type = "node:s,overlay:s", 1525 .mhandler.cmd_new = qmp_marshal_blockdev_snapshot, 1526 }, 1527 1528SQMP 1529blockdev-snapshot 1530----------------- 1531Since 2.5 1532 1533Create a snapshot, by installing 'node' as the backing image of 1534'overlay'. Additionally, if 'node' is associated with a block 1535device, the block device changes to using 'overlay' as its new active 1536image. 1537 1538Arguments: 1539 1540- "node": device that will have a snapshot created (json-string) 1541- "overlay": device that will have 'node' as its backing image (json-string) 1542 1543Example: 1544 1545-> { "execute": "blockdev-add", 1546 "arguments": { "options": { "driver": "qcow2", 1547 "node-name": "node1534", 1548 "file": { "driver": "file", 1549 "filename": "hd1.qcow2" }, 1550 "backing": "" } } } 1551 1552<- { "return": {} } 1553 1554-> { "execute": "blockdev-snapshot", "arguments": { "node": "ide-hd0", 1555 "overlay": "node1534" } } 1556<- { "return": {} } 1557 1558EQMP 1559 1560 { 1561 .name = "blockdev-snapshot-internal-sync", 1562 .args_type = "device:B,name:s", 1563 .mhandler.cmd_new = qmp_marshal_blockdev_snapshot_internal_sync, 1564 }, 1565 1566SQMP 1567blockdev-snapshot-internal-sync 1568------------------------------- 1569 1570Synchronously take an internal snapshot of a block device when the format of 1571image used supports it. If the name is an empty string, or a snapshot with 1572name already exists, the operation will fail. 1573 1574Arguments: 1575 1576- "device": device name to snapshot (json-string) 1577- "name": name of the new snapshot (json-string) 1578 1579Example: 1580 1581-> { "execute": "blockdev-snapshot-internal-sync", 1582 "arguments": { "device": "ide-hd0", 1583 "name": "snapshot0" } 1584 } 1585<- { "return": {} } 1586 1587EQMP 1588 1589 { 1590 .name = "blockdev-snapshot-delete-internal-sync", 1591 .args_type = "device:B,id:s?,name:s?", 1592 .mhandler.cmd_new = 1593 qmp_marshal_blockdev_snapshot_delete_internal_sync, 1594 }, 1595 1596SQMP 1597blockdev-snapshot-delete-internal-sync 1598-------------------------------------- 1599 1600Synchronously delete an internal snapshot of a block device when the format of 1601image used supports it. The snapshot is identified by name or id or both. One 1602of name or id is required. If the snapshot is not found, the operation will 1603fail. 1604 1605Arguments: 1606 1607- "device": device name (json-string) 1608- "id": ID of the snapshot (json-string, optional) 1609- "name": name of the snapshot (json-string, optional) 1610 1611Example: 1612 1613-> { "execute": "blockdev-snapshot-delete-internal-sync", 1614 "arguments": { "device": "ide-hd0", 1615 "name": "snapshot0" } 1616 } 1617<- { "return": { 1618 "id": "1", 1619 "name": "snapshot0", 1620 "vm-state-size": 0, 1621 "date-sec": 1000012, 1622 "date-nsec": 10, 1623 "vm-clock-sec": 100, 1624 "vm-clock-nsec": 20 1625 } 1626 } 1627 1628EQMP 1629 1630 { 1631 .name = "drive-mirror", 1632 .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?," 1633 "node-name:s?,replaces:s?," 1634 "on-source-error:s?,on-target-error:s?," 1635 "unmap:b?," 1636 "granularity:i?,buf-size:i?", 1637 .mhandler.cmd_new = qmp_marshal_drive_mirror, 1638 }, 1639 1640SQMP 1641drive-mirror 1642------------ 1643 1644Start mirroring a block device's writes to a new destination. target 1645specifies the target of the new image. If the file exists, or if it is 1646a device, it will be used as the new destination for writes. If it does not 1647exist, a new file will be created. format specifies the format of the 1648mirror image, default is to probe if mode='existing', else the format 1649of the source. 1650 1651Arguments: 1652 1653- "device": device name to operate on (json-string) 1654- "target": name of new image file (json-string) 1655- "format": format of new image (json-string, optional) 1656- "node-name": the name of the new block driver state in the node graph 1657 (json-string, optional) 1658- "replaces": the block driver node name to replace when finished 1659 (json-string, optional) 1660- "mode": how an image file should be created into the target 1661 file/device (NewImageMode, optional, default 'absolute-paths') 1662- "speed": maximum speed of the streaming job, in bytes per second 1663 (json-int) 1664- "granularity": granularity of the dirty bitmap, in bytes (json-int, optional) 1665- "buf-size": maximum amount of data in flight from source to target, in bytes 1666 (json-int, default 10M) 1667- "sync": what parts of the disk image should be copied to the destination; 1668 possibilities include "full" for all the disk, "top" for only the sectors 1669 allocated in the topmost image, or "none" to only replicate new I/O 1670 (MirrorSyncMode). 1671- "on-source-error": the action to take on an error on the source 1672 (BlockdevOnError, default 'report') 1673- "on-target-error": the action to take on an error on the target 1674 (BlockdevOnError, default 'report') 1675- "unmap": whether the target sectors should be discarded where source has only 1676 zeroes. (json-bool, optional, default true) 1677 1678The default value of the granularity is the image cluster size clamped 1679between 4096 and 65536, if the image format defines one. If the format 1680does not define a cluster size, the default value of the granularity 1681is 65536. 1682 1683 1684Example: 1685 1686-> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0", 1687 "target": "/some/place/my-image", 1688 "sync": "full", 1689 "format": "qcow2" } } 1690<- { "return": {} } 1691 1692EQMP 1693 1694 { 1695 .name = "blockdev-mirror", 1696 .args_type = "sync:s,device:B,target:B,replaces:s?,speed:i?," 1697 "on-source-error:s?,on-target-error:s?," 1698 "granularity:i?,buf-size:i?", 1699 .mhandler.cmd_new = qmp_marshal_blockdev_mirror, 1700 }, 1701 1702SQMP 1703blockdev-mirror 1704------------ 1705 1706Start mirroring a block device's writes to another block device. target 1707specifies the target of mirror operation. 1708 1709Arguments: 1710 1711- "device": device name to operate on (json-string) 1712- "target": device name to mirror to (json-string) 1713- "replaces": the block driver node name to replace when finished 1714 (json-string, optional) 1715- "speed": maximum speed of the streaming job, in bytes per second 1716 (json-int) 1717- "granularity": granularity of the dirty bitmap, in bytes (json-int, optional) 1718- "buf_size": maximum amount of data in flight from source to target, in bytes 1719 (json-int, default 10M) 1720- "sync": what parts of the disk image should be copied to the destination; 1721 possibilities include "full" for all the disk, "top" for only the sectors 1722 allocated in the topmost image, or "none" to only replicate new I/O 1723 (MirrorSyncMode). 1724- "on-source-error": the action to take on an error on the source 1725 (BlockdevOnError, default 'report') 1726- "on-target-error": the action to take on an error on the target 1727 (BlockdevOnError, default 'report') 1728 1729The default value of the granularity is the image cluster size clamped 1730between 4096 and 65536, if the image format defines one. If the format 1731does not define a cluster size, the default value of the granularity 1732is 65536. 1733 1734Example: 1735 1736-> { "execute": "blockdev-mirror", "arguments": { "device": "ide-hd0", 1737 "target": "target0", 1738 "sync": "full" } } 1739<- { "return": {} } 1740 1741EQMP 1742 { 1743 .name = "change-backing-file", 1744 .args_type = "device:s,image-node-name:s,backing-file:s", 1745 .mhandler.cmd_new = qmp_marshal_change_backing_file, 1746 }, 1747 1748SQMP 1749change-backing-file 1750------------------- 1751Since: 2.1 1752 1753Change the backing file in the image file metadata. This does not cause 1754QEMU to reopen the image file to reparse the backing filename (it may, 1755however, perform a reopen to change permissions from r/o -> r/w -> r/o, 1756if needed). The new backing file string is written into the image file 1757metadata, and the QEMU internal strings are updated. 1758 1759Arguments: 1760 1761- "image-node-name": The name of the block driver state node of the 1762 image to modify. The "device" is argument is used to 1763 verify "image-node-name" is in the chain described by 1764 "device". 1765 (json-string, optional) 1766 1767- "device": The name of the device. 1768 (json-string) 1769 1770- "backing-file": The string to write as the backing file. This string is 1771 not validated, so care should be taken when specifying 1772 the string or the image chain may not be able to be 1773 reopened again. 1774 (json-string) 1775 1776Returns: Nothing on success 1777 If "device" does not exist or cannot be determined, DeviceNotFound 1778 1779EQMP 1780 1781 { 1782 .name = "balloon", 1783 .args_type = "value:M", 1784 .mhandler.cmd_new = qmp_marshal_balloon, 1785 }, 1786 1787SQMP 1788balloon 1789------- 1790 1791Request VM to change its memory allocation (in bytes). 1792 1793Arguments: 1794 1795- "value": New memory allocation (json-int) 1796 1797Example: 1798 1799-> { "execute": "balloon", "arguments": { "value": 536870912 } } 1800<- { "return": {} } 1801 1802EQMP 1803 1804 { 1805 .name = "set_link", 1806 .args_type = "name:s,up:b", 1807 .mhandler.cmd_new = qmp_marshal_set_link, 1808 }, 1809 1810SQMP 1811set_link 1812-------- 1813 1814Change the link status of a network adapter. 1815 1816Arguments: 1817 1818- "name": network device name (json-string) 1819- "up": status is up (json-bool) 1820 1821Example: 1822 1823-> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } } 1824<- { "return": {} } 1825 1826EQMP 1827 1828 { 1829 .name = "getfd", 1830 .args_type = "fdname:s", 1831 .params = "getfd name", 1832 .help = "receive a file descriptor via SCM rights and assign it a name", 1833 .mhandler.cmd_new = qmp_marshal_getfd, 1834 }, 1835 1836SQMP 1837getfd 1838----- 1839 1840Receive a file descriptor via SCM rights and assign it a name. 1841 1842Arguments: 1843 1844- "fdname": file descriptor name (json-string) 1845 1846Example: 1847 1848-> { "execute": "getfd", "arguments": { "fdname": "fd1" } } 1849<- { "return": {} } 1850 1851Notes: 1852 1853(1) If the name specified by the "fdname" argument already exists, 1854 the file descriptor assigned to it will be closed and replaced 1855 by the received file descriptor. 1856(2) The 'closefd' command can be used to explicitly close the file 1857 descriptor when it is no longer needed. 1858 1859EQMP 1860 1861 { 1862 .name = "closefd", 1863 .args_type = "fdname:s", 1864 .params = "closefd name", 1865 .help = "close a file descriptor previously passed via SCM rights", 1866 .mhandler.cmd_new = qmp_marshal_closefd, 1867 }, 1868 1869SQMP 1870closefd 1871------- 1872 1873Close a file descriptor previously passed via SCM rights. 1874 1875Arguments: 1876 1877- "fdname": file descriptor name (json-string) 1878 1879Example: 1880 1881-> { "execute": "closefd", "arguments": { "fdname": "fd1" } } 1882<- { "return": {} } 1883 1884EQMP 1885 1886 { 1887 .name = "add-fd", 1888 .args_type = "fdset-id:i?,opaque:s?", 1889 .params = "add-fd fdset-id opaque", 1890 .help = "Add a file descriptor, that was passed via SCM rights, to an fd set", 1891 .mhandler.cmd_new = qmp_marshal_add_fd, 1892 }, 1893 1894SQMP 1895add-fd 1896------- 1897 1898Add a file descriptor, that was passed via SCM rights, to an fd set. 1899 1900Arguments: 1901 1902- "fdset-id": The ID of the fd set to add the file descriptor to. 1903 (json-int, optional) 1904- "opaque": A free-form string that can be used to describe the fd. 1905 (json-string, optional) 1906 1907Return a json-object with the following information: 1908 1909- "fdset-id": The ID of the fd set that the fd was added to. (json-int) 1910- "fd": The file descriptor that was received via SCM rights and added to the 1911 fd set. (json-int) 1912 1913Example: 1914 1915-> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } 1916<- { "return": { "fdset-id": 1, "fd": 3 } } 1917 1918Notes: 1919 1920(1) The list of fd sets is shared by all monitor connections. 1921(2) If "fdset-id" is not specified, a new fd set will be created. 1922 1923EQMP 1924 1925 { 1926 .name = "remove-fd", 1927 .args_type = "fdset-id:i,fd:i?", 1928 .params = "remove-fd fdset-id fd", 1929 .help = "Remove a file descriptor from an fd set", 1930 .mhandler.cmd_new = qmp_marshal_remove_fd, 1931 }, 1932 1933SQMP 1934remove-fd 1935--------- 1936 1937Remove a file descriptor from an fd set. 1938 1939Arguments: 1940 1941- "fdset-id": The ID of the fd set that the file descriptor belongs to. 1942 (json-int) 1943- "fd": The file descriptor that is to be removed. (json-int, optional) 1944 1945Example: 1946 1947-> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } 1948<- { "return": {} } 1949 1950Notes: 1951 1952(1) The list of fd sets is shared by all monitor connections. 1953(2) If "fd" is not specified, all file descriptors in "fdset-id" will be 1954 removed. 1955 1956EQMP 1957 1958 { 1959 .name = "query-fdsets", 1960 .args_type = "", 1961 .help = "Return information describing all fd sets", 1962 .mhandler.cmd_new = qmp_marshal_query_fdsets, 1963 }, 1964 1965SQMP 1966query-fdsets 1967------------- 1968 1969Return information describing all fd sets. 1970 1971Arguments: None 1972 1973Example: 1974 1975-> { "execute": "query-fdsets" } 1976<- { "return": [ 1977 { 1978 "fds": [ 1979 { 1980 "fd": 30, 1981 "opaque": "rdonly:/path/to/file" 1982 }, 1983 { 1984 "fd": 24, 1985 "opaque": "rdwr:/path/to/file" 1986 } 1987 ], 1988 "fdset-id": 1 1989 }, 1990 { 1991 "fds": [ 1992 { 1993 "fd": 28 1994 }, 1995 { 1996 "fd": 29 1997 } 1998 ], 1999 "fdset-id": 0 2000 }
2001 ] 2002 } 2003 2004Note: The list of fd sets is shared by all monitor connections. 2005 2006EQMP 2007 2008 { 2009 .name = "block_passwd", 2010 .args_type = "device:s?,node-name:s?,password:s", 2011 .mhandler.cmd_new = qmp_marshal_block_passwd, 2012 }, 2013 2014SQMP 2015block_passwd 2016------------ 2017 2018Set the password of encrypted block devices. 2019 2020Arguments: 2021 2022- "device": device name (json-string) 2023- "node-name": name in the block driver state graph (json-string) 2024- "password": password (json-string) 2025 2026Example: 2027 2028-> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0", 2029 "password": "12345" } } 2030<- { "return": {} } 2031 2032EQMP 2033 2034 { 2035 .name = "block_set_io_throttle", 2036 .args_type = "device:B,bps:l,bps_rd:l,bps_wr:l,iops:l,iops_rd:l,iops_wr:l,bps_max:l?,bps_rd_max:l?,bps_wr_max:l?,iops_max:l?,iops_rd_max:l?,iops_wr_max:l?,bps_max_length:l?,bps_rd_max_length:l?,bps_wr_max_length:l?,iops_max_length:l?,iops_rd_max_length:l?,iops_wr_max_length:l?,iops_size:l?,group:s?", 2037 .mhandler.cmd_new = qmp_marshal_block_set_io_throttle, 2038 }, 2039 2040SQMP 2041block_set_io_throttle 2042------------ 2043 2044Change I/O throttle limits for a block drive. 2045 2046Arguments: 2047 2048- "device": device name (json-string) 2049- "bps": total throughput limit in bytes per second (json-int) 2050- "bps_rd": read throughput limit in bytes per second (json-int) 2051- "bps_wr": write throughput limit in bytes per second (json-int) 2052- "iops": total I/O operations per second (json-int) 2053- "iops_rd": read I/O operations per second (json-int) 2054- "iops_wr": write I/O operations per second (json-int) 2055- "bps_max": total throughput limit during bursts, in bytes (json-int, optional) 2056- "bps_rd_max": read throughput limit during bursts, in bytes (json-int, optional) 2057- "bps_wr_max": write throughput limit during bursts, in bytes (json-int, optional) 2058- "iops_max": total I/O operations per second during bursts (json-int, optional) 2059- "iops_rd_max": read I/O operations per second during bursts (json-int, optional) 2060- "iops_wr_max": write I/O operations per second during bursts (json-int, optional) 2061- "bps_max_length": maximum length of the @bps_max burst period, in seconds (json-int, optional) 2062- "bps_rd_max_length": maximum length of the @bps_rd_max burst period, in seconds (json-int, optional) 2063- "bps_wr_max_length": maximum length of the @bps_wr_max burst period, in seconds (json-int, optional) 2064- "iops_max_length": maximum length of the @iops_max burst period, in seconds (json-int, optional) 2065- "iops_rd_max_length": maximum length of the @iops_rd_max burst period, in seconds (json-int, optional) 2066- "iops_wr_max_length": maximum length of the @iops_wr_max burst period, in seconds (json-int, optional) 2067- "iops_size": I/O size in bytes when limiting (json-int, optional) 2068- "group": throttle group name (json-string, optional) 2069 2070Example: 2071 2072-> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0", 2073 "bps": 1000000, 2074 "bps_rd": 0, 2075 "bps_wr": 0, 2076 "iops": 0, 2077 "iops_rd": 0, 2078 "iops_wr": 0, 2079 "bps_max": 8000000, 2080 "bps_rd_max": 0, 2081 "bps_wr_max": 0, 2082 "iops_max": 0, 2083 "iops_rd_max": 0, 2084 "iops_wr_max": 0, 2085 "bps_max_length": 60, 2086 "iops_size": 0 } } 2087<- { "return": {} } 2088 2089EQMP 2090 2091 { 2092 .name = "set_password", 2093 .args_type = "protocol:s,password:s,connected:s?", 2094 .mhandler.cmd_new = qmp_marshal_set_password, 2095 }, 2096 2097SQMP 2098set_password 2099------------ 2100 2101Set the password for vnc/spice protocols. 2102 2103Arguments: 2104 2105- "protocol": protocol name (json-string) 2106- "password": password (json-string) 2107- "connected": [ keep | disconnect | fail ] (json-string, optional) 2108 2109Example: 2110 2111-> { "execute": "set_password", "arguments": { "protocol": "vnc", 2112 "password": "secret" } } 2113<- { "return": {} } 2114 2115EQMP 2116 2117 { 2118 .name = "expire_password", 2119 .args_type = "protocol:s,time:s", 2120 .mhandler.cmd_new = qmp_marshal_expire_password, 2121 }, 2122 2123SQMP 2124expire_password 2125--------------- 2126 2127Set the password expire time for vnc/spice protocols. 2128 2129Arguments: 2130 2131- "protocol": protocol name (json-string) 2132- "time": [ now | never | +secs | secs ] (json-string) 2133 2134Example: 2135 2136-> { "execute": "expire_password", "arguments": { "protocol": "vnc", 2137 "time": "+60" } } 2138<- { "return": {} } 2139 2140EQMP 2141 2142 { 2143 .name = "add_client", 2144 .args_type = "protocol:s,fdname:s,skipauth:b?,tls:b?", 2145 .mhandler.cmd_new = qmp_marshal_add_client, 2146 }, 2147 2148SQMP 2149add_client 2150---------- 2151 2152Add a graphics client 2153 2154Arguments: 2155 2156- "protocol": protocol name (json-string) 2157- "fdname": file descriptor name (json-string) 2158- "skipauth": whether to skip authentication (json-bool, optional) 2159- "tls": whether to perform TLS (json-bool, optional) 2160 2161Example: 2162 2163-> { "execute": "add_client", "arguments": { "protocol": "vnc", 2164 "fdname": "myclient" } } 2165<- { "return": {} } 2166 2167EQMP 2168 { 2169 .name = "qmp_capabilities", 2170 .args_type = "", 2171 .params = "", 2172 .help = "enable QMP capabilities", 2173 .mhandler.cmd_new = qmp_capabilities, 2174 }, 2175 2176SQMP 2177qmp_capabilities 2178---------------- 2179 2180Enable QMP capabilities. 2181 2182Arguments: None. 2183 2184Example: 2185 2186-> { "execute": "qmp_capabilities" } 2187<- { "return": {} } 2188 2189Note: This command must be issued before issuing any other command. 2190 2191EQMP 2192 2193 { 2194 .name = "human-monitor-command", 2195 .args_type = "command-line:s,cpu-index:i?", 2196 .mhandler.cmd_new = qmp_marshal_human_monitor_command, 2197 }, 2198 2199SQMP 2200human-monitor-command 2201--------------------- 2202 2203Execute a Human Monitor command. 2204 2205Arguments: 2206 2207- command-line: the command name and its arguments, just like the 2208 Human Monitor's shell (json-string) 2209- cpu-index: select the CPU number to be used by commands which access CPU 2210 data, like 'info registers'. The Monitor selects CPU 0 if this 2211 argument is not provided (json-int, optional) 2212 2213Example: 2214 2215-> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } } 2216<- { "return": "kvm support: enabled\r\n" } 2217 2218Notes: 2219 2220(1) The Human Monitor is NOT an stable interface, this means that command 2221 names, arguments and responses can change or be removed at ANY time. 2222 Applications that rely on long term stability guarantees should NOT 2223 use this command 2224 2225(2) Limitations: 2226 2227 o This command is stateless, this means that commands that depend 2228 on state information (such as getfd) might not work 2229 2230 o Commands that prompt the user for data (eg. 'cont' when the block 2231 device is encrypted) don't currently work 2232 22333. Query Commands 2234================= 2235 2236HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change 2237HXCOMM this! We will possibly move query commands definitions inside those 2238HXCOMM sections, just like regular commands. 2239 2240EQMP 2241 2242SQMP 2243query-version 2244------------- 2245 2246Show QEMU version. 2247 2248Return a json-object with the following information: 2249 2250- "qemu": A json-object containing three integer values: 2251 - "major": QEMU's major version (json-int) 2252 - "minor": QEMU's minor version (json-int) 2253 - "micro": QEMU's micro version (json-int) 2254- "package": package's version (json-string) 2255 2256Example: 2257 2258-> { "execute": "query-version" } 2259<- { 2260 "return":{ 2261 "qemu":{ 2262 "major":0, 2263 "minor":11, 2264 "micro":5 2265 }, 2266 "package":"" 2267 } 2268 } 2269 2270EQMP 2271 2272 { 2273 .name = "query-version", 2274 .args_type = "", 2275 .mhandler.cmd_new = qmp_marshal_query_version, 2276 }, 2277 2278SQMP 2279query-commands 2280-------------- 2281 2282List QMP available commands. 2283 2284Each command is represented by a json-object, the returned value is a json-array 2285of all commands. 2286 2287Each json-object contain: 2288 2289- "name": command's name (json-string) 2290 2291Example: 2292 2293-> { "execute": "query-commands" } 2294<- { 2295 "return":[ 2296 { 2297 "name":"query-balloon" 2298 }, 2299 { 2300 "name":"system_powerdown" 2301 } 2302 ] 2303 } 2304 2305Note: This example has been shortened as the real response is too long. 2306 2307EQMP 2308 2309 { 2310 .name = "query-commands", 2311 .args_type = "", 2312 .mhandler.cmd_new = qmp_marshal_query_commands, 2313 }, 2314 2315SQMP 2316query-events 2317-------------- 2318 2319List QMP available events. 2320 2321Each event is represented by a json-object, the returned value is a json-array 2322of all events. 2323 2324Each json-object contains: 2325 2326- "name": event's name (json-string) 2327 2328Example: 2329 2330-> { "execute": "query-events" } 2331<- { 2332 "return":[ 2333 { 2334 "name":"SHUTDOWN" 2335 }, 2336 { 2337 "name":"RESET" 2338 } 2339 ] 2340 } 2341 2342Note: This example has been shortened as the real response is too long. 2343 2344EQMP 2345 2346 { 2347 .name = "query-events", 2348 .args_type = "", 2349 .mhandler.cmd_new = qmp_marshal_query_events, 2350 }, 2351 2352SQMP 2353query-qmp-schema 2354---------------- 2355 2356Return the QMP wire schema. The returned value is a json-array of 2357named schema entities. Entities are commands, events and various 2358types. See docs/qapi-code-gen.txt for information on their structure 2359and intended use. 2360 2361EQMP 2362 2363 { 2364 .name = "query-qmp-schema", 2365 .args_type = "", 2366 .mhandler.cmd_new = qmp_query_qmp_schema, 2367 }, 2368 2369SQMP 2370query-chardev 2371------------- 2372 2373Each device is represented by a json-object. The returned value is a json-array 2374of all devices. 2375 2376Each json-object contain the following: 2377 2378- "label": device's label (json-string) 2379- "filename": device's file (json-string) 2380- "frontend-open": open/closed state of the frontend device attached to this 2381 backend (json-bool) 2382 2383Example: 2384 2385-> { "execute": "query-chardev" } 2386<- { 2387 "return": [ 2388 { 2389 "label": "charchannel0", 2390 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server", 2391 "frontend-open": false 2392 }, 2393 { 2394 "label": "charmonitor", 2395 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server", 2396 "frontend-open": true 2397 }, 2398 { 2399 "label": "charserial0", 2400 "filename": "pty:/dev/pts/2", 2401 "frontend-open": true 2402 } 2403 ] 2404 } 2405 2406EQMP 2407 2408 { 2409 .name = "query-chardev", 2410 .args_type = "", 2411 .mhandler.cmd_new = qmp_marshal_query_chardev, 2412 }, 2413 2414SQMP 2415query-chardev-backends 2416------------- 2417 2418List available character device backends. 2419 2420Each backend is represented by a json-object, the returned value is a json-array 2421of all backends. 2422 2423Each json-object contains: 2424 2425- "name": backend name (json-string) 2426 2427Example: 2428 2429-> { "execute": "query-chardev-backends" } 2430<- { 2431 "return":[ 2432 { 2433 "name":"udp" 2434 }, 2435 { 2436 "name":"tcp" 2437 }, 2438 { 2439 "name":"unix" 2440 }, 2441 { 2442 "name":"spiceport" 2443 } 2444 ] 2445 } 2446 2447EQMP 2448 2449 { 2450 .name = "query-chardev-backends", 2451 .args_type = "", 2452 .mhandler.cmd_new = qmp_marshal_query_chardev_backends, 2453 }, 2454 2455SQMP 2456query-block 2457----------- 2458 2459Show the block devices. 2460 2461Each block device information is stored in a json-object and the returned value 2462is a json-array of all devices. 2463 2464Each json-object contain the following: 2465 2466- "device": device name (json-string) 2467- "type": device type (json-string) 2468 - deprecated, retained for backward compatibility 2469 - Possible values: "unknown" 2470- "removable": true if the device is removable, false otherwise (json-bool) 2471- "locked": true if the device is locked, false otherwise (json-bool) 2472- "tray_open": only present if removable, true if the device has a tray, 2473 and it is open (json-bool) 2474- "inserted": only present if the device is inserted, it is a json-object 2475 containing the following: 2476 - "file": device file name (json-string) 2477 - "ro": true if read-only, false otherwise (json-bool) 2478 - "drv": driver format name (json-string) 2479 - Possible values: "blkdebug", "bochs", "cloop", "dmg", 2480 "file", "file", "ftp", "ftps", "host_cdrom", 2481 "host_device", "http", "https", 2482 "nbd", "parallels", "qcow", "qcow2", "raw", 2483 "tftp", "vdi", "vmdk", "vpc", "vvfat" 2484 - "backing_file": backing file name (json-string, optional) 2485 - "backing_file_depth": number of files in the backing file chain (json-int) 2486 - "encrypted": true if encrypted, false otherwise (json-bool) 2487 - "bps": limit total bytes per second (json-int) 2488 - "bps_rd": limit read bytes per second (json-int) 2489 - "bps_wr": limit write bytes per second (json-int) 2490 - "iops": limit total I/O operations per second (json-int) 2491 - "iops_rd": limit read operations per second (json-int) 2492 - "iops_wr": limit write operations per second (json-int) 2493 - "bps_max": total max in bytes (json-int) 2494 - "bps_rd_max": read max in bytes (json-int) 2495 - "bps_wr_max": write max in bytes (json-int) 2496 - "iops_max": total I/O operations max (json-int) 2497 - "iops_rd_max": read I/O operations max (json-int) 2498 - "iops_wr_max": write I/O operations max (json-int) 2499 - "iops_size": I/O size when limiting by iops (json-int) 2500 - "detect_zeroes": detect and optimize zero writing (json-string) 2501 - Possible values: "off", "on", "unmap" 2502 - "write_threshold": write offset threshold in bytes, a event will be 2503 emitted if crossed. Zero if disabled (json-int) 2504 - "image": the detail of the image, it is a json-object containing 2505 the following: 2506 - "filename": image file name (json-string) 2507 - "format": image format (json-string) 2508 - "virtual-size": image capacity in bytes (json-int) 2509 - "dirty-flag": true if image is not cleanly closed, not present 2510 means clean (json-bool, optional) 2511 - "actual-size": actual size on disk in bytes of the image, not 2512 present when image does not support thin 2513 provision (json-int, optional) 2514 - "cluster-size": size of a cluster in bytes, not present if image 2515 format does not support it (json-int, optional) 2516 - "encrypted": true if the image is encrypted, not present means 2517 false or the image format does not support 2518 encryption (json-bool, optional) 2519 - "backing_file": backing file name, not present means no backing 2520 file is used or the image format does not 2521 support backing file chain 2522 (json-string, optional) 2523 - "full-backing-filename": full path of the backing file, not 2524 present if it equals backing_file or no 2525 backing file is used 2526 (json-string, optional) 2527 - "backing-filename-format": the format of the backing file, not 2528 present means unknown or no backing 2529 file (json-string, optional) 2530 - "snapshots": the internal snapshot info, it is an optional list 2531 of json-object containing the following: 2532 - "id": unique snapshot id (json-string) 2533 - "name": snapshot name (json-string) 2534 - "vm-state-size": size of the VM state in bytes (json-int) 2535 - "date-sec": UTC date of the snapshot in seconds (json-int) 2536 - "date-nsec": fractional part in nanoseconds to be used with 2537 date-sec (json-int) 2538 - "vm-clock-sec": VM clock relative to boot in seconds 2539 (json-int) 2540 - "vm-clock-nsec": fractional part in nanoseconds to be used 2541 with vm-clock-sec (json-int) 2542 - "backing-image": the detail of the backing image, it is an 2543 optional json-object only present when a 2544 backing image present for this image 2545 2546- "io-status": I/O operation status, only present if the device supports it 2547 and the VM is configured to stop on errors. It's always reset 2548 to "ok" when the "cont" command is issued (json_string, optional) 2549 - Possible values: "ok", "failed", "nospace" 2550 2551Example: 2552 2553-> { "execute": "query-block" } 2554<- { 2555 "return":[ 2556 { 2557 "io-status": "ok", 2558 "device":"ide0-hd0", 2559 "locked":false, 2560 "removable":false, 2561 "inserted":{ 2562 "ro":false, 2563 "drv":"qcow2", 2564 "encrypted":false, 2565 "file":"disks/test.qcow2", 2566 "backing_file_depth":1, 2567 "bps":1000000, 2568 "bps_rd":0, 2569 "bps_wr":0, 2570 "iops":1000000, 2571 "iops_rd":0, 2572 "iops_wr":0, 2573 "bps_max": 8000000, 2574 "bps_rd_max": 0, 2575 "bps_wr_max": 0, 2576 "iops_max": 0, 2577 "iops_rd_max": 0, 2578 "iops_wr_max": 0, 2579 "iops_size": 0, 2580 "detect_zeroes": "on", 2581 "write_threshold": 0, 2582 "image":{ 2583 "filename":"disks/test.qcow2", 2584 "format":"qcow2", 2585 "virtual-size":2048000, 2586 "backing_file":"base.qcow2", 2587 "full-backing-filename":"disks/base.qcow2", 2588 "backing-filename-format":"qcow2", 2589 "snapshots":[ 2590 { 2591 "id": "1", 2592 "name": "snapshot1", 2593 "vm-state-size": 0, 2594 "date-sec": 10000200, 2595 "date-nsec": 12, 2596 "vm-clock-sec": 206, 2597 "vm-clock-nsec": 30 2598 } 2599 ], 2600 "backing-image":{ 2601 "filename":"disks/base.qcow2", 2602 "format":"qcow2", 2603 "virtual-size":2048000 2604 } 2605 } 2606 }, 2607 "type":"unknown" 2608 }, 2609 { 2610 "io-status": "ok", 2611 "device":"ide1-cd0", 2612 "locked":false, 2613 "removable":true, 2614 "type":"unknown" 2615 }, 2616 { 2617 "device":"floppy0", 2618 "locked":false, 2619 "removable":true, 2620 "type":"unknown" 2621 }, 2622 { 2623 "device":"sd0", 2624 "locked":false, 2625 "removable":true, 2626 "type":"unknown" 2627 } 2628 ] 2629 } 2630 2631EQMP 2632 2633 { 2634 .name = "query-block", 2635 .args_type = "", 2636 .mhandler.cmd_new = qmp_marshal_query_block, 2637 }, 2638 2639SQMP 2640query-blockstats 2641---------------- 2642 2643Show block device statistics. 2644 2645Each device statistic information is stored in a json-object and the returned 2646value is a json-array of all devices. 2647 2648Each json-object contain the following: 2649 2650- "device": device name (json-string) 2651- "stats": A json-object with the statistics information, it contains: 2652 - "rd_bytes": bytes read (json-int) 2653 - "wr_bytes": bytes written (json-int) 2654 - "rd_operations": read operations (json-int) 2655 - "wr_operations": write operations (json-int) 2656 - "flush_operations": cache flush operations (json-int) 2657 - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int) 2658 - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int) 2659 - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int) 2660 - "wr_highest_offset": The offset after the greatest byte written to the 2661 BlockDriverState since it has been opened (json-int) 2662 - "rd_merged": number of read requests that have been merged into 2663 another request (json-int) 2664 - "wr_merged": number of write requests that have been merged into 2665 another request (json-int) 2666 - "idle_time_ns": time since the last I/O operation, in 2667 nanoseconds. If the field is absent it means 2668 that there haven't been any operations yet 2669 (json-int, optional) 2670 - "failed_rd_operations": number of failed read operations 2671 (json-int) 2672 - "failed_wr_operations": number of failed write operations 2673 (json-int) 2674 - "failed_flush_operations": number of failed flush operations 2675 (json-int) 2676 - "invalid_rd_operations": number of invalid read operations 2677 (json-int) 2678 - "invalid_wr_operations": number of invalid write operations 2679 (json-int) 2680 - "invalid_flush_operations": number of invalid flush operations 2681 (json-int) 2682 - "account_invalid": whether invalid operations are included in 2683 the last access statistics (json-bool) 2684 - "account_failed": whether failed operations are included in the 2685 latency and last access statistics 2686 (json-bool) 2687 - "timed_stats": A json-array containing statistics collected in 2688 specific intervals, with the following members: 2689 - "interval_length": interval used for calculating the 2690 statistics, in seconds (json-int) 2691 - "min_rd_latency_ns": minimum latency of read operations in 2692 the defined interval, in nanoseconds 2693 (json-int) 2694 - "min_wr_latency_ns": minimum latency of write operations in 2695 the defined interval, in nanoseconds 2696 (json-int) 2697 - "min_flush_latency_ns": minimum latency of flush operations 2698 in the defined interval, in 2699 nanoseconds (json-int) 2700 - "max_rd_latency_ns": maximum latency of read operations in 2701 the defined interval, in nanoseconds 2702 (json-int) 2703 - "max_wr_latency_ns": maximum latency of write operations in 2704 the defined interval, in nanoseconds 2705 (json-int) 2706 - "max_flush_latency_ns": maximum latency of flush operations 2707 in the defined interval, in 2708 nanoseconds (json-int) 2709 - "avg_rd_latency_ns": average latency of read operations in 2710 the defined interval, in nanoseconds 2711 (json-int) 2712 - "avg_wr_latency_ns": average latency of write operations in 2713 the defined interval, in nanoseconds 2714 (json-int) 2715 - "avg_flush_latency_ns": average latency of flush operations 2716 in the defined interval, in 2717 nanoseconds (json-int) 2718 - "avg_rd_queue_depth": average number of pending read 2719 operations in the defined interval 2720 (json-number) 2721 - "avg_wr_queue_depth": average number of pending write 2722 operations in the defined interval 2723 (json-number). 2724- "parent": Contains recursively the statistics of the underlying 2725 protocol (e.g. the host file for a qcow2 image). If there is 2726 no underlying protocol, this field is omitted 2727 (json-object, optional) 2728 2729Example: 2730 2731-> { "execute": "query-blockstats" } 2732<- { 2733 "return":[ 2734 { 2735 "device":"ide0-hd0", 2736 "parent":{ 2737 "stats":{ 2738 "wr_highest_offset":3686448128, 2739 "wr_bytes":9786368, 2740 "wr_operations":751, 2741 "rd_bytes":122567168, 2742 "rd_operations":36772 2743 "wr_total_times_ns":313253456 2744 "rd_total_times_ns":3465673657 2745 "flush_total_times_ns":49653 2746 "flush_operations":61, 2747 "rd_merged":0, 2748 "wr_merged":0, 2749 "idle_time_ns":2953431879, 2750 "account_invalid":true, 2751 "account_failed":false 2752 } 2753 }, 2754 "stats":{ 2755 "wr_highest_offset":2821110784, 2756 "wr_bytes":9786368, 2757 "wr_operations":692, 2758 "rd_bytes":122739200, 2759 "rd_operations":36604 2760 "flush_operations":51, 2761 "wr_total_times_ns":313253456 2762 "rd_total_times_ns":3465673657 2763 "flush_total_times_ns":49653, 2764 "rd_merged":0, 2765 "wr_merged":0, 2766 "idle_time_ns":2953431879, 2767 "account_invalid":true, 2768 "account_failed":false 2769 } 2770 }, 2771 { 2772 "device":"ide1-cd0", 2773 "stats":{ 2774 "wr_highest_offset":0, 2775 "wr_bytes":0, 2776 "wr_operations":0, 2777 "rd_bytes":0, 2778 "rd_operations":0 2779 "flush_operations":0, 2780 "wr_total_times_ns":0 2781 "rd_total_times_ns":0 2782 "flush_total_times_ns":0, 2783 "rd_merged":0, 2784 "wr_merged":0, 2785 "account_invalid":false, 2786 "account_failed":false 2787 } 2788 }, 2789 { 2790 "device":"floppy0", 2791 "stats":{ 2792 "wr_highest_offset":0, 2793 "wr_bytes":0, 2794 "wr_operations":0, 2795 "rd_bytes":0, 2796 "rd_operations":0 2797 "flush_operations":0, 2798 "wr_total_times_ns":0 2799 "rd_total_times_ns":0 2800 "flush_total_times_ns":0, 2801 "rd_merged":0, 2802 "wr_merged":0, 2803 "account_invalid":false, 2804 "account_failed":false 2805 } 2806 }, 2807 { 2808 "device":"sd0", 2809 "stats":{ 2810 "wr_highest_offset":0, 2811 "wr_bytes":0, 2812 "wr_operations":0, 2813 "rd_bytes":0, 2814 "rd_operations":0 2815 "flush_operations":0, 2816 "wr_total_times_ns":0 2817 "rd_total_times_ns":0 2818 "flush_total_times_ns":0, 2819 "rd_merged":0, 2820 "wr_merged":0, 2821 "account_invalid":false, 2822 "account_failed":false 2823 } 2824 } 2825 ] 2826 } 2827 2828EQMP 2829 2830 { 2831 .name = "query-blockstats", 2832 .args_type = "query-nodes:b?", 2833 .mhandler.cmd_new = qmp_marshal_query_blockstats, 2834 }, 2835 2836SQMP 2837query-cpus 2838---------- 2839 2840Show CPU information. 2841 2842Return a json-array. Each CPU is represented by a json-object, which contains: 2843 2844- "CPU": CPU index (json-int) 2845- "current": true if this is the current CPU, false otherwise (json-bool) 2846- "halted": true if the cpu is halted, false otherwise (json-bool) 2847- "qom_path": path to the CPU object in the QOM tree (json-str) 2848- "arch": architecture of the cpu, which determines what additional 2849 keys will be present (json-str) 2850- Current program counter. The key's name depends on the architecture: 2851 "pc": i386/x86_64 (json-int) 2852 "nip": PPC (json-int) 2853 "pc" and "npc": sparc (json-int) 2854 "PC": mips (json-int) 2855- "thread_id": ID of the underlying host thread (json-int) 2856 2857Example: 2858 2859-> { "execute": "query-cpus" } 2860<- { 2861 "return":[ 2862 { 2863 "CPU":0, 2864 "current":true, 2865 "halted":false, 2866 "qom_path":"/machine/unattached/device[0]", 2867 "arch":"x86", 2868 "pc":3227107138, 2869 "thread_id":3134 2870 }, 2871 { 2872 "CPU":1, 2873 "current":false, 2874 "halted":true, 2875 "qom_path":"/machine/unattached/device[2]", 2876 "arch":"x86", 2877 "pc":7108165, 2878 "thread_id":3135 2879 } 2880 ] 2881 } 2882 2883EQMP 2884 2885 { 2886 .name = "query-cpus", 2887 .args_type = "", 2888 .mhandler.cmd_new = qmp_marshal_query_cpus, 2889 }, 2890 2891SQMP 2892query-iothreads 2893--------------- 2894 2895Returns a list of information about each iothread. 2896 2897Note this list excludes the QEMU main loop thread, which is not declared 2898using the -object iothread command-line option. It is always the main thread 2899of the process. 2900 2901Return a json-array. Each iothread is represented by a json-object, which contains: 2902 2903- "id": name of iothread (json-str) 2904- "thread-id": ID of the underlying host thread (json-int) 2905 2906Example: 2907 2908-> { "execute": "query-iothreads" } 2909<- { 2910 "return":[ 2911 { 2912 "id":"iothread0", 2913 "thread-id":3134 2914 }, 2915 { 2916 "id":"iothread1", 2917 "thread-id":3135 2918 } 2919 ] 2920 } 2921 2922EQMP 2923 2924 { 2925 .name = "query-iothreads", 2926 .args_type = "", 2927 .mhandler.cmd_new = qmp_marshal_query_iothreads, 2928 }, 2929 2930SQMP 2931query-pci 2932--------- 2933 2934PCI buses and devices information. 2935 2936The returned value is a json-array of all buses. Each bus is represented by 2937a json-object, which has a key with a json-array of all PCI devices attached 2938to it. Each device is represented by a json-object. 2939 2940The bus json-object contains the following: 2941 2942- "bus": bus number (json-int) 2943- "devices": a json-array of json-objects, each json-object represents a 2944 PCI device 2945 2946The PCI device json-object contains the following: 2947 2948- "bus": identical to the parent's bus number (json-int) 2949- "slot": slot number (json-int) 2950- "function": function number (json-int) 2951- "class_info": a json-object containing: 2952 - "desc": device class description (json-string, optional) 2953 - "class": device class number (json-int) 2954- "id": a json-object containing: 2955 - "device": device ID (json-int) 2956 - "vendor": vendor ID (json-int) 2957- "irq": device's IRQ if assigned (json-int, optional) 2958- "qdev_id": qdev id string (json-string) 2959- "pci_bridge": It's a json-object, only present if this device is a 2960 PCI bridge, contains: 2961 - "bus": bus number (json-int) 2962 - "secondary": secondary bus number (json-int) 2963 - "subordinate": subordinate bus number (json-int) 2964 - "io_range": I/O memory range information, a json-object with the 2965 following members: 2966 - "base": base address, in bytes (json-int) 2967 - "limit": limit address, in bytes (json-int) 2968 - "memory_range": memory range information, a json-object with the 2969 following members: 2970 - "base": base address, in bytes (json-int) 2971 - "limit": limit address, in bytes (json-int) 2972 - "prefetchable_range": Prefetchable memory range information, a 2973 json-object with the following members: 2974 - "base": base address, in bytes (json-int) 2975 - "limit": limit address, in bytes (json-int) 2976 - "devices": a json-array of PCI devices if there's any attached, each 2977 each element is represented by a json-object, which contains 2978 the same members of the 'PCI device json-object' described 2979 above (optional) 2980- "regions": a json-array of json-objects, each json-object represents a 2981 memory region of this device 2982 2983The memory range json-object contains the following: 2984 2985- "base": base memory address (json-int) 2986- "limit": limit value (json-int) 2987 2988The region json-object can be an I/O region or a memory region, an I/O region 2989json-object contains the following: 2990 2991- "type": "io" (json-string, fixed) 2992- "bar": BAR number (json-int) 2993- "address": memory address (json-int) 2994- "size": memory size (json-int) 2995 2996A memory region json-object contains the following: 2997 2998- "type": "memory" (json-string, fixed) 2999- "bar": BAR number (json-int) 3000- "address": memory address (json-int)
3001- "size": memory size (json-int) 3002- "mem_type_64": true or false (json-bool) 3003- "prefetch": true or false (json-bool) 3004 3005Example: 3006 3007-> { "execute": "query-pci" } 3008<- { 3009 "return":[ 3010 { 3011 "bus":0, 3012 "devices":[ 3013 { 3014 "bus":0, 3015 "qdev_id":"", 3016 "slot":0, 3017 "class_info":{ 3018 "class":1536, 3019 "desc":"Host bridge" 3020 }, 3021 "id":{ 3022 "device":32902, 3023 "vendor":4663 3024 }, 3025 "function":0, 3026 "regions":[ 3027 3028 ] 3029 }, 3030 { 3031 "bus":0, 3032 "qdev_id":"", 3033 "slot":1, 3034 "class_info":{ 3035 "class":1537, 3036 "desc":"ISA bridge" 3037 }, 3038 "id":{ 3039 "device":32902, 3040 "vendor":28672 3041 }, 3042 "function":0, 3043 "regions":[ 3044 3045 ] 3046 }, 3047 { 3048 "bus":0, 3049 "qdev_id":"", 3050 "slot":1, 3051 "class_info":{ 3052 "class":257, 3053 "desc":"IDE controller" 3054 }, 3055 "id":{ 3056 "device":32902, 3057 "vendor":28688 3058 }, 3059 "function":1, 3060 "regions":[ 3061 { 3062 "bar":4, 3063 "size":16, 3064 "address":49152, 3065 "type":"io" 3066 } 3067 ] 3068 }, 3069 { 3070 "bus":0, 3071 "qdev_id":"", 3072 "slot":2, 3073 "class_info":{ 3074 "class":768, 3075 "desc":"VGA controller" 3076 }, 3077 "id":{ 3078 "device":4115, 3079 "vendor":184 3080 }, 3081 "function":0, 3082 "regions":[ 3083 { 3084 "prefetch":true, 3085 "mem_type_64":false, 3086 "bar":0, 3087 "size":33554432, 3088 "address":4026531840, 3089 "type":"memory" 3090 }, 3091 { 3092 "prefetch":false, 3093 "mem_type_64":false, 3094 "bar":1, 3095 "size":4096, 3096 "address":4060086272, 3097 "type":"memory" 3098 }, 3099 { 3100 "prefetch":false, 3101 "mem_type_64":false, 3102 "bar":6, 3103 "size":65536, 3104 "address":-1, 3105 "type":"memory" 3106 } 3107 ] 3108 }, 3109 { 3110 "bus":0, 3111 "qdev_id":"", 3112 "irq":11, 3113 "slot":4, 3114 "class_info":{ 3115 "class":1280, 3116 "desc":"RAM controller" 3117 }, 3118 "id":{ 3119 "device":6900, 3120 "vendor":4098 3121 }, 3122 "function":0, 3123 "regions":[ 3124 { 3125 "bar":0, 3126 "size":32, 3127 "address":49280, 3128 "type":"io" 3129 } 3130 ] 3131 } 3132 ] 3133 } 3134 ] 3135 } 3136 3137Note: This example has been shortened as the real response is too long. 3138 3139EQMP 3140 3141 { 3142 .name = "query-pci", 3143 .args_type = "", 3144 .mhandler.cmd_new = qmp_marshal_query_pci, 3145 }, 3146 3147SQMP 3148query-kvm 3149--------- 3150 3151Show KVM information. 3152 3153Return a json-object with the following information: 3154 3155- "enabled": true if KVM support is enabled, false otherwise (json-bool) 3156- "present": true if QEMU has KVM support, false otherwise (json-bool) 3157 3158Example: 3159 3160-> { "execute": "query-kvm" } 3161<- { "return": { "enabled": true, "present": true } } 3162 3163EQMP 3164 3165 { 3166 .name = "query-kvm", 3167 .args_type = "", 3168 .mhandler.cmd_new = qmp_marshal_query_kvm, 3169 }, 3170 3171SQMP 3172query-status 3173------------ 3174 3175Return a json-object with the following information: 3176 3177- "running": true if the VM is running, or false if it is paused (json-bool) 3178- "singlestep": true if the VM is in single step mode, 3179 false otherwise (json-bool) 3180- "status": one of the following values (json-string) 3181 "debug" - QEMU is running on a debugger 3182 "inmigrate" - guest is paused waiting for an incoming migration 3183 "internal-error" - An internal error that prevents further guest 3184 execution has occurred 3185 "io-error" - the last IOP has failed and the device is configured 3186 to pause on I/O errors 3187 "paused" - guest has been paused via the 'stop' command 3188 "postmigrate" - guest is paused following a successful 'migrate' 3189 "prelaunch" - QEMU was started with -S and guest has not started 3190 "finish-migrate" - guest is paused to finish the migration process 3191 "restore-vm" - guest is paused to restore VM state 3192 "running" - guest is actively running 3193 "save-vm" - guest is paused to save the VM state 3194 "shutdown" - guest is shut down (and -no-shutdown is in use) 3195 "watchdog" - the watchdog action is configured to pause and 3196 has been triggered 3197 3198Example: 3199 3200-> { "execute": "query-status" } 3201<- { "return": { "running": true, "singlestep": false, "status": "running" } } 3202 3203EQMP 3204 3205 { 3206 .name = "query-status", 3207 .args_type = "", 3208 .mhandler.cmd_new = qmp_marshal_query_status, 3209 }, 3210 3211SQMP 3212query-mice 3213---------- 3214 3215Show VM mice information. 3216 3217Each mouse is represented by a json-object, the returned value is a json-array 3218of all mice. 3219 3220The mouse json-object contains the following: 3221 3222- "name": mouse's name (json-string) 3223- "index": mouse's index (json-int) 3224- "current": true if this mouse is receiving events, false otherwise (json-bool) 3225- "absolute": true if the mouse generates absolute input events (json-bool) 3226 3227Example: 3228 3229-> { "execute": "query-mice" } 3230<- { 3231 "return":[ 3232 { 3233 "name":"QEMU Microsoft Mouse", 3234 "index":0, 3235 "current":false, 3236 "absolute":false 3237 }, 3238 { 3239 "name":"QEMU PS/2 Mouse", 3240 "index":1, 3241 "current":true, 3242 "absolute":true 3243 } 3244 ] 3245 } 3246 3247EQMP 3248 3249 { 3250 .name = "query-mice", 3251 .args_type = "", 3252 .mhandler.cmd_new = qmp_marshal_query_mice, 3253 }, 3254 3255SQMP 3256query-vnc 3257--------- 3258 3259Show VNC server information. 3260 3261Return a json-object with server information. Connected clients are returned 3262as a json-array of json-objects. 3263 3264The main json-object contains the following: 3265 3266- "enabled": true or false (json-bool) 3267- "host": server's IP address (json-string) 3268- "family": address family (json-string) 3269 - Possible values: "ipv4", "ipv6", "unix", "unknown" 3270- "service": server's port number (json-string) 3271- "auth": authentication method (json-string) 3272 - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight", 3273 "tls", "ultra", "unknown", "vencrypt", "vencrypt", 3274 "vencrypt+plain", "vencrypt+tls+none", 3275 "vencrypt+tls+plain", "vencrypt+tls+sasl", 3276 "vencrypt+tls+vnc", "vencrypt+x509+none", 3277 "vencrypt+x509+plain", "vencrypt+x509+sasl", 3278 "vencrypt+x509+vnc", "vnc" 3279- "clients": a json-array of all connected clients 3280 3281Clients are described by a json-object, each one contain the following: 3282 3283- "host": client's IP address (json-string) 3284- "family": address family (json-string) 3285 - Possible values: "ipv4", "ipv6", "unix", "unknown" 3286- "service": client's port number (json-string) 3287- "x509_dname": TLS dname (json-string, optional) 3288- "sasl_username": SASL username (json-string, optional) 3289 3290Example: 3291 3292-> { "execute": "query-vnc" } 3293<- { 3294 "return":{ 3295 "enabled":true, 3296 "host":"0.0.0.0", 3297 "service":"50402", 3298 "auth":"vnc", 3299 "family":"ipv4", 3300 "clients":[ 3301 { 3302 "host":"127.0.0.1", 3303 "service":"50401", 3304 "family":"ipv4" 3305 } 3306 ] 3307 } 3308 } 3309 3310EQMP 3311 3312 { 3313 .name = "query-vnc", 3314 .args_type = "", 3315 .mhandler.cmd_new = qmp_marshal_query_vnc, 3316 }, 3317 { 3318 .name = "query-vnc-servers", 3319 .args_type = "", 3320 .mhandler.cmd_new = qmp_marshal_query_vnc_servers, 3321 }, 3322 3323SQMP 3324query-spice 3325----------- 3326 3327Show SPICE server information. 3328 3329Return a json-object with server information. Connected clients are returned 3330as a json-array of json-objects. 3331 3332The main json-object contains the following: 3333 3334- "enabled": true or false (json-bool) 3335- "host": server's IP address (json-string) 3336- "port": server's port number (json-int, optional) 3337- "tls-port": server's port number (json-int, optional) 3338- "auth": authentication method (json-string) 3339 - Possible values: "none", "spice" 3340- "channels": a json-array of all active channels clients 3341 3342Channels are described by a json-object, each one contain the following: 3343 3344- "host": client's IP address (json-string) 3345- "family": address family (json-string) 3346 - Possible values: "ipv4", "ipv6", "unix", "unknown" 3347- "port": client's port number (json-string) 3348- "connection-id": spice connection id. All channels with the same id 3349 belong to the same spice session (json-int) 3350- "channel-type": channel type. "1" is the main control channel, filter for 3351 this one if you want track spice sessions only (json-int) 3352- "channel-id": channel id. Usually "0", might be different needed when 3353 multiple channels of the same type exist, such as multiple 3354 display channels in a multihead setup (json-int) 3355- "tls": whether the channel is encrypted (json-bool) 3356 3357Example: 3358 3359-> { "execute": "query-spice" } 3360<- { 3361 "return": { 3362 "enabled": true, 3363 "auth": "spice", 3364 "port": 5920, 3365 "tls-port": 5921, 3366 "host": "0.0.0.0", 3367 "channels": [ 3368 { 3369 "port": "54924", 3370 "family": "ipv4", 3371 "channel-type": 1, 3372 "connection-id": 1804289383, 3373 "host": "127.0.0.1", 3374 "channel-id": 0, 3375 "tls": true 3376 }, 3377 { 3378 "port": "36710", 3379 "family": "ipv4", 3380 "channel-type": 4, 3381 "connection-id": 1804289383, 3382 "host": "127.0.0.1", 3383 "channel-id": 0, 3384 "tls": false 3385 }, 3386 [ ... more channels follow ... ] 3387 ] 3388 } 3389 } 3390 3391EQMP 3392 3393#if defined(CONFIG_SPICE) 3394 { 3395 .name = "query-spice", 3396 .args_type = "", 3397 .mhandler.cmd_new = qmp_marshal_query_spice, 3398 }, 3399#endif 3400 3401SQMP 3402query-name 3403---------- 3404 3405Show VM name. 3406 3407Return a json-object with the following information: 3408 3409- "name": VM's name (json-string, optional) 3410 3411Example: 3412 3413-> { "execute": "query-name" } 3414<- { "return": { "name": "qemu-name" } } 3415 3416EQMP 3417 3418 { 3419 .name = "query-name", 3420 .args_type = "", 3421 .mhandler.cmd_new = qmp_marshal_query_name, 3422 }, 3423 3424SQMP 3425query-uuid 3426---------- 3427 3428Show VM UUID. 3429 3430Return a json-object with the following information: 3431 3432- "UUID": Universally Unique Identifier (json-string) 3433 3434Example: 3435 3436-> { "execute": "query-uuid" } 3437<- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } 3438 3439EQMP 3440 3441 { 3442 .name = "query-uuid", 3443 .args_type = "", 3444 .mhandler.cmd_new = qmp_marshal_query_uuid, 3445 }, 3446 3447SQMP 3448query-command-line-options 3449-------------------------- 3450 3451Show command line option schema. 3452 3453Return a json-array of command line option schema for all options (or for 3454the given option), returning an error if the given option doesn't exist. 3455 3456Each array entry contains the following: 3457 3458- "option": option name (json-string) 3459- "parameters": a json-array describes all parameters of the option: 3460 - "name": parameter name (json-string) 3461 - "type": parameter type (one of 'string', 'boolean', 'number', 3462 or 'size') 3463 - "help": human readable description of the parameter 3464 (json-string, optional) 3465 - "default": default value string for the parameter 3466 (json-string, optional) 3467 3468Example: 3469 3470-> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } } 3471<- { "return": [ 3472 { 3473 "parameters": [ 3474 { 3475 "name": "romfile", 3476 "type": "string" 3477 }, 3478 { 3479 "name": "bootindex", 3480 "type": "number" 3481 } 3482 ], 3483 "option": "option-rom" 3484 } 3485 ] 3486 } 3487 3488EQMP 3489 3490 { 3491 .name = "query-command-line-options", 3492 .args_type = "option:s?", 3493 .mhandler.cmd_new = qmp_marshal_query_command_line_options, 3494 }, 3495 3496SQMP 3497query-migrate 3498------------- 3499 3500Migration status. 3501 3502Return a json-object. If migration is active there will be another json-object 3503with RAM migration status and if block migration is active another one with 3504block migration status. 3505 3506The main json-object contains the following: 3507 3508- "status": migration status (json-string) 3509 - Possible values: "setup", "active", "completed", "failed", "cancelled" 3510- "total-time": total amount of ms since migration started. If 3511 migration has ended, it returns the total migration 3512 time (json-int) 3513- "setup-time" amount of setup time in milliseconds _before_ the 3514 iterations begin but _after_ the QMP command is issued. 3515 This is designed to provide an accounting of any activities 3516 (such as RDMA pinning) which may be expensive, but do not 3517 actually occur during the iterative migration rounds 3518 themselves. (json-int) 3519- "downtime": only present when migration has finished correctly 3520 total amount in ms for downtime that happened (json-int) 3521- "expected-downtime": only present while migration is active 3522 total amount in ms for downtime that was calculated on 3523 the last bitmap round (json-int) 3524- "ram": only present if "status" is "active", it is a json-object with the 3525 following RAM information: 3526 - "transferred": amount transferred in bytes (json-int) 3527 - "remaining": amount remaining to transfer in bytes (json-int) 3528 - "total": total amount of memory in bytes (json-int) 3529 - "duplicate": number of pages filled entirely with the same 3530 byte (json-int) 3531 These are sent over the wire much more efficiently. 3532 - "skipped": number of skipped zero pages (json-int) 3533 - "normal" : number of whole pages transferred. I.e. they 3534 were not sent as duplicate or xbzrle pages (json-int) 3535 - "normal-bytes" : number of bytes transferred in whole 3536 pages. This is just normal pages times size of one page, 3537 but this way upper levels don't need to care about page 3538 size (json-int) 3539 - "dirty-sync-count": times that dirty ram was synchronized (json-int) 3540- "disk": only present if "status" is "active" and it is a block migration, 3541 it is a json-object with the following disk information: 3542 - "transferred": amount transferred in bytes (json-int) 3543 - "remaining": amount remaining to transfer in bytes json-int) 3544 - "total": total disk size in bytes (json-int) 3545- "xbzrle-cache": only present if XBZRLE is active. 3546 It is a json-object with the following XBZRLE information: 3547 - "cache-size": XBZRLE cache size in bytes 3548 - "bytes": number of bytes transferred for XBZRLE compressed pages 3549 - "pages": number of XBZRLE compressed pages 3550 - "cache-miss": number of XBRZRLE page cache misses 3551 - "cache-miss-rate": rate of XBRZRLE page cache misses 3552 - "overflow": number of times XBZRLE overflows. This means 3553 that the XBZRLE encoding was bigger than just sent the 3554 whole page, and then we sent the whole page instead (as as 3555 normal page). 3556 3557Examples: 3558 35591. Before the first migration 3560 3561-> { "execute": "query-migrate" } 3562<- { "return": {} } 3563 35642. Migration is done and has succeeded 3565 3566-> { "execute": "query-migrate" } 3567<- { "return": { 3568 "status": "completed", 3569 "ram":{ 3570 "transferred":123, 3571 "remaining":123, 3572 "total":246, 3573 "total-time":12345, 3574 "setup-time":12345, 3575 "downtime":12345, 3576 "duplicate":123, 3577 "normal":123, 3578 "normal-bytes":123456, 3579 "dirty-sync-count":15 3580 } 3581 } 3582 } 3583 35843. Migration is done and has failed 3585 3586-> { "execute": "query-migrate" } 3587<- { "return": { "status": "failed" } } 3588 35894. Migration is being performed and is not a block migration: 3590 3591-> { "execute": "query-migrate" } 3592<- { 3593 "return":{ 3594 "status":"active", 3595 "ram":{ 3596 "transferred":123, 3597 "remaining":123, 3598 "total":246, 3599 "total-time":12345, 3600 "setup-time":12345, 3601 "expected-downtime":12345, 3602 "duplicate":123, 3603 "normal":123, 3604 "normal-bytes":123456, 3605 "dirty-sync-count":15 3606 } 3607 } 3608 } 3609 36105. Migration is being performed and is a block migration: 3611 3612-> { "execute": "query-migrate" } 3613<- { 3614 "return":{ 3615 "status":"active", 3616 "ram":{ 3617 "total":1057024, 3618 "remaining":1053304, 3619 "transferred":3720, 3620 "total-time":12345, 3621 "setup-time":12345, 3622 "expected-downtime":12345, 3623 "duplicate":123, 3624 "normal":123, 3625 "normal-bytes":123456, 3626 "dirty-sync-count":15 3627 }, 3628 "disk":{ 3629 "total":20971520, 3630 "remaining":20880384, 3631 "transferred":91136 3632 } 3633 } 3634 } 3635 36366. Migration is being performed and XBZRLE is active: 3637 3638-> { "execute": "query-migrate" } 3639<- { 3640 "return":{ 3641 "status":"active", 3642 "capabilities" : [ { "capability": "xbzrle", "state" : true } ], 3643 "ram":{ 3644 "total":1057024, 3645 "remaining":1053304, 3646 "transferred":3720, 3647 "total-time":12345, 3648 "setup-time":12345, 3649 "expected-downtime":12345, 3650 "duplicate":10, 3651 "normal":3333, 3652 "normal-bytes":3412992, 3653 "dirty-sync-count":15 3654 }, 3655 "xbzrle-cache":{ 3656 "cache-size":67108864, 3657 "bytes":20971520, 3658 "pages":2444343, 3659 "cache-miss":2244, 3660 "cache-miss-rate":0.123, 3661 "overflow":34434 3662 } 3663 } 3664 } 3665 3666EQMP 3667 3668 { 3669 .name = "query-migrate", 3670 .args_type = "", 3671 .mhandler.cmd_new = qmp_marshal_query_migrate, 3672 }, 3673 3674SQMP 3675migrate-set-capabilities 3676------------------------ 3677 3678Enable/Disable migration capabilities 3679 3680- "xbzrle": XBZRLE support 3681- "rdma-pin-all": pin all pages when using RDMA during migration 3682- "auto-converge": throttle down guest to help convergence of migration 3683- "zero-blocks": compress zero blocks during block migration 3684- "compress": use multiple compression threads to accelerate live migration 3685- "events": generate events for each migration state change 3686- "postcopy-ram": postcopy mode for live migration 3687 3688Arguments: 3689 3690Example: 3691 3692-> { "execute": "migrate-set-capabilities" , "arguments": 3693 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } } 3694 3695EQMP 3696 3697 { 3698 .name = "migrate-set-capabilities", 3699 .args_type = "capabilities:q", 3700 .params = "capability:s,state:b", 3701 .mhandler.cmd_new = qmp_marshal_migrate_set_capabilities, 3702 }, 3703SQMP 3704query-migrate-capabilities 3705-------------------------- 3706 3707Query current migration capabilities 3708 3709- "capabilities": migration capabilities state 3710 - "xbzrle" : XBZRLE state (json-bool) 3711 - "rdma-pin-all" : RDMA Pin Page state (json-bool) 3712 - "auto-converge" : Auto Converge state (json-bool) 3713 - "zero-blocks" : Zero Blocks state (json-bool) 3714 - "compress": Multiple compression threads state (json-bool) 3715 - "events": Migration state change event state (json-bool) 3716 - "postcopy-ram": postcopy ram state (json-bool) 3717 3718Arguments: 3719 3720Example: 3721 3722-> { "execute": "query-migrate-capabilities" } 3723<- {"return": [ 3724 {"state": false, "capability": "xbzrle"}, 3725 {"state": false, "capability": "rdma-pin-all"}, 3726 {"state": false, "capability": "auto-converge"}, 3727 {"state": false, "capability": "zero-blocks"}, 3728 {"state": false, "capability": "compress"}, 3729 {"state": true, "capability": "events"}, 3730 {"state": false, "capability": "postcopy-ram"} 3731 ]} 3732 3733EQMP 3734 3735 { 3736 .name = "query-migrate-capabilities", 3737 .args_type = "", 3738 .mhandler.cmd_new = qmp_marshal_query_migrate_capabilities, 3739 }, 3740 3741SQMP 3742migrate-set-parameters 3743---------------------- 3744 3745Set migration parameters 3746 3747- "compress-level": set compression level during migration (json-int) 3748- "compress-threads": set compression thread count for migration (json-int) 3749- "decompress-threads": set decompression thread count for migration (json-int) 3750- "x-cpu-throttle-initial": set initial percentage of time guest cpus are 3751 throttled for auto-converge (json-int) 3752- "x-cpu-throttle-increment": set throttle increasing percentage for 3753 auto-converge (json-int) 3754 3755Arguments: 3756 3757Example: 3758 3759-> { "execute": "migrate-set-parameters" , "arguments": 3760 { "compress-level": 1 } } 3761 3762EQMP 3763 3764 { 3765 .name = "migrate-set-parameters", 3766 .args_type = 3767 "compress-level:i?,compress-threads:i?,decompress-threads:i?,x-cpu-throttle-initial:i?,x-cpu-throttle-increment:i?", 3768 .mhandler.cmd_new = qmp_marshal_migrate_set_parameters, 3769 }, 3770SQMP 3771query-migrate-parameters 3772------------------------ 3773 3774Query current migration parameters 3775 3776- "parameters": migration parameters value 3777 - "compress-level" : compression level value (json-int) 3778 - "compress-threads" : compression thread count value (json-int) 3779 - "decompress-threads" : decompression thread count value (json-int) 3780 - "x-cpu-throttle-initial" : initial percentage of time guest cpus are 3781 throttled (json-int) 3782 - "x-cpu-throttle-increment" : throttle increasing percentage for 3783 auto-converge (json-int) 3784 3785Arguments: 3786 3787Example: 3788 3789-> { "execute": "query-migrate-parameters" } 3790<- { 3791 "return": { 3792 "decompress-threads": 2, 3793 "x-cpu-throttle-increment": 10, 3794 "compress-threads": 8, 3795 "compress-level": 1, 3796 "x-cpu-throttle-initial": 20 3797 } 3798 } 3799 3800EQMP 3801 3802 { 3803 .name = "query-migrate-parameters", 3804 .args_type = "", 3805 .mhandler.cmd_new = qmp_marshal_query_migrate_parameters, 3806 }, 3807 3808SQMP 3809query-balloon 3810------------- 3811 3812Show balloon information. 3813 3814Make an asynchronous request for balloon info. When the request completes a 3815json-object will be returned containing the following data: 3816 3817- "actual": current balloon value in bytes (json-int) 3818 3819Example: 3820 3821-> { "execute": "query-balloon" } 3822<- { 3823 "return":{ 3824 "actual":1073741824, 3825 } 3826 } 3827 3828EQMP 3829 3830 { 3831 .name = "query-balloon", 3832 .args_type = "", 3833 .mhandler.cmd_new = qmp_marshal_query_balloon, 3834 }, 3835 3836 { 3837 .name = "query-block-jobs", 3838 .args_type = "", 3839 .mhandler.cmd_new = qmp_marshal_query_block_jobs, 3840 }, 3841 3842 { 3843 .name = "qom-list", 3844 .args_type = "path:s", 3845 .mhandler.cmd_new = qmp_marshal_qom_list, 3846 }, 3847 3848 { 3849 .name = "qom-set", 3850 .args_type = "path:s,property:s,value:q", 3851 .mhandler.cmd_new = qmp_marshal_qom_set, 3852 }, 3853 3854 { 3855 .name = "qom-get", 3856 .args_type = "path:s,property:s", 3857 .mhandler.cmd_new = qmp_marshal_qom_get, 3858 }, 3859 3860 { 3861 .name = "nbd-server-start", 3862 .args_type = "addr:q,tls-creds:s?", 3863 .mhandler.cmd_new = qmp_marshal_nbd_server_start, 3864 }, 3865 { 3866 .name = "nbd-server-add", 3867 .args_type = "device:B,writable:b?", 3868 .mhandler.cmd_new = qmp_marshal_nbd_server_add, 3869 }, 3870 { 3871 .name = "nbd-server-stop", 3872 .args_type = "", 3873 .mhandler.cmd_new = qmp_marshal_nbd_server_stop, 3874 }, 3875 3876 { 3877 .name = "change-vnc-password", 3878 .args_type = "password:s", 3879 .mhandler.cmd_new = qmp_marshal_change_vnc_password, 3880 }, 3881 { 3882 .name = "qom-list-types", 3883 .args_type = "implements:s?,abstract:b?", 3884 .mhandler.cmd_new = qmp_marshal_qom_list_types, 3885 }, 3886 3887 { 3888 .name = "device-list-properties", 3889 .args_type = "typename:s", 3890 .mhandler.cmd_new = qmp_marshal_device_list_properties, 3891 }, 3892 3893 { 3894 .name = "query-machines", 3895 .args_type = "", 3896 .mhandler.cmd_new = qmp_marshal_query_machines, 3897 }, 3898 3899 { 3900 .name = "query-cpu-definitions", 3901 .args_type = "", 3902 .mhandler.cmd_new = qmp_marshal_query_cpu_definitions, 3903 }, 3904 3905 { 3906 .name = "query-target", 3907 .args_type = "", 3908 .mhandler.cmd_new = qmp_marshal_query_target, 3909 }, 3910 3911 { 3912 .name = "query-tpm", 3913 .args_type = "", 3914 .mhandler.cmd_new = qmp_marshal_query_tpm, 3915 }, 3916 3917SQMP 3918query-tpm 3919--------- 3920 3921Return information about the TPM device. 3922 3923Arguments: None 3924 3925Example: 3926 3927-> { "execute": "query-tpm" } 3928<- { "return": 3929 [ 3930 { "model": "tpm-tis", 3931 "options": 3932 { "type": "passthrough", 3933 "data": 3934 { "cancel-path": "/sys/class/misc/tpm0/device/cancel", 3935 "path": "/dev/tpm0" 3936 } 3937 }, 3938 "id": "tpm0" 3939 } 3940 ] 3941 } 3942 3943EQMP 3944 3945 { 3946 .name = "query-tpm-models", 3947 .args_type = "", 3948 .mhandler.cmd_new = qmp_marshal_query_tpm_models, 3949 }, 3950 3951SQMP 3952query-tpm-models 3953---------------- 3954 3955Return a list of supported TPM models. 3956 3957Arguments: None 3958 3959Example: 3960 3961-> { "execute": "query-tpm-models" } 3962<- { "return": [ "tpm-tis" ] } 3963 3964EQMP 3965 3966 { 3967 .name = "query-tpm-types", 3968 .args_type = "", 3969 .mhandler.cmd_new = qmp_marshal_query_tpm_types, 3970 }, 3971 3972SQMP 3973query-tpm-types 3974--------------- 3975 3976Return a list of supported TPM types. 3977 3978Arguments: None 3979 3980Example: 3981 3982-> { "execute": "query-tpm-types" } 3983<- { "return": [ "passthrough" ] } 3984 3985EQMP 3986 3987 { 3988 .name = "chardev-add", 3989 .args_type = "id:s,backend:q", 3990 .mhandler.cmd_new = qmp_marshal_chardev_add, 3991 }, 3992 3993SQMP 3994chardev-add 3995---------------- 3996 3997Add a chardev. 3998 3999Arguments: 4000
4001- "id": the chardev's ID, must be unique (json-string) 4002- "backend": chardev backend type + parameters 4003 4004Examples: 4005 4006-> { "execute" : "chardev-add", 4007 "arguments" : { "id" : "foo", 4008 "backend" : { "type" : "null", "data" : {} } } } 4009<- { "return": {} } 4010 4011-> { "execute" : "chardev-add", 4012 "arguments" : { "id" : "bar", 4013 "backend" : { "type" : "file", 4014 "data" : { "out" : "/tmp/bar.log" } } } } 4015<- { "return": {} } 4016 4017-> { "execute" : "chardev-add", 4018 "arguments" : { "id" : "baz", 4019 "backend" : { "type" : "pty", "data" : {} } } } 4020<- { "return": { "pty" : "/dev/pty/42" } } 4021 4022EQMP 4023 4024 { 4025 .name = "chardev-remove", 4026 .args_type = "id:s", 4027 .mhandler.cmd_new = qmp_marshal_chardev_remove, 4028 }, 4029 4030 4031SQMP 4032chardev-remove 4033-------------- 4034 4035Remove a chardev. 4036 4037Arguments: 4038 4039- "id": the chardev's ID, must exist and not be in use (json-string) 4040 4041Example: 4042 4043-> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } 4044<- { "return": {} } 4045 4046EQMP 4047 { 4048 .name = "query-rx-filter", 4049 .args_type = "name:s?", 4050 .mhandler.cmd_new = qmp_marshal_query_rx_filter, 4051 }, 4052 4053SQMP 4054query-rx-filter 4055--------------- 4056 4057Show rx-filter information. 4058 4059Returns a json-array of rx-filter information for all NICs (or for the 4060given NIC), returning an error if the given NIC doesn't exist, or 4061given NIC doesn't support rx-filter querying, or given net client 4062isn't a NIC. 4063 4064The query will clear the event notification flag of each NIC, then qemu 4065will start to emit event to QMP monitor. 4066 4067Each array entry contains the following: 4068 4069- "name": net client name (json-string) 4070- "promiscuous": promiscuous mode is enabled (json-bool) 4071- "multicast": multicast receive state (one of 'normal', 'none', 'all') 4072- "unicast": unicast receive state (one of 'normal', 'none', 'all') 4073- "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0) 4074- "broadcast-allowed": allow to receive broadcast (json-bool) 4075- "multicast-overflow": multicast table is overflowed (json-bool) 4076- "unicast-overflow": unicast table is overflowed (json-bool) 4077- "main-mac": main macaddr string (json-string) 4078- "vlan-table": a json-array of active vlan id 4079- "unicast-table": a json-array of unicast macaddr string 4080- "multicast-table": a json-array of multicast macaddr string 4081 4082Example: 4083 4084-> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } } 4085<- { "return": [ 4086 { 4087 "promiscuous": true, 4088 "name": "vnet0", 4089 "main-mac": "52:54:00:12:34:56", 4090 "unicast": "normal", 4091 "vlan": "normal", 4092 "vlan-table": [ 4093 4, 4094 0 4095 ], 4096 "unicast-table": [ 4097 ], 4098 "multicast": "normal", 4099 "multicast-overflow": false, 4100 "unicast-overflow": false, 4101 "multicast-table": [ 4102 "01:00:5e:00:00:01", 4103 "33:33:00:00:00:01", 4104 "33:33:ff:12:34:56" 4105 ], 4106 "broadcast-allowed": false 4107 } 4108 ] 4109 } 4110 4111EQMP 4112 4113 { 4114 .name = "blockdev-add", 4115 .args_type = "options:q", 4116 .mhandler.cmd_new = qmp_marshal_blockdev_add, 4117 }, 4118 4119SQMP 4120blockdev-add 4121------------ 4122 4123Add a block device. 4124 4125This command is still a work in progress. It doesn't support all 4126block drivers among other things. Stay away from it unless you want 4127to help with its development. 4128 4129Arguments: 4130 4131- "options": block driver options 4132 4133Example (1): 4134 4135-> { "execute": "blockdev-add", 4136 "arguments": { "options" : { "driver": "qcow2", 4137 "file": { "driver": "file", 4138 "filename": "test.qcow2" } } } } 4139<- { "return": {} } 4140 4141Example (2): 4142 4143-> { "execute": "blockdev-add", 4144 "arguments": { 4145 "options": { 4146 "driver": "qcow2", 4147 "id": "my_disk", 4148 "discard": "unmap", 4149 "cache": { 4150 "direct": true, 4151 "writeback": true 4152 }, 4153 "file": { 4154 "driver": "file", 4155 "filename": "/tmp/test.qcow2" 4156 }, 4157 "backing": { 4158 "driver": "raw", 4159 "file": { 4160 "driver": "file", 4161 "filename": "/dev/fdset/4" 4162 } 4163 } 4164 } 4165 } 4166 } 4167 4168<- { "return": {} } 4169 4170EQMP 4171 4172 { 4173 .name = "x-blockdev-del", 4174 .args_type = "id:s?,node-name:s?", 4175 .mhandler.cmd_new = qmp_marshal_x_blockdev_del, 4176 }, 4177 4178SQMP 4179x-blockdev-del 4180------------ 4181Since 2.5 4182 4183Deletes a block device thas has been added using blockdev-add. 4184The selected device can be either a block backend or a graph node. 4185 4186In the former case the backend will be destroyed, along with its 4187inserted medium if there's any. The command will fail if the backend 4188or its medium are in use. 4189 4190In the latter case the node will be destroyed. The command will fail 4191if the node is attached to a block backend or is otherwise being 4192used. 4193 4194One of "id" or "node-name" must be specified, but not both. 4195 4196This command is still a work in progress and is considered 4197experimental. Stay away from it unless you want to help with its 4198development. 4199 4200Arguments: 4201 4202- "id": Name of the block backend device to delete (json-string, optional) 4203- "node-name": Name of the graph node to delete (json-string, optional) 4204 4205Example: 4206 4207-> { "execute": "blockdev-add", 4208 "arguments": { 4209 "options": { 4210 "driver": "qcow2", 4211 "id": "drive0", 4212 "file": { 4213 "driver": "file", 4214 "filename": "test.qcow2" 4215 } 4216 } 4217 } 4218 } 4219 4220<- { "return": {} } 4221 4222-> { "execute": "x-blockdev-del", 4223 "arguments": { "id": "drive0" } 4224 } 4225<- { "return": {} } 4226 4227EQMP 4228 4229 { 4230 .name = "blockdev-open-tray", 4231 .args_type = "device:s,force:b?", 4232 .mhandler.cmd_new = qmp_marshal_blockdev_open_tray, 4233 }, 4234 4235SQMP 4236blockdev-open-tray 4237------------------ 4238 4239Opens a block device's tray. If there is a block driver state tree inserted as a 4240medium, it will become inaccessible to the guest (but it will remain associated 4241to the block device, so closing the tray will make it accessible again). 4242 4243If the tray was already open before, this will be a no-op. 4244 4245Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are cases in 4246which no such event will be generated, these include: 4247- if the guest has locked the tray, @force is false and the guest does not 4248 respond to the eject request 4249- if the BlockBackend denoted by @device does not have a guest device attached 4250 to it 4251- if the guest device does not have an actual tray and is empty, for instance 4252 for floppy disk drives 4253 4254Arguments: 4255 4256- "device": block device name (json-string) 4257- "force": if false (the default), an eject request will be sent to the guest if 4258 it has locked the tray (and the tray will not be opened immediately); 4259 if true, the tray will be opened regardless of whether it is locked 4260 (json-bool, optional) 4261 4262Example: 4263 4264-> { "execute": "blockdev-open-tray", 4265 "arguments": { "device": "ide1-cd0" } } 4266 4267<- { "timestamp": { "seconds": 1418751016, 4268 "microseconds": 716996 }, 4269 "event": "DEVICE_TRAY_MOVED", 4270 "data": { "device": "ide1-cd0", 4271 "tray-open": true } } 4272 4273<- { "return": {} } 4274 4275EQMP 4276 4277 { 4278 .name = "blockdev-close-tray", 4279 .args_type = "device:s", 4280 .mhandler.cmd_new = qmp_marshal_blockdev_close_tray, 4281 }, 4282 4283SQMP 4284blockdev-close-tray 4285------------------- 4286 4287Closes a block device's tray. If there is a block driver state tree associated 4288with the block device (which is currently ejected), that tree will be loaded as 4289the medium. 4290 4291If the tray was already closed before, this will be a no-op. 4292 4293Arguments: 4294 4295- "device": block device name (json-string) 4296 4297Example: 4298 4299-> { "execute": "blockdev-close-tray", 4300 "arguments": { "device": "ide1-cd0" } } 4301 4302<- { "timestamp": { "seconds": 1418751345, 4303 "microseconds": 272147 }, 4304 "event": "DEVICE_TRAY_MOVED", 4305 "data": { "device": "ide1-cd0", 4306 "tray-open": false } } 4307 4308<- { "return": {} } 4309 4310EQMP 4311 4312 { 4313 .name = "x-blockdev-remove-medium", 4314 .args_type = "device:s", 4315 .mhandler.cmd_new = qmp_marshal_x_blockdev_remove_medium, 4316 }, 4317 4318SQMP 4319x-blockdev-remove-medium 4320------------------------ 4321 4322Removes a medium (a block driver state tree) from a block device. That block 4323device's tray must currently be open (unless there is no attached guest device). 4324 4325If the tray is open and there is no medium inserted, this will be a no-op. 4326 4327This command is still a work in progress and is considered experimental. 4328Stay away from it unless you want to help with its development. 4329 4330Arguments: 4331 4332- "device": block device name (json-string) 4333 4334Example: 4335 4336-> { "execute": "x-blockdev-remove-medium", 4337 "arguments": { "device": "ide1-cd0" } } 4338 4339<- { "error": { "class": "GenericError", 4340 "desc": "Tray of device 'ide1-cd0' is not open" } } 4341 4342-> { "execute": "blockdev-open-tray", 4343 "arguments": { "device": "ide1-cd0" } } 4344 4345<- { "timestamp": { "seconds": 1418751627, 4346 "microseconds": 549958 }, 4347 "event": "DEVICE_TRAY_MOVED", 4348 "data": { "device": "ide1-cd0", 4349 "tray-open": true } } 4350 4351<- { "return": {} } 4352 4353-> { "execute": "x-blockdev-remove-medium", 4354 "arguments": { "device": "ide1-cd0" } } 4355 4356<- { "return": {} } 4357 4358EQMP 4359 4360 { 4361 .name = "x-blockdev-insert-medium", 4362 .args_type = "device:s,node-name:s", 4363 .mhandler.cmd_new = qmp_marshal_x_blockdev_insert_medium, 4364 }, 4365 4366SQMP 4367x-blockdev-insert-medium 4368------------------------ 4369 4370Inserts a medium (a block driver state tree) into a block device. That block 4371device's tray must currently be open (unless there is no attached guest device) 4372and there must be no medium inserted already. 4373 4374This command is still a work in progress and is considered experimental. 4375Stay away from it unless you want to help with its development. 4376 4377Arguments: 4378 4379- "device": block device name (json-string) 4380- "node-name": root node of the BDS tree to insert into the block device 4381 4382Example: 4383 4384-> { "execute": "blockdev-add", 4385 "arguments": { "options": { "node-name": "node0", 4386 "driver": "raw", 4387 "file": { "driver": "file", 4388 "filename": "fedora.iso" } } } } 4389 4390<- { "return": {} } 4391 4392-> { "execute": "x-blockdev-insert-medium", 4393 "arguments": { "device": "ide1-cd0", 4394 "node-name": "node0" } } 4395 4396<- { "return": {} } 4397 4398EQMP 4399 4400 { 4401 .name = "query-named-block-nodes", 4402 .args_type = "", 4403 .mhandler.cmd_new = qmp_marshal_query_named_block_nodes, 4404 }, 4405 4406SQMP 4407@query-named-block-nodes 4408------------------------ 4409 4410Return a list of BlockDeviceInfo for all the named block driver nodes 4411 4412Example: 4413 4414-> { "execute": "query-named-block-nodes" } 4415<- { "return": [ { "ro":false, 4416 "drv":"qcow2", 4417 "encrypted":false, 4418 "file":"disks/test.qcow2", 4419 "node-name": "my-node", 4420 "backing_file_depth":1, 4421 "bps":1000000, 4422 "bps_rd":0, 4423 "bps_wr":0, 4424 "iops":1000000, 4425 "iops_rd":0, 4426 "iops_wr":0, 4427 "bps_max": 8000000, 4428 "bps_rd_max": 0, 4429 "bps_wr_max": 0, 4430 "iops_max": 0, 4431 "iops_rd_max": 0, 4432 "iops_wr_max": 0, 4433 "iops_size": 0, 4434 "write_threshold": 0, 4435 "image":{ 4436 "filename":"disks/test.qcow2", 4437 "format":"qcow2", 4438 "virtual-size":2048000, 4439 "backing_file":"base.qcow2", 4440 "full-backing-filename":"disks/base.qcow2", 4441 "backing-filename-format":"qcow2", 4442 "snapshots":[ 4443 { 4444 "id": "1", 4445 "name": "snapshot1", 4446 "vm-state-size": 0, 4447 "date-sec": 10000200, 4448 "date-nsec": 12, 4449 "vm-clock-sec": 206, 4450 "vm-clock-nsec": 30 4451 } 4452 ], 4453 "backing-image":{ 4454 "filename":"disks/base.qcow2", 4455 "format":"qcow2", 4456 "virtual-size":2048000 4457 } 4458 } } ] } 4459 4460EQMP 4461 4462 { 4463 .name = "blockdev-change-medium", 4464 .args_type = "device:B,filename:F,format:s?,read-only-mode:s?", 4465 .mhandler.cmd_new = qmp_marshal_blockdev_change_medium, 4466 }, 4467 4468SQMP 4469blockdev-change-medium 4470---------------------- 4471 4472Changes the medium inserted into a block device by ejecting the current medium 4473and loading a new image file which is inserted as the new medium. 4474 4475Arguments: 4476 4477- "device": device name (json-string) 4478- "filename": filename of the new image (json-string) 4479- "format": format of the new image (json-string, optional) 4480- "read-only-mode": new read-only mode (json-string, optional) 4481 - Possible values: "retain" (default), "read-only", "read-write" 4482 4483Examples: 4484 44851. Change a removable medium 4486 4487-> { "execute": "blockdev-change-medium", 4488 "arguments": { "device": "ide1-cd0", 4489 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso", 4490 "format": "raw" } } 4491<- { "return": {} } 4492 44932. Load a read-only medium into a writable drive 4494 4495-> { "execute": "blockdev-change-medium", 4496 "arguments": { "device": "isa-fd0", 4497 "filename": "/srv/images/ro.img", 4498 "format": "raw", 4499 "read-only-mode": "retain" } } 4500 4501<- { "error": 4502 { "class": "GenericError", 4503 "desc": "Could not open '/srv/images/ro.img': Permission denied" } } 4504 4505-> { "execute": "blockdev-change-medium", 4506 "arguments": { "device": "isa-fd0", 4507 "filename": "/srv/images/ro.img", 4508 "format": "raw", 4509 "read-only-mode": "read-only" } } 4510 4511<- { "return": {} } 4512 4513EQMP 4514 4515 { 4516 .name = "query-memdev", 4517 .args_type = "", 4518 .mhandler.cmd_new = qmp_marshal_query_memdev, 4519 }, 4520 4521SQMP 4522query-memdev 4523------------ 4524 4525Show memory devices information. 4526 4527 4528Example (1): 4529 4530-> { "execute": "query-memdev" } 4531<- { "return": [ 4532 { 4533 "size": 536870912, 4534 "merge": false, 4535 "dump": true, 4536 "prealloc": false, 4537 "host-nodes": [0, 1], 4538 "policy": "bind" 4539 }, 4540 { 4541 "size": 536870912, 4542 "merge": false, 4543 "dump": true, 4544 "prealloc": true, 4545 "host-nodes": [2, 3], 4546 "policy": "preferred" 4547 } 4548 ] 4549 } 4550 4551EQMP 4552 4553 { 4554 .name = "query-memory-devices", 4555 .args_type = "", 4556 .mhandler.cmd_new = qmp_marshal_query_memory_devices, 4557 }, 4558 4559SQMP 4560@query-memory-devices 4561-------------------- 4562 4563Return a list of memory devices. 4564 4565Example: 4566-> { "execute": "query-memory-devices" } 4567<- { "return": [ { "data": 4568 { "addr": 5368709120, 4569 "hotpluggable": true, 4570 "hotplugged": true, 4571 "id": "d1", 4572 "memdev": "/objects/memX", 4573 "node": 0, 4574 "size": 1073741824, 4575 "slot": 0}, 4576 "type": "dimm" 4577 } ] } 4578EQMP 4579 4580 { 4581 .name = "query-acpi-ospm-status", 4582 .args_type = "", 4583 .mhandler.cmd_new = qmp_marshal_query_acpi_ospm_status, 4584 }, 4585 4586SQMP 4587@query-acpi-ospm-status 4588-------------------- 4589 4590Return list of ACPIOSTInfo for devices that support status reporting 4591via ACPI _OST method. 4592 4593Example: 4594-> { "execute": "query-acpi-ospm-status" } 4595<- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0}, 4596 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0}, 4597 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0}, 4598 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0} 4599 ]} 4600EQMP 4601 4602#if defined TARGET_I386 4603 { 4604 .name = "rtc-reset-reinjection", 4605 .args_type = "", 4606 .mhandler.cmd_new = qmp_marshal_rtc_reset_reinjection, 4607 }, 4608#endif 4609 4610SQMP 4611rtc-reset-reinjection 4612--------------------- 4613 4614Reset the RTC interrupt reinjection backlog. 4615 4616Arguments: None. 4617 4618Example: 4619 4620-> { "execute": "rtc-reset-reinjection" } 4621<- { "return": {} } 4622EQMP 4623 4624 { 4625 .name = "trace-event-get-state", 4626 .args_type = "name:s", 4627 .mhandler.cmd_new = qmp_marshal_trace_event_get_state, 4628 }, 4629 4630SQMP 4631trace-event-get-state 4632--------------------- 4633 4634Query the state of events. 4635 4636Example: 4637 4638-> { "execute": "trace-event-get-state", "arguments": { "name": "qemu_memalign" } } 4639<- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] } 4640EQMP 4641 4642 { 4643 .name = "trace-event-set-state", 4644 .args_type = "name:s,enable:b,ignore-unavailable:b?", 4645 .mhandler.cmd_new = qmp_marshal_trace_event_set_state, 4646 }, 4647 4648SQMP 4649trace-event-set-state 4650--------------------- 4651 4652Set the state of events. 4653 4654Example: 4655 4656-> { "execute": "trace-event-set-state", "arguments": { "name": "qemu_memalign", "enable": "true" } } 4657<- { "return": {} } 4658EQMP 4659 4660 { 4661 .name = "input-send-event", 4662 .args_type = "console:i?,events:q", 4663 .mhandler.cmd_new = qmp_marshal_input_send_event, 4664 }, 4665 4666SQMP 4667@input-send-event 4668----------------- 4669 4670Send input event to guest. 4671 4672Arguments: 4673 4674- "device": display device (json-string, optional) 4675- "head": display head (json-int, optional) 4676- "events": list of input events 4677 4678The consoles are visible in the qom tree, under 4679/backend/console[$index]. They have a device link and head property, so 4680it is possible to map which console belongs to which device and display. 4681 4682Note: this command is experimental, and not a stable API. 4683 4684Example (1): 4685 4686Press left mouse button. 4687 4688-> { "execute": "input-send-event", 4689 "arguments": { "device": "video0", 4690 "events": [ { "type": "btn", 4691 "data" : { "down": true, "button": "left" } } ] } } 4692<- { "return": {} } 4693 4694-> { "execute": "input-send-event", 4695 "arguments": { "device": "video0", 4696 "events": [ { "type": "btn", 4697 "data" : { "down": false, "button": "left" } } ] } } 4698<- { "return": {} } 4699 4700Example (2): 4701 4702Press ctrl-alt-del. 4703 4704-> { "execute": "input-send-event", 4705 "arguments": { "events": [ 4706 { "type": "key", "data" : { "down": true, 4707 "key": {"type": "qcode", "data": "ctrl" } } }, 4708 { "type": "key", "data" : { "down": true, 4709 "key": {"type": "qcode", "data": "alt" } } }, 4710 { "type": "key", "data" : { "down": true, 4711 "key": {"type": "qcode", "data": "delete" } } } ] } } 4712<- { "return": {} } 4713 4714Example (3): 4715 4716Move mouse pointer to absolute coordinates (20000, 400). 4717 4718-> { "execute": "input-send-event" , 4719 "arguments": { "events": [ 4720 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } }, 4721 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } } 4722<- { "return": {} } 4723 4724EQMP 4725 4726 { 4727 .name = "block-set-write-threshold", 4728 .args_type = "node-name:s,write-threshold:l", 4729 .mhandler.cmd_new = qmp_marshal_block_set_write_threshold, 4730 }, 4731 4732SQMP 4733block-set-write-threshold 4734------------ 4735 4736Change the write threshold for a block drive. The threshold is an offset, 4737thus must be non-negative. Default is no write threshold. 4738Setting the threshold to zero disables it. 4739 4740Arguments: 4741 4742- "node-name": the node name in the block driver state graph (json-string) 4743- "write-threshold": the write threshold in bytes (json-int) 4744 4745Example: 4746 4747-> { "execute": "block-set-write-threshold", 4748 "arguments": { "node-name": "mydev", 4749 "write-threshold": 17179869184 } } 4750<- { "return": {} } 4751 4752EQMP 4753 4754 { 4755 .name = "query-rocker", 4756 .args_type = "name:s", 4757 .mhandler.cmd_new = qmp_marshal_query_rocker, 4758 }, 4759 4760SQMP 4761Show rocker switch 4762------------------ 4763 4764Arguments: 4765 4766- "name": switch name 4767 4768Example: 4769 4770-> { "execute": "query-rocker", "arguments": { "name": "sw1" } } 4771<- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} 4772 4773EQMP 4774 4775 { 4776 .name = "query-rocker-ports", 4777 .args_type = "name:s", 4778 .mhandler.cmd_new = qmp_marshal_query_rocker_ports, 4779 }, 4780 4781SQMP 4782Show rocker switch ports 4783------------------------ 4784 4785Arguments: 4786 4787- "name": switch name 4788 4789Example: 4790 4791-> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } } 4792<- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1", 4793 "autoneg": "off", "link-up": true, "speed": 10000}, 4794 {"duplex": "full", "enabled": true, "name": "sw1.2", 4795 "autoneg": "off", "link-up": true, "speed": 10000} 4796 ]} 4797 4798EQMP 4799 4800 { 4801 .name = "query-rocker-of-dpa-flows", 4802 .args_type = "name:s,tbl-id:i?", 4803 .mhandler.cmd_new = qmp_marshal_query_rocker_of_dpa_flows, 4804 }, 4805 4806SQMP 4807Show rocker switch OF-DPA flow tables 4808------------------------------------- 4809 4810Arguments: 4811 4812- "name": switch name 4813- "tbl-id": (optional) flow table ID 4814 4815Example: 4816 4817-> { "execute": "query-rocker-of-dpa-flows", "arguments": { "name": "sw1" } } 4818<- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0}, 4819 "hits": 138, 4820 "cookie": 0, 4821 "action": {"goto-tbl": 10}, 4822 "mask": {"in-pport": 4294901760} 4823 }, 4824 {...more...}, 4825 ]} 4826 4827EQMP 4828 4829 { 4830 .name = "query-rocker-of-dpa-groups", 4831 .args_type = "name:s,type:i?", 4832 .mhandler.cmd_new = qmp_marshal_query_rocker_of_dpa_groups, 4833 }, 4834 4835SQMP 4836Show rocker OF-DPA group tables 4837------------------------------- 4838 4839Arguments: 4840 4841- "name": switch name 4842- "type": (optional) group type 4843 4844Example: 4845 4846-> { "execute": "query-rocker-of-dpa-groups", "arguments": { "name": "sw1" } } 4847<- { "return": [ {"type": 0, "out-pport": 2, "pport": 2, "vlan-id": 3841, 4848 "pop-vlan": 1, "id": 251723778}, 4849 {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3841, 4850 "pop-vlan": 1, "id": 251723776}, 4851 {"type": 0, "out-pport": 1, "pport": 1, "vlan-id": 3840, 4852 "pop-vlan": 1, "id": 251658241}, 4853 {"type": 0, "out-pport": 0, "pport": 0, "vlan-id": 3840, 4854 "pop-vlan": 1, "id": 251658240} 4855 ]} 4856 4857EQMP 4858 4859#if defined TARGET_ARM 4860 { 4861 .name = "query-gic-capabilities", 4862 .args_type = "", 4863 .mhandler.cmd_new = qmp_marshal_query_gic_capabilities, 4864 }, 4865#endif 4866 4867SQMP 4868query-gic-capabilities 4869--------------- 4870 4871Return a list of GICCapability objects, describing supported GIC 4872(Generic Interrupt Controller) versions. 4873 4874Arguments: None 4875 4876Example: 4877 4878-> { "execute": "query-gic-capabilities" } 4879<- { "return": [{ "version": 2, "emulated": true, "kernel": false }, 4880 { "version": 3, "emulated": false, "kernel": true } ] } 4881 4882EQMP 4883