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