1QEMU-QMP-REF.7(7) QEMU-QMP-REF.7(7)
2
6 qemu-qmp-ref - QEMU QMP Reference Manual
7
9 Introduction
10 This document describes all commands currently supported by QMP.
11 Most of the time their usage is exactly the same as in the user
13 Monitor, this means that any other document which also describe
14 commands (the manpage, QEMU's manual, etc) can and should be consulted.
15 QMP has two types of commands: regular and query commands. Regular
17 commands usually change the Virtual Machine's state someway, while
18 query commands just return information. The sections below are divided
19 accordingly.
20 It's important to observe that all communication examples are formatted
22 in a reader-friendly way, so that they're easier to understand.
23 However, in real protocol usage, they're emitted as a single line.
24 Also, the following notation is used to denote data flow:
26 Example:
28 -> data issued by the Client
30 <- Server data response
34 Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
36 detailed information on the Server command and response formats.
37 Stability Considerations
39 The current QMP command set (described in this file) may be useful for
40 a number of use cases, however it's limited and several commands have
41 bad defined semantics, specially with regard to command completion.
42 These problems are going to be solved incrementally in the next QEMU
44 releases and we're going to establish a deprecation policy for badly
45 defined commands.
46 If you're planning to adopt QMP, please observe the following:
48 1. The deprecation policy will take effect and be documented soon,
50 please check the documentation of each used command as soon as a
51 new release of QEMU is available
52 2. DO NOT rely on anything which is not explicit documented
54 3. Errors, in special, are not documented. Applications should NOT
56 check for specific errors classes or data (it's strongly
57 recommended to only check for the "error" key)
58 Common data types
60 QapiErrorClass (Enum)
61 QEMU error classes
63 Values:
65 "GenericError"
67 this is used for errors that don't require a specific error class.
68 This should be the default case for most errors
69 "CommandNotFound"
71 the requested command has not been found
72 "DeviceNotActive"
74 a device has failed to be become active
75 "DeviceNotFound"
77 the requested device has not been found
78 "KVMMissingCap"
80 the requested operation can't be fulfilled because a required KVM
81 capability is missing
82 Since: 1.2
84 IoOperationType (Enum)
86 An enumeration of the I/O operation types
88 Values:
90 "read"
92 read operation
93 "write"
95 write operation
96 Since: 2.1
98 OnOffAuto (Enum)
100 An enumeration of three options: on, off, and auto
102 Values:
104 "auto"
106 QEMU selects the value between on and off
107 "on"
109 Enabled
110 "off"
112 Disabled
113 Since: 2.2
115 OnOffSplit (Enum)
117 An enumeration of three values: on, off, and split
119 Values:
121 "on"
123 Enabled
124 "off"
126 Disabled
127 "split"
129 Mixed
130 Since: 2.6
132 String (Object)
134 A fat type wrapping 'str', to be embedded in lists.
136 Members:
138 "str: string"
140 Not documented
141 Since: 1.2
143 StrOrNull (Alternate)
145 This is a string value or the explicit lack of a string (null pointer
147 in C). Intended for cases when 'optional absent' already has a
148 different meaning.
149 Members:
151 "s: string"
153 the string value
154 "n: null"
156 no string value
157 Since: 2.10
159 OffAutoPCIBAR (Enum)
161 An enumeration of options for specifying a PCI BAR
163 Values:
165 "off"
167 The specified feature is disabled
168 "auto"
170 The PCI BAR for the feature is automatically selected
171 "bar0"
173 PCI BAR0 is used for the feature
174 "bar1"
176 PCI BAR1 is used for the feature
177 "bar2"
179 PCI BAR2 is used for the feature
180 "bar3"
182 PCI BAR3 is used for the feature
183 "bar4"
185 PCI BAR4 is used for the feature
186 "bar5"
188 PCI BAR5 is used for the feature
189 Since: 2.12
191 SysEmuTarget (Enum)
193 The comprehensive enumeration of QEMU system emulation ("softmmu")
195 targets. Run "./configure --help" in the project root directory, and
196 look for the *-softmmu targets near the "--target-list" option. The
197 individual target constants are not documented here, for the time
198 being.
199 Values:
201 "aarch64"
203 Not documented
204 "alpha"
206 Not documented
207 "arm"
209 Not documented
210 "cris"
212 Not documented
213 "hppa"
215 Not documented
216 "i386"
218 Not documented
219 "lm32"
221 Not documented
222 "m68k"
224 Not documented
225 "microblaze"
227 Not documented
228 "microblazeel"
230 Not documented
231 "mips"
233 Not documented
234 "mips64"
236 Not documented
237 "mips64el"
239 Not documented
240 "mipsel"
242 Not documented
243 "moxie"
245 Not documented
246 "nios2"
248 Not documented
249 "or1k"
251 Not documented
252 "ppc"
254 Not documented
255 "ppc64"
257 Not documented
258 "riscv32"
260 Not documented
261 "riscv64"
263 Not documented
264 "s390x"
266 Not documented
267 "sh4"
269 Not documented
270 "sh4eb"
272 Not documented
273 "sparc"
275 Not documented
276 "sparc64"
278 Not documented
279 "tricore"
281 Not documented
282 "unicore32"
284 Not documented
285 "x86_64"
287 Not documented
288 "xtensa"
290 Not documented
291 "xtensaeb"
293 Not documented
294 Notes: The resulting QMP strings can be appended to the "qemu-system-"
296 prefix to produce the corresponding QEMU executable name. This is true
297 even for "qemu-system-x86_64".
298 ppcemb: dropped in 3.1
300 Since: 3.0
302 Socket data types
304 NetworkAddressFamily (Enum)
305 The network address family
307 Values:
309 "ipv4"
311 IPV4 family
312 "ipv6"
314 IPV6 family
315 "unix"
317 unix socket
318 "vsock"
320 vsock family (since 2.8)
321 "unknown"
323 otherwise
324 Since: 2.1
326 InetSocketAddressBase (Object)
328 Members:
330 "host: string"
332 host part of the address
333 "port: string"
335 port part of the address
336 InetSocketAddress (Object)
338 Captures a socket address or address range in the Internet namespace.
340 Members:
342 "numeric: boolean" (optional)
344 true if the host/port are guaranteed to be numeric, false if name
345 resolution should be attempted. Defaults to false. (Since 2.9)
346 "to: int" (optional)
348 If present, this is range of possible addresses, with port between
349 "port" and "to".
350 "ipv4: boolean" (optional)
352 whether to accept IPv4 addresses, default try both IPv4 and IPv6
353 "ipv6: boolean" (optional)
355 whether to accept IPv6 addresses, default try both IPv4 and IPv6
356 The members of "InetSocketAddressBase"
358 Since: 1.3
360 UnixSocketAddress (Object)
362 Captures a socket address in the local ("Unix socket") namespace.
364 Members:
366 "path: string"
368 filesystem path to use
369 Since: 1.3
371 VsockSocketAddress (Object)
373 Captures a socket address in the vsock namespace.
375 Members:
377 "cid: string"
379 unique host identifier
380 "port: string"
382 port
383 Note: string types are used to allow for possible future hostname or
385 service resolution support.
386 Since: 2.8
388 SocketAddressLegacy (Object)
390 Captures the address of a socket, which could also be a named file
392 descriptor
393 Members:
395 "type"
397 One of "inet", "unix", "vsock", "fd"
398 "data: InetSocketAddress" when "type" is "inet"
400 "data: UnixSocketAddress" when "type" is "unix"
401 "data: VsockSocketAddress" when "type" is "vsock"
402 "data: String" when "type" is "fd"
403 Note: This type is deprecated in favor of SocketAddress. The
405 difference between SocketAddressLegacy and SocketAddress is that the
406 latter is a flat union rather than a simple union. Flat is nicer
407 because it avoids nesting on the wire, i.e. that form has fewer {}.
408 Since: 1.3
410 SocketAddressType (Enum)
412 Available SocketAddress types
414 Values:
416 "inet"
418 Internet address
419 "unix"
421 Unix domain socket
422 "vsock"
424 VMCI address
425 "fd"
427 decimal is for file descriptor number, otherwise a file descriptor
428 name. Named file descriptors are permitted in monitor commands, in
429 combination with the 'getfd' command. Decimal file descriptors are
430 permitted at startup or other contexts where no monitor context is
431 active.
432 Since: 2.9
434 SocketAddress (Object)
436 Captures the address of a socket, which could also be a named file
438 descriptor
439 Members:
441 "type: SocketAddressType"
443 Transport type
444 The members of "InetSocketAddress" when "type" is "inet"
446 The members of "UnixSocketAddress" when "type" is "unix"
447 The members of "VsockSocketAddress" when "type" is "vsock"
448 The members of "String" when "type" is "fd"
449 Since: 2.9
451 VM run state
453 RunState (Enum)
454 An enumeration of VM run states.
456 Values:
458 "debug"
460 QEMU is running on a debugger
461 "finish-migrate"
463 guest is paused to finish the migration process
464 "inmigrate"
466 guest is paused waiting for an incoming migration. Note that this
467 state does not tell whether the machine will start at the end of
468 the migration. This depends on the command-line -S option and any
469 invocation of 'stop' or 'cont' that has happened since QEMU was
470 started.
471 "internal-error"
473 An internal error that prevents further guest execution has
474 occurred
475 "io-error"
477 the last IOP has failed and the device is configured to pause on
478 I/O errors
479 "paused"
481 guest has been paused via the 'stop' command
482 "postmigrate"
484 guest is paused following a successful 'migrate'
485 "prelaunch"
487 QEMU was started with -S and guest has not started
488 "restore-vm"
490 guest is paused to restore VM state
491 "running"
493 guest is actively running
494 "save-vm"
496 guest is paused to save the VM state
497 "shutdown"
499 guest is shut down (and -no-shutdown is in use)
500 "suspended"
502 guest is suspended (ACPI S3)
503 "watchdog"
505 the watchdog action is configured to pause and has been triggered
506 "guest-panicked"
508 guest has been panicked as a result of guest OS panic
509 "colo"
511 guest is paused to save/restore VM state under colo checkpoint, VM
512 can not get into this state unless colo capability is enabled for
513 migration. (since 2.8)
514 "preconfig"
516 QEMU is paused before board specific init callback is executed.
517 The state is reachable only if the --preconfig CLI option is used.
518 (Since 3.0)
519 StatusInfo (Object)
521 Information about VCPU run state
523 Members:
525 "running: boolean"
527 true if all VCPUs are runnable, false if not runnable
528 "singlestep: boolean"
530 true if VCPUs are in single-step mode
531 "status: RunState"
533 the virtual machine "RunState"
534 Since: 0.14.0
536 Notes: "singlestep" is enabled through the GDB stub
538 query-status (Command) Query the run status of all VCPUs
540 Returns: "StatusInfo" reflecting all VCPUs
542 Since: 0.14.0
544 Example:
546 -> { "execute": "query-status" }
548 <- { "return": { "running": true,
549 "singlestep": false,
550 "status": "running" } }
551 SHUTDOWN (Event) Emitted when the virtual machine has shut down,
553 indicating that qemu is about to exit.
554 Arguments:
556 "guest: boolean"
558 If true, the shutdown was triggered by a guest request (such as a
559 guest-initiated ACPI shutdown request or other hardware-specific
560 action) rather than a host request (such as sending qemu a SIGINT).
561 (since 2.10)
562 Note: If the command-line option "-no-shutdown" has been specified,
564 qemu will not exit, and a STOP event will eventually follow the
565 SHUTDOWN event
566 Since: 0.12.0
568 Example:
570 <- { "event": "SHUTDOWN", "data": { "guest": true },
572 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
573 POWERDOWN (Event) Emitted when the virtual machine is powered down
575 through the power control system, such as via ACPI.
576 Since: 0.12.0
578 Example:
580 <- { "event": "POWERDOWN",
582 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
583 RESET (Event) Emitted when the virtual machine is reset
585 Arguments:
587 "guest: boolean"
589 If true, the reset was triggered by a guest request (such as a
590 guest-initiated ACPI reboot request or other hardware-specific
591 action) rather than a host request (such as the QMP command
592 system_reset). (since 2.10)
593 Since: 0.12.0
595 Example:
597 <- { "event": "RESET", "data": { "guest": false },
599 "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
600 STOP (Event) Emitted when the virtual machine is stopped
602 Since: 0.12.0
604 Example:
606 <- { "event": "STOP",
608 "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
609 RESUME (Event) Emitted when the virtual machine resumes execution
611 Since: 0.12.0
613 Example:
615 <- { "event": "RESUME",
617 "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
618 SUSPEND (Event) Emitted when guest enters a hardware suspension state,
620 for example, S3 state, which is sometimes called standby state
621 Since: 1.1
623 Example:
625 <- { "event": "SUSPEND",
627 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
628 SUSPEND_DISK (Event) Emitted when guest enters a hardware suspension
630 state with data saved on disk, for example, S4 state, which is
631 sometimes called hibernate state
632 Note: QEMU shuts down (similar to event "SHUTDOWN") when entering this
634 state
635 Since: 1.2
637 Example:
639 <- { "event": "SUSPEND_DISK",
641 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
642 WAKEUP (Event) Emitted when the guest has woken up from suspend state
644 and is running
645 Since: 1.1
647 Example:
649 <- { "event": "WAKEUP",
651 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
652 WATCHDOG (Event) Emitted when the watchdog device's timer is expired
654 Arguments:
656 "action: WatchdogAction"
658 action that has been taken
659 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event
661 is followed respectively by the RESET, SHUTDOWN, or STOP events
662 Note: This event is rate-limited.
664 Since: 0.13.0
666 Example:
668 <- { "event": "WATCHDOG",
670 "data": { "action": "reset" },
671 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
672 WatchdogAction (Enum)
674 An enumeration of the actions taken when the watchdog device's timer is
676 expired
677 Values:
679 "reset"
681 system resets
682 "shutdown"
684 system shutdown, note that it is similar to "powerdown", which
685 tries to set to system status and notify guest
686 "poweroff"
688 system poweroff, the emulator program exits
689 "pause"
691 system pauses, similar to "stop"
692 "debug"
694 system enters debug state
695 "none"
697 nothing is done
698 "inject-nmi"
700 a non-maskable interrupt is injected into the first VCPU (all VCPUS
701 on x86) (since 2.4)
702 Since: 2.1
704 watchdog-set-action (Command) Set watchdog action
706 Arguments:
708 "action: WatchdogAction"
710 Not documented
711 Since: 2.11
713 GUEST_PANICKED (Event) Emitted when guest OS panic is detected
715 Arguments:
717 "action: GuestPanicAction"
719 action that has been taken, currently always "pause"
720 "info: GuestPanicInformation" (optional)
722 information about a panic (since 2.9)
723 Since: 1.5
725 Example:
727 <- { "event": "GUEST_PANICKED",
729 "data": { "action": "pause" } }
730 GuestPanicAction (Enum)
732 An enumeration of the actions taken when guest OS panic is detected
734 Values:
736 "pause"
738 system pauses
739 "poweroff"
741 Not documented
742 Since: 2.1 (poweroff since 2.8)
744 GuestPanicInformationType (Enum)
746 An enumeration of the guest panic information types
748 Values:
750 "hyper-v"
752 hyper-v guest panic information type
753 "s390"
755 s390 guest panic information type (Since: 2.12)
756 Since: 2.9
758 GuestPanicInformation (Object)
760 Information about a guest panic
762 Members:
764 "type: GuestPanicInformationType"
766 Crash type that defines the hypervisor specific information
767 The members of "GuestPanicInformationHyperV" when "type" is "hyper-v"
769 The members of "GuestPanicInformationS390" when "type" is "s390"
770 Since: 2.9
772 GuestPanicInformationHyperV (Object)
774 Hyper-V specific guest panic information (HV crash MSRs)
776 Members:
778 "arg1: int"
780 Not documented
781 "arg2: int"
783 Not documented
784 "arg3: int"
786 Not documented
787 "arg4: int"
789 Not documented
790 "arg5: int"
792 Not documented
793 Since: 2.9
795 S390CrashReason (Enum)
797 Reason why the CPU is in a crashed state.
799 Values:
801 "unknown"
803 no crash reason was set
804 "disabled-wait"
806 the CPU has entered a disabled wait state
807 "extint-loop"
809 clock comparator or cpu timer interrupt with new PSW enabled for
810 external interrupts
811 "pgmint-loop"
813 program interrupt with BAD new PSW
814 "opint-loop"
816 operation exception interrupt with invalid code at the program
817 interrupt new PSW
818 Since: 2.12
820 GuestPanicInformationS390 (Object)
822 S390 specific guest panic information (PSW)
824 Members:
826 "core: int"
828 core id of the CPU that crashed
829 "psw-mask: int"
831 control fields of guest PSW
832 "psw-addr: int"
834 guest instruction address
835 "reason: S390CrashReason"
837 guest crash reason
838 Since: 2.12
840 Cryptography
842 QCryptoTLSCredsEndpoint (Enum)
843 The type of network endpoint that will be using the credentials. Most
845 types of credential require different setup / structures depending on
846 whether they will be used in a server versus a client.
847 Values:
849 "client"
851 the network endpoint is acting as the client
852 "server"
854 the network endpoint is acting as the server
855 Since: 2.5
857 QCryptoSecretFormat (Enum)
859 The data format that the secret is provided in
861 Values:
863 "raw"
865 raw bytes. When encoded in JSON only valid UTF-8 sequences can be
866 used
867 "base64"
869 arbitrary base64 encoded binary data
870 Since: 2.6
872 QCryptoHashAlgorithm (Enum)
874 The supported algorithms for computing content digests
876 Values:
878 "md5"
880 MD5. Should not be used in any new code, legacy compat only
881 "sha1"
883 SHA-1. Should not be used in any new code, legacy compat only
884 "sha224"
886 SHA-224. (since 2.7)
887 "sha256"
889 SHA-256. Current recommended strong hash.
890 "sha384"
892 SHA-384. (since 2.7)
893 "sha512"
895 SHA-512. (since 2.7)
896 "ripemd160"
898 RIPEMD-160. (since 2.7)
899 Since: 2.6
901 QCryptoCipherAlgorithm (Enum)
903 The supported algorithms for content encryption ciphers
905 Values:
907 "aes-128"
909 AES with 128 bit / 16 byte keys
910 "aes-192"
912 AES with 192 bit / 24 byte keys
913 "aes-256"
915 AES with 256 bit / 32 byte keys
916 "des-rfb"
918 RFB specific variant of single DES. Do not use except in VNC.
919 "3des"
921 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
922 "cast5-128"
924 Cast5 with 128 bit / 16 byte keys
925 "serpent-128"
927 Serpent with 128 bit / 16 byte keys
928 "serpent-192"
930 Serpent with 192 bit / 24 byte keys
931 "serpent-256"
933 Serpent with 256 bit / 32 byte keys
934 "twofish-128"
936 Twofish with 128 bit / 16 byte keys
937 "twofish-192"
939 Twofish with 192 bit / 24 byte keys
940 "twofish-256"
942 Twofish with 256 bit / 32 byte keys
943 Since: 2.6
945 QCryptoCipherMode (Enum)
947 The supported modes for content encryption ciphers
949 Values:
951 "ecb"
953 Electronic Code Book
954 "cbc"
956 Cipher Block Chaining
957 "xts"
959 XEX with tweaked code book and ciphertext stealing
960 "ctr"
962 Counter (Since 2.8)
963 Since: 2.6
965 QCryptoIVGenAlgorithm (Enum)
967 The supported algorithms for generating initialization vectors for full
969 disk encryption. The 'plain' generator should not be used for disks
970 with sector numbers larger than 2^32, except where compatibility with
971 pre-existing Linux dm-crypt volumes is required.
972 Values:
974 "plain"
976 64-bit sector number truncated to 32-bits
977 "plain64"
979 64-bit sector number
980 "essiv"
982 64-bit sector number encrypted with a hash of the encryption key
983 Since: 2.6
985 QCryptoBlockFormat (Enum)
987 The supported full disk encryption formats
989 Values:
991 "qcow"
993 QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
994 data from old images.
995 "luks"
997 LUKS encryption format. Recommended for new images
998 Since: 2.6
1000 QCryptoBlockOptionsBase (Object)
1002 The common options that apply to all full disk encryption formats
1004 Members:
1006 "format: QCryptoBlockFormat"
1008 the encryption format
1009 Since: 2.6
1011 QCryptoBlockOptionsQCow (Object)
1013 The options that apply to QCow/QCow2 AES-CBC encryption format
1015 Members:
1017 "key-secret: string" (optional)
1019 the ID of a QCryptoSecret object providing the decryption key.
1020 Mandatory except when probing image for metadata only.
1021 Since: 2.6
1023 QCryptoBlockOptionsLUKS (Object)
1025 The options that apply to LUKS encryption format
1027 Members:
1029 "key-secret: string" (optional)
1031 the ID of a QCryptoSecret object providing the decryption key.
1032 Mandatory except when probing image for metadata only.
1033 Since: 2.6
1035 QCryptoBlockCreateOptionsLUKS (Object)
1037 The options that apply to LUKS encryption format initialization
1039 Members:
1041 "cipher-alg: QCryptoCipherAlgorithm" (optional)
1043 the cipher algorithm for data encryption Currently defaults to
1044 'aes'.
1045 "cipher-mode: QCryptoCipherMode" (optional)
1047 the cipher mode for data encryption Currently defaults to 'cbc'
1048 "ivgen-alg: QCryptoIVGenAlgorithm" (optional)
1050 the initialization vector generator Currently defaults to 'essiv'
1051 "ivgen-hash-alg: QCryptoHashAlgorithm" (optional)
1053 the initialization vector generator hash Currently defaults to
1054 'sha256'
1055 "hash-alg: QCryptoHashAlgorithm" (optional)
1057 the master key hash algorithm Currently defaults to 'sha256'
1058 "iter-time: int" (optional)
1060 number of milliseconds to spend in PBKDF passphrase processing.
1061 Currently defaults to 2000. (since 2.8)
1062 The members of "QCryptoBlockOptionsLUKS"
1064 Since: 2.6
1066 QCryptoBlockOpenOptions (Object)
1068 The options that are available for all encryption formats when opening
1070 an existing volume
1071 Members:
1073 The members of "QCryptoBlockOptionsBase"
1075 The members of "QCryptoBlockOptionsQCow" when "format" is "qcow"
1076 The members of "QCryptoBlockOptionsLUKS" when "format" is "luks"
1077 Since: 2.6
1079 QCryptoBlockCreateOptions (Object)
1081 The options that are available for all encryption formats when
1083 initializing a new volume
1084 Members:
1086 The members of "QCryptoBlockOptionsBase"
1088 The members of "QCryptoBlockOptionsQCow" when "format" is "qcow"
1089 The members of "QCryptoBlockCreateOptionsLUKS" when "format" is "luks"
1090 Since: 2.6
1092 QCryptoBlockInfoBase (Object)
1094 The common information that applies to all full disk encryption formats
1096 Members:
1098 "format: QCryptoBlockFormat"
1100 the encryption format
1101 Since: 2.7
1103 QCryptoBlockInfoLUKSSlot (Object)
1105 Information about the LUKS block encryption key slot options
1107 Members:
1109 "active: boolean"
1111 whether the key slot is currently in use
1112 "key-offset: int"
1114 offset to the key material in bytes
1115 "iters: int" (optional)
1117 number of PBKDF2 iterations for key material
1118 "stripes: int" (optional)
1120 number of stripes for splitting key material
1121 Since: 2.7
1123 QCryptoBlockInfoLUKS (Object)
1125 Information about the LUKS block encryption options
1127 Members:
1129 "cipher-alg: QCryptoCipherAlgorithm"
1131 the cipher algorithm for data encryption
1132 "cipher-mode: QCryptoCipherMode"
1134 the cipher mode for data encryption
1135 "ivgen-alg: QCryptoIVGenAlgorithm"
1137 the initialization vector generator
1138 "ivgen-hash-alg: QCryptoHashAlgorithm" (optional)
1140 the initialization vector generator hash
1141 "hash-alg: QCryptoHashAlgorithm"
1143 the master key hash algorithm
1144 "payload-offset: int"
1146 offset to the payload data in bytes
1147 "master-key-iters: int"
1149 number of PBKDF2 iterations for key material
1150 "uuid: string"
1152 unique identifier for the volume
1153 "slots: array of QCryptoBlockInfoLUKSSlot"
1155 information about each key slot
1156 Since: 2.7
1158 QCryptoBlockInfo (Object)
1160 Information about the block encryption options
1162 Members:
1164 The members of "QCryptoBlockInfoBase"
1166 The members of "QCryptoBlockInfoLUKS" when "format" is "luks"
1167 Since: 2.7
1169 Block devices
1171 Block core (VM unrelated)
1172 Background jobs
1174 JobType (Enum)
1176 Type of a background job.
1178 Values:
1180 "commit"
1182 block commit job type, see "block-commit"
1183 "stream"
1185 block stream job type, see "block-stream"
1186 "mirror"
1188 drive mirror job type, see "drive-mirror"
1189 "backup"
1191 drive backup job type, see "drive-backup"
1192 "create"
1194 image creation job type, see "blockdev-create" (since 3.0)
1195 Since: 1.7
1197 JobStatus (Enum)
1199 Indicates the present state of a given job in its lifetime.
1201 Values:
1203 "undefined"
1205 Erroneous, default state. Should not ever be visible.
1206 "created"
1208 The job has been created, but not yet started.
1209 "running"
1211 The job is currently running.
1212 "paused"
1214 The job is running, but paused. The pause may be requested by
1215 either the QMP user or by internal processes.
1216 "ready"
1218 The job is running, but is ready for the user to signal completion.
1219 This is used for long-running jobs like mirror that are designed to
1220 run indefinitely.
1221 "standby"
1223 The job is ready, but paused. This is nearly identical to "paused".
1224 The job may return to "ready" or otherwise be canceled.
1225 "waiting"
1227 The job is waiting for other jobs in the transaction to converge to
1228 the waiting state. This status will likely not be visible for the
1229 last job in a transaction.
1230 "pending"
1232 The job has finished its work, but has finalization steps that it
1233 needs to make prior to completing. These changes will require
1234 manual intervention via "job-finalize" if auto-finalize was set to
1235 false. These pending changes may still fail.
1236 "aborting"
1238 The job is in the process of being aborted, and will finish with an
1239 error. The job will afterwards report that it is "concluded". This
1240 status may not be visible to the management process.
1241 "concluded"
1243 The job has finished all work. If auto-dismiss was set to false,
1244 the job will remain in the query list until it is dismissed via
1245 "job-dismiss".
1246 "null"
1248 The job is in the process of being dismantled. This state should
1249 not ever be visible externally.
1250 Since: 2.12
1252 JobVerb (Enum)
1254 Represents command verbs that can be applied to a job.
1256 Values:
1258 "cancel"
1260 see "job-cancel"
1261 "pause"
1263 see "job-pause"
1264 "resume"
1266 see "job-resume"
1267 "set-speed"
1269 see "block-job-set-speed"
1270 "complete"
1272 see "job-complete"
1273 "dismiss"
1275 see "job-dismiss"
1276 "finalize"
1278 see "job-finalize"
1279 Since: 2.12
1281 JOB_STATUS_CHANGE (Event) Emitted when a job transitions to a
1283 different status.
1284 Arguments:
1286 "id: string"
1288 The job identifier
1289 "status: JobStatus"
1291 The new job status
1292 Since: 3.0
1294 job-pause (Command) Pause an active job.
1296 This command returns immediately after marking the active job for
1298 pausing. Pausing an already paused job is an error.
1299 The job will pause as soon as possible, which means transitioning into
1301 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
1302 The corresponding JOB_STATUS_CHANGE event will be emitted.
1303 Cancelling a paused job automatically resumes it.
1305 Arguments:
1307 "id: string"
1309 The job identifier.
1310 Since: 3.0
1312 job-resume (Command) Resume a paused job.
1314 This command returns immediately after resuming a paused job. Resuming
1316 an already running job is an error.
1317 "id" : The job identifier.
1319 Arguments:
1321 "id: string"
1323 Not documented
1324 Since: 3.0
1326 job-cancel (Command) Instruct an active background job to cancel at
1328 the next opportunity. This command returns immediately after marking
1329 the active job for cancellation.
1330 The job will cancel as soon as possible and then emit a
1332 JOB_STATUS_CHANGE event. Usually, the status will change to ABORTING,
1333 but it is possible that a job successfully completes (e.g. because it
1334 was almost done and there was no opportunity to cancel earlier than
1335 completing the job) and transitions to PENDING instead.
1336 Arguments:
1338 "id: string"
1340 The job identifier.
1341 Since: 3.0
1343 job-complete (Command) Manually trigger completion of an active job in
1345 the READY state.
1346 Arguments:
1348 "id: string"
1350 The job identifier.
1351 Since: 3.0
1353 job-dismiss (Command) Deletes a job that is in the CONCLUDED state.
1355 This command only needs to be run explicitly for jobs that don't have
1356 automatic dismiss enabled.
1357 This command will refuse to operate on any job that has not yet reached
1359 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
1360 JOB_READY event, job-cancel or job-complete will still need to be used
1361 as appropriate.
1362 Arguments:
1364 "id: string"
1366 The job identifier.
1367 Since: 3.0
1369 job-finalize (Command) Instructs all jobs in a transaction (or a
1371 single job if it is not part of any transaction) to finalize any graph
1372 changes and do any necessary cleanup. This command requires that all
1373 involved jobs are in the PENDING state.
1374 For jobs in a transaction, instructing one job to finalize will force
1376 ALL jobs in the transaction to finalize, so it is only necessary to
1377 instruct a single member job to finalize.
1378 Arguments:
1380 "id: string"
1382 The identifier of any job in the transaction, or of a job that is
1383 not part of any transaction.
1384 Since: 3.0
1386 JobInfo (Object)
1388 Information about a job.
1390 Members:
1392 "id: string"
1394 The job identifier
1395 "type: JobType"
1397 The kind of job that is being performed
1398 "status: JobStatus"
1400 Current job state/status
1401 "current-progress: int"
1403 Progress made until now. The unit is arbitrary and the value can
1404 only meaningfully be used for the ratio of "current-progress" to
1405 "total-progress". The value is monotonically increasing.
1406 "total-progress: int"
1408 Estimated "current-progress" value at the completion of the job.
1409 This value can arbitrarily change while the job is running, in both
1410 directions.
1411 "error: string" (optional)
1413 If this field is present, the job failed; if it is still missing in
1414 the CONCLUDED state, this indicates successful completion.
1415 The value is a human-readable error message to describe the reason
1417 for the job failure. It should not be parsed by applications.
1418 Since: 3.0
1420 query-jobs (Command) Return information about jobs.
1422 Returns: a list with a "JobInfo" for each active job
1424 Since: 3.0
1426 SnapshotInfo (Object)
1428 Members:
1430 "id: string"
1432 unique snapshot id
1433 "name: string"
1435 user chosen name
1436 "vm-state-size: int"
1438 size of the VM state
1439 "date-sec: int"
1441 UTC date of the snapshot in seconds
1442 "date-nsec: int"
1444 fractional part in nano seconds to be used with date-sec
1445 "vm-clock-sec: int"
1447 VM clock relative to boot in seconds
1448 "vm-clock-nsec: int"
1450 fractional part in nano seconds to be used with vm-clock-sec
1451 Since: 1.3
1453 ImageInfoSpecificQCow2EncryptionBase (Object)
1455 Members:
1457 "format: BlockdevQcow2EncryptionFormat"
1459 The encryption format
1460 Since: 2.10
1462 ImageInfoSpecificQCow2Encryption (Object)
1464 Members:
1466 The members of "ImageInfoSpecificQCow2EncryptionBase"
1468 The members of "QCryptoBlockInfoLUKS" when "format" is "luks"
1469 Since: 2.10
1471 ImageInfoSpecificQCow2 (Object)
1473 Members:
1475 "compat: string"
1477 compatibility level
1478 "lazy-refcounts: boolean" (optional)
1480 on or off; only valid for compat >= 1.1
1481 "corrupt: boolean" (optional)
1483 true if the image has been marked corrupt; only valid for compat >=
1484 1.1 (since 2.2)
1485 "refcount-bits: int"
1487 width of a refcount entry in bits (since 2.3)
1488 "encrypt: ImageInfoSpecificQCow2Encryption" (optional)
1490 details about encryption parameters; only set if image is encrypted
1491 (since 2.10)
1492 Since: 1.7
1494 ImageInfoSpecificVmdk (Object)
1496 Members:
1498 "create-type: string"
1500 The create type of VMDK image
1501 "cid: int"
1503 Content id of image
1504 "parent-cid: int"
1506 Parent VMDK image's cid
1507 "extents: array of ImageInfo"
1509 List of extent files
1510 Since: 1.7
1512 ImageInfoSpecific (Object)
1514 A discriminated record of image format specific information structures.
1516 Members:
1518 "type"
1520 One of "qcow2", "vmdk", "luks"
1521 "data: ImageInfoSpecificQCow2" when "type" is "qcow2"
1523 "data: ImageInfoSpecificVmdk" when "type" is "vmdk"
1524 "data: QCryptoBlockInfoLUKS" when "type" is "luks"
1525 Since: 1.7
1527 ImageInfo (Object)
1529 Information about a QEMU image file
1531 Members:
1533 "filename: string"
1535 name of the image file
1536 "format: string"
1538 format of the image file
1539 "virtual-size: int"
1541 maximum capacity in bytes of the image
1542 "actual-size: int" (optional)
1544 actual size on disk in bytes of the image
1545 "dirty-flag: boolean" (optional)
1547 true if image is not cleanly closed
1548 "cluster-size: int" (optional)
1550 size of a cluster in bytes
1551 "encrypted: boolean" (optional)
1553 true if the image is encrypted
1554 "compressed: boolean" (optional)
1556 true if the image is compressed (Since 1.7)
1557 "backing-filename: string" (optional)
1559 name of the backing file
1560 "full-backing-filename: string" (optional)
1562 full path of the backing file
1563 "backing-filename-format: string" (optional)
1565 the format of the backing file
1566 "snapshots: array of SnapshotInfo" (optional)
1568 list of VM snapshots
1569 "backing-image: ImageInfo" (optional)
1571 info of the backing image (since 1.6)
1572 "format-specific: ImageInfoSpecific" (optional)
1574 structure supplying additional format-specific information (since
1575 1.7)
1576 Since: 1.3
1578 ImageCheck (Object)
1580 Information about a QEMU image file check
1582 Members:
1584 "filename: string"
1586 name of the image file checked
1587 "format: string"
1589 format of the image file checked
1590 "check-errors: int"
1592 number of unexpected errors occurred during check
1593 "image-end-offset: int" (optional)
1595 offset (in bytes) where the image ends, this field is present if
1596 the driver for the image format supports it
1597 "corruptions: int" (optional)
1599 number of corruptions found during the check if any
1600 "leaks: int" (optional)
1602 number of leaks found during the check if any
1603 "corruptions-fixed: int" (optional)
1605 number of corruptions fixed during the check if any
1606 "leaks-fixed: int" (optional)
1608 number of leaks fixed during the check if any
1609 "total-clusters: int" (optional)
1611 total number of clusters, this field is present if the driver for
1612 the image format supports it
1613 "allocated-clusters: int" (optional)
1615 total number of allocated clusters, this field is present if the
1616 driver for the image format supports it
1617 "fragmented-clusters: int" (optional)
1619 total number of fragmented clusters, this field is present if the
1620 driver for the image format supports it
1621 "compressed-clusters: int" (optional)
1623 total number of compressed clusters, this field is present if the
1624 driver for the image format supports it
1625 Since: 1.4
1627 MapEntry (Object)
1629 Mapping information from a virtual block range to a host file range
1631 Members:
1633 "start: int"
1635 the start byte of the mapped virtual range
1636 "length: int"
1638 the number of bytes of the mapped virtual range
1639 "data: boolean"
1641 whether the mapped range has data
1642 "zero: boolean"
1644 whether the virtual blocks are zeroed
1645 "depth: int"
1647 the depth of the mapping
1648 "offset: int" (optional)
1650 the offset in file that the virtual sectors are mapped to
1651 "filename: string" (optional)
1653 filename that is referred to by "offset"
1654 Since: 2.6
1656 BlockdevCacheInfo (Object)
1658 Cache mode information for a block device
1660 Members:
1662 "writeback: boolean"
1664 true if writeback mode is enabled
1665 "direct: boolean"
1667 true if the host page cache is bypassed (O_DIRECT)
1668 "no-flush: boolean"
1670 true if flush requests are ignored for the device
1671 Since: 2.3
1673 BlockDeviceInfo (Object)
1675 Information about the backing device for a block device.
1677 Members:
1679 "file: string"
1681 the filename of the backing device
1682 "node-name: string" (optional)
1684 the name of the block driver node (Since 2.0)
1685 "ro: boolean"
1687 true if the backing device was open read-only
1688 "drv: string"
1690 the name of the block format used to open the backing device. As of
1691 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
1692 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device', 'http',
1693 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2', 'raw', 'vdi',
1694 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added, 'cow' dropped 2.3:
1695 'host_floppy' deprecated 2.5: 'host_floppy' dropped 2.6: 'luks'
1696 added 2.8: 'replication' added, 'tftp' dropped 2.9: 'archipelago'
1697 dropped
1698 "backing_file: string" (optional)
1700 the name of the backing file (for copy-on-write)
1701 "backing_file_depth: int"
1703 number of files in the backing file chain (since: 1.2)
1704 "encrypted: boolean"
1706 true if the backing device is encrypted
1707 "encryption_key_missing: boolean"
1709 Deprecated; always false
1710 "detect_zeroes: BlockdevDetectZeroesOptions"
1712 detect and optimize zero writes (Since 2.1)
1713 "bps: int"
1715 total throughput limit in bytes per second is specified
1716 "bps_rd: int"
1718 read throughput limit in bytes per second is specified
1719 "bps_wr: int"
1721 write throughput limit in bytes per second is specified
1722 "iops: int"
1724 total I/O operations per second is specified
1725 "iops_rd: int"
1727 read I/O operations per second is specified
1728 "iops_wr: int"
1730 write I/O operations per second is specified
1731 "image: ImageInfo"
1733 the info of image used (since: 1.6)
1734 "bps_max: int" (optional)
1736 total throughput limit during bursts, in bytes (Since 1.7)
1737 "bps_rd_max: int" (optional)
1739 read throughput limit during bursts, in bytes (Since 1.7)
1740 "bps_wr_max: int" (optional)
1742 write throughput limit during bursts, in bytes (Since 1.7)
1743 "iops_max: int" (optional)
1745 total I/O operations per second during bursts, in bytes (Since 1.7)
1746 "iops_rd_max: int" (optional)
1748 read I/O operations per second during bursts, in bytes (Since 1.7)
1749 "iops_wr_max: int" (optional)
1751 write I/O operations per second during bursts, in bytes (Since 1.7)
1752 "bps_max_length: int" (optional)
1754 maximum length of the "bps_max" burst period, in seconds. (Since
1755 2.6)
1756 "bps_rd_max_length: int" (optional)
1758 maximum length of the "bps_rd_max" burst period, in seconds. (Since
1759 2.6)
1760 "bps_wr_max_length: int" (optional)
1762 maximum length of the "bps_wr_max" burst period, in seconds. (Since
1763 2.6)
1764 "iops_max_length: int" (optional)
1766 maximum length of the "iops" burst period, in seconds. (Since 2.6)
1767 "iops_rd_max_length: int" (optional)
1769 maximum length of the "iops_rd_max" burst period, in seconds.
1770 (Since 2.6)
1771 "iops_wr_max_length: int" (optional)
1773 maximum length of the "iops_wr_max" burst period, in seconds.
1774 (Since 2.6)
1775 "iops_size: int" (optional)
1777 an I/O size in bytes (Since 1.7)
1778 "group: string" (optional)
1780 throttle group name (Since 2.4)
1781 "cache: BlockdevCacheInfo"
1783 the cache mode used for the block device (since: 2.3)
1784 "write_threshold: int"
1786 configured write threshold for the device. 0 if disabled. (Since
1787 2.3)
1788 Since: 0.14.0
1790 BlockDeviceIoStatus (Enum)
1792 An enumeration of block device I/O status.
1794 Values:
1796 "ok"
1798 The last I/O operation has succeeded
1799 "failed"
1801 The last I/O operation has failed
1802 "nospace"
1804 The last I/O operation has failed due to a no-space condition
1805 Since: 1.0
1807 BlockDeviceMapEntry (Object)
1809 Entry in the metadata map of the device (returned by "qemu-img map")
1811 Members:
1813 "start: int"
1815 Offset in the image of the first byte described by this entry (in
1816 bytes)
1817 "length: int"
1819 Length of the range described by this entry (in bytes)
1820 "depth: int"
1822 Number of layers (0 = top image, 1 = top image's backing file,
1823 etc.) before reaching one for which the range is allocated. The
1824 value is in the range 0 to the depth of the image chain - 1.
1825 "zero: boolean"
1827 the sectors in this range read as zeros
1828 "data: boolean"
1830 reading the image will actually read data from a file (in
1831 particular, if "offset" is present this means that the sectors are
1832 not simply preallocated, but contain actual data in raw format)
1833 "offset: int" (optional)
1835 if present, the image file stores the data for this range in raw
1836 format at the given offset.
1837 Since: 1.7
1839 DirtyBitmapStatus (Enum)
1841 An enumeration of possible states that a dirty bitmap can report to the
1843 user.
1844 Values:
1846 "frozen"
1848 The bitmap is currently in-use by a backup operation or block job,
1849 and is immutable.
1850 "disabled"
1852 The bitmap is currently in-use by an internal operation and is
1853 read-only. It can still be deleted.
1854 "active"
1856 The bitmap is actively monitoring for new writes, and can be
1857 cleared, deleted, or used for backup operations.
1858 "locked"
1860 The bitmap is currently in-use by some operation and can not be
1861 cleared, deleted, or used for backup operations. (Since 2.12)
1862 Since: 2.4
1864 BlockDirtyInfo (Object)
1866 Block dirty bitmap information.
1868 Members:
1870 "name: string" (optional)
1872 the name of the dirty bitmap (Since 2.4)
1873 "count: int"
1875 number of dirty bytes according to the dirty bitmap
1876 "granularity: int"
1878 granularity of the dirty bitmap in bytes (since 1.4)
1879 "status: DirtyBitmapStatus"
1881 current status of the dirty bitmap (since 2.4)
1882 Since: 1.3
1884 BlockLatencyHistogramInfo (Object)
1886 Block latency histogram.
1888 Members:
1890 "boundaries: array of int"
1892 list of interval boundary values in nanoseconds, all greater than
1893 zero and in ascending order. For example, the list [10, 50, 100]
1894 produces the following histogram intervals: [0, 10), [10, 50), [50,
1895 100), [100, +inf).
1896 "bins: array of int"
1898 list of io request counts corresponding to histogram intervals.
1899 len("bins") = len("boundaries") + 1 For the example above, "bins"
1900 may be something like [3, 1, 5, 2], and corresponding histogram
1901 looks like:
1902 5| * 4| * 3| 2| * 1|
1904 +------------------ 10 50 100
1905 Since: 2.12
1907 x-block-latency-histogram-set (Command) Manage read, write and flush
1909 latency histograms for the device.
1910 If only "device" parameter is specified, remove all present latency
1912 histograms for the device. Otherwise, add/reset some of (or all)
1913 latency histograms.
1914 Arguments:
1916 "device: string"
1918 device name to set latency histogram for.
1919 "boundaries: array of int" (optional)
1921 list of interval boundary values (see description in
1922 BlockLatencyHistogramInfo definition). If specified, all latency
1923 histograms are removed, and empty ones created for all io types
1924 with intervals corresponding to "boundaries" (except for io types,
1925 for which specific boundaries are set through the following
1926 parameters).
1927 "boundaries-read: array of int" (optional)
1929 list of interval boundary values for read latency histogram. If
1930 specified, old read latency histogram is removed, and empty one
1931 created with intervals corresponding to "boundaries-read". The
1932 parameter has higher priority then "boundaries".
1933 "boundaries-write: array of int" (optional)
1935 list of interval boundary values for write latency histogram.
1936 "boundaries-flush: array of int" (optional)
1938 list of interval boundary values for flush latency histogram.
1939 Returns: error if device is not found or any boundary arrays are
1941 invalid.
1942 Since: 2.12
1944 Example:
1946 set new histograms for all io types with intervals
1948 [0, 10), [10, 50), [50, 100), [100, +inf):
1949 -> { "execute": "block-latency-histogram-set",
1951 "arguments": { "device": "drive0",
1952 "boundaries": [10, 50, 100] } }
1953 <- { "return": {} }
1954 Example:
1956 set new histogram only for write, other histograms will remain
1958 not changed (or not created):
1959 -> { "execute": "block-latency-histogram-set",
1961 "arguments": { "device": "drive0",
1962 "boundaries-write": [10, 50, 100] } }
1963 <- { "return": {} }
1964 Example:
1966 set new histograms with the following intervals:
1968 read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
1969 write: [0, 1000), [1000, 5000), [5000, +inf)
1970 -> { "execute": "block-latency-histogram-set",
1972 "arguments": { "device": "drive0",
1973 "boundaries": [10, 50, 100],
1974 "boundaries-write": [1000, 5000] } }
1975 <- { "return": {} }
1976 Example:
1978 remove all latency histograms:
1980 -> { "execute": "block-latency-histogram-set",
1982 "arguments": { "device": "drive0" } }
1983 <- { "return": {} }
1984 BlockInfo (Object)
1986 Block device information. This structure describes a virtual device
1988 and the backing device associated with it.
1989 Members:
1991 "device: string"
1993 The device name associated with the virtual device.
1994 "qdev: string" (optional)
1996 The qdev ID, or if no ID is assigned, the QOM path of the block
1997 device. (since 2.10)
1998 "type: string"
2000 This field is returned only for compatibility reasons, it should
2001 not be used (always returns 'unknown')
2002 "removable: boolean"
2004 True if the device supports removable media.
2005 "locked: boolean"
2007 True if the guest has locked this device from having its media
2008 removed
2009 "tray_open: boolean" (optional)
2011 True if the device's tray is open (only present if it has a tray)
2012 "dirty-bitmaps: array of BlockDirtyInfo" (optional)
2014 dirty bitmaps information (only present if the driver has one or
2015 more dirty bitmaps) (Since 2.0)
2016 "io-status: BlockDeviceIoStatus" (optional)
2018 "BlockDeviceIoStatus". Only present if the device supports it and
2019 the VM is configured to stop on errors (supported device models:
2020 virtio-blk, IDE, SCSI except scsi-generic)
2021 "inserted: BlockDeviceInfo" (optional)
2023 "BlockDeviceInfo" describing the device if media is present
2024 Since: 0.14.0
2026 BlockMeasureInfo (Object)
2028 Image file size calculation information. This structure describes the
2030 size requirements for creating a new image file.
2031 The size requirements depend on the new image file format. File size
2033 always equals virtual disk size for the 'raw' format, even for sparse
2034 POSIX files. Compact formats such as 'qcow2' represent unallocated and
2035 zero regions efficiently so file size may be smaller than virtual disk
2036 size.
2037 The values are upper bounds that are guaranteed to fit the new image
2039 file. Subsequent modification, such as internal snapshot or bitmap
2040 creation, may require additional space and is not covered here.
2041 Members:
2043 "required: int"
2045 Size required for a new image file, in bytes.
2046 "fully-allocated: int"
2048 Image file size, in bytes, once data has been written to all
2049 sectors.
2050 Since: 2.10
2052 query-block (Command) Get a list of BlockInfo for all virtual block
2054 devices.
2055 Returns: a list of "BlockInfo" describing each virtual block device.
2057 Filter nodes that were created implicitly are skipped over.
2058 Since: 0.14.0
2060 Example:
2062 -> { "execute": "query-block" }
2064 <- {
2065 "return":[
2066 {
2067 "io-status": "ok",
2068 "device":"ide0-hd0",
2069 "locked":false,
2070 "removable":false,
2071 "inserted":{
2072 "ro":false,
2073 "drv":"qcow2",
2074 "encrypted":false,
2075 "file":"disks/test.qcow2",
2076 "backing_file_depth":1,
2077 "bps":1000000,
2078 "bps_rd":0,
2079 "bps_wr":0,
2080 "iops":1000000,
2081 "iops_rd":0,
2082 "iops_wr":0,
2083 "bps_max": 8000000,
2084 "bps_rd_max": 0,
2085 "bps_wr_max": 0,
2086 "iops_max": 0,
2087 "iops_rd_max": 0,
2088 "iops_wr_max": 0,
2089 "iops_size": 0,
2090 "detect_zeroes": "on",
2091 "write_threshold": 0,
2092 "image":{
2093 "filename":"disks/test.qcow2",
2094 "format":"qcow2",
2095 "virtual-size":2048000,
2096 "backing_file":"base.qcow2",
2097 "full-backing-filename":"disks/base.qcow2",
2098 "backing-filename-format":"qcow2",
2099 "snapshots":[
2100 {
2101 "id": "1",
2102 "name": "snapshot1",
2103 "vm-state-size": 0,
2104 "date-sec": 10000200,
2105 "date-nsec": 12,
2106 "vm-clock-sec": 206,
2107 "vm-clock-nsec": 30
2108 }
2109 ],
2110 "backing-image":{
2111 "filename":"disks/base.qcow2",
2112 "format":"qcow2",
2113 "virtual-size":2048000
2114 }
2115 }
2116 },
2117 "qdev": "ide_disk",
2118 "type":"unknown"
2119 },
2120 {
2121 "io-status": "ok",
2122 "device":"ide1-cd0",
2123 "locked":false,
2124 "removable":true,
2125 "qdev": "/machine/unattached/device[23]",
2126 "tray_open": false,
2127 "type":"unknown"
2128 },
2129 {
2130 "device":"floppy0",
2131 "locked":false,
2132 "removable":true,
2133 "qdev": "/machine/unattached/device[20]",
2134 "type":"unknown"
2135 },
2136 {
2137 "device":"sd0",
2138 "locked":false,
2139 "removable":true,
2140 "type":"unknown"
2141 }
2142 ]
2143 }
2144 BlockDeviceTimedStats (Object)
2146 Statistics of a block device during a given interval of time.
2148 Members:
2150 "interval_length: int"
2152 Interval used for calculating the statistics, in seconds.
2153 "min_rd_latency_ns: int"
2155 Minimum latency of read operations in the defined interval, in
2156 nanoseconds.
2157 "min_wr_latency_ns: int"
2159 Minimum latency of write operations in the defined interval, in
2160 nanoseconds.
2161 "min_flush_latency_ns: int"
2163 Minimum latency of flush operations in the defined interval, in
2164 nanoseconds.
2165 "max_rd_latency_ns: int"
2167 Maximum latency of read operations in the defined interval, in
2168 nanoseconds.
2169 "max_wr_latency_ns: int"
2171 Maximum latency of write operations in the defined interval, in
2172 nanoseconds.
2173 "max_flush_latency_ns: int"
2175 Maximum latency of flush operations in the defined interval, in
2176 nanoseconds.
2177 "avg_rd_latency_ns: int"
2179 Average latency of read operations in the defined interval, in
2180 nanoseconds.
2181 "avg_wr_latency_ns: int"
2183 Average latency of write operations in the defined interval, in
2184 nanoseconds.
2185 "avg_flush_latency_ns: int"
2187 Average latency of flush operations in the defined interval, in
2188 nanoseconds.
2189 "avg_rd_queue_depth: number"
2191 Average number of pending read operations in the defined interval.
2192 "avg_wr_queue_depth: number"
2194 Average number of pending write operations in the defined interval.
2195 Since: 2.5
2197 BlockDeviceStats (Object)
2199 Statistics of a virtual block device or a block backing device.
2201 Members:
2203 "rd_bytes: int"
2205 The number of bytes read by the device.
2206 "wr_bytes: int"
2208 The number of bytes written by the device.
2209 "rd_operations: int"
2211 The number of read operations performed by the device.
2212 "wr_operations: int"
2214 The number of write operations performed by the device.
2215 "flush_operations: int"
2217 The number of cache flush operations performed by the device (since
2218 0.15.0)
2219 "flush_total_time_ns: int"
2221 Total time spend on cache flushes in nano-seconds (since 0.15.0).
2222 "wr_total_time_ns: int"
2224 Total time spend on writes in nano-seconds (since 0.15.0).
2225 "rd_total_time_ns: int"
2227 Total_time_spend on reads in nano-seconds (since 0.15.0).
2228 "wr_highest_offset: int"
2230 The offset after the greatest byte written to the device. The
2231 intended use of this information is for growable sparse files (like
2232 qcow2) that are used on top of a physical device.
2233 "rd_merged: int"
2235 Number of read requests that have been merged into another request
2236 (Since 2.3).
2237 "wr_merged: int"
2239 Number of write requests that have been merged into another request
2240 (Since 2.3).
2241 "idle_time_ns: int" (optional)
2243 Time since the last I/O operation, in nanoseconds. If the field is
2244 absent it means that there haven't been any operations yet (Since
2245 2.5).
2246 "failed_rd_operations: int"
2248 The number of failed read operations performed by the device (Since
2249 2.5)
2250 "failed_wr_operations: int"
2252 The number of failed write operations performed by the device
2253 (Since 2.5)
2254 "failed_flush_operations: int"
2256 The number of failed flush operations performed by the device
2257 (Since 2.5)
2258 "invalid_rd_operations: int"
2260 The number of invalid read operations performed by the device
2261 (Since 2.5)
2262 "invalid_wr_operations: int"
2264 The number of invalid write operations performed by the device
2265 (Since 2.5)
2266 "invalid_flush_operations: int"
2268 The number of invalid flush operations performed by the device
2269 (Since 2.5)
2270 "account_invalid: boolean"
2272 Whether invalid operations are included in the last access
2273 statistics (Since 2.5)
2274 "account_failed: boolean"
2276 Whether failed operations are included in the latency and last
2277 access statistics (Since 2.5)
2278 "timed_stats: array of BlockDeviceTimedStats"
2280 Statistics specific to the set of previously defined intervals of
2281 time (Since 2.5)
2282 "x_rd_latency_histogram: BlockLatencyHistogramInfo" (optional)
2284 "BlockLatencyHistogramInfo". (Since 2.12)
2285 "x_wr_latency_histogram: BlockLatencyHistogramInfo" (optional)
2287 "BlockLatencyHistogramInfo". (Since 2.12)
2288 "x_flush_latency_histogram: BlockLatencyHistogramInfo" (optional)
2290 "BlockLatencyHistogramInfo". (Since 2.12)
2291 Since: 0.14.0
2293 BlockStats (Object)
2295 Statistics of a virtual block device or a block backing device.
2297 Members:
2299 "device: string" (optional)
2301 If the stats are for a virtual block device, the name corresponding
2302 to the virtual block device.
2303 "node-name: string" (optional)
2305 The node name of the device. (Since 2.3)
2306 "qdev: string" (optional)
2308 The qdev ID, or if no ID is assigned, the QOM path of the block
2309 device. (since 3.0)
2310 "stats: BlockDeviceStats"
2312 A "BlockDeviceStats" for the device.
2313 "parent: BlockStats" (optional)
2315 This describes the file block device if it has one. Contains
2316 recursively the statistics of the underlying protocol (e.g. the
2317 host file for a qcow2 image). If there is no underlying protocol,
2318 this field is omitted
2319 "backing: BlockStats" (optional)
2321 This describes the backing block device if it has one. (Since 2.0)
2322 Since: 0.14.0
2324 query-blockstats (Command) Query the "BlockStats" for all virtual
2326 block devices.
2327 Arguments:
2329 "query-nodes: boolean" (optional)
2331 If true, the command will query all the block nodes that have a
2332 node name, in a list which will include "parent" information, but
2333 not "backing". If false or omitted, the behavior is as before -
2334 query all the device backends, recursively including their "parent"
2335 and "backing". Filter nodes that were created implicitly are
2336 skipped over in this mode. (Since 2.3)
2337 Returns: A list of "BlockStats" for each virtual block devices.
2339 Since: 0.14.0
2341 Example:
2343 -> { "execute": "query-blockstats" }
2345 <- {
2346 "return":[
2347 {
2348 "device":"ide0-hd0",
2349 "parent":{
2350 "stats":{
2351 "wr_highest_offset":3686448128,
2352 "wr_bytes":9786368,
2353 "wr_operations":751,
2354 "rd_bytes":122567168,
2355 "rd_operations":36772
2356 "wr_total_times_ns":313253456
2357 "rd_total_times_ns":3465673657
2358 "flush_total_times_ns":49653
2359 "flush_operations":61,
2360 "rd_merged":0,
2361 "wr_merged":0,
2362 "idle_time_ns":2953431879,
2363 "account_invalid":true,
2364 "account_failed":false
2365 }
2366 },
2367 "stats":{
2368 "wr_highest_offset":2821110784,
2369 "wr_bytes":9786368,
2370 "wr_operations":692,
2371 "rd_bytes":122739200,
2372 "rd_operations":36604
2373 "flush_operations":51,
2374 "wr_total_times_ns":313253456
2375 "rd_total_times_ns":3465673657
2376 "flush_total_times_ns":49653,
2377 "rd_merged":0,
2378 "wr_merged":0,
2379 "idle_time_ns":2953431879,
2380 "account_invalid":true,
2381 "account_failed":false
2382 },
2383 "qdev": "/machine/unattached/device[23]"
2384 },
2385 {
2386 "device":"ide1-cd0",
2387 "stats":{
2388 "wr_highest_offset":0,
2389 "wr_bytes":0,
2390 "wr_operations":0,
2391 "rd_bytes":0,
2392 "rd_operations":0
2393 "flush_operations":0,
2394 "wr_total_times_ns":0
2395 "rd_total_times_ns":0
2396 "flush_total_times_ns":0,
2397 "rd_merged":0,
2398 "wr_merged":0,
2399 "account_invalid":false,
2400 "account_failed":false
2401 },
2402 "qdev": "/machine/unattached/device[24]"
2403 },
2404 {
2405 "device":"floppy0",
2406 "stats":{
2407 "wr_highest_offset":0,
2408 "wr_bytes":0,
2409 "wr_operations":0,
2410 "rd_bytes":0,
2411 "rd_operations":0
2412 "flush_operations":0,
2413 "wr_total_times_ns":0
2414 "rd_total_times_ns":0
2415 "flush_total_times_ns":0,
2416 "rd_merged":0,
2417 "wr_merged":0,
2418 "account_invalid":false,
2419 "account_failed":false
2420 },
2421 "qdev": "/machine/unattached/device[16]"
2422 },
2423 {
2424 "device":"sd0",
2425 "stats":{
2426 "wr_highest_offset":0,
2427 "wr_bytes":0,
2428 "wr_operations":0,
2429 "rd_bytes":0,
2430 "rd_operations":0
2431 "flush_operations":0,
2432 "wr_total_times_ns":0
2433 "rd_total_times_ns":0
2434 "flush_total_times_ns":0,
2435 "rd_merged":0,
2436 "wr_merged":0,
2437 "account_invalid":false,
2438 "account_failed":false
2439 }
2440 }
2441 ]
2442 }
2443 BlockdevOnError (Enum)
2445 An enumeration of possible behaviors for errors on I/O operations. The
2447 exact meaning depends on whether the I/O was initiated by a guest or by
2448 a block job
2449 Values:
2451 "report"
2453 for guest operations, report the error to the guest; for jobs,
2454 cancel the job
2455 "ignore"
2457 ignore the error, only report a QMP event (BLOCK_IO_ERROR or
2458 BLOCK_JOB_ERROR)
2459 "enospc"
2461 same as "stop" on ENOSPC, same as "report" otherwise.
2462 "stop"
2464 for guest operations, stop the virtual machine; for jobs, pause the
2465 job
2466 "auto"
2468 inherit the error handling policy of the backend (since: 2.7)
2469 Since: 1.3
2471 MirrorSyncMode (Enum)
2473 An enumeration of possible behaviors for the initial synchronization
2475 phase of storage mirroring.
2476 Values:
2478 "top"
2480 copies data in the topmost image to the destination
2481 "full"
2483 copies data from all images to the destination
2484 "none"
2486 only copy data written from now on
2487 "incremental"
2489 only copy data described by the dirty bitmap. Since: 2.4
2490 Since: 1.3
2492 MirrorCopyMode (Enum)
2494 An enumeration whose values tell the mirror block job when to trigger
2496 writes to the target.
2497 Values:
2499 "background"
2501 copy data in background only.
2502 "write-blocking"
2504 when data is written to the source, write it (synchronously) to the
2505 target as well. In addition, data is copied in background just
2506 like in "background" mode.
2507 Since: 3.0
2509 BlockJobInfo (Object)
2511 Information about a long-running block device operation.
2513 Members:
2515 "type: string"
2517 the job type ('stream' for image streaming)
2518 "device: string"
2520 The job identifier. Originally the device name but other values are
2521 allowed since QEMU 2.7
2522 "len: int"
2524 Estimated "offset" value at the completion of the job. This value
2525 can arbitrarily change while the job is running, in both
2526 directions.
2527 "offset: int"
2529 Progress made until now. The unit is arbitrary and the value can
2530 only meaningfully be used for the ratio of "offset" to "len". The
2531 value is monotonically increasing.
2532 "busy: boolean"
2534 false if the job is known to be in a quiescent state, with no
2535 pending I/O. Since 1.3.
2536 "paused: boolean"
2538 whether the job is paused or, if "busy" is true, will pause itself
2539 as soon as possible. Since 1.3.
2540 "speed: int"
2542 the rate limit, bytes per second
2543 "io-status: BlockDeviceIoStatus"
2545 the status of the job (since 1.3)
2546 "ready: boolean"
2548 true if the job may be completed (since 2.2)
2549 "status: JobStatus"
2551 Current job state/status (since 2.12)
2552 "auto-finalize: boolean"
2554 Job will finalize itself when PENDING, moving to the CONCLUDED
2555 state. (since 2.12)
2556 "auto-dismiss: boolean"
2558 Job will dismiss itself when CONCLUDED, moving to the NULL state
2559 and disappearing from the query list. (since 2.12)
2560 "error: string" (optional)
2562 Error information if the job did not complete successfully. Not
2563 set if the job completed successfully. (since 2.12.1)
2564 Since: 1.1
2566 query-block-jobs (Command) Return information about long-running block
2568 device operations.
2569 Returns: a list of "BlockJobInfo" for each active block job
2571 Since: 1.1
2573 block_passwd (Command) This command sets the password of a block
2575 device that has not been open with a password and requires one.
2576 This command is now obsolete and will always return an error since 2.10
2578 Arguments:
2580 "device: string" (optional)
2582 Not documented
2583 "node-name: string" (optional)
2585 Not documented
2586 "password: string"
2588 Not documented
2589 block_resize (Command) Resize a block image while a guest is running.
2591 Either "device" or "node-name" must be set but not both.
2593 Arguments:
2595 "device: string" (optional)
2597 the name of the device to get the image resized
2598 "node-name: string" (optional)
2600 graph node name to get the image resized (Since 2.0)
2601 "size: int"
2603 new image size in bytes
2604 Returns: nothing on success If "device" is not a valid block device,
2606 DeviceNotFound
2607 Since: 0.14.0
2609 Example:
2611 -> { "execute": "block_resize",
2613 "arguments": { "device": "scratch", "size": 1073741824 } }
2614 <- { "return": {} }
2615 NewImageMode (Enum)
2617 An enumeration that tells QEMU how to set the backing file path in a
2619 new image file.
2620 Values:
2622 "existing"
2624 QEMU should look for an existing image file.
2625 "absolute-paths"
2627 QEMU should create a new image with absolute paths for the backing
2628 file. If there is no backing file available, the new image will not
2629 be backed either.
2630 Since: 1.1
2632 BlockdevSnapshotSync (Object)
2634 Either "device" or "node-name" must be set but not both.
2636 Members:
2638 "device: string" (optional)
2640 the name of the device to generate the snapshot from.
2641 "node-name: string" (optional)
2643 graph node name to generate the snapshot from (Since 2.0)
2644 "snapshot-file: string"
2646 the target of the new image. If the file exists, or if it is a
2647 device, the snapshot will be created in the existing file/device.
2648 Otherwise, a new file will be created.
2649 "snapshot-node-name: string" (optional)
2651 the graph node name of the new image (Since 2.0)
2652 "format: string" (optional)
2654 the format of the snapshot image, default is 'qcow2'.
2655 "mode: NewImageMode" (optional)
2657 whether and how QEMU should create a new image, default is
2658 'absolute-paths'.
2659 BlockdevSnapshot (Object)
2661 Members:
2663 "node: string"
2665 device or node name that will have a snapshot created.
2666 "overlay: string"
2668 reference to the existing block device that will become the overlay
2669 of "node", as part of creating the snapshot. It must not have a
2670 current backing file (this can be achieved by passing "backing":
2671 null to blockdev-add).
2672 Since: 2.5
2674 DriveBackup (Object)
2676 Members:
2678 "job-id: string" (optional)
2680 identifier for the newly-created block job. If omitted, the device
2681 name will be used. (Since 2.7)
2682 "device: string"
2684 the device name or node-name of a root node which should be copied.
2685 "target: string"
2687 the target of the new image. If the file exists, or if it is a
2688 device, the existing file/device will be used as the new
2689 destination. If it does not exist, a new file will be created.
2690 "format: string" (optional)
2692 the format of the new destination, default is to probe if "mode" is
2693 'existing', else the format of the source
2694 "sync: MirrorSyncMode"
2696 what parts of the disk image should be copied to the destination
2697 (all the disk, only the sectors allocated in the topmost image,
2698 from a dirty bitmap, or only new I/O).
2699 "mode: NewImageMode" (optional)
2701 whether and how QEMU should create a new image, default is
2702 'absolute-paths'.
2703 "speed: int" (optional)
2705 the maximum speed, in bytes per second
2706 "bitmap: string" (optional)
2708 the name of dirty bitmap if sync is "incremental". Must be present
2709 if sync is "incremental", must NOT be present otherwise. (Since
2710 2.4)
2711 "compress: boolean" (optional)
2713 true to compress data, if the target format supports it. (default:
2714 false) (since 2.8)
2715 "on-source-error: BlockdevOnError" (optional)
2717 the action to take on an error on the source, default 'report'.
2718 'stop' and 'enospc' can only be used if the block device supports
2719 io-status (see BlockInfo).
2720 "on-target-error: BlockdevOnError" (optional)
2722 the action to take on an error on the target, default 'report' (no
2723 limitations, since this applies to a different block device than
2724 "device").
2725 "auto-finalize: boolean" (optional)
2727 When false, this job will wait in a PENDING state after it has
2728 finished its work, waiting for "block-job-finalize" before making
2729 any block graph changes. When true, this job will automatically
2730 perform its abort or commit actions. Defaults to true. (Since
2731 2.12)
2732 "auto-dismiss: boolean" (optional)
2734 When false, this job will wait in a CONCLUDED state after it has
2735 completely ceased all work, and awaits "block-job-dismiss". When
2736 true, this job will automatically disappear from the query list
2737 without user intervention. Defaults to true. (Since 2.12)
2738 Note: "on-source-error" and "on-target-error" only affect background
2740 I/O. If an error occurs during a guest write request, the device's
2741 rerror/werror actions will be used.
2742 Since: 1.6
2744 BlockdevBackup (Object)
2746 Members:
2748 "job-id: string" (optional)
2750 identifier for the newly-created block job. If omitted, the device
2751 name will be used. (Since 2.7)
2752 "device: string"
2754 the device name or node-name of a root node which should be copied.
2755 "target: string"
2757 the device name or node-name of the backup target node.
2758 "sync: MirrorSyncMode"
2760 what parts of the disk image should be copied to the destination
2761 (all the disk, only the sectors allocated in the topmost image, or
2762 only new I/O).
2763 "speed: int" (optional)
2765 the maximum speed, in bytes per second. The default is 0, for
2766 unlimited.
2767 "bitmap: string" (optional)
2769 the name of dirty bitmap if sync is "incremental". Must be present
2770 if sync is "incremental", must NOT be present otherwise. (Since
2771 3.1)
2772 "compress: boolean" (optional)
2774 true to compress data, if the target format supports it. (default:
2775 false) (since 2.8)
2776 "on-source-error: BlockdevOnError" (optional)
2778 the action to take on an error on the source, default 'report'.
2779 'stop' and 'enospc' can only be used if the block device supports
2780 io-status (see BlockInfo).
2781 "on-target-error: BlockdevOnError" (optional)
2783 the action to take on an error on the target, default 'report' (no
2784 limitations, since this applies to a different block device than
2785 "device").
2786 "auto-finalize: boolean" (optional)
2788 When false, this job will wait in a PENDING state after it has
2789 finished its work, waiting for "block-job-finalize" before making
2790 any block graph changes. When true, this job will automatically
2791 perform its abort or commit actions. Defaults to true. (Since
2792 2.12)
2793 "auto-dismiss: boolean" (optional)
2795 When false, this job will wait in a CONCLUDED state after it has
2796 completely ceased all work, and awaits "block-job-dismiss". When
2797 true, this job will automatically disappear from the query list
2798 without user intervention. Defaults to true. (Since 2.12)
2799 Note: "on-source-error" and "on-target-error" only affect background
2801 I/O. If an error occurs during a guest write request, the device's
2802 rerror/werror actions will be used.
2803 Since: 2.3
2805 blockdev-snapshot-sync (Command) Generates a synchronous snapshot of a
2807 block device.
2808 For the arguments, see the documentation of BlockdevSnapshotSync.
2810 Returns: nothing on success If "device" is not a valid block device,
2812 DeviceNotFound
2813 Since: 0.14.0
2815 Example:
2817 -> { "execute": "blockdev-snapshot-sync",
2819 "arguments": { "device": "ide-hd0",
2820 "snapshot-file":
2821 "/some/place/my-image",
2822 "format": "qcow2" } }
2823 <- { "return": {} }
2824 blockdev-snapshot (Command) Generates a snapshot of a block device.
2826 Create a snapshot, by installing 'node' as the backing image of
2828 'overlay'. Additionally, if 'node' is associated with a block device,
2829 the block device changes to using 'overlay' as its new active image.
2830 For the arguments, see the documentation of BlockdevSnapshot.
2832 Since: 2.5
2834 Example:
2836 -> { "execute": "blockdev-add",
2838 "arguments": { "driver": "qcow2",
2839 "node-name": "node1534",
2840 "file": { "driver": "file",
2841 "filename": "hd1.qcow2" },
2842 "backing": null } }
2843 <- { "return": {} }
2845 -> { "execute": "blockdev-snapshot",
2847 "arguments": { "node": "ide-hd0",
2848 "overlay": "node1534" } }
2849 <- { "return": {} }
2850 change-backing-file (Command) Change the backing file in the image
2852 file metadata. This does not cause QEMU to reopen the image file to
2853 reparse the backing filename (it may, however, perform a reopen to
2854 change permissions from r/o -> r/w -> r/o, if needed). The new backing
2855 file string is written into the image file metadata, and the QEMU
2856 internal strings are updated.
2857 Arguments:
2859 "image-node-name: string"
2861 The name of the block driver state node of the image to modify. The
2862 "device" argument is used to verify "image-node-name" is in the
2863 chain described by "device".
2864 "device: string"
2866 The device name or node-name of the root node that owns image-node-
2867 name.
2868 "backing-file: string"
2870 The string to write as the backing file. This string is not
2871 validated, so care should be taken when specifying the string or
2872 the image chain may not be able to be reopened again.
2873 Returns: Nothing on success
2875 If "device" does not exist or cannot be determined, DeviceNotFound
2877 Since: 2.1
2879 block-commit (Command) Live commit of data from overlay image nodes
2881 into backing nodes - i.e., writes data between 'top' and 'base' into
2882 'base'.
2883 Arguments:
2885 "job-id: string" (optional)
2887 identifier for the newly-created block job. If omitted, the device
2888 name will be used. (Since 2.7)
2889 "device: string"
2891 the device name or node-name of a root node
2892 "base-node: string" (optional)
2894 The node name of the backing image to write data into. If not
2895 specified, this is the deepest backing image. (since: 3.1)
2896 "base: string" (optional)
2898 Same as "base-node", except that it is a file name rather than a
2899 node name. This must be the exact filename string that was used to
2900 open the node; other strings, even if addressing the same file, are
2901 not accepted (deprecated, use "base-node" instead)
2902 "top-node: string" (optional)
2904 The node name of the backing image within the image chain which
2905 contains the topmost data to be committed down. If not specified,
2906 this is the active layer. (since: 3.1)
2907 "top: string" (optional)
2909 Same as "top-node", except that it is a file name rather than a
2910 node name. This must be the exact filename string that was used to
2911 open the node; other strings, even if addressing the same file, are
2912 not accepted (deprecated, use "base-node" instead)
2913 "backing-file: string" (optional)
2915 The backing file string to write into the overlay image of 'top'.
2916 If 'top' is the active layer, specifying a backing file string is
2917 an error. This filename is not validated.
2918 If a pathname string is such that it cannot be resolved by QEMU,
2920 that means that subsequent QMP or HMP commands must use node-names
2921 for the image in question, as filename lookup methods will fail.
2922 If not specified, QEMU will automatically determine the backing
2924 file string to use, or error out if there is no obvious choice.
2925 Care should be taken when specifying the string, to specify a valid
2926 filename or protocol. (Since 2.1)
2927 If top == base, that is an error. If top == active, the job will
2929 not be completed by itself, user needs to complete the job with the
2930 block-job-complete command after getting the ready event. (Since
2931 2.0)
2932 If the base image is smaller than top, then the base image will be
2934 resized to be the same size as top. If top is smaller than the
2935 base image, the base will not be truncated. If you want the base
2936 image size to match the size of the smaller top, you can safely
2937 truncate it yourself once the commit operation successfully
2938 completes.
2939 "speed: int" (optional)
2941 the maximum speed, in bytes per second
2942 "filter-node-name: string" (optional)
2944 the node name that should be assigned to the filter driver that the
2945 commit job inserts into the graph above "top". If this option is
2946 not given, a node name is autogenerated. (Since: 2.9)
2947 "auto-finalize: boolean" (optional)
2949 When false, this job will wait in a PENDING state after it has
2950 finished its work, waiting for "block-job-finalize" before making
2951 any block graph changes. When true, this job will automatically
2952 perform its abort or commit actions. Defaults to true. (Since 3.1)
2953 "auto-dismiss: boolean" (optional)
2955 When false, this job will wait in a CONCLUDED state after it has
2956 completely ceased all work, and awaits "block-job-dismiss". When
2957 true, this job will automatically disappear from the query list
2958 without user intervention. Defaults to true. (Since 3.1)
2959 Returns: Nothing on success If "device" does not exist, DeviceNotFound
2961 Any other error returns a GenericError.
2962 Since: 1.3
2964 Example:
2966 -> { "execute": "block-commit",
2968 "arguments": { "device": "virtio0",
2969 "top": "/tmp/snap1.qcow2" } }
2970 <- { "return": {} }
2971 drive-backup (Command) Start a point-in-time copy of a block device to
2973 a new destination. The status of ongoing drive-backup operations can
2974 be checked with query-block-jobs where the BlockJobInfo.type field has
2975 the value 'backup'. The operation can be stopped before it has
2976 completed using the block-job-cancel command.
2977 Arguments: the members of "DriveBackup"
2979 Returns: nothing on success If "device" is not a valid block device,
2981 GenericError
2982 Since: 1.6
2984 Example:
2986 -> { "execute": "drive-backup",
2988 "arguments": { "device": "drive0",
2989 "sync": "full",
2990 "target": "backup.img" } }
2991 <- { "return": {} }
2992 blockdev-backup (Command) Start a point-in-time copy of a block device
2994 to a new destination. The status of ongoing blockdev-backup operations
2995 can be checked with query-block-jobs where the BlockJobInfo.type field
2996 has the value 'backup'. The operation can be stopped before it has
2997 completed using the block-job-cancel command.
2998 Arguments: the members of "BlockdevBackup"
3000 Returns: nothing on success If "device" is not a valid block device,
3002 DeviceNotFound
3003 Since: 2.3
3005 Example:
3007 -> { "execute": "blockdev-backup",
3009 "arguments": { "device": "src-id",
3010 "sync": "full",
3011 "target": "tgt-id" } }
3012 <- { "return": {} }
3013 query-named-block-nodes (Command) Get the named block driver list
3015 Returns: the list of BlockDeviceInfo
3017 Since: 2.0
3019 Example:
3021 -> { "execute": "query-named-block-nodes" }
3023 <- { "return": [ { "ro":false,
3024 "drv":"qcow2",
3025 "encrypted":false,
3026 "file":"disks/test.qcow2",
3027 "node-name": "my-node",
3028 "backing_file_depth":1,
3029 "bps":1000000,
3030 "bps_rd":0,
3031 "bps_wr":0,
3032 "iops":1000000,
3033 "iops_rd":0,
3034 "iops_wr":0,
3035 "bps_max": 8000000,
3036 "bps_rd_max": 0,
3037 "bps_wr_max": 0,
3038 "iops_max": 0,
3039 "iops_rd_max": 0,
3040 "iops_wr_max": 0,
3041 "iops_size": 0,
3042 "write_threshold": 0,
3043 "image":{
3044 "filename":"disks/test.qcow2",
3045 "format":"qcow2",
3046 "virtual-size":2048000,
3047 "backing_file":"base.qcow2",
3048 "full-backing-filename":"disks/base.qcow2",
3049 "backing-filename-format":"qcow2",
3050 "snapshots":[
3051 {
3052 "id": "1",
3053 "name": "snapshot1",
3054 "vm-state-size": 0,
3055 "date-sec": 10000200,
3056 "date-nsec": 12,
3057 "vm-clock-sec": 206,
3058 "vm-clock-nsec": 30
3059 }
3060 ],
3061 "backing-image":{
3062 "filename":"disks/base.qcow2",
3063 "format":"qcow2",
3064 "virtual-size":2048000
3065 }
3066 } } ] }
3067 drive-mirror (Command) Start mirroring a block device's writes to a
3069 new destination. target specifies the target of the new image. If the
3070 file exists, or if it is a device, it will be used as the new
3071 destination for writes. If it does not exist, a new file will be
3072 created. format specifies the format of the mirror image, default is to
3073 probe if mode='existing', else the format of the source.
3074 Arguments: the members of "DriveMirror"
3076 Returns: nothing on success If "device" is not a valid block device,
3078 GenericError
3079 Since: 1.3
3081 Example:
3083 -> { "execute": "drive-mirror",
3085 "arguments": { "device": "ide-hd0",
3086 "target": "/some/place/my-image",
3087 "sync": "full",
3088 "format": "qcow2" } }
3089 <- { "return": {} }
3090 DriveMirror (Object)
3092 A set of parameters describing drive mirror setup.
3094 Members:
3096 "job-id: string" (optional)
3098 identifier for the newly-created block job. If omitted, the device
3099 name will be used. (Since 2.7)
3100 "device: string"
3102 the device name or node-name of a root node whose writes should be
3103 mirrored.
3104 "target: string"
3106 the target of the new image. If the file exists, or if it is a
3107 device, the existing file/device will be used as the new
3108 destination. If it does not exist, a new file will be created.
3109 "format: string" (optional)
3111 the format of the new destination, default is to probe if "mode" is
3112 'existing', else the format of the source
3113 "node-name: string" (optional)
3115 the new block driver state node name in the graph (Since 2.1)
3116 "replaces: string" (optional)
3118 with sync=full graph node name to be replaced by the new image when
3119 a whole image copy is done. This can be used to repair broken
3120 Quorum files. (Since 2.1)
3121 "mode: NewImageMode" (optional)
3123 whether and how QEMU should create a new image, default is
3124 'absolute-paths'.
3125 "speed: int" (optional)
3127 the maximum speed, in bytes per second
3128 "sync: MirrorSyncMode"
3130 what parts of the disk image should be copied to the destination
3131 (all the disk, only the sectors allocated in the topmost image, or
3132 only new I/O).
3133 "granularity: int" (optional)
3135 granularity of the dirty bitmap, default is 64K if the image format
3136 doesn't have clusters, 4K if the clusters are smaller than that,
3137 else the cluster size. Must be a power of 2 between 512 and 64M
3138 (since 1.4).
3139 "buf-size: int" (optional)
3141 maximum amount of data in flight from source to target (since 1.4).
3142 "on-source-error: BlockdevOnError" (optional)
3144 the action to take on an error on the source, default 'report'.
3145 'stop' and 'enospc' can only be used if the block device supports
3146 io-status (see BlockInfo).
3147 "on-target-error: BlockdevOnError" (optional)
3149 the action to take on an error on the target, default 'report' (no
3150 limitations, since this applies to a different block device than
3151 "device").
3152 "unmap: boolean" (optional)
3154 Whether to try to unmap target sectors where source has only zero.
3155 If true, and target unallocated sectors will read as zero, target
3156 image sectors will be unmapped; otherwise, zeroes will be written.
3157 Both will result in identical contents. Default is true. (Since
3158 2.4)
3159 "copy-mode: MirrorCopyMode" (optional)
3161 when to copy data to the destination; defaults to 'background'
3162 (Since: 3.0)
3163 "auto-finalize: boolean" (optional)
3165 When false, this job will wait in a PENDING state after it has
3166 finished its work, waiting for "block-job-finalize" before making
3167 any block graph changes. When true, this job will automatically
3168 perform its abort or commit actions. Defaults to true. (Since 3.1)
3169 "auto-dismiss: boolean" (optional)
3171 When false, this job will wait in a CONCLUDED state after it has
3172 completely ceased all work, and awaits "block-job-dismiss". When
3173 true, this job will automatically disappear from the query list
3174 without user intervention. Defaults to true. (Since 3.1)
3175 Since: 1.3
3177 BlockDirtyBitmap (Object)
3179 Members:
3181 "node: string"
3183 name of device/node which the bitmap is tracking
3184 "name: string"
3186 name of the dirty bitmap
3187 Since: 2.4
3189 BlockDirtyBitmapAdd (Object)
3191 Members:
3193 "node: string"
3195 name of device/node which the bitmap is tracking
3196 "name: string"
3198 name of the dirty bitmap
3199 "granularity: int" (optional)
3201 the bitmap granularity, default is 64k for block-dirty-bitmap-add
3202 "persistent: boolean" (optional)
3204 the bitmap is persistent, i.e. it will be saved to the
3205 corresponding block device image file on its close. For now only
3206 Qcow2 disks support persistent bitmaps. Default is false for block-
3207 dirty-bitmap-add. (Since: 2.10)
3208 "autoload: boolean" (optional)
3210 ignored and deprecated since 2.12. Currently, all dirty tracking
3211 bitmaps are loaded from Qcow2 on open.
3212 "x-disabled: boolean" (optional)
3214 the bitmap is created in the disabled state, which means that it
3215 will not track drive changes. The bitmap may be enabled with
3216 x-block-dirty-bitmap-enable. Default is false. (Since: 3.0)
3217 Since: 2.4
3219 BlockDirtyBitmapMerge (Object)
3221 Members:
3223 "node: string"
3225 name of device/node which the bitmap is tracking
3226 "dst_name: string"
3228 name of the destination dirty bitmap
3229 "src_name: string"
3231 name of the source dirty bitmap
3232 Since: 3.0
3234 block-dirty-bitmap-add (Command) Create a dirty bitmap with a name on
3236 the node, and start tracking the writes.
3237 Returns: nothing on success If "node" is not a valid block device or
3239 node, DeviceNotFound If "name" is already taken, GenericError with an
3240 explanation
3241 Since: 2.4
3243 Example:
3245 -> { "execute": "block-dirty-bitmap-add",
3247 "arguments": { "node": "drive0", "name": "bitmap0" } }
3248 <- { "return": {} }
3249 block-dirty-bitmap-remove (Command) Stop write tracking and remove the
3251 dirty bitmap that was created with block-dirty-bitmap-add. If the
3252 bitmap is persistent, remove it from its storage too.
3253 Returns: nothing on success If "node" is not a valid block device or
3255 node, DeviceNotFound If "name" is not found, GenericError with an
3256 explanation if "name" is frozen by an operation, GenericError
3257 Since: 2.4
3259 Example:
3261 -> { "execute": "block-dirty-bitmap-remove",
3263 "arguments": { "node": "drive0", "name": "bitmap0" } }
3264 <- { "return": {} }
3265 block-dirty-bitmap-clear (Command) Clear (reset) a dirty bitmap on the
3267 device, so that an incremental backup from this point in time forward
3268 will only backup clusters modified after this clear operation.
3269 Returns: nothing on success If "node" is not a valid block device,
3271 DeviceNotFound If "name" is not found, GenericError with an explanation
3272 Since: 2.4
3274 Example:
3276 -> { "execute": "block-dirty-bitmap-clear",
3278 "arguments": { "node": "drive0", "name": "bitmap0" } }
3279 <- { "return": {} }
3280 x-block-dirty-bitmap-enable (Command) Enables a dirty bitmap so that
3282 it will begin tracking disk changes.
3283 Returns: nothing on success If "node" is not a valid block device,
3285 DeviceNotFound If "name" is not found, GenericError with an explanation
3286 Since: 3.0
3288 Example:
3290 -> { "execute": "x-block-dirty-bitmap-enable",
3292 "arguments": { "node": "drive0", "name": "bitmap0" } }
3293 <- { "return": {} }
3294 x-block-dirty-bitmap-disable (Command) Disables a dirty bitmap so that
3296 it will stop tracking disk changes.
3297 Returns: nothing on success If "node" is not a valid block device,
3299 DeviceNotFound If "name" is not found, GenericError with an explanation
3300 Since: 3.0
3302 Example:
3304 -> { "execute": "x-block-dirty-bitmap-disable",
3306 "arguments": { "node": "drive0", "name": "bitmap0" } }
3307 <- { "return": {} }
3308 x-block-dirty-bitmap-merge (Command) FIXME: Rename "src_name" and
3310 "dst_name" to src-name and dst-name.
3311 Merge "src_name" dirty bitmap to "dst_name" dirty bitmap. "src_name"
3313 dirty bitmap is unchanged. On error, "dst_name" is unchanged.
3314 Returns: nothing on success If "node" is not a valid block device,
3316 DeviceNotFound If "dst_name" or "src_name" is not found, GenericError
3317 If bitmaps has different sizes or granularities, GenericError
3318 Since: 3.0
3320 Example:
3322 -> { "execute": "x-block-dirty-bitmap-merge",
3324 "arguments": { "node": "drive0", "dst_name": "bitmap0",
3325 "src_name": "bitmap1" } }
3326 <- { "return": {} }
3327 BlockDirtyBitmapSha256 (Object)
3329 SHA256 hash of dirty bitmap data
3331 Members:
3333 "sha256: string"
3335 ASCII representation of SHA256 bitmap hash
3336 Since: 2.10
3338 x-debug-block-dirty-bitmap-sha256 (Command) Get bitmap SHA256
3340 Returns: BlockDirtyBitmapSha256 on success If "node" is not a valid
3342 block device, DeviceNotFound If "name" is not found or if hashing has
3343 failed, GenericError with an explanation
3344 Since: 2.10
3346 blockdev-mirror (Command) Start mirroring a block device's writes to a
3348 new destination.
3349 Arguments:
3351 "job-id: string" (optional)
3353 identifier for the newly-created block job. If omitted, the device
3354 name will be used. (Since 2.7)
3355 "device: string"
3357 The device name or node-name of a root node whose writes should be
3358 mirrored.
3359 "target: string"
3361 the id or node-name of the block device to mirror to. This mustn't
3362 be attached to guest.
3363 "replaces: string" (optional)
3365 with sync=full graph node name to be replaced by the new image when
3366 a whole image copy is done. This can be used to repair broken
3367 Quorum files.
3368 "speed: int" (optional)
3370 the maximum speed, in bytes per second
3371 "sync: MirrorSyncMode"
3373 what parts of the disk image should be copied to the destination
3374 (all the disk, only the sectors allocated in the topmost image, or
3375 only new I/O).
3376 "granularity: int" (optional)
3378 granularity of the dirty bitmap, default is 64K if the image format
3379 doesn't have clusters, 4K if the clusters are smaller than that,
3380 else the cluster size. Must be a power of 2 between 512 and 64M
3381 "buf-size: int" (optional)
3383 maximum amount of data in flight from source to target
3384 "on-source-error: BlockdevOnError" (optional)
3386 the action to take on an error on the source, default 'report'.
3387 'stop' and 'enospc' can only be used if the block device supports
3388 io-status (see BlockInfo).
3389 "on-target-error: BlockdevOnError" (optional)
3391 the action to take on an error on the target, default 'report' (no
3392 limitations, since this applies to a different block device than
3393 "device").
3394 "filter-node-name: string" (optional)
3396 the node name that should be assigned to the filter driver that the
3397 mirror job inserts into the graph above "device". If this option is
3398 not given, a node name is autogenerated. (Since: 2.9)
3399 "copy-mode: MirrorCopyMode" (optional)
3401 when to copy data to the destination; defaults to 'background'
3402 (Since: 3.0)
3403 "auto-finalize: boolean" (optional)
3405 When false, this job will wait in a PENDING state after it has
3406 finished its work, waiting for "block-job-finalize" before making
3407 any block graph changes. When true, this job will automatically
3408 perform its abort or commit actions. Defaults to true. (Since 3.1)
3409 "auto-dismiss: boolean" (optional)
3411 When false, this job will wait in a CONCLUDED state after it has
3412 completely ceased all work, and awaits "block-job-dismiss". When
3413 true, this job will automatically disappear from the query list
3414 without user intervention. Defaults to true. (Since 3.1)
3415 Returns: nothing on success.
3417 Since: 2.6
3419 Example:
3421 -> { "execute": "blockdev-mirror",
3423 "arguments": { "device": "ide-hd0",
3424 "target": "target0",
3425 "sync": "full" } }
3426 <- { "return": {} }
3427 block_set_io_throttle (Command) Change I/O throttle limits for a block
3429 drive.
3430 Since QEMU 2.4, each device with I/O limits is member of a throttle
3432 group.
3433 If two or more devices are members of the same group, the limits will
3435 apply to the combined I/O of the whole group in a round-robin fashion.
3436 Therefore, setting new I/O limits to a device will affect the whole
3437 group.
3438 The name of the group can be specified using the 'group' parameter. If
3440 the parameter is unset, it is assumed to be the current group of that
3441 device. If it's not in any group yet, the name of the device will be
3442 used as the name for its group.
3443 The 'group' parameter can also be used to move a device to a different
3445 group. In this case the limits specified in the parameters will be
3446 applied to the new group only.
3447 I/O limits can be disabled by setting all of them to 0. In this case
3449 the device will be removed from its group and the rest of its members
3450 will not be affected. The 'group' parameter is ignored.
3451 Arguments: the members of "BlockIOThrottle"
3453 Returns: Nothing on success If "device" is not a valid block device,
3455 DeviceNotFound
3456 Since: 1.1
3458 Example:
3460 -> { "execute": "block_set_io_throttle",
3462 "arguments": { "id": "virtio-blk-pci0/virtio-backend",
3463 "bps": 0,
3464 "bps_rd": 0,
3465 "bps_wr": 0,
3466 "iops": 512,
3467 "iops_rd": 0,
3468 "iops_wr": 0,
3469 "bps_max": 0,
3470 "bps_rd_max": 0,
3471 "bps_wr_max": 0,
3472 "iops_max": 0,
3473 "iops_rd_max": 0,
3474 "iops_wr_max": 0,
3475 "bps_max_length": 0,
3476 "iops_size": 0 } }
3477 <- { "return": {} }
3478 -> { "execute": "block_set_io_throttle",
3480 "arguments": { "id": "ide0-1-0",
3481 "bps": 1000000,
3482 "bps_rd": 0,
3483 "bps_wr": 0,
3484 "iops": 0,
3485 "iops_rd": 0,
3486 "iops_wr": 0,
3487 "bps_max": 8000000,
3488 "bps_rd_max": 0,
3489 "bps_wr_max": 0,
3490 "iops_max": 0,
3491 "iops_rd_max": 0,
3492 "iops_wr_max": 0,
3493 "bps_max_length": 60,
3494 "iops_size": 0 } }
3495 <- { "return": {} }
3496 BlockIOThrottle (Object)
3498 A set of parameters describing block throttling.
3500 Members:
3502 "device: string" (optional)
3504 Block device name (deprecated, use "id" instead)
3505 "id: string" (optional)
3507 The name or QOM path of the guest device (since: 2.8)
3508 "bps: int"
3510 total throughput limit in bytes per second
3511 "bps_rd: int"
3513 read throughput limit in bytes per second
3514 "bps_wr: int"
3516 write throughput limit in bytes per second
3517 "iops: int"
3519 total I/O operations per second
3520 "iops_rd: int"
3522 read I/O operations per second
3523 "iops_wr: int"
3525 write I/O operations per second
3526 "bps_max: int" (optional)
3528 total throughput limit during bursts, in bytes (Since 1.7)
3529 "bps_rd_max: int" (optional)
3531 read throughput limit during bursts, in bytes (Since 1.7)
3532 "bps_wr_max: int" (optional)
3534 write throughput limit during bursts, in bytes (Since 1.7)
3535 "iops_max: int" (optional)
3537 total I/O operations per second during bursts, in bytes (Since 1.7)
3538 "iops_rd_max: int" (optional)
3540 read I/O operations per second during bursts, in bytes (Since 1.7)
3541 "iops_wr_max: int" (optional)
3543 write I/O operations per second during bursts, in bytes (Since 1.7)
3544 "bps_max_length: int" (optional)
3546 maximum length of the "bps_max" burst period, in seconds. It must
3547 only be set if "bps_max" is set as well. Defaults to 1. (Since
3548 2.6)
3549 "bps_rd_max_length: int" (optional)
3551 maximum length of the "bps_rd_max" burst period, in seconds. It
3552 must only be set if "bps_rd_max" is set as well. Defaults to 1.
3553 (Since 2.6)
3554 "bps_wr_max_length: int" (optional)
3556 maximum length of the "bps_wr_max" burst period, in seconds. It
3557 must only be set if "bps_wr_max" is set as well. Defaults to 1.
3558 (Since 2.6)
3559 "iops_max_length: int" (optional)
3561 maximum length of the "iops" burst period, in seconds. It must only
3562 be set if "iops_max" is set as well. Defaults to 1. (Since 2.6)
3563 "iops_rd_max_length: int" (optional)
3565 maximum length of the "iops_rd_max" burst period, in seconds. It
3566 must only be set if "iops_rd_max" is set as well. Defaults to 1.
3567 (Since 2.6)
3568 "iops_wr_max_length: int" (optional)
3570 maximum length of the "iops_wr_max" burst period, in seconds. It
3571 must only be set if "iops_wr_max" is set as well. Defaults to 1.
3572 (Since 2.6)
3573 "iops_size: int" (optional)
3575 an I/O size in bytes (Since 1.7)
3576 "group: string" (optional)
3578 throttle group name (Since 2.4)
3579 Since: 1.1
3581 ThrottleLimits (Object)
3583 Limit parameters for throttling. Since some limit combinations are
3585 illegal, limits should always be set in one transaction. All fields are
3586 optional. When setting limits, if a field is missing the current value
3587 is not changed.
3588 Members:
3590 "iops-total: int" (optional)
3592 limit total I/O operations per second
3593 "iops-total-max: int" (optional)
3595 I/O operations burst
3596 "iops-total-max-length: int" (optional)
3598 length of the iops-total-max burst period, in seconds It must only
3599 be set if "iops-total-max" is set as well.
3600 "iops-read: int" (optional)
3602 limit read operations per second
3603 "iops-read-max: int" (optional)
3605 I/O operations read burst
3606 "iops-read-max-length: int" (optional)
3608 length of the iops-read-max burst period, in seconds It must only
3609 be set if "iops-read-max" is set as well.
3610 "iops-write: int" (optional)
3612 limit write operations per second
3613 "iops-write-max: int" (optional)
3615 I/O operations write burst
3616 "iops-write-max-length: int" (optional)
3618 length of the iops-write-max burst period, in seconds It must only
3619 be set if "iops-write-max" is set as well.
3620 "bps-total: int" (optional)
3622 limit total bytes per second
3623 "bps-total-max: int" (optional)
3625 total bytes burst
3626 "bps-total-max-length: int" (optional)
3628 length of the bps-total-max burst period, in seconds. It must only
3629 be set if "bps-total-max" is set as well.
3630 "bps-read: int" (optional)
3632 limit read bytes per second
3633 "bps-read-max: int" (optional)
3635 total bytes read burst
3636 "bps-read-max-length: int" (optional)
3638 length of the bps-read-max burst period, in seconds It must only be
3639 set if "bps-read-max" is set as well.
3640 "bps-write: int" (optional)
3642 limit write bytes per second
3643 "bps-write-max: int" (optional)
3645 total bytes write burst
3646 "bps-write-max-length: int" (optional)
3648 length of the bps-write-max burst period, in seconds It must only
3649 be set if "bps-write-max" is set as well.
3650 "iops-size: int" (optional)
3652 when limiting by iops max size of an I/O in bytes
3653 Since: 2.11
3655 block-stream (Command) Copy data from a backing file into a block
3657 device.
3658 The block streaming operation is performed in the background until the
3660 entire backing file has been copied. This command returns immediately
3661 once streaming has started. The status of ongoing block streaming
3662 operations can be checked with query-block-jobs. The operation can be
3663 stopped before it has completed using the block-job-cancel command.
3664 The node that receives the data is called the top image, can be located
3666 in any part of the chain (but always above the base image; see below)
3667 and can be specified using its device or node name. Earlier qemu
3668 versions only allowed 'device' to name the top level node; presence of
3669 the 'base-node' parameter during introspection can be used as a witness
3670 of the enhanced semantics of 'device'.
3671 If a base file is specified then sectors are not copied from that base
3673 file and its backing chain. When streaming completes the image file
3674 will have the base file as its backing file. This can be used to
3675 stream a subset of the backing file chain instead of flattening the
3676 entire image.
3677 On successful completion the image file is updated to drop the backing
3679 file and the BLOCK_JOB_COMPLETED event is emitted.
3680 Arguments:
3682 "job-id: string" (optional)
3684 identifier for the newly-created block job. If omitted, the device
3685 name will be used. (Since 2.7)
3686 "device: string"
3688 the device or node name of the top image
3689 "base: string" (optional)
3691 the common backing file name. It cannot be set if "base-node" is
3692 also set.
3693 "base-node: string" (optional)
3695 the node name of the backing file. It cannot be set if "base" is
3696 also set. (Since 2.8)
3697 "backing-file: string" (optional)
3699 The backing file string to write into the top image. This filename
3700 is not validated.
3701 If a pathname string is such that it cannot be resolved by QEMU,
3703 that means that subsequent QMP or HMP commands must use node-names
3704 for the image in question, as filename lookup methods will fail.
3705 If not specified, QEMU will automatically determine the backing
3707 file string to use, or error out if there is no obvious choice.
3708 Care should be taken when specifying the string, to specify a valid
3709 filename or protocol. (Since 2.1)
3710 "speed: int" (optional)
3712 the maximum speed, in bytes per second
3713 "on-error: BlockdevOnError" (optional)
3715 the action to take on an error (default report). 'stop' and
3716 'enospc' can only be used if the block device supports io-status
3717 (see BlockInfo). Since 1.3.
3718 "auto-finalize: boolean" (optional)
3720 When false, this job will wait in a PENDING state after it has
3721 finished its work, waiting for "block-job-finalize" before making
3722 any block graph changes. When true, this job will automatically
3723 perform its abort or commit actions. Defaults to true. (Since 3.1)
3724 "auto-dismiss: boolean" (optional)
3726 When false, this job will wait in a CONCLUDED state after it has
3727 completely ceased all work, and awaits "block-job-dismiss". When
3728 true, this job will automatically disappear from the query list
3729 without user intervention. Defaults to true. (Since 3.1)
3730 Returns: Nothing on success. If "device" does not exist,
3732 DeviceNotFound.
3733 Since: 1.1
3735 Example:
3737 -> { "execute": "block-stream",
3739 "arguments": { "device": "virtio0",
3740 "base": "/tmp/master.qcow2" } }
3741 <- { "return": {} }
3742 block-job-set-speed (Command) Set maximum speed for a background block
3744 operation.
3745 This command can only be issued when there is an active block job.
3747 Throttling can be disabled by setting the speed to 0.
3749 Arguments:
3751 "device: string"
3753 The job identifier. This used to be a device name (hence the name
3754 of the parameter), but since QEMU 2.7 it can have other values.
3755 "speed: int"
3757 the maximum speed, in bytes per second, or 0 for unlimited.
3758 Defaults to 0.
3759 Returns: Nothing on success If no background operation is active on
3761 this device, DeviceNotActive
3762 Since: 1.1
3764 block-job-cancel (Command) Stop an active background block operation.
3766 This command returns immediately after marking the active background
3768 block operation for cancellation. It is an error to call this command
3769 if no operation is in progress.
3770 The operation will cancel as soon as possible and then emit the
3772 BLOCK_JOB_CANCELLED event. Before that happens the job is still
3773 visible when enumerated using query-block-jobs.
3774 Note that if you issue 'block-job-cancel' after 'drive-mirror' has
3776 indicated (via the event BLOCK_JOB_READY) that the source and
3777 destination are synchronized, then the event triggered by this command
3778 changes to BLOCK_JOB_COMPLETED, to indicate that the mirroring has
3779 ended and the destination now has a point-in-time copy tied to the time
3780 of the cancellation.
3781 For streaming, the image file retains its backing file unless the
3783 streaming operation happens to complete just as it is being cancelled.
3784 A new streaming operation can be started at a later time to finish
3785 copying all data from the backing file.
3786 Arguments:
3788 "device: string"
3790 The job identifier. This used to be a device name (hence the name
3791 of the parameter), but since QEMU 2.7 it can have other values.
3792 "force: boolean" (optional)
3794 If true, and the job has already emitted the event BLOCK_JOB_READY,
3795 abandon the job immediately (even if it is paused) instead of
3796 waiting for the destination to complete its final synchronization
3797 (since 1.3)
3798 Returns: Nothing on success If no background operation is active on
3800 this device, DeviceNotActive
3801 Since: 1.1
3803 block-job-pause (Command) Pause an active background block operation.
3805 This command returns immediately after marking the active background
3807 block operation for pausing. It is an error to call this command if no
3808 operation is in progress or if the job is already paused.
3809 The operation will pause as soon as possible. No event is emitted when
3811 the operation is actually paused. Cancelling a paused job
3812 automatically resumes it.
3813 Arguments:
3815 "device: string"
3817 The job identifier. This used to be a device name (hence the name
3818 of the parameter), but since QEMU 2.7 it can have other values.
3819 Returns: Nothing on success If no background operation is active on
3821 this device, DeviceNotActive
3822 Since: 1.3
3824 block-job-resume (Command) Resume an active background block
3826 operation.
3827 This command returns immediately after resuming a paused background
3829 block operation. It is an error to call this command if no operation
3830 is in progress or if the job is not paused.
3831 This command also clears the error status of the job.
3833 Arguments:
3835 "device: string"
3837 The job identifier. This used to be a device name (hence the name
3838 of the parameter), but since QEMU 2.7 it can have other values.
3839 Returns: Nothing on success If no background operation is active on
3841 this device, DeviceNotActive
3842 Since: 1.3
3844 block-job-complete (Command) Manually trigger completion of an active
3846 background block operation. This is supported for drive mirroring,
3847 where it also switches the device to write to the target path only.
3848 The ability to complete is signaled with a BLOCK_JOB_READY event.
3849 This command completes an active background block operation
3851 synchronously. The ordering of this command's return with the
3852 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
3853 occurs during the processing of this command: 1) the command itself
3854 will fail; 2) the error will be processed according to the
3855 rerror/werror arguments that were specified when starting the
3856 operation.
3857 A cancelled or paused job cannot be completed.
3859 Arguments:
3861 "device: string"
3863 The job identifier. This used to be a device name (hence the name
3864 of the parameter), but since QEMU 2.7 it can have other values.
3865 Returns: Nothing on success If no background operation is active on
3867 this device, DeviceNotActive
3868 Since: 1.3
3870 block-job-dismiss (Command) For jobs that have already concluded,
3872 remove them from the block-job-query list. This command only needs to
3873 be run for jobs which were started with QEMU 2.12+ job lifetime
3874 management semantics.
3875 This command will refuse to operate on any job that has not yet reached
3877 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
3878 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
3879 still need to be used as appropriate.
3880 Arguments:
3882 "id: string"
3884 The job identifier.
3885 Returns: Nothing on success
3887 Since: 2.12
3889 block-job-finalize (Command) Once a job that has manual=true reaches
3891 the pending state, it can be instructed to finalize any graph changes
3892 and do any necessary cleanup via this command. For jobs in a
3893 transaction, instructing one job to finalize will force ALL jobs in the
3894 transaction to finalize, so it is only necessary to instruct a single
3895 member job to finalize.
3896 Arguments:
3898 "id: string"
3900 The job identifier.
3901 Returns: Nothing on success
3903 Since: 2.12
3905 BlockdevDiscardOptions (Enum)
3907 Determines how to handle discard requests.
3909 Values:
3911 "ignore"
3913 Ignore the request
3914 "unmap"
3916 Forward as an unmap request
3917 Since: 2.9
3919 BlockdevDetectZeroesOptions (Enum)
3921 Describes the operation mode for the automatic conversion of plain zero
3923 writes by the OS to driver specific optimized zero write commands.
3924 Values:
3926 "off"
3928 Disabled (default)
3929 "on"
3931 Enabled
3932 "unmap"
3934 Enabled and even try to unmap blocks if possible. This requires
3935 also that "BlockdevDiscardOptions" is set to unmap for this device.
3936 Since: 2.1
3938 BlockdevAioOptions (Enum)
3940 Selects the AIO backend to handle I/O requests
3942 Values:
3944 "threads"
3946 Use qemu's thread pool
3947 "native"
3949 Use native AIO backend (only Linux and Windows)
3950 Since: 2.9
3952 BlockdevCacheOptions (Object)
3954 Includes cache-related options for block devices
3956 Members:
3958 "direct: boolean" (optional)
3960 enables use of O_DIRECT (bypass the host page cache; default:
3961 false)
3962 "no-flush: boolean" (optional)
3964 ignore any flush requests for the device (default: false)
3965 Since: 2.9
3967 BlockdevDriver (Enum)
3969 Drivers that are supported in block device operations.
3971 Values:
3973 "vxhs"
3975 Since 2.10
3976 "throttle"
3978 Since 2.11
3979 "nvme"
3981 Since 2.12
3982 "copy-on-read"
3984 Since 3.0
3985 "blklogwrites"
3987 Since 3.0
3988 "blkdebug"
3990 Not documented
3991 "blkverify"
3993 Not documented
3994 "bochs"
3996 Not documented
3997 "cloop"
3999 Not documented
4000 "dmg"
4002 Not documented
4003 "file"
4005 Not documented
4006 "ftp"
4008 Not documented
4009 "ftps"
4011 Not documented
4012 "gluster"
4014 Not documented
4015 "host_cdrom"
4017 Not documented
4018 "host_device"
4020 Not documented
4021 "http"
4023 Not documented
4024 "https"
4026 Not documented
4027 "iscsi"
4029 Not documented
4030 "luks"
4032 Not documented
4033 "nbd"
4035 Not documented
4036 "nfs"
4038 Not documented
4039 "null-aio"
4041 Not documented
4042 "null-co"
4044 Not documented
4045 "parallels"
4047 Not documented
4048 "qcow"
4050 Not documented
4051 "qcow2"
4053 Not documented
4054 "qed"
4056 Not documented
4057 "quorum"
4059 Not documented
4060 "raw"
4062 Not documented
4063 "rbd"
4065 Not documented
4066 "replication"
4068 Not documented
4069 "sheepdog"
4071 Not documented
4072 "ssh"
4074 Not documented
4075 "vdi"
4077 Not documented
4078 "vhdx"
4080 Not documented
4081 "vmdk"
4083 Not documented
4084 "vpc"
4086 Not documented
4087 "vvfat"
4089 Not documented
4090 Since: 2.9
4092 BlockdevOptionsFile (Object)
4094 Driver specific block device options for the file backend.
4096 Members:
4098 "filename: string"
4100 path to the image file
4101 "pr-manager: string" (optional)
4103 the id for the object that will handle persistent reservations for
4104 this device (default: none, forward the commands via SG_IO; since
4105 2.11)
4106 "aio: BlockdevAioOptions" (optional)
4108 AIO backend (default: threads) (since: 2.8)
4109 "locking: OnOffAuto" (optional)
4111 whether to enable file locking. If set to 'auto', only enable when
4112 Open File Descriptor (OFD) locking API is available (default: auto,
4113 since 2.10)
4114 "x-check-cache-dropped: boolean" (optional)
4116 whether to check that page cache was dropped on live migration.
4117 May cause noticeable delays if the image file is large, do not use
4118 in production. (default: off) (since: 3.0)
4119 Since: 2.9
4121 BlockdevOptionsNull (Object)
4123 Driver specific block device options for the null backend.
4125 Members:
4127 "size: int" (optional)
4129 size of the device in bytes.
4130 "latency-ns: int" (optional)
4132 emulated latency (in nanoseconds) in processing requests. Default
4133 to zero which completes requests immediately. (Since 2.4)
4134 Since: 2.9
4136 BlockdevOptionsNVMe (Object)
4138 Driver specific block device options for the NVMe backend.
4140 Members:
4142 "device: string"
4144 controller address of the NVMe device.
4145 "namespace: int"
4147 namespace number of the device, starting from 1.
4148 Since: 2.12
4150 BlockdevOptionsVVFAT (Object)
4152 Driver specific block device options for the vvfat protocol.
4154 Members:
4156 "dir: string"
4158 directory to be exported as FAT image
4159 "fat-type: int" (optional)
4161 FAT type: 12, 16 or 32
4162 "floppy: boolean" (optional)
4164 whether to export a floppy image (true) or partitioned hard disk
4165 (false; default)
4166 "label: string" (optional)
4168 set the volume label, limited to 11 bytes. FAT16 and FAT32
4169 traditionally have some restrictions on labels, which are ignored
4170 by most operating systems. Defaults to "QEMU VVFAT". (since 2.4)
4171 "rw: boolean" (optional)
4173 whether to allow write operations (default: false)
4174 Since: 2.9
4176 BlockdevOptionsGenericFormat (Object)
4178 Driver specific block device options for image format that have no
4180 option besides their data source.
4181 Members:
4183 "file: BlockdevRef"
4185 reference to or definition of the data source block device
4186 Since: 2.9
4188 BlockdevOptionsLUKS (Object)
4190 Driver specific block device options for LUKS.
4192 Members:
4194 "key-secret: string" (optional)
4196 the ID of a QCryptoSecret object providing the decryption key
4197 (since 2.6). Mandatory except when doing a metadata-only probe of
4198 the image.
4199 The members of "BlockdevOptionsGenericFormat"
4201 Since: 2.9
4203 BlockdevOptionsGenericCOWFormat (Object)
4205 Driver specific block device options for image format that have no
4207 option besides their data source and an optional backing file.
4208 Members:
4210 "backing: BlockdevRefOrNull" (optional)
4212 reference to or definition of the backing file block device, null
4213 disables the backing file entirely. Defaults to the backing file
4214 stored the image file.
4215 The members of "BlockdevOptionsGenericFormat"
4217 Since: 2.9
4219 Qcow2OverlapCheckMode (Enum)
4221 General overlap check modes.
4223 Values:
4225 "none"
4227 Do not perform any checks
4228 "constant"
4230 Perform only checks which can be done in constant time and without
4231 reading anything from disk
4232 "cached"
4234 Perform only checks which can be done without reading anything from
4235 disk
4236 "all"
4238 Perform all available overlap checks
4239 Since: 2.9
4241 Qcow2OverlapCheckFlags (Object)
4243 Structure of flags for each metadata structure. Setting a field to
4245 'true' makes qemu guard that structure against unintended overwriting.
4246 The default value is chosen according to the template given.
4247 Members:
4249 "template: Qcow2OverlapCheckMode" (optional)
4251 Specifies a template mode which can be adjusted using the other
4252 flags, defaults to 'cached'
4253 "bitmap-directory: boolean" (optional)
4255 since 3.0
4256 "main-header: boolean" (optional)
4258 Not documented
4259 "active-l1: boolean" (optional)
4261 Not documented
4262 "active-l2: boolean" (optional)
4264 Not documented
4265 "refcount-table: boolean" (optional)
4267 Not documented
4268 "refcount-block: boolean" (optional)
4270 Not documented
4271 "snapshot-table: boolean" (optional)
4273 Not documented
4274 "inactive-l1: boolean" (optional)
4276 Not documented
4277 "inactive-l2: boolean" (optional)
4279 Not documented
4280 Since: 2.9
4282 Qcow2OverlapChecks (Alternate)
4284 Specifies which metadata structures should be guarded against
4286 unintended overwriting.
4287 Members:
4289 "flags: Qcow2OverlapCheckFlags"
4291 set of flags for separate specification of each metadata structure
4292 type
4293 "mode: Qcow2OverlapCheckMode"
4295 named mode which chooses a specific set of flags
4296 Since: 2.9
4298 BlockdevQcowEncryptionFormat (Enum)
4300 Values:
4302 "aes"
4304 AES-CBC with plain64 initialization vectors
4305 Since: 2.10
4307 BlockdevQcowEncryption (Object)
4309 Members:
4311 "format: BlockdevQcowEncryptionFormat"
4313 Not documented
4314 The members of "QCryptoBlockOptionsQCow" when "format" is "aes"
4316 Since: 2.10
4318 BlockdevOptionsQcow (Object)
4320 Driver specific block device options for qcow.
4322 Members:
4324 "encrypt: BlockdevQcowEncryption" (optional)
4326 Image decryption options. Mandatory for encrypted images, except
4327 when doing a metadata-only probe of the image.
4328 The members of "BlockdevOptionsGenericCOWFormat"
4330 Since: 2.10
4332 BlockdevQcow2EncryptionFormat (Enum)
4334 Values:
4336 "aes"
4338 AES-CBC with plain64 initialization venctors
4339 "luks"
4341 Not documented
4342 Since: 2.10
4344 BlockdevQcow2Encryption (Object)
4346 Members:
4348 "format: BlockdevQcow2EncryptionFormat"
4350 Not documented
4351 The members of "QCryptoBlockOptionsQCow" when "format" is "aes"
4353 The members of "QCryptoBlockOptionsLUKS" when "format" is "luks"
4354 Since: 2.10
4356 BlockdevOptionsQcow2 (Object)
4358 Driver specific block device options for qcow2.
4360 Members:
4362 "lazy-refcounts: boolean" (optional)
4364 whether to enable the lazy refcounts feature (default is taken from
4365 the image file)
4366 "pass-discard-request: boolean" (optional)
4368 whether discard requests to the qcow2 device should be forwarded to
4369 the data source
4370 "pass-discard-snapshot: boolean" (optional)
4372 whether discard requests for the data source should be issued when
4373 a snapshot operation (e.g. deleting a snapshot) frees clusters in
4374 the qcow2 file
4375 "pass-discard-other: boolean" (optional)
4377 whether discard requests for the data source should be issued on
4378 other occasions where a cluster gets freed
4379 "overlap-check: Qcow2OverlapChecks" (optional)
4381 which overlap checks to perform for writes to the image, defaults
4382 to 'cached' (since 2.2)
4383 "cache-size: int" (optional)
4385 the maximum total size of the L2 table and refcount block caches in
4386 bytes (since 2.2)
4387 "l2-cache-size: int" (optional)
4389 the maximum size of the L2 table cache in bytes (since 2.2)
4390 "l2-cache-entry-size: int" (optional)
4392 the size of each entry in the L2 cache in bytes. It must be a power
4393 of two between 512 and the cluster size. The default value is the
4394 cluster size (since 2.12)
4395 "refcount-cache-size: int" (optional)
4397 the maximum size of the refcount block cache in bytes (since 2.2)
4398 "cache-clean-interval: int" (optional)
4400 clean unused entries in the L2 and refcount caches. The interval is
4401 in seconds. The default value is 600 on supporting platforms, and 0
4402 on other platforms. 0 disables this feature. (since 2.5)
4403 "encrypt: BlockdevQcow2Encryption" (optional)
4405 Image decryption options. Mandatory for encrypted images, except
4406 when doing a metadata-only probe of the image. (since 2.10)
4407 The members of "BlockdevOptionsGenericCOWFormat"
4409 Since: 2.9
4411 SshHostKeyCheckMode (Enum)
4413 "none" Don't check the host key at all "hash"
4415 Compare the host key with a given hash "known_hosts" Check the
4416 host key against the known_hosts file
4417 Values:
4419 "none"
4421 Not documented
4422 "hash"
4424 Not documented
4425 "known_hosts"
4427 Not documented
4428 Since: 2.12
4430 SshHostKeyCheckHashType (Enum)
4432 "md5" The given hash is an md5 hash "sha1" The
4434 given hash is an sha1 hash
4435 Values:
4437 "md5"
4439 Not documented
4440 "sha1"
4442 Not documented
4443 Since: 2.12
4445 SshHostKeyHash (Object)
4447 "type" The hash algorithm used for the hash "hash"
4449 The expected hash value
4450 Members:
4452 "type: SshHostKeyCheckHashType"
4454 Not documented
4455 "hash: string"
4457 Not documented
4458 Since: 2.12
4460 SshHostKeyCheck (Object)
4462 Members:
4464 "mode: SshHostKeyCheckMode"
4466 Not documented
4467 The members of "SshHostKeyHash" when "mode" is "hash"
4469 Since: 2.12
4471 BlockdevOptionsSsh (Object)
4473 Members:
4475 "server: InetSocketAddress"
4477 host address
4478 "path: string"
4480 path to the image on the host
4481 "user: string" (optional)
4483 user as which to connect, defaults to current local user name
4484 "host-key-check: SshHostKeyCheck" (optional)
4486 Defines how and what to check the host key against (default:
4487 known_hosts)
4488 Since: 2.9
4490 BlkdebugEvent (Enum)
4492 Trigger events supported by blkdebug.
4494 Values:
4496 "l1_shrink_write_table"
4498 write zeros to the l1 table to shrink image. (since 2.11)
4499 "l1_shrink_free_l2_clusters"
4501 discard the l2 tables. (since 2.11)
4502 "cor_write"
4504 a write due to copy-on-read (since 2.11)
4505 "l1_update"
4507 Not documented
4508 "l1_grow_alloc_table"
4510 Not documented
4511 "l1_grow_write_table"
4513 Not documented
4514 "l1_grow_activate_table"
4516 Not documented
4517 "l2_load"
4519 Not documented
4520 "l2_update"
4522 Not documented
4523 "l2_update_compressed"
4525 Not documented
4526 "l2_alloc_cow_read"
4528 Not documented
4529 "l2_alloc_write"
4531 Not documented
4532 "read_aio"
4534 Not documented
4535 "read_backing_aio"
4537 Not documented
4538 "read_compressed"
4540 Not documented
4541 "write_aio"
4543 Not documented
4544 "write_compressed"
4546 Not documented
4547 "vmstate_load"
4549 Not documented
4550 "vmstate_save"
4552 Not documented
4553 "cow_read"
4555 Not documented
4556 "cow_write"
4558 Not documented
4559 "reftable_load"
4561 Not documented
4562 "reftable_grow"
4564 Not documented
4565 "reftable_update"
4567 Not documented
4568 "refblock_load"
4570 Not documented
4571 "refblock_update"
4573 Not documented
4574 "refblock_update_part"
4576 Not documented
4577 "refblock_alloc"
4579 Not documented
4580 "refblock_alloc_hookup"
4582 Not documented
4583 "refblock_alloc_write"
4585 Not documented
4586 "refblock_alloc_write_blocks"
4588 Not documented
4589 "refblock_alloc_write_table"
4591 Not documented
4592 "refblock_alloc_switch_table"
4594 Not documented
4595 "cluster_alloc"
4597 Not documented
4598 "cluster_alloc_bytes"
4600 Not documented
4601 "cluster_free"
4603 Not documented
4604 "flush_to_os"
4606 Not documented
4607 "flush_to_disk"
4609 Not documented
4610 "pwritev_rmw_head"
4612 Not documented
4613 "pwritev_rmw_after_head"
4615 Not documented
4616 "pwritev_rmw_tail"
4618 Not documented
4619 "pwritev_rmw_after_tail"
4621 Not documented
4622 "pwritev"
4624 Not documented
4625 "pwritev_zero"
4627 Not documented
4628 "pwritev_done"
4630 Not documented
4631 "empty_image_prepare"
4633 Not documented
4634 Since: 2.9
4636 BlkdebugInjectErrorOptions (Object)
4638 Describes a single error injection for blkdebug.
4640 Members:
4642 "event: BlkdebugEvent"
4644 trigger event
4645 "state: int" (optional)
4647 the state identifier blkdebug needs to be in to actually trigger
4648 the event; defaults to "any"
4649 "errno: int" (optional)
4651 error identifier (errno) to be returned; defaults to EIO
4652 "sector: int" (optional)
4654 specifies the sector index which has to be affected in order to
4655 actually trigger the event; defaults to "any sector"
4656 "once: boolean" (optional)
4658 disables further events after this one has been triggered; defaults
4659 to false
4660 "immediately: boolean" (optional)
4662 fail immediately; defaults to false
4663 Since: 2.9
4665 BlkdebugSetStateOptions (Object)
4667 Describes a single state-change event for blkdebug.
4669 Members:
4671 "event: BlkdebugEvent"
4673 trigger event
4674 "state: int" (optional)
4676 the current state identifier blkdebug needs to be in; defaults to
4677 "any"
4678 "new_state: int"
4680 the state identifier blkdebug is supposed to assume if this event
4681 is triggered
4682 Since: 2.9
4684 BlockdevOptionsBlkdebug (Object)
4686 Driver specific block device options for blkdebug.
4688 Members:
4690 "image: BlockdevRef"
4692 underlying raw block device (or image file)
4693 "config: string" (optional)
4695 filename of the configuration file
4696 "align: int" (optional)
4698 required alignment for requests in bytes, must be positive power of
4699 2, or 0 for default
4700 "max-transfer: int" (optional)
4702 maximum size for I/O transfers in bytes, must be positive multiple
4703 of "align" and of the underlying file's request alignment (but need
4704 not be a power of 2), or 0 for default (since 2.10)
4705 "opt-write-zero: int" (optional)
4707 preferred alignment for write zero requests in bytes, must be
4708 positive multiple of "align" and of the underlying file's request
4709 alignment (but need not be a power of 2), or 0 for default (since
4710 2.10)
4711 "max-write-zero: int" (optional)
4713 maximum size for write zero requests in bytes, must be positive
4714 multiple of "align", of "opt-write-zero", and of the underlying
4715 file's request alignment (but need not be a power of 2), or 0 for
4716 default (since 2.10)
4717 "opt-discard: int" (optional)
4719 preferred alignment for discard requests in bytes, must be positive
4720 multiple of "align" and of the underlying file's request alignment
4721 (but need not be a power of 2), or 0 for default (since 2.10)
4722 "max-discard: int" (optional)
4724 maximum size for discard requests in bytes, must be positive
4725 multiple of "align", of "opt-discard", and of the underlying file's
4726 request alignment (but need not be a power of 2), or 0 for default
4727 (since 2.10)
4728 "inject-error: array of BlkdebugInjectErrorOptions" (optional)
4730 array of error injection descriptions
4731 "set-state: array of BlkdebugSetStateOptions" (optional)
4733 array of state-change descriptions
4734 Since: 2.9
4736 BlockdevOptionsBlklogwrites (Object)
4738 Driver specific block device options for blklogwrites.
4740 Members:
4742 "file: BlockdevRef"
4744 block device
4745 "log: BlockdevRef"
4747 block device used to log writes to "file"
4748 "log-sector-size: int" (optional)
4750 sector size used in logging writes to "file", determines
4751 granularity of offsets and sizes of writes (default: 512)
4752 "log-append: boolean" (optional)
4754 append to an existing log (default: false)
4755 "log-super-update-interval: int" (optional)
4757 interval of write requests after which the log super block is
4758 updated to disk (default: 4096)
4759 Since: 3.0
4761 BlockdevOptionsBlkverify (Object)
4763 Driver specific block device options for blkverify.
4765 Members:
4767 "test: BlockdevRef"
4769 block device to be tested
4770 "raw: BlockdevRef"
4772 raw image used for verification
4773 Since: 2.9
4775 QuorumReadPattern (Enum)
4777 An enumeration of quorum read patterns.
4779 Values:
4781 "quorum"
4783 read all the children and do a quorum vote on reads
4784 "fifo"
4786 read only from the first child that has not failed
4787 Since: 2.9
4789 BlockdevOptionsQuorum (Object)
4791 Driver specific block device options for Quorum
4793 Members:
4795 "blkverify: boolean" (optional)
4797 true if the driver must print content mismatch set to false by
4798 default
4799 "children: array of BlockdevRef"
4801 the children block devices to use
4802 "vote-threshold: int"
4804 the vote limit under which a read will fail
4805 "rewrite-corrupted: boolean" (optional)
4807 rewrite corrupted data when quorum is reached (Since 2.1)
4808 "read-pattern: QuorumReadPattern" (optional)
4810 choose read pattern and set to quorum by default (Since 2.2)
4811 Since: 2.9
4813 BlockdevOptionsGluster (Object)
4815 Driver specific block device options for Gluster
4817 Members:
4819 "volume: string"
4821 name of gluster volume where VM image resides
4822 "path: string"
4824 absolute path to image file in gluster volume
4825 "server: array of SocketAddress"
4827 gluster servers description
4828 "debug: int" (optional)
4830 libgfapi log level (default '4' which is Error) (Since 2.8)
4831 "logfile: string" (optional)
4833 libgfapi log file (default /dev/stderr) (Since 2.8)
4834 Since: 2.9
4836 IscsiTransport (Enum)
4838 An enumeration of libiscsi transport types
4840 Values:
4842 "tcp"
4844 Not documented
4845 "iser"
4847 Not documented
4848 Since: 2.9
4850 IscsiHeaderDigest (Enum)
4852 An enumeration of header digests supported by libiscsi
4854 Values:
4856 "crc32c"
4858 Not documented
4859 "none"
4861 Not documented
4862 "crc32c-none"
4864 Not documented
4865 "none-crc32c"
4867 Not documented
4868 Since: 2.9
4870 BlockdevOptionsIscsi (Object)
4872 Members:
4874 "transport: IscsiTransport"
4876 The iscsi transport type
4877 "portal: string"
4879 The address of the iscsi portal
4880 "target: string"
4882 The target iqn name
4883 "lun: int" (optional)
4885 LUN to connect to. Defaults to 0.
4886 "user: string" (optional)
4888 User name to log in with. If omitted, no CHAP authentication is
4889 performed.
4890 "password-secret: string" (optional)
4892 The ID of a QCryptoSecret object providing the password for the
4893 login. This option is required if "user" is specified.
4894 "initiator-name: string" (optional)
4896 The iqn name we want to identify to the target as. If this option
4897 is not specified, an initiator name is generated automatically.
4898 "header-digest: IscsiHeaderDigest" (optional)
4900 The desired header digest. Defaults to none-crc32c.
4901 "timeout: int" (optional)
4903 Timeout in seconds after which a request will timeout. 0 means no
4904 timeout and is the default.
4905 Driver specific block device options for iscsi
4907 Since: 2.9
4909 RbdAuthMode (Enum)
4911 Values:
4913 "cephx"
4915 Not documented
4916 "none"
4918 Not documented
4919 Since: 3.0
4921 BlockdevOptionsRbd (Object)
4923 Members:
4925 "pool: string"
4927 Ceph pool name.
4928 "image: string"
4930 Image name in the Ceph pool.
4931 "conf: string" (optional)
4933 path to Ceph configuration file. Values in the configuration file
4934 will be overridden by options specified via QAPI.
4935 "snapshot: string" (optional)
4937 Ceph snapshot name.
4938 "user: string" (optional)
4940 Ceph id name.
4941 "auth-client-required: array of RbdAuthMode" (optional)
4943 Acceptable authentication modes. This maps to Ceph configuration
4944 option "auth_client_required". (Since 3.0)
4945 "key-secret: string" (optional)
4947 ID of a QCryptoSecret object providing a key for cephx
4948 authentication. This maps to Ceph configuration option "key".
4949 (Since 3.0)
4950 "server: array of InetSocketAddressBase" (optional)
4952 Monitor host address and port. This maps to the "mon_host" Ceph
4953 option.
4954 Since: 2.9
4956 BlockdevOptionsSheepdog (Object)
4958 Driver specific block device options for sheepdog
4960 Members:
4962 "vdi: string"
4964 Virtual disk image name
4965 "server: SocketAddress"
4967 The Sheepdog server to connect to
4968 "snap-id: int" (optional)
4970 Snapshot ID
4971 "tag: string" (optional)
4973 Snapshot tag name
4974 Only one of "snap-id" and "tag" may be present.
4976 Since: 2.9
4978 ReplicationMode (Enum)
4980 An enumeration of replication modes.
4982 Values:
4984 "primary"
4986 Primary mode, the vm's state will be sent to secondary QEMU.
4987 "secondary"
4989 Secondary mode, receive the vm's state from primary QEMU.
4990 Since: 2.9
4992 BlockdevOptionsReplication (Object)
4994 Driver specific block device options for replication
4996 Members:
4998 "mode: ReplicationMode"
5000 the replication mode
5001 "top-id: string" (optional)
5003 In secondary mode, node name or device ID of the root node who owns
5004 the replication node chain. Must not be given in primary mode.
5005 The members of "BlockdevOptionsGenericFormat"
5007 Since: 2.9
5009 NFSTransport (Enum)
5011 An enumeration of NFS transport types
5013 Values:
5015 "inet"
5017 TCP transport
5018 Since: 2.9
5020 NFSServer (Object)
5022 Captures the address of the socket
5024 Members:
5026 "type: NFSTransport"
5028 transport type used for NFS (only TCP supported)
5029 "host: string"
5031 host address for NFS server
5032 Since: 2.9
5034 BlockdevOptionsNfs (Object)
5036 Driver specific block device option for NFS
5038 Members:
5040 "server: NFSServer"
5042 host address
5043 "path: string"
5045 path of the image on the host
5046 "user: int" (optional)
5048 UID value to use when talking to the server (defaults to 65534 on
5049 Windows and getuid() on unix)
5050 "group: int" (optional)
5052 GID value to use when talking to the server (defaults to 65534 on
5053 Windows and getgid() in unix)
5054 "tcp-syn-count: int" (optional)
5056 number of SYNs during the session establishment (defaults to libnfs
5057 default)
5058 "readahead-size: int" (optional)
5060 set the readahead size in bytes (defaults to libnfs default)
5061 "page-cache-size: int" (optional)
5063 set the pagecache size in bytes (defaults to libnfs default)
5064 "debug: int" (optional)
5066 set the NFS debug level (max 2) (defaults to libnfs default)
5067 Since: 2.9
5069 BlockdevOptionsCurlBase (Object)
5071 Driver specific block device options shared by all protocols supported
5073 by the curl backend.
5074 Members:
5076 "url: string"
5078 URL of the image file
5079 "readahead: int" (optional)
5081 Size of the read-ahead cache; must be a multiple of 512 (defaults
5082 to 256 kB)
5083 "timeout: int" (optional)
5085 Timeout for connections, in seconds (defaults to 5)
5086 "username: string" (optional)
5088 Username for authentication (defaults to none)
5089 "password-secret: string" (optional)
5091 ID of a QCryptoSecret object providing a password for
5092 authentication (defaults to no password)
5093 "proxy-username: string" (optional)
5095 Username for proxy authentication (defaults to none)
5096 "proxy-password-secret: string" (optional)
5098 ID of a QCryptoSecret object providing a password for proxy
5099 authentication (defaults to no password)
5100 Since: 2.9
5102 BlockdevOptionsCurlHttp (Object)
5104 Driver specific block device options for HTTP connections over the curl
5106 backend. URLs must start with "http://".
5107 Members:
5109 "cookie: string" (optional)
5111 List of cookies to set; format is "name1=content1; name2=content2;"
5112 as explained by CURLOPT_COOKIE(3). Defaults to no cookies.
5113 "cookie-secret: string" (optional)
5115 ID of a QCryptoSecret object providing the cookie data in a secure
5116 way. See "cookie" for the format. (since 2.10)
5117 The members of "BlockdevOptionsCurlBase"
5119 Since: 2.9
5121 BlockdevOptionsCurlHttps (Object)
5123 Driver specific block device options for HTTPS connections over the
5125 curl backend. URLs must start with "https://".
5126 Members:
5128 "cookie: string" (optional)
5130 List of cookies to set; format is "name1=content1; name2=content2;"
5131 as explained by CURLOPT_COOKIE(3). Defaults to no cookies.
5132 "sslverify: boolean" (optional)
5134 Whether to verify the SSL certificate's validity (defaults to true)
5135 "cookie-secret: string" (optional)
5137 ID of a QCryptoSecret object providing the cookie data in a secure
5138 way. See "cookie" for the format. (since 2.10)
5139 The members of "BlockdevOptionsCurlBase"
5141 Since: 2.9
5143 BlockdevOptionsCurlFtp (Object)
5145 Driver specific block device options for FTP connections over the curl
5147 backend. URLs must start with "ftp://".
5148 Members:
5150 The members of "BlockdevOptionsCurlBase"
5152 Since: 2.9
5154 BlockdevOptionsCurlFtps (Object)
5156 Driver specific block device options for FTPS connections over the curl
5158 backend. URLs must start with "ftps://".
5159 Members:
5161 "sslverify: boolean" (optional)
5163 Whether to verify the SSL certificate's validity (defaults to true)
5164 The members of "BlockdevOptionsCurlBase"
5166 Since: 2.9
5168 BlockdevOptionsNbd (Object)
5170 Driver specific block device options for NBD.
5172 Members:
5174 "server: SocketAddress"
5176 NBD server address
5177 "export: string" (optional)
5179 export name
5180 "tls-creds: string" (optional)
5182 TLS credentials ID
5183 "x-dirty-bitmap: string" (optional)
5185 A "qemu:dirty-bitmap:NAME" string to query in place of traditional
5186 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
5187 the NBD protocol) (since 3.0)
5188 Since: 2.9
5190 BlockdevOptionsRaw (Object)
5192 Driver specific block device options for the raw driver.
5194 Members:
5196 "offset: int" (optional)
5198 position where the block device starts
5199 "size: int" (optional)
5201 the assumed size of the device
5202 The members of "BlockdevOptionsGenericFormat"
5204 Since: 2.9
5206 BlockdevOptionsVxHS (Object)
5208 Driver specific block device options for VxHS
5210 Members:
5212 "vdisk-id: string"
5214 UUID of VxHS volume
5215 "server: InetSocketAddressBase"
5217 vxhs server IP, port
5218 "tls-creds: string" (optional)
5220 TLS credentials ID
5221 Since: 2.10
5223 BlockdevOptionsThrottle (Object)
5225 Driver specific block device options for the throttle driver
5227 Members:
5229 "throttle-group: string"
5231 the name of the throttle-group object to use. It must already
5232 exist.
5233 "file: BlockdevRef"
5235 reference to or definition of the data source block device
5236 Since: 2.11
5238 BlockdevOptions (Object)
5240 Options for creating a block device. Many options are available for
5242 all block devices, independent of the block driver:
5243 Members:
5245 "driver: BlockdevDriver"
5247 block driver name
5248 "node-name: string" (optional)
5250 the node name of the new node (Since 2.0). This option is required
5251 on the top level of blockdev-add. Valid node names start with an
5252 alphabetic character and may contain only alphanumeric characters,
5253 '-', '.' and '_'. Their maximum length is 31 characters.
5254 "discard: BlockdevDiscardOptions" (optional)
5256 discard-related options (default: ignore)
5257 "cache: BlockdevCacheOptions" (optional)
5259 cache-related options
5260 "read-only: boolean" (optional)
5262 whether the block device should be read-only (default: false).
5263 Note that some block drivers support only read-only access, either
5264 generally or in certain configurations. In this case, the default
5265 value does not work and the option must be specified explicitly.
5266 "auto-read-only: boolean" (optional)
5268 if true and "read-only" is false, QEMU may automatically decide not
5269 to open the image read-write as requested, but fall back to read-
5270 only instead (and switch between the modes later), e.g. depending
5271 on whether the image file is writable or whether a writing user is
5272 attached to the node (default: false, since 3.1)
5273 "detect-zeroes: BlockdevDetectZeroesOptions" (optional)
5275 detect and optimize zero writes (Since 2.1) (default: off)
5276 "force-share: boolean" (optional)
5278 force share all permission on added nodes. Requires
5279 read-only=true. (Since 2.10)
5280 The members of "BlockdevOptionsBlkdebug" when "driver" is "blkdebug"
5282 The members of "BlockdevOptionsBlklogwrites" when "driver" is
5283 "blklogwrites"
5284 The members of "BlockdevOptionsBlkverify" when "driver" is "blkverify"
5285 The members of "BlockdevOptionsGenericFormat" when "driver" is "bochs"
5286 The members of "BlockdevOptionsGenericFormat" when "driver" is "cloop"
5287 The members of "BlockdevOptionsGenericFormat" when "driver" is "copy-
5288 on-read"
5289 The members of "BlockdevOptionsGenericFormat" when "driver" is "dmg"
5290 The members of "BlockdevOptionsFile" when "driver" is "file"
5291 The members of "BlockdevOptionsCurlFtp" when "driver" is "ftp"
5292 The members of "BlockdevOptionsCurlFtps" when "driver" is "ftps"
5293 The members of "BlockdevOptionsGluster" when "driver" is "gluster"
5294 The members of "BlockdevOptionsFile" when "driver" is "host_cdrom"
5295 The members of "BlockdevOptionsFile" when "driver" is "host_device"
5296 The members of "BlockdevOptionsCurlHttp" when "driver" is "http"
5297 The members of "BlockdevOptionsCurlHttps" when "driver" is "https"
5298 The members of "BlockdevOptionsIscsi" when "driver" is "iscsi"
5299 The members of "BlockdevOptionsLUKS" when "driver" is "luks"
5300 The members of "BlockdevOptionsNbd" when "driver" is "nbd"
5301 The members of "BlockdevOptionsNfs" when "driver" is "nfs"
5302 The members of "BlockdevOptionsNull" when "driver" is "null-aio"
5303 The members of "BlockdevOptionsNull" when "driver" is "null-co"
5304 The members of "BlockdevOptionsNVMe" when "driver" is "nvme"
5305 The members of "BlockdevOptionsGenericFormat" when "driver" is
5306 "parallels"
5307 The members of "BlockdevOptionsQcow2" when "driver" is "qcow2"
5308 The members of "BlockdevOptionsQcow" when "driver" is "qcow"
5309 The members of "BlockdevOptionsGenericCOWFormat" when "driver" is "qed"
5310 The members of "BlockdevOptionsQuorum" when "driver" is "quorum"
5311 The members of "BlockdevOptionsRaw" when "driver" is "raw"
5312 The members of "BlockdevOptionsRbd" when "driver" is "rbd"
5313 The members of "BlockdevOptionsReplication" when "driver" is
5314 "replication"
5315 The members of "BlockdevOptionsSheepdog" when "driver" is "sheepdog"
5316 The members of "BlockdevOptionsSsh" when "driver" is "ssh"
5317 The members of "BlockdevOptionsThrottle" when "driver" is "throttle"
5318 The members of "BlockdevOptionsGenericFormat" when "driver" is "vdi"
5319 The members of "BlockdevOptionsGenericFormat" when "driver" is "vhdx"
5320 The members of "BlockdevOptionsGenericCOWFormat" when "driver" is
5321 "vmdk"
5322 The members of "BlockdevOptionsGenericFormat" when "driver" is "vpc"
5323 The members of "BlockdevOptionsVVFAT" when "driver" is "vvfat"
5324 The members of "BlockdevOptionsVxHS" when "driver" is "vxhs"
5325 Remaining options are determined by the block driver.
5327 Since: 2.9
5329 BlockdevRef (Alternate)
5331 Reference to a block device.
5333 Members:
5335 "definition: BlockdevOptions"
5337 defines a new block device inline
5338 "reference: string"
5340 references the ID of an existing block device
5341 Since: 2.9
5343 BlockdevRefOrNull (Alternate)
5345 Reference to a block device.
5347 Members:
5349 "definition: BlockdevOptions"
5351 defines a new block device inline
5352 "reference: string"
5354 references the ID of an existing block device. An empty string
5355 means that no block device should be referenced. Deprecated; use
5356 null instead.
5357 "null: null"
5359 No block device should be referenced (since 2.10)
5360 Since: 2.9
5362 blockdev-add (Command) Creates a new block device. If the "id" option
5364 is given at the top level, a BlockBackend will be created; otherwise,
5365 "node-name" is mandatory at the top level and no BlockBackend will be
5366 created.
5367 Arguments: the members of "BlockdevOptions"
5369 Since: 2.9
5371 Example:
5373 1.
5375 -> { "execute": "blockdev-add",
5376 "arguments": {
5377 "driver": "qcow2",
5378 "node-name": "test1",
5379 "file": {
5380 "driver": "file",
5381 "filename": "test.qcow2"
5382 }
5383 }
5384 }
5385 <- { "return": {} }
5386 2.
5388 -> { "execute": "blockdev-add",
5389 "arguments": {
5390 "driver": "qcow2",
5391 "node-name": "node0",
5392 "discard": "unmap",
5393 "cache": {
5394 "direct": true
5395 },
5396 "file": {
5397 "driver": "file",
5398 "filename": "/tmp/test.qcow2"
5399 },
5400 "backing": {
5401 "driver": "raw",
5402 "file": {
5403 "driver": "file",
5404 "filename": "/dev/fdset/4"
5405 }
5406 }
5407 }
5408 }
5409 <- { "return": {} }
5411 blockdev-del (Command) Deletes a block device that has been added
5413 using blockdev-add. The command will fail if the node is attached to a
5414 device or is otherwise being used.
5415 Arguments:
5417 "node-name: string"
5419 Name of the graph node to delete.
5420 Since: 2.9
5422 Example:
5424 -> { "execute": "blockdev-add",
5426 "arguments": {
5427 "driver": "qcow2",
5428 "node-name": "node0",
5429 "file": {
5430 "driver": "file",
5431 "filename": "test.qcow2"
5432 }
5433 }
5434 }
5435 <- { "return": {} }
5436 -> { "execute": "blockdev-del",
5438 "arguments": { "node-name": "node0" }
5439 }
5440 <- { "return": {} }
5441 BlockdevCreateOptionsFile (Object)
5443 Driver specific image creation options for file.
5445 "filename" Filename for the new image file "size"
5447 Size of the virtual disk in bytes "preallocation" Preallocation mode
5448 for the new image (default: off) "nocow" Turn off copy-on-
5449 write (valid only on btrfs; default: off)
5450 Members:
5452 "filename: string"
5454 Not documented
5455 "size: int"
5457 Not documented
5458 "preallocation: PreallocMode" (optional)
5460 Not documented
5461 "nocow: boolean" (optional)
5463 Not documented
5464 Since: 2.12
5466 BlockdevCreateOptionsGluster (Object)
5468 Driver specific image creation options for gluster.
5470 "location" Where to store the new image file "size"
5472 Size of the virtual disk in bytes "preallocation" Preallocation mode
5473 for the new image (default: off)
5474 Members:
5476 "location: BlockdevOptionsGluster"
5478 Not documented
5479 "size: int"
5481 Not documented
5482 "preallocation: PreallocMode" (optional)
5484 Not documented
5485 Since: 2.12
5487 BlockdevCreateOptionsLUKS (Object)
5489 Driver specific image creation options for LUKS.
5491 "file" Node to create the image format on "size"
5493 Size of the virtual disk in bytes
5494 Members:
5496 "file: BlockdevRef"
5498 Not documented
5499 "size: int"
5501 Not documented
5502 The members of "QCryptoBlockCreateOptionsLUKS"
5504 Since: 2.12
5506 BlockdevCreateOptionsNfs (Object)
5508 Driver specific image creation options for NFS.
5510 "location" Where to store the new image file "size"
5512 Size of the virtual disk in bytes
5513 Members:
5515 "location: BlockdevOptionsNfs"
5517 Not documented
5518 "size: int"
5520 Not documented
5521 Since: 2.12
5523 BlockdevCreateOptionsParallels (Object)
5525 Driver specific image creation options for parallels.
5527 "file" Node to create the image format on "size"
5529 Size of the virtual disk in bytes "cluster-size" Cluster size in
5530 bytes (default: 1 MB)
5531 Members:
5533 "file: BlockdevRef"
5535 Not documented
5536 "size: int"
5538 Not documented
5539 "cluster-size: int" (optional)
5541 Not documented
5542 Since: 2.12
5544 BlockdevCreateOptionsQcow (Object)
5546 Driver specific image creation options for qcow.
5548 "file" Node to create the image format on "size"
5550 Size of the virtual disk in bytes "backing-file" File name of the
5551 backing file if a backing file should be used "encrypt"
5552 Encryption options if the image should be encrypted
5553 Members:
5555 "file: BlockdevRef"
5557 Not documented
5558 "size: int"
5560 Not documented
5561 "backing-file: string" (optional)
5563 Not documented
5564 "encrypt: QCryptoBlockCreateOptions" (optional)
5566 Not documented
5567 Since: 2.12
5569 BlockdevQcow2Version (Enum)
5571 Values:
5573 "v2"
5575 The original QCOW2 format as introduced in qemu 0.10 (version 2)
5576 "v3"
5578 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
5579 Since: 2.12
5581 BlockdevCreateOptionsQcow2 (Object)
5583 Driver specific image creation options for qcow2.
5585 "file" Node to create the image format on "size"
5587 Size of the virtual disk in bytes "version" Compatibility
5588 level (default: v3) "backing-file" File name of the backing file if
5589 a backing file should be used "backing-fmt" Name of the block
5590 driver to use for the backing file "encrypt" Encryption
5591 options if the image should be encrypted "cluster-size" qcow2
5592 cluster size in bytes (default: 65536) "preallocation" Preallocation
5593 mode for the new image (default: off) "lazy-refcounts" True if
5594 refcounts may be updated lazily (default: off) "refcount-bits" Width
5595 of reference counts in bits (default: 16)
5596 Members:
5598 "file: BlockdevRef"
5600 Not documented
5601 "size: int"
5603 Not documented
5604 "version: BlockdevQcow2Version" (optional)
5606 Not documented
5607 "backing-file: string" (optional)
5609 Not documented
5610 "backing-fmt: BlockdevDriver" (optional)
5612 Not documented
5613 "encrypt: QCryptoBlockCreateOptions" (optional)
5615 Not documented
5616 "cluster-size: int" (optional)
5618 Not documented
5619 "preallocation: PreallocMode" (optional)
5621 Not documented
5622 "lazy-refcounts: boolean" (optional)
5624 Not documented
5625 "refcount-bits: int" (optional)
5627 Not documented
5628 Since: 2.12
5630 BlockdevCreateOptionsQed (Object)
5632 Driver specific image creation options for qed.
5634 "file" Node to create the image format on "size"
5636 Size of the virtual disk in bytes "backing-file" File name of the
5637 backing file if a backing file should be used "backing-fmt" Name
5638 of the block driver to use for the backing file "cluster-size"
5639 Cluster size in bytes (default: 65536) "table-size" L1/L2 table
5640 size (in clusters)
5641 Members:
5643 "file: BlockdevRef"
5645 Not documented
5646 "size: int"
5648 Not documented
5649 "backing-file: string" (optional)
5651 Not documented
5652 "backing-fmt: BlockdevDriver" (optional)
5654 Not documented
5655 "cluster-size: int" (optional)
5657 Not documented
5658 "table-size: int" (optional)
5660 Not documented
5661 Since: 2.12
5663 BlockdevCreateOptionsRbd (Object)
5665 Driver specific image creation options for rbd/Ceph.
5667 "location" Where to store the new image file. This location
5669 cannot point to a snapshot. "size" Size of the virtual
5670 disk in bytes "cluster-size" RBD object size
5671 Members:
5673 "location: BlockdevOptionsRbd"
5675 Not documented
5676 "size: int"
5678 Not documented
5679 "cluster-size: int" (optional)
5681 Not documented
5682 Since: 2.12
5684 SheepdogRedundancyType (Enum)
5686 "full" Create a fully replicated vdi with x copies
5688 "erasure-coded" Create an erasure coded vdi with x data strips and y
5689 parity strips
5690 Values:
5692 "full"
5694 Not documented
5695 "erasure-coded"
5697 Not documented
5698 Since: 2.12
5700 SheepdogRedundancyFull (Object)
5702 "copies" Number of copies to use (between 1 and 31)
5704 Members:
5706 "copies: int"
5708 Not documented
5709 Since: 2.12
5711 SheepdogRedundancyErasureCoded (Object)
5713 "data-strips" Number of data strips to use (one of {2,4,8,16})
5715 "parity-strips" Number of parity strips to use (between 1 and 15)
5716 Members:
5718 "data-strips: int"
5720 Not documented
5721 "parity-strips: int"
5723 Not documented
5724 Since: 2.12
5726 SheepdogRedundancy (Object)
5728 Members:
5730 "type: SheepdogRedundancyType"
5732 Not documented
5733 The members of "SheepdogRedundancyFull" when "type" is "full"
5735 The members of "SheepdogRedundancyErasureCoded" when "type" is
5736 "erasure-coded"
5737 Since: 2.12
5739 BlockdevCreateOptionsSheepdog (Object)
5741 Driver specific image creation options for Sheepdog.
5743 "location" Where to store the new image file "size"
5745 Size of the virtual disk in bytes "backing-file" File name of a
5746 base image "preallocation" Preallocation mode (allowed values: off,
5747 full) "redundancy" Redundancy of the image "object-size"
5748 Object size of the image
5749 Members:
5751 "location: BlockdevOptionsSheepdog"
5753 Not documented
5754 "size: int"
5756 Not documented
5757 "backing-file: string" (optional)
5759 Not documented
5760 "preallocation: PreallocMode" (optional)
5762 Not documented
5763 "redundancy: SheepdogRedundancy" (optional)
5765 Not documented
5766 "object-size: int" (optional)
5768 Not documented
5769 Since: 2.12
5771 BlockdevCreateOptionsSsh (Object)
5773 Driver specific image creation options for SSH.
5775 "location" Where to store the new image file "size"
5777 Size of the virtual disk in bytes
5778 Members:
5780 "location: BlockdevOptionsSsh"
5782 Not documented
5783 "size: int"
5785 Not documented
5786 Since: 2.12
5788 BlockdevCreateOptionsVdi (Object)
5790 Driver specific image creation options for VDI.
5792 "file" Node to create the image format on "size"
5794 Size of the virtual disk in bytes "preallocation" Preallocation mode
5795 for the new image (allowed values: off, metadata; default: off)
5796 Members:
5798 "file: BlockdevRef"
5800 Not documented
5801 "size: int"
5803 Not documented
5804 "preallocation: PreallocMode" (optional)
5806 Not documented
5807 Since: 2.12
5809 BlockdevVhdxSubformat (Enum)
5811 Values:
5813 "dynamic"
5815 Growing image file
5816 "fixed"
5818 Preallocated fixed-size image file
5819 Since: 2.12
5821 BlockdevCreateOptionsVhdx (Object)
5823 Driver specific image creation options for vhdx.
5825 "file" Node to create the image format on "size"
5827 Size of the virtual disk in bytes "log-size" Log size in bytes,
5828 must be a multiple of 1 MB (default: 1 MB) "block-size" Block
5829 size in bytes, must be a multiple of 1 MB and not larger than 256 MB
5830 (default: automatically choose a block size depending on the image
5831 size) "subformat" vhdx subformat (default: dynamic)
5832 "block-state-zero" Force use of payload blocks of type 'ZERO'. Non-
5833 standard, but default. Do not set to 'off' when using 'qemu-img
5834 convert' with subformat=dynamic.
5835 Members:
5837 "file: BlockdevRef"
5839 Not documented
5840 "size: int"
5842 Not documented
5843 "log-size: int" (optional)
5845 Not documented
5846 "block-size: int" (optional)
5848 Not documented
5849 "subformat: BlockdevVhdxSubformat" (optional)
5851 Not documented
5852 "block-state-zero: boolean" (optional)
5854 Not documented
5855 Since: 2.12
5857 BlockdevVpcSubformat (Enum)
5859 Values:
5861 "dynamic"
5863 Growing image file
5864 "fixed"
5866 Preallocated fixed-size image file
5867 Since: 2.12
5869 BlockdevCreateOptionsVpc (Object)
5871 Driver specific image creation options for vpc (VHD).
5873 "file" Node to create the image format on "size"
5875 Size of the virtual disk in bytes "subformat" vhdx subformat
5876 (default: dynamic) "force-size" Force use of the exact byte size
5877 instead of rounding to the next size that can be represented in CHS
5878 geometry (default: false)
5879 Members:
5881 "file: BlockdevRef"
5883 Not documented
5884 "size: int"
5886 Not documented
5887 "subformat: BlockdevVpcSubformat" (optional)
5889 Not documented
5890 "force-size: boolean" (optional)
5892 Not documented
5893 Since: 2.12
5895 BlockdevCreateOptions (Object)
5897 Options for creating an image format on a given node.
5899 "driver" block driver to create the image format
5901 Members:
5903 "driver: BlockdevDriver"
5905 Not documented
5906 The members of "BlockdevCreateOptionsFile" when "driver" is "file"
5908 The members of "BlockdevCreateOptionsGluster" when "driver" is
5909 "gluster"
5910 The members of "BlockdevCreateOptionsLUKS" when "driver" is "luks"
5911 The members of "BlockdevCreateOptionsNfs" when "driver" is "nfs"
5912 The members of "BlockdevCreateOptionsParallels" when "driver" is
5913 "parallels"
5914 The members of "BlockdevCreateOptionsQcow" when "driver" is "qcow"
5915 The members of "BlockdevCreateOptionsQcow2" when "driver" is "qcow2"
5916 The members of "BlockdevCreateOptionsQed" when "driver" is "qed"
5917 The members of "BlockdevCreateOptionsRbd" when "driver" is "rbd"
5918 The members of "BlockdevCreateOptionsSheepdog" when "driver" is
5919 "sheepdog"
5920 The members of "BlockdevCreateOptionsSsh" when "driver" is "ssh"
5921 The members of "BlockdevCreateOptionsVdi" when "driver" is "vdi"
5922 The members of "BlockdevCreateOptionsVhdx" when "driver" is "vhdx"
5923 The members of "BlockdevCreateOptionsVpc" when "driver" is "vpc"
5924 Since: 2.12
5926 blockdev-create (Command) Starts a job to create an image format on a
5928 given node. The job is automatically finalized, but a manual job-
5929 dismiss is required.
5930 Arguments:
5932 "job-id: string"
5934 Identifier for the newly created job.
5935 "options: BlockdevCreateOptions"
5937 Options for the image creation.
5938 Since: 3.0
5940 blockdev-open-tray (Command) Opens a block device's tray. If there is
5942 a block driver state tree inserted as a medium, it will become
5943 inaccessible to the guest (but it will remain associated to the block
5944 device, so closing the tray will make it accessible again).
5945 If the tray was already open before, this will be a no-op.
5947 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are
5949 cases in which no such event will be generated, these include:
5950 - if the guest has locked the tray, "force" is false and the guest
5952 does not respond to the eject request
5953 - if the BlockBackend denoted by "device" does not have a guest
5955 device attached to it
5956 - if the guest device does not have an actual tray
5958 Arguments:
5960 "device: string" (optional)
5962 Block device name (deprecated, use "id" instead)
5963 "id: string" (optional)
5965 The name or QOM path of the guest device (since: 2.8)
5966 "force: boolean" (optional)
5968 if false (the default), an eject request will be sent to the guest
5969 if it has locked the tray (and the tray will not be opened
5970 immediately); if true, the tray will be opened regardless of
5971 whether it is locked
5972 Since: 2.5
5974 Example:
5976 -> { "execute": "blockdev-open-tray",
5978 "arguments": { "id": "ide0-1-0" } }
5979 <- { "timestamp": { "seconds": 1418751016,
5981 "microseconds": 716996 },
5982 "event": "DEVICE_TRAY_MOVED",
5983 "data": { "device": "ide1-cd0",
5984 "id": "ide0-1-0",
5985 "tray-open": true } }
5986 <- { "return": {} }
5988 blockdev-close-tray (Command) Closes a block device's tray. If there
5990 is a block driver state tree associated with the block device (which is
5991 currently ejected), that tree will be loaded as the medium.
5992 If the tray was already closed before, this will be a no-op.
5994 Arguments:
5996 "device: string" (optional)
5998 Block device name (deprecated, use "id" instead)
5999 "id: string" (optional)
6001 The name or QOM path of the guest device (since: 2.8)
6002 Since: 2.5
6004 Example:
6006 -> { "execute": "blockdev-close-tray",
6008 "arguments": { "id": "ide0-1-0" } }
6009 <- { "timestamp": { "seconds": 1418751345,
6011 "microseconds": 272147 },
6012 "event": "DEVICE_TRAY_MOVED",
6013 "data": { "device": "ide1-cd0",
6014 "id": "ide0-1-0",
6015 "tray-open": false } }
6016 <- { "return": {} }
6018 blockdev-remove-medium (Command) Removes a medium (a block driver
6020 state tree) from a block device. That block device's tray must
6021 currently be open (unless there is no attached guest device).
6022 If the tray is open and there is no medium inserted, this will be a no-
6024 op.
6025 Arguments:
6027 "id: string"
6029 The name or QOM path of the guest device
6030 Since: 2.12
6032 Example:
6034 -> { "execute": "blockdev-remove-medium",
6036 "arguments": { "id": "ide0-1-0" } }
6037 <- { "error": { "class": "GenericError",
6039 "desc": "Tray of device 'ide0-1-0' is not open" } }
6040 -> { "execute": "blockdev-open-tray",
6042 "arguments": { "id": "ide0-1-0" } }
6043 <- { "timestamp": { "seconds": 1418751627,
6045 "microseconds": 549958 },
6046 "event": "DEVICE_TRAY_MOVED",
6047 "data": { "device": "ide1-cd0",
6048 "id": "ide0-1-0",
6049 "tray-open": true } }
6050 <- { "return": {} }
6052 -> { "execute": "blockdev-remove-medium",
6054 "arguments": { "id": "ide0-1-0" } }
6055 <- { "return": {} }
6057 blockdev-insert-medium (Command) Inserts a medium (a block driver
6059 state tree) into a block device. That block device's tray must
6060 currently be open (unless there is no attached guest device) and there
6061 must be no medium inserted already.
6062 Arguments:
6064 "id: string"
6066 The name or QOM path of the guest device
6067 "node-name: string"
6069 name of a node in the block driver state graph
6070 Since: 2.12
6072 Example:
6074 -> { "execute": "blockdev-add",
6076 "arguments": {
6077 "node-name": "node0",
6078 "driver": "raw",
6079 "file": { "driver": "file",
6080 "filename": "fedora.iso" } } }
6081 <- { "return": {} }
6082 -> { "execute": "blockdev-insert-medium",
6084 "arguments": { "id": "ide0-1-0",
6085 "node-name": "node0" } }
6086 <- { "return": {} }
6088 BlockdevChangeReadOnlyMode (Enum)
6090 Specifies the new read-only mode of a block device subject to the
6092 "blockdev-change-medium" command.
6093 Values:
6095 "retain"
6097 Retains the current read-only mode
6098 "read-only"
6100 Makes the device read-only
6101 "read-write"
6103 Makes the device writable
6104 Since: 2.3
6106 blockdev-change-medium (Command) Changes the medium inserted into a
6108 block device by ejecting the current medium and loading a new image
6109 file which is inserted as the new medium (this command combines
6110 blockdev-open-tray, blockdev-remove-medium, blockdev-insert-medium and
6111 blockdev-close-tray).
6112 Arguments:
6114 "device: string" (optional)
6116 Block device name (deprecated, use "id" instead)
6117 "id: string" (optional)
6119 The name or QOM path of the guest device (since: 2.8)
6120 "filename: string"
6122 filename of the new image to be loaded
6123 "format: string" (optional)
6125 format to open the new image with (defaults to the probed format)
6126 "read-only-mode: BlockdevChangeReadOnlyMode" (optional)
6128 change the read-only mode of the device; defaults to 'retain'
6129 Since: 2.5
6131 Examples:
6133 1. Change a removable medium
6135 -> { "execute": "blockdev-change-medium",
6137 "arguments": { "id": "ide0-1-0",
6138 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
6139 "format": "raw" } }
6140 <- { "return": {} }
6141 2. Load a read-only medium into a writable drive
6143 -> { "execute": "blockdev-change-medium",
6145 "arguments": { "id": "floppyA",
6146 "filename": "/srv/images/ro.img",
6147 "format": "raw",
6148 "read-only-mode": "retain" } }
6149 <- { "error":
6151 { "class": "GenericError",
6152 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
6153 -> { "execute": "blockdev-change-medium",
6155 "arguments": { "id": "floppyA",
6156 "filename": "/srv/images/ro.img",
6157 "format": "raw",
6158 "read-only-mode": "read-only" } }
6159 <- { "return": {} }
6161 BlockErrorAction (Enum)
6163 An enumeration of action that has been taken when a DISK I/O occurs
6165 Values:
6167 "ignore"
6169 error has been ignored
6170 "report"
6172 error has been reported to the device
6173 "stop"
6175 error caused VM to be stopped
6176 Since: 2.1
6178 BLOCK_IMAGE_CORRUPTED (Event) Emitted when a disk image is being
6180 marked corrupt. The image can be identified by its device or node name.
6181 The 'device' field is always present for compatibility reasons, but it
6182 can be empty ("") if the image does not have a device name associated.
6183 Arguments:
6185 "device: string"
6187 device name. This is always present for compatibility reasons, but
6188 it can be empty ("") if the image does not have a device name
6189 associated.
6190 "node-name: string" (optional)
6192 node name (Since: 2.4)
6193 "msg: string"
6195 informative message for human consumption, such as the kind of
6196 corruption being detected. It should not be parsed by machine as it
6197 is not guaranteed to be stable
6198 "offset: int" (optional)
6200 if the corruption resulted from an image access, this is the host's
6201 access offset into the image
6202 "size: int" (optional)
6204 if the corruption resulted from an image access, this is the access
6205 size
6206 "fatal: boolean"
6208 if set, the image is marked corrupt and therefore unusable after
6209 this event and must be repaired (Since 2.2; before, every
6210 BLOCK_IMAGE_CORRUPTED event was fatal)
6211 Note: If action is "stop", a STOP event will eventually follow the
6213 BLOCK_IO_ERROR event.
6214 Example:
6216 <- { "event": "BLOCK_IMAGE_CORRUPTED",
6218 "data": { "device": "ide0-hd0", "node-name": "node0",
6219 "msg": "Prevented active L1 table overwrite", "offset": 196608,
6220 "size": 65536 },
6221 "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
6222 Since: 1.7
6224 BLOCK_IO_ERROR (Event) Emitted when a disk I/O error occurs
6226 Arguments:
6228 "device: string"
6230 device name. This is always present for compatibility reasons, but
6231 it can be empty ("") if the image does not have a device name
6232 associated.
6233 "node-name: string" (optional)
6235 node name. Note that errors may be reported for the root node that
6236 is directly attached to a guest device rather than for the node
6237 where the error occurred. The node name is not present if the drive
6238 is empty. (Since: 2.8)
6239 "operation: IoOperationType"
6241 I/O operation
6242 "action: BlockErrorAction"
6244 action that has been taken
6245 "nospace: boolean" (optional)
6247 true if I/O error was caused due to a no-space condition. This key
6248 is only present if query-block's io-status is present, please see
6249 query-block documentation for more information (since: 2.2)
6250 "reason: string"
6252 human readable string describing the error cause. (This field is a
6253 debugging aid for humans, it should not be parsed by applications)
6254 (since: 2.2)
6255 Note: If action is "stop", a STOP event will eventually follow the
6257 BLOCK_IO_ERROR event
6258 Since: 0.13.0
6260 Example:
6262 <- { "event": "BLOCK_IO_ERROR",
6264 "data": { "device": "ide0-hd1",
6265 "node-name": "#block212",
6266 "operation": "write",
6267 "action": "stop" },
6268 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6269 BLOCK_JOB_COMPLETED (Event) Emitted when a block job has completed
6271 Arguments:
6273 "type: JobType"
6275 job type
6276 "device: string"
6278 The job identifier. Originally the device name but other values are
6279 allowed since QEMU 2.7
6280 "len: int"
6282 maximum progress value
6283 "offset: int"
6285 current progress value. On success this is equal to len. On
6286 failure this is less than len
6287 "speed: int"
6289 rate limit, bytes per second
6290 "error: string" (optional)
6292 error message. Only present on failure. This field contains a
6293 human-readable error message. There are no semantics other than
6294 that streaming has failed and clients should not try to interpret
6295 the error string
6296 Since: 1.1
6298 Example:
6300 <- { "event": "BLOCK_JOB_COMPLETED",
6302 "data": { "type": "stream", "device": "virtio-disk0",
6303 "len": 10737418240, "offset": 10737418240,
6304 "speed": 0 },
6305 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6306 BLOCK_JOB_CANCELLED (Event) Emitted when a block job has been
6308 cancelled
6309 Arguments:
6311 "type: JobType"
6313 job type
6314 "device: string"
6316 The job identifier. Originally the device name but other values are
6317 allowed since QEMU 2.7
6318 "len: int"
6320 maximum progress value
6321 "offset: int"
6323 current progress value. On success this is equal to len. On
6324 failure this is less than len
6325 "speed: int"
6327 rate limit, bytes per second
6328 Since: 1.1
6330 Example:
6332 <- { "event": "BLOCK_JOB_CANCELLED",
6334 "data": { "type": "stream", "device": "virtio-disk0",
6335 "len": 10737418240, "offset": 134217728,
6336 "speed": 0 },
6337 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6338 BLOCK_JOB_ERROR (Event) Emitted when a block job encounters an error
6340 Arguments:
6342 "device: string"
6344 The job identifier. Originally the device name but other values are
6345 allowed since QEMU 2.7
6346 "operation: IoOperationType"
6348 I/O operation
6349 "action: BlockErrorAction"
6351 action that has been taken
6352 Since: 1.3
6354 Example:
6356 <- { "event": "BLOCK_JOB_ERROR",
6358 "data": { "device": "ide0-hd1",
6359 "operation": "write",
6360 "action": "stop" },
6361 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6362 BLOCK_JOB_READY (Event) Emitted when a block job is ready to complete
6364 Arguments:
6366 "type: JobType"
6368 job type
6369 "device: string"
6371 The job identifier. Originally the device name but other values are
6372 allowed since QEMU 2.7
6373 "len: int"
6375 maximum progress value
6376 "offset: int"
6378 current progress value. On success this is equal to len. On
6379 failure this is less than len
6380 "speed: int"
6382 rate limit, bytes per second
6383 Note: The "ready to complete" status is always reset by a
6385 "BLOCK_JOB_ERROR" event
6386 Since: 1.3
6388 Example:
6390 <- { "event": "BLOCK_JOB_READY",
6392 "data": { "device": "drive0", "type": "mirror", "speed": 0,
6393 "len": 2097152, "offset": 2097152 }
6394 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6395 BLOCK_JOB_PENDING (Event) Emitted when a block job is awaiting
6397 explicit authorization to finalize graph changes via
6398 "block-job-finalize". If this job is part of a transaction, it will not
6399 emit this event until the transaction has converged first.
6400 Arguments:
6402 "type: JobType"
6404 job type
6405 "id: string"
6407 The job identifier.
6408 Since: 2.12
6410 Example:
6412 <- { "event": "BLOCK_JOB_WAITING",
6414 "data": { "device": "drive0", "type": "mirror" },
6415 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6416 PreallocMode (Enum)
6418 Preallocation mode of QEMU image file
6420 Values:
6422 "off"
6424 no preallocation
6425 "metadata"
6427 preallocate only for metadata
6428 "falloc"
6430 like "full" preallocation but allocate disk space by
6431 posix_fallocate() rather than writing zeros.
6432 "full"
6434 preallocate all data by writing zeros to device to ensure disk
6435 space is really available. "full" preallocation also sets up
6436 metadata correctly.
6437 Since: 2.2
6439 BLOCK_WRITE_THRESHOLD (Event) Emitted when writes on block device
6441 reaches or exceeds the configured write threshold. For thin-provisioned
6442 devices, this means the device should be extended to avoid pausing for
6443 disk exhaustion. The event is one shot. Once triggered, it needs to be
6444 re-registered with another block-set-write-threshold command.
6445 Arguments:
6447 "node-name: string"
6449 graph node name on which the threshold was exceeded.
6450 "amount-exceeded: int"
6452 amount of data which exceeded the threshold, in bytes.
6453 "write-threshold: int"
6455 last configured threshold, in bytes.
6456 Since: 2.3
6458 block-set-write-threshold (Command) Change the write threshold for a
6460 block drive. An event will be delivered if a write to this block drive
6461 crosses the configured threshold. The threshold is an offset, thus
6462 must be non-negative. Default is no write threshold. Setting the
6463 threshold to zero disables it.
6464 This is useful to transparently resize thin-provisioned drives without
6466 the guest OS noticing.
6467 Arguments:
6469 "node-name: string"
6471 graph node name on which the threshold must be set.
6472 "write-threshold: int"
6474 configured threshold for the block device, bytes. Use 0 to disable
6475 the threshold.
6476 Since: 2.3
6478 Example:
6480 -> { "execute": "block-set-write-threshold",
6482 "arguments": { "node-name": "mydev",
6483 "write-threshold": 17179869184 } }
6484 <- { "return": {} }
6485 x-blockdev-change (Command) Dynamically reconfigure the block driver
6487 state graph. It can be used to add, remove, insert or replace a graph
6488 node. Currently only the Quorum driver implements this feature to add
6489 or remove its child. This is useful to fix a broken quorum child.
6490 If "node" is specified, it will be inserted under "parent". "child" may
6492 not be specified in this case. If both "parent" and "child" are
6493 specified but "node" is not, "child" will be detached from "parent".
6494 Arguments:
6496 "parent: string"
6498 the id or name of the parent node.
6499 "child: string" (optional)
6501 the name of a child under the given parent node.
6502 "node: string" (optional)
6504 the name of the node that will be added.
6505 Note: this command is experimental, and its API is not stable. It does
6507 not support all kinds of operations, all kinds of children, nor all
6508 block drivers.
6509 FIXME Removing children from a quorum node means introducing gaps in
6511 the child indices. This cannot be represented in the 'children' list of
6512 BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename().
6513 Warning: The data in a new quorum child MUST be consistent with that of
6515 the rest of the array.
6516 Since: 2.7
6518 Example:
6520 1. Add a new node to a quorum
6522 -> { "execute": "blockdev-add",
6523 "arguments": {
6524 "driver": "raw",
6525 "node-name": "new_node",
6526 "file": { "driver": "file",
6527 "filename": "test.raw" } } }
6528 <- { "return": {} }
6529 -> { "execute": "x-blockdev-change",
6530 "arguments": { "parent": "disk1",
6531 "node": "new_node" } }
6532 <- { "return": {} }
6533 2. Delete a quorum's node
6535 -> { "execute": "x-blockdev-change",
6536 "arguments": { "parent": "disk1",
6537 "child": "children.1" } }
6538 <- { "return": {} }
6539 x-blockdev-set-iothread (Command) Move "node" and its children into
6541 the "iothread". If "iothread" is null then move "node" and its
6542 children into the main loop.
6543 The node must not be attached to a BlockBackend.
6545 Arguments:
6547 "node-name: string"
6549 the name of the block driver node
6550 "iothread: StrOrNull"
6552 the name of the IOThread object or null for the main loop
6553 "force: boolean" (optional)
6555 true if the node and its children should be moved when a
6556 BlockBackend is already attached
6557 Note: this command is experimental and intended for test cases that
6559 need control over IOThreads only.
6560 Since: 2.12
6562 Example:
6564 1. Move a node into an IOThread
6566 -> { "execute": "x-blockdev-set-iothread",
6567 "arguments": { "node-name": "disk1",
6568 "iothread": "iothread0" } }
6569 <- { "return": {} }
6570 2. Move a node into the main loop
6572 -> { "execute": "x-blockdev-set-iothread",
6573 "arguments": { "node-name": "disk1",
6574 "iothread": null } }
6575 <- { "return": {} }
6576 Additional block stuff (VM related)
6578 BiosAtaTranslation (Enum)
6580 Policy that BIOS should use to interpret cylinder/head/sector
6582 addresses. Note that Bochs BIOS and SeaBIOS will not actually
6583 translate logical CHS to physical; instead, they will use logical block
6584 addressing.
6585 Values:
6587 "auto"
6589 If cylinder/heads/sizes are passed, choose between none and LBA
6590 depending on the size of the disk. If they are not passed, choose
6591 none if QEMU can guess that the disk had 16 or fewer heads, large
6592 if QEMU can guess that the disk had 131072 or fewer tracks across
6593 all heads (i.e. cylinders*heads<131072), otherwise LBA.
6594 "none"
6596 The physical disk geometry is equal to the logical geometry.
6597 "lba"
6599 Assume 63 sectors per track and one of 16, 32, 64, 128 or 255 heads
6600 (if fewer than 255 are enough to cover the whole disk with 1024
6601 cylinders/head). The number of cylinders/head is then computed
6602 based on the number of sectors and heads.
6603 "large"
6605 The number of cylinders per head is scaled down to 1024 by
6606 correspondingly scaling up the number of heads.
6607 "rechs"
6609 Same as "large", but first convert a 16-head geometry to 15-head,
6610 by proportionally scaling up the number of cylinders/head.
6611 Since: 2.0
6613 FloppyDriveType (Enum)
6615 Type of Floppy drive to be emulated by the Floppy Disk Controller.
6617 Values:
6619 144 1.44MB 3.5" drive
6621 288 2.88MB 3.5" drive
6623 120 1.2MB 5.25" drive
6625 "none"
6627 No drive connected
6628 "auto"
6630 Automatically determined by inserted media at boot
6631 Since: 2.6
6633 BlockdevSnapshotInternal (Object)
6635 Members:
6637 "device: string"
6639 the device name or node-name of a root node to generate the
6640 snapshot from
6641 "name: string"
6643 the name of the internal snapshot to be created
6644 Notes: In transaction, if "name" is empty, or any snapshot matching
6646 "name" exists, the operation will fail. Only some image formats support
6647 it, for example, qcow2, rbd, and sheepdog.
6648 Since: 1.7
6650 PRManagerInfo (Object)
6652 Information about a persistent reservation manager
6654 Members:
6656 "id: string"
6658 the identifier of the persistent reservation manager
6659 "connected: boolean"
6661 true if the persistent reservation manager is connected to the
6662 underlying storage or helper
6663 Since: 3.0
6665 query-pr-managers (Command) Returns a list of information about each
6667 persistent reservation manager.
6668 Returns: a list of "PRManagerInfo" for each persistent reservation
6670 manager
6671 Since: 3.0
6673 blockdev-snapshot-internal-sync (Command) Synchronously take an
6675 internal snapshot of a block device, when the format of the image used
6676 supports it. If the name is an empty string, or a snapshot with name
6677 already exists, the operation will fail.
6678 For the arguments, see the documentation of BlockdevSnapshotInternal.
6680 Returns: nothing on success
6682 If "device" is not a valid block device, GenericError
6684 If any snapshot matching "name" exists, or "name" is empty,
6686 GenericError
6687 If the format of the image used does not support it,
6689 BlockFormatFeatureNotSupported
6690 Since: 1.7
6692 Example:
6694 -> { "execute": "blockdev-snapshot-internal-sync",
6696 "arguments": { "device": "ide-hd0",
6697 "name": "snapshot0" }
6698 }
6699 <- { "return": {} }
6700 blockdev-snapshot-delete-internal-sync (Command) Synchronously delete
6702 an internal snapshot of a block device, when the format of the image
6703 used support it. The snapshot is identified by name or id or both. One
6704 of the name or id is required. Return SnapshotInfo for the successfully
6705 deleted snapshot.
6706 Arguments:
6708 "device: string"
6710 the device name or node-name of a root node to delete the snapshot
6711 from
6712 "id: string" (optional)
6714 optional the snapshot's ID to be deleted
6715 "name: string" (optional)
6717 optional the snapshot's name to be deleted
6718 Returns: SnapshotInfo on success If "device" is not a valid block
6720 device, GenericError If snapshot not found, GenericError If the format
6721 of the image used does not support it, BlockFormatFeatureNotSupported
6722 If "id" and "name" are both not specified, GenericError
6723 Since: 1.7
6725 Example:
6727 -> { "execute": "blockdev-snapshot-delete-internal-sync",
6729 "arguments": { "device": "ide-hd0",
6730 "name": "snapshot0" }
6731 }
6732 <- { "return": {
6733 "id": "1",
6734 "name": "snapshot0",
6735 "vm-state-size": 0,
6736 "date-sec": 1000012,
6737 "date-nsec": 10,
6738 "vm-clock-sec": 100,
6739 "vm-clock-nsec": 20
6740 }
6741 }
6742 eject (Command) Ejects a device from a removable drive.
6744 Arguments:
6746 "device: string" (optional)
6748 Block device name (deprecated, use "id" instead)
6749 "id: string" (optional)
6751 The name or QOM path of the guest device (since: 2.8)
6752 "force: boolean" (optional)
6754 If true, eject regardless of whether the drive is locked. If not
6755 specified, the default value is false.
6756 Returns: Nothing on success
6758 If "device" is not a valid block device, DeviceNotFound
6760 Notes: Ejecting a device with no media results in success
6762 Since: 0.14.0
6764 Example:
6766 -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
6768 <- { "return": {} }
6769 nbd-server-start (Command) Start an NBD server listening on the given
6771 host and port. Block devices can then be exported using
6772 "nbd-server-add". The NBD server will present them as named exports;
6773 for example, another QEMU instance could refer to them as
6774 "nbd:HOST:PORT:exportname=NAME".
6775 Arguments:
6777 "addr: SocketAddressLegacy"
6779 Address on which to listen.
6780 "tls-creds: string" (optional)
6782 (optional) ID of the TLS credentials object. Since 2.6
6783 Returns: error if the server is already running.
6785 Since: 1.3.0
6787 nbd-server-add (Command) Export a block node to QEMU's embedded NBD
6789 server.
6790 Arguments:
6792 "device: string"
6794 The device name or node name of the node to be exported
6795 "name: string" (optional)
6797 Export name. If unspecified, the "device" parameter is used as the
6798 export name. (Since 2.12)
6799 "writable: boolean" (optional)
6801 Whether clients should be able to write to the device via the NBD
6802 connection (default false).
6803 Returns: error if the server is not running, or export with the same
6805 name already exists.
6806 Since: 1.3.0
6808 NbdServerRemoveMode (Enum)
6810 Mode for removing an NBD export.
6812 Values:
6814 "safe"
6816 Remove export if there are no existing connections, fail otherwise.
6817 "hard"
6819 Drop all connections immediately and remove export.
6820 Potential additional modes to be added in the future:
6822 hide: Just hide export from new clients, leave existing connections as
6824 is. Remove export after all clients are disconnected.
6825 soft: Hide export from new clients, answer with ESHUTDOWN for all
6827 further requests from existing clients.
6828 Since: 2.12
6830 nbd-server-remove (Command) Remove NBD export by name.
6832 Arguments:
6834 "name: string"
6836 Export name.
6837 "mode: NbdServerRemoveMode" (optional)
6839 Mode of command operation. See "NbdServerRemoveMode" description.
6840 Default is 'safe'.
6841 Returns: error if
6843 - the server is not running
6845 - export is not found
6847 - mode is 'safe' and there are existing connections
6849 Since: 2.12
6851 x-nbd-server-add-bitmap (Command) Expose a dirty bitmap associated
6853 with the selected export. The bitmap search starts at the device
6854 attached to the export, and includes all backing files. The exported
6855 bitmap is then locked until the NBD export is removed.
6856 Arguments:
6858 "name: string"
6860 Export name.
6861 "bitmap: string"
6863 Bitmap name to search for.
6864 "bitmap-export-name: string" (optional)
6866 How the bitmap will be seen by nbd clients (default "bitmap")
6867 Note: the client must use NBD_OPT_SET_META_CONTEXT with a query of
6869 "qemu:dirty-bitmap:NAME" (where NAME matches "bitmap-export-name") to
6870 access the exposed bitmap.
6871 Since: 3.0
6873 nbd-server-stop (Command) Stop QEMU's embedded NBD server, and
6875 unregister all devices previously added via "nbd-server-add".
6876 Since: 1.3.0
6878 DEVICE_TRAY_MOVED (Event) Emitted whenever the tray of a removable
6880 device is moved by the guest or by HMP/QMP commands
6881 Arguments:
6883 "device: string"
6885 Block device name. This is always present for compatibility
6886 reasons, but it can be empty ("") if the image does not have a
6887 device name associated.
6888 "id: string"
6890 The name or QOM path of the guest device (since 2.8)
6891 "tray-open: boolean"
6893 true if the tray has been opened or false if it has been closed
6894 Since: 1.1
6896 Example:
6898 <- { "event": "DEVICE_TRAY_MOVED",
6900 "data": { "device": "ide1-cd0",
6901 "id": "/machine/unattached/device[22]",
6902 "tray-open": true
6903 },
6904 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6905 PR_MANAGER_STATUS_CHANGED (Event) Emitted whenever the connected
6907 status of a persistent reservation manager changes.
6908 Arguments:
6910 "id: string"
6912 The id of the PR manager object
6913 "connected: boolean"
6915 true if the PR manager is connected to a backend
6916 Since: 3.0
6918 Example:
6920 <- { "event": "PR_MANAGER_STATUS_CHANGED",
6922 "data": { "id": "pr-helper0",
6923 "connected": true
6924 },
6925 "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
6926 QuorumOpType (Enum)
6928 An enumeration of the quorum operation types
6930 Values:
6932 "read"
6934 read operation
6935 "write"
6937 write operation
6938 "flush"
6940 flush operation
6941 Since: 2.6
6943 QUORUM_FAILURE (Event) Emitted by the Quorum block driver if it fails
6945 to establish a quorum
6946 Arguments:
6948 "reference: string"
6950 device name if defined else node name
6951 "sector-num: int"
6953 number of the first sector of the failed read operation
6954 "sectors-count: int"
6956 failed read operation sector count
6957 Note: This event is rate-limited.
6959 Since: 2.0
6961 Example:
6963 <- { "event": "QUORUM_FAILURE",
6965 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
6966 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
6967 QUORUM_REPORT_BAD (Event) Emitted to report a corruption of a Quorum
6969 file
6970 Arguments:
6972 "type: QuorumOpType"
6974 quorum operation type (Since 2.6)
6975 "error: string" (optional)
6977 error message. Only present on failure. This field contains a
6978 human-readable error message. There are no semantics other than
6979 that the block layer reported an error and clients should not try
6980 to interpret the error string.
6981 "node-name: string"
6983 the graph node name of the block driver state
6984 "sector-num: int"
6986 number of the first sector of the failed read operation
6987 "sectors-count: int"
6989 failed read operation sector count
6990 Note: This event is rate-limited.
6992 Since: 2.0
6994 Example:
6996 1. Read operation
6998 { "event": "QUORUM_REPORT_BAD",
7000 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
7001 "type": "read" },
7002 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7003 2. Flush operation
7005 { "event": "QUORUM_REPORT_BAD",
7007 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
7008 "type": "flush", "error": "Broken pipe" },
7009 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
7010 Character devices
7012 ChardevInfo (Object)
7013 Information about a character device.
7015 Members:
7017 "label: string"
7019 the label of the character device
7020 "filename: string"
7022 the filename of the character device
7023 "frontend-open: boolean"
7025 shows whether the frontend device attached to this backend (eg.
7026 with the chardev=... option) is in open or closed state (since 2.1)
7027 Notes: "filename" is encoded using the QEMU command line character
7029 device encoding. See the QEMU man page for details.
7030 Since: 0.14.0
7032 query-chardev (Command) Returns information about current character
7034 devices.
7035 Returns: a list of "ChardevInfo"
7037 Since: 0.14.0
7039 Example:
7041 -> { "execute": "query-chardev" }
7043 <- {
7044 "return": [
7045 {
7046 "label": "charchannel0",
7047 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
7048 "frontend-open": false
7049 },
7050 {
7051 "label": "charmonitor",
7052 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
7053 "frontend-open": true
7054 },
7055 {
7056 "label": "charserial0",
7057 "filename": "pty:/dev/pts/2",
7058 "frontend-open": true
7059 }
7060 ]
7061 }
7062 ChardevBackendInfo (Object)
7064 Information about a character device backend
7066 Members:
7068 "name: string"
7070 The backend name
7071 Since: 2.0
7073 query-chardev-backends (Command) Returns information about character
7075 device backends.
7076 Returns: a list of "ChardevBackendInfo"
7078 Since: 2.0
7080 Example:
7082 -> { "execute": "query-chardev-backends" }
7084 <- {
7085 "return":[
7086 {
7087 "name":"udp"
7088 },
7089 {
7090 "name":"tcp"
7091 },
7092 {
7093 "name":"unix"
7094 },
7095 {
7096 "name":"spiceport"
7097 }
7098 ]
7099 }
7100 DataFormat (Enum)
7102 An enumeration of data format.
7104 Values:
7106 "utf8"
7108 Data is a UTF-8 string (RFC 3629)
7109 "base64"
7111 Data is Base64 encoded binary (RFC 3548)
7112 Since: 1.4
7114 ringbuf-write (Command) Write to a ring buffer character device.
7116 Arguments:
7118 "device: string"
7120 the ring buffer character device name
7121 "data: string"
7123 data to write
7124 "format: DataFormat" (optional)
7126 data encoding (default 'utf8').
7127 - base64: data must be base64 encoded text. Its binary decoding
7129 gets written.
7130 - utf8: data's UTF-8 encoding is written
7132 - data itself is always Unicode regardless of format, like any
7134 other string.
7135 Returns: Nothing on success
7137 Since: 1.4
7139 Example:
7141 -> { "execute": "ringbuf-write",
7143 "arguments": { "device": "foo",
7144 "data": "abcdefgh",
7145 "format": "utf8" } }
7146 <- { "return": {} }
7147 ringbuf-read (Command) Read from a ring buffer character device.
7149 Arguments:
7151 "device: string"
7153 the ring buffer character device name
7154 "size: int"
7156 how many bytes to read at most
7157 "format: DataFormat" (optional)
7159 data encoding (default 'utf8').
7160 - base64: the data read is returned in base64 encoding.
7162 - utf8: the data read is interpreted as UTF-8. Bug: can screw up
7164 when the buffer contains invalid UTF-8 sequences, NUL
7165 characters, after the ring buffer lost data, and when reading
7166 stops because the size limit is reached.
7167 - The return value is always Unicode regardless of format, like
7169 any other string.
7170 Returns: data read from the device
7172 Since: 1.4
7174 Example:
7176 -> { "execute": "ringbuf-read",
7178 "arguments": { "device": "foo",
7179 "size": 1000,
7180 "format": "utf8" } }
7181 <- { "return": "abcdefgh" }
7182 ChardevCommon (Object)
7184 Configuration shared across all chardev backends
7186 Members:
7188 "logfile: string" (optional)
7190 The name of a logfile to save output
7191 "logappend: boolean" (optional)
7193 true to append instead of truncate (default to false to truncate)
7194 Since: 2.6
7196 ChardevFile (Object)
7198 Configuration info for file chardevs.
7200 Members:
7202 "in: string" (optional)
7204 The name of the input file
7205 "out: string"
7207 The name of the output file
7208 "append: boolean" (optional)
7210 Open the file in append mode (default false to truncate) (Since
7211 2.6)
7212 The members of "ChardevCommon"
7214 Since: 1.4
7216 ChardevHostdev (Object)
7218 Configuration info for device and pipe chardevs.
7220 Members:
7222 "device: string"
7224 The name of the special file for the device, i.e. /dev/ttyS0 on
7225 Unix or COM1: on Windows
7226 The members of "ChardevCommon"
7228 Since: 1.4
7230 ChardevSocket (Object)
7232 Configuration info for (stream) socket chardevs.
7234 Members:
7236 "addr: SocketAddressLegacy"
7238 socket address to listen on (server=true) or connect to
7239 (server=false)
7240 "tls-creds: string" (optional)
7242 the ID of the TLS credentials object (since 2.6)
7243 "server: boolean" (optional)
7245 create server socket (default: true)
7246 "wait: boolean" (optional)
7248 wait for incoming connection on server sockets (default: false).
7249 "nodelay: boolean" (optional)
7251 set TCP_NODELAY socket option (default: false)
7252 "telnet: boolean" (optional)
7254 enable telnet protocol on server sockets (default: false)
7255 "tn3270: boolean" (optional)
7257 enable tn3270 protocol on server sockets (default: false) (Since:
7258 2.10)
7259 "websocket: boolean" (optional)
7261 enable websocket protocol on server sockets (default: false)
7262 (Since: 3.1)
7263 "reconnect: int" (optional)
7265 For a client socket, if a socket is disconnected, then attempt a
7266 reconnect after the given number of seconds. Setting this to zero
7267 disables this function. (default: 0) (Since: 2.2)
7268 The members of "ChardevCommon"
7270 Since: 1.4
7272 ChardevUdp (Object)
7274 Configuration info for datagram socket chardevs.
7276 Members:
7278 "remote: SocketAddressLegacy"
7280 remote address
7281 "local: SocketAddressLegacy" (optional)
7283 local address
7284 The members of "ChardevCommon"
7286 Since: 1.5
7288 ChardevMux (Object)
7290 Configuration info for mux chardevs.
7292 Members:
7294 "chardev: string"
7296 name of the base chardev.
7297 The members of "ChardevCommon"
7299 Since: 1.5
7301 ChardevStdio (Object)
7303 Configuration info for stdio chardevs.
7305 Members:
7307 "signal: boolean" (optional)
7309 Allow signals (such as SIGINT triggered by ^C) be delivered to
7310 qemu. Default: true in -nographic mode, false otherwise.
7311 The members of "ChardevCommon"
7313 Since: 1.5
7315 ChardevSpiceChannel (Object)
7317 Configuration info for spice vm channel chardevs.
7319 Members:
7321 "type: string"
7323 kind of channel (for example vdagent).
7324 The members of "ChardevCommon"
7326 Since: 1.5
7328 ChardevSpicePort (Object)
7330 Configuration info for spice port chardevs.
7332 Members:
7334 "fqdn: string"
7336 name of the channel (see docs/spice-port-fqdn.txt)
7337 The members of "ChardevCommon"
7339 Since: 1.5
7341 ChardevVC (Object)
7343 Configuration info for virtual console chardevs.
7345 Members:
7347 "width: int" (optional)
7349 console width, in pixels
7350 "height: int" (optional)
7352 console height, in pixels
7353 "cols: int" (optional)
7355 console width, in chars
7356 "rows: int" (optional)
7358 console height, in chars
7359 The members of "ChardevCommon"
7361 Since: 1.5
7363 ChardevRingbuf (Object)
7365 Configuration info for ring buffer chardevs.
7367 Members:
7369 "size: int" (optional)
7371 ring buffer size, must be power of two, default is 65536
7372 The members of "ChardevCommon"
7374 Since: 1.5
7376 ChardevBackend (Object)
7378 Configuration info for the new chardev backend.
7380 Members:
7382 "type"
7384 One of "file", "serial", "parallel", "pipe", "socket", "udp",
7385 "pty", "null", "mux", "msmouse", "wctablet", "braille", "testdev",
7386 "stdio", "console", "spicevmc", "spiceport", "vc", "ringbuf",
7387 "memory"
7388 "data: ChardevFile" when "type" is "file"
7390 "data: ChardevHostdev" when "type" is "serial"
7391 "data: ChardevHostdev" when "type" is "parallel"
7392 "data: ChardevHostdev" when "type" is "pipe"
7393 "data: ChardevSocket" when "type" is "socket"
7394 "data: ChardevUdp" when "type" is "udp"
7395 "data: ChardevCommon" when "type" is "pty"
7396 "data: ChardevCommon" when "type" is "null"
7397 "data: ChardevMux" when "type" is "mux"
7398 "data: ChardevCommon" when "type" is "msmouse"
7399 "data: ChardevCommon" when "type" is "wctablet"
7400 "data: ChardevCommon" when "type" is "braille"
7401 "data: ChardevCommon" when "type" is "testdev"
7402 "data: ChardevStdio" when "type" is "stdio"
7403 "data: ChardevCommon" when "type" is "console"
7404 "data: ChardevSpiceChannel" when "type" is "spicevmc"
7405 "data: ChardevSpicePort" when "type" is "spiceport"
7406 "data: ChardevVC" when "type" is "vc"
7407 "data: ChardevRingbuf" when "type" is "ringbuf"
7408 "data: ChardevRingbuf" when "type" is "memory"
7409 Since: 1.4 (testdev since 2.2, wctablet since 2.9)
7411 ChardevReturn (Object)
7413 Return info about the chardev backend just created.
7415 Members:
7417 "pty: string" (optional)
7419 name of the slave pseudoterminal device, present if and only if a
7420 chardev of type 'pty' was created
7421 Since: 1.4
7423 chardev-add (Command) Add a character device backend
7425 Arguments:
7427 "id: string"
7429 the chardev's ID, must be unique
7430 "backend: ChardevBackend"
7432 backend type and parameters
7433 Returns: ChardevReturn.
7435 Since: 1.4
7437 Example:
7439 -> { "execute" : "chardev-add",
7441 "arguments" : { "id" : "foo",
7442 "backend" : { "type" : "null", "data" : {} } } }
7443 <- { "return": {} }
7444 -> { "execute" : "chardev-add",
7446 "arguments" : { "id" : "bar",
7447 "backend" : { "type" : "file",
7448 "data" : { "out" : "/tmp/bar.log" } } } }
7449 <- { "return": {} }
7450 -> { "execute" : "chardev-add",
7452 "arguments" : { "id" : "baz",
7453 "backend" : { "type" : "pty", "data" : {} } } }
7454 <- { "return": { "pty" : "/dev/pty/42" } }
7455 chardev-change (Command) Change a character device backend
7457 Arguments:
7459 "id: string"
7461 the chardev's ID, must exist
7462 "backend: ChardevBackend"
7464 new backend type and parameters
7465 Returns: ChardevReturn.
7467 Since: 2.10
7469 Example:
7471 -> { "execute" : "chardev-change",
7473 "arguments" : { "id" : "baz",
7474 "backend" : { "type" : "pty", "data" : {} } } }
7475 <- { "return": { "pty" : "/dev/pty/42" } }
7476 -> {"execute" : "chardev-change",
7478 "arguments" : {
7479 "id" : "charchannel2",
7480 "backend" : {
7481 "type" : "socket",
7482 "data" : {
7483 "addr" : {
7484 "type" : "unix" ,
7485 "data" : {
7486 "path" : "/tmp/charchannel2.socket"
7487 }
7488 },
7489 "server" : true,
7490 "wait" : false }}}}
7491 <- {"return": {}}
7492 chardev-remove (Command) Remove a character device backend
7494 Arguments:
7496 "id: string"
7498 the chardev's ID, must exist and not be in use
7499 Returns: Nothing on success
7501 Since: 1.4
7503 Example:
7505 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
7507 <- { "return": {} }
7508 chardev-send-break (Command) Send a break to a character device
7510 Arguments:
7512 "id: string"
7514 the chardev's ID, must exist
7515 Returns: Nothing on success
7517 Since: 2.10
7519 Example:
7521 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
7523 <- { "return": {} }
7524 VSERPORT_CHANGE (Event) Emitted when the guest opens or closes a
7526 virtio-serial port.
7527 Arguments:
7529 "id: string"
7531 device identifier of the virtio-serial port
7532 "open: boolean"
7534 true if the guest has opened the virtio-serial port
7535 Since: 2.1
7537 Example:
7539 <- { "event": "VSERPORT_CHANGE",
7541 "data": { "id": "channel0", "open": true },
7542 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
7543 Net devices
7545 set_link (Command) Sets the link status of a virtual network adapter.
7546 Arguments:
7548 "name: string"
7550 the device name of the virtual network adapter
7551 "up: boolean"
7553 true to set the link status to be up
7554 Returns: Nothing on success If "name" is not a valid network device,
7556 DeviceNotFound
7557 Since: 0.14.0
7559 Notes: Not all network adapters support setting link status. This
7561 command will succeed even if the network adapter does not support link
7562 status notification.
7563 Example:
7565 -> { "execute": "set_link",
7567 "arguments": { "name": "e1000.0", "up": false } }
7568 <- { "return": {} }
7569 netdev_add (Command) Add a network backend.
7571 Arguments:
7573 "type: string"
7575 the type of network backend. Possible values are listed in
7576 NetClientDriver (excluding 'none' and 'nic')
7577 "id: string"
7579 the name of the new network backend
7580 Additional arguments depend on the type.
7582 TODO: This command effectively bypasses QAPI completely due to its
7584 "additional arguments" business. It shouldn't have been added to the
7585 schema in this form. It should be qapified properly, or replaced by a
7586 properly qapified command.
7587 Since: 0.14.0
7589 Returns: Nothing on success If "type" is not a valid network backend,
7591 DeviceNotFound
7592 Example:
7594 -> { "execute": "netdev_add",
7596 "arguments": { "type": "user", "id": "netdev1",
7597 "dnssearch": "example.org" } }
7598 <- { "return": {} }
7599 netdev_del (Command) Remove a network backend.
7601 Arguments:
7603 "id: string"
7605 the name of the network backend to remove
7606 Returns: Nothing on success If "id" is not a valid network backend,
7608 DeviceNotFound
7609 Since: 0.14.0
7611 Example:
7613 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
7615 <- { "return": {} }
7616 NetLegacyNicOptions (Object)
7618 Create a new Network Interface Card.
7620 Members:
7622 "netdev: string" (optional)
7624 id of -netdev to connect to
7625 "macaddr: string" (optional)
7627 MAC address
7628 "model: string" (optional)
7630 device model (e1000, rtl8139, virtio etc.)
7631 "addr: string" (optional)
7633 PCI device address
7634 "vectors: int" (optional)
7636 number of MSI-x vectors, 0 to disable MSI-X
7637 Since: 1.2
7639 NetdevUserOptions (Object)
7641 Use the user mode network stack which requires no administrator
7643 privilege to run.
7644 Members:
7646 "hostname: string" (optional)
7648 client hostname reported by the builtin DHCP server
7649 "restrict: boolean" (optional)
7651 isolate the guest from the host
7652 "ipv4: boolean" (optional)
7654 whether to support IPv4, default true for enabled (since 2.6)
7655 "ipv6: boolean" (optional)
7657 whether to support IPv6, default true for enabled (since 2.6)
7658 "ip: string" (optional)
7660 legacy parameter, use net= instead
7661 "net: string" (optional)
7663 IP network address that the guest will see, in the form
7664 addr[/netmask] The netmask is optional, and can be either in the
7665 form a.b.c.d or as a number of valid top-most bits. Default is
7666 10.0.2.0/24.
7667 "host: string" (optional)
7669 guest-visible address of the host
7670 "tftp: string" (optional)
7672 root directory of the built-in TFTP server
7673 "bootfile: string" (optional)
7675 BOOTP filename, for use with tftp=
7676 "dhcpstart: string" (optional)
7678 the first of the 16 IPs the built-in DHCP server can assign
7679 "dns: string" (optional)
7681 guest-visible address of the virtual nameserver
7682 "dnssearch: array of String" (optional)
7684 list of DNS suffixes to search, passed as DHCP option to the guest
7685 "domainname: string" (optional)
7687 guest-visible domain name of the virtual nameserver (since 3.0)
7688 "ipv6-prefix: string" (optional)
7690 IPv6 network prefix (default is fec0::) (since 2.6). The network
7691 prefix is given in the usual hexadecimal IPv6 address notation.
7692 "ipv6-prefixlen: int" (optional)
7694 IPv6 network prefix length (default is 64) (since 2.6)
7695 "ipv6-host: string" (optional)
7697 guest-visible IPv6 address of the host (since 2.6)
7698 "ipv6-dns: string" (optional)
7700 guest-visible IPv6 address of the virtual nameserver (since 2.6)
7701 "smb: string" (optional)
7703 root directory of the built-in SMB server
7704 "smbserver: string" (optional)
7706 IP address of the built-in SMB server
7707 "hostfwd: array of String" (optional)
7709 redirect incoming TCP or UDP host connections to guest endpoints
7710 "guestfwd: array of String" (optional)
7712 forward guest TCP connections
7713 "tftp-server-name: string" (optional)
7715 RFC2132 "TFTP server name" string (Since 3.1)
7716 Since: 1.2
7718 NetdevTapOptions (Object)
7720 Used to configure a host TAP network interface backend.
7722 Members:
7724 "ifname: string" (optional)
7726 interface name
7727 "fd: string" (optional)
7729 file descriptor of an already opened tap
7730 "fds: string" (optional)
7732 multiple file descriptors of already opened multiqueue capable tap
7733 "script: string" (optional)
7735 script to initialize the interface
7736 "downscript: string" (optional)
7738 script to shut down the interface
7739 "br: string" (optional)
7741 bridge name (since 2.8)
7742 "helper: string" (optional)
7744 command to execute to configure bridge
7745 "sndbuf: int" (optional)
7747 send buffer limit. Understands [TGMKkb] suffixes.
7748 "vnet_hdr: boolean" (optional)
7750 enable the IFF_VNET_HDR flag on the tap interface
7751 "vhost: boolean" (optional)
7753 enable vhost-net network accelerator
7754 "vhostfd: string" (optional)
7756 file descriptor of an already opened vhost net device
7757 "vhostfds: string" (optional)
7759 file descriptors of multiple already opened vhost net devices
7760 "vhostforce: boolean" (optional)
7762 vhost on for non-MSIX virtio guests
7763 "queues: int" (optional)
7765 number of queues to be created for multiqueue capable tap
7766 "poll-us: int" (optional)
7768 maximum number of microseconds that could be spent on busy polling
7769 for tap (since 2.7)
7770 Since: 1.2
7772 NetdevSocketOptions (Object)
7774 Socket netdevs are used to establish a network connection to another
7776 QEMU virtual machine via a TCP socket.
7777 Members:
7779 "fd: string" (optional)
7781 file descriptor of an already opened socket
7782 "listen: string" (optional)
7784 port number, and optional hostname, to listen on
7785 "connect: string" (optional)
7787 port number, and optional hostname, to connect to
7788 "mcast: string" (optional)
7790 UDP multicast address and port number
7791 "localaddr: string" (optional)
7793 source address and port for multicast and udp packets
7794 "udp: string" (optional)
7796 UDP unicast address and port number
7797 Since: 1.2
7799 NetdevL2TPv3Options (Object)
7801 Configure an Ethernet over L2TPv3 tunnel.
7803 Members:
7805 "src: string"
7807 source address
7808 "dst: string"
7810 destination address
7811 "srcport: string" (optional)
7813 source port - mandatory for udp, optional for ip
7814 "dstport: string" (optional)
7816 destination port - mandatory for udp, optional for ip
7817 "ipv6: boolean" (optional)
7819 force the use of ipv6
7820 "udp: boolean" (optional)
7822 use the udp version of l2tpv3 encapsulation
7823 "cookie64: boolean" (optional)
7825 use 64 bit coookies
7826 "counter: boolean" (optional)
7828 have sequence counter
7829 "pincounter: boolean" (optional)
7831 pin sequence counter to zero - workaround for buggy implementations
7832 or networks with packet reorder
7833 "txcookie: int" (optional)
7835 32 or 64 bit transmit cookie
7836 "rxcookie: int" (optional)
7838 32 or 64 bit receive cookie
7839 "txsession: int"
7841 32 bit transmit session
7842 "rxsession: int" (optional)
7844 32 bit receive session - if not specified set to the same value as
7845 transmit
7846 "offset: int" (optional)
7848 additional offset - allows the insertion of additional application-
7849 specific data before the packet payload
7850 Since: 2.1
7852 NetdevVdeOptions (Object)
7854 Connect to a vde switch running on the host.
7856 Members:
7858 "sock: string" (optional)
7860 socket path
7861 "port: int" (optional)
7863 port number
7864 "group: string" (optional)
7866 group owner of socket
7867 "mode: int" (optional)
7869 permissions for socket
7870 Since: 1.2
7872 NetdevBridgeOptions (Object)
7874 Connect a host TAP network interface to a host bridge device.
7876 Members:
7878 "br: string" (optional)
7880 bridge name
7881 "helper: string" (optional)
7883 command to execute to configure bridge
7884 Since: 1.2
7886 NetdevHubPortOptions (Object)
7888 Connect two or more net clients through a software hub.
7890 Members:
7892 "hubid: int"
7894 hub identifier number
7895 "netdev: string" (optional)
7897 used to connect hub to a netdev instead of a device (since 2.12)
7898 Since: 1.2
7900 NetdevNetmapOptions (Object)
7902 Connect a client to a netmap-enabled NIC or to a VALE switch port
7904 Members:
7906 "ifname: string"
7908 Either the name of an existing network interface supported by
7909 netmap, or the name of a VALE port (created on the fly). A VALE
7910 port name is in the form 'valeXXX:YYY', where XXX and YYY are non-
7911 negative integers. XXX identifies a switch and YYY identifies a
7912 port of the switch. VALE ports having the same XXX are therefore
7913 connected to the same switch.
7914 "devname: string" (optional)
7916 path of the netmap device (default: '/dev/netmap').
7917 Since: 2.0
7919 NetdevVhostUserOptions (Object)
7921 Vhost-user network backend
7923 Members:
7925 "chardev: string"
7927 name of a unix socket chardev
7928 "vhostforce: boolean" (optional)
7930 vhost on for non-MSIX virtio guests (default: false).
7931 "queues: int" (optional)
7933 number of queues to be created for multiqueue vhost-user (default:
7934 1) (Since 2.5)
7935 Since: 2.1
7937 NetClientDriver (Enum)
7939 Available netdev drivers.
7941 Values:
7943 "none"
7945 Not documented
7946 "nic"
7948 Not documented
7949 "user"
7951 Not documented
7952 "tap"
7954 Not documented
7955 "l2tpv3"
7957 Not documented
7958 "socket"
7960 Not documented
7961 "vde"
7963 Not documented
7964 "bridge"
7966 Not documented
7967 "hubport"
7969 Not documented
7970 "netmap"
7972 Not documented
7973 "vhost-user"
7975 Not documented
7976 Since: 2.7
7978 'dump': dropped in 2.12
7980 Netdev (Object)
7982 Captures the configuration of a network device.
7984 Members:
7986 "id: string"
7988 identifier for monitor commands.
7989 "type: NetClientDriver"
7991 Specify the driver used for interpreting remaining arguments.
7992 The members of "NetLegacyNicOptions" when "type" is "nic"
7994 The members of "NetdevUserOptions" when "type" is "user"
7995 The members of "NetdevTapOptions" when "type" is "tap"
7996 The members of "NetdevL2TPv3Options" when "type" is "l2tpv3"
7997 The members of "NetdevSocketOptions" when "type" is "socket"
7998 The members of "NetdevVdeOptions" when "type" is "vde"
7999 The members of "NetdevBridgeOptions" when "type" is "bridge"
8000 The members of "NetdevHubPortOptions" when "type" is "hubport"
8001 The members of "NetdevNetmapOptions" when "type" is "netmap"
8002 The members of "NetdevVhostUserOptions" when "type" is "vhost-user"
8003 Since: 1.2
8005 'l2tpv3' - since 2.1
8007 NetLegacy (Object)
8009 Captures the configuration of a network device; legacy.
8011 Members:
8013 "id: string" (optional)
8015 identifier for monitor commands
8016 "name: string" (optional)
8018 identifier for monitor commands, ignored if "id" is present
8019 "opts: NetLegacyOptions"
8021 device type specific properties (legacy)
8022 Since: 1.2
8024 'vlan': dropped in 3.0
8026 NetLegacyOptionsType (Enum)
8028 Values:
8030 "none"
8032 Not documented
8033 "nic"
8035 Not documented
8036 "user"
8038 Not documented
8039 "tap"
8041 Not documented
8042 "l2tpv3"
8044 Not documented
8045 "socket"
8047 Not documented
8048 "vde"
8050 Not documented
8051 "bridge"
8053 Not documented
8054 "netmap"
8056 Not documented
8057 "vhost-user"
8059 Not documented
8060 Since: 1.2
8062 NetLegacyOptions (Object)
8064 Like Netdev, but for use only by the legacy command line options
8066 Members:
8068 "type: NetLegacyOptionsType"
8070 Not documented
8071 The members of "NetLegacyNicOptions" when "type" is "nic"
8073 The members of "NetdevUserOptions" when "type" is "user"
8074 The members of "NetdevTapOptions" when "type" is "tap"
8075 The members of "NetdevL2TPv3Options" when "type" is "l2tpv3"
8076 The members of "NetdevSocketOptions" when "type" is "socket"
8077 The members of "NetdevVdeOptions" when "type" is "vde"
8078 The members of "NetdevBridgeOptions" when "type" is "bridge"
8079 The members of "NetdevNetmapOptions" when "type" is "netmap"
8080 The members of "NetdevVhostUserOptions" when "type" is "vhost-user"
8081 Since: 1.2
8083 NetFilterDirection (Enum)
8085 Indicates whether a netfilter is attached to a netdev's transmit queue
8087 or receive queue or both.
8088 Values:
8090 "all"
8092 the filter is attached both to the receive and the transmit queue
8093 of the netdev (default).
8094 "rx"
8096 the filter is attached to the receive queue of the netdev, where it
8097 will receive packets sent to the netdev.
8098 "tx"
8100 the filter is attached to the transmit queue of the netdev, where
8101 it will receive packets sent by the netdev.
8102 Since: 2.5
8104 RxState (Enum)
8106 Packets receiving state
8108 Values:
8110 "normal"
8112 filter assigned packets according to the mac-table
8113 "none"
8115 don't receive any assigned packet
8116 "all"
8118 receive all assigned packets
8119 Since: 1.6
8121 RxFilterInfo (Object)
8123 Rx-filter information for a NIC.
8125 Members:
8127 "name: string"
8129 net client name
8130 "promiscuous: boolean"
8132 whether promiscuous mode is enabled
8133 "multicast: RxState"
8135 multicast receive state
8136 "unicast: RxState"
8138 unicast receive state
8139 "vlan: RxState"
8141 vlan receive state (Since 2.0)
8142 "broadcast-allowed: boolean"
8144 whether to receive broadcast
8145 "multicast-overflow: boolean"
8147 multicast table is overflowed or not
8148 "unicast-overflow: boolean"
8150 unicast table is overflowed or not
8151 "main-mac: string"
8153 the main macaddr string
8154 "vlan-table: array of int"
8156 a list of active vlan id
8157 "unicast-table: array of string"
8159 a list of unicast macaddr string
8160 "multicast-table: array of string"
8162 a list of multicast macaddr string
8163 Since: 1.6
8165 query-rx-filter (Command) Return rx-filter information for all NICs
8167 (or for the given NIC).
8168 Arguments:
8170 "name: string" (optional)
8172 net client name
8173 Returns: list of "RxFilterInfo" for all NICs (or for the given NIC).
8175 Returns an error if the given "name" doesn't exist, or given NIC
8176 doesn't support rx-filter querying, or given net client isn't a NIC.
8177 Since: 1.6
8179 Example:
8181 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
8183 <- { "return": [
8184 {
8185 "promiscuous": true,
8186 "name": "vnet0",
8187 "main-mac": "52:54:00:12:34:56",
8188 "unicast": "normal",
8189 "vlan": "normal",
8190 "vlan-table": [
8191 4,
8192 0
8193 ],
8194 "unicast-table": [
8195 ],
8196 "multicast": "normal",
8197 "multicast-overflow": false,
8198 "unicast-overflow": false,
8199 "multicast-table": [
8200 "01:00:5e:00:00:01",
8201 "33:33:00:00:00:01",
8202 "33:33:ff:12:34:56"
8203 ],
8204 "broadcast-allowed": false
8205 }
8206 ]
8207 }
8208 NIC_RX_FILTER_CHANGED (Event) Emitted once until the 'query-rx-filter'
8210 command is executed, the first event will always be emitted
8211 Arguments:
8213 "name: string" (optional)
8215 net client name
8216 "path: string"
8218 device path
8219 Since: 1.6
8221 Example:
8223 <- { "event": "NIC_RX_FILTER_CHANGED",
8225 "data": { "name": "vnet0",
8226 "path": "/machine/peripheral/vnet0/virtio-backend" },
8227 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
8228 }
8229 Rocker switch device
8231 RockerSwitch (Object)
8232 Rocker switch information.
8234 Members:
8236 "name: string"
8238 switch name
8239 "id: int"
8241 switch ID
8242 "ports: int"
8244 number of front-panel ports
8245 Since: 2.4
8247 query-rocker (Command) Return rocker switch information.
8249 Arguments:
8251 "name: string"
8253 Not documented
8254 Returns: "Rocker" information
8256 Since: 2.4
8258 Example:
8260 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
8262 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
8263 RockerPortDuplex (Enum)
8265 An eumeration of port duplex states.
8267 Values:
8269 "half"
8271 half duplex
8272 "full"
8274 full duplex
8275 Since: 2.4
8277 RockerPortAutoneg (Enum)
8279 An eumeration of port autoneg states.
8281 Values:
8283 "off"
8285 autoneg is off
8286 "on"
8288 autoneg is on
8289 Since: 2.4
8291 RockerPort (Object)
8293 Rocker switch port information.
8295 Members:
8297 "name: string"
8299 port name
8300 "enabled: boolean"
8302 port is enabled for I/O
8303 "link-up: boolean"
8305 physical link is UP on port
8306 "speed: int"
8308 port link speed in Mbps
8309 "duplex: RockerPortDuplex"
8311 port link duplex
8312 "autoneg: RockerPortAutoneg"
8314 port link autoneg
8315 Since: 2.4
8317 query-rocker-ports (Command) Return rocker switch port information.
8319 Arguments:
8321 "name: string"
8323 Not documented
8324 Returns: a list of "RockerPort" information
8326 Since: 2.4
8328 Example:
8330 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
8332 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
8333 "autoneg": "off", "link-up": true, "speed": 10000},
8334 {"duplex": "full", "enabled": true, "name": "sw1.2",
8335 "autoneg": "off", "link-up": true, "speed": 10000}
8336 ]}
8337 RockerOfDpaFlowKey (Object)
8339 Rocker switch OF-DPA flow key
8341 Members:
8343 "priority: int"
8345 key priority, 0 being lowest priority
8346 "tbl-id: int"
8348 flow table ID
8349 "in-pport: int" (optional)
8351 physical input port
8352 "tunnel-id: int" (optional)
8354 tunnel ID
8355 "vlan-id: int" (optional)
8357 VLAN ID
8358 "eth-type: int" (optional)
8360 Ethernet header type
8361 "eth-src: string" (optional)
8363 Ethernet header source MAC address
8364 "eth-dst: string" (optional)
8366 Ethernet header destination MAC address
8367 "ip-proto: int" (optional)
8369 IP Header protocol field
8370 "ip-tos: int" (optional)
8372 IP header TOS field
8373 "ip-dst: string" (optional)
8375 IP header destination address
8376 Note: optional members may or may not appear in the flow key depending
8378 if they're relevant to the flow key.
8379 Since: 2.4
8381 RockerOfDpaFlowMask (Object)
8383 Rocker switch OF-DPA flow mask
8385 Members:
8387 "in-pport: int" (optional)
8389 physical input port
8390 "tunnel-id: int" (optional)
8392 tunnel ID
8393 "vlan-id: int" (optional)
8395 VLAN ID
8396 "eth-src: string" (optional)
8398 Ethernet header source MAC address
8399 "eth-dst: string" (optional)
8401 Ethernet header destination MAC address
8402 "ip-proto: int" (optional)
8404 IP Header protocol field
8405 "ip-tos: int" (optional)
8407 IP header TOS field
8408 Note: optional members may or may not appear in the flow mask depending
8410 if they're relevant to the flow mask.
8411 Since: 2.4
8413 RockerOfDpaFlowAction (Object)
8415 Rocker switch OF-DPA flow action
8417 Members:
8419 "goto-tbl: int" (optional)
8421 next table ID
8422 "group-id: int" (optional)
8424 group ID
8425 "tunnel-lport: int" (optional)
8427 tunnel logical port ID
8428 "vlan-id: int" (optional)
8430 VLAN ID
8431 "new-vlan-id: int" (optional)
8433 new VLAN ID
8434 "out-pport: int" (optional)
8436 physical output port
8437 Note: optional members may or may not appear in the flow action
8439 depending if they're relevant to the flow action.
8440 Since: 2.4
8442 RockerOfDpaFlow (Object)
8444 Rocker switch OF-DPA flow
8446 Members:
8448 "cookie: int"
8450 flow unique cookie ID
8451 "hits: int"
8453 count of matches (hits) on flow
8454 "key: RockerOfDpaFlowKey"
8456 flow key
8457 "mask: RockerOfDpaFlowMask"
8459 flow mask
8460 "action: RockerOfDpaFlowAction"
8462 flow action
8463 Since: 2.4
8465 query-rocker-of-dpa-flows (Command) Return rocker OF-DPA flow
8467 information.
8468 Arguments:
8470 "name: string"
8472 switch name
8473 "tbl-id: int" (optional)
8475 flow table ID. If tbl-id is not specified, returns flow
8476 information for all tables.
8477 Returns: rocker OF-DPA flow information
8479 Since: 2.4
8481 Example:
8483 -> { "execute": "query-rocker-of-dpa-flows",
8485 "arguments": { "name": "sw1" } }
8486 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
8487 "hits": 138,
8488 "cookie": 0,
8489 "action": {"goto-tbl": 10},
8490 "mask": {"in-pport": 4294901760}
8491 },
8492 {...more...},
8493 ]}
8494 RockerOfDpaGroup (Object)
8496 Rocker switch OF-DPA group
8498 Members:
8500 "id: int"
8502 group unique ID
8503 "type: int"
8505 group type
8506 "vlan-id: int" (optional)
8508 VLAN ID
8509 "pport: int" (optional)
8511 physical port number
8512 "index: int" (optional)
8514 group index, unique with group type
8515 "out-pport: int" (optional)
8517 output physical port number
8518 "group-id: int" (optional)
8520 next group ID
8521 "set-vlan-id: int" (optional)
8523 VLAN ID to set
8524 "pop-vlan: int" (optional)
8526 pop VLAN headr from packet
8527 "group-ids: array of int" (optional)
8529 list of next group IDs
8530 "set-eth-src: string" (optional)
8532 set source MAC address in Ethernet header
8533 "set-eth-dst: string" (optional)
8535 set destination MAC address in Ethernet header
8536 "ttl-check: int" (optional)
8538 perform TTL check
8539 Note: optional members may or may not appear in the group depending if
8541 they're relevant to the group type.
8542 Since: 2.4
8544 query-rocker-of-dpa-groups (Command) Return rocker OF-DPA group
8546 information.
8547 Arguments:
8549 "name: string"
8551 switch name
8552 "type: int" (optional)
8554 group type. If type is not specified, returns group information
8555 for all group types.
8556 Returns: rocker OF-DPA group information
8558 Since: 2.4
8560 Example:
8562 -> { "execute": "query-rocker-of-dpa-groups",
8564 "arguments": { "name": "sw1" } }
8565 <- { "return": [ {"type": 0, "out-pport": 2,
8566 "pport": 2, "vlan-id": 3841,
8567 "pop-vlan": 1, "id": 251723778},
8568 {"type": 0, "out-pport": 0,
8569 "pport": 0, "vlan-id": 3841,
8570 "pop-vlan": 1, "id": 251723776},
8571 {"type": 0, "out-pport": 1,
8572 "pport": 1, "vlan-id": 3840,
8573 "pop-vlan": 1, "id": 251658241},
8574 {"type": 0, "out-pport": 0,
8575 "pport": 0, "vlan-id": 3840,
8576 "pop-vlan": 1, "id": 251658240}
8577 ]}
8578 TPM (trusted platform module) devices
8580 TpmModel (Enum)
8581 An enumeration of TPM models
8583 Values:
8585 "tpm-tis"
8587 TPM TIS model
8588 "tpm-crb"
8590 TPM CRB model (since 2.12)
8591 Since: 1.5
8593 query-tpm-models (Command) Return a list of supported TPM models
8595 Returns: a list of TpmModel
8597 Since: 1.5
8599 Example:
8601 -> { "execute": "query-tpm-models" }
8603 <- { "return": [ "tpm-tis", "tpm-crb" ] }
8604 TpmType (Enum)
8606 An enumeration of TPM types
8608 Values:
8610 "passthrough"
8612 TPM passthrough type
8613 "emulator"
8615 Software Emulator TPM type Since: 2.11
8616 Since: 1.5
8618 query-tpm-types (Command) Return a list of supported TPM types
8620 Returns: a list of TpmType
8622 Since: 1.5
8624 Example:
8626 -> { "execute": "query-tpm-types" }
8628 <- { "return": [ "passthrough", "emulator" ] }
8629 TPMPassthroughOptions (Object)
8631 Information about the TPM passthrough type
8633 Members:
8635 "path: string" (optional)
8637 string describing the path used for accessing the TPM device
8638 "cancel-path: string" (optional)
8640 string showing the TPM's sysfs cancel file for cancellation of TPM
8641 commands while they are executing
8642 Since: 1.5
8644 TPMEmulatorOptions (Object)
8646 Information about the TPM emulator type
8648 Members:
8650 "chardev: string"
8652 Name of a unix socket chardev
8653 Since: 2.11
8655 TpmTypeOptions (Object)
8657 A union referencing different TPM backend types' configuration options
8659 Members:
8661 "type"
8663 'passthrough' The configuration options for the TPM passthrough
8664 type 'emulator' The configuration options for TPM emulator backend
8665 type
8666 "data: TPMPassthroughOptions" when "type" is "passthrough"
8668 "data: TPMEmulatorOptions" when "type" is "emulator"
8669 Since: 1.5
8671 TPMInfo (Object)
8673 Information about the TPM
8675 Members:
8677 "id: string"
8679 The Id of the TPM
8680 "model: TpmModel"
8682 The TPM frontend model
8683 "options: TpmTypeOptions"
8685 The TPM (backend) type configuration options
8686 Since: 1.5
8688 query-tpm (Command) Return information about the TPM device
8690 Returns: "TPMInfo" on success
8692 Since: 1.5
8694 Example:
8696 -> { "execute": "query-tpm" }
8698 <- { "return":
8699 [
8700 { "model": "tpm-tis",
8701 "options":
8702 { "type": "passthrough",
8703 "data":
8704 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
8705 "path": "/dev/tpm0"
8706 }
8707 },
8708 "id": "tpm0"
8709 }
8710 ]
8711 }
8712 Remote desktop
8714 set_password (Command) Sets the password of a remote display session.
8715 Arguments:
8717 "protocol: string"
8719 `vnc' to modify the VNC server password `spice' to modify the Spice
8720 server password
8721 "password: string"
8723 the new password
8724 "connected: string" (optional)
8726 how to handle existing clients when changing the password. If
8727 nothing is specified, defaults to `keep' `fail' to fail the command
8728 if clients are connected `disconnect' to disconnect existing
8729 clients `keep' to maintain existing clients
8730 Returns: Nothing on success If Spice is not enabled, DeviceNotFound
8732 Since: 0.14.0
8734 Example:
8736 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
8738 "password": "secret" } }
8739 <- { "return": {} }
8740 expire_password (Command) Expire the password of a remote display
8742 server.
8743 Arguments:
8745 "protocol: string"
8747 the name of the remote display protocol `vnc' or `spice'
8748 "time: string"
8750 when to expire the password. `now' to expire the password
8751 immediately `never' to cancel password expiration `+INT' where INT
8752 is the number of seconds from now (integer) `INT' where INT is the
8753 absolute time in seconds
8754 Returns: Nothing on success If "protocol" is `spice' and Spice is not
8756 active, DeviceNotFound
8757 Since: 0.14.0
8759 Notes: Time is relative to the server and currently there is no way to
8761 coordinate server time with client time. It is not recommended to use
8762 the absolute time version of the "time" parameter unless you're sure
8763 you are on the same machine as the QEMU instance.
8764 Example:
8766 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
8768 "time": "+60" } }
8769 <- { "return": {} }
8770 screendump (Command) Write a PPM of the VGA screen to a file.
8772 Arguments:
8774 "filename: string"
8776 the path of a new PPM file to store the image
8777 "device: string" (optional)
8779 ID of the display device that should be dumped. If this parameter
8780 is missing, the primary display will be used. (Since 2.12)
8781 "head: int" (optional)
8783 head to use in case the device supports multiple heads. If this
8784 parameter is missing, head #0 will be used. Also note that the head
8785 can only be specified in conjunction with the device ID. (Since
8786 2.12)
8787 Returns: Nothing on success
8789 Since: 0.14.0
8791 Example:
8793 -> { "execute": "screendump",
8795 "arguments": { "filename": "/tmp/image" } }
8796 <- { "return": {} }
8797 Spice
8799 SpiceBasicInfo (Object)
8801 The basic information for SPICE network connection
8803 Members:
8805 "host: string"
8807 IP address
8808 "port: string"
8810 port number
8811 "family: NetworkAddressFamily"
8813 address family
8814 Since: 2.1
8816 If: "defined(CONFIG_SPICE)"
8818 SpiceServerInfo (Object)
8820 Information about a SPICE server
8822 Members:
8824 "auth: string" (optional)
8826 authentication method
8827 The members of "SpiceBasicInfo"
8829 Since: 2.1
8831 If: "defined(CONFIG_SPICE)"
8833 SpiceChannel (Object)
8835 Information about a SPICE client channel.
8837 Members:
8839 "connection-id: int"
8841 SPICE connection id number. All channels with the same id belong
8842 to the same SPICE session.
8843 "channel-type: int"
8845 SPICE channel type number. "1" is the main control channel, filter
8846 for this one if you want to track spice sessions only
8847 "channel-id: int"
8849 SPICE channel ID number. Usually "0", might be different when
8850 multiple channels of the same type exist, such as multiple display
8851 channels in a multihead setup
8852 "tls: boolean"
8854 true if the channel is encrypted, false otherwise.
8855 The members of "SpiceBasicInfo"
8857 Since: 0.14.0
8859 If: "defined(CONFIG_SPICE)"
8861 SpiceQueryMouseMode (Enum)
8863 An enumeration of Spice mouse states.
8865 Values:
8867 "client"
8869 Mouse cursor position is determined by the client.
8870 "server"
8872 Mouse cursor position is determined by the server.
8873 "unknown"
8875 No information is available about mouse mode used by the spice
8876 server.
8877 Note: spice/enums.h has a SpiceMouseMode already, hence the name.
8879 Since: 1.1
8881 If: "defined(CONFIG_SPICE)"
8883 SpiceInfo (Object)
8885 Information about the SPICE session.
8887 Members:
8889 "enabled: boolean"
8891 true if the SPICE server is enabled, false otherwise
8892 "migrated: boolean"
8894 true if the last guest migration completed and spice migration had
8895 completed as well. false otherwise. (since 1.4)
8896 "host: string" (optional)
8898 The hostname the SPICE server is bound to. This depends on the
8899 name resolution on the host and may be an IP address.
8900 "port: int" (optional)
8902 The SPICE server's port number.
8903 "compiled-version: string" (optional)
8905 SPICE server version.
8906 "tls-port: int" (optional)
8908 The SPICE server's TLS port number.
8909 "auth: string" (optional)
8911 the current authentication type used by the server 'none' if no
8912 authentication is being used 'spice' uses SASL or direct TLS
8913 authentication, depending on command line options
8914 "mouse-mode: SpiceQueryMouseMode"
8916 The mode in which the mouse cursor is displayed currently. Can be
8917 determined by the client or the server, or unknown if spice server
8918 doesn't provide this information. (since: 1.1)
8919 "channels: array of SpiceChannel" (optional)
8921 a list of "SpiceChannel" for each active spice channel
8922 Since: 0.14.0
8924 If: "defined(CONFIG_SPICE)"
8926 query-spice (Command) Returns information about the current SPICE
8928 server
8929 Returns: "SpiceInfo"
8931 Since: 0.14.0
8933 Example:
8935 -> { "execute": "query-spice" }
8937 <- { "return": {
8938 "enabled": true,
8939 "auth": "spice",
8940 "port": 5920,
8941 "tls-port": 5921,
8942 "host": "0.0.0.0",
8943 "channels": [
8944 {
8945 "port": "54924",
8946 "family": "ipv4",
8947 "channel-type": 1,
8948 "connection-id": 1804289383,
8949 "host": "127.0.0.1",
8950 "channel-id": 0,
8951 "tls": true
8952 },
8953 {
8954 "port": "36710",
8955 "family": "ipv4",
8956 "channel-type": 4,
8957 "connection-id": 1804289383,
8958 "host": "127.0.0.1",
8959 "channel-id": 0,
8960 "tls": false
8961 },
8962 [ ... more channels follow ... ]
8963 ]
8964 }
8965 }
8966 If: "defined(CONFIG_SPICE)"
8968 SPICE_CONNECTED (Event) Emitted when a SPICE client establishes a
8970 connection
8971 Arguments:
8973 "server: SpiceBasicInfo"
8975 server information
8976 "client: SpiceBasicInfo"
8978 client information
8979 Since: 0.14.0
8981 Example:
8983 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
8985 "event": "SPICE_CONNECTED",
8986 "data": {
8987 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
8988 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
8989 }}
8990 If: "defined(CONFIG_SPICE)"
8992 SPICE_INITIALIZED (Event) Emitted after initial handshake and
8994 authentication takes place (if any) and the SPICE channel is up and
8995 running
8996 Arguments:
8998 "server: SpiceServerInfo"
9000 server information
9001 "client: SpiceChannel"
9003 client information
9004 Since: 0.14.0
9006 Example:
9008 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
9010 "event": "SPICE_INITIALIZED",
9011 "data": {"server": {"auth": "spice", "port": "5921",
9012 "family": "ipv4", "host": "127.0.0.1"},
9013 "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
9014 "connection-id": 1804289383, "host": "127.0.0.1",
9015 "channel-id": 0, "tls": true}
9016 }}
9017 If: "defined(CONFIG_SPICE)"
9019 SPICE_DISCONNECTED (Event) Emitted when the SPICE connection is closed
9021 Arguments:
9023 "server: SpiceBasicInfo"
9025 server information
9026 "client: SpiceBasicInfo"
9028 client information
9029 Since: 0.14.0
9031 Example:
9033 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
9035 "event": "SPICE_DISCONNECTED",
9036 "data": {
9037 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
9038 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
9039 }}
9040 If: "defined(CONFIG_SPICE)"
9042 SPICE_MIGRATE_COMPLETED (Event) Emitted when SPICE migration has
9044 completed
9045 Since: 1.3
9047 Example:
9049 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
9051 "event": "SPICE_MIGRATE_COMPLETED" }
9052 If: "defined(CONFIG_SPICE)"
9054 VNC
9056 VncBasicInfo (Object)
9058 The basic information for vnc network connection
9060 Members:
9062 "host: string"
9064 IP address
9065 "service: string"
9067 The service name of the vnc port. This may depend on the host
9068 system's service database so symbolic names should not be relied
9069 on.
9070 "family: NetworkAddressFamily"
9072 address family
9073 "websocket: boolean"
9075 true in case the socket is a websocket (since 2.3).
9076 Since: 2.1
9078 If: "defined(CONFIG_VNC)"
9080 VncServerInfo (Object)
9082 The network connection information for server
9084 Members:
9086 "auth: string" (optional)
9088 authentication method used for the plain (non-websocket) VNC server
9089 The members of "VncBasicInfo"
9091 Since: 2.1
9093 If: "defined(CONFIG_VNC)"
9095 VncClientInfo (Object)
9097 Information about a connected VNC client.
9099 Members:
9101 "x509_dname: string" (optional)
9103 If x509 authentication is in use, the Distinguished Name of the
9104 client.
9105 "sasl_username: string" (optional)
9107 If SASL authentication is in use, the SASL username used for
9108 authentication.
9109 The members of "VncBasicInfo"
9111 Since: 0.14.0
9113 If: "defined(CONFIG_VNC)"
9115 VncInfo (Object)
9117 Information about the VNC session.
9119 Members:
9121 "enabled: boolean"
9123 true if the VNC server is enabled, false otherwise
9124 "host: string" (optional)
9126 The hostname the VNC server is bound to. This depends on the name
9127 resolution on the host and may be an IP address.
9128 "family: NetworkAddressFamily" (optional)
9130 'ipv6' if the host is listening for IPv6 connections 'ipv4' if the
9131 host is listening for IPv4 connections 'unix' if the host is
9132 listening on a unix domain socket 'unknown' otherwise
9133 "service: string" (optional)
9135 The service name of the server's port. This may depends on the
9136 host system's service database so symbolic names should not be
9137 relied on.
9138 "auth: string" (optional)
9140 the current authentication type used by the server 'none' if no
9141 authentication is being used 'vnc' if VNC authentication is being
9142 used 'vencrypt+plain' if VEncrypt is used with plain text
9143 authentication 'vencrypt+tls+none' if VEncrypt is used with TLS and
9144 no authentication 'vencrypt+tls+vnc' if VEncrypt is used with TLS
9145 and VNC authentication 'vencrypt+tls+plain' if VEncrypt is used
9146 with TLS and plain text auth 'vencrypt+x509+none' if VEncrypt is
9147 used with x509 and no auth 'vencrypt+x509+vnc' if VEncrypt is used
9148 with x509 and VNC auth 'vencrypt+x509+plain' if VEncrypt is used
9149 with x509 and plain text auth 'vencrypt+tls+sasl' if VEncrypt is
9150 used with TLS and SASL auth 'vencrypt+x509+sasl' if VEncrypt is
9151 used with x509 and SASL auth
9152 "clients: array of VncClientInfo" (optional)
9154 a list of "VncClientInfo" of all currently connected clients
9155 Since: 0.14.0
9157 If: "defined(CONFIG_VNC)"
9159 VncPrimaryAuth (Enum)
9161 vnc primary authentication method.
9163 Values:
9165 "none"
9167 Not documented
9168 "vnc"
9170 Not documented
9171 "ra2"
9173 Not documented
9174 "ra2ne"
9176 Not documented
9177 "tight"
9179 Not documented
9180 "ultra"
9182 Not documented
9183 "tls"
9185 Not documented
9186 "vencrypt"
9188 Not documented
9189 "sasl"
9191 Not documented
9192 Since: 2.3
9194 If: "defined(CONFIG_VNC)"
9196 VncVencryptSubAuth (Enum)
9198 vnc sub authentication method with vencrypt.
9200 Values:
9202 "plain"
9204 Not documented
9205 "tls-none"
9207 Not documented
9208 "x509-none"
9210 Not documented
9211 "tls-vnc"
9213 Not documented
9214 "x509-vnc"
9216 Not documented
9217 "tls-plain"
9219 Not documented
9220 "x509-plain"
9222 Not documented
9223 "tls-sasl"
9225 Not documented
9226 "x509-sasl"
9228 Not documented
9229 Since: 2.3
9231 If: "defined(CONFIG_VNC)"
9233 VncServerInfo2 (Object)
9235 The network connection information for server
9237 Members:
9239 "auth: VncPrimaryAuth"
9241 The current authentication type used by the servers
9242 "vencrypt: VncVencryptSubAuth" (optional)
9244 The vencrypt sub authentication type used by the servers, only
9245 specified in case auth == vencrypt.
9246 The members of "VncBasicInfo"
9248 Since: 2.9
9250 If: "defined(CONFIG_VNC)"
9252 VncInfo2 (Object)
9254 Information about a vnc server
9256 Members:
9258 "id: string"
9260 vnc server name.
9261 "server: array of VncServerInfo2"
9263 A list of "VncBasincInfo" describing all listening sockets. The
9264 list can be empty (in case the vnc server is disabled). It also
9265 may have multiple entries: normal + websocket, possibly also ipv4 +
9266 ipv6 in the future.
9267 "clients: array of VncClientInfo"
9269 A list of "VncClientInfo" of all currently connected clients. The
9270 list can be empty, for obvious reasons.
9271 "auth: VncPrimaryAuth"
9273 The current authentication type used by the non-websockets servers
9274 "vencrypt: VncVencryptSubAuth" (optional)
9276 The vencrypt authentication type used by the servers, only
9277 specified in case auth == vencrypt.
9278 "display: string" (optional)
9280 The display device the vnc server is linked to.
9281 Since: 2.3
9283 If: "defined(CONFIG_VNC)"
9285 query-vnc (Command) Returns information about the current VNC server
9287 Returns: "VncInfo"
9289 Since: 0.14.0
9291 Example:
9293 -> { "execute": "query-vnc" }
9295 <- { "return": {
9296 "enabled":true,
9297 "host":"0.0.0.0",
9298 "service":"50402",
9299 "auth":"vnc",
9300 "family":"ipv4",
9301 "clients":[
9302 {
9303 "host":"127.0.0.1",
9304 "service":"50401",
9305 "family":"ipv4"
9306 }
9307 ]
9308 }
9309 }
9310 If: "defined(CONFIG_VNC)"
9312 query-vnc-servers (Command) Returns a list of vnc servers. The list
9314 can be empty.
9315 Returns: a list of "VncInfo2"
9317 Since: 2.3
9319 If: "defined(CONFIG_VNC)"
9321 change-vnc-password (Command) Change the VNC server password.
9323 Arguments:
9325 "password: string"
9327 the new password to use with VNC authentication
9328 Since: 1.1
9330 Notes: An empty password in this command will set the password to the
9332 empty string. Existing clients are unaffected by executing this
9333 command.
9334 If: "defined(CONFIG_VNC)"
9336 VNC_CONNECTED (Event) Emitted when a VNC client establishes a
9338 connection
9339 Arguments:
9341 "server: VncServerInfo"
9343 server information
9344 "client: VncBasicInfo"
9346 client information
9347 Note: This event is emitted before any authentication takes place, thus
9349 the authentication ID is not provided
9350 Since: 0.13.0
9352 Example:
9354 <- { "event": "VNC_CONNECTED",
9356 "data": {
9357 "server": { "auth": "sasl", "family": "ipv4",
9358 "service": "5901", "host": "0.0.0.0" },
9359 "client": { "family": "ipv4", "service": "58425",
9360 "host": "127.0.0.1" } },
9361 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
9362 If: "defined(CONFIG_VNC)"
9364 VNC_INITIALIZED (Event) Emitted after authentication takes place (if
9366 any) and the VNC session is made active
9367 Arguments:
9369 "server: VncServerInfo"
9371 server information
9372 "client: VncClientInfo"
9374 client information
9375 Since: 0.13.0
9377 Example:
9379 <- { "event": "VNC_INITIALIZED",
9381 "data": {
9382 "server": { "auth": "sasl", "family": "ipv4",
9383 "service": "5901", "host": "0.0.0.0"},
9384 "client": { "family": "ipv4", "service": "46089",
9385 "host": "127.0.0.1", "sasl_username": "luiz" } },
9386 "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
9387 If: "defined(CONFIG_VNC)"
9389 VNC_DISCONNECTED (Event) Emitted when the connection is closed
9391 Arguments:
9393 "server: VncServerInfo"
9395 server information
9396 "client: VncClientInfo"
9398 client information
9399 Since: 0.13.0
9401 Example:
9403 <- { "event": "VNC_DISCONNECTED",
9405 "data": {
9406 "server": { "auth": "sasl", "family": "ipv4",
9407 "service": "5901", "host": "0.0.0.0" },
9408 "client": { "family": "ipv4", "service": "58425",
9409 "host": "127.0.0.1", "sasl_username": "luiz" } },
9410 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
9411 If: "defined(CONFIG_VNC)"
9413 Input
9415 MouseInfo (Object)
9416 Information about a mouse device.
9418 Members:
9420 "name: string"
9422 the name of the mouse device
9423 "index: int"
9425 the index of the mouse device
9426 "current: boolean"
9428 true if this device is currently receiving mouse events
9429 "absolute: boolean"
9431 true if this device supports absolute coordinates as input
9432 Since: 0.14.0
9434 query-mice (Command) Returns information about each active mouse
9436 device
9437 Returns: a list of "MouseInfo" for each device
9439 Since: 0.14.0
9441 Example:
9443 -> { "execute": "query-mice" }
9445 <- { "return": [
9446 {
9447 "name":"QEMU Microsoft Mouse",
9448 "index":0,
9449 "current":false,
9450 "absolute":false
9451 },
9452 {
9453 "name":"QEMU PS/2 Mouse",
9454 "index":1,
9455 "current":true,
9456 "absolute":true
9457 }
9458 ]
9459 }
9460 QKeyCode (Enum)
9462 An enumeration of key name.
9464 This is used by the "send-key" command.
9466 Values:
9468 "unmapped"
9470 since 2.0
9471 "pause"
9473 since 2.0
9474 "ro"
9476 since 2.4
9477 "kp_comma"
9479 since 2.4
9480 "kp_equals"
9482 since 2.6
9483 "power"
9485 since 2.6
9486 "hiragana"
9488 since 2.9
9489 "henkan"
9491 since 2.9
9492 "yen"
9494 since 2.9
9495 "sleep"
9497 since 2.10
9498 "wake"
9500 since 2.10
9501 "audionext"
9503 since 2.10
9504 "audioprev"
9506 since 2.10
9507 "audiostop"
9509 since 2.10
9510 "audioplay"
9512 since 2.10
9513 "audiomute"
9515 since 2.10
9516 "volumeup"
9518 since 2.10
9519 "volumedown"
9521 since 2.10
9522 "mediaselect"
9524 since 2.10
9525 "mail"
9527 since 2.10
9528 "calculator"
9530 since 2.10
9531 "computer"
9533 since 2.10
9534 "ac_home"
9536 since 2.10
9537 "ac_back"
9539 since 2.10
9540 "ac_forward"
9542 since 2.10
9543 "ac_refresh"
9545 since 2.10
9546 "ac_bookmarks"
9548 since 2.10 altgr, altgr_r: dropped in 2.10
9549 "muhenkan"
9551 since 2.12
9552 "katakanahiragana"
9554 since 2.12
9555 "shift"
9557 Not documented
9558 "shift_r"
9560 Not documented
9561 "alt"
9563 Not documented
9564 "alt_r"
9566 Not documented
9567 "ctrl"
9569 Not documented
9570 "ctrl_r"
9572 Not documented
9573 "menu"
9575 Not documented
9576 "esc"
9578 Not documented
9579 1 Not documented
9581 2 Not documented
9583 3 Not documented
9585 4 Not documented
9587 5 Not documented
9589 6 Not documented
9591 7 Not documented
9593 8 Not documented
9595 9 Not documented
9597 0 Not documented
9599 "minus"
9601 Not documented
9602 "equal"
9604 Not documented
9605 "backspace"
9607 Not documented
9608 "tab"
9610 Not documented
9611 "q" Not documented
9613 "w" Not documented
9615 "e" Not documented
9617 "r" Not documented
9619 "t" Not documented
9621 "y" Not documented
9623 "u" Not documented
9625 "i" Not documented
9627 "o" Not documented
9629 "p" Not documented
9631 "bracket_left"
9633 Not documented
9634 "bracket_right"
9636 Not documented
9637 "ret"
9639 Not documented
9640 "a" Not documented
9642 "s" Not documented
9644 "d" Not documented
9646 "f" Not documented
9648 "g" Not documented
9650 "h" Not documented
9652 "j" Not documented
9654 "k" Not documented
9656 "l" Not documented
9658 "semicolon"
9660 Not documented
9661 "apostrophe"
9663 Not documented
9664 "grave_accent"
9666 Not documented
9667 "backslash"
9669 Not documented
9670 "z" Not documented
9672 "x" Not documented
9674 "c" Not documented
9676 "v" Not documented
9678 "b" Not documented
9680 "n" Not documented
9682 "m" Not documented
9684 "comma"
9686 Not documented
9687 "dot"
9689 Not documented
9690 "slash"
9692 Not documented
9693 "asterisk"
9695 Not documented
9696 "spc"
9698 Not documented
9699 "caps_lock"
9701 Not documented
9702 "f1"
9704 Not documented
9705 "f2"
9707 Not documented
9708 "f3"
9710 Not documented
9711 "f4"
9713 Not documented
9714 "f5"
9716 Not documented
9717 "f6"
9719 Not documented
9720 "f7"
9722 Not documented
9723 "f8"
9725 Not documented
9726 "f9"
9728 Not documented
9729 "f10"
9731 Not documented
9732 "num_lock"
9734 Not documented
9735 "scroll_lock"
9737 Not documented
9738 "kp_divide"
9740 Not documented
9741 "kp_multiply"
9743 Not documented
9744 "kp_subtract"
9746 Not documented
9747 "kp_add"
9749 Not documented
9750 "kp_enter"
9752 Not documented
9753 "kp_decimal"
9755 Not documented
9756 "sysrq"
9758 Not documented
9759 "kp_0"
9761 Not documented
9762 "kp_1"
9764 Not documented
9765 "kp_2"
9767 Not documented
9768 "kp_3"
9770 Not documented
9771 "kp_4"
9773 Not documented
9774 "kp_5"
9776 Not documented
9777 "kp_6"
9779 Not documented
9780 "kp_7"
9782 Not documented
9783 "kp_8"
9785 Not documented
9786 "kp_9"
9788 Not documented
9789 "less"
9791 Not documented
9792 "f11"
9794 Not documented
9795 "f12"
9797 Not documented
9798 "print"
9800 Not documented
9801 "home"
9803 Not documented
9804 "pgup"
9806 Not documented
9807 "pgdn"
9809 Not documented
9810 "end"
9812 Not documented
9813 "left"
9815 Not documented
9816 "up"
9818 Not documented
9819 "down"
9821 Not documented
9822 "right"
9824 Not documented
9825 "insert"
9827 Not documented
9828 "delete"
9830 Not documented
9831 "stop"
9833 Not documented
9834 "again"
9836 Not documented
9837 "props"
9839 Not documented
9840 "undo"
9842 Not documented
9843 "front"
9845 Not documented
9846 "copy"
9848 Not documented
9849 "open"
9851 Not documented
9852 "paste"
9854 Not documented
9855 "find"
9857 Not documented
9858 "cut"
9860 Not documented
9861 "lf"
9863 Not documented
9864 "help"
9866 Not documented
9867 "meta_l"
9869 Not documented
9870 "meta_r"
9872 Not documented
9873 "compose"
9875 Not documented
9876 'sysrq' was mistakenly added to hack around the fact that the ps2
9878 driver was not generating correct scancodes sequences when 'alt+print'
9879 was pressed. This flaw is now fixed and the 'sysrq' key serves no
9880 further purpose. Any further use of 'sysrq' will be transparently
9881 changed to 'print', so they are effectively synonyms.
9882 Since: 1.3.0
9884 KeyValue (Object)
9886 Represents a keyboard key.
9888 Members:
9890 "type"
9892 One of "number", "qcode"
9893 "data: int" when "type" is "number"
9895 "data: QKeyCode" when "type" is "qcode"
9896 Since: 1.3.0
9898 send-key (Command) Send keys to guest.
9900 Arguments:
9902 "keys: array of KeyValue"
9904 An array of "KeyValue" elements. All "KeyValues" in this array are
9905 simultaneously sent to the guest. A "KeyValue".number value is sent
9906 directly to the guest, while "KeyValue".qcode must be a valid
9907 "QKeyCode" value
9908 "hold-time: int" (optional)
9910 time to delay key up events, milliseconds. Defaults to 100
9911 Returns: Nothing on success If key is unknown or redundant,
9913 InvalidParameter
9914 Since: 1.3.0
9916 Example:
9918 -> { "execute": "send-key",
9920 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
9921 { "type": "qcode", "data": "alt" },
9922 { "type": "qcode", "data": "delete" } ] } }
9923 <- { "return": {} }
9924 InputButton (Enum)
9926 Button of a pointer input device (mouse, tablet).
9928 Values:
9930 "side"
9932 front side button of a 5-button mouse (since 2.9)
9933 "extra"
9935 rear side button of a 5-button mouse (since 2.9)
9936 "left"
9938 Not documented
9939 "middle"
9941 Not documented
9942 "right"
9944 Not documented
9945 "wheel-up"
9947 Not documented
9948 "wheel-down"
9950 Not documented
9951 Since: 2.0
9953 InputAxis (Enum)
9955 Position axis of a pointer input device (mouse, tablet).
9957 Values:
9959 "x" Not documented
9961 "y" Not documented
9963 Since: 2.0
9965 InputKeyEvent (Object)
9967 Keyboard input event.
9969 Members:
9971 "key: KeyValue"
9973 Which key this event is for.
9974 "down: boolean"
9976 True for key-down and false for key-up events.
9977 Since: 2.0
9979 InputBtnEvent (Object)
9981 Pointer button input event.
9983 Members:
9985 "button: InputButton"
9987 Which button this event is for.
9988 "down: boolean"
9990 True for key-down and false for key-up events.
9991 Since: 2.0
9993 InputMoveEvent (Object)
9995 Pointer motion input event.
9997 Members:
9999 "axis: InputAxis"
10001 Which axis is referenced by "value".
10002 "value: int"
10004 Pointer position. For absolute coordinates the valid range is 0 ->
10005 0x7ffff
10006 Since: 2.0
10008 InputEvent (Object)
10010 Input event union.
10012 Members:
10014 "type"
10016 the input type, one of:
10017 - 'key': Input event of Keyboard
10019 - 'btn': Input event of pointer buttons
10021 - 'rel': Input event of relative pointer motion
10023 - 'abs': Input event of absolute pointer motion
10025 "data: InputKeyEvent" when "type" is "key"
10027 "data: InputBtnEvent" when "type" is "btn"
10028 "data: InputMoveEvent" when "type" is "rel"
10029 "data: InputMoveEvent" when "type" is "abs"
10030 Since: 2.0
10032 input-send-event (Command) Send input event(s) to guest.
10034 Arguments:
10036 "device: string" (optional)
10038 display device to send event(s) to.
10039 "head: int" (optional)
10041 head to send event(s) to, in case the display device supports
10042 multiple scanouts.
10043 "events: array of InputEvent"
10045 List of InputEvent union.
10046 Returns: Nothing on success.
10048 The "device" and "head" parameters can be used to send the input event
10050 to specific input devices in case (a) multiple input devices of the
10051 same kind are added to the virtual machine and (b) you have configured
10052 input routing (see docs/multiseat.txt) for those input devices. The
10053 parameters work exactly like the device and head properties of input
10054 devices. If "device" is missing, only devices that have no input
10055 routing config are admissible. If "device" is specified, both input
10056 devices with and without input routing config are admissible, but
10057 devices with input routing config take precedence.
10058 Since: 2.6
10060 Note: The consoles are visible in the qom tree, under
10062 /backend/console[$index]. They have a device link and head property, so
10063 it is possible to map which console belongs to which device and
10064 display.
10065 Example:
10067 1. Press left mouse button.
10069 -> { "execute": "input-send-event",
10071 "arguments": { "device": "video0",
10072 "events": [ { "type": "btn",
10073 "data" : { "down": true, "button": "left" } } ] } }
10074 <- { "return": {} }
10075 -> { "execute": "input-send-event",
10077 "arguments": { "device": "video0",
10078 "events": [ { "type": "btn",
10079 "data" : { "down": false, "button": "left" } } ] } }
10080 <- { "return": {} }
10081 2. Press ctrl-alt-del.
10083 -> { "execute": "input-send-event",
10085 "arguments": { "events": [
10086 { "type": "key", "data" : { "down": true,
10087 "key": {"type": "qcode", "data": "ctrl" } } },
10088 { "type": "key", "data" : { "down": true,
10089 "key": {"type": "qcode", "data": "alt" } } },
10090 { "type": "key", "data" : { "down": true,
10091 "key": {"type": "qcode", "data": "delete" } } } ] } }
10092 <- { "return": {} }
10093 3. Move mouse pointer to absolute coordinates (20000, 400).
10095 -> { "execute": "input-send-event" ,
10097 "arguments": { "events": [
10098 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
10099 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
10100 <- { "return": {} }
10101 DisplayGTK (Object)
10103 GTK display options.
10105 Members:
10107 "grab-on-hover: boolean" (optional)
10109 Grab keyboard input on mouse hover.
10110 "zoom-to-fit: boolean" (optional)
10112 Zoom guest display to fit into the host window. When turned off
10113 the host window will be resized instead. In case the display
10114 device can notify the guest on window resizes (virtio-gpu) this
10115 will default to "on", assuming the guest will resize the display to
10116 match the window size then. Otherwise it defaults to "off". Since
10117 3.1
10118 Since: 2.12
10120 DisplayEGLHeadless (Object)
10122 EGL headless display options.
10124 Members:
10126 "rendernode: string" (optional)
10128 Which DRM render node should be used. Default is the first
10129 available node on the host.
10130 Since: 3.1
10132 DisplayGLMode (Enum)
10134 Display OpenGL mode.
10136 Values:
10138 "off"
10140 Disable OpenGL (default).
10141 "on"
10143 Use OpenGL, pick context type automatically. Would better be named
10144 'auto' but is called 'on' for backward compatibility with bool
10145 type.
10146 "core"
10148 Use OpenGL with Core (desktop) Context.
10149 "es"
10151 Use OpenGL with ES (embedded systems) Context.
10152 Since: 3.0
10154 DisplayType (Enum)
10156 Display (user interface) type.
10158 Values:
10160 "default"
10162 Not documented
10163 "none"
10165 Not documented
10166 "gtk"
10168 Not documented
10169 "sdl"
10171 Not documented
10172 "egl-headless"
10174 Not documented
10175 "curses"
10177 Not documented
10178 "cocoa"
10180 Not documented
10181 Since: 2.12
10183 DisplayOptions (Object)
10185 Display (user interface) options.
10187 Members:
10189 "type: DisplayType"
10191 Which DisplayType qemu should use.
10192 "full-screen: boolean" (optional)
10194 Start user interface in fullscreen mode (default: off).
10195 "window-close: boolean" (optional)
10197 Allow to quit qemu with window close button (default: on).
10198 "gl: DisplayGLMode" (optional)
10200 Enable OpenGL support (default: off).
10201 The members of "DisplayGTK" when "type" is "gtk"
10203 The members of "DisplayEGLHeadless" when "type" is "egl-headless"
10204 Since: 2.12
10206 query-display-options (Command) Returns information about display
10208 configuration
10209 Returns: "DisplayOptions"
10211 Since: 3.1
10213 Migration
10215 MigrationStats (Object)
10216 Detailed migration status.
10218 Members:
10220 "transferred: int"
10222 amount of bytes already transferred to the target VM
10223 "remaining: int"
10225 amount of bytes remaining to be transferred to the target VM
10226 "total: int"
10228 total amount of bytes involved in the migration process
10229 "duplicate: int"
10231 number of duplicate (zero) pages (since 1.2)
10232 "skipped: int"
10234 number of skipped zero pages (since 1.5)
10235 "normal: int"
10237 number of normal pages (since 1.2)
10238 "normal-bytes: int"
10240 number of normal bytes sent (since 1.2)
10241 "dirty-pages-rate: int"
10243 number of pages dirtied by second by the guest (since 1.3)
10244 "mbps: number"
10246 throughput in megabits/sec. (since 1.6)
10247 "dirty-sync-count: int"
10249 number of times that dirty ram was synchronized (since 2.1)
10250 "postcopy-requests: int"
10252 The number of page requests received from the destination (since
10253 2.7)
10254 "page-size: int"
10256 The number of bytes per page for the various page-based statistics
10257 (since 2.10)
10258 "multifd-bytes: int"
10260 The number of bytes sent through multifd (since 3.0)
10261 Since: 0.14.0
10263 XBZRLECacheStats (Object)
10265 Detailed XBZRLE migration cache statistics
10267 Members:
10269 "cache-size: int"
10271 XBZRLE cache size
10272 "bytes: int"
10274 amount of bytes already transferred to the target VM
10275 "pages: int"
10277 amount of pages transferred to the target VM
10278 "cache-miss: int"
10280 number of cache miss
10281 "cache-miss-rate: number"
10283 rate of cache miss (since 2.1)
10284 "overflow: int"
10286 number of overflows
10287 Since: 1.2
10289 CompressionStats (Object)
10291 Detailed migration compression statistics
10293 Members:
10295 "pages: int"
10297 amount of pages compressed and transferred to the target VM
10298 "busy: int"
10300 count of times that no free thread was available to compress data
10301 "busy-rate: number"
10303 rate of thread busy
10304 "compressed-size: int"
10306 amount of bytes after compression
10307 "compression-rate: number"
10309 rate of compressed size
10310 Since: 3.1
10312 MigrationStatus (Enum)
10314 An enumeration of migration status.
10316 Values:
10318 "none"
10320 no migration has ever happened.
10321 "setup"
10323 migration process has been initiated.
10324 "cancelling"
10326 in the process of cancelling migration.
10327 "cancelled"
10329 cancelling migration is finished.
10330 "active"
10332 in the process of doing migration.
10333 "postcopy-active"
10335 like active, but now in postcopy mode. (since 2.5)
10336 "postcopy-paused"
10338 during postcopy but paused. (since 3.0)
10339 "postcopy-recover"
10341 trying to recover from a paused postcopy. (since 3.0)
10342 "completed"
10344 migration is finished.
10345 "failed"
10347 some error occurred during migration process.
10348 "colo"
10350 VM is in the process of fault tolerance, VM can not get into this
10351 state unless colo capability is enabled for migration. (since 2.8)
10352 "pre-switchover"
10354 Paused before device serialisation. (since 2.11)
10355 "device"
10357 During device serialisation when pause-before-switchover is enabled
10358 (since 2.11)
10359 Since: 2.3
10361 MigrationInfo (Object)
10363 Information about current migration process.
10365 Members:
10367 "status: MigrationStatus" (optional)
10369 "MigrationStatus" describing the current migration status. If this
10370 field is not returned, no migration process has been initiated
10371 "ram: MigrationStats" (optional)
10373 "MigrationStats" containing detailed migration status, only
10374 returned if status is 'active' or 'completed'(since 1.2)
10375 "disk: MigrationStats" (optional)
10377 "MigrationStats" containing detailed disk migration status, only
10378 returned if status is 'active' and it is a block migration
10379 "xbzrle-cache: XBZRLECacheStats" (optional)
10381 "XBZRLECacheStats" containing detailed XBZRLE migration statistics,
10382 only returned if XBZRLE feature is on and status is 'active' or
10383 'completed' (since 1.2)
10384 "total-time: int" (optional)
10386 total amount of milliseconds since migration started. If migration
10387 has ended, it returns the total migration time. (since 1.2)
10388 "downtime: int" (optional)
10390 only present when migration finishes correctly total downtime in
10391 milliseconds for the guest. (since 1.3)
10392 "expected-downtime: int" (optional)
10394 only present while migration is active expected downtime in
10395 milliseconds for the guest in last walk of the dirty bitmap. (since
10396 1.3)
10397 "setup-time: int" (optional)
10399 amount of setup time in milliseconds before the iterations begin
10400 but after the QMP command is issued. This is designed to provide an
10401 accounting of any activities (such as RDMA pinning) which may be
10402 expensive, but do not actually occur during the iterative migration
10403 rounds themselves. (since 1.6)
10404 "cpu-throttle-percentage: int" (optional)
10406 percentage of time guest cpus are being throttled during auto-
10407 converge. This is only present when auto-converge has started
10408 throttling guest cpus. (Since 2.7)
10409 "error-desc: string" (optional)
10411 the human readable error description string, when "status" is
10412 'failed'. Clients should not attempt to parse the error strings.
10413 (Since 2.7)
10414 "postcopy-blocktime: int" (optional)
10416 total time when all vCPU were blocked during postcopy live
10417 migration. This is only present when the postcopy-blocktime
10418 migration capability is enabled. (Since 3.0)
10419 "postcopy-vcpu-blocktime: array of int" (optional)
10421 list of the postcopy blocktime per vCPU. This is only present when
10422 the postcopy-blocktime migration capability is enabled. (Since 3.0)
10423 "compression: CompressionStats" (optional)
10425 migration compression statistics, only returned if compression
10426 feature is on and status is 'active' or 'completed' (Since 3.1)
10427 Since: 0.14.0
10429 query-migrate (Command) Returns information about current migration
10431 process. If migration is active there will be another json-object with
10432 RAM migration status and if block migration is active another one with
10433 block migration status.
10434 Returns: "MigrationInfo"
10436 Since: 0.14.0
10438 Example:
10440 1. Before the first migration
10442 -> { "execute": "query-migrate" }
10444 <- { "return": {} }
10445 2. Migration is done and has succeeded
10447 -> { "execute": "query-migrate" }
10449 <- { "return": {
10450 "status": "completed",
10451 "total-time":12345,
10452 "setup-time":12345,
10453 "downtime":12345,
10454 "ram":{
10455 "transferred":123,
10456 "remaining":123,
10457 "total":246,
10458 "duplicate":123,
10459 "normal":123,
10460 "normal-bytes":123456,
10461 "dirty-sync-count":15
10462 }
10463 }
10464 }
10465 3. Migration is done and has failed
10467 -> { "execute": "query-migrate" }
10469 <- { "return": { "status": "failed" } }
10470 4. Migration is being performed and is not a block migration:
10472 -> { "execute": "query-migrate" }
10474 <- {
10475 "return":{
10476 "status":"active",
10477 "total-time":12345,
10478 "setup-time":12345,
10479 "expected-downtime":12345,
10480 "ram":{
10481 "transferred":123,
10482 "remaining":123,
10483 "total":246,
10484 "duplicate":123,
10485 "normal":123,
10486 "normal-bytes":123456,
10487 "dirty-sync-count":15
10488 }
10489 }
10490 }
10491 5. Migration is being performed and is a block migration:
10493 -> { "execute": "query-migrate" }
10495 <- {
10496 "return":{
10497 "status":"active",
10498 "total-time":12345,
10499 "setup-time":12345,
10500 "expected-downtime":12345,
10501 "ram":{
10502 "total":1057024,
10503 "remaining":1053304,
10504 "transferred":3720,
10505 "duplicate":123,
10506 "normal":123,
10507 "normal-bytes":123456,
10508 "dirty-sync-count":15
10509 },
10510 "disk":{
10511 "total":20971520,
10512 "remaining":20880384,
10513 "transferred":91136
10514 }
10515 }
10516 }
10517 6. Migration is being performed and XBZRLE is active:
10519 -> { "execute": "query-migrate" }
10521 <- {
10522 "return":{
10523 "status":"active",
10524 "total-time":12345,
10525 "setup-time":12345,
10526 "expected-downtime":12345,
10527 "ram":{
10528 "total":1057024,
10529 "remaining":1053304,
10530 "transferred":3720,
10531 "duplicate":10,
10532 "normal":3333,
10533 "normal-bytes":3412992,
10534 "dirty-sync-count":15
10535 },
10536 "xbzrle-cache":{
10537 "cache-size":67108864,
10538 "bytes":20971520,
10539 "pages":2444343,
10540 "cache-miss":2244,
10541 "cache-miss-rate":0.123,
10542 "overflow":34434
10543 }
10544 }
10545 }
10546 MigrationCapability (Enum)
10548 Migration capabilities enumeration
10550 Values:
10552 "xbzrle"
10554 Migration supports xbzrle (Xor Based Zero Run Length Encoding).
10555 This feature allows us to minimize migration traffic for certain
10556 work loads, by sending compressed difference of the pages
10557 "rdma-pin-all"
10559 Controls whether or not the entire VM memory footprint is mlock()'d
10560 on demand or all at once. Refer to docs/rdma.txt for usage.
10561 Disabled by default. (since 2.0)
10562 "zero-blocks"
10564 During storage migration encode blocks of zeroes efficiently. This
10565 essentially saves 1MB of zeroes per block on the wire. Enabling
10566 requires source and target VM to support this feature. To enable it
10567 is sufficient to enable the capability on the source VM. The
10568 feature is disabled by default. (since 1.6)
10569 "compress"
10571 Use multiple compression threads to accelerate live migration.
10572 This feature can help to reduce the migration traffic, by sending
10573 compressed pages. Please note that if compress and xbzrle are both
10574 on, compress only takes effect in the ram bulk stage, after that,
10575 it will be disabled and only xbzrle takes effect, this can help to
10576 minimize migration traffic. The feature is disabled by default.
10577 (since 2.4 )
10578 "events"
10580 generate events for each migration state change (since 2.4 )
10581 "auto-converge"
10583 If enabled, QEMU will automatically throttle down the guest to
10584 speed up convergence of RAM migration. (since 1.6)
10585 "postcopy-ram"
10587 Start executing on the migration target before all of RAM has been
10588 migrated, pulling the remaining pages along as needed. The capacity
10589 must have the same setting on both source and target or migration
10590 will not even start. NOTE: If the migration fails during postcopy
10591 the VM will fail. (since 2.6)
10592 "x-colo"
10594 If enabled, migration will never end, and the state of the VM on
10595 the primary side will be migrated continuously to the VM on
10596 secondary side, this process is called COarse-Grain LOck Stepping
10597 (COLO) for Non-stop Service. (since 2.8)
10598 "release-ram"
10600 if enabled, qemu will free the migrated ram pages on the source
10601 during postcopy-ram migration. (since 2.9)
10602 "block"
10604 If enabled, QEMU will also migrate the contents of all block
10605 devices. Default is disabled. A possible alternative uses mirror
10606 jobs to a builtin NBD server on the destination, which offers more
10607 flexibility. (Since 2.10)
10608 "return-path"
10610 If enabled, migration will use the return path even for precopy.
10611 (since 2.10)
10612 "pause-before-switchover"
10614 Pause outgoing migration before serialising device state and before
10615 disabling block IO (since 2.11)
10616 "x-multifd"
10618 Use more than one fd for migration (since 2.11)
10619 "dirty-bitmaps"
10621 If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
10622 "postcopy-blocktime"
10624 Calculate downtime for postcopy live migration (since 3.0)
10625 "late-block-activate"
10627 If enabled, the destination will not activate block devices (and
10628 thus take locks) immediately at the end of migration. (since 3.0)
10629 Since: 1.2
10631 MigrationCapabilityStatus (Object)
10633 Migration capability information
10635 Members:
10637 "capability: MigrationCapability"
10639 capability enum
10640 "state: boolean"
10642 capability state bool
10643 Since: 1.2
10645 migrate-set-capabilities (Command) Enable/Disable the following
10647 migration capabilities (like xbzrle)
10648 Arguments:
10650 "capabilities: array of MigrationCapabilityStatus"
10652 json array of capability modifications to make
10653 Since: 1.2
10655 Example:
10657 -> { "execute": "migrate-set-capabilities" , "arguments":
10659 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
10660 query-migrate-capabilities (Command) Returns information about the
10662 current migration capabilities status
10663 Returns: "MigrationCapabilitiesStatus"
10665 Since: 1.2
10667 Example:
10669 -> { "execute": "query-migrate-capabilities" }
10671 <- { "return": [
10672 {"state": false, "capability": "xbzrle"},
10673 {"state": false, "capability": "rdma-pin-all"},
10674 {"state": false, "capability": "auto-converge"},
10675 {"state": false, "capability": "zero-blocks"},
10676 {"state": false, "capability": "compress"},
10677 {"state": true, "capability": "events"},
10678 {"state": false, "capability": "postcopy-ram"},
10679 {"state": false, "capability": "x-colo"}
10680 ]}
10681 MigrationParameter (Enum)
10683 Migration parameters enumeration
10685 Values:
10687 "compress-level"
10689 Set the compression level to be used in live migration, the
10690 compression level is an integer between 0 and 9, where 0 means no
10691 compression, 1 means the best compression speed, and 9 means best
10692 compression ratio which will consume more CPU.
10693 "compress-threads"
10695 Set compression thread count to be used in live migration, the
10696 compression thread count is an integer between 1 and 255.
10697 "compress-wait-thread"
10699 Controls behavior when all compression threads are currently busy.
10700 If true (default), wait for a free compression thread to become
10701 available; otherwise, send the page uncompressed. (Since 3.1)
10702 "decompress-threads"
10704 Set decompression thread count to be used in live migration, the
10705 decompression thread count is an integer between 1 and 255.
10706 Usually, decompression is at least 4 times as fast as compression,
10707 so set the decompress-threads to the number about 1/4 of compress-
10708 threads is adequate.
10709 "cpu-throttle-initial"
10711 Initial percentage of time guest cpus are throttled when migration
10712 auto-converge is activated. The default value is 20. (Since 2.7)
10713 "cpu-throttle-increment"
10715 throttle percentage increase each time auto-converge detects that
10716 migration is not making progress. The default value is 10. (Since
10717 2.7)
10718 "tls-creds"
10720 ID of the 'tls-creds' object that provides credentials for
10721 establishing a TLS connection over the migration data channel. On
10722 the outgoing side of the migration, the credentials must be for a
10723 'client' endpoint, while for the incoming side the credentials must
10724 be for a 'server' endpoint. Setting this will enable TLS for all
10725 migrations. The default is unset, resulting in unsecured migration
10726 at the QEMU level. (Since 2.7)
10727 "tls-hostname"
10729 hostname of the target host for the migration. This is required
10730 when using x509 based TLS credentials and the migration URI does
10731 not already include a hostname. For example if using fd: or exec:
10732 based migration, the hostname must be provided so that the server's
10733 x509 certificate identity can be validated. (Since 2.7)
10734 "max-bandwidth"
10736 to set maximum speed for migration. maximum speed in bytes per
10737 second. (Since 2.8)
10738 "downtime-limit"
10740 set maximum tolerated downtime for migration. maximum downtime in
10741 milliseconds (Since 2.8)
10742 "x-checkpoint-delay"
10744 The delay time (in ms) between two COLO checkpoints in periodic
10745 mode. (Since 2.8)
10746 "block-incremental"
10748 Affects how much storage is migrated when the block migration
10749 capability is enabled. When false, the entire storage backing
10750 chain is migrated into a flattened image at the destination; when
10751 true, only the active qcow2 layer is migrated and the destination
10752 must already have access to the same backing chain as was used on
10753 the source. (since 2.10)
10754 "x-multifd-channels"
10756 Number of channels used to migrate data in parallel. This is the
10757 same number that the number of sockets used for migration. The
10758 default value is 2 (since 2.11)
10759 "x-multifd-page-count"
10761 Number of pages sent together to a thread. The default value is 16
10762 (since 2.11)
10763 "xbzrle-cache-size"
10765 cache size to be used by XBZRLE migration. It needs to be a
10766 multiple of the target page size and a power of 2 (Since 2.11)
10767 "max-postcopy-bandwidth"
10769 Background transfer bandwidth during postcopy. Defaults to 0
10770 (unlimited). In bytes per second. (Since 3.0)
10771 "max-cpu-throttle"
10773 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
10774 Since: 2.4
10776 MigrateSetParameters (Object)
10778 Members:
10780 "compress-level: int" (optional)
10782 compression level
10783 "compress-threads: int" (optional)
10785 compression thread count
10786 "compress-wait-thread: boolean" (optional)
10788 Controls behavior when all compression threads are currently busy.
10789 If true (default), wait for a free compression thread to become
10790 available; otherwise, send the page uncompressed. (Since 3.1)
10791 "decompress-threads: int" (optional)
10793 decompression thread count
10794 "cpu-throttle-initial: int" (optional)
10796 Initial percentage of time guest cpus are throttled when migration
10797 auto-converge is activated. The default value is 20. (Since 2.7)
10798 "cpu-throttle-increment: int" (optional)
10800 throttle percentage increase each time auto-converge detects that
10801 migration is not making progress. The default value is 10. (Since
10802 2.7)
10803 "tls-creds: StrOrNull" (optional)
10805 ID of the 'tls-creds' object that provides credentials for
10806 establishing a TLS connection over the migration data channel. On
10807 the outgoing side of the migration, the credentials must be for a
10808 'client' endpoint, while for the incoming side the credentials must
10809 be for a 'server' endpoint. Setting this to a non-empty string
10810 enables TLS for all migrations. An empty string means that QEMU
10811 will use plain text mode for migration, rather than TLS (Since 2.9)
10812 Previously (since 2.7), this was reported by omitting tls-creds
10813 instead.
10814 "tls-hostname: StrOrNull" (optional)
10816 hostname of the target host for the migration. This is required
10817 when using x509 based TLS credentials and the migration URI does
10818 not already include a hostname. For example if using fd: or exec:
10819 based migration, the hostname must be provided so that the server's
10820 x509 certificate identity can be validated. (Since 2.7) An empty
10821 string means that QEMU will use the hostname associated with the
10822 migration URI, if any. (Since 2.9) Previously (since 2.7), this was
10823 reported by omitting tls-hostname instead.
10824 "max-bandwidth: int" (optional)
10826 to set maximum speed for migration. maximum speed in bytes per
10827 second. (Since 2.8)
10828 "downtime-limit: int" (optional)
10830 set maximum tolerated downtime for migration. maximum downtime in
10831 milliseconds (Since 2.8)
10832 "x-checkpoint-delay: int" (optional)
10834 the delay time between two COLO checkpoints. (Since 2.8)
10835 "block-incremental: boolean" (optional)
10837 Affects how much storage is migrated when the block migration
10838 capability is enabled. When false, the entire storage backing
10839 chain is migrated into a flattened image at the destination; when
10840 true, only the active qcow2 layer is migrated and the destination
10841 must already have access to the same backing chain as was used on
10842 the source. (since 2.10)
10843 "x-multifd-channels: int" (optional)
10845 Number of channels used to migrate data in parallel. This is the
10846 same number that the number of sockets used for migration. The
10847 default value is 2 (since 2.11)
10848 "x-multifd-page-count: int" (optional)
10850 Number of pages sent together to a thread. The default value is 16
10851 (since 2.11)
10852 "xbzrle-cache-size: int" (optional)
10854 cache size to be used by XBZRLE migration. It needs to be a
10855 multiple of the target page size and a power of 2 (Since 2.11)
10856 "max-postcopy-bandwidth: int" (optional)
10858 Background transfer bandwidth during postcopy. Defaults to 0
10859 (unlimited). In bytes per second. (Since 3.0)
10860 "max-cpu-throttle: int" (optional)
10862 maximum cpu throttle percentage. The default value is 99. (Since
10863 3.1)
10864 Since: 2.4
10866 migrate-set-parameters (Command) Set various migration parameters.
10868 Arguments: the members of "MigrateSetParameters"
10870 Since: 2.4
10872 Example:
10874 -> { "execute": "migrate-set-parameters" ,
10876 "arguments": { "compress-level": 1 } }
10877 MigrationParameters (Object)
10879 The optional members aren't actually optional.
10881 Members:
10883 "compress-level: int" (optional)
10885 compression level
10886 "compress-threads: int" (optional)
10888 compression thread count
10889 "compress-wait-thread: boolean" (optional)
10891 Controls behavior when all compression threads are currently busy.
10892 If true (default), wait for a free compression thread to become
10893 available; otherwise, send the page uncompressed. (Since 3.1)
10894 "decompress-threads: int" (optional)
10896 decompression thread count
10897 "cpu-throttle-initial: int" (optional)
10899 Initial percentage of time guest cpus are throttled when migration
10900 auto-converge is activated. (Since 2.7)
10901 "cpu-throttle-increment: int" (optional)
10903 throttle percentage increase each time auto-converge detects that
10904 migration is not making progress. (Since 2.7)
10905 "tls-creds: string" (optional)
10907 ID of the 'tls-creds' object that provides credentials for
10908 establishing a TLS connection over the migration data channel. On
10909 the outgoing side of the migration, the credentials must be for a
10910 'client' endpoint, while for the incoming side the credentials must
10911 be for a 'server' endpoint. An empty string means that QEMU will
10912 use plain text mode for migration, rather than TLS (Since 2.7)
10913 Note: 2.8 reports this by omitting tls-creds instead.
10914 "tls-hostname: string" (optional)
10916 hostname of the target host for the migration. This is required
10917 when using x509 based TLS credentials and the migration URI does
10918 not already include a hostname. For example if using fd: or exec:
10919 based migration, the hostname must be provided so that the server's
10920 x509 certificate identity can be validated. (Since 2.7) An empty
10921 string means that QEMU will use the hostname associated with the
10922 migration URI, if any. (Since 2.9) Note: 2.8 reports this by
10923 omitting tls-hostname instead.
10924 "max-bandwidth: int" (optional)
10926 to set maximum speed for migration. maximum speed in bytes per
10927 second. (Since 2.8)
10928 "downtime-limit: int" (optional)
10930 set maximum tolerated downtime for migration. maximum downtime in
10931 milliseconds (Since 2.8)
10932 "x-checkpoint-delay: int" (optional)
10934 the delay time between two COLO checkpoints. (Since 2.8)
10935 "block-incremental: boolean" (optional)
10937 Affects how much storage is migrated when the block migration
10938 capability is enabled. When false, the entire storage backing
10939 chain is migrated into a flattened image at the destination; when
10940 true, only the active qcow2 layer is migrated and the destination
10941 must already have access to the same backing chain as was used on
10942 the source. (since 2.10)
10943 "x-multifd-channels: int" (optional)
10945 Number of channels used to migrate data in parallel. This is the
10946 same number that the number of sockets used for migration. The
10947 default value is 2 (since 2.11)
10948 "x-multifd-page-count: int" (optional)
10950 Number of pages sent together to a thread. The default value is 16
10951 (since 2.11)
10952 "xbzrle-cache-size: int" (optional)
10954 cache size to be used by XBZRLE migration. It needs to be a
10955 multiple of the target page size and a power of 2 (Since 2.11)
10956 "max-postcopy-bandwidth: int" (optional)
10958 Background transfer bandwidth during postcopy. Defaults to 0
10959 (unlimited). In bytes per second. (Since 3.0)
10960 "max-cpu-throttle: int" (optional)
10962 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
10963 Since: 2.4
10965 query-migrate-parameters (Command) Returns information about the
10967 current migration parameters
10968 Returns: "MigrationParameters"
10970 Since: 2.4
10972 Example:
10974 -> { "execute": "query-migrate-parameters" }
10976 <- { "return": {
10977 "decompress-threads": 2,
10978 "cpu-throttle-increment": 10,
10979 "compress-threads": 8,
10980 "compress-level": 1,
10981 "cpu-throttle-initial": 20,
10982 "max-bandwidth": 33554432,
10983 "downtime-limit": 300
10984 }
10985 }
10986 client_migrate_info (Command) Set migration information for remote
10988 display. This makes the server ask the client to automatically
10989 reconnect using the new parameters once migration finished
10990 successfully. Only implemented for SPICE.
10991 Arguments:
10993 "protocol: string"
10995 must be "spice"
10996 "hostname: string"
10998 migration target hostname
10999 "port: int" (optional)
11001 spice tcp port for plaintext channels
11002 "tls-port: int" (optional)
11004 spice tcp port for tls-secured channels
11005 "cert-subject: string" (optional)
11007 server certificate subject
11008 Since: 0.14.0
11010 Example:
11012 -> { "execute": "client_migrate_info",
11014 "arguments": { "protocol": "spice",
11015 "hostname": "virt42.lab.kraxel.org",
11016 "port": 1234 } }
11017 <- { "return": {} }
11018 migrate-start-postcopy (Command) Followup to a migration command to
11020 switch the migration to postcopy mode. The postcopy-ram capability
11021 must be set on both source and destination before the original
11022 migration command.
11023 Since: 2.5
11025 Example:
11027 -> { "execute": "migrate-start-postcopy" }
11029 <- { "return": {} }
11030 MIGRATION (Event) Emitted when a migration event happens
11032 Arguments:
11034 "status: MigrationStatus"
11036 "MigrationStatus" describing the current migration status.
11037 Since: 2.4
11039 Example:
11041 <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
11043 "event": "MIGRATION",
11044 "data": {"status": "completed"} }
11045 MIGRATION_PASS (Event) Emitted from the source side of a migration at
11047 the start of each pass (when it syncs the dirty bitmap)
11048 Arguments:
11050 "pass: int"
11052 An incrementing count (starting at 1 on the first pass)
11053 Since: 2.6
11055 Example:
11057 { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
11059 "event": "MIGRATION_PASS", "data": {"pass": 2} }
11060 COLOMessage (Enum)
11062 The message transmission between Primary side and Secondary side.
11064 Values:
11066 "checkpoint-ready"
11068 Secondary VM (SVM) is ready for checkpointing
11069 "checkpoint-request"
11071 Primary VM (PVM) tells SVM to prepare for checkpointing
11072 "checkpoint-reply"
11074 SVM gets PVM's checkpoint request
11075 "vmstate-send"
11077 VM's state will be sent by PVM.
11078 "vmstate-size"
11080 The total size of VMstate.
11081 "vmstate-received"
11083 VM's state has been received by SVM.
11084 "vmstate-loaded"
11086 VM's state has been loaded by SVM.
11087 Since: 2.8
11089 COLOMode (Enum)
11091 The COLO current mode.
11093 Values:
11095 "none"
11097 COLO is disabled.
11098 "primary"
11100 COLO node in primary side.
11101 "secondary"
11103 COLO node in slave side.
11104 Since: 2.8
11106 FailoverStatus (Enum)
11108 An enumeration of COLO failover status
11110 Values:
11112 "none"
11114 no failover has ever happened
11115 "require"
11117 got failover requirement but not handled
11118 "active"
11120 in the process of doing failover
11121 "completed"
11123 finish the process of failover
11124 "relaunch"
11126 restart the failover process, from 'none' -> 'completed' (Since
11127 2.9)
11128 Since: 2.8
11130 COLO_EXIT (Event) Emitted when VM finishes COLO mode due to some
11132 errors happening or at the request of users.
11133 Arguments:
11135 "mode: COLOMode"
11137 report COLO mode when COLO exited.
11138 "reason: COLOExitReason"
11140 describes the reason for the COLO exit.
11141 Since: 3.1
11143 Example:
11145 <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
11147 "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
11148 COLOExitReason (Enum)
11150 The reason for a COLO exit
11152 Values:
11154 "none"
11156 no failover has ever happened. This can't occur in the COLO_EXIT
11157 event, only in the result of query-colo-status.
11158 "request"
11160 COLO exit is due to an external request
11161 "error"
11163 COLO exit is due to an internal error
11164 Since: 3.1
11166 x-colo-lost-heartbeat (Command) Tell qemu that heartbeat is lost,
11168 request it to do takeover procedures. If this command is sent to the
11169 PVM, the Primary side will exit COLO mode. If sent to the Secondary,
11170 the Secondary side will run failover work, then takes over server
11171 operation to become the service VM.
11172 Since: 2.8
11174 Example:
11176 -> { "execute": "x-colo-lost-heartbeat" }
11178 <- { "return": {} }
11179 migrate_cancel (Command) Cancel the current executing migration
11181 process.
11182 Returns: nothing on success
11184 Notes: This command succeeds even if there is no migration process
11186 running.
11187 Since: 0.14.0
11189 Example:
11191 -> { "execute": "migrate_cancel" }
11193 <- { "return": {} }
11194 migrate-continue (Command) Continue migration when it's in a paused
11196 state.
11197 Arguments:
11199 "state: MigrationStatus"
11201 The state the migration is currently expected to be in
11202 Returns: nothing on success
11204 Since: 2.11
11206 Example:
11208 -> { "execute": "migrate-continue" , "arguments":
11210 { "state": "pre-switchover" } }
11211 <- { "return": {} }
11212 migrate_set_downtime (Command) Set maximum tolerated downtime for
11214 migration.
11215 Arguments:
11217 "value: number"
11219 maximum downtime in seconds
11220 Returns: nothing on success
11222 Notes: This command is deprecated in favor of 'migrate-set-parameters'
11224 Since: 0.14.0
11226 Example:
11228 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
11230 <- { "return": {} }
11231 migrate_set_speed (Command) Set maximum speed for migration.
11233 Arguments:
11235 "value: int"
11237 maximum speed in bytes per second.
11238 Returns: nothing on success
11240 Notes: This command is deprecated in favor of 'migrate-set-parameters'
11242 Since: 0.14.0
11244 Example:
11246 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
11248 <- { "return": {} }
11249 migrate-set-cache-size (Command) Set cache size to be used by XBZRLE
11251 migration
11252 Arguments:
11254 "value: int"
11256 cache size in bytes
11257 The size will be rounded down to the nearest power of 2. The cache
11259 size can be modified before and during ongoing migration
11260 Returns: nothing on success
11262 Notes: This command is deprecated in favor of 'migrate-set-parameters'
11264 Since: 1.2
11266 Example:
11268 -> { "execute": "migrate-set-cache-size",
11270 "arguments": { "value": 536870912 } }
11271 <- { "return": {} }
11272 query-migrate-cache-size (Command) Query migration XBZRLE cache size
11274 Returns: XBZRLE cache size in bytes
11276 Notes: This command is deprecated in favor of
11278 'query-migrate-parameters'
11279 Since: 1.2
11281 Example:
11283 -> { "execute": "query-migrate-cache-size" }
11285 <- { "return": 67108864 }
11286 migrate (Command) Migrates the current running guest to another
11288 Virtual Machine.
11289 Arguments:
11291 "uri: string"
11293 the Uniform Resource Identifier of the destination VM
11294 "blk: boolean" (optional)
11296 do block migration (full disk copy)
11297 "inc: boolean" (optional)
11299 incremental disk copy migration
11300 "detach: boolean" (optional)
11302 this argument exists only for compatibility reasons and is ignored
11303 by QEMU
11304 "resume: boolean" (optional)
11306 resume one paused migration, default "off". (since 3.0)
11307 Returns: nothing on success
11309 Since: 0.14.0
11311 Notes:
11313 1. The 'query-migrate' command should be used to check migration's
11315 progress and final result (this information is provided by the
11316 'status' member)
11317 2. All boolean arguments default to false
11319 3. The user Monitor's "detach" argument is invalid in QMP and should
11321 not be used
11322 Example:
11324 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
11326 <- { "return": {} }
11327 migrate-incoming (Command) Start an incoming migration, the qemu must
11329 have been started with -incoming defer
11330 Arguments:
11332 "uri: string"
11334 The Uniform Resource Identifier identifying the source or address
11335 to listen on
11336 Returns: nothing on success
11338 Since: 2.3
11340 Notes:
11342 1. It's a bad idea to use a string for the uri, but it needs to stay
11344 compatible with -incoming and the format of the uri is already
11345 exposed above libvirt.
11346 2. QEMU must be started with -incoming defer to allow migrate-incoming
11348 to be used.
11349 3. The uri format is the same as for -incoming
11351 Example:
11353 -> { "execute": "migrate-incoming",
11355 "arguments": { "uri": "tcp::4446" } }
11356 <- { "return": {} }
11357 xen-save-devices-state (Command) Save the state of all devices to
11359 file. The RAM and the block devices of the VM are not saved by this
11360 command.
11361 Arguments:
11363 "filename: string"
11365 the file to save the state of the devices to as binary data. See
11366 xen-save-devices-state.txt for a description of the binary format.
11367 "live: boolean" (optional)
11369 Optional argument to ask QEMU to treat this command as part of a
11370 live migration. Default to true. (since 2.11)
11371 Returns: Nothing on success
11373 Since: 1.1
11375 Example:
11377 -> { "execute": "xen-save-devices-state",
11379 "arguments": { "filename": "/tmp/save" } }
11380 <- { "return": {} }
11381 xen-set-replication (Command) Enable or disable replication.
11383 Arguments:
11385 "enable: boolean"
11387 true to enable, false to disable.
11388 "primary: boolean"
11390 true for primary or false for secondary.
11391 "failover: boolean" (optional)
11393 true to do failover, false to stop. but cannot be specified if
11394 'enable' is true. default value is false.
11395 Returns: nothing.
11397 Example:
11399 -> { "execute": "xen-set-replication",
11401 "arguments": {"enable": true, "primary": false} }
11402 <- { "return": {} }
11403 Since: 2.9
11405 ReplicationStatus (Object)
11407 The result format for 'query-xen-replication-status'.
11409 Members:
11411 "error: boolean"
11413 true if an error happened, false if replication is normal.
11414 "desc: string" (optional)
11416 the human readable error description string, when "error" is
11417 'true'.
11418 Since: 2.9
11420 query-xen-replication-status (Command) Query replication status while
11422 the vm is running.
11423 Returns: A "ReplicationResult" object showing the status.
11425 Example:
11427 -> { "execute": "query-xen-replication-status" }
11429 <- { "return": { "error": false } }
11430 Since: 2.9
11432 xen-colo-do-checkpoint (Command) Xen uses this command to notify
11434 replication to trigger a checkpoint.
11435 Returns: nothing.
11437 Example:
11439 -> { "execute": "xen-colo-do-checkpoint" }
11441 <- { "return": {} }
11442 Since: 2.9
11444 COLOStatus (Object)
11446 The result format for 'query-colo-status'.
11448 Members:
11450 "mode: COLOMode"
11452 COLO running mode. If COLO is running, this field will return
11453 'primary' or 'secondary'.
11454 "reason: COLOExitReason"
11456 describes the reason for the COLO exit.
11457 Since: 3.1
11459 query-colo-status (Command) Query COLO status while the vm is running.
11461 Returns: A "COLOStatus" object showing the status.
11463 Example:
11465 -> { "execute": "query-colo-status" }
11467 <- { "return": { "mode": "primary", "active": true, "reason": "request" } }
11468 Since: 3.1
11470 migrate-recover (Command) Provide a recovery migration stream URI.
11472 Arguments:
11474 "uri: string"
11476 the URI to be used for the recovery of migration stream.
11477 Returns: nothing.
11479 Example:
11481 -> { "execute": "migrate-recover",
11483 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
11484 <- { "return": {} }
11485 Since: 3.0
11487 migrate-pause (Command) Pause a migration. Currently it only supports
11489 postcopy.
11490 Returns: nothing.
11492 Example:
11494 -> { "execute": "migrate-pause" }
11496 <- { "return": {} }
11497 Since: 3.0
11499 Transactions
11501 Abort (Object)
11502 This action can be used to test transaction failure.
11504 Since: 1.6
11506 ActionCompletionMode (Enum)
11508 An enumeration of Transactional completion modes.
11510 Values:
11512 "individual"
11514 Do not attempt to cancel any other Actions if any Actions fail
11515 after the Transaction request succeeds. All Actions that can
11516 complete successfully will do so without waiting on others. This
11517 is the default.
11518 "grouped"
11520 If any Action fails after the Transaction succeeds, cancel all
11521 Actions. Actions do not complete until all Actions are ready to
11522 complete. May be rejected by Actions that do not support this
11523 completion mode.
11524 Since: 2.5
11526 TransactionAction (Object)
11528 A discriminated record of operations that can be performed with
11530 "transaction". Action "type" can be:
11531 - "abort": since 1.6
11533 - "block-dirty-bitmap-add": since 2.5
11535 - "block-dirty-bitmap-clear": since 2.5
11537 - "x-block-dirty-bitmap-enable": since 3.0
11539 - "x-block-dirty-bitmap-disable": since 3.0
11541 - "x-block-dirty-bitmap-merge": since 3.1
11543 - "blockdev-backup": since 2.3
11545 - "blockdev-snapshot": since 2.5
11547 - "blockdev-snapshot-internal-sync": since 1.7
11549 - "blockdev-snapshot-sync": since 1.1
11551 - "drive-backup": since 1.6
11553 Members:
11555 "type"
11557 One of "abort", "block-dirty-bitmap-add", "block-dirty-bitmap-
11558 clear", "x-block-dirty-bitmap-enable", "x-block-dirty-bitmap-
11559 disable", "x-block-dirty-bitmap-merge", "blockdev-backup",
11560 "blockdev-snapshot", "blockdev-snapshot-internal-sync", "blockdev-
11561 snapshot-sync", "drive-backup"
11562 "data: Abort" when "type" is "abort"
11564 "data: BlockDirtyBitmapAdd" when "type" is "block-dirty-bitmap-add"
11565 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-clear"
11566 "data: BlockDirtyBitmap" when "type" is "x-block-dirty-bitmap-enable"
11567 "data: BlockDirtyBitmap" when "type" is "x-block-dirty-bitmap-disable"
11568 "data: BlockDirtyBitmapMerge" when "type" is "x-block-dirty-bitmap-
11569 merge"
11570 "data: BlockdevBackup" when "type" is "blockdev-backup"
11571 "data: BlockdevSnapshot" when "type" is "blockdev-snapshot"
11572 "data: BlockdevSnapshotInternal" when "type" is "blockdev-snapshot-
11573 internal-sync"
11574 "data: BlockdevSnapshotSync" when "type" is "blockdev-snapshot-sync"
11575 "data: DriveBackup" when "type" is "drive-backup"
11576 Since: 1.1
11578 TransactionProperties (Object)
11580 Optional arguments to modify the behavior of a Transaction.
11582 Members:
11584 "completion-mode: ActionCompletionMode" (optional)
11586 Controls how jobs launched asynchronously by Actions will complete
11587 or fail as a group. See "ActionCompletionMode" for details.
11588 Since: 2.5
11590 transaction (Command) Executes a number of transactionable QMP
11592 commands atomically. If any operation fails, then the entire set of
11593 actions will be abandoned and the appropriate error returned.
11594 For external snapshots, the dictionary contains the device, the file to
11596 use for the new snapshot, and the format. The default format, if not
11597 specified, is qcow2.
11598 Each new snapshot defaults to being created by QEMU (wiping any
11600 contents if the file already exists), but it is also possible to reuse
11601 an externally-created file. In the latter case, you should ensure that
11602 the new image file has the same contents as the current one; QEMU
11603 cannot perform any meaningful check. Typically this is achieved by
11604 using the current image file as the backing file for the new image.
11605 On failure, the original disks pre-snapshot attempt will be used.
11607 For internal snapshots, the dictionary contains the device and the
11609 snapshot's name. If an internal snapshot matching name already exists,
11610 the request will be rejected. Only some image formats support it, for
11611 example, qcow2, rbd, and sheepdog.
11612 On failure, qemu will try delete the newly created internal snapshot in
11614 the transaction. When an I/O error occurs during deletion, the user
11615 needs to fix it later with qemu-img or other command.
11616 Arguments:
11618 "actions: array of TransactionAction"
11620 List of "TransactionAction"; information needed for the respective
11621 operations.
11622 "properties: TransactionProperties" (optional)
11624 structure of additional options to control the execution of the
11625 transaction. See "TransactionProperties" for additional detail.
11626 Returns: nothing on success
11628 Errors depend on the operations of the transaction
11630 Note: The transaction aborts on the first failure. Therefore, there
11632 will be information on only one failed operation returned in an error
11633 condition, and subsequent actions will not have been attempted.
11634 Since: 1.1
11636 Example:
11638 -> { "execute": "transaction",
11640 "arguments": { "actions": [
11641 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
11642 "snapshot-file": "/some/place/my-image",
11643 "format": "qcow2" } },
11644 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
11645 "snapshot-file": "/some/place/my-image2",
11646 "snapshot-node-name": "node3432",
11647 "mode": "existing",
11648 "format": "qcow2" } },
11649 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
11650 "snapshot-file": "/some/place/my-image2",
11651 "mode": "existing",
11652 "format": "qcow2" } },
11653 { "type": "blockdev-snapshot-internal-sync", "data" : {
11654 "device": "ide-hd2",
11655 "name": "snapshot0" } } ] } }
11656 <- { "return": {} }
11657 Tracing
11659 TraceEventState (Enum)
11660 State of a tracing event.
11662 Values:
11664 "unavailable"
11666 The event is statically disabled.
11667 "disabled"
11669 The event is dynamically disabled.
11670 "enabled"
11672 The event is dynamically enabled.
11673 Since: 2.2
11675 TraceEventInfo (Object)
11677 Information of a tracing event.
11679 Members:
11681 "name: string"
11683 Event name.
11684 "state: TraceEventState"
11686 Tracing state.
11687 "vcpu: boolean"
11689 Whether this is a per-vCPU event (since 2.7).
11690 An event is per-vCPU if it has the "vcpu" property in the "trace-
11692 events" files.
11693 Since: 2.2
11695 trace-event-get-state (Command) Query the state of events.
11697 Arguments:
11699 "name: string"
11701 Event name pattern (case-sensitive glob).
11702 "vcpu: int" (optional)
11704 The vCPU to query (any by default; since 2.7).
11705 Returns: a list of "TraceEventInfo" for the matching events
11707 An event is returned if:
11709 - its name matches the "name" pattern, and
11711 - if "vcpu" is given, the event has the "vcpu" property.
11713 Therefore, if "vcpu" is given, the operation will only match per-vCPU
11715 events, returning their state on the specified vCPU. Special case: if
11716 "name" is an exact match, "vcpu" is given and the event does not have
11717 the "vcpu" property, an error is returned.
11718 Since: 2.2
11720 Example:
11722 -> { "execute": "trace-event-get-state",
11724 "arguments": { "name": "qemu_memalign" } }
11725 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
11726 trace-event-set-state (Command) Set the dynamic tracing state of
11728 events.
11729 Arguments:
11731 "name: string"
11733 Event name pattern (case-sensitive glob).
11734 "enable: boolean"
11736 Whether to enable tracing.
11737 "ignore-unavailable: boolean" (optional)
11739 Do not match unavailable events with "name".
11740 "vcpu: int" (optional)
11742 The vCPU to act upon (all by default; since 2.7).
11743 An event's state is modified if:
11745 - its name matches the "name" pattern, and
11747 - if "vcpu" is given, the event has the "vcpu" property.
11749 Therefore, if "vcpu" is given, the operation will only match per-vCPU
11751 events, setting their state on the specified vCPU. Special case: if
11752 "name" is an exact match, "vcpu" is given and the event does not have
11753 the "vcpu" property, an error is returned.
11754 Since: 2.2
11756 Example:
11758 -> { "execute": "trace-event-set-state",
11760 "arguments": { "name": "qemu_memalign", "enable": "true" } }
11761 <- { "return": {} }
11762 QMP introspection
11764 query-qmp-schema (Command) Command query-qmp-schema exposes the QMP
11765 wire ABI as an array of SchemaInfo. This lets QMP clients figure out
11766 what commands and events are available in this QEMU, and their
11767 parameters and results.
11768 However, the SchemaInfo can't reflect all the rules and restrictions
11770 that apply to QMP. It's interface introspection (figuring out what's
11771 there), not interface specification. The specification is in the QAPI
11772 schema.
11773 Furthermore, while we strive to keep the QMP wire format backwards-
11775 compatible across qemu versions, the introspection output is not
11776 guaranteed to have the same stability. For example, one version of
11777 qemu may list an object member as an optional non-variant, while
11778 another lists the same member only through the object's variants; or
11779 the type of a member may change from a generic string into a specific
11780 enum or from one specific type into an alternate that includes the
11781 original type alongside something else.
11782 Returns: array of "SchemaInfo", where each element describes an entity
11784 in the ABI: command, event, type, ...
11785 The order of the various SchemaInfo is unspecified; however, all names
11787 are guaranteed to be unique (no name will be duplicated with different
11788 meta-types).
11789 Note: the QAPI schema is also used to help define internal interfaces,
11791 by defining QAPI types. These are not part of the QMP wire ABI, and
11792 therefore not returned by this command.
11793 Since: 2.5
11795 SchemaMetaType (Enum)
11797 This is a "SchemaInfo"'s meta type, i.e. the kind of entity it
11799 describes.
11800 Values:
11802 "builtin"
11804 a predefined type such as 'int' or 'bool'.
11805 "enum"
11807 an enumeration type
11808 "array"
11810 an array type
11811 "object"
11813 an object type (struct or union)
11814 "alternate"
11816 an alternate type
11817 "command"
11819 a QMP command
11820 "event"
11822 a QMP event
11823 Since: 2.5
11825 SchemaInfo (Object)
11827 Members:
11829 "name: string"
11831 the entity's name, inherited from "base". The SchemaInfo is always
11832 referenced by this name. Commands and events have the name defined
11833 in the QAPI schema. Unlike command and event names, type names are
11834 not part of the wire ABI. Consequently, type names are meaningless
11835 strings here, although they are still guaranteed unique regardless
11836 of "meta-type".
11837 "meta-type: SchemaMetaType"
11839 the entity's meta type, inherited from "base".
11840 The members of "SchemaInfoBuiltin" when "meta-type" is "builtin"
11842 The members of "SchemaInfoEnum" when "meta-type" is "enum"
11843 The members of "SchemaInfoArray" when "meta-type" is "array"
11844 The members of "SchemaInfoObject" when "meta-type" is "object"
11845 The members of "SchemaInfoAlternate" when "meta-type" is "alternate"
11846 The members of "SchemaInfoCommand" when "meta-type" is "command"
11847 The members of "SchemaInfoEvent" when "meta-type" is "event"
11848 Additional members depend on the value of "meta-type".
11850 Since: 2.5
11852 SchemaInfoBuiltin (Object)
11854 Additional SchemaInfo members for meta-type 'builtin'.
11856 Members:
11858 "json-type: JSONType"
11860 the JSON type used for this type on the wire.
11861 Since: 2.5
11863 JSONType (Enum)
11865 The four primitive and two structured types according to RFC 8259
11867 section 1, plus 'int' (split off 'number'), plus the obvious top type
11868 'value'.
11869 Values:
11871 "string"
11873 Not documented
11874 "number"
11876 Not documented
11877 "int"
11879 Not documented
11880 "boolean"
11882 Not documented
11883 "null"
11885 Not documented
11886 "object"
11888 Not documented
11889 "array"
11891 Not documented
11892 "value"
11894 Not documented
11895 Since: 2.5
11897 SchemaInfoEnum (Object)
11899 Additional SchemaInfo members for meta-type 'enum'.
11901 Members:
11903 "values: array of string"
11905 the enumeration type's values, in no particular order.
11906 Values of this type are JSON string on the wire.
11908 Since: 2.5
11910 SchemaInfoArray (Object)
11912 Additional SchemaInfo members for meta-type 'array'.
11914 Members:
11916 "element-type: string"
11918 the array type's element type.
11919 Values of this type are JSON array on the wire.
11921 Since: 2.5
11923 SchemaInfoObject (Object)
11925 Additional SchemaInfo members for meta-type 'object'.
11927 Members:
11929 "members: array of SchemaInfoObjectMember"
11931 the object type's (non-variant) members, in no particular order.
11932 "tag: string" (optional)
11934 the name of the member serving as type tag. An element of
11935 "members" with this name must exist.
11936 "variants: array of SchemaInfoObjectVariant" (optional)
11938 variant members, i.e. additional members that depend on the type
11939 tag's value. Present exactly when "tag" is present. The variants
11940 are in no particular order, and may even differ from the order of
11941 the values of the enum type of the "tag".
11942 Values of this type are JSON object on the wire.
11944 Since: 2.5
11946 SchemaInfoObjectMember (Object)
11948 An object member.
11950 Members:
11952 "name: string"
11954 the member's name, as defined in the QAPI schema.
11955 "type: string"
11957 the name of the member's type.
11958 "default: value" (optional)
11960 default when used as command parameter. If absent, the parameter
11961 is mandatory. If present, the value must be null. The parameter
11962 is optional, and behavior when it's missing is not specified here.
11963 Future extension: if present and non-null, the parameter is
11964 optional, and defaults to this value.
11965 Since: 2.5
11967 SchemaInfoObjectVariant (Object)
11969 The variant members for a value of the type tag.
11971 Members:
11973 "case: string"
11975 a value of the type tag.
11976 "type: string"
11978 the name of the object type that provides the variant members when
11979 the type tag has value "case".
11980 Since: 2.5
11982 SchemaInfoAlternate (Object)
11984 Additional SchemaInfo members for meta-type 'alternate'.
11986 Members:
11988 "members: array of SchemaInfoAlternateMember"
11990 the alternate type's members, in no particular order. The members'
11991 wire encoding is distinct, see docs/devel/qapi-code-gen.txt section
11992 Alternate types.
11993 On the wire, this can be any of the members.
11995 Since: 2.5
11997 SchemaInfoAlternateMember (Object)
11999 An alternate member.
12001 Members:
12003 "type: string"
12005 the name of the member's type.
12006 Since: 2.5
12008 SchemaInfoCommand (Object)
12010 Additional SchemaInfo members for meta-type 'command'.
12012 Members:
12014 "arg-type: string"
12016 the name of the object type that provides the command's parameters.
12017 "ret-type: string"
12019 the name of the command's result type.
12020 "allow-oob: boolean" (optional)
12022 whether the command allows out-of-band execution, defaults to false
12023 (Since: 2.12)
12024 TODO: "success-response" (currently irrelevant, because it's QGA, not
12026 QMP)
12027 Since: 2.5
12029 SchemaInfoEvent (Object)
12031 Additional SchemaInfo members for meta-type 'event'.
12033 Members:
12035 "arg-type: string"
12037 the name of the object type that provides the event's parameters.
12038 Since: 2.5
12040 Miscellanea
12042 qmp_capabilities (Command) Enable QMP capabilities.
12043 Arguments:
12045 Arguments:
12047 "enable: array of QMPCapability" (optional)
12049 An optional list of QMPCapability values to enable. The client
12050 must not enable any capability that is not mentioned in the QMP
12051 greeting message. If the field is not provided, it means no QMP
12052 capabilities will be enabled. (since 2.12)
12053 Example:
12055 -> { "execute": "qmp_capabilities",
12057 "arguments": { "enable": [ "oob" ] } }
12058 <- { "return": {} }
12059 Notes: This command is valid exactly when first connecting: it must be
12061 issued before any other command will be accepted, and will fail once
12062 the monitor is accepting other commands. (see qemu
12063 docs/interop/qmp-spec.txt)
12064 The QMP client needs to explicitly enable QMP capabilities, otherwise
12066 all the QMP capabilities will be turned off by default.
12067 Since: 0.13
12069 QMPCapability (Enum)
12071 Enumeration of capabilities to be advertised during initial client
12073 connection, used for agreeing on particular QMP extension behaviors.
12074 Values:
12076 "oob"
12078 QMP ability to support out-of-band requests. (Please refer to
12079 qmp-spec.txt for more information on OOB)
12080 Since: 2.12
12082 VersionTriple (Object)
12084 A three-part version number.
12086 Members:
12088 "major: int"
12090 The major version number.
12091 "minor: int"
12093 The minor version number.
12094 "micro: int"
12096 The micro version number.
12097 Since: 2.4
12099 VersionInfo (Object)
12101 A description of QEMU's version.
12103 Members:
12105 "qemu: VersionTriple"
12107 The version of QEMU. By current convention, a micro version of 50
12108 signifies a development branch. A micro version greater than or
12109 equal to 90 signifies a release candidate for the next minor
12110 version. A micro version of less than 50 signifies a stable
12111 release.
12112 "package: string"
12114 QEMU will always set this field to an empty string. Downstream
12115 versions of QEMU should set this to a non-empty string. The exact
12116 format depends on the downstream however it highly recommended that
12117 a unique name is used.
12118 Since: 0.14.0
12120 query-version (Command) Returns the current version of QEMU.
12122 Returns: A "VersionInfo" object describing the current version of QEMU.
12124 Since: 0.14.0
12126 Example:
12128 -> { "execute": "query-version" }
12130 <- {
12131 "return":{
12132 "qemu":{
12133 "major":0,
12134 "minor":11,
12135 "micro":5
12136 },
12137 "package":""
12138 }
12139 }
12140 CommandInfo (Object)
12142 Information about a QMP command
12144 Members:
12146 "name: string"
12148 The command name
12149 Since: 0.14.0
12151 query-commands (Command) Return a list of supported QMP commands by
12153 this server
12154 Returns: A list of "CommandInfo" for all supported commands
12156 Since: 0.14.0
12158 Example:
12160 -> { "execute": "query-commands" }
12162 <- {
12163 "return":[
12164 {
12165 "name":"query-balloon"
12166 },
12167 {
12168 "name":"system_powerdown"
12169 }
12170 ]
12171 }
12172 Note: This example has been shortened as the real response is too long.
12174 LostTickPolicy (Enum)
12176 Policy for handling lost ticks in timer devices.
12178 Values:
12180 "discard"
12182 throw away the missed tick(s) and continue with future injection
12183 normally. Guest time may be delayed, unless the OS has explicit
12184 handling of lost ticks
12185 "delay"
12187 continue to deliver ticks at the normal rate. Guest time will be
12188 delayed due to the late tick
12189 "merge"
12191 merge the missed tick(s) into one tick and inject. Guest time may
12192 be delayed, depending on how the OS reacts to the merging of ticks
12193 "slew"
12195 deliver ticks at a higher rate to catch up with the missed tick.
12196 The guest time should not be delayed once catchup is complete.
12197 Since: 2.0
12199 add_client (Command) Allow client connections for VNC, Spice and
12201 socket based character devices to be passed in to QEMU via SCM_RIGHTS.
12202 Arguments:
12204 "protocol: string"
12206 protocol name. Valid names are "vnc", "spice" or the name of a
12207 character device (eg. from -chardev id=XXXX)
12208 "fdname: string"
12210 file descriptor name previously passed via 'getfd' command
12211 "skipauth: boolean" (optional)
12213 whether to skip authentication. Only applies to "vnc" and "spice"
12214 protocols
12215 "tls: boolean" (optional)
12217 whether to perform TLS. Only applies to the "spice" protocol
12218 Returns: nothing on success.
12220 Since: 0.14.0
12222 Example:
12224 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
12226 "fdname": "myclient" } }
12227 <- { "return": {} }
12228 NameInfo (Object)
12230 Guest name information.
12232 Members:
12234 "name: string" (optional)
12236 The name of the guest
12237 Since: 0.14.0
12239 query-name (Command) Return the name information of a guest.
12241 Returns: "NameInfo" of the guest
12243 Since: 0.14.0
12245 Example:
12247 -> { "execute": "query-name" }
12249 <- { "return": { "name": "qemu-name" } }
12250 KvmInfo (Object)
12252 Information about support for KVM acceleration
12254 Members:
12256 "enabled: boolean"
12258 true if KVM acceleration is active
12259 "present: boolean"
12261 true if KVM acceleration is built into this executable
12262 Since: 0.14.0
12264 query-kvm (Command) Returns information about KVM acceleration
12266 Returns: "KvmInfo"
12268 Since: 0.14.0
12270 Example:
12272 -> { "execute": "query-kvm" }
12274 <- { "return": { "enabled": true, "present": true } }
12275 UuidInfo (Object)
12277 Guest UUID information (Universally Unique Identifier).
12279 Members:
12281 "UUID: string"
12283 the UUID of the guest
12284 Since: 0.14.0
12286 Notes: If no UUID was specified for the guest, a null UUID is returned.
12288 query-uuid (Command) Query the guest UUID information.
12290 Returns: The "UuidInfo" for the guest
12292 Since: 0.14.0
12294 Example:
12296 -> { "execute": "query-uuid" }
12298 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
12299 EventInfo (Object)
12301 Information about a QMP event
12303 Members:
12305 "name: string"
12307 The event name
12308 Since: 1.2.0
12310 query-events (Command) Return a list of supported QMP events by this
12312 server
12313 Returns: A list of "EventInfo" for all supported events
12315 Since: 1.2.0
12317 Example:
12319 -> { "execute": "query-events" }
12321 <- {
12322 "return": [
12323 {
12324 "name":"SHUTDOWN"
12325 },
12326 {
12327 "name":"RESET"
12328 }
12329 ]
12330 }
12331 Note: This example has been shortened as the real response is too long.
12333 CpuInfoArch (Enum)
12335 An enumeration of cpu types that enable additional information during
12337 "query-cpus" and "query-cpus-fast".
12338 Values:
12340 "s390"
12342 since 2.12
12343 "riscv"
12345 since 2.12
12346 "x86"
12348 Not documented
12349 "sparc"
12351 Not documented
12352 "ppc"
12354 Not documented
12355 "mips"
12357 Not documented
12358 "tricore"
12360 Not documented
12361 "other"
12363 Not documented
12364 Since: 2.6
12366 CpuInfo (Object)
12368 Information about a virtual CPU
12370 Members:
12372 "CPU: int"
12374 the index of the virtual CPU
12375 "current: boolean"
12377 this only exists for backwards compatibility and should be ignored
12378 "halted: boolean"
12380 true if the virtual CPU is in the halt state. Halt usually refers
12381 to a processor specific low power mode.
12382 "qom_path: string"
12384 path to the CPU object in the QOM tree (since 2.4)
12385 "thread_id: int"
12387 ID of the underlying host thread
12388 "props: CpuInstanceProperties" (optional)
12390 properties describing to which node/socket/core/thread virtual CPU
12391 belongs to, provided if supported by board (since 2.10)
12392 "arch: CpuInfoArch"
12394 architecture of the cpu, which determines which additional fields
12395 will be listed (since 2.6)
12396 The members of "CpuInfoX86" when "arch" is "x86"
12398 The members of "CpuInfoSPARC" when "arch" is "sparc"
12399 The members of "CpuInfoPPC" when "arch" is "ppc"
12400 The members of "CpuInfoMIPS" when "arch" is "mips"
12401 The members of "CpuInfoTricore" when "arch" is "tricore"
12402 The members of "CpuInfoS390" when "arch" is "s390"
12403 The members of "CpuInfoRISCV" when "arch" is "riscv"
12404 Since: 0.14.0
12406 Notes: "halted" is a transient state that changes frequently. By the
12408 time the data is sent to the client, the guest may no longer be halted.
12409 CpuInfoX86 (Object)
12411 Additional information about a virtual i386 or x86_64 CPU
12413 Members:
12415 "pc: int"
12417 the 64-bit instruction pointer
12418 Since: 2.6
12420 CpuInfoSPARC (Object)
12422 Additional information about a virtual SPARC CPU
12424 Members:
12426 "pc: int"
12428 the PC component of the instruction pointer
12429 "npc: int"
12431 the NPC component of the instruction pointer
12432 Since: 2.6
12434 CpuInfoPPC (Object)
12436 Additional information about a virtual PPC CPU
12438 Members:
12440 "nip: int"
12442 the instruction pointer
12443 Since: 2.6
12445 CpuInfoMIPS (Object)
12447 Additional information about a virtual MIPS CPU
12449 Members:
12451 "PC: int"
12453 the instruction pointer
12454 Since: 2.6
12456 CpuInfoTricore (Object)
12458 Additional information about a virtual Tricore CPU
12460 Members:
12462 "PC: int"
12464 the instruction pointer
12465 Since: 2.6
12467 CpuInfoRISCV (Object)
12469 Additional information about a virtual RISCV CPU
12471 Members:
12473 "pc: int"
12475 the instruction pointer
12476 Since 2.12
12478 CpuS390State (Enum)
12480 An enumeration of cpu states that can be assumed by a virtual S390 CPU
12482 Values:
12484 "uninitialized"
12486 Not documented
12487 "stopped"
12489 Not documented
12490 "check-stop"
12492 Not documented
12493 "operating"
12495 Not documented
12496 "load"
12498 Not documented
12499 Since: 2.12
12501 CpuInfoS390 (Object)
12503 Additional information about a virtual S390 CPU
12505 Members:
12507 "cpu-state: CpuS390State"
12509 the virtual CPU's state
12510 Since: 2.12
12512 query-cpus (Command) Returns a list of information about each virtual
12514 CPU.
12515 This command causes vCPU threads to exit to userspace, which causes a
12517 small interruption to guest CPU execution. This will have a negative
12518 impact on realtime guests and other latency sensitive guest workloads.
12519 It is recommended to use "query-cpus-fast" instead of this command to
12520 avoid the vCPU interruption.
12521 Returns: a list of "CpuInfo" for each virtual CPU
12523 Since: 0.14.0
12525 Example:
12527 -> { "execute": "query-cpus" }
12529 <- { "return": [
12530 {
12531 "CPU":0,
12532 "current":true,
12533 "halted":false,
12534 "qom_path":"/machine/unattached/device[0]",
12535 "arch":"x86",
12536 "pc":3227107138,
12537 "thread_id":3134
12538 },
12539 {
12540 "CPU":1,
12541 "current":false,
12542 "halted":true,
12543 "qom_path":"/machine/unattached/device[2]",
12544 "arch":"x86",
12545 "pc":7108165,
12546 "thread_id":3135
12547 }
12548 ]
12549 }
12550 Notes: This interface is deprecated (since 2.12.0), and it is strongly
12552 recommended that you avoid using it. Use "query-cpus-fast" to obtain
12553 information about virtual CPUs.
12554 CpuInfoFast (Object)
12556 Information about a virtual CPU
12558 Members:
12560 "cpu-index: int"
12562 index of the virtual CPU
12563 "qom-path: string"
12565 path to the CPU object in the QOM tree
12566 "thread-id: int"
12568 ID of the underlying host thread
12569 "props: CpuInstanceProperties" (optional)
12571 properties describing to which node/socket/core/thread virtual CPU
12572 belongs to, provided if supported by board
12573 "arch: CpuInfoArch"
12575 base architecture of the cpu; deprecated since 3.0.0 in favor of
12576 "target"
12577 "target: SysEmuTarget"
12579 the QEMU system emulation target, which determines which additional
12580 fields will be listed (since 3.0)
12581 The members of "CpuInfoS390" when "target" is "s390x"
12583 Since: 2.12
12585 query-cpus-fast (Command) Returns information about all virtual CPUs.
12587 This command does not incur a performance penalty and should be used in
12588 production instead of query-cpus.
12589 Returns: list of "CpuInfoFast"
12591 Since: 2.12
12593 Example:
12595 -> { "execute": "query-cpus-fast" }
12597 <- { "return": [
12598 {
12599 "thread-id": 25627,
12600 "props": {
12601 "core-id": 0,
12602 "thread-id": 0,
12603 "socket-id": 0
12604 },
12605 "qom-path": "/machine/unattached/device[0]",
12606 "arch":"x86",
12607 "target":"x86_64",
12608 "cpu-index": 0
12609 },
12610 {
12611 "thread-id": 25628,
12612 "props": {
12613 "core-id": 0,
12614 "thread-id": 0,
12615 "socket-id": 1
12616 },
12617 "qom-path": "/machine/unattached/device[2]",
12618 "arch":"x86",
12619 "target":"x86_64",
12620 "cpu-index": 1
12621 }
12622 ]
12623 }
12624 IOThreadInfo (Object)
12626 Information about an iothread
12628 Members:
12630 "id: string"
12632 the identifier of the iothread
12633 "thread-id: int"
12635 ID of the underlying host thread
12636 "poll-max-ns: int"
12638 maximum polling time in ns, 0 means polling is disabled (since 2.9)
12639 "poll-grow: int"
12641 how many ns will be added to polling time, 0 means that it's not
12642 configured (since 2.9)
12643 "poll-shrink: int"
12645 how many ns will be removed from polling time, 0 means that it's
12646 not configured (since 2.9)
12647 Since: 2.0
12649 query-iothreads (Command) Returns a list of information about each
12651 iothread.
12652 Note: this list excludes the QEMU main loop thread, which is not
12654 declared using the -object iothread command-line option. It is always
12655 the main thread of the process.
12656 Returns: a list of "IOThreadInfo" for each iothread
12658 Since: 2.0
12660 Example:
12662 -> { "execute": "query-iothreads" }
12664 <- { "return": [
12665 {
12666 "id":"iothread0",
12667 "thread-id":3134
12668 },
12669 {
12670 "id":"iothread1",
12671 "thread-id":3135
12672 }
12673 ]
12674 }
12675 BalloonInfo (Object)
12677 Information about the guest balloon device.
12679 Members:
12681 "actual: int"
12683 the number of bytes the balloon currently contains
12684 Since: 0.14.0
12686 query-balloon (Command) Return information about the balloon device.
12688 Returns: "BalloonInfo" on success
12690 If the balloon driver is enabled but not functional because the KVM
12692 kernel module cannot support it, KvmMissingCap
12693 If no balloon device is present, DeviceNotActive
12695 Since: 0.14.0
12697 Example:
12699 -> { "execute": "query-balloon" }
12701 <- { "return": {
12702 "actual": 1073741824,
12703 }
12704 }
12705 BALLOON_CHANGE (Event) Emitted when the guest changes the actual
12707 BALLOON level. This value is equivalent to the "actual" field return by
12708 the 'query-balloon' command
12709 Arguments:
12711 "actual: int"
12713 actual level of the guest memory balloon in bytes
12714 Note: this event is rate-limited.
12716 Since: 1.2
12718 Example:
12720 <- { "event": "BALLOON_CHANGE",
12722 "data": { "actual": 944766976 },
12723 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
12724 PciMemoryRange (Object)
12726 A PCI device memory region
12728 Members:
12730 "base: int"
12732 the starting address (guest physical)
12733 "limit: int"
12735 the ending address (guest physical)
12736 Since: 0.14.0
12738 PciMemoryRegion (Object)
12740 Information about a PCI device I/O region.
12742 Members:
12744 "bar: int"
12746 the index of the Base Address Register for this region
12747 "type: string"
12749 'io' if the region is a PIO region 'memory' if the region is a MMIO
12750 region
12751 "size: int"
12753 memory size
12754 "prefetch: boolean" (optional)
12756 if "type" is 'memory', true if the memory is prefetchable
12757 "mem_type_64: boolean" (optional)
12759 if "type" is 'memory', true if the BAR is 64-bit
12760 "address: int"
12762 Not documented
12763 Since: 0.14.0
12765 PciBusInfo (Object)
12767 Information about a bus of a PCI Bridge device
12769 Members:
12771 "number: int"
12773 primary bus interface number. This should be the number of the bus
12774 the device resides on.
12775 "secondary: int"
12777 secondary bus interface number. This is the number of the main bus
12778 for the bridge
12779 "subordinate: int"
12781 This is the highest number bus that resides below the bridge.
12782 "io_range: PciMemoryRange"
12784 The PIO range for all devices on this bridge
12785 "memory_range: PciMemoryRange"
12787 The MMIO range for all devices on this bridge
12788 "prefetchable_range: PciMemoryRange"
12790 The range of prefetchable MMIO for all devices on this bridge
12791 Since: 2.4
12793 PciBridgeInfo (Object)
12795 Information about a PCI Bridge device
12797 Members:
12799 "bus: PciBusInfo"
12801 information about the bus the device resides on
12802 "devices: array of PciDeviceInfo" (optional)
12804 a list of "PciDeviceInfo" for each device on this bridge
12805 Since: 0.14.0
12807 PciDeviceClass (Object)
12809 Information about the Class of a PCI device
12811 Members:
12813 "desc: string" (optional)
12815 a string description of the device's class
12816 "class: int"
12818 the class code of the device
12819 Since: 2.4
12821 PciDeviceId (Object)
12823 Information about the Id of a PCI device
12825 Members:
12827 "device: int"
12829 the PCI device id
12830 "vendor: int"
12832 the PCI vendor id
12833 "subsystem: int" (optional)
12835 the PCI subsystem id (since 3.1)
12836 "subsystem-vendor: int" (optional)
12838 the PCI subsystem vendor id (since 3.1)
12839 Since: 2.4
12841 PciDeviceInfo (Object)
12843 Information about a PCI device
12845 Members:
12847 "bus: int"
12849 the bus number of the device
12850 "slot: int"
12852 the slot the device is located in
12853 "function: int"
12855 the function of the slot used by the device
12856 "class_info: PciDeviceClass"
12858 the class of the device
12859 "id: PciDeviceId"
12861 the PCI device id
12862 "irq: int" (optional)
12864 if an IRQ is assigned to the device, the IRQ number
12865 "qdev_id: string"
12867 the device name of the PCI device
12868 "pci_bridge: PciBridgeInfo" (optional)
12870 if the device is a PCI bridge, the bridge information
12871 "regions: array of PciMemoryRegion"
12873 a list of the PCI I/O regions associated with the device
12874 Notes: the contents of "class_info".desc are not stable and should only
12876 be treated as informational.
12877 Since: 0.14.0
12879 PciInfo (Object)
12881 Information about a PCI bus
12883 Members:
12885 "bus: int"
12887 the bus index
12888 "devices: array of PciDeviceInfo"
12890 a list of devices on this bus
12891 Since: 0.14.0
12893 query-pci (Command) Return information about the PCI bus topology of
12895 the guest.
12896 Returns: a list of "PciInfo" for each PCI bus. Each bus is represented
12898 by a json-object, which has a key with a json-array of all PCI devices
12899 attached to it. Each device is represented by a json-object.
12900 Since: 0.14.0
12902 Example:
12904 -> { "execute": "query-pci" }
12906 <- { "return": [
12907 {
12908 "bus": 0,
12909 "devices": [
12910 {
12911 "bus": 0,
12912 "qdev_id": "",
12913 "slot": 0,
12914 "class_info": {
12915 "class": 1536,
12916 "desc": "Host bridge"
12917 },
12918 "id": {
12919 "device": 32902,
12920 "vendor": 4663
12921 },
12922 "function": 0,
12923 "regions": [
12924 ]
12925 },
12926 {
12927 "bus": 0,
12928 "qdev_id": "",
12929 "slot": 1,
12930 "class_info": {
12931 "class": 1537,
12932 "desc": "ISA bridge"
12933 },
12934 "id": {
12935 "device": 32902,
12936 "vendor": 28672
12937 },
12938 "function": 0,
12939 "regions": [
12940 ]
12941 },
12942 {
12943 "bus": 0,
12944 "qdev_id": "",
12945 "slot": 1,
12946 "class_info": {
12947 "class": 257,
12948 "desc": "IDE controller"
12949 },
12950 "id": {
12951 "device": 32902,
12952 "vendor": 28688
12953 },
12954 "function": 1,
12955 "regions": [
12956 {
12957 "bar": 4,
12958 "size": 16,
12959 "address": 49152,
12960 "type": "io"
12961 }
12962 ]
12963 },
12964 {
12965 "bus": 0,
12966 "qdev_id": "",
12967 "slot": 2,
12968 "class_info": {
12969 "class": 768,
12970 "desc": "VGA controller"
12971 },
12972 "id": {
12973 "device": 4115,
12974 "vendor": 184
12975 },
12976 "function": 0,
12977 "regions": [
12978 {
12979 "prefetch": true,
12980 "mem_type_64": false,
12981 "bar": 0,
12982 "size": 33554432,
12983 "address": 4026531840,
12984 "type": "memory"
12985 },
12986 {
12987 "prefetch": false,
12988 "mem_type_64": false,
12989 "bar": 1,
12990 "size": 4096,
12991 "address": 4060086272,
12992 "type": "memory"
12993 },
12994 {
12995 "prefetch": false,
12996 "mem_type_64": false,
12997 "bar": 6,
12998 "size": 65536,
12999 "address": -1,
13000 "type": "memory"
13001 }
13002 ]
13003 },
13004 {
13005 "bus": 0,
13006 "qdev_id": "",
13007 "irq": 11,
13008 "slot": 4,
13009 "class_info": {
13010 "class": 1280,
13011 "desc": "RAM controller"
13012 },
13013 "id": {
13014 "device": 6900,
13015 "vendor": 4098
13016 },
13017 "function": 0,
13018 "regions": [
13019 {
13020 "bar": 0,
13021 "size": 32,
13022 "address": 49280,
13023 "type": "io"
13024 }
13025 ]
13026 }
13027 ]
13028 }
13029 ]
13030 }
13031 Note: This example has been shortened as the real response is too long.
13033 quit (Command) This command will cause the QEMU process to exit
13035 gracefully. While every attempt is made to send the QMP response
13036 before terminating, this is not guaranteed. When using this interface,
13037 a premature EOF would not be unexpected.
13038 Since: 0.14.0
13040 Example:
13042 -> { "execute": "quit" }
13044 <- { "return": {} }
13045 stop (Command) Stop all guest VCPU execution.
13047 Since: 0.14.0
13049 Notes: This function will succeed even if the guest is already in the
13051 stopped state. In "inmigrate" state, it will ensure that the guest
13052 remains paused once migration finishes, as if the -S option was passed
13053 on the command line.
13054 Example:
13056 -> { "execute": "stop" }
13058 <- { "return": {} }
13059 system_reset (Command) Performs a hard reset of a guest.
13061 Since: 0.14.0
13063 Example:
13065 -> { "execute": "system_reset" }
13067 <- { "return": {} }
13068 system_powerdown (Command) Requests that a guest perform a powerdown
13070 operation.
13071 Since: 0.14.0
13073 Notes: A guest may or may not respond to this command. This command
13075 returning does not indicate that a guest has accepted the request or
13076 that it has shut down. Many guests will respond to this command by
13077 prompting the user in some way.
13078 Example:
13080 -> { "execute": "system_powerdown" }
13082 <- { "return": {} }
13083 cpu-add (Command) Adds CPU with specified ID
13085 Arguments:
13087 "id: int"
13089 ID of CPU to be created, valid values [0..max_cpus)
13090 Returns: Nothing on success
13092 Since: 1.5
13094 Example:
13096 -> { "execute": "cpu-add", "arguments": { "id": 2 } }
13098 <- { "return": {} }
13099 memsave (Command) Save a portion of guest memory to a file.
13101 Arguments:
13103 "val: int"
13105 the virtual address of the guest to start from
13106 "size: int"
13108 the size of memory region to save
13109 "filename: string"
13111 the file to save the memory to as binary data
13112 "cpu-index: int" (optional)
13114 the index of the virtual CPU to use for translating the virtual
13115 address (defaults to CPU 0)
13116 Returns: Nothing on success
13118 Since: 0.14.0
13120 Notes: Errors were not reliably returned until 1.1
13122 Example:
13124 -> { "execute": "memsave",
13126 "arguments": { "val": 10,
13127 "size": 100,
13128 "filename": "/tmp/virtual-mem-dump" } }
13129 <- { "return": {} }
13130 pmemsave (Command) Save a portion of guest physical memory to a file.
13132 Arguments:
13134 "val: int"
13136 the physical address of the guest to start from
13137 "size: int"
13139 the size of memory region to save
13140 "filename: string"
13142 the file to save the memory to as binary data
13143 Returns: Nothing on success
13145 Since: 0.14.0
13147 Notes: Errors were not reliably returned until 1.1
13149 Example:
13151 -> { "execute": "pmemsave",
13153 "arguments": { "val": 10,
13154 "size": 100,
13155 "filename": "/tmp/physical-mem-dump" } }
13156 <- { "return": {} }
13157 cont (Command) Resume guest VCPU execution.
13159 Since: 0.14.0
13161 Returns: If successful, nothing
13163 Notes: This command will succeed if the guest is currently running. It
13165 will also succeed if the guest is in the "inmigrate" state; in this
13166 case, the effect of the command is to make sure the guest starts once
13167 migration finishes, removing the effect of the -S command line option
13168 if it was passed.
13169 Example:
13171 -> { "execute": "cont" }
13173 <- { "return": {} }
13174 x-exit-preconfig (Command) Exit from "preconfig" state
13176 This command makes QEMU exit the preconfig state and proceed with VM
13178 initialization using configuration data provided on the command line
13179 and via the QMP monitor during the preconfig state. The command is only
13180 available during the preconfig state (i.e. when the --preconfig command
13181 line option was in use).
13182 Since 3.0
13184 Returns: nothing
13186 Example:
13188 -> { "execute": "x-exit-preconfig" }
13190 <- { "return": {} }
13191 system_wakeup (Command) Wakeup guest from suspend. Does nothing in
13193 case the guest isn't suspended.
13194 Since: 1.1
13196 Returns: nothing.
13198 Example:
13200 -> { "execute": "system_wakeup" }
13202 <- { "return": {} }
13203 inject-nmi (Command) Injects a Non-Maskable Interrupt into the default
13205 CPU (x86/s390) or all CPUs (ppc64). The command fails when the guest
13206 doesn't support injecting.
13207 Returns: If successful, nothing
13209 Since: 0.14.0
13211 Note: prior to 2.1, this command was only supported for x86 and s390
13213 VMs
13214 Example:
13216 -> { "execute": "inject-nmi" }
13218 <- { "return": {} }
13219 balloon (Command) Request the balloon driver to change its balloon
13221 size.
13222 Arguments:
13224 "value: int"
13226 the target size of the balloon in bytes
13227 Returns: Nothing on success If the balloon driver is enabled but not
13229 functional because the KVM kernel module cannot support it,
13230 KvmMissingCap If no balloon device is present, DeviceNotActive
13231 Notes: This command just issues a request to the guest. When it
13233 returns, the balloon size may not have changed. A guest can change the
13234 balloon size independent of this command.
13235 Since: 0.14.0
13237 Example:
13239 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
13241 <- { "return": {} }
13242 human-monitor-command (Command) Execute a command on the human monitor
13244 and return the output.
13245 Arguments:
13247 "command-line: string"
13249 the command to execute in the human monitor
13250 "cpu-index: int" (optional)
13252 The CPU to use for commands that require an implicit CPU
13253 Returns: the output of the command as a string
13255 Since: 0.14.0
13257 Notes: This command only exists as a stop-gap. Its use is highly
13259 discouraged. The semantics of this command are not guaranteed: this
13260 means that command names, arguments and responses can change or be
13261 removed at ANY time. Applications that rely on long term stability
13262 guarantees should NOT use this command.
13263 Known limitations:
13265 · This command is stateless, this means that commands that depend on
13267 state information (such as getfd) might not work
13268 · Commands that prompt the user for data don't currently work
13270 Example:
13272 -> { "execute": "human-monitor-command",
13274 "arguments": { "command-line": "info kvm" } }
13275 <- { "return": "kvm support: enabled\r\n" }
13276 ObjectPropertyInfo (Object)
13278 Members:
13280 "name: string"
13282 the name of the property
13283 "type: string"
13285 the type of the property. This will typically come in one of four
13286 forms:
13287 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or
13289 'double'. These types are mapped to the appropriate JSON type.
13290 2) A child type in the form 'child<subtype>' where subtype is a
13292 qdev device type name. Child properties create the composition
13293 tree.
13294 3) A link type in the form 'link<subtype>' where subtype is a qdev
13296 device type name. Link properties form the device model graph.
13297 "description: string" (optional)
13299 if specified, the description of the property.
13300 Since: 1.2
13302 qom-list (Command) This command will list any properties of a object
13304 given a path in the object model.
13305 Arguments:
13307 "path: string"
13309 the path within the object model. See "qom-get" for a description
13310 of this parameter.
13311 Returns: a list of "ObjectPropertyInfo" that describe the properties of
13313 the object.
13314 Since: 1.2
13316 qom-get (Command) This command will get a property from a object model
13318 path and return the value.
13319 Arguments:
13321 "path: string"
13323 The path within the object model. There are two forms of supported
13324 paths--absolute and partial paths.
13325 Absolute paths are derived from the root object and can follow
13327 child<> or link<> properties. Since they can follow link<>
13328 properties, they can be arbitrarily long. Absolute paths look like
13329 absolute filenames and are prefixed with a leading slash.
13330 Partial paths look like relative filenames. They do not begin with
13332 a prefix. The matching rules for partial paths are subtle but
13333 designed to make specifying objects easy. At each level of the
13334 composition tree, the partial path is matched as an absolute path.
13335 The first match is not returned. At least two matches are searched
13336 for. A successful result is only returned if only one match is
13337 found. If more than one match is found, a flag is return to
13338 indicate that the match was ambiguous.
13339 "property: string"
13341 The property name to read
13342 Returns: The property value. The type depends on the property type.
13344 child<> and link<> properties are returned as #str pathnames. All
13345 integer property types (u8, u16, etc) are returned as #int.
13346 Since: 1.2
13348 qom-set (Command) This command will set a property from a object model
13350 path.
13351 Arguments:
13353 "path: string"
13355 see "qom-get" for a description of this parameter
13356 "property: string"
13358 the property name to set
13359 "value: value"
13361 a value who's type is appropriate for the property type. See
13362 "qom-get" for a description of type mapping.
13363 Since: 1.2
13365 change (Command) This command is multiple commands multiplexed
13367 together.
13368 Arguments:
13370 "device: string"
13372 This is normally the name of a block device but it may also be
13373 'vnc'. when it's 'vnc', then sub command depends on "target"
13374 "target: string"
13376 If "device" is a block device, then this is the new filename. If
13377 "device" is 'vnc', then if the value 'password' selects the vnc
13378 change password command. Otherwise, this specifies a new server
13379 URI address to listen to for VNC connections.
13380 "arg: string" (optional)
13382 If "device" is a block device, then this is an optional format to
13383 open the device with. If "device" is 'vnc' and "target" is
13384 'password', this is the new VNC password to set. See change-vnc-
13385 password for additional notes.
13386 Returns: Nothing on success. If "device" is not a valid block device,
13388 DeviceNotFound
13389 Notes: This interface is deprecated, and it is strongly recommended
13391 that you avoid using it. For changing block devices, use blockdev-
13392 change-medium; for changing VNC parameters, use change-vnc-password.
13393 Since: 0.14.0
13395 Example:
13397 1. Change a removable medium
13399 -> { "execute": "change",
13401 "arguments": { "device": "ide1-cd0",
13402 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
13403 <- { "return": {} }
13404 2. Change VNC password
13406 -> { "execute": "change",
13408 "arguments": { "device": "vnc", "target": "password",
13409 "arg": "foobar1" } }
13410 <- { "return": {} }
13411 ObjectTypeInfo (Object)
13413 This structure describes a search result from "qom-list-types"
13415 Members:
13417 "name: string"
13419 the type name found in the search
13420 "abstract: boolean" (optional)
13422 the type is abstract and can't be directly instantiated. Omitted
13423 if false. (since 2.10)
13424 "parent: string" (optional)
13426 Name of parent type, if any (since 2.10)
13427 Since: 1.1
13429 qom-list-types (Command) This command will return a list of types
13431 given search parameters
13432 Arguments:
13434 "implements: string" (optional)
13436 if specified, only return types that implement this type name
13437 "abstract: boolean" (optional)
13439 if true, include abstract types in the results
13440 Returns: a list of "ObjectTypeInfo" or an empty list if no results are
13442 found
13443 Since: 1.1
13445 device-list-properties (Command) List properties associated with a
13447 device.
13448 Arguments:
13450 "typename: string"
13452 the type name of a device
13453 Returns: a list of ObjectPropertyInfo describing a devices properties
13455 Note: objects can create properties at runtime, for example to describe
13457 links between different devices and/or objects. These properties are
13458 not included in the output of this command.
13459 Since: 1.2
13461 qom-list-properties (Command) List properties associated with a QOM
13463 object.
13464 Arguments:
13466 "typename: string"
13468 the type name of an object
13469 Note: objects can create properties at runtime, for example to describe
13471 links between different devices and/or objects. These properties are
13472 not included in the output of this command.
13473 Returns: a list of ObjectPropertyInfo describing object properties
13475 Since: 2.12
13477 xen-set-global-dirty-log (Command) Enable or disable the global dirty
13479 log mode.
13480 Arguments:
13482 "enable: boolean"
13484 true to enable, false to disable.
13485 Returns: nothing
13487 Since: 1.3
13489 Example:
13491 -> { "execute": "xen-set-global-dirty-log",
13493 "arguments": { "enable": true } }
13494 <- { "return": {} }
13495 device_add (Command)
13497 Arguments:
13499 "driver: string"
13501 the name of the new device's driver
13502 "bus: string" (optional)
13504 the device's parent bus (device tree path)
13505 "id: string" (optional)
13507 the device's ID, must be unique
13508 Additional arguments depend on the type.
13510 Add a device.
13512 Notes:
13514 1. For detailed information about this command, please refer to the
13516 'docs/qdev-device-use.txt' file.
13517 2. It's possible to list device properties by running QEMU with the
13519 "-device DEVICE,help" command-line argument, where DEVICE is the
13520 device's name
13521 Example:
13523 -> { "execute": "device_add",
13525 "arguments": { "driver": "e1000", "id": "net1",
13526 "bus": "pci.0",
13527 "mac": "52:54:00:12:34:56" } }
13528 <- { "return": {} }
13529 TODO: This command effectively bypasses QAPI completely due to its
13531 "additional arguments" business. It shouldn't have been added to the
13532 schema in this form. It should be qapified properly, or replaced by a
13533 properly qapified command.
13534 Since: 0.13
13536 device_del (Command) Remove a device from a guest
13538 Arguments:
13540 "id: string"
13542 the device's ID or QOM path
13543 Returns: Nothing on success If "id" is not a valid device,
13545 DeviceNotFound
13546 Notes: When this command completes, the device may not be removed from
13548 the guest. Hot removal is an operation that requires guest
13549 cooperation. This command merely requests that the guest begin the hot
13550 removal process. Completion of the device removal process is signaled
13551 with a DEVICE_DELETED event. Guest reset will automatically complete
13552 removal for all devices.
13553 Since: 0.14.0
13555 Example:
13557 -> { "execute": "device_del",
13559 "arguments": { "id": "net1" } }
13560 <- { "return": {} }
13561 -> { "execute": "device_del",
13563 "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
13564 <- { "return": {} }
13565 DEVICE_DELETED (Event) Emitted whenever the device removal completion
13567 is acknowledged by the guest. At this point, it's safe to reuse the
13568 specified device ID. Device removal can be initiated by the guest or by
13569 HMP/QMP commands.
13570 Arguments:
13572 "device: string" (optional)
13574 device name
13575 "path: string"
13577 device path
13578 Since: 1.5
13580 Example:
13582 <- { "event": "DEVICE_DELETED",
13584 "data": { "device": "virtio-net-pci-0",
13585 "path": "/machine/peripheral/virtio-net-pci-0" },
13586 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
13587 DumpGuestMemoryFormat (Enum)
13589 An enumeration of guest-memory-dump's format.
13591 Values:
13593 "elf"
13595 elf format
13596 "kdump-zlib"
13598 kdump-compressed format with zlib-compressed
13599 "kdump-lzo"
13601 kdump-compressed format with lzo-compressed
13602 "kdump-snappy"
13604 kdump-compressed format with snappy-compressed
13605 "win-dmp"
13607 Windows full crashdump format, can be used instead of ELF
13608 converting (since 2.13)
13609 Since: 2.0
13611 dump-guest-memory (Command) Dump guest's memory to vmcore. It is a
13613 synchronous operation that can take very long depending on the amount
13614 of guest memory.
13615 Arguments:
13617 "paging: boolean"
13619 if true, do paging to get guest's memory mapping. This allows using
13620 gdb to process the core file.
13621 IMPORTANT: this option can make QEMU allocate several gigabytes of
13623 RAM. This can happen for a large guest, or a malicious guest
13624 pretending to be large.
13625 Also, paging=true has the following limitations:
13627 1. The guest may be in a catastrophic state or can have corrupted
13629 memory, which cannot be trusted
13630 2. The guest can be in real-mode even if paging is enabled. For
13632 example, the guest uses ACPI to sleep, and ACPI sleep state
13633 goes in real-mode
13634 3. Currently only supported on i386 and x86_64.
13636 "protocol: string"
13638 the filename or file descriptor of the vmcore. The supported
13639 protocols are:
13640 1. file: the protocol starts with "file:", and the following
13642 string is the file's path.
13643 2. fd: the protocol starts with "fd:", and the following string is
13645 the fd's name.
13646 "detach: boolean" (optional)
13648 if true, QMP will return immediately rather than waiting for the
13649 dump to finish. The user can track progress using "query-dump".
13650 (since 2.6).
13651 "begin: int" (optional)
13653 if specified, the starting physical address.
13654 "length: int" (optional)
13656 if specified, the memory size, in bytes. If you don't want to dump
13657 all guest's memory, please specify the start "begin" and "length"
13658 "format: DumpGuestMemoryFormat" (optional)
13660 if specified, the format of guest memory dump. But non-elf format
13661 is conflict with paging and filter, ie. "paging", "begin" and
13662 "length" is not allowed to be specified with non-elf "format" at
13663 the same time (since 2.0)
13664 Note: All boolean arguments default to false
13666 Returns: nothing on success
13668 Since: 1.2
13670 Example:
13672 -> { "execute": "dump-guest-memory",
13674 "arguments": { "protocol": "fd:dump" } }
13675 <- { "return": {} }
13676 DumpStatus (Enum)
13678 Describe the status of a long-running background guest memory dump.
13680 Values:
13682 "none"
13684 no dump-guest-memory has started yet.
13685 "active"
13687 there is one dump running in background.
13688 "completed"
13690 the last dump has finished successfully.
13691 "failed"
13693 the last dump has failed.
13694 Since: 2.6
13696 DumpQueryResult (Object)
13698 The result format for 'query-dump'.
13700 Members:
13702 "status: DumpStatus"
13704 enum of "DumpStatus", which shows current dump status
13705 "completed: int"
13707 bytes written in latest dump (uncompressed)
13708 "total: int"
13710 total bytes to be written in latest dump (uncompressed)
13711 Since: 2.6
13713 query-dump (Command) Query latest dump status.
13715 Returns: A "DumpStatus" object showing the dump status.
13717 Since: 2.6
13719 Example:
13721 -> { "execute": "query-dump" }
13723 <- { "return": { "status": "active", "completed": 1024000,
13724 "total": 2048000 } }
13725 DUMP_COMPLETED (Event) Emitted when background dump has completed
13727 Arguments:
13729 "result: DumpQueryResult"
13731 final dump status
13732 "error: string" (optional)
13734 human-readable error string that provides hint on why dump failed.
13735 Only presents on failure. The user should not try to interpret the
13736 error string.
13737 Since: 2.6
13739 Example:
13741 { "event": "DUMP_COMPLETED",
13743 "data": {"result": {"total": 1090650112, "status": "completed",
13744 "completed": 1090650112} } }
13745 DumpGuestMemoryCapability (Object)
13747 A list of the available formats for dump-guest-memory
13749 Members:
13751 "formats: array of DumpGuestMemoryFormat"
13753 Not documented
13754 Since: 2.0
13756 query-dump-guest-memory-capability (Command) Returns the available
13758 formats for dump-guest-memory
13759 Returns: A "DumpGuestMemoryCapability" object listing available formats
13761 for dump-guest-memory
13762 Since: 2.0
13764 Example:
13766 -> { "execute": "query-dump-guest-memory-capability" }
13768 <- { "return": { "formats":
13769 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
13770 dump-skeys (Command) Dump guest's storage keys
13772 Arguments:
13774 "filename: string"
13776 the path to the file to dump to
13777 This command is only supported on s390 architecture.
13779 Since: 2.5
13781 Example:
13783 -> { "execute": "dump-skeys",
13785 "arguments": { "filename": "/tmp/skeys" } }
13786 <- { "return": {} }
13787 object-add (Command) Create a QOM object.
13789 Arguments:
13791 "qom-type: string"
13793 the class name for the object to be created
13794 "id: string"
13796 the name of the new object
13797 "props: value" (optional)
13799 a dictionary of properties to be passed to the backend
13800 Returns: Nothing on success Error if "qom-type" is not a valid class
13802 name
13803 Since: 2.0
13805 Example:
13807 -> { "execute": "object-add",
13809 "arguments": { "qom-type": "rng-random", "id": "rng1",
13810 "props": { "filename": "/dev/hwrng" } } }
13811 <- { "return": {} }
13812 object-del (Command) Remove a QOM object.
13814 Arguments:
13816 "id: string"
13818 the name of the QOM object to remove
13819 Returns: Nothing on success Error if "id" is not a valid id for a QOM
13821 object
13822 Since: 2.0
13824 Example:
13826 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
13828 <- { "return": {} }
13829 getfd (Command) Receive a file descriptor via SCM rights and assign it
13831 a name
13832 Arguments:
13834 "fdname: string"
13836 file descriptor name
13837 Returns: Nothing on success
13839 Since: 0.14.0
13841 Notes: If "fdname" already exists, the file descriptor assigned to it
13843 will be closed and replaced by the received file descriptor.
13844 The 'closefd' command can be used to explicitly close the file
13846 descriptor when it is no longer needed.
13847 Example:
13849 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
13851 <- { "return": {} }
13852 closefd (Command) Close a file descriptor previously passed via SCM
13854 rights
13855 Arguments:
13857 "fdname: string"
13859 file descriptor name
13860 Returns: Nothing on success
13862 Since: 0.14.0
13864 Example:
13866 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
13868 <- { "return": {} }
13869 MachineInfo (Object)
13871 Information describing a machine.
13873 Members:
13875 "name: string"
13877 the name of the machine
13878 "alias: string" (optional)
13880 an alias for the machine name
13881 "is-default: boolean" (optional)
13883 whether the machine is default
13884 "cpu-max: int"
13886 maximum number of CPUs supported by the machine type (since 1.5.0)
13887 "hotpluggable-cpus: boolean"
13889 cpu hotplug via -device is supported (since 2.7.0)
13890 Since: 1.2.0
13892 query-machines (Command) Return a list of supported machines
13894 Returns: a list of MachineInfo
13896 Since: 1.2.0
13898 CpuDefinitionInfo (Object)
13900 Virtual CPU definition.
13902 Members:
13904 "name: string"
13906 the name of the CPU definition
13907 "migration-safe: boolean" (optional)
13909 whether a CPU definition can be safely used for migration in
13910 combination with a QEMU compatibility machine when migrating
13911 between different QEMU versions and between hosts with different
13912 sets of (hardware or software) capabilities. If not provided,
13913 information is not available and callers should not assume the CPU
13914 definition to be migration-safe. (since 2.8)
13915 "static: boolean"
13917 whether a CPU definition is static and will not change depending on
13918 QEMU version, machine type, machine options and accelerator
13919 options. A static model is always migration-safe. (since 2.8)
13920 "unavailable-features: array of string" (optional)
13922 List of properties that prevent the CPU model from running in the
13923 current host. (since 2.8)
13924 "typename: string"
13926 Type name that can be used as argument to "device-list-properties",
13927 to introspect properties configurable using -cpu or -global.
13928 (since 2.9)
13929 "unavailable-features" is a list of QOM property names that represent
13931 CPU model attributes that prevent the CPU from running. If the QOM
13932 property is read-only, that means there's no known way to make the CPU
13933 model run in the current host. Implementations that choose not to
13934 provide specific information return the property name "type". If the
13935 property is read-write, it means that it MAY be possible to run the CPU
13936 model in the current host if that property is changed. Management
13937 software can use it as hints to suggest or choose an alternative for
13938 the user, or just to generate meaningful error messages explaining why
13939 the CPU model can't be used. If "unavailable-features" is an empty
13940 list, the CPU model is runnable using the current host and machine-
13941 type. If "unavailable-features" is not present, runnability
13942 information for the CPU is not available.
13943 Since: 1.2.0
13945 MemoryInfo (Object)
13947 Actual memory information in bytes.
13949 Members:
13951 "base-memory: int"
13953 size of "base" memory specified with command line option -m.
13954 "plugged-memory: int" (optional)
13956 size of memory that can be hot-unplugged. This field is omitted if
13957 target doesn't support memory hotplug (i.e. CONFIG_MEM_DEVICE not
13958 defined at build time).
13959 Since: 2.11.0
13961 query-memory-size-summary (Command) Return the amount of initially
13963 allocated and present hotpluggable (if enabled) memory in bytes.
13964 Example:
13966 -> { "execute": "query-memory-size-summary" }
13968 <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
13969 Since: 2.11.0
13971 query-cpu-definitions (Command) Return a list of supported virtual CPU
13973 definitions
13974 Returns: a list of CpuDefInfo
13976 Since: 1.2.0
13978 CpuModelInfo (Object)
13980 Virtual CPU model.
13982 A CPU model consists of the name of a CPU definition, to which delta
13984 changes are applied (e.g. features added/removed). Most magic values
13985 that an architecture might require should be hidden behind the name.
13986 However, if required, architectures can expose relevant properties.
13987 Members:
13989 "name: string"
13991 the name of the CPU definition the model is based on
13992 "props: value" (optional)
13994 a dictionary of QOM properties to be applied
13995 Since: 2.8.0
13997 CpuModelExpansionType (Enum)
13999 An enumeration of CPU model expansion types.
14001 Values:
14003 "static"
14005 Expand to a static CPU model, a combination of a static base model
14006 name and property delta changes. As the static base model will
14007 never change, the expanded CPU model will be the same, independent
14008 of QEMU version, machine type, machine options, and accelerator
14009 options. Therefore, the resulting model can be used by tooling
14010 without having to specify a compatibility machine - e.g. when
14011 displaying the "host" model. The "static" CPU models are migration-
14012 safe.
14013 "full"
14015 Expand all properties. The produced model is not guaranteed to be
14016 migration-safe, but allows tooling to get an insight and work with
14017 model details.
14018 Note: When a non-migration-safe CPU model is expanded in static mode,
14020 some features enabled by the CPU model may be omitted, because they
14021 can't be implemented by a static CPU model definition (e.g. cache info
14022 passthrough and PMU passthrough in x86). If you need an accurate
14023 representation of the features enabled by a non-migration-safe CPU
14024 model, use "full". If you need a static representation that will keep
14025 ABI compatibility even when changing QEMU version or machine-type, use
14026 "static" (but keep in mind that some features may be omitted).
14027 Since: 2.8.0
14029 CpuModelExpansionInfo (Object)
14031 The result of a cpu model expansion.
14033 Members:
14035 "model: CpuModelInfo"
14037 the expanded CpuModelInfo.
14038 Since: 2.8.0
14040 query-cpu-model-expansion (Command) Expands a given CPU model (or a
14042 combination of CPU model + additional options) to different
14043 granularities, allowing tooling to get an understanding what a specific
14044 CPU model looks like in QEMU under a certain configuration.
14045 This interface can be used to query the "host" CPU model.
14047 The data returned by this command may be affected by:
14049 · QEMU version: CPU models may look different depending on the QEMU
14051 version. (Except for CPU models reported as "static" in query-cpu-
14052 definitions.)
14053 · machine-type: CPU model may look different depending on the
14055 machine-type. (Except for CPU models reported as "static" in
14056 query-cpu-definitions.)
14057 · machine options (including accelerator): in some architectures, CPU
14059 models may look different depending on machine and accelerator
14060 options. (Except for CPU models reported as "static" in query-cpu-
14061 definitions.)
14062 · "-cpu" arguments and global properties: arguments to the -cpu
14064 option and global properties may affect expansion of CPU models.
14065 Using query-cpu-model-expansion while using these is not advised.
14066 Some architectures may not support all expansion types. s390x supports
14068 "full" and "static".
14069 Arguments:
14071 "type: CpuModelExpansionType"
14073 Not documented
14074 "model: CpuModelInfo"
14076 Not documented
14077 Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU
14079 models is not supported, if the model cannot be expanded, if the model
14080 contains an unknown CPU definition name, unknown properties or
14081 properties with a wrong type. Also returns an error if an expansion
14082 type is not supported.
14083 Since: 2.8.0
14085 CpuModelCompareResult (Enum)
14087 An enumeration of CPU model comparison results. The result is usually
14089 calculated using e.g. CPU features or CPU generations.
14090 Values:
14092 "incompatible"
14094 If model A is incompatible to model B, model A is not guaranteed to
14095 run where model B runs and the other way around.
14096 "identical"
14098 If model A is identical to model B, model A is guaranteed to run
14099 where model B runs and the other way around.
14100 "superset"
14102 If model A is a superset of model B, model B is guaranteed to run
14103 where model A runs. There are no guarantees about the other way.
14104 "subset"
14106 If model A is a subset of model B, model A is guaranteed to run
14107 where model B runs. There are no guarantees about the other way.
14108 Since: 2.8.0
14110 CpuModelCompareInfo (Object)
14112 The result of a CPU model comparison.
14114 Members:
14116 "result: CpuModelCompareResult"
14118 The result of the compare operation.
14119 "responsible-properties: array of string"
14121 List of properties that led to the comparison result not being
14122 identical.
14123 "responsible-properties" is a list of QOM property names that led to
14125 both CPUs not being detected as identical. For identical models, this
14126 list is empty. If a QOM property is read-only, that means there's no
14127 known way to make the CPU models identical. If the special property
14128 name "type" is included, the models are by definition not identical and
14129 cannot be made identical.
14130 Since: 2.8.0
14132 query-cpu-model-comparison (Command) Compares two CPU models,
14134 returning how they compare in a specific configuration. The results
14135 indicates how both models compare regarding runnability. This result
14136 can be used by tooling to make decisions if a certain CPU model will
14137 run in a certain configuration or if a compatible CPU model has to be
14138 created by baselining.
14139 Usually, a CPU model is compared against the maximum possible CPU model
14141 of a certain configuration (e.g. the "host" model for KVM). If that CPU
14142 model is identical or a subset, it will run in that configuration.
14143 The result returned by this command may be affected by:
14145 · QEMU version: CPU models may look different depending on the QEMU
14147 version. (Except for CPU models reported as "static" in query-cpu-
14148 definitions.)
14149 · machine-type: CPU model may look different depending on the
14151 machine-type. (Except for CPU models reported as "static" in
14152 query-cpu-definitions.)
14153 · machine options (including accelerator): in some architectures, CPU
14155 models may look different depending on machine and accelerator
14156 options. (Except for CPU models reported as "static" in query-cpu-
14157 definitions.)
14158 · "-cpu" arguments and global properties: arguments to the -cpu
14160 option and global properties may affect expansion of CPU models.
14161 Using query-cpu-model-expansion while using these is not advised.
14162 Some architectures may not support comparing CPU models. s390x supports
14164 comparing CPU models.
14165 Arguments:
14167 "modela: CpuModelInfo"
14169 Not documented
14170 "modelb: CpuModelInfo"
14172 Not documented
14173 Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU
14175 models is not supported, if a model cannot be used, if a model contains
14176 an unknown cpu definition name, unknown properties or properties with
14177 wrong types.
14178 Since: 2.8.0
14180 CpuModelBaselineInfo (Object)
14182 The result of a CPU model baseline.
14184 Members:
14186 "model: CpuModelInfo"
14188 the baselined CpuModelInfo.
14189 Since: 2.8.0
14191 query-cpu-model-baseline (Command) Baseline two CPU models, creating a
14193 compatible third model. The created model will always be a static,
14194 migration-safe CPU model (see "static" CPU model expansion for
14195 details).
14196 This interface can be used by tooling to create a compatible CPU model
14198 out two CPU models. The created CPU model will be identical to or a
14199 subset of both CPU models when comparing them. Therefore, the created
14200 CPU model is guaranteed to run where the given CPU models run.
14201 The result returned by this command may be affected by:
14203 · QEMU version: CPU models may look different depending on the QEMU
14205 version. (Except for CPU models reported as "static" in query-cpu-
14206 definitions.)
14207 · machine-type: CPU model may look different depending on the
14209 machine-type. (Except for CPU models reported as "static" in
14210 query-cpu-definitions.)
14211 · machine options (including accelerator): in some architectures, CPU
14213 models may look different depending on machine and accelerator
14214 options. (Except for CPU models reported as "static" in query-cpu-
14215 definitions.)
14216 · "-cpu" arguments and global properties: arguments to the -cpu
14218 option and global properties may affect expansion of CPU models.
14219 Using query-cpu-model-expansion while using these is not advised.
14220 Some architectures may not support baselining CPU models. s390x
14222 supports baselining CPU models.
14223 Arguments:
14225 "modela: CpuModelInfo"
14227 Not documented
14228 "modelb: CpuModelInfo"
14230 Not documented
14231 Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU
14233 models is not supported, if a model cannot be used, if a model contains
14234 an unknown cpu definition name, unknown properties or properties with
14235 wrong types.
14236 Since: 2.8.0
14238 AddfdInfo (Object)
14240 Information about a file descriptor that was added to an fd set.
14242 Members:
14244 "fdset-id: int"
14246 The ID of the fd set that "fd" was added to.
14247 "fd: int"
14249 The file descriptor that was received via SCM rights and added to
14250 the fd set.
14251 Since: 1.2.0
14253 add-fd (Command) Add a file descriptor, that was passed via SCM
14255 rights, to an fd set.
14256 Arguments:
14258 "fdset-id: int" (optional)
14260 The ID of the fd set to add the file descriptor to.
14261 "opaque: string" (optional)
14263 A free-form string that can be used to describe the fd.
14264 Returns: "AddfdInfo" on success
14266 If file descriptor was not received, FdNotSupplied
14268 If "fdset-id" is a negative value, InvalidParameterValue
14270 Notes: The list of fd sets is shared by all monitor connections.
14272 If "fdset-id" is not specified, a new fd set will be created.
14274 Since: 1.2.0
14276 Example:
14278 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
14280 <- { "return": { "fdset-id": 1, "fd": 3 } }
14281 remove-fd (Command) Remove a file descriptor from an fd set.
14283 Arguments:
14285 "fdset-id: int"
14287 The ID of the fd set that the file descriptor belongs to.
14288 "fd: int" (optional)
14290 The file descriptor that is to be removed.
14291 Returns: Nothing on success If "fdset-id" or "fd" is not found,
14293 FdNotFound
14294 Since: 1.2.0
14296 Notes: The list of fd sets is shared by all monitor connections.
14298 If "fd" is not specified, all file descriptors in "fdset-id" will be
14300 removed.
14301 Example:
14303 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
14305 <- { "return": {} }
14306 FdsetFdInfo (Object)
14308 Information about a file descriptor that belongs to an fd set.
14310 Members:
14312 "fd: int"
14314 The file descriptor value.
14315 "opaque: string" (optional)
14317 A free-form string that can be used to describe the fd.
14318 Since: 1.2.0
14320 FdsetInfo (Object)
14322 Information about an fd set.
14324 Members:
14326 "fdset-id: int"
14328 The ID of the fd set.
14329 "fds: array of FdsetFdInfo"
14331 A list of file descriptors that belong to this fd set.
14332 Since: 1.2.0
14334 query-fdsets (Command) Return information describing all fd sets.
14336 Returns: A list of "FdsetInfo"
14338 Since: 1.2.0
14340 Note: The list of fd sets is shared by all monitor connections.
14342 Example:
14344 -> { "execute": "query-fdsets" }
14346 <- { "return": [
14347 {
14348 "fds": [
14349 {
14350 "fd": 30,
14351 "opaque": "rdonly:/path/to/file"
14352 },
14353 {
14354 "fd": 24,
14355 "opaque": "rdwr:/path/to/file"
14356 }
14357 ],
14358 "fdset-id": 1
14359 },
14360 {
14361 "fds": [
14362 {
14363 "fd": 28
14364 },
14365 {
14366 "fd": 29
14367 }
14368 ],
14369 "fdset-id": 0
14370 }
14371 ]
14372 }
14373 TargetInfo (Object)
14375 Information describing the QEMU target.
14377 Members:
14379 "arch: SysEmuTarget"
14381 the target architecture
14382 Since: 1.2.0
14384 query-target (Command) Return information about the target for this
14386 QEMU
14387 Returns: TargetInfo
14389 Since: 1.2.0
14391 AcpiTableOptions (Object)
14393 Specify an ACPI table on the command line to load.
14395 At most one of "file" and "data" can be specified. The list of files
14397 specified by any one of them is loaded and concatenated in order. If
14398 both are omitted, "data" is implied.
14399 Other fields / optargs can be used to override fields of the generic
14401 ACPI table header; refer to the ACPI specification 5.0, section 5.2.6
14402 System Description Table Header. If a header field is not overridden,
14403 then the corresponding value from the concatenated blob is used (in
14404 case of "file"), or it is filled in with a hard-coded value (in case of
14405 "data").
14406 String fields are copied into the matching ACPI member from lowest
14408 address upwards, and silently truncated / NUL-padded to length.
14409 Members:
14411 "sig: string" (optional)
14413 table signature / identifier (4 bytes)
14414 "rev: int" (optional)
14416 table revision number (dependent on signature, 1 byte)
14417 "oem_id: string" (optional)
14419 OEM identifier (6 bytes)
14420 "oem_table_id: string" (optional)
14422 OEM table identifier (8 bytes)
14423 "oem_rev: int" (optional)
14425 OEM-supplied revision number (4 bytes)
14426 "asl_compiler_id: string" (optional)
14428 identifier of the utility that created the table (4 bytes)
14429 "asl_compiler_rev: int" (optional)
14431 revision number of the utility that created the table (4 bytes)
14432 "file: string" (optional)
14434 colon (:) separated list of pathnames to load and concatenate as
14435 table data. The resultant binary blob is expected to have an ACPI
14436 table header. At least one file is required. This field excludes
14437 "data".
14438 "data: string" (optional)
14440 colon (:) separated list of pathnames to load and concatenate as
14441 table data. The resultant binary blob must not have an ACPI table
14442 header. At least one file is required. This field excludes "file".
14443 Since: 1.5
14445 CommandLineParameterType (Enum)
14447 Possible types for an option parameter.
14449 Values:
14451 "string"
14453 accepts a character string
14454 "boolean"
14456 accepts "on" or "off"
14457 "number"
14459 accepts a number
14460 "size"
14462 accepts a number followed by an optional suffix (K)ilo, (M)ega,
14463 (G)iga, (T)era
14464 Since: 1.5
14466 CommandLineParameterInfo (Object)
14468 Details about a single parameter of a command line option.
14470 Members:
14472 "name: string"
14474 parameter name
14475 "type: CommandLineParameterType"
14477 parameter "CommandLineParameterType"
14478 "help: string" (optional)
14480 human readable text string, not suitable for parsing.
14481 "default: string" (optional)
14483 default value string (since 2.1)
14484 Since: 1.5
14486 CommandLineOptionInfo (Object)
14488 Details about a command line option, including its list of parameter
14490 details
14491 Members:
14493 "option: string"
14495 option name
14496 "parameters: array of CommandLineParameterInfo"
14498 an array of "CommandLineParameterInfo"
14499 Since: 1.5
14501 query-command-line-options (Command) Query command line option schema.
14503 Arguments:
14505 "option: string" (optional)
14507 option name
14508 Returns: list of "CommandLineOptionInfo" for all options (or for the
14510 given "option"). Returns an error if the given "option" doesn't exist.
14511 Since: 1.5
14513 Example:
14515 -> { "execute": "query-command-line-options",
14517 "arguments": { "option": "option-rom" } }
14518 <- { "return": [
14519 {
14520 "parameters": [
14521 {
14522 "name": "romfile",
14523 "type": "string"
14524 },
14525 {
14526 "name": "bootindex",
14527 "type": "number"
14528 }
14529 ],
14530 "option": "option-rom"
14531 }
14532 ]
14533 }
14534 X86CPURegister32 (Enum)
14536 A X86 32-bit register
14538 Values:
14540 "EAX"
14542 Not documented
14543 "EBX"
14545 Not documented
14546 "ECX"
14548 Not documented
14549 "EDX"
14551 Not documented
14552 "ESP"
14554 Not documented
14555 "EBP"
14557 Not documented
14558 "ESI"
14560 Not documented
14561 "EDI"
14563 Not documented
14564 Since: 1.5
14566 X86CPUFeatureWordInfo (Object)
14568 Information about a X86 CPU feature word
14570 Members:
14572 "cpuid-input-eax: int"
14574 Input EAX value for CPUID instruction for that feature word
14575 "cpuid-input-ecx: int" (optional)
14577 Input ECX value for CPUID instruction for that feature word
14578 "cpuid-register: X86CPURegister32"
14580 Output register containing the feature bits
14581 "features: int"
14583 value of output register, containing the feature bits
14584 Since: 1.5
14586 DummyForceArrays (Object)
14588 Not used by QMP; hack to let us use X86CPUFeatureWordInfoList
14590 internally
14591 Members:
14593 "unused: array of X86CPUFeatureWordInfo"
14595 Not documented
14596 Since: 2.5
14598 NumaOptionsType (Enum)
14600 Values:
14602 "node"
14604 NUMA nodes configuration
14605 "dist"
14607 NUMA distance configuration (since 2.10)
14608 "cpu"
14610 property based CPU(s) to node mapping (Since: 2.10)
14611 Since: 2.1
14613 NumaOptions (Object)
14615 A discriminated record of NUMA options. (for OptsVisitor)
14617 Members:
14619 "type: NumaOptionsType"
14621 Not documented
14622 The members of "NumaNodeOptions" when "type" is "node"
14624 The members of "NumaDistOptions" when "type" is "dist"
14625 The members of "NumaCpuOptions" when "type" is "cpu"
14626 Since: 2.1
14628 NumaNodeOptions (Object)
14630 Create a guest NUMA node. (for OptsVisitor)
14632 Members:
14634 "nodeid: int" (optional)
14636 NUMA node ID (increase by 1 from 0 if omitted)
14637 "cpus: array of int" (optional)
14639 VCPUs belonging to this node (assign VCPUS round-robin if omitted)
14640 "mem: int" (optional)
14642 memory size of this node; mutually exclusive with "memdev".
14643 Equally divide total memory among nodes if both "mem" and "memdev"
14644 are omitted.
14645 "memdev: string" (optional)
14647 memory backend object. If specified for one node, it must be
14648 specified for all nodes.
14649 Since: 2.1
14651 NumaDistOptions (Object)
14653 Set the distance between 2 NUMA nodes.
14655 Members:
14657 "src: int"
14659 source NUMA node.
14660 "dst: int"
14662 destination NUMA node.
14663 "val: int"
14665 NUMA distance from source node to destination node. When a node is
14666 unreachable from another node, set the distance between them to
14667 255.
14668 Since: 2.10
14670 NumaCpuOptions (Object)
14672 Option "-numa cpu" overrides default cpu to node mapping. It accepts
14674 the same set of cpu properties as returned by
14675 query-hotpluggable-cpus[].props, where node-id could be used to
14676 override default node mapping.
14677 Members:
14679 The members of "CpuInstanceProperties"
14681 Since: 2.10
14683 HostMemPolicy (Enum)
14685 Host memory policy types
14687 Values:
14689 "default"
14691 restore default policy, remove any nondefault policy
14692 "preferred"
14694 set the preferred host nodes for allocation
14695 "bind"
14697 a strict policy that restricts memory allocation to the host nodes
14698 specified
14699 "interleave"
14701 memory allocations are interleaved across the set of host nodes
14702 specified
14703 Since: 2.1
14705 Memdev (Object)
14707 Information about memory backend
14709 Members:
14711 "id: string" (optional)
14713 backend's ID if backend has 'id' property (since 2.9)
14714 "size: int"
14716 memory backend size
14717 "merge: boolean"
14719 enables or disables memory merge support
14720 "dump: boolean"
14722 includes memory backend's memory in a core dump or not
14723 "prealloc: boolean"
14725 enables or disables memory preallocation
14726 "host-nodes: array of int"
14728 host nodes for its memory policy
14729 "policy: HostMemPolicy"
14731 memory policy of memory backend
14732 Since: 2.1
14734 query-memdev (Command) Returns information for all memory backends.
14736 Returns: a list of "Memdev".
14738 Since: 2.1
14740 Example:
14742 -> { "execute": "query-memdev" }
14744 <- { "return": [
14745 {
14746 "id": "mem1",
14747 "size": 536870912,
14748 "merge": false,
14749 "dump": true,
14750 "prealloc": false,
14751 "host-nodes": [0, 1],
14752 "policy": "bind"
14753 },
14754 {
14755 "size": 536870912,
14756 "merge": false,
14757 "dump": true,
14758 "prealloc": true,
14759 "host-nodes": [2, 3],
14760 "policy": "preferred"
14761 }
14762 ]
14763 }
14764 PCDIMMDeviceInfo (Object)
14766 PCDIMMDevice state information
14768 Members:
14770 "id: string" (optional)
14772 device's ID
14773 "addr: int"
14775 physical address, where device is mapped
14776 "size: int"
14778 size of memory that the device provides
14779 "slot: int"
14781 slot number at which device is plugged in
14782 "node: int"
14784 NUMA node number where device is plugged in
14785 "memdev: string"
14787 memory backend linked with device
14788 "hotplugged: boolean"
14790 true if device was hotplugged
14791 "hotpluggable: boolean"
14793 true if device if could be added/removed while machine is running
14794 Since: 2.1
14796 MemoryDeviceInfo (Object)
14798 Union containing information about a memory device
14800 Members:
14802 "type"
14804 One of "dimm", "nvdimm"
14805 "data: PCDIMMDeviceInfo" when "type" is "dimm"
14807 "data: PCDIMMDeviceInfo" when "type" is "nvdimm"
14808 Since: 2.1
14810 query-memory-devices (Command) Lists available memory devices and
14812 their state
14813 Since: 2.1
14815 Example:
14817 -> { "execute": "query-memory-devices" }
14819 <- { "return": [ { "data":
14820 { "addr": 5368709120,
14821 "hotpluggable": true,
14822 "hotplugged": true,
14823 "id": "d1",
14824 "memdev": "/objects/memX",
14825 "node": 0,
14826 "size": 1073741824,
14827 "slot": 0},
14828 "type": "dimm"
14829 } ] }
14830 MEM_UNPLUG_ERROR (Event) Emitted when memory hot unplug error occurs.
14832 Arguments:
14834 "device: string"
14836 device name
14837 "msg: string"
14839 Informative message
14840 Since: 2.4
14842 Example:
14844 <- { "event": "MEM_UNPLUG_ERROR"
14846 "data": { "device": "dimm1",
14847 "msg": "acpi: device unplug for unsupported device"
14848 },
14849 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
14850 ACPISlotType (Enum)
14852 Values:
14854 "DIMM"
14856 memory slot
14857 "CPU"
14859 logical CPU slot (since 2.7)
14860 ACPIOSTInfo (Object)
14862 OSPM Status Indication for a device For description of possible values
14864 of "source" and "status" fields see "_OST (OSPM Status Indication)"
14865 chapter of ACPI5.0 spec.
14866 Members:
14868 "device: string" (optional)
14870 device ID associated with slot
14871 "slot: string"
14873 slot ID, unique per slot of a given "slot-type"
14874 "slot-type: ACPISlotType"
14876 type of the slot
14877 "source: int"
14879 an integer containing the source event
14880 "status: int"
14882 an integer containing the status code
14883 Since: 2.1
14885 query-acpi-ospm-status (Command) Return a list of ACPIOSTInfo for
14887 devices that support status reporting via ACPI _OST method.
14888 Since: 2.1
14890 Example:
14892 -> { "execute": "query-acpi-ospm-status" }
14894 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
14895 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
14896 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
14897 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
14898 ]}
14899 ACPI_DEVICE_OST (Event) Emitted when guest executes ACPI _OST method.
14901 Arguments:
14903 "info: ACPIOSTInfo"
14905 OSPM Status Indication
14906 Since: 2.1
14908 Example:
14910 <- { "event": "ACPI_DEVICE_OST",
14912 "data": { "device": "d1", "slot": "0",
14913 "slot-type": "DIMM", "source": 1, "status": 0 } }
14914 rtc-reset-reinjection (Command) This command will reset the RTC
14916 interrupt reinjection backlog. Can be used if another mechanism to
14917 synchronize guest time is in effect, for example QEMU guest agent's
14918 guest-set-time command.
14919 Since: 2.1
14921 Example:
14923 -> { "execute": "rtc-reset-reinjection" }
14925 <- { "return": {} }
14926 RTC_CHANGE (Event) Emitted when the guest changes the RTC time.
14928 Arguments:
14930 "offset: int"
14932 offset between base RTC clock (as specified by -rtc base), and new
14933 RTC clock value. Note that value will be different depending on
14934 clock chosen to drive RTC (specified by -rtc clock).
14935 Note: This event is rate-limited.
14937 Since: 0.13.0
14939 Example:
14941 <- { "event": "RTC_CHANGE",
14943 "data": { "offset": 78 },
14944 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
14945 ReplayMode (Enum)
14947 Mode of the replay subsystem.
14949 Values:
14951 "none"
14953 normal execution mode. Replay or record are not enabled.
14954 "record"
14956 record mode. All non-deterministic data is written into the replay
14957 log.
14958 "play"
14960 replay mode. Non-deterministic data required for system execution
14961 is read from the log.
14962 Since: 2.5
14964 xen-load-devices-state (Command) Load the state of all devices from
14966 file. The RAM and the block devices of the VM are not loaded by this
14967 command.
14968 Arguments:
14970 "filename: string"
14972 the file to load the state of the devices from as binary data. See
14973 xen-save-devices-state.txt for a description of the binary format.
14974 Since: 2.7
14976 Example:
14978 -> { "execute": "xen-load-devices-state",
14980 "arguments": { "filename": "/tmp/resume" } }
14981 <- { "return": {} }
14982 GICCapability (Object)
14984 The struct describes capability for a specific GIC (Generic Interrupt
14986 Controller) version. These bits are not only decided by QEMU/KVM
14987 software version, but also decided by the hardware that the program is
14988 running upon.
14989 Members:
14991 "version: int"
14993 version of GIC to be described. Currently, only 2 and 3 are
14994 supported.
14995 "emulated: boolean"
14997 whether current QEMU/hardware supports emulated GIC device in user
14998 space.
14999 "kernel: boolean"
15001 whether current QEMU/hardware supports hardware accelerated GIC
15002 device in kernel.
15003 Since: 2.6
15005 query-gic-capabilities (Command) This command is ARM-only. It will
15007 return a list of GICCapability objects that describe its capability
15008 bits.
15009 Returns: a list of GICCapability objects.
15011 Since: 2.6
15013 Example:
15015 -> { "execute": "query-gic-capabilities" }
15017 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
15018 { "version": 3, "emulated": false, "kernel": true } ] }
15019 CpuInstanceProperties (Object)
15021 List of properties to be used for hotplugging a CPU instance, it should
15023 be passed by management with device_add command when a CPU is being
15024 hotplugged.
15025 Members:
15027 "node-id: int" (optional)
15029 NUMA node ID the CPU belongs to
15030 "socket-id: int" (optional)
15032 socket number within node/board the CPU belongs to
15033 "core-id: int" (optional)
15035 core number within socket the CPU belongs to
15036 "thread-id: int" (optional)
15038 thread number within core the CPU belongs to
15039 Note: currently there are 4 properties that could be present but
15041 management should be prepared to pass through other properties with
15042 device_add command to allow for future interface extension. This also
15043 requires the filed names to be kept in sync with the properties passed
15044 to -device/device_add.
15045 Since: 2.7
15047 HotpluggableCPU (Object)
15049 Members:
15051 "type: string"
15053 CPU object type for usage with device_add command
15054 "props: CpuInstanceProperties"
15056 list of properties to be used for hotplugging CPU
15057 "vcpus-count: int"
15059 number of logical VCPU threads "HotpluggableCPU" provides
15060 "qom-path: string" (optional)
15062 link to existing CPU object if CPU is present or omitted if CPU is
15063 not present.
15064 Since: 2.7
15066 query-hotpluggable-cpus (Command)
15068 Returns: a list of HotpluggableCPU objects.
15070 Since: 2.7
15072 Example:
15074 For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
15076 -> { "execute": "query-hotpluggable-cpus" }
15078 <- {"return": [
15079 { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
15080 "vcpus-count": 1 },
15081 { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
15082 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
15083 ]}'
15084 For pc machine type started with -smp 1,maxcpus=2:
15086 -> { "execute": "query-hotpluggable-cpus" }
15088 <- {"return": [
15089 {
15090 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
15091 "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
15092 },
15093 {
15094 "qom-path": "/machine/unattached/device[0]",
15095 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
15096 "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
15097 }
15098 ]}
15099 For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
15101 (Since: 2.11):
15102 -> { "execute": "query-hotpluggable-cpus" }
15104 <- {"return": [
15105 {
15106 "type": "qemu-s390x-cpu", "vcpus-count": 1,
15107 "props": { "core-id": 1 }
15108 },
15109 {
15110 "qom-path": "/machine/unattached/device[0]",
15111 "type": "qemu-s390x-cpu", "vcpus-count": 1,
15112 "props": { "core-id": 0 }
15113 }
15114 ]}
15115 GuidInfo (Object)
15117 GUID information.
15119 Members:
15121 "guid: string"
15123 the globally unique identifier
15124 Since: 2.9
15126 query-vm-generation-id (Command) Show Virtual Machine Generation ID
15128 Since: 2.9
15130 SevState (Enum)
15132 An enumeration of SEV state information used during "query-sev".
15134 Values:
15136 "uninit"
15138 The guest is uninitialized.
15139 "launch-update"
15141 The guest is currently being launched; plaintext data and register
15142 state is being imported.
15143 "launch-secret"
15145 The guest is currently being launched; ciphertext data is being
15146 imported.
15147 "running"
15149 The guest is fully launched or migrated in.
15150 "send-update"
15152 The guest is currently being migrated out to another machine.
15153 "receive-update"
15155 The guest is currently being migrated from another machine.
15156 Since: 2.12
15158 SevInfo (Object)
15160 Information about Secure Encrypted Virtualization (SEV) support
15162 Members:
15164 "enabled: boolean"
15166 true if SEV is active
15167 "api-major: int"
15169 SEV API major version
15170 "api-minor: int"
15172 SEV API minor version
15173 "build-id: int"
15175 SEV FW build id
15176 "policy: int"
15178 SEV policy value
15179 "state: SevState"
15181 SEV guest state
15182 "handle: int"
15184 SEV firmware handle
15185 Since: 2.12
15187 query-sev (Command) Returns information about SEV
15189 Returns: "SevInfo"
15191 Since: 2.12
15193 Example:
15195 -> { "execute": "query-sev" }
15197 <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
15198 "build-id" : 0, "policy" : 0, "state" : "running",
15199 "handle" : 1 } }
15200 SevLaunchMeasureInfo (Object)
15202 SEV Guest Launch measurement information
15204 Members:
15206 "data: string"
15208 the measurement value encoded in base64
15209 Since: 2.12
15211 query-sev-launch-measure (Command) Query the SEV guest launch
15213 information.
15214 Returns: The "SevLaunchMeasureInfo" for the guest
15216 Since: 2.12
15218 Example:
15220 -> { "execute": "query-sev-launch-measure" }
15222 <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
15223 SevCapability (Object)
15225 The struct describes capability for a Secure Encrypted Virtualization
15227 feature.
15228 Members:
15230 "pdh: string"
15232 Platform Diffie-Hellman key (base64 encoded)
15233 "cert-chain: string"
15235 PDH certificate chain (base64 encoded)
15236 "cbitpos: int"
15238 C-bit location in page table entry
15239 "reduced-phys-bits: int"
15241 Number of physical Address bit reduction when SEV is enabled
15242 Since: 2.12
15244 query-sev-capabilities (Command) This command is used to get the SEV
15246 capabilities, and is supported on AMD X86 platforms only.
15247 Returns: SevCapability objects.
15249 Since: 2.12
15251 Example:
15253 -> { "execute": "query-sev-capabilities" }
15255 <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
15256 "cbitpos": 47, "reduced-phys-bits": 5}}
15257 CommandDropReason (Enum)
15259 Reasons that caused one command to be dropped.
15261 Values:
15263 "queue-full"
15265 the command queue is full. This can only occur when the client
15266 sends a new non-oob command before the response to the previous
15267 non-oob command has been received.
15268 Since: 2.12
15270 COMMAND_DROPPED (Event) Emitted when a command is dropped due to some
15272 reason. Commands can only be dropped when the oob capability is
15273 enabled.
15274 Arguments:
15276 "id: value"
15278 The dropped command's "id" field. FIXME Broken by design. Events
15279 are broadcast to all monitors. If another monitor's client has a
15280 command with the same ID in flight, the event will incorrectly
15281 claim that command was dropped.
15282 "reason: CommandDropReason"
15284 The reason why the command is dropped.
15285 Since: 2.12
15287 Example:
15289 { "event": "COMMAND_DROPPED",
15291 "data": {"result": {"id": "libvirt-102",
15292 "reason": "queue-full" } } }
15293 set-numa-node (Command) Runtime equivalent of '-numa' CLI option,
15295 available at preconfigure stage to configure numa mapping before
15296 initializing machine.
15297 Since 3.0
15299 Arguments: the members of "NumaOptions"
15301 2019-05-14 QEMU-QMP-REF.7(7)