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