target-arm: Make the ARM PMCCNTR register 64-bit
[qemu/ar7.git] / qmp-commands.hx
blob7658d4bd24f9f11276716c6d7a9bdff6588a21ca
1 HXCOMM QMP dispatch table and documentation
2 HXCOMM Text between SQMP and EQMP is copied to the QMP documention file and
3 HXCOMM does not show up in the other formats.
5 SQMP
6 QMP Supported Commands
7 ----------------------
9 This document describes all commands currently supported by QMP.
11 Most of the time their usage is exactly the same as in the user Monitor, this
12 means that any other document which also describe commands (the manpage,
13 QEMU's manual, etc) can and should be consulted.
15 QMP has two types of commands: regular and query commands. Regular commands
16 usually change the Virtual Machine's state someway, while query commands just
17 return information. The sections below are divided accordingly.
19 It's important to observe that all communication examples are formatted in
20 a reader-friendly way, so that they're easier to understand. However, in real
21 protocol usage, they're emitted as a single line.
23 Also, the following notation is used to denote data flow:
25 -> data issued by the Client
26 <- Server data response
28 Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed
29 information on the Server command and response formats.
31 NOTE: This document is temporary and will be replaced soon.
33 1. Stability Considerations
34 ===========================
36 The current QMP command set (described in this file) may be useful for a
37 number of use cases, however it's limited and several commands have bad
38 defined semantics, specially with regard to command completion.
40 These problems are going to be solved incrementally in the next QEMU releases
41 and we're going to establish a deprecation policy for badly defined commands.
43 If you're planning to adopt QMP, please observe the following:
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
49 2. DO NOT rely on anything which is not explicit documented
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)
55 2. Regular Commands
56 ===================
58 Server's responses in the examples below are always a success response, please
59 refer to the QMP specification for more details on error responses.
61 EQMP
64 .name = "quit",
65 .args_type = "",
66 .mhandler.cmd_new = qmp_marshal_input_quit,
69 SQMP
70 quit
71 ----
73 Quit the emulator.
75 Arguments: None.
77 Example:
79 -> { "execute": "quit" }
80 <- { "return": {} }
82 EQMP
85 .name = "eject",
86 .args_type = "force:-f,device:B",
87 .mhandler.cmd_new = qmp_marshal_input_eject,
90 SQMP
91 eject
92 -----
94 Eject a removable medium.
96 Arguments:
98 - force: force ejection (json-bool, optional)
99 - device: device name (json-string)
101 Example:
103 -> { "execute": "eject", "arguments": { "device": "ide1-cd0" } }
104 <- { "return": {} }
106 Note: The "force" argument defaults to false.
108 EQMP
111 .name = "change",
112 .args_type = "device:B,target:F,arg:s?",
113 .mhandler.cmd_new = qmp_marshal_input_change,
116 SQMP
117 change
118 ------
120 Change a removable medium or VNC configuration.
122 Arguments:
124 - "device": device name (json-string)
125 - "target": filename or item (json-string)
126 - "arg": additional argument (json-string, optional)
128 Examples:
130 1. Change a removable medium
132 -> { "execute": "change",
133 "arguments": { "device": "ide1-cd0",
134 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
135 <- { "return": {} }
137 2. Change VNC password
139 -> { "execute": "change",
140 "arguments": { "device": "vnc", "target": "password",
141 "arg": "foobar1" } }
142 <- { "return": {} }
144 EQMP
147 .name = "screendump",
148 .args_type = "filename:F",
149 .mhandler.cmd_new = qmp_marshal_input_screendump,
152 SQMP
153 screendump
154 ----------
156 Save screen into PPM image.
158 Arguments:
160 - "filename": file path (json-string)
162 Example:
164 -> { "execute": "screendump", "arguments": { "filename": "/tmp/image" } }
165 <- { "return": {} }
167 EQMP
170 .name = "stop",
171 .args_type = "",
172 .mhandler.cmd_new = qmp_marshal_input_stop,
175 SQMP
176 stop
177 ----
179 Stop the emulator.
181 Arguments: None.
183 Example:
185 -> { "execute": "stop" }
186 <- { "return": {} }
188 EQMP
191 .name = "cont",
192 .args_type = "",
193 .mhandler.cmd_new = qmp_marshal_input_cont,
196 SQMP
197 cont
198 ----
200 Resume emulation.
202 Arguments: None.
204 Example:
206 -> { "execute": "cont" }
207 <- { "return": {} }
209 EQMP
212 .name = "system_wakeup",
213 .args_type = "",
214 .mhandler.cmd_new = qmp_marshal_input_system_wakeup,
217 SQMP
218 system_wakeup
219 -------------
221 Wakeup guest from suspend.
223 Arguments: None.
225 Example:
227 -> { "execute": "system_wakeup" }
228 <- { "return": {} }
230 EQMP
233 .name = "system_reset",
234 .args_type = "",
235 .mhandler.cmd_new = qmp_marshal_input_system_reset,
238 SQMP
239 system_reset
240 ------------
242 Reset the system.
244 Arguments: None.
246 Example:
248 -> { "execute": "system_reset" }
249 <- { "return": {} }
251 EQMP
254 .name = "system_powerdown",
255 .args_type = "",
256 .mhandler.cmd_new = qmp_marshal_input_system_powerdown,
259 SQMP
260 system_powerdown
261 ----------------
263 Send system power down event.
265 Arguments: None.
267 Example:
269 -> { "execute": "system_powerdown" }
270 <- { "return": {} }
272 EQMP
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 .user_print = monitor_user_noop,
280 .mhandler.cmd_new = do_device_add,
283 SQMP
284 device_add
285 ----------
287 Add a device.
289 Arguments:
291 - "driver": the name of the new device's driver (json-string)
292 - "bus": the device's parent bus (device tree path, json-string, optional)
293 - "id": the device's ID, must be unique (json-string)
294 - device properties
296 Example:
298 -> { "execute": "device_add", "arguments": { "driver": "e1000", "id": "net1" } }
299 <- { "return": {} }
301 Notes:
303 (1) For detailed information about this command, please refer to the
304 'docs/qdev-device-use.txt' file.
306 (2) It's possible to list device properties by running QEMU with the
307 "-device DEVICE,\?" command-line argument, where DEVICE is the device's name
309 EQMP
312 .name = "device_del",
313 .args_type = "id:s",
314 .mhandler.cmd_new = qmp_marshal_input_device_del,
317 SQMP
318 device_del
319 ----------
321 Remove a device.
323 Arguments:
325 - "id": the device's ID (json-string)
327 Example:
329 -> { "execute": "device_del", "arguments": { "id": "net1" } }
330 <- { "return": {} }
332 EQMP
335 .name = "send-key",
336 .args_type = "keys:O,hold-time:i?",
337 .mhandler.cmd_new = qmp_marshal_input_send_key,
340 SQMP
341 send-key
342 ----------
344 Send keys to VM.
346 Arguments:
348 keys array:
349 - "key": key sequence (a json-array of key union values,
350 union can be number or qcode enum)
352 - hold-time: time to delay key up events, milliseconds. Defaults to 100
353 (json-int, optional)
355 Example:
357 -> { "execute": "send-key",
358 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
359 { "type": "qcode", "data": "alt" },
360 { "type": "qcode", "data": "delete" } ] } }
361 <- { "return": {} }
363 EQMP
366 .name = "cpu",
367 .args_type = "index:i",
368 .mhandler.cmd_new = qmp_marshal_input_cpu,
371 SQMP
375 Set the default CPU.
377 Arguments:
379 - "index": the CPU's index (json-int)
381 Example:
383 -> { "execute": "cpu", "arguments": { "index": 0 } }
384 <- { "return": {} }
386 Note: CPUs' indexes are obtained with the 'query-cpus' command.
388 EQMP
391 .name = "cpu-add",
392 .args_type = "id:i",
393 .mhandler.cmd_new = qmp_marshal_input_cpu_add,
396 SQMP
397 cpu-add
398 -------
400 Adds virtual cpu
402 Arguments:
404 - "id": cpu id (json-int)
406 Example:
408 -> { "execute": "cpu-add", "arguments": { "id": 2 } }
409 <- { "return": {} }
411 EQMP
414 .name = "memsave",
415 .args_type = "val:l,size:i,filename:s,cpu:i?",
416 .mhandler.cmd_new = qmp_marshal_input_memsave,
419 SQMP
420 memsave
421 -------
423 Save to disk virtual memory dump starting at 'val' of size 'size'.
425 Arguments:
427 - "val": the starting address (json-int)
428 - "size": the memory size, in bytes (json-int)
429 - "filename": file path (json-string)
430 - "cpu": virtual CPU index (json-int, optional)
432 Example:
434 -> { "execute": "memsave",
435 "arguments": { "val": 10,
436 "size": 100,
437 "filename": "/tmp/virtual-mem-dump" } }
438 <- { "return": {} }
440 EQMP
443 .name = "pmemsave",
444 .args_type = "val:l,size:i,filename:s",
445 .mhandler.cmd_new = qmp_marshal_input_pmemsave,
448 SQMP
449 pmemsave
450 --------
452 Save to disk physical memory dump starting at 'val' of size 'size'.
454 Arguments:
456 - "val": the starting address (json-int)
457 - "size": the memory size, in bytes (json-int)
458 - "filename": file path (json-string)
460 Example:
462 -> { "execute": "pmemsave",
463 "arguments": { "val": 10,
464 "size": 100,
465 "filename": "/tmp/physical-mem-dump" } }
466 <- { "return": {} }
468 EQMP
471 .name = "inject-nmi",
472 .args_type = "",
473 .mhandler.cmd_new = qmp_marshal_input_inject_nmi,
476 SQMP
477 inject-nmi
478 ----------
480 Inject an NMI on the default CPU (x86/s390) or all CPUs (ppc64).
482 Arguments: None.
484 Example:
486 -> { "execute": "inject-nmi" }
487 <- { "return": {} }
489 Note: inject-nmi fails when the guest doesn't support injecting.
491 EQMP
494 .name = "ringbuf-write",
495 .args_type = "device:s,data:s,format:s?",
496 .mhandler.cmd_new = qmp_marshal_input_ringbuf_write,
499 SQMP
500 ringbuf-write
501 -------------
503 Write to a ring buffer character device.
505 Arguments:
507 - "device": ring buffer character device name (json-string)
508 - "data": data to write (json-string)
509 - "format": data format (json-string, optional)
510 - Possible values: "utf8" (default), "base64"
511 Bug: invalid base64 is currently not rejected.
512 Whitespace *is* invalid.
514 Example:
516 -> { "execute": "ringbuf-write",
517 "arguments": { "device": "foo",
518 "data": "abcdefgh",
519 "format": "utf8" } }
520 <- { "return": {} }
522 EQMP
525 .name = "ringbuf-read",
526 .args_type = "device:s,size:i,format:s?",
527 .mhandler.cmd_new = qmp_marshal_input_ringbuf_read,
530 SQMP
531 ringbuf-read
532 -------------
534 Read from a ring buffer character device.
536 Arguments:
538 - "device": ring buffer character device name (json-string)
539 - "size": how many bytes to read at most (json-int)
540 - Number of data bytes, not number of characters in encoded data
541 - "format": data format (json-string, optional)
542 - Possible values: "utf8" (default), "base64"
543 - Naturally, format "utf8" works only when the ring buffer
544 contains valid UTF-8 text. Invalid UTF-8 sequences get
545 replaced. Bug: replacement doesn't work. Bug: can screw
546 up on encountering NUL characters, after the ring buffer
547 lost data, and when reading stops because the size limit
548 is reached.
550 Example:
552 -> { "execute": "ringbuf-read",
553 "arguments": { "device": "foo",
554 "size": 1000,
555 "format": "utf8" } }
556 <- {"return": "abcdefgh"}
558 EQMP
561 .name = "xen-save-devices-state",
562 .args_type = "filename:F",
563 .mhandler.cmd_new = qmp_marshal_input_xen_save_devices_state,
566 SQMP
567 xen-save-devices-state
568 -------
570 Save the state of all devices to file. The RAM and the block devices
571 of the VM are not saved by this command.
573 Arguments:
575 - "filename": the file to save the state of the devices to as binary
576 data. See xen-save-devices-state.txt for a description of the binary
577 format.
579 Example:
581 -> { "execute": "xen-save-devices-state",
582 "arguments": { "filename": "/tmp/save" } }
583 <- { "return": {} }
585 EQMP
588 .name = "xen-set-global-dirty-log",
589 .args_type = "enable:b",
590 .mhandler.cmd_new = qmp_marshal_input_xen_set_global_dirty_log,
593 SQMP
594 xen-set-global-dirty-log
595 -------
597 Enable or disable the global dirty log mode.
599 Arguments:
601 - "enable": Enable it or disable it.
603 Example:
605 -> { "execute": "xen-set-global-dirty-log",
606 "arguments": { "enable": true } }
607 <- { "return": {} }
609 EQMP
612 .name = "migrate",
613 .args_type = "detach:-d,blk:-b,inc:-i,uri:s",
614 .mhandler.cmd_new = qmp_marshal_input_migrate,
617 SQMP
618 migrate
619 -------
621 Migrate to URI.
623 Arguments:
625 - "blk": block migration, full disk copy (json-bool, optional)
626 - "inc": incremental disk copy (json-bool, optional)
627 - "uri": Destination URI (json-string)
629 Example:
631 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
632 <- { "return": {} }
634 Notes:
636 (1) The 'query-migrate' command should be used to check migration's progress
637 and final result (this information is provided by the 'status' member)
638 (2) All boolean arguments default to false
639 (3) The user Monitor's "detach" argument is invalid in QMP and should not
640 be used
642 EQMP
645 .name = "migrate_cancel",
646 .args_type = "",
647 .mhandler.cmd_new = qmp_marshal_input_migrate_cancel,
650 SQMP
651 migrate_cancel
652 --------------
654 Cancel the current migration.
656 Arguments: None.
658 Example:
660 -> { "execute": "migrate_cancel" }
661 <- { "return": {} }
663 EQMP
665 .name = "migrate-set-cache-size",
666 .args_type = "value:o",
667 .mhandler.cmd_new = qmp_marshal_input_migrate_set_cache_size,
670 SQMP
671 migrate-set-cache-size
672 ----------------------
674 Set cache size to be used by XBZRLE migration, the cache size will be rounded
675 down to the nearest power of 2
677 Arguments:
679 - "value": cache size in bytes (json-int)
681 Example:
683 -> { "execute": "migrate-set-cache-size", "arguments": { "value": 536870912 } }
684 <- { "return": {} }
686 EQMP
688 .name = "query-migrate-cache-size",
689 .args_type = "",
690 .mhandler.cmd_new = qmp_marshal_input_query_migrate_cache_size,
693 SQMP
694 query-migrate-cache-size
695 ------------------------
697 Show cache size to be used by XBZRLE migration
699 returns a json-object with the following information:
700 - "size" : json-int
702 Example:
704 -> { "execute": "query-migrate-cache-size" }
705 <- { "return": 67108864 }
707 EQMP
710 .name = "migrate_set_speed",
711 .args_type = "value:o",
712 .mhandler.cmd_new = qmp_marshal_input_migrate_set_speed,
715 SQMP
716 migrate_set_speed
717 -----------------
719 Set maximum speed for migrations.
721 Arguments:
723 - "value": maximum speed, in bytes per second (json-int)
725 Example:
727 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
728 <- { "return": {} }
730 EQMP
733 .name = "migrate_set_downtime",
734 .args_type = "value:T",
735 .mhandler.cmd_new = qmp_marshal_input_migrate_set_downtime,
738 SQMP
739 migrate_set_downtime
740 --------------------
742 Set maximum tolerated downtime (in seconds) for migrations.
744 Arguments:
746 - "value": maximum downtime (json-number)
748 Example:
750 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
751 <- { "return": {} }
753 EQMP
756 .name = "client_migrate_info",
757 .args_type = "protocol:s,hostname:s,port:i?,tls-port:i?,cert-subject:s?",
758 .params = "protocol hostname port tls-port cert-subject",
759 .help = "send migration info to spice/vnc client",
760 .user_print = monitor_user_noop,
761 .mhandler.cmd_async = client_migrate_info,
762 .flags = MONITOR_CMD_ASYNC,
765 SQMP
766 client_migrate_info
767 ------------------
769 Set the spice/vnc connection info for the migration target. The spice/vnc
770 server will ask the spice/vnc client to automatically reconnect using the
771 new parameters (if specified) once the vm migration finished successfully.
773 Arguments:
775 - "protocol": protocol: "spice" or "vnc" (json-string)
776 - "hostname": migration target hostname (json-string)
777 - "port": spice/vnc tcp port for plaintext channels (json-int, optional)
778 - "tls-port": spice tcp port for tls-secured channels (json-int, optional)
779 - "cert-subject": server certificate subject (json-string, optional)
781 Example:
783 -> { "execute": "client_migrate_info",
784 "arguments": { "protocol": "spice",
785 "hostname": "virt42.lab.kraxel.org",
786 "port": 1234 } }
787 <- { "return": {} }
789 EQMP
792 .name = "dump-guest-memory",
793 .args_type = "paging:b,protocol:s,begin:i?,end:i?,format:s?",
794 .params = "-p protocol [begin] [length] [format]",
795 .help = "dump guest memory to file",
796 .user_print = monitor_user_noop,
797 .mhandler.cmd_new = qmp_marshal_input_dump_guest_memory,
800 SQMP
801 dump
804 Dump guest memory to file. The file can be processed with crash or gdb.
806 Arguments:
808 - "paging": do paging to get guest's memory mapping (json-bool)
809 - "protocol": destination file(started with "file:") or destination file
810 descriptor (started with "fd:") (json-string)
811 - "begin": the starting physical address. It's optional, and should be specified
812 with length together (json-int)
813 - "length": the memory size, in bytes. It's optional, and should be specified
814 with begin together (json-int)
815 - "format": the format of guest memory dump. It's optional, and can be
816 elf|kdump-zlib|kdump-lzo|kdump-snappy, but non-elf formats will
817 conflict with paging and filter, ie. begin and length (json-string)
819 Example:
821 -> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
822 <- { "return": {} }
824 Notes:
826 (1) All boolean arguments default to false
828 EQMP
831 .name = "query-dump-guest-memory-capability",
832 .args_type = "",
833 .mhandler.cmd_new = qmp_marshal_input_query_dump_guest_memory_capability,
836 SQMP
837 query-dump-guest-memory-capability
838 ----------
840 Show available formats for 'dump-guest-memory'
842 Example:
844 -> { "execute": "query-dump-guest-memory-capability" }
845 <- { "return": { "formats":
846 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
848 EQMP
851 .name = "netdev_add",
852 .args_type = "netdev:O",
853 .mhandler.cmd_new = qmp_netdev_add,
856 SQMP
857 netdev_add
858 ----------
860 Add host network device.
862 Arguments:
864 - "type": the device type, "tap", "user", ... (json-string)
865 - "id": the device's ID, must be unique (json-string)
866 - device options
868 Example:
870 -> { "execute": "netdev_add", "arguments": { "type": "user", "id": "netdev1" } }
871 <- { "return": {} }
873 Note: The supported device options are the same ones supported by the '-netdev'
874 command-line argument, which are listed in the '-help' output or QEMU's
875 manual
877 EQMP
880 .name = "netdev_del",
881 .args_type = "id:s",
882 .mhandler.cmd_new = qmp_marshal_input_netdev_del,
885 SQMP
886 netdev_del
887 ----------
889 Remove host network device.
891 Arguments:
893 - "id": the device's ID, must be unique (json-string)
895 Example:
897 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
898 <- { "return": {} }
901 EQMP
904 .name = "object-add",
905 .args_type = "qom-type:s,id:s,props:q?",
906 .mhandler.cmd_new = qmp_object_add,
909 SQMP
910 object-add
911 ----------
913 Create QOM object.
915 Arguments:
917 - "qom-type": the object's QOM type, i.e. the class name (json-string)
918 - "id": the object's ID, must be unique (json-string)
919 - "props": a dictionary of object property values (optional, json-dict)
921 Example:
923 -> { "execute": "object-add", "arguments": { "qom-type": "rng-random", "id": "rng1",
924 "props": { "filename": "/dev/hwrng" } } }
925 <- { "return": {} }
927 EQMP
930 .name = "object-del",
931 .args_type = "id:s",
932 .mhandler.cmd_new = qmp_marshal_input_object_del,
935 SQMP
936 object-del
937 ----------
939 Remove QOM object.
941 Arguments:
943 - "id": the object's ID (json-string)
945 Example:
947 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
948 <- { "return": {} }
951 EQMP
955 .name = "block_resize",
956 .args_type = "device:s?,node-name:s?,size:o",
957 .mhandler.cmd_new = qmp_marshal_input_block_resize,
960 SQMP
961 block_resize
962 ------------
964 Resize a block image while a guest is running.
966 Arguments:
968 - "device": the device's ID, must be unique (json-string)
969 - "node-name": the node name in the block driver state graph (json-string)
970 - "size": new size
972 Example:
974 -> { "execute": "block_resize", "arguments": { "device": "scratch", "size": 1073741824 } }
975 <- { "return": {} }
977 EQMP
980 .name = "block-stream",
981 .args_type = "device:B,base:s?,speed:o?,backing-file:s?,on-error:s?",
982 .mhandler.cmd_new = qmp_marshal_input_block_stream,
986 .name = "block-commit",
987 .args_type = "device:B,base:s?,top:s?,backing-file:s?,speed:o?",
988 .mhandler.cmd_new = qmp_marshal_input_block_commit,
991 SQMP
992 block-commit
993 ------------
995 Live commit of data from overlay image nodes into backing nodes - i.e., writes
996 data between 'top' and 'base' into 'base'.
998 Arguments:
1000 - "device": The device's ID, must be unique (json-string)
1001 - "base": The file name of the backing image to write data into.
1002 If not specified, this is the deepest backing image
1003 (json-string, optional)
1004 - "top": The file name of the backing image within the image chain,
1005 which contains the topmost data to be committed down. If
1006 not specified, this is the active layer. (json-string, optional)
1008 - backing-file: The backing file string to write into the overlay
1009 image of 'top'. If 'top' is the active layer,
1010 specifying a backing file string is an error. This
1011 filename is not validated.
1013 If a pathname string is such that it cannot be
1014 resolved by QEMU, that means that subsequent QMP or
1015 HMP commands must use node-names for the image in
1016 question, as filename lookup methods will fail.
1018 If not specified, QEMU will automatically determine
1019 the backing file string to use, or error out if
1020 there is no obvious choice. Care should be taken
1021 when specifying the string, to specify a valid
1022 filename or protocol.
1023 (json-string, optional) (Since 2.1)
1025 If top == base, that is an error.
1026 If top == active, the job will not be completed by itself,
1027 user needs to complete the job with the block-job-complete
1028 command after getting the ready event. (Since 2.0)
1030 If the base image is smaller than top, then the base image
1031 will be resized to be the same size as top. If top is
1032 smaller than the base image, the base will not be
1033 truncated. If you want the base image size to match the
1034 size of the smaller top, you can safely truncate it
1035 yourself once the commit operation successfully completes.
1036 (json-string)
1037 - "speed": the maximum speed, in bytes per second (json-int, optional)
1040 Example:
1042 -> { "execute": "block-commit", "arguments": { "device": "virtio0",
1043 "top": "/tmp/snap1.qcow2" } }
1044 <- { "return": {} }
1046 EQMP
1049 .name = "drive-backup",
1050 .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
1051 "on-source-error:s?,on-target-error:s?",
1052 .mhandler.cmd_new = qmp_marshal_input_drive_backup,
1055 SQMP
1056 drive-backup
1057 ------------
1059 Start a point-in-time copy of a block device to a new destination. The
1060 status of ongoing drive-backup operations can be checked with
1061 query-block-jobs where the BlockJobInfo.type field has the value 'backup'.
1062 The operation can be stopped before it has completed using the
1063 block-job-cancel command.
1065 Arguments:
1067 - "device": the name of the device which should be copied.
1068 (json-string)
1069 - "target": the target of the new image. If the file exists, or if it is a
1070 device, the existing file/device will be used as the new
1071 destination. If it does not exist, a new file will be created.
1072 (json-string)
1073 - "format": the format of the new destination, default is to probe if 'mode' is
1074 'existing', else the format of the source
1075 (json-string, optional)
1076 - "sync": what parts of the disk image should be copied to the destination;
1077 possibilities include "full" for all the disk, "top" for only the sectors
1078 allocated in the topmost image, or "none" to only replicate new I/O
1079 (MirrorSyncMode).
1080 - "mode": whether and how QEMU should create a new image
1081 (NewImageMode, optional, default 'absolute-paths')
1082 - "speed": the maximum speed, in bytes per second (json-int, optional)
1083 - "on-source-error": the action to take on an error on the source, default
1084 'report'. 'stop' and 'enospc' can only be used
1085 if the block device supports io-status.
1086 (BlockdevOnError, optional)
1087 - "on-target-error": the action to take on an error on the target, default
1088 'report' (no limitations, since this applies to
1089 a different block device than device).
1090 (BlockdevOnError, optional)
1092 Example:
1093 -> { "execute": "drive-backup", "arguments": { "device": "drive0",
1094 "sync": "full",
1095 "target": "backup.img" } }
1096 <- { "return": {} }
1097 EQMP
1100 .name = "block-job-set-speed",
1101 .args_type = "device:B,speed:o",
1102 .mhandler.cmd_new = qmp_marshal_input_block_job_set_speed,
1106 .name = "block-job-cancel",
1107 .args_type = "device:B,force:b?",
1108 .mhandler.cmd_new = qmp_marshal_input_block_job_cancel,
1111 .name = "block-job-pause",
1112 .args_type = "device:B",
1113 .mhandler.cmd_new = qmp_marshal_input_block_job_pause,
1116 .name = "block-job-resume",
1117 .args_type = "device:B",
1118 .mhandler.cmd_new = qmp_marshal_input_block_job_resume,
1121 .name = "block-job-complete",
1122 .args_type = "device:B",
1123 .mhandler.cmd_new = qmp_marshal_input_block_job_complete,
1126 .name = "transaction",
1127 .args_type = "actions:q",
1128 .mhandler.cmd_new = qmp_marshal_input_transaction,
1131 SQMP
1132 transaction
1133 -----------
1135 Atomically operate on one or more block devices. The only supported operations
1136 for now are drive-backup, internal and external snapshotting. A list of
1137 dictionaries is accepted, that contains the actions to be performed.
1138 If there is any failure performing any of the operations, all operations
1139 for the group are abandoned.
1141 For external snapshots, the dictionary contains the device, the file to use for
1142 the new snapshot, and the format. The default format, if not specified, is
1143 qcow2.
1145 Each new snapshot defaults to being created by QEMU (wiping any
1146 contents if the file already exists), but it is also possible to reuse
1147 an externally-created file. In the latter case, you should ensure that
1148 the new image file has the same contents as the current one; QEMU cannot
1149 perform any meaningful check. Typically this is achieved by using the
1150 current image file as the backing file for the new image.
1152 On failure, the original disks pre-snapshot attempt will be used.
1154 For internal snapshots, the dictionary contains the device and the snapshot's
1155 name. If an internal snapshot matching name already exists, the request will
1156 be rejected. Only some image formats support it, for example, qcow2, rbd,
1157 and sheepdog.
1159 On failure, qemu will try delete the newly created internal snapshot in the
1160 transaction. When an I/O error occurs during deletion, the user needs to fix
1161 it later with qemu-img or other command.
1163 Arguments:
1165 actions array:
1166 - "type": the operation to perform. The only supported
1167 value is "blockdev-snapshot-sync". (json-string)
1168 - "data": a dictionary. The contents depend on the value
1169 of "type". When "type" is "blockdev-snapshot-sync":
1170 - "device": device name to snapshot (json-string)
1171 - "node-name": graph node name to snapshot (json-string)
1172 - "snapshot-file": name of new image file (json-string)
1173 - "snapshot-node-name": graph node name of the new snapshot (json-string)
1174 - "format": format of new image (json-string, optional)
1175 - "mode": whether and how QEMU should create the snapshot file
1176 (NewImageMode, optional, default "absolute-paths")
1177 When "type" is "blockdev-snapshot-internal-sync":
1178 - "device": device name to snapshot (json-string)
1179 - "name": name of the new snapshot (json-string)
1181 Example:
1183 -> { "execute": "transaction",
1184 "arguments": { "actions": [
1185 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
1186 "snapshot-file": "/some/place/my-image",
1187 "format": "qcow2" } },
1188 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
1189 "snapshot-file": "/some/place/my-image2",
1190 "snapshot-node-name": "node3432",
1191 "mode": "existing",
1192 "format": "qcow2" } },
1193 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
1194 "snapshot-file": "/some/place/my-image2",
1195 "mode": "existing",
1196 "format": "qcow2" } },
1197 { "type": "blockdev-snapshot-internal-sync", "data" : {
1198 "device": "ide-hd2",
1199 "name": "snapshot0" } } ] } }
1200 <- { "return": {} }
1202 EQMP
1205 .name = "blockdev-snapshot-sync",
1206 .args_type = "device:s?,node-name:s?,snapshot-file:s,snapshot-node-name:s?,format:s?,mode:s?",
1207 .mhandler.cmd_new = qmp_marshal_input_blockdev_snapshot_sync,
1210 SQMP
1211 blockdev-snapshot-sync
1212 ----------------------
1214 Synchronous snapshot of a block device. snapshot-file specifies the
1215 target of the new image. If the file exists, or if it is a device, the
1216 snapshot will be created in the existing file/device. If does not
1217 exist, a new file will be created. format specifies the format of the
1218 snapshot image, default is qcow2.
1220 Arguments:
1222 - "device": device name to snapshot (json-string)
1223 - "node-name": graph node name to snapshot (json-string)
1224 - "snapshot-file": name of new image file (json-string)
1225 - "snapshot-node-name": graph node name of the new snapshot (json-string)
1226 - "mode": whether and how QEMU should create the snapshot file
1227 (NewImageMode, optional, default "absolute-paths")
1228 - "format": format of new image (json-string, optional)
1230 Example:
1232 -> { "execute": "blockdev-snapshot-sync", "arguments": { "device": "ide-hd0",
1233 "snapshot-file":
1234 "/some/place/my-image",
1235 "format": "qcow2" } }
1236 <- { "return": {} }
1238 EQMP
1241 .name = "blockdev-snapshot-internal-sync",
1242 .args_type = "device:B,name:s",
1243 .mhandler.cmd_new = qmp_marshal_input_blockdev_snapshot_internal_sync,
1246 SQMP
1247 blockdev-snapshot-internal-sync
1248 -------------------------------
1250 Synchronously take an internal snapshot of a block device when the format of
1251 image used supports it. If the name is an empty string, or a snapshot with
1252 name already exists, the operation will fail.
1254 Arguments:
1256 - "device": device name to snapshot (json-string)
1257 - "name": name of the new snapshot (json-string)
1259 Example:
1261 -> { "execute": "blockdev-snapshot-internal-sync",
1262 "arguments": { "device": "ide-hd0",
1263 "name": "snapshot0" }
1265 <- { "return": {} }
1267 EQMP
1270 .name = "blockdev-snapshot-delete-internal-sync",
1271 .args_type = "device:B,id:s?,name:s?",
1272 .mhandler.cmd_new =
1273 qmp_marshal_input_blockdev_snapshot_delete_internal_sync,
1276 SQMP
1277 blockdev-snapshot-delete-internal-sync
1278 --------------------------------------
1280 Synchronously delete an internal snapshot of a block device when the format of
1281 image used supports it. The snapshot is identified by name or id or both. One
1282 of name or id is required. If the snapshot is not found, the operation will
1283 fail.
1285 Arguments:
1287 - "device": device name (json-string)
1288 - "id": ID of the snapshot (json-string, optional)
1289 - "name": name of the snapshot (json-string, optional)
1291 Example:
1293 -> { "execute": "blockdev-snapshot-delete-internal-sync",
1294 "arguments": { "device": "ide-hd0",
1295 "name": "snapshot0" }
1297 <- { "return": {
1298 "id": "1",
1299 "name": "snapshot0",
1300 "vm-state-size": 0,
1301 "date-sec": 1000012,
1302 "date-nsec": 10,
1303 "vm-clock-sec": 100,
1304 "vm-clock-nsec": 20
1308 EQMP
1311 .name = "drive-mirror",
1312 .args_type = "sync:s,device:B,target:s,speed:i?,mode:s?,format:s?,"
1313 "node-name:s?,replaces:s?,"
1314 "on-source-error:s?,on-target-error:s?,"
1315 "granularity:i?,buf-size:i?",
1316 .mhandler.cmd_new = qmp_marshal_input_drive_mirror,
1319 SQMP
1320 drive-mirror
1321 ------------
1323 Start mirroring a block device's writes to a new destination. target
1324 specifies the target of the new image. If the file exists, or if it is
1325 a device, it will be used as the new destination for writes. If it does not
1326 exist, a new file will be created. format specifies the format of the
1327 mirror image, default is to probe if mode='existing', else the format
1328 of the source.
1330 Arguments:
1332 - "device": device name to operate on (json-string)
1333 - "target": name of new image file (json-string)
1334 - "format": format of new image (json-string, optional)
1335 - "node-name": the name of the new block driver state in the node graph
1336 (json-string, optional)
1337 - "replaces": the block driver node name to replace when finished
1338 (json-string, optional)
1339 - "mode": how an image file should be created into the target
1340 file/device (NewImageMode, optional, default 'absolute-paths')
1341 - "speed": maximum speed of the streaming job, in bytes per second
1342 (json-int)
1343 - "granularity": granularity of the dirty bitmap, in bytes (json-int, optional)
1344 - "buf_size": maximum amount of data in flight from source to target, in bytes
1345 (json-int, default 10M)
1346 - "sync": what parts of the disk image should be copied to the destination;
1347 possibilities include "full" for all the disk, "top" for only the sectors
1348 allocated in the topmost image, or "none" to only replicate new I/O
1349 (MirrorSyncMode).
1350 - "on-source-error": the action to take on an error on the source
1351 (BlockdevOnError, default 'report')
1352 - "on-target-error": the action to take on an error on the target
1353 (BlockdevOnError, default 'report')
1355 The default value of the granularity is the image cluster size clamped
1356 between 4096 and 65536, if the image format defines one. If the format
1357 does not define a cluster size, the default value of the granularity
1358 is 65536.
1361 Example:
1363 -> { "execute": "drive-mirror", "arguments": { "device": "ide-hd0",
1364 "target": "/some/place/my-image",
1365 "sync": "full",
1366 "format": "qcow2" } }
1367 <- { "return": {} }
1369 EQMP
1372 .name = "change-backing-file",
1373 .args_type = "device:s,image-node-name:s,backing-file:s",
1374 .mhandler.cmd_new = qmp_marshal_input_change_backing_file,
1377 SQMP
1378 change-backing-file
1379 -------------------
1380 Since: 2.1
1382 Change the backing file in the image file metadata. This does not cause
1383 QEMU to reopen the image file to reparse the backing filename (it may,
1384 however, perform a reopen to change permissions from r/o -> r/w -> r/o,
1385 if needed). The new backing file string is written into the image file
1386 metadata, and the QEMU internal strings are updated.
1388 Arguments:
1390 - "image-node-name": The name of the block driver state node of the
1391 image to modify. The "device" is argument is used to
1392 verify "image-node-name" is in the chain described by
1393 "device".
1394 (json-string, optional)
1396 - "device": The name of the device.
1397 (json-string)
1399 - "backing-file": The string to write as the backing file. This string is
1400 not validated, so care should be taken when specifying
1401 the string or the image chain may not be able to be
1402 reopened again.
1403 (json-string)
1405 Returns: Nothing on success
1406 If "device" does not exist or cannot be determined, DeviceNotFound
1408 EQMP
1411 .name = "balloon",
1412 .args_type = "value:M",
1413 .mhandler.cmd_new = qmp_marshal_input_balloon,
1416 SQMP
1417 balloon
1418 -------
1420 Request VM to change its memory allocation (in bytes).
1422 Arguments:
1424 - "value": New memory allocation (json-int)
1426 Example:
1428 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
1429 <- { "return": {} }
1431 EQMP
1434 .name = "set_link",
1435 .args_type = "name:s,up:b",
1436 .mhandler.cmd_new = qmp_marshal_input_set_link,
1439 SQMP
1440 set_link
1441 --------
1443 Change the link status of a network adapter.
1445 Arguments:
1447 - "name": network device name (json-string)
1448 - "up": status is up (json-bool)
1450 Example:
1452 -> { "execute": "set_link", "arguments": { "name": "e1000.0", "up": false } }
1453 <- { "return": {} }
1455 EQMP
1458 .name = "getfd",
1459 .args_type = "fdname:s",
1460 .params = "getfd name",
1461 .help = "receive a file descriptor via SCM rights and assign it a name",
1462 .mhandler.cmd_new = qmp_marshal_input_getfd,
1465 SQMP
1466 getfd
1467 -----
1469 Receive a file descriptor via SCM rights and assign it a name.
1471 Arguments:
1473 - "fdname": file descriptor name (json-string)
1475 Example:
1477 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
1478 <- { "return": {} }
1480 Notes:
1482 (1) If the name specified by the "fdname" argument already exists,
1483 the file descriptor assigned to it will be closed and replaced
1484 by the received file descriptor.
1485 (2) The 'closefd' command can be used to explicitly close the file
1486 descriptor when it is no longer needed.
1488 EQMP
1491 .name = "closefd",
1492 .args_type = "fdname:s",
1493 .params = "closefd name",
1494 .help = "close a file descriptor previously passed via SCM rights",
1495 .mhandler.cmd_new = qmp_marshal_input_closefd,
1498 SQMP
1499 closefd
1500 -------
1502 Close a file descriptor previously passed via SCM rights.
1504 Arguments:
1506 - "fdname": file descriptor name (json-string)
1508 Example:
1510 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
1511 <- { "return": {} }
1513 EQMP
1516 .name = "add-fd",
1517 .args_type = "fdset-id:i?,opaque:s?",
1518 .params = "add-fd fdset-id opaque",
1519 .help = "Add a file descriptor, that was passed via SCM rights, to an fd set",
1520 .mhandler.cmd_new = qmp_marshal_input_add_fd,
1523 SQMP
1524 add-fd
1525 -------
1527 Add a file descriptor, that was passed via SCM rights, to an fd set.
1529 Arguments:
1531 - "fdset-id": The ID of the fd set to add the file descriptor to.
1532 (json-int, optional)
1533 - "opaque": A free-form string that can be used to describe the fd.
1534 (json-string, optional)
1536 Return a json-object with the following information:
1538 - "fdset-id": The ID of the fd set that the fd was added to. (json-int)
1539 - "fd": The file descriptor that was received via SCM rights and added to the
1540 fd set. (json-int)
1542 Example:
1544 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
1545 <- { "return": { "fdset-id": 1, "fd": 3 } }
1547 Notes:
1549 (1) The list of fd sets is shared by all monitor connections.
1550 (2) If "fdset-id" is not specified, a new fd set will be created.
1552 EQMP
1555 .name = "remove-fd",
1556 .args_type = "fdset-id:i,fd:i?",
1557 .params = "remove-fd fdset-id fd",
1558 .help = "Remove a file descriptor from an fd set",
1559 .mhandler.cmd_new = qmp_marshal_input_remove_fd,
1562 SQMP
1563 remove-fd
1564 ---------
1566 Remove a file descriptor from an fd set.
1568 Arguments:
1570 - "fdset-id": The ID of the fd set that the file descriptor belongs to.
1571 (json-int)
1572 - "fd": The file descriptor that is to be removed. (json-int, optional)
1574 Example:
1576 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
1577 <- { "return": {} }
1579 Notes:
1581 (1) The list of fd sets is shared by all monitor connections.
1582 (2) If "fd" is not specified, all file descriptors in "fdset-id" will be
1583 removed.
1585 EQMP
1588 .name = "query-fdsets",
1589 .args_type = "",
1590 .help = "Return information describing all fd sets",
1591 .mhandler.cmd_new = qmp_marshal_input_query_fdsets,
1594 SQMP
1595 query-fdsets
1596 -------------
1598 Return information describing all fd sets.
1600 Arguments: None
1602 Example:
1604 -> { "execute": "query-fdsets" }
1605 <- { "return": [
1607 "fds": [
1609 "fd": 30,
1610 "opaque": "rdonly:/path/to/file"
1613 "fd": 24,
1614 "opaque": "rdwr:/path/to/file"
1617 "fdset-id": 1
1620 "fds": [
1622 "fd": 28
1625 "fd": 29
1628 "fdset-id": 0
1633 Note: The list of fd sets is shared by all monitor connections.
1635 EQMP
1638 .name = "block_passwd",
1639 .args_type = "device:s?,node-name:s?,password:s",
1640 .mhandler.cmd_new = qmp_marshal_input_block_passwd,
1643 SQMP
1644 block_passwd
1645 ------------
1647 Set the password of encrypted block devices.
1649 Arguments:
1651 - "device": device name (json-string)
1652 - "node-name": name in the block driver state graph (json-string)
1653 - "password": password (json-string)
1655 Example:
1657 -> { "execute": "block_passwd", "arguments": { "device": "ide0-hd0",
1658 "password": "12345" } }
1659 <- { "return": {} }
1661 EQMP
1664 .name = "block_set_io_throttle",
1665 .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?,iops_size:l?",
1666 .mhandler.cmd_new = qmp_marshal_input_block_set_io_throttle,
1669 SQMP
1670 block_set_io_throttle
1671 ------------
1673 Change I/O throttle limits for a block drive.
1675 Arguments:
1677 - "device": device name (json-string)
1678 - "bps": total throughput limit in bytes per second (json-int)
1679 - "bps_rd": read throughput limit in bytes per second (json-int)
1680 - "bps_wr": write throughput limit in bytes per second (json-int)
1681 - "iops": total I/O operations per second (json-int)
1682 - "iops_rd": read I/O operations per second (json-int)
1683 - "iops_wr": write I/O operations per second (json-int)
1684 - "bps_max": total max in bytes (json-int)
1685 - "bps_rd_max": read max in bytes (json-int)
1686 - "bps_wr_max": write max in bytes (json-int)
1687 - "iops_max": total I/O operations max (json-int)
1688 - "iops_rd_max": read I/O operations max (json-int)
1689 - "iops_wr_max": write I/O operations max (json-int)
1690 - "iops_size": I/O size in bytes when limiting (json-int)
1692 Example:
1694 -> { "execute": "block_set_io_throttle", "arguments": { "device": "virtio0",
1695 "bps": 1000000,
1696 "bps_rd": 0,
1697 "bps_wr": 0,
1698 "iops": 0,
1699 "iops_rd": 0,
1700 "iops_wr": 0,
1701 "bps_max": 8000000,
1702 "bps_rd_max": 0,
1703 "bps_wr_max": 0,
1704 "iops_max": 0,
1705 "iops_rd_max": 0,
1706 "iops_wr_max": 0,
1707 "iops_size": 0 } }
1708 <- { "return": {} }
1710 EQMP
1713 .name = "set_password",
1714 .args_type = "protocol:s,password:s,connected:s?",
1715 .mhandler.cmd_new = qmp_marshal_input_set_password,
1718 SQMP
1719 set_password
1720 ------------
1722 Set the password for vnc/spice protocols.
1724 Arguments:
1726 - "protocol": protocol name (json-string)
1727 - "password": password (json-string)
1728 - "connected": [ keep | disconnect | fail ] (josn-string, optional)
1730 Example:
1732 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
1733 "password": "secret" } }
1734 <- { "return": {} }
1736 EQMP
1739 .name = "expire_password",
1740 .args_type = "protocol:s,time:s",
1741 .mhandler.cmd_new = qmp_marshal_input_expire_password,
1744 SQMP
1745 expire_password
1746 ---------------
1748 Set the password expire time for vnc/spice protocols.
1750 Arguments:
1752 - "protocol": protocol name (json-string)
1753 - "time": [ now | never | +secs | secs ] (json-string)
1755 Example:
1757 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
1758 "time": "+60" } }
1759 <- { "return": {} }
1761 EQMP
1764 .name = "add_client",
1765 .args_type = "protocol:s,fdname:s,skipauth:b?,tls:b?",
1766 .mhandler.cmd_new = qmp_marshal_input_add_client,
1769 SQMP
1770 add_client
1771 ----------
1773 Add a graphics client
1775 Arguments:
1777 - "protocol": protocol name (json-string)
1778 - "fdname": file descriptor name (json-string)
1779 - "skipauth": whether to skip authentication (json-bool, optional)
1780 - "tls": whether to perform TLS (json-bool, optional)
1782 Example:
1784 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
1785 "fdname": "myclient" } }
1786 <- { "return": {} }
1788 EQMP
1790 .name = "qmp_capabilities",
1791 .args_type = "",
1792 .params = "",
1793 .help = "enable QMP capabilities",
1794 .user_print = monitor_user_noop,
1795 .mhandler.cmd_new = do_qmp_capabilities,
1798 SQMP
1799 qmp_capabilities
1800 ----------------
1802 Enable QMP capabilities.
1804 Arguments: None.
1806 Example:
1808 -> { "execute": "qmp_capabilities" }
1809 <- { "return": {} }
1811 Note: This command must be issued before issuing any other command.
1813 EQMP
1816 .name = "human-monitor-command",
1817 .args_type = "command-line:s,cpu-index:i?",
1818 .mhandler.cmd_new = qmp_marshal_input_human_monitor_command,
1821 SQMP
1822 human-monitor-command
1823 ---------------------
1825 Execute a Human Monitor command.
1827 Arguments:
1829 - command-line: the command name and its arguments, just like the
1830 Human Monitor's shell (json-string)
1831 - cpu-index: select the CPU number to be used by commands which access CPU
1832 data, like 'info registers'. The Monitor selects CPU 0 if this
1833 argument is not provided (json-int, optional)
1835 Example:
1837 -> { "execute": "human-monitor-command", "arguments": { "command-line": "info kvm" } }
1838 <- { "return": "kvm support: enabled\r\n" }
1840 Notes:
1842 (1) The Human Monitor is NOT an stable interface, this means that command
1843 names, arguments and responses can change or be removed at ANY time.
1844 Applications that rely on long term stability guarantees should NOT
1845 use this command
1847 (2) Limitations:
1849 o This command is stateless, this means that commands that depend
1850 on state information (such as getfd) might not work
1852 o Commands that prompt the user for data (eg. 'cont' when the block
1853 device is encrypted) don't currently work
1855 3. Query Commands
1856 =================
1858 HXCOMM Each query command below is inside a SQMP/EQMP section, do NOT change
1859 HXCOMM this! We will possibly move query commands definitions inside those
1860 HXCOMM sections, just like regular commands.
1862 EQMP
1864 SQMP
1865 query-version
1866 -------------
1868 Show QEMU version.
1870 Return a json-object with the following information:
1872 - "qemu": A json-object containing three integer values:
1873 - "major": QEMU's major version (json-int)
1874 - "minor": QEMU's minor version (json-int)
1875 - "micro": QEMU's micro version (json-int)
1876 - "package": package's version (json-string)
1878 Example:
1880 -> { "execute": "query-version" }
1881 <- {
1882 "return":{
1883 "qemu":{
1884 "major":0,
1885 "minor":11,
1886 "micro":5
1888 "package":""
1892 EQMP
1895 .name = "query-version",
1896 .args_type = "",
1897 .mhandler.cmd_new = qmp_marshal_input_query_version,
1900 SQMP
1901 query-commands
1902 --------------
1904 List QMP available commands.
1906 Each command is represented by a json-object, the returned value is a json-array
1907 of all commands.
1909 Each json-object contain:
1911 - "name": command's name (json-string)
1913 Example:
1915 -> { "execute": "query-commands" }
1916 <- {
1917 "return":[
1919 "name":"query-balloon"
1922 "name":"system_powerdown"
1927 Note: This example has been shortened as the real response is too long.
1929 EQMP
1932 .name = "query-commands",
1933 .args_type = "",
1934 .mhandler.cmd_new = qmp_marshal_input_query_commands,
1937 SQMP
1938 query-events
1939 --------------
1941 List QMP available events.
1943 Each event is represented by a json-object, the returned value is a json-array
1944 of all events.
1946 Each json-object contains:
1948 - "name": event's name (json-string)
1950 Example:
1952 -> { "execute": "query-events" }
1953 <- {
1954 "return":[
1956 "name":"SHUTDOWN"
1959 "name":"RESET"
1964 Note: This example has been shortened as the real response is too long.
1966 EQMP
1969 .name = "query-events",
1970 .args_type = "",
1971 .mhandler.cmd_new = qmp_marshal_input_query_events,
1974 SQMP
1975 query-chardev
1976 -------------
1978 Each device is represented by a json-object. The returned value is a json-array
1979 of all devices.
1981 Each json-object contain the following:
1983 - "label": device's label (json-string)
1984 - "filename": device's file (json-string)
1985 - "frontend-open": open/closed state of the frontend device attached to this
1986 backend (json-bool)
1988 Example:
1990 -> { "execute": "query-chardev" }
1991 <- {
1992 "return": [
1994 "label": "charchannel0",
1995 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
1996 "frontend-open": false
1999 "label": "charmonitor",
2000 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
2001 "frontend-open": true
2004 "label": "charserial0",
2005 "filename": "pty:/dev/pts/2",
2006 "frontend-open": true
2011 EQMP
2014 .name = "query-chardev",
2015 .args_type = "",
2016 .mhandler.cmd_new = qmp_marshal_input_query_chardev,
2019 SQMP
2020 query-chardev-backends
2021 -------------
2023 List available character device backends.
2025 Each backend is represented by a json-object, the returned value is a json-array
2026 of all backends.
2028 Each json-object contains:
2030 - "name": backend name (json-string)
2032 Example:
2034 -> { "execute": "query-chardev-backends" }
2035 <- {
2036 "return":[
2038 "name":"udp"
2041 "name":"tcp"
2044 "name":"unix"
2047 "name":"spiceport"
2052 EQMP
2055 .name = "query-chardev-backends",
2056 .args_type = "",
2057 .mhandler.cmd_new = qmp_marshal_input_query_chardev_backends,
2060 SQMP
2061 query-block
2062 -----------
2064 Show the block devices.
2066 Each block device information is stored in a json-object and the returned value
2067 is a json-array of all devices.
2069 Each json-object contain the following:
2071 - "device": device name (json-string)
2072 - "type": device type (json-string)
2073 - deprecated, retained for backward compatibility
2074 - Possible values: "unknown"
2075 - "removable": true if the device is removable, false otherwise (json-bool)
2076 - "locked": true if the device is locked, false otherwise (json-bool)
2077 - "tray_open": only present if removable, true if the device has a tray,
2078 and it is open (json-bool)
2079 - "inserted": only present if the device is inserted, it is a json-object
2080 containing the following:
2081 - "file": device file name (json-string)
2082 - "ro": true if read-only, false otherwise (json-bool)
2083 - "drv": driver format name (json-string)
2084 - Possible values: "blkdebug", "bochs", "cloop", "cow", "dmg",
2085 "file", "file", "ftp", "ftps", "host_cdrom",
2086 "host_device", "host_floppy", "http", "https",
2087 "nbd", "parallels", "qcow", "qcow2", "raw",
2088 "tftp", "vdi", "vmdk", "vpc", "vvfat"
2089 - "backing_file": backing file name (json-string, optional)
2090 - "backing_file_depth": number of files in the backing file chain (json-int)
2091 - "encrypted": true if encrypted, false otherwise (json-bool)
2092 - "bps": limit total bytes per second (json-int)
2093 - "bps_rd": limit read bytes per second (json-int)
2094 - "bps_wr": limit write bytes per second (json-int)
2095 - "iops": limit total I/O operations per second (json-int)
2096 - "iops_rd": limit read operations per second (json-int)
2097 - "iops_wr": limit write operations per second (json-int)
2098 - "bps_max": total max in bytes (json-int)
2099 - "bps_rd_max": read max in bytes (json-int)
2100 - "bps_wr_max": write max in bytes (json-int)
2101 - "iops_max": total I/O operations max (json-int)
2102 - "iops_rd_max": read I/O operations max (json-int)
2103 - "iops_wr_max": write I/O operations max (json-int)
2104 - "iops_size": I/O size when limiting by iops (json-int)
2105 - "detect_zeroes": detect and optimize zero writing (json-string)
2106 - Possible values: "off", "on", "unmap"
2107 - "image": the detail of the image, it is a json-object containing
2108 the following:
2109 - "filename": image file name (json-string)
2110 - "format": image format (json-string)
2111 - "virtual-size": image capacity in bytes (json-int)
2112 - "dirty-flag": true if image is not cleanly closed, not present
2113 means clean (json-bool, optional)
2114 - "actual-size": actual size on disk in bytes of the image, not
2115 present when image does not support thin
2116 provision (json-int, optional)
2117 - "cluster-size": size of a cluster in bytes, not present if image
2118 format does not support it (json-int, optional)
2119 - "encrypted": true if the image is encrypted, not present means
2120 false or the image format does not support
2121 encryption (json-bool, optional)
2122 - "backing_file": backing file name, not present means no backing
2123 file is used or the image format does not
2124 support backing file chain
2125 (json-string, optional)
2126 - "full-backing-filename": full path of the backing file, not
2127 present if it equals backing_file or no
2128 backing file is used
2129 (json-string, optional)
2130 - "backing-filename-format": the format of the backing file, not
2131 present means unknown or no backing
2132 file (json-string, optional)
2133 - "snapshots": the internal snapshot info, it is an optional list
2134 of json-object containing the following:
2135 - "id": unique snapshot id (json-string)
2136 - "name": snapshot name (json-string)
2137 - "vm-state-size": size of the VM state in bytes (json-int)
2138 - "date-sec": UTC date of the snapshot in seconds (json-int)
2139 - "date-nsec": fractional part in nanoseconds to be used with
2140 date-sec (json-int)
2141 - "vm-clock-sec": VM clock relative to boot in seconds
2142 (json-int)
2143 - "vm-clock-nsec": fractional part in nanoseconds to be used
2144 with vm-clock-sec (json-int)
2145 - "backing-image": the detail of the backing image, it is an
2146 optional json-object only present when a
2147 backing image present for this image
2149 - "io-status": I/O operation status, only present if the device supports it
2150 and the VM is configured to stop on errors. It's always reset
2151 to "ok" when the "cont" command is issued (json_string, optional)
2152 - Possible values: "ok", "failed", "nospace"
2154 Example:
2156 -> { "execute": "query-block" }
2157 <- {
2158 "return":[
2160 "io-status": "ok",
2161 "device":"ide0-hd0",
2162 "locked":false,
2163 "removable":false,
2164 "inserted":{
2165 "ro":false,
2166 "drv":"qcow2",
2167 "encrypted":false,
2168 "file":"disks/test.qcow2",
2169 "backing_file_depth":1,
2170 "bps":1000000,
2171 "bps_rd":0,
2172 "bps_wr":0,
2173 "iops":1000000,
2174 "iops_rd":0,
2175 "iops_wr":0,
2176 "bps_max": 8000000,
2177 "bps_rd_max": 0,
2178 "bps_wr_max": 0,
2179 "iops_max": 0,
2180 "iops_rd_max": 0,
2181 "iops_wr_max": 0,
2182 "iops_size": 0,
2183 "detect_zeroes": "on",
2184 "image":{
2185 "filename":"disks/test.qcow2",
2186 "format":"qcow2",
2187 "virtual-size":2048000,
2188 "backing_file":"base.qcow2",
2189 "full-backing-filename":"disks/base.qcow2",
2190 "backing-filename-format:"qcow2",
2191 "snapshots":[
2193 "id": "1",
2194 "name": "snapshot1",
2195 "vm-state-size": 0,
2196 "date-sec": 10000200,
2197 "date-nsec": 12,
2198 "vm-clock-sec": 206,
2199 "vm-clock-nsec": 30
2202 "backing-image":{
2203 "filename":"disks/base.qcow2",
2204 "format":"qcow2",
2205 "virtual-size":2048000
2209 "type":"unknown"
2212 "io-status": "ok",
2213 "device":"ide1-cd0",
2214 "locked":false,
2215 "removable":true,
2216 "type":"unknown"
2219 "device":"floppy0",
2220 "locked":false,
2221 "removable":true,
2222 "type":"unknown"
2225 "device":"sd0",
2226 "locked":false,
2227 "removable":true,
2228 "type":"unknown"
2233 EQMP
2236 .name = "query-block",
2237 .args_type = "",
2238 .mhandler.cmd_new = qmp_marshal_input_query_block,
2241 SQMP
2242 query-blockstats
2243 ----------------
2245 Show block device statistics.
2247 Each device statistic information is stored in a json-object and the returned
2248 value is a json-array of all devices.
2250 Each json-object contain the following:
2252 - "device": device name (json-string)
2253 - "stats": A json-object with the statistics information, it contains:
2254 - "rd_bytes": bytes read (json-int)
2255 - "wr_bytes": bytes written (json-int)
2256 - "rd_operations": read operations (json-int)
2257 - "wr_operations": write operations (json-int)
2258 - "flush_operations": cache flush operations (json-int)
2259 - "wr_total_time_ns": total time spend on writes in nano-seconds (json-int)
2260 - "rd_total_time_ns": total time spend on reads in nano-seconds (json-int)
2261 - "flush_total_time_ns": total time spend on cache flushes in nano-seconds (json-int)
2262 - "wr_highest_offset": Highest offset of a sector written since the
2263 BlockDriverState has been opened (json-int)
2264 - "parent": Contains recursively the statistics of the underlying
2265 protocol (e.g. the host file for a qcow2 image). If there is
2266 no underlying protocol, this field is omitted
2267 (json-object, optional)
2269 Example:
2271 -> { "execute": "query-blockstats" }
2272 <- {
2273 "return":[
2275 "device":"ide0-hd0",
2276 "parent":{
2277 "stats":{
2278 "wr_highest_offset":3686448128,
2279 "wr_bytes":9786368,
2280 "wr_operations":751,
2281 "rd_bytes":122567168,
2282 "rd_operations":36772
2283 "wr_total_times_ns":313253456
2284 "rd_total_times_ns":3465673657
2285 "flush_total_times_ns":49653
2286 "flush_operations":61,
2289 "stats":{
2290 "wr_highest_offset":2821110784,
2291 "wr_bytes":9786368,
2292 "wr_operations":692,
2293 "rd_bytes":122739200,
2294 "rd_operations":36604
2295 "flush_operations":51,
2296 "wr_total_times_ns":313253456
2297 "rd_total_times_ns":3465673657
2298 "flush_total_times_ns":49653
2302 "device":"ide1-cd0",
2303 "stats":{
2304 "wr_highest_offset":0,
2305 "wr_bytes":0,
2306 "wr_operations":0,
2307 "rd_bytes":0,
2308 "rd_operations":0
2309 "flush_operations":0,
2310 "wr_total_times_ns":0
2311 "rd_total_times_ns":0
2312 "flush_total_times_ns":0
2316 "device":"floppy0",
2317 "stats":{
2318 "wr_highest_offset":0,
2319 "wr_bytes":0,
2320 "wr_operations":0,
2321 "rd_bytes":0,
2322 "rd_operations":0
2323 "flush_operations":0,
2324 "wr_total_times_ns":0
2325 "rd_total_times_ns":0
2326 "flush_total_times_ns":0
2330 "device":"sd0",
2331 "stats":{
2332 "wr_highest_offset":0,
2333 "wr_bytes":0,
2334 "wr_operations":0,
2335 "rd_bytes":0,
2336 "rd_operations":0
2337 "flush_operations":0,
2338 "wr_total_times_ns":0
2339 "rd_total_times_ns":0
2340 "flush_total_times_ns":0
2346 EQMP
2349 .name = "query-blockstats",
2350 .args_type = "",
2351 .mhandler.cmd_new = qmp_marshal_input_query_blockstats,
2354 SQMP
2355 query-cpus
2356 ----------
2358 Show CPU information.
2360 Return a json-array. Each CPU is represented by a json-object, which contains:
2362 - "CPU": CPU index (json-int)
2363 - "current": true if this is the current CPU, false otherwise (json-bool)
2364 - "halted": true if the cpu is halted, false otherwise (json-bool)
2365 - Current program counter. The key's name depends on the architecture:
2366 "pc": i386/x86_64 (json-int)
2367 "nip": PPC (json-int)
2368 "pc" and "npc": sparc (json-int)
2369 "PC": mips (json-int)
2370 - "thread_id": ID of the underlying host thread (json-int)
2372 Example:
2374 -> { "execute": "query-cpus" }
2375 <- {
2376 "return":[
2378 "CPU":0,
2379 "current":true,
2380 "halted":false,
2381 "pc":3227107138
2382 "thread_id":3134
2385 "CPU":1,
2386 "current":false,
2387 "halted":true,
2388 "pc":7108165
2389 "thread_id":3135
2394 EQMP
2397 .name = "query-cpus",
2398 .args_type = "",
2399 .mhandler.cmd_new = qmp_marshal_input_query_cpus,
2402 SQMP
2403 query-iothreads
2404 ---------------
2406 Returns a list of information about each iothread.
2408 Note this list excludes the QEMU main loop thread, which is not declared
2409 using the -object iothread command-line option. It is always the main thread
2410 of the process.
2412 Return a json-array. Each iothread is represented by a json-object, which contains:
2414 - "id": name of iothread (json-str)
2415 - "thread-id": ID of the underlying host thread (json-int)
2417 Example:
2419 -> { "execute": "query-iothreads" }
2420 <- {
2421 "return":[
2423 "id":"iothread0",
2424 "thread-id":3134
2427 "id":"iothread1",
2428 "thread-id":3135
2433 EQMP
2436 .name = "query-iothreads",
2437 .args_type = "",
2438 .mhandler.cmd_new = qmp_marshal_input_query_iothreads,
2441 SQMP
2442 query-pci
2443 ---------
2445 PCI buses and devices information.
2447 The returned value is a json-array of all buses. Each bus is represented by
2448 a json-object, which has a key with a json-array of all PCI devices attached
2449 to it. Each device is represented by a json-object.
2451 The bus json-object contains the following:
2453 - "bus": bus number (json-int)
2454 - "devices": a json-array of json-objects, each json-object represents a
2455 PCI device
2457 The PCI device json-object contains the following:
2459 - "bus": identical to the parent's bus number (json-int)
2460 - "slot": slot number (json-int)
2461 - "function": function number (json-int)
2462 - "class_info": a json-object containing:
2463 - "desc": device class description (json-string, optional)
2464 - "class": device class number (json-int)
2465 - "id": a json-object containing:
2466 - "device": device ID (json-int)
2467 - "vendor": vendor ID (json-int)
2468 - "irq": device's IRQ if assigned (json-int, optional)
2469 - "qdev_id": qdev id string (json-string)
2470 - "pci_bridge": It's a json-object, only present if this device is a
2471 PCI bridge, contains:
2472 - "bus": bus number (json-int)
2473 - "secondary": secondary bus number (json-int)
2474 - "subordinate": subordinate bus number (json-int)
2475 - "io_range": I/O memory range information, a json-object with the
2476 following members:
2477 - "base": base address, in bytes (json-int)
2478 - "limit": limit address, in bytes (json-int)
2479 - "memory_range": memory range information, a json-object with the
2480 following members:
2481 - "base": base address, in bytes (json-int)
2482 - "limit": limit address, in bytes (json-int)
2483 - "prefetchable_range": Prefetchable memory range information, a
2484 json-object with the following members:
2485 - "base": base address, in bytes (json-int)
2486 - "limit": limit address, in bytes (json-int)
2487 - "devices": a json-array of PCI devices if there's any attached, each
2488 each element is represented by a json-object, which contains
2489 the same members of the 'PCI device json-object' described
2490 above (optional)
2491 - "regions": a json-array of json-objects, each json-object represents a
2492 memory region of this device
2494 The memory range json-object contains the following:
2496 - "base": base memory address (json-int)
2497 - "limit": limit value (json-int)
2499 The region json-object can be an I/O region or a memory region, an I/O region
2500 json-object contains the following:
2502 - "type": "io" (json-string, fixed)
2503 - "bar": BAR number (json-int)
2504 - "address": memory address (json-int)
2505 - "size": memory size (json-int)
2507 A memory region json-object contains the following:
2509 - "type": "memory" (json-string, fixed)
2510 - "bar": BAR number (json-int)
2511 - "address": memory address (json-int)
2512 - "size": memory size (json-int)
2513 - "mem_type_64": true or false (json-bool)
2514 - "prefetch": true or false (json-bool)
2516 Example:
2518 -> { "execute": "query-pci" }
2519 <- {
2520 "return":[
2522 "bus":0,
2523 "devices":[
2525 "bus":0,
2526 "qdev_id":"",
2527 "slot":0,
2528 "class_info":{
2529 "class":1536,
2530 "desc":"Host bridge"
2532 "id":{
2533 "device":32902,
2534 "vendor":4663
2536 "function":0,
2537 "regions":[
2542 "bus":0,
2543 "qdev_id":"",
2544 "slot":1,
2545 "class_info":{
2546 "class":1537,
2547 "desc":"ISA bridge"
2549 "id":{
2550 "device":32902,
2551 "vendor":28672
2553 "function":0,
2554 "regions":[
2559 "bus":0,
2560 "qdev_id":"",
2561 "slot":1,
2562 "class_info":{
2563 "class":257,
2564 "desc":"IDE controller"
2566 "id":{
2567 "device":32902,
2568 "vendor":28688
2570 "function":1,
2571 "regions":[
2573 "bar":4,
2574 "size":16,
2575 "address":49152,
2576 "type":"io"
2581 "bus":0,
2582 "qdev_id":"",
2583 "slot":2,
2584 "class_info":{
2585 "class":768,
2586 "desc":"VGA controller"
2588 "id":{
2589 "device":4115,
2590 "vendor":184
2592 "function":0,
2593 "regions":[
2595 "prefetch":true,
2596 "mem_type_64":false,
2597 "bar":0,
2598 "size":33554432,
2599 "address":4026531840,
2600 "type":"memory"
2603 "prefetch":false,
2604 "mem_type_64":false,
2605 "bar":1,
2606 "size":4096,
2607 "address":4060086272,
2608 "type":"memory"
2611 "prefetch":false,
2612 "mem_type_64":false,
2613 "bar":6,
2614 "size":65536,
2615 "address":-1,
2616 "type":"memory"
2621 "bus":0,
2622 "qdev_id":"",
2623 "irq":11,
2624 "slot":4,
2625 "class_info":{
2626 "class":1280,
2627 "desc":"RAM controller"
2629 "id":{
2630 "device":6900,
2631 "vendor":4098
2633 "function":0,
2634 "regions":[
2636 "bar":0,
2637 "size":32,
2638 "address":49280,
2639 "type":"io"
2648 Note: This example has been shortened as the real response is too long.
2650 EQMP
2653 .name = "query-pci",
2654 .args_type = "",
2655 .mhandler.cmd_new = qmp_marshal_input_query_pci,
2658 SQMP
2659 query-kvm
2660 ---------
2662 Show KVM information.
2664 Return a json-object with the following information:
2666 - "enabled": true if KVM support is enabled, false otherwise (json-bool)
2667 - "present": true if QEMU has KVM support, false otherwise (json-bool)
2669 Example:
2671 -> { "execute": "query-kvm" }
2672 <- { "return": { "enabled": true, "present": true } }
2674 EQMP
2677 .name = "query-kvm",
2678 .args_type = "",
2679 .mhandler.cmd_new = qmp_marshal_input_query_kvm,
2682 SQMP
2683 query-status
2684 ------------
2686 Return a json-object with the following information:
2688 - "running": true if the VM is running, or false if it is paused (json-bool)
2689 - "singlestep": true if the VM is in single step mode,
2690 false otherwise (json-bool)
2691 - "status": one of the following values (json-string)
2692 "debug" - QEMU is running on a debugger
2693 "inmigrate" - guest is paused waiting for an incoming migration
2694 "internal-error" - An internal error that prevents further guest
2695 execution has occurred
2696 "io-error" - the last IOP has failed and the device is configured
2697 to pause on I/O errors
2698 "paused" - guest has been paused via the 'stop' command
2699 "postmigrate" - guest is paused following a successful 'migrate'
2700 "prelaunch" - QEMU was started with -S and guest has not started
2701 "finish-migrate" - guest is paused to finish the migration process
2702 "restore-vm" - guest is paused to restore VM state
2703 "running" - guest is actively running
2704 "save-vm" - guest is paused to save the VM state
2705 "shutdown" - guest is shut down (and -no-shutdown is in use)
2706 "watchdog" - the watchdog action is configured to pause and
2707 has been triggered
2709 Example:
2711 -> { "execute": "query-status" }
2712 <- { "return": { "running": true, "singlestep": false, "status": "running" } }
2714 EQMP
2717 .name = "query-status",
2718 .args_type = "",
2719 .mhandler.cmd_new = qmp_marshal_input_query_status,
2722 SQMP
2723 query-mice
2724 ----------
2726 Show VM mice information.
2728 Each mouse is represented by a json-object, the returned value is a json-array
2729 of all mice.
2731 The mouse json-object contains the following:
2733 - "name": mouse's name (json-string)
2734 - "index": mouse's index (json-int)
2735 - "current": true if this mouse is receiving events, false otherwise (json-bool)
2736 - "absolute": true if the mouse generates absolute input events (json-bool)
2738 Example:
2740 -> { "execute": "query-mice" }
2741 <- {
2742 "return":[
2744 "name":"QEMU Microsoft Mouse",
2745 "index":0,
2746 "current":false,
2747 "absolute":false
2750 "name":"QEMU PS/2 Mouse",
2751 "index":1,
2752 "current":true,
2753 "absolute":true
2758 EQMP
2761 .name = "query-mice",
2762 .args_type = "",
2763 .mhandler.cmd_new = qmp_marshal_input_query_mice,
2766 SQMP
2767 query-vnc
2768 ---------
2770 Show VNC server information.
2772 Return a json-object with server information. Connected clients are returned
2773 as a json-array of json-objects.
2775 The main json-object contains the following:
2777 - "enabled": true or false (json-bool)
2778 - "host": server's IP address (json-string)
2779 - "family": address family (json-string)
2780 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2781 - "service": server's port number (json-string)
2782 - "auth": authentication method (json-string)
2783 - Possible values: "invalid", "none", "ra2", "ra2ne", "sasl", "tight",
2784 "tls", "ultra", "unknown", "vencrypt", "vencrypt",
2785 "vencrypt+plain", "vencrypt+tls+none",
2786 "vencrypt+tls+plain", "vencrypt+tls+sasl",
2787 "vencrypt+tls+vnc", "vencrypt+x509+none",
2788 "vencrypt+x509+plain", "vencrypt+x509+sasl",
2789 "vencrypt+x509+vnc", "vnc"
2790 - "clients": a json-array of all connected clients
2792 Clients are described by a json-object, each one contain the following:
2794 - "host": client's IP address (json-string)
2795 - "family": address family (json-string)
2796 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2797 - "service": client's port number (json-string)
2798 - "x509_dname": TLS dname (json-string, optional)
2799 - "sasl_username": SASL username (json-string, optional)
2801 Example:
2803 -> { "execute": "query-vnc" }
2804 <- {
2805 "return":{
2806 "enabled":true,
2807 "host":"0.0.0.0",
2808 "service":"50402",
2809 "auth":"vnc",
2810 "family":"ipv4",
2811 "clients":[
2813 "host":"127.0.0.1",
2814 "service":"50401",
2815 "family":"ipv4"
2821 EQMP
2824 .name = "query-vnc",
2825 .args_type = "",
2826 .mhandler.cmd_new = qmp_marshal_input_query_vnc,
2829 SQMP
2830 query-spice
2831 -----------
2833 Show SPICE server information.
2835 Return a json-object with server information. Connected clients are returned
2836 as a json-array of json-objects.
2838 The main json-object contains the following:
2840 - "enabled": true or false (json-bool)
2841 - "host": server's IP address (json-string)
2842 - "port": server's port number (json-int, optional)
2843 - "tls-port": server's port number (json-int, optional)
2844 - "auth": authentication method (json-string)
2845 - Possible values: "none", "spice"
2846 - "channels": a json-array of all active channels clients
2848 Channels are described by a json-object, each one contain the following:
2850 - "host": client's IP address (json-string)
2851 - "family": address family (json-string)
2852 - Possible values: "ipv4", "ipv6", "unix", "unknown"
2853 - "port": client's port number (json-string)
2854 - "connection-id": spice connection id. All channels with the same id
2855 belong to the same spice session (json-int)
2856 - "channel-type": channel type. "1" is the main control channel, filter for
2857 this one if you want track spice sessions only (json-int)
2858 - "channel-id": channel id. Usually "0", might be different needed when
2859 multiple channels of the same type exist, such as multiple
2860 display channels in a multihead setup (json-int)
2861 - "tls": whevener the channel is encrypted (json-bool)
2863 Example:
2865 -> { "execute": "query-spice" }
2866 <- {
2867 "return": {
2868 "enabled": true,
2869 "auth": "spice",
2870 "port": 5920,
2871 "tls-port": 5921,
2872 "host": "0.0.0.0",
2873 "channels": [
2875 "port": "54924",
2876 "family": "ipv4",
2877 "channel-type": 1,
2878 "connection-id": 1804289383,
2879 "host": "127.0.0.1",
2880 "channel-id": 0,
2881 "tls": true
2884 "port": "36710",
2885 "family": "ipv4",
2886 "channel-type": 4,
2887 "connection-id": 1804289383,
2888 "host": "127.0.0.1",
2889 "channel-id": 0,
2890 "tls": false
2892 [ ... more channels follow ... ]
2897 EQMP
2899 #if defined(CONFIG_SPICE)
2901 .name = "query-spice",
2902 .args_type = "",
2903 .mhandler.cmd_new = qmp_marshal_input_query_spice,
2905 #endif
2907 SQMP
2908 query-name
2909 ----------
2911 Show VM name.
2913 Return a json-object with the following information:
2915 - "name": VM's name (json-string, optional)
2917 Example:
2919 -> { "execute": "query-name" }
2920 <- { "return": { "name": "qemu-name" } }
2922 EQMP
2925 .name = "query-name",
2926 .args_type = "",
2927 .mhandler.cmd_new = qmp_marshal_input_query_name,
2930 SQMP
2931 query-uuid
2932 ----------
2934 Show VM UUID.
2936 Return a json-object with the following information:
2938 - "UUID": Universally Unique Identifier (json-string)
2940 Example:
2942 -> { "execute": "query-uuid" }
2943 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
2945 EQMP
2948 .name = "query-uuid",
2949 .args_type = "",
2950 .mhandler.cmd_new = qmp_marshal_input_query_uuid,
2953 SQMP
2954 query-command-line-options
2955 --------------------------
2957 Show command line option schema.
2959 Return a json-array of command line option schema for all options (or for
2960 the given option), returning an error if the given option doesn't exist.
2962 Each array entry contains the following:
2964 - "option": option name (json-string)
2965 - "parameters": a json-array describes all parameters of the option:
2966 - "name": parameter name (json-string)
2967 - "type": parameter type (one of 'string', 'boolean', 'number',
2968 or 'size')
2969 - "help": human readable description of the parameter
2970 (json-string, optional)
2971 - "default": default value string for the parameter
2972 (json-string, optional)
2974 Example:
2976 -> { "execute": "query-command-line-options", "arguments": { "option": "option-rom" } }
2977 <- { "return": [
2979 "parameters": [
2981 "name": "romfile",
2982 "type": "string"
2985 "name": "bootindex",
2986 "type": "number"
2989 "option": "option-rom"
2994 EQMP
2997 .name = "query-command-line-options",
2998 .args_type = "option:s?",
2999 .mhandler.cmd_new = qmp_marshal_input_query_command_line_options,
3002 SQMP
3003 query-migrate
3004 -------------
3006 Migration status.
3008 Return a json-object. If migration is active there will be another json-object
3009 with RAM migration status and if block migration is active another one with
3010 block migration status.
3012 The main json-object contains the following:
3014 - "status": migration status (json-string)
3015 - Possible values: "setup", "active", "completed", "failed", "cancelled"
3016 - "total-time": total amount of ms since migration started. If
3017 migration has ended, it returns the total migration
3018 time (json-int)
3019 - "setup-time" amount of setup time in milliseconds _before_ the
3020 iterations begin but _after_ the QMP command is issued.
3021 This is designed to provide an accounting of any activities
3022 (such as RDMA pinning) which may be expensive, but do not
3023 actually occur during the iterative migration rounds
3024 themselves. (json-int)
3025 - "downtime": only present when migration has finished correctly
3026 total amount in ms for downtime that happened (json-int)
3027 - "expected-downtime": only present while migration is active
3028 total amount in ms for downtime that was calculated on
3029 the last bitmap round (json-int)
3030 - "ram": only present if "status" is "active", it is a json-object with the
3031 following RAM information:
3032 - "transferred": amount transferred in bytes (json-int)
3033 - "remaining": amount remaining to transfer in bytes (json-int)
3034 - "total": total amount of memory in bytes (json-int)
3035 - "duplicate": number of pages filled entirely with the same
3036 byte (json-int)
3037 These are sent over the wire much more efficiently.
3038 - "skipped": number of skipped zero pages (json-int)
3039 - "normal" : number of whole pages transferred. I.e. they
3040 were not sent as duplicate or xbzrle pages (json-int)
3041 - "normal-bytes" : number of bytes transferred in whole
3042 pages. This is just normal pages times size of one page,
3043 but this way upper levels don't need to care about page
3044 size (json-int)
3045 - "dirty-sync-count": times that dirty ram was synchronized (json-int)
3046 - "disk": only present if "status" is "active" and it is a block migration,
3047 it is a json-object with the following disk information:
3048 - "transferred": amount transferred in bytes (json-int)
3049 - "remaining": amount remaining to transfer in bytes json-int)
3050 - "total": total disk size in bytes (json-int)
3051 - "xbzrle-cache": only present if XBZRLE is active.
3052 It is a json-object with the following XBZRLE information:
3053 - "cache-size": XBZRLE cache size in bytes
3054 - "bytes": number of bytes transferred for XBZRLE compressed pages
3055 - "pages": number of XBZRLE compressed pages
3056 - "cache-miss": number of XBRZRLE page cache misses
3057 - "cache-miss-rate": rate of XBRZRLE page cache misses
3058 - "overflow": number of times XBZRLE overflows. This means
3059 that the XBZRLE encoding was bigger than just sent the
3060 whole page, and then we sent the whole page instead (as as
3061 normal page).
3063 Examples:
3065 1. Before the first migration
3067 -> { "execute": "query-migrate" }
3068 <- { "return": {} }
3070 2. Migration is done and has succeeded
3072 -> { "execute": "query-migrate" }
3073 <- { "return": {
3074 "status": "completed",
3075 "ram":{
3076 "transferred":123,
3077 "remaining":123,
3078 "total":246,
3079 "total-time":12345,
3080 "setup-time":12345,
3081 "downtime":12345,
3082 "duplicate":123,
3083 "normal":123,
3084 "normal-bytes":123456,
3085 "dirty-sync-count":15
3090 3. Migration is done and has failed
3092 -> { "execute": "query-migrate" }
3093 <- { "return": { "status": "failed" } }
3095 4. Migration is being performed and is not a block migration:
3097 -> { "execute": "query-migrate" }
3098 <- {
3099 "return":{
3100 "status":"active",
3101 "ram":{
3102 "transferred":123,
3103 "remaining":123,
3104 "total":246,
3105 "total-time":12345,
3106 "setup-time":12345,
3107 "expected-downtime":12345,
3108 "duplicate":123,
3109 "normal":123,
3110 "normal-bytes":123456,
3111 "dirty-sync-count":15
3116 5. Migration is being performed and is a block migration:
3118 -> { "execute": "query-migrate" }
3119 <- {
3120 "return":{
3121 "status":"active",
3122 "ram":{
3123 "total":1057024,
3124 "remaining":1053304,
3125 "transferred":3720,
3126 "total-time":12345,
3127 "setup-time":12345,
3128 "expected-downtime":12345,
3129 "duplicate":123,
3130 "normal":123,
3131 "normal-bytes":123456,
3132 "dirty-sync-count":15
3134 "disk":{
3135 "total":20971520,
3136 "remaining":20880384,
3137 "transferred":91136
3142 6. Migration is being performed and XBZRLE is active:
3144 -> { "execute": "query-migrate" }
3145 <- {
3146 "return":{
3147 "status":"active",
3148 "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
3149 "ram":{
3150 "total":1057024,
3151 "remaining":1053304,
3152 "transferred":3720,
3153 "total-time":12345,
3154 "setup-time":12345,
3155 "expected-downtime":12345,
3156 "duplicate":10,
3157 "normal":3333,
3158 "normal-bytes":3412992,
3159 "dirty-sync-count":15
3161 "xbzrle-cache":{
3162 "cache-size":67108864,
3163 "bytes":20971520,
3164 "pages":2444343,
3165 "cache-miss":2244,
3166 "cache-miss-rate":0.123,
3167 "overflow":34434
3172 EQMP
3175 .name = "query-migrate",
3176 .args_type = "",
3177 .mhandler.cmd_new = qmp_marshal_input_query_migrate,
3180 SQMP
3181 migrate-set-capabilities
3182 ------------------------
3184 Enable/Disable migration capabilities
3186 - "xbzrle": XBZRLE support
3188 Arguments:
3190 Example:
3192 -> { "execute": "migrate-set-capabilities" , "arguments":
3193 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
3195 EQMP
3198 .name = "migrate-set-capabilities",
3199 .args_type = "capabilities:O",
3200 .params = "capability:s,state:b",
3201 .mhandler.cmd_new = qmp_marshal_input_migrate_set_capabilities,
3203 SQMP
3204 query-migrate-capabilities
3205 --------------------------
3207 Query current migration capabilities
3209 - "capabilities": migration capabilities state
3210 - "xbzrle" : XBZRLE state (json-bool)
3212 Arguments:
3214 Example:
3216 -> { "execute": "query-migrate-capabilities" }
3217 <- { "return": [ { "state": false, "capability": "xbzrle" } ] }
3219 EQMP
3222 .name = "query-migrate-capabilities",
3223 .args_type = "",
3224 .mhandler.cmd_new = qmp_marshal_input_query_migrate_capabilities,
3227 SQMP
3228 query-balloon
3229 -------------
3231 Show balloon information.
3233 Make an asynchronous request for balloon info. When the request completes a
3234 json-object will be returned containing the following data:
3236 - "actual": current balloon value in bytes (json-int)
3238 Example:
3240 -> { "execute": "query-balloon" }
3241 <- {
3242 "return":{
3243 "actual":1073741824,
3247 EQMP
3250 .name = "query-balloon",
3251 .args_type = "",
3252 .mhandler.cmd_new = qmp_marshal_input_query_balloon,
3256 .name = "query-block-jobs",
3257 .args_type = "",
3258 .mhandler.cmd_new = qmp_marshal_input_query_block_jobs,
3262 .name = "qom-list",
3263 .args_type = "path:s",
3264 .mhandler.cmd_new = qmp_marshal_input_qom_list,
3268 .name = "qom-set",
3269 .args_type = "path:s,property:s,value:q",
3270 .mhandler.cmd_new = qmp_qom_set,
3274 .name = "qom-get",
3275 .args_type = "path:s,property:s",
3276 .mhandler.cmd_new = qmp_qom_get,
3280 .name = "nbd-server-start",
3281 .args_type = "addr:q",
3282 .mhandler.cmd_new = qmp_marshal_input_nbd_server_start,
3285 .name = "nbd-server-add",
3286 .args_type = "device:B,writable:b?",
3287 .mhandler.cmd_new = qmp_marshal_input_nbd_server_add,
3290 .name = "nbd-server-stop",
3291 .args_type = "",
3292 .mhandler.cmd_new = qmp_marshal_input_nbd_server_stop,
3296 .name = "change-vnc-password",
3297 .args_type = "password:s",
3298 .mhandler.cmd_new = qmp_marshal_input_change_vnc_password,
3301 .name = "qom-list-types",
3302 .args_type = "implements:s?,abstract:b?",
3303 .mhandler.cmd_new = qmp_marshal_input_qom_list_types,
3307 .name = "device-list-properties",
3308 .args_type = "typename:s",
3309 .mhandler.cmd_new = qmp_marshal_input_device_list_properties,
3313 .name = "query-machines",
3314 .args_type = "",
3315 .mhandler.cmd_new = qmp_marshal_input_query_machines,
3319 .name = "query-cpu-definitions",
3320 .args_type = "",
3321 .mhandler.cmd_new = qmp_marshal_input_query_cpu_definitions,
3325 .name = "query-target",
3326 .args_type = "",
3327 .mhandler.cmd_new = qmp_marshal_input_query_target,
3331 .name = "query-tpm",
3332 .args_type = "",
3333 .mhandler.cmd_new = qmp_marshal_input_query_tpm,
3336 SQMP
3337 query-tpm
3338 ---------
3340 Return information about the TPM device.
3342 Arguments: None
3344 Example:
3346 -> { "execute": "query-tpm" }
3347 <- { "return":
3349 { "model": "tpm-tis",
3350 "options":
3351 { "type": "passthrough",
3352 "data":
3353 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
3354 "path": "/dev/tpm0"
3357 "id": "tpm0"
3362 EQMP
3365 .name = "query-tpm-models",
3366 .args_type = "",
3367 .mhandler.cmd_new = qmp_marshal_input_query_tpm_models,
3370 SQMP
3371 query-tpm-models
3372 ----------------
3374 Return a list of supported TPM models.
3376 Arguments: None
3378 Example:
3380 -> { "execute": "query-tpm-models" }
3381 <- { "return": [ "tpm-tis" ] }
3383 EQMP
3386 .name = "query-tpm-types",
3387 .args_type = "",
3388 .mhandler.cmd_new = qmp_marshal_input_query_tpm_types,
3391 SQMP
3392 query-tpm-types
3393 ---------------
3395 Return a list of supported TPM types.
3397 Arguments: None
3399 Example:
3401 -> { "execute": "query-tpm-types" }
3402 <- { "return": [ "passthrough" ] }
3404 EQMP
3407 .name = "chardev-add",
3408 .args_type = "id:s,backend:q",
3409 .mhandler.cmd_new = qmp_marshal_input_chardev_add,
3412 SQMP
3413 chardev-add
3414 ----------------
3416 Add a chardev.
3418 Arguments:
3420 - "id": the chardev's ID, must be unique (json-string)
3421 - "backend": chardev backend type + parameters
3423 Examples:
3425 -> { "execute" : "chardev-add",
3426 "arguments" : { "id" : "foo",
3427 "backend" : { "type" : "null", "data" : {} } } }
3428 <- { "return": {} }
3430 -> { "execute" : "chardev-add",
3431 "arguments" : { "id" : "bar",
3432 "backend" : { "type" : "file",
3433 "data" : { "out" : "/tmp/bar.log" } } } }
3434 <- { "return": {} }
3436 -> { "execute" : "chardev-add",
3437 "arguments" : { "id" : "baz",
3438 "backend" : { "type" : "pty", "data" : {} } } }
3439 <- { "return": { "pty" : "/dev/pty/42" } }
3441 EQMP
3444 .name = "chardev-remove",
3445 .args_type = "id:s",
3446 .mhandler.cmd_new = qmp_marshal_input_chardev_remove,
3450 SQMP
3451 chardev-remove
3452 --------------
3454 Remove a chardev.
3456 Arguments:
3458 - "id": the chardev's ID, must exist and not be in use (json-string)
3460 Example:
3462 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
3463 <- { "return": {} }
3465 EQMP
3467 .name = "query-rx-filter",
3468 .args_type = "name:s?",
3469 .mhandler.cmd_new = qmp_marshal_input_query_rx_filter,
3472 SQMP
3473 query-rx-filter
3474 ---------------
3476 Show rx-filter information.
3478 Returns a json-array of rx-filter information for all NICs (or for the
3479 given NIC), returning an error if the given NIC doesn't exist, or
3480 given NIC doesn't support rx-filter querying, or given net client
3481 isn't a NIC.
3483 The query will clear the event notification flag of each NIC, then qemu
3484 will start to emit event to QMP monitor.
3486 Each array entry contains the following:
3488 - "name": net client name (json-string)
3489 - "promiscuous": promiscuous mode is enabled (json-bool)
3490 - "multicast": multicast receive state (one of 'normal', 'none', 'all')
3491 - "unicast": unicast receive state (one of 'normal', 'none', 'all')
3492 - "vlan": vlan receive state (one of 'normal', 'none', 'all') (Since 2.0)
3493 - "broadcast-allowed": allow to receive broadcast (json-bool)
3494 - "multicast-overflow": multicast table is overflowed (json-bool)
3495 - "unicast-overflow": unicast table is overflowed (json-bool)
3496 - "main-mac": main macaddr string (json-string)
3497 - "vlan-table": a json-array of active vlan id
3498 - "unicast-table": a json-array of unicast macaddr string
3499 - "multicast-table": a json-array of multicast macaddr string
3501 Example:
3503 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
3504 <- { "return": [
3506 "promiscuous": true,
3507 "name": "vnet0",
3508 "main-mac": "52:54:00:12:34:56",
3509 "unicast": "normal",
3510 "vlan": "normal",
3511 "vlan-table": [
3515 "unicast-table": [
3517 "multicast": "normal",
3518 "multicast-overflow": false,
3519 "unicast-overflow": false,
3520 "multicast-table": [
3521 "01:00:5e:00:00:01",
3522 "33:33:00:00:00:01",
3523 "33:33:ff:12:34:56"
3525 "broadcast-allowed": false
3530 EQMP
3533 .name = "blockdev-add",
3534 .args_type = "options:q",
3535 .mhandler.cmd_new = qmp_marshal_input_blockdev_add,
3538 SQMP
3539 blockdev-add
3540 ------------
3542 Add a block device.
3544 Arguments:
3546 - "options": block driver options
3548 Example (1):
3550 -> { "execute": "blockdev-add",
3551 "arguments": { "options" : { "driver": "qcow2",
3552 "file": { "driver": "file",
3553 "filename": "test.qcow2" } } } }
3554 <- { "return": {} }
3556 Example (2):
3558 -> { "execute": "blockdev-add",
3559 "arguments": {
3560 "options": {
3561 "driver": "qcow2",
3562 "id": "my_disk",
3563 "discard": "unmap",
3564 "cache": {
3565 "direct": true,
3566 "writeback": true
3568 "file": {
3569 "driver": "file",
3570 "filename": "/tmp/test.qcow2"
3572 "backing": {
3573 "driver": "raw",
3574 "file": {
3575 "driver": "file",
3576 "filename": "/dev/fdset/4"
3583 <- { "return": {} }
3585 EQMP
3588 .name = "query-named-block-nodes",
3589 .args_type = "",
3590 .mhandler.cmd_new = qmp_marshal_input_query_named_block_nodes,
3593 SQMP
3594 @query-named-block-nodes
3595 ------------------------
3597 Return a list of BlockDeviceInfo for all the named block driver nodes
3599 Example:
3601 -> { "execute": "query-named-block-nodes" }
3602 <- { "return": [ { "ro":false,
3603 "drv":"qcow2",
3604 "encrypted":false,
3605 "file":"disks/test.qcow2",
3606 "node-name": "my-node",
3607 "backing_file_depth":1,
3608 "bps":1000000,
3609 "bps_rd":0,
3610 "bps_wr":0,
3611 "iops":1000000,
3612 "iops_rd":0,
3613 "iops_wr":0,
3614 "bps_max": 8000000,
3615 "bps_rd_max": 0,
3616 "bps_wr_max": 0,
3617 "iops_max": 0,
3618 "iops_rd_max": 0,
3619 "iops_wr_max": 0,
3620 "iops_size": 0,
3621 "image":{
3622 "filename":"disks/test.qcow2",
3623 "format":"qcow2",
3624 "virtual-size":2048000,
3625 "backing_file":"base.qcow2",
3626 "full-backing-filename":"disks/base.qcow2",
3627 "backing-filename-format:"qcow2",
3628 "snapshots":[
3630 "id": "1",
3631 "name": "snapshot1",
3632 "vm-state-size": 0,
3633 "date-sec": 10000200,
3634 "date-nsec": 12,
3635 "vm-clock-sec": 206,
3636 "vm-clock-nsec": 30
3639 "backing-image":{
3640 "filename":"disks/base.qcow2",
3641 "format":"qcow2",
3642 "virtual-size":2048000
3644 } } ] }
3646 EQMP
3649 .name = "query-memdev",
3650 .args_type = "",
3651 .mhandler.cmd_new = qmp_marshal_input_query_memdev,
3654 SQMP
3655 query-memdev
3656 ------------
3658 Show memory devices information.
3661 Example (1):
3663 -> { "execute": "query-memdev" }
3664 <- { "return": [
3666 "size": 536870912,
3667 "merge": false,
3668 "dump": true,
3669 "prealloc": false,
3670 "host-nodes": [0, 1],
3671 "policy": "bind"
3674 "size": 536870912,
3675 "merge": false,
3676 "dump": true,
3677 "prealloc": true,
3678 "host-nodes": [2, 3],
3679 "policy": "preferred"
3684 EQMP
3687 .name = "query-memory-devices",
3688 .args_type = "",
3689 .mhandler.cmd_new = qmp_marshal_input_query_memory_devices,
3692 SQMP
3693 @query-memory-devices
3694 --------------------
3696 Return a list of memory devices.
3698 Example:
3699 -> { "execute": "query-memory-devices" }
3700 <- { "return": [ { "data":
3701 { "addr": 5368709120,
3702 "hotpluggable": true,
3703 "hotplugged": true,
3704 "id": "d1",
3705 "memdev": "/objects/memX",
3706 "node": 0,
3707 "size": 1073741824,
3708 "slot": 0},
3709 "type": "dimm"
3710 } ] }
3711 EQMP
3714 .name = "query-acpi-ospm-status",
3715 .args_type = "",
3716 .mhandler.cmd_new = qmp_marshal_input_query_acpi_ospm_status,
3719 SQMP
3720 @query-acpi-ospm-status
3721 --------------------
3723 Return list of ACPIOSTInfo for devices that support status reporting
3724 via ACPI _OST method.
3726 Example:
3727 -> { "execute": "query-acpi-ospm-status" }
3728 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
3729 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
3730 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
3731 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
3733 EQMP
3735 #if defined TARGET_I386
3737 .name = "rtc-reset-reinjection",
3738 .args_type = "",
3739 .mhandler.cmd_new = qmp_marshal_input_rtc_reset_reinjection,
3741 #endif
3743 SQMP
3744 rtc-reset-reinjection
3745 ---------------------
3747 Reset the RTC interrupt reinjection backlog.
3749 Arguments: None.
3751 Example:
3753 -> { "execute": "rtc-reset-reinjection" }
3754 <- { "return": {} }
3756 EQMP