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 PCIELinkSpeed (Enum)
193 An enumeration of PCIe link speeds in units of GT/s
195 Values:
197 "2_5"
199 2.5GT/s
200 5 5.0GT/s
202 8 8.0GT/s
204 16 16.0GT/s
206 Since: 4.0
208 PCIELinkWidth (Enum)
210 An enumeration of PCIe link width
212 Values:
214 1 x1
216 2 x2
218 4 x4
220 8 x8
222 12 x12
224 16 x16
226 32 x32
228 Since: 4.0
230 SysEmuTarget (Enum)
232 The comprehensive enumeration of QEMU system emulation ("softmmu")
234 targets. Run "./configure --help" in the project root directory, and
235 look for the *-softmmu targets near the "--target-list" option. The
236 individual target constants are not documented here, for the time
237 being.
238 Values:
240 "aarch64"
242 Not documented
243 "alpha"
245 Not documented
246 "arm"
248 Not documented
249 "cris"
251 Not documented
252 "hppa"
254 Not documented
255 "i386"
257 Not documented
258 "lm32"
260 Not documented
261 "m68k"
263 Not documented
264 "microblaze"
266 Not documented
267 "microblazeel"
269 Not documented
270 "mips"
272 Not documented
273 "mips64"
275 Not documented
276 "mips64el"
278 Not documented
279 "mipsel"
281 Not documented
282 "moxie"
284 Not documented
285 "nios2"
287 Not documented
288 "or1k"
290 Not documented
291 "ppc"
293 Not documented
294 "ppc64"
296 Not documented
297 "riscv32"
299 Not documented
300 "riscv64"
302 Not documented
303 "s390x"
305 Not documented
306 "sh4"
308 Not documented
309 "sh4eb"
311 Not documented
312 "sparc"
314 Not documented
315 "sparc64"
317 Not documented
318 "tricore"
320 Not documented
321 "unicore32"
323 Not documented
324 "x86_64"
326 Not documented
327 "xtensa"
329 Not documented
330 "xtensaeb"
332 Not documented
333 Notes: The resulting QMP strings can be appended to the "qemu-system-"
335 prefix to produce the corresponding QEMU executable name. This is true
336 even for "qemu-system-x86_64".
337 ppcemb: dropped in 3.1
339 Since: 3.0
341 Socket data types
343 NetworkAddressFamily (Enum)
344 The network address family
346 Values:
348 "ipv4"
350 IPV4 family
351 "ipv6"
353 IPV6 family
354 "unix"
356 unix socket
357 "vsock"
359 vsock family (since 2.8)
360 "unknown"
362 otherwise
363 Since: 2.1
365 InetSocketAddressBase (Object)
367 Members:
369 "host: string"
371 host part of the address
372 "port: string"
374 port part of the address
375 InetSocketAddress (Object)
377 Captures a socket address or address range in the Internet namespace.
379 Members:
381 "numeric: boolean" (optional)
383 true if the host/port are guaranteed to be numeric, false if name
384 resolution should be attempted. Defaults to false. (Since 2.9)
385 "to: int" (optional)
387 If present, this is range of possible addresses, with port between
388 "port" and "to".
389 "ipv4: boolean" (optional)
391 whether to accept IPv4 addresses, default try both IPv4 and IPv6
392 "ipv6: boolean" (optional)
394 whether to accept IPv6 addresses, default try both IPv4 and IPv6
395 The members of "InetSocketAddressBase"
397 Since: 1.3
399 UnixSocketAddress (Object)
401 Captures a socket address in the local ("Unix socket") namespace.
403 Members:
405 "path: string"
407 filesystem path to use
408 Since: 1.3
410 VsockSocketAddress (Object)
412 Captures a socket address in the vsock namespace.
414 Members:
416 "cid: string"
418 unique host identifier
419 "port: string"
421 port
422 Note: string types are used to allow for possible future hostname or
424 service resolution support.
425 Since: 2.8
427 SocketAddressLegacy (Object)
429 Captures the address of a socket, which could also be a named file
431 descriptor
432 Members:
434 "type"
436 One of "inet", "unix", "vsock", "fd"
437 "data: InetSocketAddress" when "type" is "inet"
439 "data: UnixSocketAddress" when "type" is "unix"
440 "data: VsockSocketAddress" when "type" is "vsock"
441 "data: String" when "type" is "fd"
442 Note: This type is deprecated in favor of SocketAddress. The
444 difference between SocketAddressLegacy and SocketAddress is that the
445 latter is a flat union rather than a simple union. Flat is nicer
446 because it avoids nesting on the wire, i.e. that form has fewer {}.
447 Since: 1.3
449 SocketAddressType (Enum)
451 Available SocketAddress types
453 Values:
455 "inet"
457 Internet address
458 "unix"
460 Unix domain socket
461 "vsock"
463 VMCI address
464 "fd"
466 decimal is for file descriptor number, otherwise a file descriptor
467 name. Named file descriptors are permitted in monitor commands, in
468 combination with the 'getfd' command. Decimal file descriptors are
469 permitted at startup or other contexts where no monitor context is
470 active.
471 Since: 2.9
473 SocketAddress (Object)
475 Captures the address of a socket, which could also be a named file
477 descriptor
478 Members:
480 "type: SocketAddressType"
482 Transport type
483 The members of "InetSocketAddress" when "type" is "inet"
485 The members of "UnixSocketAddress" when "type" is "unix"
486 The members of "VsockSocketAddress" when "type" is "vsock"
487 The members of "String" when "type" is "fd"
488 Since: 2.9
490 VM run state
492 RunState (Enum)
493 An enumeration of VM run states.
495 Values:
497 "debug"
499 QEMU is running on a debugger
500 "finish-migrate"
502 guest is paused to finish the migration process
503 "inmigrate"
505 guest is paused waiting for an incoming migration. Note that this
506 state does not tell whether the machine will start at the end of
507 the migration. This depends on the command-line -S option and any
508 invocation of 'stop' or 'cont' that has happened since QEMU was
509 started.
510 "internal-error"
512 An internal error that prevents further guest execution has
513 occurred
514 "io-error"
516 the last IOP has failed and the device is configured to pause on
517 I/O errors
518 "paused"
520 guest has been paused via the 'stop' command
521 "postmigrate"
523 guest is paused following a successful 'migrate'
524 "prelaunch"
526 QEMU was started with -S and guest has not started
527 "restore-vm"
529 guest is paused to restore VM state
530 "running"
532 guest is actively running
533 "save-vm"
535 guest is paused to save the VM state
536 "shutdown"
538 guest is shut down (and -no-shutdown is in use)
539 "suspended"
541 guest is suspended (ACPI S3)
542 "watchdog"
544 the watchdog action is configured to pause and has been triggered
545 "guest-panicked"
547 guest has been panicked as a result of guest OS panic
548 "colo"
550 guest is paused to save/restore VM state under colo checkpoint, VM
551 can not get into this state unless colo capability is enabled for
552 migration. (since 2.8)
553 "preconfig"
555 QEMU is paused before board specific init callback is executed.
556 The state is reachable only if the --preconfig CLI option is used.
557 (Since 3.0)
558 ShutdownCause (Enum)
560 An enumeration of reasons for a Shutdown.
562 Values:
564 "none"
566 No shutdown request pending
567 "host-error"
569 An error prevents further use of guest
570 "host-qmp-quit"
572 Reaction to the QMP command 'quit'
573 "host-qmp-system-reset"
575 Reaction to the QMP command 'system_reset'
576 "host-signal"
578 Reaction to a signal, such as SIGINT
579 "host-ui"
581 Reaction to a UI event, like window close
582 "guest-shutdown"
584 Guest shutdown/suspend request, via ACPI or other hardware-specific
585 means
586 "guest-reset"
588 Guest reset request, and command line turns that into a shutdown
589 "guest-panic"
591 Guest panicked, and command line turns that into a shutdown
592 "subsystem-reset"
594 Partial guest reset that does not trigger QMP events and ignores
595 --no-reboot. This is useful for sanitizing hypercalls on s390 that
596 are used during kexec/kdump/boot
597 StatusInfo (Object)
599 Information about VCPU run state
601 Members:
603 "running: boolean"
605 true if all VCPUs are runnable, false if not runnable
606 "singlestep: boolean"
608 true if VCPUs are in single-step mode
609 "status: RunState"
611 the virtual machine "RunState"
612 Since: 0.14.0
614 Notes: "singlestep" is enabled through the GDB stub
616 query-status (Command) Query the run status of all VCPUs
618 Returns: "StatusInfo" reflecting all VCPUs
620 Since: 0.14.0
622 Example:
624 -> { "execute": "query-status" }
626 <- { "return": { "running": true,
627 "singlestep": false,
628 "status": "running" } }
629 SHUTDOWN (Event) Emitted when the virtual machine has shut down,
631 indicating that qemu is about to exit.
632 Arguments:
634 "guest: boolean"
636 If true, the shutdown was triggered by a guest request (such as a
637 guest-initiated ACPI shutdown request or other hardware-specific
638 action) rather than a host request (such as sending qemu a SIGINT).
639 (since 2.10)
640 "reason: ShutdownCause"
642 The "ShutdownCause" which resulted in the SHUTDOWN. (since 4.0)
643 Note: If the command-line option "-no-shutdown" has been specified,
645 qemu will not exit, and a STOP event will eventually follow the
646 SHUTDOWN event
647 Since: 0.12.0
649 Example:
651 <- { "event": "SHUTDOWN", "data": { "guest": true },
653 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
654 POWERDOWN (Event) Emitted when the virtual machine is powered down
656 through the power control system, such as via ACPI.
657 Since: 0.12.0
659 Example:
661 <- { "event": "POWERDOWN",
663 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
664 RESET (Event) Emitted when the virtual machine is reset
666 Arguments:
668 "guest: boolean"
670 If true, the reset was triggered by a guest request (such as a
671 guest-initiated ACPI reboot request or other hardware-specific
672 action) rather than a host request (such as the QMP command
673 system_reset). (since 2.10)
674 "reason: ShutdownCause"
676 The "ShutdownCause" of the RESET. (since 4.0)
677 Since: 0.12.0
679 Example:
681 <- { "event": "RESET", "data": { "guest": false },
683 "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
684 STOP (Event) Emitted when the virtual machine is stopped
686 Since: 0.12.0
688 Example:
690 <- { "event": "STOP",
692 "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
693 RESUME (Event) Emitted when the virtual machine resumes execution
695 Since: 0.12.0
697 Example:
699 <- { "event": "RESUME",
701 "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
702 SUSPEND (Event) Emitted when guest enters a hardware suspension state,
704 for example, S3 state, which is sometimes called standby state
705 Since: 1.1
707 Example:
709 <- { "event": "SUSPEND",
711 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
712 SUSPEND_DISK (Event) Emitted when guest enters a hardware suspension
714 state with data saved on disk, for example, S4 state, which is
715 sometimes called hibernate state
716 Note: QEMU shuts down (similar to event "SHUTDOWN") when entering this
718 state
719 Since: 1.2
721 Example:
723 <- { "event": "SUSPEND_DISK",
725 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
726 WAKEUP (Event) Emitted when the guest has woken up from suspend state
728 and is running
729 Since: 1.1
731 Example:
733 <- { "event": "WAKEUP",
735 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
736 WATCHDOG (Event) Emitted when the watchdog device's timer is expired
738 Arguments:
740 "action: WatchdogAction"
742 action that has been taken
743 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event
745 is followed respectively by the RESET, SHUTDOWN, or STOP events
746 Note: This event is rate-limited.
748 Since: 0.13.0
750 Example:
752 <- { "event": "WATCHDOG",
754 "data": { "action": "reset" },
755 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
756 WatchdogAction (Enum)
758 An enumeration of the actions taken when the watchdog device's timer is
760 expired
761 Values:
763 "reset"
765 system resets
766 "shutdown"
768 system shutdown, note that it is similar to "powerdown", which
769 tries to set to system status and notify guest
770 "poweroff"
772 system poweroff, the emulator program exits
773 "pause"
775 system pauses, similar to "stop"
776 "debug"
778 system enters debug state
779 "none"
781 nothing is done
782 "inject-nmi"
784 a non-maskable interrupt is injected into the first VCPU (all VCPUS
785 on x86) (since 2.4)
786 Since: 2.1
788 watchdog-set-action (Command) Set watchdog action
790 Arguments:
792 "action: WatchdogAction"
794 Not documented
795 Since: 2.11
797 GUEST_PANICKED (Event) Emitted when guest OS panic is detected
799 Arguments:
801 "action: GuestPanicAction"
803 action that has been taken, currently always "pause"
804 "info: GuestPanicInformation" (optional)
806 information about a panic (since 2.9)
807 Since: 1.5
809 Example:
811 <- { "event": "GUEST_PANICKED",
813 "data": { "action": "pause" } }
814 GuestPanicAction (Enum)
816 An enumeration of the actions taken when guest OS panic is detected
818 Values:
820 "pause"
822 system pauses
823 "poweroff"
825 Not documented
826 Since: 2.1 (poweroff since 2.8)
828 GuestPanicInformationType (Enum)
830 An enumeration of the guest panic information types
832 Values:
834 "hyper-v"
836 hyper-v guest panic information type
837 "s390"
839 s390 guest panic information type (Since: 2.12)
840 Since: 2.9
842 GuestPanicInformation (Object)
844 Information about a guest panic
846 Members:
848 "type: GuestPanicInformationType"
850 Crash type that defines the hypervisor specific information
851 The members of "GuestPanicInformationHyperV" when "type" is "hyper-v"
853 The members of "GuestPanicInformationS390" when "type" is "s390"
854 Since: 2.9
856 GuestPanicInformationHyperV (Object)
858 Hyper-V specific guest panic information (HV crash MSRs)
860 Members:
862 "arg1: int"
864 Not documented
865 "arg2: int"
867 Not documented
868 "arg3: int"
870 Not documented
871 "arg4: int"
873 Not documented
874 "arg5: int"
876 Not documented
877 Since: 2.9
879 S390CrashReason (Enum)
881 Reason why the CPU is in a crashed state.
883 Values:
885 "unknown"
887 no crash reason was set
888 "disabled-wait"
890 the CPU has entered a disabled wait state
891 "extint-loop"
893 clock comparator or cpu timer interrupt with new PSW enabled for
894 external interrupts
895 "pgmint-loop"
897 program interrupt with BAD new PSW
898 "opint-loop"
900 operation exception interrupt with invalid code at the program
901 interrupt new PSW
902 Since: 2.12
904 GuestPanicInformationS390 (Object)
906 S390 specific guest panic information (PSW)
908 Members:
910 "core: int"
912 core id of the CPU that crashed
913 "psw-mask: int"
915 control fields of guest PSW
916 "psw-addr: int"
918 guest instruction address
919 "reason: S390CrashReason"
921 guest crash reason
922 Since: 2.12
924 Cryptography
926 QCryptoTLSCredsEndpoint (Enum)
927 The type of network endpoint that will be using the credentials. Most
929 types of credential require different setup / structures depending on
930 whether they will be used in a server versus a client.
931 Values:
933 "client"
935 the network endpoint is acting as the client
936 "server"
938 the network endpoint is acting as the server
939 Since: 2.5
941 QCryptoSecretFormat (Enum)
943 The data format that the secret is provided in
945 Values:
947 "raw"
949 raw bytes. When encoded in JSON only valid UTF-8 sequences can be
950 used
951 "base64"
953 arbitrary base64 encoded binary data
954 Since: 2.6
956 QCryptoHashAlgorithm (Enum)
958 The supported algorithms for computing content digests
960 Values:
962 "md5"
964 MD5. Should not be used in any new code, legacy compat only
965 "sha1"
967 SHA-1. Should not be used in any new code, legacy compat only
968 "sha224"
970 SHA-224. (since 2.7)
971 "sha256"
973 SHA-256. Current recommended strong hash.
974 "sha384"
976 SHA-384. (since 2.7)
977 "sha512"
979 SHA-512. (since 2.7)
980 "ripemd160"
982 RIPEMD-160. (since 2.7)
983 Since: 2.6
985 QCryptoCipherAlgorithm (Enum)
987 The supported algorithms for content encryption ciphers
989 Values:
991 "aes-128"
993 AES with 128 bit / 16 byte keys
994 "aes-192"
996 AES with 192 bit / 24 byte keys
997 "aes-256"
999 AES with 256 bit / 32 byte keys
1000 "des-rfb"
1002 RFB specific variant of single DES. Do not use except in VNC.
1003 "3des"
1005 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
1006 "cast5-128"
1008 Cast5 with 128 bit / 16 byte keys
1009 "serpent-128"
1011 Serpent with 128 bit / 16 byte keys
1012 "serpent-192"
1014 Serpent with 192 bit / 24 byte keys
1015 "serpent-256"
1017 Serpent with 256 bit / 32 byte keys
1018 "twofish-128"
1020 Twofish with 128 bit / 16 byte keys
1021 "twofish-192"
1023 Twofish with 192 bit / 24 byte keys
1024 "twofish-256"
1026 Twofish with 256 bit / 32 byte keys
1027 Since: 2.6
1029 QCryptoCipherMode (Enum)
1031 The supported modes for content encryption ciphers
1033 Values:
1035 "ecb"
1037 Electronic Code Book
1038 "cbc"
1040 Cipher Block Chaining
1041 "xts"
1043 XEX with tweaked code book and ciphertext stealing
1044 "ctr"
1046 Counter (Since 2.8)
1047 Since: 2.6
1049 QCryptoIVGenAlgorithm (Enum)
1051 The supported algorithms for generating initialization vectors for full
1053 disk encryption. The 'plain' generator should not be used for disks
1054 with sector numbers larger than 2^32, except where compatibility with
1055 pre-existing Linux dm-crypt volumes is required.
1056 Values:
1058 "plain"
1060 64-bit sector number truncated to 32-bits
1061 "plain64"
1063 64-bit sector number
1064 "essiv"
1066 64-bit sector number encrypted with a hash of the encryption key
1067 Since: 2.6
1069 QCryptoBlockFormat (Enum)
1071 The supported full disk encryption formats
1073 Values:
1075 "qcow"
1077 QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
1078 data from old images.
1079 "luks"
1081 LUKS encryption format. Recommended for new images
1082 Since: 2.6
1084 QCryptoBlockOptionsBase (Object)
1086 The common options that apply to all full disk encryption formats
1088 Members:
1090 "format: QCryptoBlockFormat"
1092 the encryption format
1093 Since: 2.6
1095 QCryptoBlockOptionsQCow (Object)
1097 The options that apply to QCow/QCow2 AES-CBC encryption format
1099 Members:
1101 "key-secret: string" (optional)
1103 the ID of a QCryptoSecret object providing the decryption key.
1104 Mandatory except when probing image for metadata only.
1105 Since: 2.6
1107 QCryptoBlockOptionsLUKS (Object)
1109 The options that apply to LUKS encryption format
1111 Members:
1113 "key-secret: string" (optional)
1115 the ID of a QCryptoSecret object providing the decryption key.
1116 Mandatory except when probing image for metadata only.
1117 Since: 2.6
1119 QCryptoBlockCreateOptionsLUKS (Object)
1121 The options that apply to LUKS encryption format initialization
1123 Members:
1125 "cipher-alg: QCryptoCipherAlgorithm" (optional)
1127 the cipher algorithm for data encryption Currently defaults to
1128 'aes-256'.
1129 "cipher-mode: QCryptoCipherMode" (optional)
1131 the cipher mode for data encryption Currently defaults to 'xts'
1132 "ivgen-alg: QCryptoIVGenAlgorithm" (optional)
1134 the initialization vector generator Currently defaults to 'plain64'
1135 "ivgen-hash-alg: QCryptoHashAlgorithm" (optional)
1137 the initialization vector generator hash Currently defaults to
1138 'sha256'
1139 "hash-alg: QCryptoHashAlgorithm" (optional)
1141 the master key hash algorithm Currently defaults to 'sha256'
1142 "iter-time: int" (optional)
1144 number of milliseconds to spend in PBKDF passphrase processing.
1145 Currently defaults to 2000. (since 2.8)
1146 The members of "QCryptoBlockOptionsLUKS"
1148 Since: 2.6
1150 QCryptoBlockOpenOptions (Object)
1152 The options that are available for all encryption formats when opening
1154 an existing volume
1155 Members:
1157 The members of "QCryptoBlockOptionsBase"
1159 The members of "QCryptoBlockOptionsQCow" when "format" is "qcow"
1160 The members of "QCryptoBlockOptionsLUKS" when "format" is "luks"
1161 Since: 2.6
1163 QCryptoBlockCreateOptions (Object)
1165 The options that are available for all encryption formats when
1167 initializing a new volume
1168 Members:
1170 The members of "QCryptoBlockOptionsBase"
1172 The members of "QCryptoBlockOptionsQCow" when "format" is "qcow"
1173 The members of "QCryptoBlockCreateOptionsLUKS" when "format" is "luks"
1174 Since: 2.6
1176 QCryptoBlockInfoBase (Object)
1178 The common information that applies to all full disk encryption formats
1180 Members:
1182 "format: QCryptoBlockFormat"
1184 the encryption format
1185 Since: 2.7
1187 QCryptoBlockInfoLUKSSlot (Object)
1189 Information about the LUKS block encryption key slot options
1191 Members:
1193 "active: boolean"
1195 whether the key slot is currently in use
1196 "key-offset: int"
1198 offset to the key material in bytes
1199 "iters: int" (optional)
1201 number of PBKDF2 iterations for key material
1202 "stripes: int" (optional)
1204 number of stripes for splitting key material
1205 Since: 2.7
1207 QCryptoBlockInfoLUKS (Object)
1209 Information about the LUKS block encryption options
1211 Members:
1213 "cipher-alg: QCryptoCipherAlgorithm"
1215 the cipher algorithm for data encryption
1216 "cipher-mode: QCryptoCipherMode"
1218 the cipher mode for data encryption
1219 "ivgen-alg: QCryptoIVGenAlgorithm"
1221 the initialization vector generator
1222 "ivgen-hash-alg: QCryptoHashAlgorithm" (optional)
1224 the initialization vector generator hash
1225 "hash-alg: QCryptoHashAlgorithm"
1227 the master key hash algorithm
1228 "payload-offset: int"
1230 offset to the payload data in bytes
1231 "master-key-iters: int"
1233 number of PBKDF2 iterations for key material
1234 "uuid: string"
1236 unique identifier for the volume
1237 "slots: array of QCryptoBlockInfoLUKSSlot"
1239 information about each key slot
1240 Since: 2.7
1242 QCryptoBlockInfo (Object)
1244 Information about the block encryption options
1246 Members:
1248 The members of "QCryptoBlockInfoBase"
1250 The members of "QCryptoBlockInfoLUKS" when "format" is "luks"
1251 Since: 2.7
1253 Block devices
1255 Block core (VM unrelated)
1256 Background jobs
1258 JobType (Enum)
1260 Type of a background job.
1262 Values:
1264 "commit"
1266 block commit job type, see "block-commit"
1267 "stream"
1269 block stream job type, see "block-stream"
1270 "mirror"
1272 drive mirror job type, see "drive-mirror"
1273 "backup"
1275 drive backup job type, see "drive-backup"
1276 "create"
1278 image creation job type, see "blockdev-create" (since 3.0)
1279 Since: 1.7
1281 JobStatus (Enum)
1283 Indicates the present state of a given job in its lifetime.
1285 Values:
1287 "undefined"
1289 Erroneous, default state. Should not ever be visible.
1290 "created"
1292 The job has been created, but not yet started.
1293 "running"
1295 The job is currently running.
1296 "paused"
1298 The job is running, but paused. The pause may be requested by
1299 either the QMP user or by internal processes.
1300 "ready"
1302 The job is running, but is ready for the user to signal completion.
1303 This is used for long-running jobs like mirror that are designed to
1304 run indefinitely.
1305 "standby"
1307 The job is ready, but paused. This is nearly identical to "paused".
1308 The job may return to "ready" or otherwise be canceled.
1309 "waiting"
1311 The job is waiting for other jobs in the transaction to converge to
1312 the waiting state. This status will likely not be visible for the
1313 last job in a transaction.
1314 "pending"
1316 The job has finished its work, but has finalization steps that it
1317 needs to make prior to completing. These changes will require
1318 manual intervention via "job-finalize" if auto-finalize was set to
1319 false. These pending changes may still fail.
1320 "aborting"
1322 The job is in the process of being aborted, and will finish with an
1323 error. The job will afterwards report that it is "concluded". This
1324 status may not be visible to the management process.
1325 "concluded"
1327 The job has finished all work. If auto-dismiss was set to false,
1328 the job will remain in the query list until it is dismissed via
1329 "job-dismiss".
1330 "null"
1332 The job is in the process of being dismantled. This state should
1333 not ever be visible externally.
1334 Since: 2.12
1336 JobVerb (Enum)
1338 Represents command verbs that can be applied to a job.
1340 Values:
1342 "cancel"
1344 see "job-cancel"
1345 "pause"
1347 see "job-pause"
1348 "resume"
1350 see "job-resume"
1351 "set-speed"
1353 see "block-job-set-speed"
1354 "complete"
1356 see "job-complete"
1357 "dismiss"
1359 see "job-dismiss"
1360 "finalize"
1362 see "job-finalize"
1363 Since: 2.12
1365 JOB_STATUS_CHANGE (Event) Emitted when a job transitions to a
1367 different status.
1368 Arguments:
1370 "id: string"
1372 The job identifier
1373 "status: JobStatus"
1375 The new job status
1376 Since: 3.0
1378 job-pause (Command) Pause an active job.
1380 This command returns immediately after marking the active job for
1382 pausing. Pausing an already paused job is an error.
1383 The job will pause as soon as possible, which means transitioning into
1385 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
1386 The corresponding JOB_STATUS_CHANGE event will be emitted.
1387 Cancelling a paused job automatically resumes it.
1389 Arguments:
1391 "id: string"
1393 The job identifier.
1394 Since: 3.0
1396 job-resume (Command) Resume a paused job.
1398 This command returns immediately after resuming a paused job. Resuming
1400 an already running job is an error.
1401 "id" : The job identifier.
1403 Arguments:
1405 "id: string"
1407 Not documented
1408 Since: 3.0
1410 job-cancel (Command) Instruct an active background job to cancel at
1412 the next opportunity. This command returns immediately after marking
1413 the active job for cancellation.
1414 The job will cancel as soon as possible and then emit a
1416 JOB_STATUS_CHANGE event. Usually, the status will change to ABORTING,
1417 but it is possible that a job successfully completes (e.g. because it
1418 was almost done and there was no opportunity to cancel earlier than
1419 completing the job) and transitions to PENDING instead.
1420 Arguments:
1422 "id: string"
1424 The job identifier.
1425 Since: 3.0
1427 job-complete (Command) Manually trigger completion of an active job in
1429 the READY state.
1430 Arguments:
1432 "id: string"
1434 The job identifier.
1435 Since: 3.0
1437 job-dismiss (Command) Deletes a job that is in the CONCLUDED state.
1439 This command only needs to be run explicitly for jobs that don't have
1440 automatic dismiss enabled.
1441 This command will refuse to operate on any job that has not yet reached
1443 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
1444 JOB_READY event, job-cancel or job-complete will still need to be used
1445 as appropriate.
1446 Arguments:
1448 "id: string"
1450 The job identifier.
1451 Since: 3.0
1453 job-finalize (Command) Instructs all jobs in a transaction (or a
1455 single job if it is not part of any transaction) to finalize any graph
1456 changes and do any necessary cleanup. This command requires that all
1457 involved jobs are in the PENDING state.
1458 For jobs in a transaction, instructing one job to finalize will force
1460 ALL jobs in the transaction to finalize, so it is only necessary to
1461 instruct a single member job to finalize.
1462 Arguments:
1464 "id: string"
1466 The identifier of any job in the transaction, or of a job that is
1467 not part of any transaction.
1468 Since: 3.0
1470 JobInfo (Object)
1472 Information about a job.
1474 Members:
1476 "id: string"
1478 The job identifier
1479 "type: JobType"
1481 The kind of job that is being performed
1482 "status: JobStatus"
1484 Current job state/status
1485 "current-progress: int"
1487 Progress made until now. The unit is arbitrary and the value can
1488 only meaningfully be used for the ratio of "current-progress" to
1489 "total-progress". The value is monotonically increasing.
1490 "total-progress: int"
1492 Estimated "current-progress" value at the completion of the job.
1493 This value can arbitrarily change while the job is running, in both
1494 directions.
1495 "error: string" (optional)
1497 If this field is present, the job failed; if it is still missing in
1498 the CONCLUDED state, this indicates successful completion.
1499 The value is a human-readable error message to describe the reason
1501 for the job failure. It should not be parsed by applications.
1502 Since: 3.0
1504 query-jobs (Command) Return information about jobs.
1506 Returns: a list with a "JobInfo" for each active job
1508 Since: 3.0
1510 SnapshotInfo (Object)
1512 Members:
1514 "id: string"
1516 unique snapshot id
1517 "name: string"
1519 user chosen name
1520 "vm-state-size: int"
1522 size of the VM state
1523 "date-sec: int"
1525 UTC date of the snapshot in seconds
1526 "date-nsec: int"
1528 fractional part in nano seconds to be used with date-sec
1529 "vm-clock-sec: int"
1531 VM clock relative to boot in seconds
1532 "vm-clock-nsec: int"
1534 fractional part in nano seconds to be used with vm-clock-sec
1535 Since: 1.3
1537 ImageInfoSpecificQCow2EncryptionBase (Object)
1539 Members:
1541 "format: BlockdevQcow2EncryptionFormat"
1543 The encryption format
1544 Since: 2.10
1546 ImageInfoSpecificQCow2Encryption (Object)
1548 Members:
1550 The members of "ImageInfoSpecificQCow2EncryptionBase"
1552 The members of "QCryptoBlockInfoLUKS" when "format" is "luks"
1553 Since: 2.10
1555 ImageInfoSpecificQCow2 (Object)
1557 Members:
1559 "compat: string"
1561 compatibility level
1562 "data-file: string" (optional)
1564 the filename of the external data file that is stored in the image
1565 and used as a default for opening the image (since: 4.0)
1566 "data-file-raw: boolean" (optional)
1568 True if the external data file must stay valid as a standalone
1569 (read-only) raw image without looking at qcow2 metadata (since:
1570 4.0)
1571 "lazy-refcounts: boolean" (optional)
1573 on or off; only valid for compat >= 1.1
1574 "corrupt: boolean" (optional)
1576 true if the image has been marked corrupt; only valid for compat >=
1577 1.1 (since 2.2)
1578 "refcount-bits: int"
1580 width of a refcount entry in bits (since 2.3)
1581 "encrypt: ImageInfoSpecificQCow2Encryption" (optional)
1583 details about encryption parameters; only set if image is encrypted
1584 (since 2.10)
1585 "bitmaps: array of Qcow2BitmapInfo" (optional)
1587 A list of qcow2 bitmap details (since 4.0)
1588 Since: 1.7
1590 ImageInfoSpecificVmdk (Object)
1592 Members:
1594 "create-type: string"
1596 The create type of VMDK image
1597 "cid: int"
1599 Content id of image
1600 "parent-cid: int"
1602 Parent VMDK image's cid
1603 "extents: array of ImageInfo"
1605 List of extent files
1606 Since: 1.7
1608 ImageInfoSpecific (Object)
1610 A discriminated record of image format specific information structures.
1612 Members:
1614 "type"
1616 One of "qcow2", "vmdk", "luks"
1617 "data: ImageInfoSpecificQCow2" when "type" is "qcow2"
1619 "data: ImageInfoSpecificVmdk" when "type" is "vmdk"
1620 "data: QCryptoBlockInfoLUKS" when "type" is "luks"
1621 Since: 1.7
1623 ImageInfo (Object)
1625 Information about a QEMU image file
1627 Members:
1629 "filename: string"
1631 name of the image file
1632 "format: string"
1634 format of the image file
1635 "virtual-size: int"
1637 maximum capacity in bytes of the image
1638 "actual-size: int" (optional)
1640 actual size on disk in bytes of the image
1641 "dirty-flag: boolean" (optional)
1643 true if image is not cleanly closed
1644 "cluster-size: int" (optional)
1646 size of a cluster in bytes
1647 "encrypted: boolean" (optional)
1649 true if the image is encrypted
1650 "compressed: boolean" (optional)
1652 true if the image is compressed (Since 1.7)
1653 "backing-filename: string" (optional)
1655 name of the backing file
1656 "full-backing-filename: string" (optional)
1658 full path of the backing file
1659 "backing-filename-format: string" (optional)
1661 the format of the backing file
1662 "snapshots: array of SnapshotInfo" (optional)
1664 list of VM snapshots
1665 "backing-image: ImageInfo" (optional)
1667 info of the backing image (since 1.6)
1668 "format-specific: ImageInfoSpecific" (optional)
1670 structure supplying additional format-specific information (since
1671 1.7)
1672 Since: 1.3
1674 ImageCheck (Object)
1676 Information about a QEMU image file check
1678 Members:
1680 "filename: string"
1682 name of the image file checked
1683 "format: string"
1685 format of the image file checked
1686 "check-errors: int"
1688 number of unexpected errors occurred during check
1689 "image-end-offset: int" (optional)
1691 offset (in bytes) where the image ends, this field is present if
1692 the driver for the image format supports it
1693 "corruptions: int" (optional)
1695 number of corruptions found during the check if any
1696 "leaks: int" (optional)
1698 number of leaks found during the check if any
1699 "corruptions-fixed: int" (optional)
1701 number of corruptions fixed during the check if any
1702 "leaks-fixed: int" (optional)
1704 number of leaks fixed during the check if any
1705 "total-clusters: int" (optional)
1707 total number of clusters, this field is present if the driver for
1708 the image format supports it
1709 "allocated-clusters: int" (optional)
1711 total number of allocated clusters, this field is present if the
1712 driver for the image format supports it
1713 "fragmented-clusters: int" (optional)
1715 total number of fragmented clusters, this field is present if the
1716 driver for the image format supports it
1717 "compressed-clusters: int" (optional)
1719 total number of compressed clusters, this field is present if the
1720 driver for the image format supports it
1721 Since: 1.4
1723 MapEntry (Object)
1725 Mapping information from a virtual block range to a host file range
1727 Members:
1729 "start: int"
1731 the start byte of the mapped virtual range
1732 "length: int"
1734 the number of bytes of the mapped virtual range
1735 "data: boolean"
1737 whether the mapped range has data
1738 "zero: boolean"
1740 whether the virtual blocks are zeroed
1741 "depth: int"
1743 the depth of the mapping
1744 "offset: int" (optional)
1746 the offset in file that the virtual sectors are mapped to
1747 "filename: string" (optional)
1749 filename that is referred to by "offset"
1750 Since: 2.6
1752 BlockdevCacheInfo (Object)
1754 Cache mode information for a block device
1756 Members:
1758 "writeback: boolean"
1760 true if writeback mode is enabled
1761 "direct: boolean"
1763 true if the host page cache is bypassed (O_DIRECT)
1764 "no-flush: boolean"
1766 true if flush requests are ignored for the device
1767 Since: 2.3
1769 BlockDeviceInfo (Object)
1771 Information about the backing device for a block device.
1773 Members:
1775 "file: string"
1777 the filename of the backing device
1778 "node-name: string" (optional)
1780 the name of the block driver node (Since 2.0)
1781 "ro: boolean"
1783 true if the backing device was open read-only
1784 "drv: string"
1786 the name of the block format used to open the backing device. As of
1787 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
1788 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device', 'http',
1789 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2', 'raw', 'vdi',
1790 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added, 'cow' dropped 2.3:
1791 'host_floppy' deprecated 2.5: 'host_floppy' dropped 2.6: 'luks'
1792 added 2.8: 'replication' added, 'tftp' dropped 2.9: 'archipelago'
1793 dropped
1794 "backing_file: string" (optional)
1796 the name of the backing file (for copy-on-write)
1797 "backing_file_depth: int"
1799 number of files in the backing file chain (since: 1.2)
1800 "encrypted: boolean"
1802 true if the backing device is encrypted
1803 "encryption_key_missing: boolean"
1805 Deprecated; always false
1806 "detect_zeroes: BlockdevDetectZeroesOptions"
1808 detect and optimize zero writes (Since 2.1)
1809 "bps: int"
1811 total throughput limit in bytes per second is specified
1812 "bps_rd: int"
1814 read throughput limit in bytes per second is specified
1815 "bps_wr: int"
1817 write throughput limit in bytes per second is specified
1818 "iops: int"
1820 total I/O operations per second is specified
1821 "iops_rd: int"
1823 read I/O operations per second is specified
1824 "iops_wr: int"
1826 write I/O operations per second is specified
1827 "image: ImageInfo"
1829 the info of image used (since: 1.6)
1830 "bps_max: int" (optional)
1832 total throughput limit during bursts, in bytes (Since 1.7)
1833 "bps_rd_max: int" (optional)
1835 read throughput limit during bursts, in bytes (Since 1.7)
1836 "bps_wr_max: int" (optional)
1838 write throughput limit during bursts, in bytes (Since 1.7)
1839 "iops_max: int" (optional)
1841 total I/O operations per second during bursts, in bytes (Since 1.7)
1842 "iops_rd_max: int" (optional)
1844 read I/O operations per second during bursts, in bytes (Since 1.7)
1845 "iops_wr_max: int" (optional)
1847 write I/O operations per second during bursts, in bytes (Since 1.7)
1848 "bps_max_length: int" (optional)
1850 maximum length of the "bps_max" burst period, in seconds. (Since
1851 2.6)
1852 "bps_rd_max_length: int" (optional)
1854 maximum length of the "bps_rd_max" burst period, in seconds. (Since
1855 2.6)
1856 "bps_wr_max_length: int" (optional)
1858 maximum length of the "bps_wr_max" burst period, in seconds. (Since
1859 2.6)
1860 "iops_max_length: int" (optional)
1862 maximum length of the "iops" burst period, in seconds. (Since 2.6)
1863 "iops_rd_max_length: int" (optional)
1865 maximum length of the "iops_rd_max" burst period, in seconds.
1866 (Since 2.6)
1867 "iops_wr_max_length: int" (optional)
1869 maximum length of the "iops_wr_max" burst period, in seconds.
1870 (Since 2.6)
1871 "iops_size: int" (optional)
1873 an I/O size in bytes (Since 1.7)
1874 "group: string" (optional)
1876 throttle group name (Since 2.4)
1877 "cache: BlockdevCacheInfo"
1879 the cache mode used for the block device (since: 2.3)
1880 "write_threshold: int"
1882 configured write threshold for the device. 0 if disabled. (Since
1883 2.3)
1884 Since: 0.14.0
1886 BlockDeviceIoStatus (Enum)
1888 An enumeration of block device I/O status.
1890 Values:
1892 "ok"
1894 The last I/O operation has succeeded
1895 "failed"
1897 The last I/O operation has failed
1898 "nospace"
1900 The last I/O operation has failed due to a no-space condition
1901 Since: 1.0
1903 BlockDeviceMapEntry (Object)
1905 Entry in the metadata map of the device (returned by "qemu-img map")
1907 Members:
1909 "start: int"
1911 Offset in the image of the first byte described by this entry (in
1912 bytes)
1913 "length: int"
1915 Length of the range described by this entry (in bytes)
1916 "depth: int"
1918 Number of layers (0 = top image, 1 = top image's backing file,
1919 etc.) before reaching one for which the range is allocated. The
1920 value is in the range 0 to the depth of the image chain - 1.
1921 "zero: boolean"
1923 the sectors in this range read as zeros
1924 "data: boolean"
1926 reading the image will actually read data from a file (in
1927 particular, if "offset" is present this means that the sectors are
1928 not simply preallocated, but contain actual data in raw format)
1929 "offset: int" (optional)
1931 if present, the image file stores the data for this range in raw
1932 format at the given offset.
1933 Since: 1.7
1935 DirtyBitmapStatus (Enum)
1937 An enumeration of possible states that a dirty bitmap can report to the
1939 user.
1940 Values:
1942 "frozen"
1944 The bitmap is currently in-use by some operation and is immutable.
1945 If the bitmap was "active" prior to the operation, new writes by
1946 the guest are being recorded in a temporary buffer, and will not be
1947 lost. Generally, bitmaps are cleared on successful use in an
1948 operation and the temporary buffer is committed into the bitmap. On
1949 failure, the temporary buffer is merged back into the bitmap
1950 without first clearing it. Please refer to the documentation for
1951 each bitmap-using operation, See also "blockdev-backup",
1952 "drive-backup".
1953 "disabled"
1955 The bitmap is not currently recording new writes by the guest.
1956 This is requested explicitly via "block-dirty-bitmap-disable". It
1957 can still be cleared, deleted, or used for backup operations.
1958 "active"
1960 The bitmap is actively monitoring for new writes, and can be
1961 cleared, deleted, or used for backup operations.
1962 "locked"
1964 The bitmap is currently in-use by some operation and is immutable.
1965 If the bitmap was "active" prior to the operation, it is still
1966 recording new writes. If the bitmap was "disabled", it is not
1967 recording new writes. (Since 2.12)
1968 "inconsistent"
1970 This is a persistent dirty bitmap that was marked in-use on disk,
1971 and is unusable by QEMU. It can only be deleted. Please rely on
1972 the inconsistent field in "BlockDirtyInfo" instead, as the status
1973 field is deprecated. (Since 4.0)
1974 Since: 2.4
1976 BlockDirtyInfo (Object)
1978 Block dirty bitmap information.
1980 Members:
1982 "name: string" (optional)
1984 the name of the dirty bitmap (Since 2.4)
1985 "count: int"
1987 number of dirty bytes according to the dirty bitmap
1988 "granularity: int"
1990 granularity of the dirty bitmap in bytes (since 1.4)
1991 "status: DirtyBitmapStatus"
1993 Deprecated in favor of "recording" and "locked". (since 2.4)
1994 "recording: boolean"
1996 true if the bitmap is recording new writes from the guest.
1997 Replaces `active` and `disabled` statuses. (since 4.0)
1998 "busy: boolean"
2000 true if the bitmap is in-use by some operation (NBD or jobs) and
2001 cannot be modified via QMP or used by another operation. Replaces
2002 `locked` and `frozen` statuses. (since 4.0)
2003 "persistent: boolean"
2005 true if the bitmap was stored on disk, is scheduled to be stored on
2006 disk, or both. (since 4.0)
2007 "inconsistent: boolean" (optional)
2009 true if this is a persistent bitmap that was improperly stored.
2010 Implies "persistent" to be true; "recording" and "busy" to be
2011 false. This bitmap cannot be used. To remove it, use
2012 "block-dirty-bitmap-remove". (Since 4.0)
2013 Since: 1.3
2015 Qcow2BitmapInfoFlags (Enum)
2017 An enumeration of flags that a bitmap can report to the user.
2019 Values:
2021 "in-use"
2023 This flag is set by any process actively modifying the qcow2 file,
2024 and cleared when the updated bitmap is flushed to the qcow2 image.
2025 The presence of this flag in an offline image means that the bitmap
2026 was not saved correctly after its last usage, and may contain
2027 inconsistent data.
2028 "auto"
2030 The bitmap must reflect all changes of the virtual disk by any
2031 application that would write to this qcow2 file.
2032 Since: 4.0
2034 Qcow2BitmapInfo (Object)
2036 Qcow2 bitmap information.
2038 Members:
2040 "name: string"
2042 the name of the bitmap
2043 "granularity: int"
2045 granularity of the bitmap in bytes
2046 "flags: array of Qcow2BitmapInfoFlags"
2048 flags of the bitmap
2049 Since: 4.0
2051 BlockLatencyHistogramInfo (Object)
2053 Block latency histogram.
2055 Members:
2057 "boundaries: array of int"
2059 list of interval boundary values in nanoseconds, all greater than
2060 zero and in ascending order. For example, the list [10, 50, 100]
2061 produces the following histogram intervals: [0, 10), [10, 50), [50,
2062 100), [100, +inf).
2063 "bins: array of int"
2065 list of io request counts corresponding to histogram intervals.
2066 len("bins") = len("boundaries") + 1 For the example above, "bins"
2067 may be something like [3, 1, 5, 2], and corresponding histogram
2068 looks like:
2069 5| * 4| * 3| 2| * 1|
2071 +------------------ 10 50 100
2072 Since: 4.0
2074 block-latency-histogram-set (Command) Manage read, write and flush
2076 latency histograms for the device.
2077 If only "id" parameter is specified, remove all present latency
2079 histograms for the device. Otherwise, add/reset some of (or all)
2080 latency histograms.
2081 Arguments:
2083 "id: string"
2085 The name or QOM path of the guest device.
2086 "boundaries: array of int" (optional)
2088 list of interval boundary values (see description in
2089 BlockLatencyHistogramInfo definition). If specified, all latency
2090 histograms are removed, and empty ones created for all io types
2091 with intervals corresponding to "boundaries" (except for io types,
2092 for which specific boundaries are set through the following
2093 parameters).
2094 "boundaries-read: array of int" (optional)
2096 list of interval boundary values for read latency histogram. If
2097 specified, old read latency histogram is removed, and empty one
2098 created with intervals corresponding to "boundaries-read". The
2099 parameter has higher priority then "boundaries".
2100 "boundaries-write: array of int" (optional)
2102 list of interval boundary values for write latency histogram.
2103 "boundaries-flush: array of int" (optional)
2105 list of interval boundary values for flush latency histogram.
2106 Returns: error if device is not found or any boundary arrays are
2108 invalid.
2109 Since: 4.0
2111 Example:
2113 set new histograms for all io types with intervals
2115 [0, 10), [10, 50), [50, 100), [100, +inf):
2116 -> { "execute": "block-latency-histogram-set",
2118 "arguments": { "id": "drive0",
2119 "boundaries": [10, 50, 100] } }
2120 <- { "return": {} }
2121 Example:
2123 set new histogram only for write, other histograms will remain
2125 not changed (or not created):
2126 -> { "execute": "block-latency-histogram-set",
2128 "arguments": { "id": "drive0",
2129 "boundaries-write": [10, 50, 100] } }
2130 <- { "return": {} }
2131 Example:
2133 set new histograms with the following intervals:
2135 read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
2136 write: [0, 1000), [1000, 5000), [5000, +inf)
2137 -> { "execute": "block-latency-histogram-set",
2139 "arguments": { "id": "drive0",
2140 "boundaries": [10, 50, 100],
2141 "boundaries-write": [1000, 5000] } }
2142 <- { "return": {} }
2143 Example:
2145 remove all latency histograms:
2147 -> { "execute": "block-latency-histogram-set",
2149 "arguments": { "id": "drive0" } }
2150 <- { "return": {} }
2151 BlockInfo (Object)
2153 Block device information. This structure describes a virtual device
2155 and the backing device associated with it.
2156 Members:
2158 "device: string"
2160 The device name associated with the virtual device.
2161 "qdev: string" (optional)
2163 The qdev ID, or if no ID is assigned, the QOM path of the block
2164 device. (since 2.10)
2165 "type: string"
2167 This field is returned only for compatibility reasons, it should
2168 not be used (always returns 'unknown')
2169 "removable: boolean"
2171 True if the device supports removable media.
2172 "locked: boolean"
2174 True if the guest has locked this device from having its media
2175 removed
2176 "tray_open: boolean" (optional)
2178 True if the device's tray is open (only present if it has a tray)
2179 "dirty-bitmaps: array of BlockDirtyInfo" (optional)
2181 dirty bitmaps information (only present if the driver has one or
2182 more dirty bitmaps) (Since 2.0)
2183 "io-status: BlockDeviceIoStatus" (optional)
2185 "BlockDeviceIoStatus". Only present if the device supports it and
2186 the VM is configured to stop on errors (supported device models:
2187 virtio-blk, IDE, SCSI except scsi-generic)
2188 "inserted: BlockDeviceInfo" (optional)
2190 "BlockDeviceInfo" describing the device if media is present
2191 Since: 0.14.0
2193 BlockMeasureInfo (Object)
2195 Image file size calculation information. This structure describes the
2197 size requirements for creating a new image file.
2198 The size requirements depend on the new image file format. File size
2200 always equals virtual disk size for the 'raw' format, even for sparse
2201 POSIX files. Compact formats such as 'qcow2' represent unallocated and
2202 zero regions efficiently so file size may be smaller than virtual disk
2203 size.
2204 The values are upper bounds that are guaranteed to fit the new image
2206 file. Subsequent modification, such as internal snapshot or bitmap
2207 creation, may require additional space and is not covered here.
2208 Members:
2210 "required: int"
2212 Size required for a new image file, in bytes.
2213 "fully-allocated: int"
2215 Image file size, in bytes, once data has been written to all
2216 sectors.
2217 Since: 2.10
2219 query-block (Command) Get a list of BlockInfo for all virtual block
2221 devices.
2222 Returns: a list of "BlockInfo" describing each virtual block device.
2224 Filter nodes that were created implicitly are skipped over.
2225 Since: 0.14.0
2227 Example:
2229 -> { "execute": "query-block" }
2231 <- {
2232 "return":[
2233 {
2234 "io-status": "ok",
2235 "device":"ide0-hd0",
2236 "locked":false,
2237 "removable":false,
2238 "inserted":{
2239 "ro":false,
2240 "drv":"qcow2",
2241 "encrypted":false,
2242 "file":"disks/test.qcow2",
2243 "backing_file_depth":1,
2244 "bps":1000000,
2245 "bps_rd":0,
2246 "bps_wr":0,
2247 "iops":1000000,
2248 "iops_rd":0,
2249 "iops_wr":0,
2250 "bps_max": 8000000,
2251 "bps_rd_max": 0,
2252 "bps_wr_max": 0,
2253 "iops_max": 0,
2254 "iops_rd_max": 0,
2255 "iops_wr_max": 0,
2256 "iops_size": 0,
2257 "detect_zeroes": "on",
2258 "write_threshold": 0,
2259 "image":{
2260 "filename":"disks/test.qcow2",
2261 "format":"qcow2",
2262 "virtual-size":2048000,
2263 "backing_file":"base.qcow2",
2264 "full-backing-filename":"disks/base.qcow2",
2265 "backing-filename-format":"qcow2",
2266 "snapshots":[
2267 {
2268 "id": "1",
2269 "name": "snapshot1",
2270 "vm-state-size": 0,
2271 "date-sec": 10000200,
2272 "date-nsec": 12,
2273 "vm-clock-sec": 206,
2274 "vm-clock-nsec": 30
2275 }
2276 ],
2277 "backing-image":{
2278 "filename":"disks/base.qcow2",
2279 "format":"qcow2",
2280 "virtual-size":2048000
2281 }
2282 }
2283 },
2284 "qdev": "ide_disk",
2285 "type":"unknown"
2286 },
2287 {
2288 "io-status": "ok",
2289 "device":"ide1-cd0",
2290 "locked":false,
2291 "removable":true,
2292 "qdev": "/machine/unattached/device[23]",
2293 "tray_open": false,
2294 "type":"unknown"
2295 },
2296 {
2297 "device":"floppy0",
2298 "locked":false,
2299 "removable":true,
2300 "qdev": "/machine/unattached/device[20]",
2301 "type":"unknown"
2302 },
2303 {
2304 "device":"sd0",
2305 "locked":false,
2306 "removable":true,
2307 "type":"unknown"
2308 }
2309 ]
2310 }
2311 BlockDeviceTimedStats (Object)
2313 Statistics of a block device during a given interval of time.
2315 Members:
2317 "interval_length: int"
2319 Interval used for calculating the statistics, in seconds.
2320 "min_rd_latency_ns: int"
2322 Minimum latency of read operations in the defined interval, in
2323 nanoseconds.
2324 "min_wr_latency_ns: int"
2326 Minimum latency of write operations in the defined interval, in
2327 nanoseconds.
2328 "min_flush_latency_ns: int"
2330 Minimum latency of flush operations in the defined interval, in
2331 nanoseconds.
2332 "max_rd_latency_ns: int"
2334 Maximum latency of read operations in the defined interval, in
2335 nanoseconds.
2336 "max_wr_latency_ns: int"
2338 Maximum latency of write operations in the defined interval, in
2339 nanoseconds.
2340 "max_flush_latency_ns: int"
2342 Maximum latency of flush operations in the defined interval, in
2343 nanoseconds.
2344 "avg_rd_latency_ns: int"
2346 Average latency of read operations in the defined interval, in
2347 nanoseconds.
2348 "avg_wr_latency_ns: int"
2350 Average latency of write operations in the defined interval, in
2351 nanoseconds.
2352 "avg_flush_latency_ns: int"
2354 Average latency of flush operations in the defined interval, in
2355 nanoseconds.
2356 "avg_rd_queue_depth: number"
2358 Average number of pending read operations in the defined interval.
2359 "avg_wr_queue_depth: number"
2361 Average number of pending write operations in the defined interval.
2362 Since: 2.5
2364 BlockDeviceStats (Object)
2366 Statistics of a virtual block device or a block backing device.
2368 Members:
2370 "rd_bytes: int"
2372 The number of bytes read by the device.
2373 "wr_bytes: int"
2375 The number of bytes written by the device.
2376 "rd_operations: int"
2378 The number of read operations performed by the device.
2379 "wr_operations: int"
2381 The number of write operations performed by the device.
2382 "flush_operations: int"
2384 The number of cache flush operations performed by the device (since
2385 0.15.0)
2386 "flush_total_time_ns: int"
2388 Total time spend on cache flushes in nano-seconds (since 0.15.0).
2389 "wr_total_time_ns: int"
2391 Total time spend on writes in nano-seconds (since 0.15.0).
2392 "rd_total_time_ns: int"
2394 Total_time_spend on reads in nano-seconds (since 0.15.0).
2395 "wr_highest_offset: int"
2397 The offset after the greatest byte written to the device. The
2398 intended use of this information is for growable sparse files (like
2399 qcow2) that are used on top of a physical device.
2400 "rd_merged: int"
2402 Number of read requests that have been merged into another request
2403 (Since 2.3).
2404 "wr_merged: int"
2406 Number of write requests that have been merged into another request
2407 (Since 2.3).
2408 "idle_time_ns: int" (optional)
2410 Time since the last I/O operation, in nanoseconds. If the field is
2411 absent it means that there haven't been any operations yet (Since
2412 2.5).
2413 "failed_rd_operations: int"
2415 The number of failed read operations performed by the device (Since
2416 2.5)
2417 "failed_wr_operations: int"
2419 The number of failed write operations performed by the device
2420 (Since 2.5)
2421 "failed_flush_operations: int"
2423 The number of failed flush operations performed by the device
2424 (Since 2.5)
2425 "invalid_rd_operations: int"
2427 The number of invalid read operations performed by the device
2428 (Since 2.5)
2429 "invalid_wr_operations: int"
2431 The number of invalid write operations performed by the device
2432 (Since 2.5)
2433 "invalid_flush_operations: int"
2435 The number of invalid flush operations performed by the device
2436 (Since 2.5)
2437 "account_invalid: boolean"
2439 Whether invalid operations are included in the last access
2440 statistics (Since 2.5)
2441 "account_failed: boolean"
2443 Whether failed operations are included in the latency and last
2444 access statistics (Since 2.5)
2445 "timed_stats: array of BlockDeviceTimedStats"
2447 Statistics specific to the set of previously defined intervals of
2448 time (Since 2.5)
2449 "rd_latency_histogram: BlockLatencyHistogramInfo" (optional)
2451 "BlockLatencyHistogramInfo". (Since 4.0)
2452 "wr_latency_histogram: BlockLatencyHistogramInfo" (optional)
2454 "BlockLatencyHistogramInfo". (Since 4.0)
2455 "flush_latency_histogram: BlockLatencyHistogramInfo" (optional)
2457 "BlockLatencyHistogramInfo". (Since 4.0)
2458 Since: 0.14.0
2460 BlockStats (Object)
2462 Statistics of a virtual block device or a block backing device.
2464 Members:
2466 "device: string" (optional)
2468 If the stats are for a virtual block device, the name corresponding
2469 to the virtual block device.
2470 "node-name: string" (optional)
2472 The node name of the device. (Since 2.3)
2473 "qdev: string" (optional)
2475 The qdev ID, or if no ID is assigned, the QOM path of the block
2476 device. (since 3.0)
2477 "stats: BlockDeviceStats"
2479 A "BlockDeviceStats" for the device.
2480 "parent: BlockStats" (optional)
2482 This describes the file block device if it has one. Contains
2483 recursively the statistics of the underlying protocol (e.g. the
2484 host file for a qcow2 image). If there is no underlying protocol,
2485 this field is omitted
2486 "backing: BlockStats" (optional)
2488 This describes the backing block device if it has one. (Since 2.0)
2489 Since: 0.14.0
2491 query-blockstats (Command) Query the "BlockStats" for all virtual
2493 block devices.
2494 Arguments:
2496 "query-nodes: boolean" (optional)
2498 If true, the command will query all the block nodes that have a
2499 node name, in a list which will include "parent" information, but
2500 not "backing". If false or omitted, the behavior is as before -
2501 query all the device backends, recursively including their "parent"
2502 and "backing". Filter nodes that were created implicitly are
2503 skipped over in this mode. (Since 2.3)
2504 Returns: A list of "BlockStats" for each virtual block devices.
2506 Since: 0.14.0
2508 Example:
2510 -> { "execute": "query-blockstats" }
2512 <- {
2513 "return":[
2514 {
2515 "device":"ide0-hd0",
2516 "parent":{
2517 "stats":{
2518 "wr_highest_offset":3686448128,
2519 "wr_bytes":9786368,
2520 "wr_operations":751,
2521 "rd_bytes":122567168,
2522 "rd_operations":36772
2523 "wr_total_times_ns":313253456
2524 "rd_total_times_ns":3465673657
2525 "flush_total_times_ns":49653
2526 "flush_operations":61,
2527 "rd_merged":0,
2528 "wr_merged":0,
2529 "idle_time_ns":2953431879,
2530 "account_invalid":true,
2531 "account_failed":false
2532 }
2533 },
2534 "stats":{
2535 "wr_highest_offset":2821110784,
2536 "wr_bytes":9786368,
2537 "wr_operations":692,
2538 "rd_bytes":122739200,
2539 "rd_operations":36604
2540 "flush_operations":51,
2541 "wr_total_times_ns":313253456
2542 "rd_total_times_ns":3465673657
2543 "flush_total_times_ns":49653,
2544 "rd_merged":0,
2545 "wr_merged":0,
2546 "idle_time_ns":2953431879,
2547 "account_invalid":true,
2548 "account_failed":false
2549 },
2550 "qdev": "/machine/unattached/device[23]"
2551 },
2552 {
2553 "device":"ide1-cd0",
2554 "stats":{
2555 "wr_highest_offset":0,
2556 "wr_bytes":0,
2557 "wr_operations":0,
2558 "rd_bytes":0,
2559 "rd_operations":0
2560 "flush_operations":0,
2561 "wr_total_times_ns":0
2562 "rd_total_times_ns":0
2563 "flush_total_times_ns":0,
2564 "rd_merged":0,
2565 "wr_merged":0,
2566 "account_invalid":false,
2567 "account_failed":false
2568 },
2569 "qdev": "/machine/unattached/device[24]"
2570 },
2571 {
2572 "device":"floppy0",
2573 "stats":{
2574 "wr_highest_offset":0,
2575 "wr_bytes":0,
2576 "wr_operations":0,
2577 "rd_bytes":0,
2578 "rd_operations":0
2579 "flush_operations":0,
2580 "wr_total_times_ns":0
2581 "rd_total_times_ns":0
2582 "flush_total_times_ns":0,
2583 "rd_merged":0,
2584 "wr_merged":0,
2585 "account_invalid":false,
2586 "account_failed":false
2587 },
2588 "qdev": "/machine/unattached/device[16]"
2589 },
2590 {
2591 "device":"sd0",
2592 "stats":{
2593 "wr_highest_offset":0,
2594 "wr_bytes":0,
2595 "wr_operations":0,
2596 "rd_bytes":0,
2597 "rd_operations":0
2598 "flush_operations":0,
2599 "wr_total_times_ns":0
2600 "rd_total_times_ns":0
2601 "flush_total_times_ns":0,
2602 "rd_merged":0,
2603 "wr_merged":0,
2604 "account_invalid":false,
2605 "account_failed":false
2606 }
2607 }
2608 ]
2609 }
2610 BlockdevOnError (Enum)
2612 An enumeration of possible behaviors for errors on I/O operations. The
2614 exact meaning depends on whether the I/O was initiated by a guest or by
2615 a block job
2616 Values:
2618 "report"
2620 for guest operations, report the error to the guest; for jobs,
2621 cancel the job
2622 "ignore"
2624 ignore the error, only report a QMP event (BLOCK_IO_ERROR or
2625 BLOCK_JOB_ERROR)
2626 "enospc"
2628 same as "stop" on ENOSPC, same as "report" otherwise.
2629 "stop"
2631 for guest operations, stop the virtual machine; for jobs, pause the
2632 job
2633 "auto"
2635 inherit the error handling policy of the backend (since: 2.7)
2636 Since: 1.3
2638 MirrorSyncMode (Enum)
2640 An enumeration of possible behaviors for the initial synchronization
2642 phase of storage mirroring.
2643 Values:
2645 "top"
2647 copies data in the topmost image to the destination
2648 "full"
2650 copies data from all images to the destination
2651 "none"
2653 only copy data written from now on
2654 "incremental"
2656 only copy data described by the dirty bitmap. Since: 2.4
2657 Since: 1.3
2659 MirrorCopyMode (Enum)
2661 An enumeration whose values tell the mirror block job when to trigger
2663 writes to the target.
2664 Values:
2666 "background"
2668 copy data in background only.
2669 "write-blocking"
2671 when data is written to the source, write it (synchronously) to the
2672 target as well. In addition, data is copied in background just
2673 like in "background" mode.
2674 Since: 3.0
2676 BlockJobInfo (Object)
2678 Information about a long-running block device operation.
2680 Members:
2682 "type: string"
2684 the job type ('stream' for image streaming)
2685 "device: string"
2687 The job identifier. Originally the device name but other values are
2688 allowed since QEMU 2.7
2689 "len: int"
2691 Estimated "offset" value at the completion of the job. This value
2692 can arbitrarily change while the job is running, in both
2693 directions.
2694 "offset: int"
2696 Progress made until now. The unit is arbitrary and the value can
2697 only meaningfully be used for the ratio of "offset" to "len". The
2698 value is monotonically increasing.
2699 "busy: boolean"
2701 false if the job is known to be in a quiescent state, with no
2702 pending I/O. Since 1.3.
2703 "paused: boolean"
2705 whether the job is paused or, if "busy" is true, will pause itself
2706 as soon as possible. Since 1.3.
2707 "speed: int"
2709 the rate limit, bytes per second
2710 "io-status: BlockDeviceIoStatus"
2712 the status of the job (since 1.3)
2713 "ready: boolean"
2715 true if the job may be completed (since 2.2)
2716 "status: JobStatus"
2718 Current job state/status (since 2.12)
2719 "auto-finalize: boolean"
2721 Job will finalize itself when PENDING, moving to the CONCLUDED
2722 state. (since 2.12)
2723 "auto-dismiss: boolean"
2725 Job will dismiss itself when CONCLUDED, moving to the NULL state
2726 and disappearing from the query list. (since 2.12)
2727 "error: string" (optional)
2729 Error information if the job did not complete successfully. Not
2730 set if the job completed successfully. (since 2.12.1)
2731 Since: 1.1
2733 query-block-jobs (Command) Return information about long-running block
2735 device operations.
2736 Returns: a list of "BlockJobInfo" for each active block job
2738 Since: 1.1
2740 block_passwd (Command) This command sets the password of a block
2742 device that has not been open with a password and requires one.
2743 This command is now obsolete and will always return an error since 2.10
2745 Arguments:
2747 "device: string" (optional)
2749 Not documented
2750 "node-name: string" (optional)
2752 Not documented
2753 "password: string"
2755 Not documented
2756 block_resize (Command) Resize a block image while a guest is running.
2758 Either "device" or "node-name" must be set but not both.
2760 Arguments:
2762 "device: string" (optional)
2764 the name of the device to get the image resized
2765 "node-name: string" (optional)
2767 graph node name to get the image resized (Since 2.0)
2768 "size: int"
2770 new image size in bytes
2771 Returns: nothing on success If "device" is not a valid block device,
2773 DeviceNotFound
2774 Since: 0.14.0
2776 Example:
2778 -> { "execute": "block_resize",
2780 "arguments": { "device": "scratch", "size": 1073741824 } }
2781 <- { "return": {} }
2782 NewImageMode (Enum)
2784 An enumeration that tells QEMU how to set the backing file path in a
2786 new image file.
2787 Values:
2789 "existing"
2791 QEMU should look for an existing image file.
2792 "absolute-paths"
2794 QEMU should create a new image with absolute paths for the backing
2795 file. If there is no backing file available, the new image will not
2796 be backed either.
2797 Since: 1.1
2799 BlockdevSnapshotSync (Object)
2801 Either "device" or "node-name" must be set but not both.
2803 Members:
2805 "device: string" (optional)
2807 the name of the device to take a snapshot of.
2808 "node-name: string" (optional)
2810 graph node name to generate the snapshot from (Since 2.0)
2811 "snapshot-file: string"
2813 the target of the new overlay image. If the file exists, or if it
2814 is a device, the overlay will be created in the existing
2815 file/device. Otherwise, a new file will be created.
2816 "snapshot-node-name: string" (optional)
2818 the graph node name of the new image (Since 2.0)
2819 "format: string" (optional)
2821 the format of the overlay image, default is 'qcow2'.
2822 "mode: NewImageMode" (optional)
2824 whether and how QEMU should create a new image, default is
2825 'absolute-paths'.
2826 BlockdevSnapshot (Object)
2828 Members:
2830 "node: string"
2832 device or node name that will have a snapshot taken.
2833 "overlay: string"
2835 reference to the existing block device that will become the overlay
2836 of "node", as part of taking the snapshot. It must not have a
2837 current backing file (this can be achieved by passing "backing":
2838 null to blockdev-add).
2839 Since: 2.5
2841 DriveBackup (Object)
2843 Members:
2845 "job-id: string" (optional)
2847 identifier for the newly-created block job. If omitted, the device
2848 name will be used. (Since 2.7)
2849 "device: string"
2851 the device name or node-name of a root node which should be copied.
2852 "target: string"
2854 the target of the new image. If the file exists, or if it is a
2855 device, the existing file/device will be used as the new
2856 destination. If it does not exist, a new file will be created.
2857 "format: string" (optional)
2859 the format of the new destination, default is to probe if "mode" is
2860 'existing', else the format of the source
2861 "sync: MirrorSyncMode"
2863 what parts of the disk image should be copied to the destination
2864 (all the disk, only the sectors allocated in the topmost image,
2865 from a dirty bitmap, or only new I/O).
2866 "mode: NewImageMode" (optional)
2868 whether and how QEMU should create a new image, default is
2869 'absolute-paths'.
2870 "speed: int" (optional)
2872 the maximum speed, in bytes per second
2873 "bitmap: string" (optional)
2875 the name of dirty bitmap if sync is "incremental". Must be present
2876 if sync is "incremental", must NOT be present otherwise. (Since
2877 2.4)
2878 "compress: boolean" (optional)
2880 true to compress data, if the target format supports it. (default:
2881 false) (since 2.8)
2882 "on-source-error: BlockdevOnError" (optional)
2884 the action to take on an error on the source, default 'report'.
2885 'stop' and 'enospc' can only be used if the block device supports
2886 io-status (see BlockInfo).
2887 "on-target-error: BlockdevOnError" (optional)
2889 the action to take on an error on the target, default 'report' (no
2890 limitations, since this applies to a different block device than
2891 "device").
2892 "auto-finalize: boolean" (optional)
2894 When false, this job will wait in a PENDING state after it has
2895 finished its work, waiting for "block-job-finalize" before making
2896 any block graph changes. When true, this job will automatically
2897 perform its abort or commit actions. Defaults to true. (Since
2898 2.12)
2899 "auto-dismiss: boolean" (optional)
2901 When false, this job will wait in a CONCLUDED state after it has
2902 completely ceased all work, and awaits "block-job-dismiss". When
2903 true, this job will automatically disappear from the query list
2904 without user intervention. Defaults to true. (Since 2.12)
2905 Note: "on-source-error" and "on-target-error" only affect background
2907 I/O. If an error occurs during a guest write request, the device's
2908 rerror/werror actions will be used.
2909 Since: 1.6
2911 BlockdevBackup (Object)
2913 Members:
2915 "job-id: string" (optional)
2917 identifier for the newly-created block job. If omitted, the device
2918 name will be used. (Since 2.7)
2919 "device: string"
2921 the device name or node-name of a root node which should be copied.
2922 "target: string"
2924 the device name or node-name of the backup target node.
2925 "sync: MirrorSyncMode"
2927 what parts of the disk image should be copied to the destination
2928 (all the disk, only the sectors allocated in the topmost image, or
2929 only new I/O).
2930 "speed: int" (optional)
2932 the maximum speed, in bytes per second. The default is 0, for
2933 unlimited.
2934 "bitmap: string" (optional)
2936 the name of dirty bitmap if sync is "incremental". Must be present
2937 if sync is "incremental", must NOT be present otherwise. (Since
2938 3.1)
2939 "compress: boolean" (optional)
2941 true to compress data, if the target format supports it. (default:
2942 false) (since 2.8)
2943 "on-source-error: BlockdevOnError" (optional)
2945 the action to take on an error on the source, default 'report'.
2946 'stop' and 'enospc' can only be used if the block device supports
2947 io-status (see BlockInfo).
2948 "on-target-error: BlockdevOnError" (optional)
2950 the action to take on an error on the target, default 'report' (no
2951 limitations, since this applies to a different block device than
2952 "device").
2953 "auto-finalize: boolean" (optional)
2955 When false, this job will wait in a PENDING state after it has
2956 finished its work, waiting for "block-job-finalize" before making
2957 any block graph changes. When true, this job will automatically
2958 perform its abort or commit actions. Defaults to true. (Since
2959 2.12)
2960 "auto-dismiss: boolean" (optional)
2962 When false, this job will wait in a CONCLUDED state after it has
2963 completely ceased all work, and awaits "block-job-dismiss". When
2964 true, this job will automatically disappear from the query list
2965 without user intervention. Defaults to true. (Since 2.12)
2966 Note: "on-source-error" and "on-target-error" only affect background
2968 I/O. If an error occurs during a guest write request, the device's
2969 rerror/werror actions will be used.
2970 Since: 2.3
2972 blockdev-snapshot-sync (Command) Takes a synchronous snapshot of a
2974 block device.
2975 For the arguments, see the documentation of BlockdevSnapshotSync.
2977 Returns: nothing on success If "device" is not a valid block device,
2979 DeviceNotFound
2980 Since: 0.14.0
2982 Example:
2984 -> { "execute": "blockdev-snapshot-sync",
2986 "arguments": { "device": "ide-hd0",
2987 "snapshot-file":
2988 "/some/place/my-image",
2989 "format": "qcow2" } }
2990 <- { "return": {} }
2991 blockdev-snapshot (Command) Takes a snapshot of a block device.
2993 Take a snapshot, by installing 'node' as the backing image of
2995 'overlay'. Additionally, if 'node' is associated with a block device,
2996 the block device changes to using 'overlay' as its new active image.
2997 For the arguments, see the documentation of BlockdevSnapshot.
2999 Since: 2.5
3001 Example:
3003 -> { "execute": "blockdev-add",
3005 "arguments": { "driver": "qcow2",
3006 "node-name": "node1534",
3007 "file": { "driver": "file",
3008 "filename": "hd1.qcow2" },
3009 "backing": null } }
3010 <- { "return": {} }
3012 -> { "execute": "blockdev-snapshot",
3014 "arguments": { "node": "ide-hd0",
3015 "overlay": "node1534" } }
3016 <- { "return": {} }
3017 change-backing-file (Command) Change the backing file in the image
3019 file metadata. This does not cause QEMU to reopen the image file to
3020 reparse the backing filename (it may, however, perform a reopen to
3021 change permissions from r/o -> r/w -> r/o, if needed). The new backing
3022 file string is written into the image file metadata, and the QEMU
3023 internal strings are updated.
3024 Arguments:
3026 "image-node-name: string"
3028 The name of the block driver state node of the image to modify. The
3029 "device" argument is used to verify "image-node-name" is in the
3030 chain described by "device".
3031 "device: string"
3033 The device name or node-name of the root node that owns image-node-
3034 name.
3035 "backing-file: string"
3037 The string to write as the backing file. This string is not
3038 validated, so care should be taken when specifying the string or
3039 the image chain may not be able to be reopened again.
3040 Returns: Nothing on success
3042 If "device" does not exist or cannot be determined, DeviceNotFound
3044 Since: 2.1
3046 block-commit (Command) Live commit of data from overlay image nodes
3048 into backing nodes - i.e., writes data between 'top' and 'base' into
3049 'base'.
3050 Arguments:
3052 "job-id: string" (optional)
3054 identifier for the newly-created block job. If omitted, the device
3055 name will be used. (Since 2.7)
3056 "device: string"
3058 the device name or node-name of a root node
3059 "base-node: string" (optional)
3061 The node name of the backing image to write data into. If not
3062 specified, this is the deepest backing image. (since: 3.1)
3063 "base: string" (optional)
3065 Same as "base-node", except that it is a file name rather than a
3066 node name. This must be the exact filename string that was used to
3067 open the node; other strings, even if addressing the same file, are
3068 not accepted (deprecated, use "base-node" instead)
3069 "top-node: string" (optional)
3071 The node name of the backing image within the image chain which
3072 contains the topmost data to be committed down. If not specified,
3073 this is the active layer. (since: 3.1)
3074 "top: string" (optional)
3076 Same as "top-node", except that it is a file name rather than a
3077 node name. This must be the exact filename string that was used to
3078 open the node; other strings, even if addressing the same file, are
3079 not accepted (deprecated, use "base-node" instead)
3080 "backing-file: string" (optional)
3082 The backing file string to write into the overlay image of 'top'.
3083 If 'top' is the active layer, specifying a backing file string is
3084 an error. This filename is not validated.
3085 If a pathname string is such that it cannot be resolved by QEMU,
3087 that means that subsequent QMP or HMP commands must use node-names
3088 for the image in question, as filename lookup methods will fail.
3089 If not specified, QEMU will automatically determine the backing
3091 file string to use, or error out if there is no obvious choice.
3092 Care should be taken when specifying the string, to specify a valid
3093 filename or protocol. (Since 2.1)
3094 If top == base, that is an error. If top == active, the job will
3096 not be completed by itself, user needs to complete the job with the
3097 block-job-complete command after getting the ready event. (Since
3098 2.0)
3099 If the base image is smaller than top, then the base image will be
3101 resized to be the same size as top. If top is smaller than the
3102 base image, the base will not be truncated. If you want the base
3103 image size to match the size of the smaller top, you can safely
3104 truncate it yourself once the commit operation successfully
3105 completes.
3106 "speed: int" (optional)
3108 the maximum speed, in bytes per second
3109 "filter-node-name: string" (optional)
3111 the node name that should be assigned to the filter driver that the
3112 commit job inserts into the graph above "top". If this option is
3113 not given, a node name is autogenerated. (Since: 2.9)
3114 "auto-finalize: boolean" (optional)
3116 When false, this job will wait in a PENDING state after it has
3117 finished its work, waiting for "block-job-finalize" before making
3118 any block graph changes. When true, this job will automatically
3119 perform its abort or commit actions. Defaults to true. (Since 3.1)
3120 "auto-dismiss: boolean" (optional)
3122 When false, this job will wait in a CONCLUDED state after it has
3123 completely ceased all work, and awaits "block-job-dismiss". When
3124 true, this job will automatically disappear from the query list
3125 without user intervention. Defaults to true. (Since 3.1)
3126 Returns: Nothing on success If "device" does not exist, DeviceNotFound
3128 Any other error returns a GenericError.
3129 Since: 1.3
3131 Example:
3133 -> { "execute": "block-commit",
3135 "arguments": { "device": "virtio0",
3136 "top": "/tmp/snap1.qcow2" } }
3137 <- { "return": {} }
3138 drive-backup (Command) Start a point-in-time copy of a block device to
3140 a new destination. The status of ongoing drive-backup operations can
3141 be checked with query-block-jobs where the BlockJobInfo.type field has
3142 the value 'backup'. The operation can be stopped before it has
3143 completed using the block-job-cancel command.
3144 Arguments: the members of "DriveBackup"
3146 Returns: nothing on success If "device" is not a valid block device,
3148 GenericError
3149 Since: 1.6
3151 Example:
3153 -> { "execute": "drive-backup",
3155 "arguments": { "device": "drive0",
3156 "sync": "full",
3157 "target": "backup.img" } }
3158 <- { "return": {} }
3159 blockdev-backup (Command) Start a point-in-time copy of a block device
3161 to a new destination. The status of ongoing blockdev-backup operations
3162 can be checked with query-block-jobs where the BlockJobInfo.type field
3163 has the value 'backup'. The operation can be stopped before it has
3164 completed using the block-job-cancel command.
3165 Arguments: the members of "BlockdevBackup"
3167 Returns: nothing on success If "device" is not a valid block device,
3169 DeviceNotFound
3170 Since: 2.3
3172 Example:
3174 -> { "execute": "blockdev-backup",
3176 "arguments": { "device": "src-id",
3177 "sync": "full",
3178 "target": "tgt-id" } }
3179 <- { "return": {} }
3180 query-named-block-nodes (Command) Get the named block driver list
3182 Returns: the list of BlockDeviceInfo
3184 Since: 2.0
3186 Example:
3188 -> { "execute": "query-named-block-nodes" }
3190 <- { "return": [ { "ro":false,
3191 "drv":"qcow2",
3192 "encrypted":false,
3193 "file":"disks/test.qcow2",
3194 "node-name": "my-node",
3195 "backing_file_depth":1,
3196 "bps":1000000,
3197 "bps_rd":0,
3198 "bps_wr":0,
3199 "iops":1000000,
3200 "iops_rd":0,
3201 "iops_wr":0,
3202 "bps_max": 8000000,
3203 "bps_rd_max": 0,
3204 "bps_wr_max": 0,
3205 "iops_max": 0,
3206 "iops_rd_max": 0,
3207 "iops_wr_max": 0,
3208 "iops_size": 0,
3209 "write_threshold": 0,
3210 "image":{
3211 "filename":"disks/test.qcow2",
3212 "format":"qcow2",
3213 "virtual-size":2048000,
3214 "backing_file":"base.qcow2",
3215 "full-backing-filename":"disks/base.qcow2",
3216 "backing-filename-format":"qcow2",
3217 "snapshots":[
3218 {
3219 "id": "1",
3220 "name": "snapshot1",
3221 "vm-state-size": 0,
3222 "date-sec": 10000200,
3223 "date-nsec": 12,
3224 "vm-clock-sec": 206,
3225 "vm-clock-nsec": 30
3226 }
3227 ],
3228 "backing-image":{
3229 "filename":"disks/base.qcow2",
3230 "format":"qcow2",
3231 "virtual-size":2048000
3232 }
3233 } } ] }
3234 XDbgBlockGraphNodeType (Enum)
3236 Values:
3238 "block-backend"
3240 corresponds to BlockBackend
3241 "block-job"
3243 corresonds to BlockJob
3244 "block-driver"
3246 corresponds to BlockDriverState
3247 Since: 4.0
3249 XDbgBlockGraphNode (Object)
3251 Members:
3253 "id: int"
3255 Block graph node identifier. This "id" is generated only for
3256 x-debug-query-block-graph and does not relate to any other
3257 identifiers in Qemu.
3258 "type: XDbgBlockGraphNodeType"
3260 Type of graph node. Can be one of block-backend, block-job or
3261 block-driver-state.
3262 "name: string"
3264 Human readable name of the node. Corresponds to node-name for
3265 block-driver-state nodes; is not guaranteed to be unique in the
3266 whole graph (with block-jobs and block-backends).
3267 Since: 4.0
3269 BlockPermission (Enum)
3271 Enum of base block permissions.
3273 Values:
3275 "consistent-read"
3277 A user that has the "permission" of consistent reads is guaranteed
3278 that their view of the contents of the block device is complete and
3279 self-consistent, representing the contents of a disk at a specific
3280 point. For most block devices (including their backing files) this
3281 is true, but the property cannot be maintained in a few situations
3282 like for intermediate nodes of a commit block job.
3283 "write"
3285 This permission is required to change the visible disk contents.
3286 "write-unchanged"
3288 This permission (which is weaker than BLK_PERM_WRITE) is both
3289 enough and required for writes to the block node when the caller
3290 promises that the visible disk content doesn't change. As the
3291 BLK_PERM_WRITE permission is strictly stronger, either is
3292 sufficient to perform an unchanging write.
3293 "resize"
3295 This permission is required to change the size of a block node.
3296 "graph-mod"
3298 This permission is required to change the node that this BdrvChild
3299 points to.
3300 Since: 4.0
3302 XDbgBlockGraphEdge (Object)
3304 Block Graph edge description for x-debug-query-block-graph.
3306 Members:
3308 "parent: int"
3310 parent id
3311 "child: int"
3313 child id
3314 "name: string"
3316 name of the relation (examples are 'file' and 'backing')
3317 "perm: array of BlockPermission"
3319 granted permissions for the parent operating on the child
3320 "shared-perm: array of BlockPermission"
3322 permissions that can still be granted to other users of the child
3323 while it is still attached to this parent
3324 Since: 4.0
3326 XDbgBlockGraph (Object)
3328 Block Graph - list of nodes and list of edges.
3330 Members:
3332 "nodes: array of XDbgBlockGraphNode"
3334 Not documented
3335 "edges: array of XDbgBlockGraphEdge"
3337 Not documented
3338 Since: 4.0
3340 x-debug-query-block-graph (Command) Get the block graph.
3342 Since: 4.0
3344 drive-mirror (Command) Start mirroring a block device's writes to a
3346 new destination. target specifies the target of the new image. If the
3347 file exists, or if it is a device, it will be used as the new
3348 destination for writes. If it does not exist, a new file will be
3349 created. format specifies the format of the mirror image, default is to
3350 probe if mode='existing', else the format of the source.
3351 Arguments: the members of "DriveMirror"
3353 Returns: nothing on success If "device" is not a valid block device,
3355 GenericError
3356 Since: 1.3
3358 Example:
3360 -> { "execute": "drive-mirror",
3362 "arguments": { "device": "ide-hd0",
3363 "target": "/some/place/my-image",
3364 "sync": "full",
3365 "format": "qcow2" } }
3366 <- { "return": {} }
3367 DriveMirror (Object)
3369 A set of parameters describing drive mirror setup.
3371 Members:
3373 "job-id: string" (optional)
3375 identifier for the newly-created block job. If omitted, the device
3376 name will be used. (Since 2.7)
3377 "device: string"
3379 the device name or node-name of a root node whose writes should be
3380 mirrored.
3381 "target: string"
3383 the target of the new image. If the file exists, or if it is a
3384 device, the existing file/device will be used as the new
3385 destination. If it does not exist, a new file will be created.
3386 "format: string" (optional)
3388 the format of the new destination, default is to probe if "mode" is
3389 'existing', else the format of the source
3390 "node-name: string" (optional)
3392 the new block driver state node name in the graph (Since 2.1)
3393 "replaces: string" (optional)
3395 with sync=full graph node name to be replaced by the new image when
3396 a whole image copy is done. This can be used to repair broken
3397 Quorum files. (Since 2.1)
3398 "mode: NewImageMode" (optional)
3400 whether and how QEMU should create a new image, default is
3401 'absolute-paths'.
3402 "speed: int" (optional)
3404 the maximum speed, in bytes per second
3405 "sync: MirrorSyncMode"
3407 what parts of the disk image should be copied to the destination
3408 (all the disk, only the sectors allocated in the topmost image, or
3409 only new I/O).
3410 "granularity: int" (optional)
3412 granularity of the dirty bitmap, default is 64K if the image format
3413 doesn't have clusters, 4K if the clusters are smaller than that,
3414 else the cluster size. Must be a power of 2 between 512 and 64M
3415 (since 1.4).
3416 "buf-size: int" (optional)
3418 maximum amount of data in flight from source to target (since 1.4).
3419 "on-source-error: BlockdevOnError" (optional)
3421 the action to take on an error on the source, default 'report'.
3422 'stop' and 'enospc' can only be used if the block device supports
3423 io-status (see BlockInfo).
3424 "on-target-error: BlockdevOnError" (optional)
3426 the action to take on an error on the target, default 'report' (no
3427 limitations, since this applies to a different block device than
3428 "device").
3429 "unmap: boolean" (optional)
3431 Whether to try to unmap target sectors where source has only zero.
3432 If true, and target unallocated sectors will read as zero, target
3433 image sectors will be unmapped; otherwise, zeroes will be written.
3434 Both will result in identical contents. Default is true. (Since
3435 2.4)
3436 "copy-mode: MirrorCopyMode" (optional)
3438 when to copy data to the destination; defaults to 'background'
3439 (Since: 3.0)
3440 "auto-finalize: boolean" (optional)
3442 When false, this job will wait in a PENDING state after it has
3443 finished its work, waiting for "block-job-finalize" before making
3444 any block graph changes. When true, this job will automatically
3445 perform its abort or commit actions. Defaults to true. (Since 3.1)
3446 "auto-dismiss: boolean" (optional)
3448 When false, this job will wait in a CONCLUDED state after it has
3449 completely ceased all work, and awaits "block-job-dismiss". When
3450 true, this job will automatically disappear from the query list
3451 without user intervention. Defaults to true. (Since 3.1)
3452 Since: 1.3
3454 BlockDirtyBitmap (Object)
3456 Members:
3458 "node: string"
3460 name of device/node which the bitmap is tracking
3461 "name: string"
3463 name of the dirty bitmap
3464 Since: 2.4
3466 BlockDirtyBitmapAdd (Object)
3468 Members:
3470 "node: string"
3472 name of device/node which the bitmap is tracking
3473 "name: string"
3475 name of the dirty bitmap
3476 "granularity: int" (optional)
3478 the bitmap granularity, default is 64k for block-dirty-bitmap-add
3479 "persistent: boolean" (optional)
3481 the bitmap is persistent, i.e. it will be saved to the
3482 corresponding block device image file on its close. For now only
3483 Qcow2 disks support persistent bitmaps. Default is false for block-
3484 dirty-bitmap-add. (Since: 2.10)
3485 "autoload: boolean" (optional)
3487 ignored and deprecated since 2.12. Currently, all dirty tracking
3488 bitmaps are loaded from Qcow2 on open.
3489 "disabled: boolean" (optional)
3491 the bitmap is created in the disabled state, which means that it
3492 will not track drive changes. The bitmap may be enabled with block-
3493 dirty-bitmap-enable. Default is false. (Since: 4.0)
3494 Since: 2.4
3496 BlockDirtyBitmapMergeSource (Alternate)
3498 Members:
3500 "local: string"
3502 name of the bitmap, attached to the same node as target bitmap.
3503 "external: BlockDirtyBitmap"
3505 bitmap with specified node
3506 Since: 4.1
3508 BlockDirtyBitmapMerge (Object)
3510 Members:
3512 "node: string"
3514 name of device/node which the "target" bitmap is tracking
3515 "target: string"
3517 name of the destination dirty bitmap
3518 "bitmaps: array of BlockDirtyBitmapMergeSource"
3520 name(s) of the source dirty bitmap(s) at "node" and/or fully
3521 specifed BlockDirtyBitmap elements. The latter are supported since
3522 4.1.
3523 Since: 4.0
3525 block-dirty-bitmap-add (Command) Create a dirty bitmap with a name on
3527 the node, and start tracking the writes.
3528 Returns: nothing on success If "node" is not a valid block device or
3530 node, DeviceNotFound If "name" is already taken, GenericError with an
3531 explanation
3532 Since: 2.4
3534 Example:
3536 -> { "execute": "block-dirty-bitmap-add",
3538 "arguments": { "node": "drive0", "name": "bitmap0" } }
3539 <- { "return": {} }
3540 block-dirty-bitmap-remove (Command) Stop write tracking and remove the
3542 dirty bitmap that was created with block-dirty-bitmap-add. If the
3543 bitmap is persistent, remove it from its storage too.
3544 Returns: nothing on success If "node" is not a valid block device or
3546 node, DeviceNotFound If "name" is not found, GenericError with an
3547 explanation if "name" is frozen by an operation, GenericError
3548 Since: 2.4
3550 Example:
3552 -> { "execute": "block-dirty-bitmap-remove",
3554 "arguments": { "node": "drive0", "name": "bitmap0" } }
3555 <- { "return": {} }
3556 block-dirty-bitmap-clear (Command) Clear (reset) a dirty bitmap on the
3558 device, so that an incremental backup from this point in time forward
3559 will only backup clusters modified after this clear operation.
3560 Returns: nothing on success If "node" is not a valid block device,
3562 DeviceNotFound If "name" is not found, GenericError with an explanation
3563 Since: 2.4
3565 Example:
3567 -> { "execute": "block-dirty-bitmap-clear",
3569 "arguments": { "node": "drive0", "name": "bitmap0" } }
3570 <- { "return": {} }
3571 block-dirty-bitmap-enable (Command) Enables a dirty bitmap so that it
3573 will begin tracking disk changes.
3574 Returns: nothing on success If "node" is not a valid block device,
3576 DeviceNotFound If "name" is not found, GenericError with an explanation
3577 Since: 4.0
3579 Example:
3581 -> { "execute": "block-dirty-bitmap-enable",
3583 "arguments": { "node": "drive0", "name": "bitmap0" } }
3584 <- { "return": {} }
3585 block-dirty-bitmap-disable (Command) Disables a dirty bitmap so that
3587 it will stop tracking disk changes.
3588 Returns: nothing on success If "node" is not a valid block device,
3590 DeviceNotFound If "name" is not found, GenericError with an explanation
3591 Since: 4.0
3593 Example:
3595 -> { "execute": "block-dirty-bitmap-disable",
3597 "arguments": { "node": "drive0", "name": "bitmap0" } }
3598 <- { "return": {} }
3599 block-dirty-bitmap-merge (Command) Merge dirty bitmaps listed in
3601 "bitmaps" to the "target" dirty bitmap. Dirty bitmaps in "bitmaps"
3602 will be unchanged, except if it also appears as the "target" bitmap.
3603 Any bits already set in "target" will still be set after the merge,
3604 i.e., this operation does not clear the target. On error, "target" is
3605 unchanged.
3606 The resulting bitmap will count as dirty any clusters that were dirty
3608 in any of the source bitmaps. This can be used to achieve backup
3609 checkpoints, or in simpler usages, to copy bitmaps.
3610 Returns: nothing on success If "node" is not a valid block device,
3612 DeviceNotFound If any bitmap in "bitmaps" or "target" is not found,
3613 GenericError If any of the bitmaps have different sizes or
3614 granularities, GenericError
3615 Since: 4.0
3617 Example:
3619 -> { "execute": "block-dirty-bitmap-merge",
3621 "arguments": { "node": "drive0", "target": "bitmap0",
3622 "bitmaps": ["bitmap1"] } }
3623 <- { "return": {} }
3624 BlockDirtyBitmapSha256 (Object)
3626 SHA256 hash of dirty bitmap data
3628 Members:
3630 "sha256: string"
3632 ASCII representation of SHA256 bitmap hash
3633 Since: 2.10
3635 x-debug-block-dirty-bitmap-sha256 (Command) Get bitmap SHA256.
3637 Returns: BlockDirtyBitmapSha256 on success If "node" is not a valid
3639 block device, DeviceNotFound If "name" is not found or if hashing has
3640 failed, GenericError with an explanation
3641 Since: 2.10
3643 blockdev-mirror (Command) Start mirroring a block device's writes to a
3645 new destination.
3646 Arguments:
3648 "job-id: string" (optional)
3650 identifier for the newly-created block job. If omitted, the device
3651 name will be used. (Since 2.7)
3652 "device: string"
3654 The device name or node-name of a root node whose writes should be
3655 mirrored.
3656 "target: string"
3658 the id or node-name of the block device to mirror to. This mustn't
3659 be attached to guest.
3660 "replaces: string" (optional)
3662 with sync=full graph node name to be replaced by the new image when
3663 a whole image copy is done. This can be used to repair broken
3664 Quorum files.
3665 "speed: int" (optional)
3667 the maximum speed, in bytes per second
3668 "sync: MirrorSyncMode"
3670 what parts of the disk image should be copied to the destination
3671 (all the disk, only the sectors allocated in the topmost image, or
3672 only new I/O).
3673 "granularity: int" (optional)
3675 granularity of the dirty bitmap, default is 64K if the image format
3676 doesn't have clusters, 4K if the clusters are smaller than that,
3677 else the cluster size. Must be a power of 2 between 512 and 64M
3678 "buf-size: int" (optional)
3680 maximum amount of data in flight from source to target
3681 "on-source-error: BlockdevOnError" (optional)
3683 the action to take on an error on the source, default 'report'.
3684 'stop' and 'enospc' can only be used if the block device supports
3685 io-status (see BlockInfo).
3686 "on-target-error: BlockdevOnError" (optional)
3688 the action to take on an error on the target, default 'report' (no
3689 limitations, since this applies to a different block device than
3690 "device").
3691 "filter-node-name: string" (optional)
3693 the node name that should be assigned to the filter driver that the
3694 mirror job inserts into the graph above "device". If this option is
3695 not given, a node name is autogenerated. (Since: 2.9)
3696 "copy-mode: MirrorCopyMode" (optional)
3698 when to copy data to the destination; defaults to 'background'
3699 (Since: 3.0)
3700 "auto-finalize: boolean" (optional)
3702 When false, this job will wait in a PENDING state after it has
3703 finished its work, waiting for "block-job-finalize" before making
3704 any block graph changes. When true, this job will automatically
3705 perform its abort or commit actions. Defaults to true. (Since 3.1)
3706 "auto-dismiss: boolean" (optional)
3708 When false, this job will wait in a CONCLUDED state after it has
3709 completely ceased all work, and awaits "block-job-dismiss". When
3710 true, this job will automatically disappear from the query list
3711 without user intervention. Defaults to true. (Since 3.1)
3712 Returns: nothing on success.
3714 Since: 2.6
3716 Example:
3718 -> { "execute": "blockdev-mirror",
3720 "arguments": { "device": "ide-hd0",
3721 "target": "target0",
3722 "sync": "full" } }
3723 <- { "return": {} }
3724 block_set_io_throttle (Command) Change I/O throttle limits for a block
3726 drive.
3727 Since QEMU 2.4, each device with I/O limits is member of a throttle
3729 group.
3730 If two or more devices are members of the same group, the limits will
3732 apply to the combined I/O of the whole group in a round-robin fashion.
3733 Therefore, setting new I/O limits to a device will affect the whole
3734 group.
3735 The name of the group can be specified using the 'group' parameter. If
3737 the parameter is unset, it is assumed to be the current group of that
3738 device. If it's not in any group yet, the name of the device will be
3739 used as the name for its group.
3740 The 'group' parameter can also be used to move a device to a different
3742 group. In this case the limits specified in the parameters will be
3743 applied to the new group only.
3744 I/O limits can be disabled by setting all of them to 0. In this case
3746 the device will be removed from its group and the rest of its members
3747 will not be affected. The 'group' parameter is ignored.
3748 Arguments: the members of "BlockIOThrottle"
3750 Returns: Nothing on success If "device" is not a valid block device,
3752 DeviceNotFound
3753 Since: 1.1
3755 Example:
3757 -> { "execute": "block_set_io_throttle",
3759 "arguments": { "id": "virtio-blk-pci0/virtio-backend",
3760 "bps": 0,
3761 "bps_rd": 0,
3762 "bps_wr": 0,
3763 "iops": 512,
3764 "iops_rd": 0,
3765 "iops_wr": 0,
3766 "bps_max": 0,
3767 "bps_rd_max": 0,
3768 "bps_wr_max": 0,
3769 "iops_max": 0,
3770 "iops_rd_max": 0,
3771 "iops_wr_max": 0,
3772 "bps_max_length": 0,
3773 "iops_size": 0 } }
3774 <- { "return": {} }
3775 -> { "execute": "block_set_io_throttle",
3777 "arguments": { "id": "ide0-1-0",
3778 "bps": 1000000,
3779 "bps_rd": 0,
3780 "bps_wr": 0,
3781 "iops": 0,
3782 "iops_rd": 0,
3783 "iops_wr": 0,
3784 "bps_max": 8000000,
3785 "bps_rd_max": 0,
3786 "bps_wr_max": 0,
3787 "iops_max": 0,
3788 "iops_rd_max": 0,
3789 "iops_wr_max": 0,
3790 "bps_max_length": 60,
3791 "iops_size": 0 } }
3792 <- { "return": {} }
3793 BlockIOThrottle (Object)
3795 A set of parameters describing block throttling.
3797 Members:
3799 "device: string" (optional)
3801 Block device name (deprecated, use "id" instead)
3802 "id: string" (optional)
3804 The name or QOM path of the guest device (since: 2.8)
3805 "bps: int"
3807 total throughput limit in bytes per second
3808 "bps_rd: int"
3810 read throughput limit in bytes per second
3811 "bps_wr: int"
3813 write throughput limit in bytes per second
3814 "iops: int"
3816 total I/O operations per second
3817 "iops_rd: int"
3819 read I/O operations per second
3820 "iops_wr: int"
3822 write I/O operations per second
3823 "bps_max: int" (optional)
3825 total throughput limit during bursts, in bytes (Since 1.7)
3826 "bps_rd_max: int" (optional)
3828 read throughput limit during bursts, in bytes (Since 1.7)
3829 "bps_wr_max: int" (optional)
3831 write throughput limit during bursts, in bytes (Since 1.7)
3832 "iops_max: int" (optional)
3834 total I/O operations per second during bursts, in bytes (Since 1.7)
3835 "iops_rd_max: int" (optional)
3837 read I/O operations per second during bursts, in bytes (Since 1.7)
3838 "iops_wr_max: int" (optional)
3840 write I/O operations per second during bursts, in bytes (Since 1.7)
3841 "bps_max_length: int" (optional)
3843 maximum length of the "bps_max" burst period, in seconds. It must
3844 only be set if "bps_max" is set as well. Defaults to 1. (Since
3845 2.6)
3846 "bps_rd_max_length: int" (optional)
3848 maximum length of the "bps_rd_max" burst period, in seconds. It
3849 must only be set if "bps_rd_max" is set as well. Defaults to 1.
3850 (Since 2.6)
3851 "bps_wr_max_length: int" (optional)
3853 maximum length of the "bps_wr_max" burst period, in seconds. It
3854 must only be set if "bps_wr_max" is set as well. Defaults to 1.
3855 (Since 2.6)
3856 "iops_max_length: int" (optional)
3858 maximum length of the "iops" burst period, in seconds. It must only
3859 be set if "iops_max" is set as well. Defaults to 1. (Since 2.6)
3860 "iops_rd_max_length: int" (optional)
3862 maximum length of the "iops_rd_max" burst period, in seconds. It
3863 must only be set if "iops_rd_max" is set as well. Defaults to 1.
3864 (Since 2.6)
3865 "iops_wr_max_length: int" (optional)
3867 maximum length of the "iops_wr_max" burst period, in seconds. It
3868 must only be set if "iops_wr_max" is set as well. Defaults to 1.
3869 (Since 2.6)
3870 "iops_size: int" (optional)
3872 an I/O size in bytes (Since 1.7)
3873 "group: string" (optional)
3875 throttle group name (Since 2.4)
3876 Since: 1.1
3878 ThrottleLimits (Object)
3880 Limit parameters for throttling. Since some limit combinations are
3882 illegal, limits should always be set in one transaction. All fields are
3883 optional. When setting limits, if a field is missing the current value
3884 is not changed.
3885 Members:
3887 "iops-total: int" (optional)
3889 limit total I/O operations per second
3890 "iops-total-max: int" (optional)
3892 I/O operations burst
3893 "iops-total-max-length: int" (optional)
3895 length of the iops-total-max burst period, in seconds It must only
3896 be set if "iops-total-max" is set as well.
3897 "iops-read: int" (optional)
3899 limit read operations per second
3900 "iops-read-max: int" (optional)
3902 I/O operations read burst
3903 "iops-read-max-length: int" (optional)
3905 length of the iops-read-max burst period, in seconds It must only
3906 be set if "iops-read-max" is set as well.
3907 "iops-write: int" (optional)
3909 limit write operations per second
3910 "iops-write-max: int" (optional)
3912 I/O operations write burst
3913 "iops-write-max-length: int" (optional)
3915 length of the iops-write-max burst period, in seconds It must only
3916 be set if "iops-write-max" is set as well.
3917 "bps-total: int" (optional)
3919 limit total bytes per second
3920 "bps-total-max: int" (optional)
3922 total bytes burst
3923 "bps-total-max-length: int" (optional)
3925 length of the bps-total-max burst period, in seconds. It must only
3926 be set if "bps-total-max" is set as well.
3927 "bps-read: int" (optional)
3929 limit read bytes per second
3930 "bps-read-max: int" (optional)
3932 total bytes read burst
3933 "bps-read-max-length: int" (optional)
3935 length of the bps-read-max burst period, in seconds It must only be
3936 set if "bps-read-max" is set as well.
3937 "bps-write: int" (optional)
3939 limit write bytes per second
3940 "bps-write-max: int" (optional)
3942 total bytes write burst
3943 "bps-write-max-length: int" (optional)
3945 length of the bps-write-max burst period, in seconds It must only
3946 be set if "bps-write-max" is set as well.
3947 "iops-size: int" (optional)
3949 when limiting by iops max size of an I/O in bytes
3950 Since: 2.11
3952 block-stream (Command) Copy data from a backing file into a block
3954 device.
3955 The block streaming operation is performed in the background until the
3957 entire backing file has been copied. This command returns immediately
3958 once streaming has started. The status of ongoing block streaming
3959 operations can be checked with query-block-jobs. The operation can be
3960 stopped before it has completed using the block-job-cancel command.
3961 The node that receives the data is called the top image, can be located
3963 in any part of the chain (but always above the base image; see below)
3964 and can be specified using its device or node name. Earlier qemu
3965 versions only allowed 'device' to name the top level node; presence of
3966 the 'base-node' parameter during introspection can be used as a witness
3967 of the enhanced semantics of 'device'.
3968 If a base file is specified then sectors are not copied from that base
3970 file and its backing chain. When streaming completes the image file
3971 will have the base file as its backing file. This can be used to
3972 stream a subset of the backing file chain instead of flattening the
3973 entire image.
3974 On successful completion the image file is updated to drop the backing
3976 file and the BLOCK_JOB_COMPLETED event is emitted.
3977 Arguments:
3979 "job-id: string" (optional)
3981 identifier for the newly-created block job. If omitted, the device
3982 name will be used. (Since 2.7)
3983 "device: string"
3985 the device or node name of the top image
3986 "base: string" (optional)
3988 the common backing file name. It cannot be set if "base-node" is
3989 also set.
3990 "base-node: string" (optional)
3992 the node name of the backing file. It cannot be set if "base" is
3993 also set. (Since 2.8)
3994 "backing-file: string" (optional)
3996 The backing file string to write into the top image. This filename
3997 is not validated.
3998 If a pathname string is such that it cannot be resolved by QEMU,
4000 that means that subsequent QMP or HMP commands must use node-names
4001 for the image in question, as filename lookup methods will fail.
4002 If not specified, QEMU will automatically determine the backing
4004 file string to use, or error out if there is no obvious choice.
4005 Care should be taken when specifying the string, to specify a valid
4006 filename or protocol. (Since 2.1)
4007 "speed: int" (optional)
4009 the maximum speed, in bytes per second
4010 "on-error: BlockdevOnError" (optional)
4012 the action to take on an error (default report). 'stop' and
4013 'enospc' can only be used if the block device supports io-status
4014 (see BlockInfo). Since 1.3.
4015 "auto-finalize: boolean" (optional)
4017 When false, this job will wait in a PENDING state after it has
4018 finished its work, waiting for "block-job-finalize" before making
4019 any block graph changes. When true, this job will automatically
4020 perform its abort or commit actions. Defaults to true. (Since 3.1)
4021 "auto-dismiss: boolean" (optional)
4023 When false, this job will wait in a CONCLUDED state after it has
4024 completely ceased all work, and awaits "block-job-dismiss". When
4025 true, this job will automatically disappear from the query list
4026 without user intervention. Defaults to true. (Since 3.1)
4027 Returns: Nothing on success. If "device" does not exist,
4029 DeviceNotFound.
4030 Since: 1.1
4032 Example:
4034 -> { "execute": "block-stream",
4036 "arguments": { "device": "virtio0",
4037 "base": "/tmp/master.qcow2" } }
4038 <- { "return": {} }
4039 block-job-set-speed (Command) Set maximum speed for a background block
4041 operation.
4042 This command can only be issued when there is an active block job.
4044 Throttling can be disabled by setting the speed to 0.
4046 Arguments:
4048 "device: string"
4050 The job identifier. This used to be a device name (hence the name
4051 of the parameter), but since QEMU 2.7 it can have other values.
4052 "speed: int"
4054 the maximum speed, in bytes per second, or 0 for unlimited.
4055 Defaults to 0.
4056 Returns: Nothing on success If no background operation is active on
4058 this device, DeviceNotActive
4059 Since: 1.1
4061 block-job-cancel (Command) Stop an active background block operation.
4063 This command returns immediately after marking the active background
4065 block operation for cancellation. It is an error to call this command
4066 if no operation is in progress.
4067 The operation will cancel as soon as possible and then emit the
4069 BLOCK_JOB_CANCELLED event. Before that happens the job is still
4070 visible when enumerated using query-block-jobs.
4071 Note that if you issue 'block-job-cancel' after 'drive-mirror' has
4073 indicated (via the event BLOCK_JOB_READY) that the source and
4074 destination are synchronized, then the event triggered by this command
4075 changes to BLOCK_JOB_COMPLETED, to indicate that the mirroring has
4076 ended and the destination now has a point-in-time copy tied to the time
4077 of the cancellation.
4078 For streaming, the image file retains its backing file unless the
4080 streaming operation happens to complete just as it is being cancelled.
4081 A new streaming operation can be started at a later time to finish
4082 copying all data from the backing file.
4083 Arguments:
4085 "device: string"
4087 The job identifier. This used to be a device name (hence the name
4088 of the parameter), but since QEMU 2.7 it can have other values.
4089 "force: boolean" (optional)
4091 If true, and the job has already emitted the event BLOCK_JOB_READY,
4092 abandon the job immediately (even if it is paused) instead of
4093 waiting for the destination to complete its final synchronization
4094 (since 1.3)
4095 Returns: Nothing on success If no background operation is active on
4097 this device, DeviceNotActive
4098 Since: 1.1
4100 block-job-pause (Command) Pause an active background block operation.
4102 This command returns immediately after marking the active background
4104 block operation for pausing. It is an error to call this command if no
4105 operation is in progress or if the job is already paused.
4106 The operation will pause as soon as possible. No event is emitted when
4108 the operation is actually paused. Cancelling a paused job
4109 automatically resumes it.
4110 Arguments:
4112 "device: string"
4114 The job identifier. This used to be a device name (hence the name
4115 of the parameter), but since QEMU 2.7 it can have other values.
4116 Returns: Nothing on success If no background operation is active on
4118 this device, DeviceNotActive
4119 Since: 1.3
4121 block-job-resume (Command) Resume an active background block
4123 operation.
4124 This command returns immediately after resuming a paused background
4126 block operation. It is an error to call this command if no operation
4127 is in progress or if the job is not paused.
4128 This command also clears the error status of the job.
4130 Arguments:
4132 "device: string"
4134 The job identifier. This used to be a device name (hence the name
4135 of the parameter), but since QEMU 2.7 it can have other values.
4136 Returns: Nothing on success If no background operation is active on
4138 this device, DeviceNotActive
4139 Since: 1.3
4141 block-job-complete (Command) Manually trigger completion of an active
4143 background block operation. This is supported for drive mirroring,
4144 where it also switches the device to write to the target path only.
4145 The ability to complete is signaled with a BLOCK_JOB_READY event.
4146 This command completes an active background block operation
4148 synchronously. The ordering of this command's return with the
4149 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
4150 occurs during the processing of this command: 1) the command itself
4151 will fail; 2) the error will be processed according to the
4152 rerror/werror arguments that were specified when starting the
4153 operation.
4154 A cancelled or paused job cannot be completed.
4156 Arguments:
4158 "device: string"
4160 The job identifier. This used to be a device name (hence the name
4161 of the parameter), but since QEMU 2.7 it can have other values.
4162 Returns: Nothing on success If no background operation is active on
4164 this device, DeviceNotActive
4165 Since: 1.3
4167 block-job-dismiss (Command) For jobs that have already concluded,
4169 remove them from the block-job-query list. This command only needs to
4170 be run for jobs which were started with QEMU 2.12+ job lifetime
4171 management semantics.
4172 This command will refuse to operate on any job that has not yet reached
4174 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
4175 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
4176 still need to be used as appropriate.
4177 Arguments:
4179 "id: string"
4181 The job identifier.
4182 Returns: Nothing on success
4184 Since: 2.12
4186 block-job-finalize (Command) Once a job that has manual=true reaches
4188 the pending state, it can be instructed to finalize any graph changes
4189 and do any necessary cleanup via this command. For jobs in a
4190 transaction, instructing one job to finalize will force ALL jobs in the
4191 transaction to finalize, so it is only necessary to instruct a single
4192 member job to finalize.
4193 Arguments:
4195 "id: string"
4197 The job identifier.
4198 Returns: Nothing on success
4200 Since: 2.12
4202 BlockdevDiscardOptions (Enum)
4204 Determines how to handle discard requests.
4206 Values:
4208 "ignore"
4210 Ignore the request
4211 "unmap"
4213 Forward as an unmap request
4214 Since: 2.9
4216 BlockdevDetectZeroesOptions (Enum)
4218 Describes the operation mode for the automatic conversion of plain zero
4220 writes by the OS to driver specific optimized zero write commands.
4221 Values:
4223 "off"
4225 Disabled (default)
4226 "on"
4228 Enabled
4229 "unmap"
4231 Enabled and even try to unmap blocks if possible. This requires
4232 also that "BlockdevDiscardOptions" is set to unmap for this device.
4233 Since: 2.1
4235 BlockdevAioOptions (Enum)
4237 Selects the AIO backend to handle I/O requests
4239 Values:
4241 "threads"
4243 Use qemu's thread pool
4244 "native"
4246 Use native AIO backend (only Linux and Windows)
4247 Since: 2.9
4249 BlockdevCacheOptions (Object)
4251 Includes cache-related options for block devices
4253 Members:
4255 "direct: boolean" (optional)
4257 enables use of O_DIRECT (bypass the host page cache; default:
4258 false)
4259 "no-flush: boolean" (optional)
4261 ignore any flush requests for the device (default: false)
4262 Since: 2.9
4264 BlockdevDriver (Enum)
4266 Drivers that are supported in block device operations.
4268 Values:
4270 "vxhs"
4272 Since 2.10
4273 "throttle"
4275 Since 2.11
4276 "nvme"
4278 Since 2.12
4279 "copy-on-read"
4281 Since 3.0
4282 "blklogwrites"
4284 Since 3.0
4285 "blkdebug"
4287 Not documented
4288 "blkverify"
4290 Not documented
4291 "bochs"
4293 Not documented
4294 "cloop"
4296 Not documented
4297 "dmg"
4299 Not documented
4300 "file"
4302 Not documented
4303 "ftp"
4305 Not documented
4306 "ftps"
4308 Not documented
4309 "gluster"
4311 Not documented
4312 "host_cdrom"
4314 Not documented
4315 "host_device"
4317 Not documented
4318 "http"
4320 Not documented
4321 "https"
4323 Not documented
4324 "iscsi"
4326 Not documented
4327 "luks"
4329 Not documented
4330 "nbd"
4332 Not documented
4333 "nfs"
4335 Not documented
4336 "null-aio"
4338 Not documented
4339 "null-co"
4341 Not documented
4342 "parallels"
4344 Not documented
4345 "qcow"
4347 Not documented
4348 "qcow2"
4350 Not documented
4351 "qed"
4353 Not documented
4354 "quorum"
4356 Not documented
4357 "raw"
4359 Not documented
4360 "rbd"
4362 Not documented
4363 "replication"
4365 Not documented If: "defined(CONFIG_REPLICATION)"
4366 "sheepdog"
4368 Not documented
4369 "ssh"
4371 Not documented
4372 "vdi"
4374 Not documented
4375 "vhdx"
4377 Not documented
4378 "vmdk"
4380 Not documented
4381 "vpc"
4383 Not documented
4384 "vvfat"
4386 Not documented
4387 Since: 2.9
4389 BlockdevOptionsFile (Object)
4391 Driver specific block device options for the file backend.
4393 Members:
4395 "filename: string"
4397 path to the image file
4398 "pr-manager: string" (optional)
4400 the id for the object that will handle persistent reservations for
4401 this device (default: none, forward the commands via SG_IO; since
4402 2.11)
4403 "aio: BlockdevAioOptions" (optional)
4405 AIO backend (default: threads) (since: 2.8)
4406 "locking: OnOffAuto" (optional)
4408 whether to enable file locking. If set to 'auto', only enable when
4409 Open File Descriptor (OFD) locking API is available (default: auto,
4410 since 2.10)
4411 "drop-cache: boolean" (optional)
4413 invalidate page cache during live migration. This prevents stale
4414 data on the migration destination with cache.direct=off. Currently
4415 only supported on Linux hosts. (default: on, since: 4.0) If:
4416 "defined(CONFIG_LINUX)"
4417 "x-check-cache-dropped: boolean" (optional)
4419 whether to check that page cache was dropped on live migration.
4420 May cause noticeable delays if the image file is large, do not use
4421 in production. (default: off) (since: 3.0)
4422 Features:
4424 "dynamic-auto-read-only"
4426 If present, enabled auto-read-only means that the driver will open
4427 the image read-only at first, dynamically reopen the image file
4428 read-write when the first writer is attached to the node and reopen
4429 read-only when the last writer is detached. This allows giving QEMU
4430 write permissions only on demand when an operation actually needs
4431 write access.
4432 Since: 2.9
4434 BlockdevOptionsNull (Object)
4436 Driver specific block device options for the null backend.
4438 Members:
4440 "size: int" (optional)
4442 size of the device in bytes.
4443 "latency-ns: int" (optional)
4445 emulated latency (in nanoseconds) in processing requests. Default
4446 to zero which completes requests immediately. (Since 2.4)
4447 "read-zeroes: boolean" (optional)
4449 if true, reads from the device produce zeroes; if false, the buffer
4450 is left unchanged. (default: false; since: 4.1)
4451 Since: 2.9
4453 BlockdevOptionsNVMe (Object)
4455 Driver specific block device options for the NVMe backend.
4457 Members:
4459 "device: string"
4461 controller address of the NVMe device.
4462 "namespace: int"
4464 namespace number of the device, starting from 1.
4465 Since: 2.12
4467 BlockdevOptionsVVFAT (Object)
4469 Driver specific block device options for the vvfat protocol.
4471 Members:
4473 "dir: string"
4475 directory to be exported as FAT image
4476 "fat-type: int" (optional)
4478 FAT type: 12, 16 or 32
4479 "floppy: boolean" (optional)
4481 whether to export a floppy image (true) or partitioned hard disk
4482 (false; default)
4483 "label: string" (optional)
4485 set the volume label, limited to 11 bytes. FAT16 and FAT32
4486 traditionally have some restrictions on labels, which are ignored
4487 by most operating systems. Defaults to "QEMU VVFAT". (since 2.4)
4488 "rw: boolean" (optional)
4490 whether to allow write operations (default: false)
4491 Since: 2.9
4493 BlockdevOptionsGenericFormat (Object)
4495 Driver specific block device options for image format that have no
4497 option besides their data source.
4498 Members:
4500 "file: BlockdevRef"
4502 reference to or definition of the data source block device
4503 Since: 2.9
4505 BlockdevOptionsLUKS (Object)
4507 Driver specific block device options for LUKS.
4509 Members:
4511 "key-secret: string" (optional)
4513 the ID of a QCryptoSecret object providing the decryption key
4514 (since 2.6). Mandatory except when doing a metadata-only probe of
4515 the image.
4516 The members of "BlockdevOptionsGenericFormat"
4518 Since: 2.9
4520 BlockdevOptionsGenericCOWFormat (Object)
4522 Driver specific block device options for image format that have no
4524 option besides their data source and an optional backing file.
4525 Members:
4527 "backing: BlockdevRefOrNull" (optional)
4529 reference to or definition of the backing file block device, null
4530 disables the backing file entirely. Defaults to the backing file
4531 stored the image file.
4532 The members of "BlockdevOptionsGenericFormat"
4534 Since: 2.9
4536 Qcow2OverlapCheckMode (Enum)
4538 General overlap check modes.
4540 Values:
4542 "none"
4544 Do not perform any checks
4545 "constant"
4547 Perform only checks which can be done in constant time and without
4548 reading anything from disk
4549 "cached"
4551 Perform only checks which can be done without reading anything from
4552 disk
4553 "all"
4555 Perform all available overlap checks
4556 Since: 2.9
4558 Qcow2OverlapCheckFlags (Object)
4560 Structure of flags for each metadata structure. Setting a field to
4562 'true' makes qemu guard that structure against unintended overwriting.
4563 The default value is chosen according to the template given.
4564 Members:
4566 "template: Qcow2OverlapCheckMode" (optional)
4568 Specifies a template mode which can be adjusted using the other
4569 flags, defaults to 'cached'
4570 "bitmap-directory: boolean" (optional)
4572 since 3.0
4573 "main-header: boolean" (optional)
4575 Not documented
4576 "active-l1: boolean" (optional)
4578 Not documented
4579 "active-l2: boolean" (optional)
4581 Not documented
4582 "refcount-table: boolean" (optional)
4584 Not documented
4585 "refcount-block: boolean" (optional)
4587 Not documented
4588 "snapshot-table: boolean" (optional)
4590 Not documented
4591 "inactive-l1: boolean" (optional)
4593 Not documented
4594 "inactive-l2: boolean" (optional)
4596 Not documented
4597 Since: 2.9
4599 Qcow2OverlapChecks (Alternate)
4601 Specifies which metadata structures should be guarded against
4603 unintended overwriting.
4604 Members:
4606 "flags: Qcow2OverlapCheckFlags"
4608 set of flags for separate specification of each metadata structure
4609 type
4610 "mode: Qcow2OverlapCheckMode"
4612 named mode which chooses a specific set of flags
4613 Since: 2.9
4615 BlockdevQcowEncryptionFormat (Enum)
4617 Values:
4619 "aes"
4621 AES-CBC with plain64 initialization vectors
4622 Since: 2.10
4624 BlockdevQcowEncryption (Object)
4626 Members:
4628 "format: BlockdevQcowEncryptionFormat"
4630 Not documented
4631 The members of "QCryptoBlockOptionsQCow" when "format" is "aes"
4633 Since: 2.10
4635 BlockdevOptionsQcow (Object)
4637 Driver specific block device options for qcow.
4639 Members:
4641 "encrypt: BlockdevQcowEncryption" (optional)
4643 Image decryption options. Mandatory for encrypted images, except
4644 when doing a metadata-only probe of the image.
4645 The members of "BlockdevOptionsGenericCOWFormat"
4647 Since: 2.10
4649 BlockdevQcow2EncryptionFormat (Enum)
4651 Values:
4653 "aes"
4655 AES-CBC with plain64 initialization vectors
4656 "luks"
4658 Not documented
4659 Since: 2.10
4661 BlockdevQcow2Encryption (Object)
4663 Members:
4665 "format: BlockdevQcow2EncryptionFormat"
4667 Not documented
4668 The members of "QCryptoBlockOptionsQCow" when "format" is "aes"
4670 The members of "QCryptoBlockOptionsLUKS" when "format" is "luks"
4671 Since: 2.10
4673 BlockdevOptionsQcow2 (Object)
4675 Driver specific block device options for qcow2.
4677 Members:
4679 "lazy-refcounts: boolean" (optional)
4681 whether to enable the lazy refcounts feature (default is taken from
4682 the image file)
4683 "pass-discard-request: boolean" (optional)
4685 whether discard requests to the qcow2 device should be forwarded to
4686 the data source
4687 "pass-discard-snapshot: boolean" (optional)
4689 whether discard requests for the data source should be issued when
4690 a snapshot operation (e.g. deleting a snapshot) frees clusters in
4691 the qcow2 file
4692 "pass-discard-other: boolean" (optional)
4694 whether discard requests for the data source should be issued on
4695 other occasions where a cluster gets freed
4696 "overlap-check: Qcow2OverlapChecks" (optional)
4698 which overlap checks to perform for writes to the image, defaults
4699 to 'cached' (since 2.2)
4700 "cache-size: int" (optional)
4702 the maximum total size of the L2 table and refcount block caches in
4703 bytes (since 2.2)
4704 "l2-cache-size: int" (optional)
4706 the maximum size of the L2 table cache in bytes (since 2.2)
4707 "l2-cache-entry-size: int" (optional)
4709 the size of each entry in the L2 cache in bytes. It must be a power
4710 of two between 512 and the cluster size. The default value is the
4711 cluster size (since 2.12)
4712 "refcount-cache-size: int" (optional)
4714 the maximum size of the refcount block cache in bytes (since 2.2)
4715 "cache-clean-interval: int" (optional)
4717 clean unused entries in the L2 and refcount caches. The interval is
4718 in seconds. The default value is 600 on supporting platforms, and 0
4719 on other platforms. 0 disables this feature. (since 2.5)
4720 "encrypt: BlockdevQcow2Encryption" (optional)
4722 Image decryption options. Mandatory for encrypted images, except
4723 when doing a metadata-only probe of the image. (since 2.10)
4724 "data-file: BlockdevRef" (optional)
4726 reference to or definition of the external data file. This may
4727 only be specified for images that require an external data file. If
4728 it is not specified for such an image, the data file name is loaded
4729 from the image file. (since 4.0)
4730 The members of "BlockdevOptionsGenericCOWFormat"
4732 Since: 2.9
4734 SshHostKeyCheckMode (Enum)
4736 "none" Don't check the host key at all "hash"
4738 Compare the host key with a given hash "known_hosts" Check the
4739 host key against the known_hosts file
4740 Values:
4742 "none"
4744 Not documented
4745 "hash"
4747 Not documented
4748 "known_hosts"
4750 Not documented
4751 Since: 2.12
4753 SshHostKeyCheckHashType (Enum)
4755 "md5" The given hash is an md5 hash "sha1" The
4757 given hash is an sha1 hash
4758 Values:
4760 "md5"
4762 Not documented
4763 "sha1"
4765 Not documented
4766 Since: 2.12
4768 SshHostKeyHash (Object)
4770 "type" The hash algorithm used for the hash "hash"
4772 The expected hash value
4773 Members:
4775 "type: SshHostKeyCheckHashType"
4777 Not documented
4778 "hash: string"
4780 Not documented
4781 Since: 2.12
4783 SshHostKeyCheck (Object)
4785 Members:
4787 "mode: SshHostKeyCheckMode"
4789 Not documented
4790 The members of "SshHostKeyHash" when "mode" is "hash"
4792 Since: 2.12
4794 BlockdevOptionsSsh (Object)
4796 Members:
4798 "server: InetSocketAddress"
4800 host address
4801 "path: string"
4803 path to the image on the host
4804 "user: string" (optional)
4806 user as which to connect, defaults to current local user name
4807 "host-key-check: SshHostKeyCheck" (optional)
4809 Defines how and what to check the host key against (default:
4810 known_hosts)
4811 Since: 2.9
4813 BlkdebugEvent (Enum)
4815 Trigger events supported by blkdebug.
4817 Values:
4819 "l1_shrink_write_table"
4821 write zeros to the l1 table to shrink image. (since 2.11)
4822 "l1_shrink_free_l2_clusters"
4824 discard the l2 tables. (since 2.11)
4825 "cor_write"
4827 a write due to copy-on-read (since 2.11)
4828 "cluster_alloc_space"
4830 an allocation of file space for a cluster (since 4.1)
4831 "none"
4833 triggers once at creation of the blkdebug node (since 4.1)
4834 "l1_update"
4836 Not documented
4837 "l1_grow_alloc_table"
4839 Not documented
4840 "l1_grow_write_table"
4842 Not documented
4843 "l1_grow_activate_table"
4845 Not documented
4846 "l2_load"
4848 Not documented
4849 "l2_update"
4851 Not documented
4852 "l2_update_compressed"
4854 Not documented
4855 "l2_alloc_cow_read"
4857 Not documented
4858 "l2_alloc_write"
4860 Not documented
4861 "read_aio"
4863 Not documented
4864 "read_backing_aio"
4866 Not documented
4867 "read_compressed"
4869 Not documented
4870 "write_aio"
4872 Not documented
4873 "write_compressed"
4875 Not documented
4876 "vmstate_load"
4878 Not documented
4879 "vmstate_save"
4881 Not documented
4882 "cow_read"
4884 Not documented
4885 "cow_write"
4887 Not documented
4888 "reftable_load"
4890 Not documented
4891 "reftable_grow"
4893 Not documented
4894 "reftable_update"
4896 Not documented
4897 "refblock_load"
4899 Not documented
4900 "refblock_update"
4902 Not documented
4903 "refblock_update_part"
4905 Not documented
4906 "refblock_alloc"
4908 Not documented
4909 "refblock_alloc_hookup"
4911 Not documented
4912 "refblock_alloc_write"
4914 Not documented
4915 "refblock_alloc_write_blocks"
4917 Not documented
4918 "refblock_alloc_write_table"
4920 Not documented
4921 "refblock_alloc_switch_table"
4923 Not documented
4924 "cluster_alloc"
4926 Not documented
4927 "cluster_alloc_bytes"
4929 Not documented
4930 "cluster_free"
4932 Not documented
4933 "flush_to_os"
4935 Not documented
4936 "flush_to_disk"
4938 Not documented
4939 "pwritev_rmw_head"
4941 Not documented
4942 "pwritev_rmw_after_head"
4944 Not documented
4945 "pwritev_rmw_tail"
4947 Not documented
4948 "pwritev_rmw_after_tail"
4950 Not documented
4951 "pwritev"
4953 Not documented
4954 "pwritev_zero"
4956 Not documented
4957 "pwritev_done"
4959 Not documented
4960 "empty_image_prepare"
4962 Not documented
4963 Since: 2.9
4965 BlkdebugIOType (Enum)
4967 Kinds of I/O that blkdebug can inject errors in.
4969 Values:
4971 "read"
4973 .bdrv_co_preadv()
4974 "write"
4976 .bdrv_co_pwritev()
4977 "write-zeroes"
4979 .bdrv_co_pwrite_zeroes()
4980 "discard"
4982 .bdrv_co_pdiscard()
4983 "flush"
4985 .bdrv_co_flush_to_disk()
4986 "block-status"
4988 .bdrv_co_block_status()
4989 Since: 4.1
4991 BlkdebugInjectErrorOptions (Object)
4993 Describes a single error injection for blkdebug.
4995 Members:
4997 "event: BlkdebugEvent"
4999 trigger event
5000 "state: int" (optional)
5002 the state identifier blkdebug needs to be in to actually trigger
5003 the event; defaults to "any"
5004 "iotype: BlkdebugIOType" (optional)
5006 the type of I/O operations on which this error should be injected;
5007 defaults to "all read, write, write-zeroes, discard, and flush
5008 operations" (since: 4.1)
5009 "errno: int" (optional)
5011 error identifier (errno) to be returned; defaults to EIO
5012 "sector: int" (optional)
5014 specifies the sector index which has to be affected in order to
5015 actually trigger the event; defaults to "any sector"
5016 "once: boolean" (optional)
5018 disables further events after this one has been triggered; defaults
5019 to false
5020 "immediately: boolean" (optional)
5022 fail immediately; defaults to false
5023 Since: 2.9
5025 BlkdebugSetStateOptions (Object)
5027 Describes a single state-change event for blkdebug.
5029 Members:
5031 "event: BlkdebugEvent"
5033 trigger event
5034 "state: int" (optional)
5036 the current state identifier blkdebug needs to be in; defaults to
5037 "any"
5038 "new_state: int"
5040 the state identifier blkdebug is supposed to assume if this event
5041 is triggered
5042 Since: 2.9
5044 BlockdevOptionsBlkdebug (Object)
5046 Driver specific block device options for blkdebug.
5048 Members:
5050 "image: BlockdevRef"
5052 underlying raw block device (or image file)
5053 "config: string" (optional)
5055 filename of the configuration file
5056 "align: int" (optional)
5058 required alignment for requests in bytes, must be positive power of
5059 2, or 0 for default
5060 "max-transfer: int" (optional)
5062 maximum size for I/O transfers in bytes, must be positive multiple
5063 of "align" and of the underlying file's request alignment (but need
5064 not be a power of 2), or 0 for default (since 2.10)
5065 "opt-write-zero: int" (optional)
5067 preferred alignment for write zero requests in bytes, must be
5068 positive multiple of "align" and of the underlying file's request
5069 alignment (but need not be a power of 2), or 0 for default (since
5070 2.10)
5071 "max-write-zero: int" (optional)
5073 maximum size for write zero requests in bytes, must be positive
5074 multiple of "align", of "opt-write-zero", and of the underlying
5075 file's request alignment (but need not be a power of 2), or 0 for
5076 default (since 2.10)
5077 "opt-discard: int" (optional)
5079 preferred alignment for discard requests in bytes, must be positive
5080 multiple of "align" and of the underlying file's request alignment
5081 (but need not be a power of 2), or 0 for default (since 2.10)
5082 "max-discard: int" (optional)
5084 maximum size for discard requests in bytes, must be positive
5085 multiple of "align", of "opt-discard", and of the underlying file's
5086 request alignment (but need not be a power of 2), or 0 for default
5087 (since 2.10)
5088 "inject-error: array of BlkdebugInjectErrorOptions" (optional)
5090 array of error injection descriptions
5091 "set-state: array of BlkdebugSetStateOptions" (optional)
5093 array of state-change descriptions
5094 Since: 2.9
5096 BlockdevOptionsBlklogwrites (Object)
5098 Driver specific block device options for blklogwrites.
5100 Members:
5102 "file: BlockdevRef"
5104 block device
5105 "log: BlockdevRef"
5107 block device used to log writes to "file"
5108 "log-sector-size: int" (optional)
5110 sector size used in logging writes to "file", determines
5111 granularity of offsets and sizes of writes (default: 512)
5112 "log-append: boolean" (optional)
5114 append to an existing log (default: false)
5115 "log-super-update-interval: int" (optional)
5117 interval of write requests after which the log super block is
5118 updated to disk (default: 4096)
5119 Since: 3.0
5121 BlockdevOptionsBlkverify (Object)
5123 Driver specific block device options for blkverify.
5125 Members:
5127 "test: BlockdevRef"
5129 block device to be tested
5130 "raw: BlockdevRef"
5132 raw image used for verification
5133 Since: 2.9
5135 QuorumReadPattern (Enum)
5137 An enumeration of quorum read patterns.
5139 Values:
5141 "quorum"
5143 read all the children and do a quorum vote on reads
5144 "fifo"
5146 read only from the first child that has not failed
5147 Since: 2.9
5149 BlockdevOptionsQuorum (Object)
5151 Driver specific block device options for Quorum
5153 Members:
5155 "blkverify: boolean" (optional)
5157 true if the driver must print content mismatch set to false by
5158 default
5159 "children: array of BlockdevRef"
5161 the children block devices to use
5162 "vote-threshold: int"
5164 the vote limit under which a read will fail
5165 "rewrite-corrupted: boolean" (optional)
5167 rewrite corrupted data when quorum is reached (Since 2.1)
5168 "read-pattern: QuorumReadPattern" (optional)
5170 choose read pattern and set to quorum by default (Since 2.2)
5171 Since: 2.9
5173 BlockdevOptionsGluster (Object)
5175 Driver specific block device options for Gluster
5177 Members:
5179 "volume: string"
5181 name of gluster volume where VM image resides
5182 "path: string"
5184 absolute path to image file in gluster volume
5185 "server: array of SocketAddress"
5187 gluster servers description
5188 "debug: int" (optional)
5190 libgfapi log level (default '4' which is Error) (Since 2.8)
5191 "logfile: string" (optional)
5193 libgfapi log file (default /dev/stderr) (Since 2.8)
5194 Since: 2.9
5196 IscsiTransport (Enum)
5198 An enumeration of libiscsi transport types
5200 Values:
5202 "tcp"
5204 Not documented
5205 "iser"
5207 Not documented
5208 Since: 2.9
5210 IscsiHeaderDigest (Enum)
5212 An enumeration of header digests supported by libiscsi
5214 Values:
5216 "crc32c"
5218 Not documented
5219 "none"
5221 Not documented
5222 "crc32c-none"
5224 Not documented
5225 "none-crc32c"
5227 Not documented
5228 Since: 2.9
5230 BlockdevOptionsIscsi (Object)
5232 Members:
5234 "transport: IscsiTransport"
5236 The iscsi transport type
5237 "portal: string"
5239 The address of the iscsi portal
5240 "target: string"
5242 The target iqn name
5243 "lun: int" (optional)
5245 LUN to connect to. Defaults to 0.
5246 "user: string" (optional)
5248 User name to log in with. If omitted, no CHAP authentication is
5249 performed.
5250 "password-secret: string" (optional)
5252 The ID of a QCryptoSecret object providing the password for the
5253 login. This option is required if "user" is specified.
5254 "initiator-name: string" (optional)
5256 The iqn name we want to identify to the target as. If this option
5257 is not specified, an initiator name is generated automatically.
5258 "header-digest: IscsiHeaderDigest" (optional)
5260 The desired header digest. Defaults to none-crc32c.
5261 "timeout: int" (optional)
5263 Timeout in seconds after which a request will timeout. 0 means no
5264 timeout and is the default.
5265 Driver specific block device options for iscsi
5267 Since: 2.9
5269 RbdAuthMode (Enum)
5271 Values:
5273 "cephx"
5275 Not documented
5276 "none"
5278 Not documented
5279 Since: 3.0
5281 BlockdevOptionsRbd (Object)
5283 Members:
5285 "pool: string"
5287 Ceph pool name.
5288 "image: string"
5290 Image name in the Ceph pool.
5291 "conf: string" (optional)
5293 path to Ceph configuration file. Values in the configuration file
5294 will be overridden by options specified via QAPI.
5295 "snapshot: string" (optional)
5297 Ceph snapshot name.
5298 "user: string" (optional)
5300 Ceph id name.
5301 "auth-client-required: array of RbdAuthMode" (optional)
5303 Acceptable authentication modes. This maps to Ceph configuration
5304 option "auth_client_required". (Since 3.0)
5305 "key-secret: string" (optional)
5307 ID of a QCryptoSecret object providing a key for cephx
5308 authentication. This maps to Ceph configuration option "key".
5309 (Since 3.0)
5310 "server: array of InetSocketAddressBase" (optional)
5312 Monitor host address and port. This maps to the "mon_host" Ceph
5313 option.
5314 Since: 2.9
5316 BlockdevOptionsSheepdog (Object)
5318 Driver specific block device options for sheepdog
5320 Members:
5322 "vdi: string"
5324 Virtual disk image name
5325 "server: SocketAddress"
5327 The Sheepdog server to connect to
5328 "snap-id: int" (optional)
5330 Snapshot ID
5331 "tag: string" (optional)
5333 Snapshot tag name
5334 Only one of "snap-id" and "tag" may be present.
5336 Since: 2.9
5338 ReplicationMode (Enum)
5340 An enumeration of replication modes.
5342 Values:
5344 "primary"
5346 Primary mode, the vm's state will be sent to secondary QEMU.
5347 "secondary"
5349 Secondary mode, receive the vm's state from primary QEMU.
5350 Since: 2.9
5352 If: "defined(CONFIG_REPLICATION)"
5354 BlockdevOptionsReplication (Object)
5356 Driver specific block device options for replication
5358 Members:
5360 "mode: ReplicationMode"
5362 the replication mode
5363 "top-id: string" (optional)
5365 In secondary mode, node name or device ID of the root node who owns
5366 the replication node chain. Must not be given in primary mode.
5367 The members of "BlockdevOptionsGenericFormat"
5369 Since: 2.9
5371 If: "defined(CONFIG_REPLICATION)"
5373 NFSTransport (Enum)
5375 An enumeration of NFS transport types
5377 Values:
5379 "inet"
5381 TCP transport
5382 Since: 2.9
5384 NFSServer (Object)
5386 Captures the address of the socket
5388 Members:
5390 "type: NFSTransport"
5392 transport type used for NFS (only TCP supported)
5393 "host: string"
5395 host address for NFS server
5396 Since: 2.9
5398 BlockdevOptionsNfs (Object)
5400 Driver specific block device option for NFS
5402 Members:
5404 "server: NFSServer"
5406 host address
5407 "path: string"
5409 path of the image on the host
5410 "user: int" (optional)
5412 UID value to use when talking to the server (defaults to 65534 on
5413 Windows and getuid() on unix)
5414 "group: int" (optional)
5416 GID value to use when talking to the server (defaults to 65534 on
5417 Windows and getgid() in unix)
5418 "tcp-syn-count: int" (optional)
5420 number of SYNs during the session establishment (defaults to libnfs
5421 default)
5422 "readahead-size: int" (optional)
5424 set the readahead size in bytes (defaults to libnfs default)
5425 "page-cache-size: int" (optional)
5427 set the pagecache size in bytes (defaults to libnfs default)
5428 "debug: int" (optional)
5430 set the NFS debug level (max 2) (defaults to libnfs default)
5431 Since: 2.9
5433 BlockdevOptionsCurlBase (Object)
5435 Driver specific block device options shared by all protocols supported
5437 by the curl backend.
5438 Members:
5440 "url: string"
5442 URL of the image file
5443 "readahead: int" (optional)
5445 Size of the read-ahead cache; must be a multiple of 512 (defaults
5446 to 256 kB)
5447 "timeout: int" (optional)
5449 Timeout for connections, in seconds (defaults to 5)
5450 "username: string" (optional)
5452 Username for authentication (defaults to none)
5453 "password-secret: string" (optional)
5455 ID of a QCryptoSecret object providing a password for
5456 authentication (defaults to no password)
5457 "proxy-username: string" (optional)
5459 Username for proxy authentication (defaults to none)
5460 "proxy-password-secret: string" (optional)
5462 ID of a QCryptoSecret object providing a password for proxy
5463 authentication (defaults to no password)
5464 Since: 2.9
5466 BlockdevOptionsCurlHttp (Object)
5468 Driver specific block device options for HTTP connections over the curl
5470 backend. URLs must start with "http://".
5471 Members:
5473 "cookie: string" (optional)
5475 List of cookies to set; format is "name1=content1; name2=content2;"
5476 as explained by CURLOPT_COOKIE(3). Defaults to no cookies.
5477 "cookie-secret: string" (optional)
5479 ID of a QCryptoSecret object providing the cookie data in a secure
5480 way. See "cookie" for the format. (since 2.10)
5481 The members of "BlockdevOptionsCurlBase"
5483 Since: 2.9
5485 BlockdevOptionsCurlHttps (Object)
5487 Driver specific block device options for HTTPS connections over the
5489 curl backend. URLs must start with "https://".
5490 Members:
5492 "cookie: string" (optional)
5494 List of cookies to set; format is "name1=content1; name2=content2;"
5495 as explained by CURLOPT_COOKIE(3). Defaults to no cookies.
5496 "sslverify: boolean" (optional)
5498 Whether to verify the SSL certificate's validity (defaults to true)
5499 "cookie-secret: string" (optional)
5501 ID of a QCryptoSecret object providing the cookie data in a secure
5502 way. See "cookie" for the format. (since 2.10)
5503 The members of "BlockdevOptionsCurlBase"
5505 Since: 2.9
5507 BlockdevOptionsCurlFtp (Object)
5509 Driver specific block device options for FTP connections over the curl
5511 backend. URLs must start with "ftp://".
5512 Members:
5514 The members of "BlockdevOptionsCurlBase"
5516 Since: 2.9
5518 BlockdevOptionsCurlFtps (Object)
5520 Driver specific block device options for FTPS connections over the curl
5522 backend. URLs must start with "ftps://".
5523 Members:
5525 "sslverify: boolean" (optional)
5527 Whether to verify the SSL certificate's validity (defaults to true)
5528 The members of "BlockdevOptionsCurlBase"
5530 Since: 2.9
5532 BlockdevOptionsNbd (Object)
5534 Driver specific block device options for NBD.
5536 Members:
5538 "server: SocketAddress"
5540 NBD server address
5541 "export: string" (optional)
5543 export name
5544 "tls-creds: string" (optional)
5546 TLS credentials ID
5547 "x-dirty-bitmap: string" (optional)
5549 A "qemu:dirty-bitmap:NAME" string to query in place of traditional
5550 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
5551 the NBD protocol) (since 3.0)
5552 Since: 2.9
5554 BlockdevOptionsRaw (Object)
5556 Driver specific block device options for the raw driver.
5558 Members:
5560 "offset: int" (optional)
5562 position where the block device starts
5563 "size: int" (optional)
5565 the assumed size of the device
5566 The members of "BlockdevOptionsGenericFormat"
5568 Since: 2.9
5570 BlockdevOptionsVxHS (Object)
5572 Driver specific block device options for VxHS
5574 Members:
5576 "vdisk-id: string"
5578 UUID of VxHS volume
5579 "server: InetSocketAddressBase"
5581 vxhs server IP, port
5582 "tls-creds: string" (optional)
5584 TLS credentials ID
5585 Since: 2.10
5587 BlockdevOptionsThrottle (Object)
5589 Driver specific block device options for the throttle driver
5591 Members:
5593 "throttle-group: string"
5595 the name of the throttle-group object to use. It must already
5596 exist.
5597 "file: BlockdevRef"
5599 reference to or definition of the data source block device
5600 Since: 2.11
5602 BlockdevOptions (Object)
5604 Options for creating a block device. Many options are available for
5606 all block devices, independent of the block driver:
5607 Members:
5609 "driver: BlockdevDriver"
5611 block driver name
5612 "node-name: string" (optional)
5614 the node name of the new node (Since 2.0). This option is required
5615 on the top level of blockdev-add. Valid node names start with an
5616 alphabetic character and may contain only alphanumeric characters,
5617 '-', '.' and '_'. Their maximum length is 31 characters.
5618 "discard: BlockdevDiscardOptions" (optional)
5620 discard-related options (default: ignore)
5621 "cache: BlockdevCacheOptions" (optional)
5623 cache-related options
5624 "read-only: boolean" (optional)
5626 whether the block device should be read-only (default: false).
5627 Note that some block drivers support only read-only access, either
5628 generally or in certain configurations. In this case, the default
5629 value does not work and the option must be specified explicitly.
5630 "auto-read-only: boolean" (optional)
5632 if true and "read-only" is false, QEMU may automatically decide not
5633 to open the image read-write as requested, but fall back to read-
5634 only instead (and switch between the modes later), e.g. depending
5635 on whether the image file is writable or whether a writing user is
5636 attached to the node (default: false, since 3.1)
5637 "detect-zeroes: BlockdevDetectZeroesOptions" (optional)
5639 detect and optimize zero writes (Since 2.1) (default: off)
5640 "force-share: boolean" (optional)
5642 force share all permission on added nodes. Requires
5643 read-only=true. (Since 2.10)
5644 The members of "BlockdevOptionsBlkdebug" when "driver" is "blkdebug"
5646 The members of "BlockdevOptionsBlklogwrites" when "driver" is
5647 "blklogwrites"
5648 The members of "BlockdevOptionsBlkverify" when "driver" is "blkverify"
5649 The members of "BlockdevOptionsGenericFormat" when "driver" is "bochs"
5650 The members of "BlockdevOptionsGenericFormat" when "driver" is "cloop"
5651 The members of "BlockdevOptionsGenericFormat" when "driver" is "copy-
5652 on-read"
5653 The members of "BlockdevOptionsGenericFormat" when "driver" is "dmg"
5654 The members of "BlockdevOptionsFile" when "driver" is "file"
5655 The members of "BlockdevOptionsCurlFtp" when "driver" is "ftp"
5656 The members of "BlockdevOptionsCurlFtps" when "driver" is "ftps"
5657 The members of "BlockdevOptionsGluster" when "driver" is "gluster"
5658 The members of "BlockdevOptionsFile" when "driver" is "host_cdrom"
5659 The members of "BlockdevOptionsFile" when "driver" is "host_device"
5660 The members of "BlockdevOptionsCurlHttp" when "driver" is "http"
5661 The members of "BlockdevOptionsCurlHttps" when "driver" is "https"
5662 The members of "BlockdevOptionsIscsi" when "driver" is "iscsi"
5663 The members of "BlockdevOptionsLUKS" when "driver" is "luks"
5664 The members of "BlockdevOptionsNbd" when "driver" is "nbd"
5665 The members of "BlockdevOptionsNfs" when "driver" is "nfs"
5666 The members of "BlockdevOptionsNull" when "driver" is "null-aio"
5667 The members of "BlockdevOptionsNull" when "driver" is "null-co"
5668 The members of "BlockdevOptionsNVMe" when "driver" is "nvme"
5669 The members of "BlockdevOptionsGenericFormat" when "driver" is
5670 "parallels"
5671 The members of "BlockdevOptionsQcow2" when "driver" is "qcow2"
5672 The members of "BlockdevOptionsQcow" when "driver" is "qcow"
5673 The members of "BlockdevOptionsGenericCOWFormat" when "driver" is "qed"
5674 The members of "BlockdevOptionsQuorum" when "driver" is "quorum"
5675 The members of "BlockdevOptionsRaw" when "driver" is "raw"
5676 The members of "BlockdevOptionsRbd" when "driver" is "rbd"
5677 The members of "BlockdevOptionsReplication" when "driver" is
5678 "replication" (If: "defined(CONFIG_REPLICATION)")
5679 The members of "BlockdevOptionsSheepdog" when "driver" is "sheepdog"
5680 The members of "BlockdevOptionsSsh" when "driver" is "ssh"
5681 The members of "BlockdevOptionsThrottle" when "driver" is "throttle"
5682 The members of "BlockdevOptionsGenericFormat" when "driver" is "vdi"
5683 The members of "BlockdevOptionsGenericFormat" when "driver" is "vhdx"
5684 The members of "BlockdevOptionsGenericCOWFormat" when "driver" is
5685 "vmdk"
5686 The members of "BlockdevOptionsGenericFormat" when "driver" is "vpc"
5687 The members of "BlockdevOptionsVVFAT" when "driver" is "vvfat"
5688 The members of "BlockdevOptionsVxHS" when "driver" is "vxhs"
5689 Remaining options are determined by the block driver.
5691 Since: 2.9
5693 BlockdevRef (Alternate)
5695 Reference to a block device.
5697 Members:
5699 "definition: BlockdevOptions"
5701 defines a new block device inline
5702 "reference: string"
5704 references the ID of an existing block device
5705 Since: 2.9
5707 BlockdevRefOrNull (Alternate)
5709 Reference to a block device.
5711 Members:
5713 "definition: BlockdevOptions"
5715 defines a new block device inline
5716 "reference: string"
5718 references the ID of an existing block device. An empty string
5719 means that no block device should be referenced. Deprecated; use
5720 null instead.
5721 "null: null"
5723 No block device should be referenced (since 2.10)
5724 Since: 2.9
5726 blockdev-add (Command) Creates a new block device. If the "id" option
5728 is given at the top level, a BlockBackend will be created; otherwise,
5729 "node-name" is mandatory at the top level and no BlockBackend will be
5730 created.
5731 Arguments: the members of "BlockdevOptions"
5733 Since: 2.9
5735 Example:
5737 1.
5739 -> { "execute": "blockdev-add",
5740 "arguments": {
5741 "driver": "qcow2",
5742 "node-name": "test1",
5743 "file": {
5744 "driver": "file",
5745 "filename": "test.qcow2"
5746 }
5747 }
5748 }
5749 <- { "return": {} }
5750 2.
5752 -> { "execute": "blockdev-add",
5753 "arguments": {
5754 "driver": "qcow2",
5755 "node-name": "node0",
5756 "discard": "unmap",
5757 "cache": {
5758 "direct": true
5759 },
5760 "file": {
5761 "driver": "file",
5762 "filename": "/tmp/test.qcow2"
5763 },
5764 "backing": {
5765 "driver": "raw",
5766 "file": {
5767 "driver": "file",
5768 "filename": "/dev/fdset/4"
5769 }
5770 }
5771 }
5772 }
5773 <- { "return": {} }
5775 x-blockdev-reopen (Command) Reopens a block device using the given set
5777 of options. Any option not specified will be reset to its default value
5778 regardless of its previous status. If an option cannot be changed or a
5779 particular driver does not support reopening then the command will
5780 return an error.
5781 The top-level "node-name" option (from BlockdevOptions) must be
5783 specified and is used to select the block device to be reopened. Other
5784 "node-name" options must be either omitted or set to the current name
5785 of the appropriate node. This command won't change any node name and
5786 any attempt to do it will result in an error.
5787 In the case of options that refer to child nodes, the behavior of this
5789 command depends on the value:
5790 1) A set of options (BlockdevOptions): the child is reopened with the
5792 specified set of options.
5793 2) A reference to the current child: the child is reopened using its
5795 existing set of options.
5796 3) A reference to a different node: the current child is replaced with
5798 the specified one.
5799 4) NULL: the current child (if any) is detached.
5801 Options (1) and (2) are supported in all cases, but at the moment only
5803 "backing" allows replacing or detaching an existing child.
5804 Unlike with blockdev-add, the "backing" option must always be present
5806 unless the node being reopened does not have a backing file and its
5807 image does not have a default backing file name as part of its
5808 metadata.
5809 Arguments: the members of "BlockdevOptions"
5811 Since: 4.0
5813 blockdev-del (Command) Deletes a block device that has been added
5815 using blockdev-add. The command will fail if the node is attached to a
5816 device or is otherwise being used.
5817 Arguments:
5819 "node-name: string"
5821 Name of the graph node to delete.
5822 Since: 2.9
5824 Example:
5826 -> { "execute": "blockdev-add",
5828 "arguments": {
5829 "driver": "qcow2",
5830 "node-name": "node0",
5831 "file": {
5832 "driver": "file",
5833 "filename": "test.qcow2"
5834 }
5835 }
5836 }
5837 <- { "return": {} }
5838 -> { "execute": "blockdev-del",
5840 "arguments": { "node-name": "node0" }
5841 }
5842 <- { "return": {} }
5843 BlockdevCreateOptionsFile (Object)
5845 Driver specific image creation options for file.
5847 "filename" Filename for the new image file "size"
5849 Size of the virtual disk in bytes "preallocation" Preallocation mode
5850 for the new image (default: off; allowed values: off, falloc (if
5851 defined CONFIG_POSIX_FALLOCATE), full (if defined CONFIG_POSIX))
5852 "nocow" Turn off copy-on-write (valid only on btrfs;
5853 default: off)
5854 Members:
5856 "filename: string"
5858 Not documented
5859 "size: int"
5861 Not documented
5862 "preallocation: PreallocMode" (optional)
5864 Not documented
5865 "nocow: boolean" (optional)
5867 Not documented
5868 Since: 2.12
5870 BlockdevCreateOptionsGluster (Object)
5872 Driver specific image creation options for gluster.
5874 "location" Where to store the new image file "size"
5876 Size of the virtual disk in bytes "preallocation" Preallocation mode
5877 for the new image (default: off; allowed values: off, falloc (if
5878 defined CONFIG_GLUSTERFS_FALLOCATE), full (if defined
5879 CONFIG_GLUSTERFS_ZEROFILL))
5880 Members:
5882 "location: BlockdevOptionsGluster"
5884 Not documented
5885 "size: int"
5887 Not documented
5888 "preallocation: PreallocMode" (optional)
5890 Not documented
5891 Since: 2.12
5893 BlockdevCreateOptionsLUKS (Object)
5895 Driver specific image creation options for LUKS.
5897 "file" Node to create the image format on "size"
5899 Size of the virtual disk in bytes
5900 Members:
5902 "file: BlockdevRef"
5904 Not documented
5905 "size: int"
5907 Not documented
5908 The members of "QCryptoBlockCreateOptionsLUKS"
5910 Since: 2.12
5912 BlockdevCreateOptionsNfs (Object)
5914 Driver specific image creation options for NFS.
5916 "location" Where to store the new image file "size"
5918 Size of the virtual disk in bytes
5919 Members:
5921 "location: BlockdevOptionsNfs"
5923 Not documented
5924 "size: int"
5926 Not documented
5927 Since: 2.12
5929 BlockdevCreateOptionsParallels (Object)
5931 Driver specific image creation options for parallels.
5933 "file" Node to create the image format on "size"
5935 Size of the virtual disk in bytes "cluster-size" Cluster size in
5936 bytes (default: 1 MB)
5937 Members:
5939 "file: BlockdevRef"
5941 Not documented
5942 "size: int"
5944 Not documented
5945 "cluster-size: int" (optional)
5947 Not documented
5948 Since: 2.12
5950 BlockdevCreateOptionsQcow (Object)
5952 Driver specific image creation options for qcow.
5954 "file" Node to create the image format on "size"
5956 Size of the virtual disk in bytes "backing-file" File name of the
5957 backing file if a backing file should be used "encrypt"
5958 Encryption options if the image should be encrypted
5959 Members:
5961 "file: BlockdevRef"
5963 Not documented
5964 "size: int"
5966 Not documented
5967 "backing-file: string" (optional)
5969 Not documented
5970 "encrypt: QCryptoBlockCreateOptions" (optional)
5972 Not documented
5973 Since: 2.12
5975 BlockdevQcow2Version (Enum)
5977 Values:
5979 "v2"
5981 The original QCOW2 format as introduced in qemu 0.10 (version 2)
5982 "v3"
5984 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
5985 Since: 2.12
5987 BlockdevCreateOptionsQcow2 (Object)
5989 Driver specific image creation options for qcow2.
5991 "file" Node to create the image format on "data-file"
5993 Node to use as an external data file in which all guest data is stored
5994 so that only metadata remains in the qcow2 file (since: 4.0)
5995 "data-file-raw" True if the external data file must stay valid as a
5996 standalone (read-only) raw image without looking at qcow2 metadata
5997 (default: false; since: 4.0) "size" Size of the virtual
5998 disk in bytes "version" Compatibility level (default: v3)
5999 "backing-file" File name of the backing file if a backing file
6000 should be used "backing-fmt" Name of the block driver to use for
6001 the backing file "encrypt" Encryption options if the image
6002 should be encrypted "cluster-size" qcow2 cluster size in bytes
6003 (default: 65536) "preallocation" Preallocation mode for the new
6004 image (default: off; allowed values: off, falloc, full, metadata)
6005 "lazy-refcounts" True if refcounts may be updated lazily (default:
6006 off) "refcount-bits" Width of reference counts in bits (default: 16)
6007 Members:
6009 "file: BlockdevRef"
6011 Not documented
6012 "data-file: BlockdevRef" (optional)
6014 Not documented
6015 "data-file-raw: boolean" (optional)
6017 Not documented
6018 "size: int"
6020 Not documented
6021 "version: BlockdevQcow2Version" (optional)
6023 Not documented
6024 "backing-file: string" (optional)
6026 Not documented
6027 "backing-fmt: BlockdevDriver" (optional)
6029 Not documented
6030 "encrypt: QCryptoBlockCreateOptions" (optional)
6032 Not documented
6033 "cluster-size: int" (optional)
6035 Not documented
6036 "preallocation: PreallocMode" (optional)
6038 Not documented
6039 "lazy-refcounts: boolean" (optional)
6041 Not documented
6042 "refcount-bits: int" (optional)
6044 Not documented
6045 Since: 2.12
6047 BlockdevCreateOptionsQed (Object)
6049 Driver specific image creation options for qed.
6051 "file" Node to create the image format on "size"
6053 Size of the virtual disk in bytes "backing-file" File name of the
6054 backing file if a backing file should be used "backing-fmt" Name
6055 of the block driver to use for the backing file "cluster-size"
6056 Cluster size in bytes (default: 65536) "table-size" L1/L2 table
6057 size (in clusters)
6058 Members:
6060 "file: BlockdevRef"
6062 Not documented
6063 "size: int"
6065 Not documented
6066 "backing-file: string" (optional)
6068 Not documented
6069 "backing-fmt: BlockdevDriver" (optional)
6071 Not documented
6072 "cluster-size: int" (optional)
6074 Not documented
6075 "table-size: int" (optional)
6077 Not documented
6078 Since: 2.12
6080 BlockdevCreateOptionsRbd (Object)
6082 Driver specific image creation options for rbd/Ceph.
6084 "location" Where to store the new image file. This location
6086 cannot point to a snapshot. "size" Size of the virtual
6087 disk in bytes "cluster-size" RBD object size
6088 Members:
6090 "location: BlockdevOptionsRbd"
6092 Not documented
6093 "size: int"
6095 Not documented
6096 "cluster-size: int" (optional)
6098 Not documented
6099 Since: 2.12
6101 BlockdevVmdkSubformat (Enum)
6103 Subformat options for VMDK images
6105 Values:
6107 "monolithicSparse"
6109 Single file image with sparse cluster allocation
6110 "monolithicFlat"
6112 Single flat data image and a descriptor file
6113 "twoGbMaxExtentSparse"
6115 Data is split into 2GB (per virtual LBA) sparse extent files, in
6116 addition to a descriptor file
6117 "twoGbMaxExtentFlat"
6119 Data is split into 2GB (per virtual LBA) flat extent files, in
6120 addition to a descriptor file
6121 "streamOptimized"
6123 Single file image sparse cluster allocation, optimized for
6124 streaming over network.
6125 Since: 4.0
6127 BlockdevVmdkAdapterType (Enum)
6129 Adapter type info for VMDK images
6131 Values:
6133 "ide"
6135 Not documented
6136 "buslogic"
6138 Not documented
6139 "lsilogic"
6141 Not documented
6142 "legacyESX"
6144 Not documented
6145 Since: 4.0
6147 BlockdevCreateOptionsVmdk (Object)
6149 Driver specific image creation options for VMDK.
6151 "file" Where to store the new image file. This refers to the
6153 image file for monolithcSparse and streamOptimized format, or the
6154 descriptor file for other formats. "size" Size of the virtual
6155 disk in bytes "extents" Where to store the data extents. Required
6156 for monolithcFlat, twoGbMaxExtentSparse and twoGbMaxExtentFlat formats.
6157 For monolithicFlat, only one entry is required; for twoGbMaxExtent*
6158 formats, the number of entries required is calculated as extent_number
6159 = virtual_size / 2GB. Providing more extents than will be used is an
6160 error. "subformat" The subformat of the VMDK image. Default:
6161 "monolithicSparse". "backing-file" The path of backing file. Default:
6162 no backing file is used. "adapter-type" The adapter type used to fill
6163 in the descriptor. Default: ide. "hwversion" Hardware version. The
6164 meaningful options are "4" or "6". Default: "4". "zeroed-grain"
6165 Whether to enable zeroed-grain feature for sparse subformats. Default:
6166 false.
6167 Members:
6169 "file: BlockdevRef"
6171 Not documented
6172 "size: int"
6174 Not documented
6175 "extents: array of BlockdevRef" (optional)
6177 Not documented
6178 "subformat: BlockdevVmdkSubformat" (optional)
6180 Not documented
6181 "backing-file: string" (optional)
6183 Not documented
6184 "adapter-type: BlockdevVmdkAdapterType" (optional)
6186 Not documented
6187 "hwversion: string" (optional)
6189 Not documented
6190 "zeroed-grain: boolean" (optional)
6192 Not documented
6193 Since: 4.0
6195 SheepdogRedundancyType (Enum)
6197 "full" Create a fully replicated vdi with x copies
6199 "erasure-coded" Create an erasure coded vdi with x data strips and y
6200 parity strips
6201 Values:
6203 "full"
6205 Not documented
6206 "erasure-coded"
6208 Not documented
6209 Since: 2.12
6211 SheepdogRedundancyFull (Object)
6213 "copies" Number of copies to use (between 1 and 31)
6215 Members:
6217 "copies: int"
6219 Not documented
6220 Since: 2.12
6222 SheepdogRedundancyErasureCoded (Object)
6224 "data-strips" Number of data strips to use (one of {2,4,8,16})
6226 "parity-strips" Number of parity strips to use (between 1 and 15)
6227 Members:
6229 "data-strips: int"
6231 Not documented
6232 "parity-strips: int"
6234 Not documented
6235 Since: 2.12
6237 SheepdogRedundancy (Object)
6239 Members:
6241 "type: SheepdogRedundancyType"
6243 Not documented
6244 The members of "SheepdogRedundancyFull" when "type" is "full"
6246 The members of "SheepdogRedundancyErasureCoded" when "type" is
6247 "erasure-coded"
6248 Since: 2.12
6250 BlockdevCreateOptionsSheepdog (Object)
6252 Driver specific image creation options for Sheepdog.
6254 "location" Where to store the new image file "size"
6256 Size of the virtual disk in bytes "backing-file" File name of a
6257 base image "preallocation" Preallocation mode for the new image
6258 (default: off; allowed values: off, full) "redundancy" Redundancy
6259 of the image "object-size" Object size of the image
6260 Members:
6262 "location: BlockdevOptionsSheepdog"
6264 Not documented
6265 "size: int"
6267 Not documented
6268 "backing-file: string" (optional)
6270 Not documented
6271 "preallocation: PreallocMode" (optional)
6273 Not documented
6274 "redundancy: SheepdogRedundancy" (optional)
6276 Not documented
6277 "object-size: int" (optional)
6279 Not documented
6280 Since: 2.12
6282 BlockdevCreateOptionsSsh (Object)
6284 Driver specific image creation options for SSH.
6286 "location" Where to store the new image file "size"
6288 Size of the virtual disk in bytes
6289 Members:
6291 "location: BlockdevOptionsSsh"
6293 Not documented
6294 "size: int"
6296 Not documented
6297 Since: 2.12
6299 BlockdevCreateOptionsVdi (Object)
6301 Driver specific image creation options for VDI.
6303 "file" Node to create the image format on "size"
6305 Size of the virtual disk in bytes "preallocation" Preallocation mode
6306 for the new image (default: off; allowed values: off, metadata)
6307 Members:
6309 "file: BlockdevRef"
6311 Not documented
6312 "size: int"
6314 Not documented
6315 "preallocation: PreallocMode" (optional)
6317 Not documented
6318 Since: 2.12
6320 BlockdevVhdxSubformat (Enum)
6322 Values:
6324 "dynamic"
6326 Growing image file
6327 "fixed"
6329 Preallocated fixed-size image file
6330 Since: 2.12
6332 BlockdevCreateOptionsVhdx (Object)
6334 Driver specific image creation options for vhdx.
6336 "file" Node to create the image format on "size"
6338 Size of the virtual disk in bytes "log-size" Log size in bytes,
6339 must be a multiple of 1 MB (default: 1 MB) "block-size" Block
6340 size in bytes, must be a multiple of 1 MB and not larger than 256 MB
6341 (default: automatically choose a block size depending on the image
6342 size) "subformat" vhdx subformat (default: dynamic)
6343 "block-state-zero" Force use of payload blocks of type 'ZERO'. Non-
6344 standard, but default. Do not set to 'off' when using 'qemu-img
6345 convert' with subformat=dynamic.
6346 Members:
6348 "file: BlockdevRef"
6350 Not documented
6351 "size: int"
6353 Not documented
6354 "log-size: int" (optional)
6356 Not documented
6357 "block-size: int" (optional)
6359 Not documented
6360 "subformat: BlockdevVhdxSubformat" (optional)
6362 Not documented
6363 "block-state-zero: boolean" (optional)
6365 Not documented
6366 Since: 2.12
6368 BlockdevVpcSubformat (Enum)
6370 Values:
6372 "dynamic"
6374 Growing image file
6375 "fixed"
6377 Preallocated fixed-size image file
6378 Since: 2.12
6380 BlockdevCreateOptionsVpc (Object)
6382 Driver specific image creation options for vpc (VHD).
6384 "file" Node to create the image format on "size"
6386 Size of the virtual disk in bytes "subformat" vhdx subformat
6387 (default: dynamic) "force-size" Force use of the exact byte size
6388 instead of rounding to the next size that can be represented in CHS
6389 geometry (default: false)
6390 Members:
6392 "file: BlockdevRef"
6394 Not documented
6395 "size: int"
6397 Not documented
6398 "subformat: BlockdevVpcSubformat" (optional)
6400 Not documented
6401 "force-size: boolean" (optional)
6403 Not documented
6404 Since: 2.12
6406 BlockdevCreateOptions (Object)
6408 Options for creating an image format on a given node.
6410 "driver" block driver to create the image format
6412 Members:
6414 "driver: BlockdevDriver"
6416 Not documented
6417 The members of "BlockdevCreateOptionsFile" when "driver" is "file"
6419 The members of "BlockdevCreateOptionsGluster" when "driver" is
6420 "gluster"
6421 The members of "BlockdevCreateOptionsLUKS" when "driver" is "luks"
6422 The members of "BlockdevCreateOptionsNfs" when "driver" is "nfs"
6423 The members of "BlockdevCreateOptionsParallels" when "driver" is
6424 "parallels"
6425 The members of "BlockdevCreateOptionsQcow" when "driver" is "qcow"
6426 The members of "BlockdevCreateOptionsQcow2" when "driver" is "qcow2"
6427 The members of "BlockdevCreateOptionsQed" when "driver" is "qed"
6428 The members of "BlockdevCreateOptionsRbd" when "driver" is "rbd"
6429 The members of "BlockdevCreateOptionsSheepdog" when "driver" is
6430 "sheepdog"
6431 The members of "BlockdevCreateOptionsSsh" when "driver" is "ssh"
6432 The members of "BlockdevCreateOptionsVdi" when "driver" is "vdi"
6433 The members of "BlockdevCreateOptionsVhdx" when "driver" is "vhdx"
6434 The members of "BlockdevCreateOptionsVmdk" when "driver" is "vmdk"
6435 The members of "BlockdevCreateOptionsVpc" when "driver" is "vpc"
6436 Since: 2.12
6438 blockdev-create (Command) Starts a job to create an image format on a
6440 given node. The job is automatically finalized, but a manual job-
6441 dismiss is required.
6442 Arguments:
6444 "job-id: string"
6446 Identifier for the newly created job.
6447 "options: BlockdevCreateOptions"
6449 Options for the image creation.
6450 Since: 3.0
6452 blockdev-open-tray (Command) Opens a block device's tray. If there is
6454 a block driver state tree inserted as a medium, it will become
6455 inaccessible to the guest (but it will remain associated to the block
6456 device, so closing the tray will make it accessible again).
6457 If the tray was already open before, this will be a no-op.
6459 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are
6461 cases in which no such event will be generated, these include:
6462 - if the guest has locked the tray, "force" is false and the guest
6464 does not respond to the eject request
6465 - if the BlockBackend denoted by "device" does not have a guest
6467 device attached to it
6468 - if the guest device does not have an actual tray
6470 Arguments:
6472 "device: string" (optional)
6474 Block device name (deprecated, use "id" instead)
6475 "id: string" (optional)
6477 The name or QOM path of the guest device (since: 2.8)
6478 "force: boolean" (optional)
6480 if false (the default), an eject request will be sent to the guest
6481 if it has locked the tray (and the tray will not be opened
6482 immediately); if true, the tray will be opened regardless of
6483 whether it is locked
6484 Since: 2.5
6486 Example:
6488 -> { "execute": "blockdev-open-tray",
6490 "arguments": { "id": "ide0-1-0" } }
6491 <- { "timestamp": { "seconds": 1418751016,
6493 "microseconds": 716996 },
6494 "event": "DEVICE_TRAY_MOVED",
6495 "data": { "device": "ide1-cd0",
6496 "id": "ide0-1-0",
6497 "tray-open": true } }
6498 <- { "return": {} }
6500 blockdev-close-tray (Command) Closes a block device's tray. If there
6502 is a block driver state tree associated with the block device (which is
6503 currently ejected), that tree will be loaded as the medium.
6504 If the tray was already closed before, this will be a no-op.
6506 Arguments:
6508 "device: string" (optional)
6510 Block device name (deprecated, use "id" instead)
6511 "id: string" (optional)
6513 The name or QOM path of the guest device (since: 2.8)
6514 Since: 2.5
6516 Example:
6518 -> { "execute": "blockdev-close-tray",
6520 "arguments": { "id": "ide0-1-0" } }
6521 <- { "timestamp": { "seconds": 1418751345,
6523 "microseconds": 272147 },
6524 "event": "DEVICE_TRAY_MOVED",
6525 "data": { "device": "ide1-cd0",
6526 "id": "ide0-1-0",
6527 "tray-open": false } }
6528 <- { "return": {} }
6530 blockdev-remove-medium (Command) Removes a medium (a block driver
6532 state tree) from a block device. That block device's tray must
6533 currently be open (unless there is no attached guest device).
6534 If the tray is open and there is no medium inserted, this will be a no-
6536 op.
6537 Arguments:
6539 "id: string"
6541 The name or QOM path of the guest device
6542 Since: 2.12
6544 Example:
6546 -> { "execute": "blockdev-remove-medium",
6548 "arguments": { "id": "ide0-1-0" } }
6549 <- { "error": { "class": "GenericError",
6551 "desc": "Tray of device 'ide0-1-0' is not open" } }
6552 -> { "execute": "blockdev-open-tray",
6554 "arguments": { "id": "ide0-1-0" } }
6555 <- { "timestamp": { "seconds": 1418751627,
6557 "microseconds": 549958 },
6558 "event": "DEVICE_TRAY_MOVED",
6559 "data": { "device": "ide1-cd0",
6560 "id": "ide0-1-0",
6561 "tray-open": true } }
6562 <- { "return": {} }
6564 -> { "execute": "blockdev-remove-medium",
6566 "arguments": { "id": "ide0-1-0" } }
6567 <- { "return": {} }
6569 blockdev-insert-medium (Command) Inserts a medium (a block driver
6571 state tree) into a block device. That block device's tray must
6572 currently be open (unless there is no attached guest device) and there
6573 must be no medium inserted already.
6574 Arguments:
6576 "id: string"
6578 The name or QOM path of the guest device
6579 "node-name: string"
6581 name of a node in the block driver state graph
6582 Since: 2.12
6584 Example:
6586 -> { "execute": "blockdev-add",
6588 "arguments": {
6589 "node-name": "node0",
6590 "driver": "raw",
6591 "file": { "driver": "file",
6592 "filename": "fedora.iso" } } }
6593 <- { "return": {} }
6594 -> { "execute": "blockdev-insert-medium",
6596 "arguments": { "id": "ide0-1-0",
6597 "node-name": "node0" } }
6598 <- { "return": {} }
6600 BlockdevChangeReadOnlyMode (Enum)
6602 Specifies the new read-only mode of a block device subject to the
6604 "blockdev-change-medium" command.
6605 Values:
6607 "retain"
6609 Retains the current read-only mode
6610 "read-only"
6612 Makes the device read-only
6613 "read-write"
6615 Makes the device writable
6616 Since: 2.3
6618 blockdev-change-medium (Command) Changes the medium inserted into a
6620 block device by ejecting the current medium and loading a new image
6621 file which is inserted as the new medium (this command combines
6622 blockdev-open-tray, blockdev-remove-medium, blockdev-insert-medium and
6623 blockdev-close-tray).
6624 Arguments:
6626 "device: string" (optional)
6628 Block device name (deprecated, use "id" instead)
6629 "id: string" (optional)
6631 The name or QOM path of the guest device (since: 2.8)
6632 "filename: string"
6634 filename of the new image to be loaded
6635 "format: string" (optional)
6637 format to open the new image with (defaults to the probed format)
6638 "read-only-mode: BlockdevChangeReadOnlyMode" (optional)
6640 change the read-only mode of the device; defaults to 'retain'
6641 Since: 2.5
6643 Examples:
6645 1. Change a removable medium
6647 -> { "execute": "blockdev-change-medium",
6649 "arguments": { "id": "ide0-1-0",
6650 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
6651 "format": "raw" } }
6652 <- { "return": {} }
6653 2. Load a read-only medium into a writable drive
6655 -> { "execute": "blockdev-change-medium",
6657 "arguments": { "id": "floppyA",
6658 "filename": "/srv/images/ro.img",
6659 "format": "raw",
6660 "read-only-mode": "retain" } }
6661 <- { "error":
6663 { "class": "GenericError",
6664 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
6665 -> { "execute": "blockdev-change-medium",
6667 "arguments": { "id": "floppyA",
6668 "filename": "/srv/images/ro.img",
6669 "format": "raw",
6670 "read-only-mode": "read-only" } }
6671 <- { "return": {} }
6673 BlockErrorAction (Enum)
6675 An enumeration of action that has been taken when a DISK I/O occurs
6677 Values:
6679 "ignore"
6681 error has been ignored
6682 "report"
6684 error has been reported to the device
6685 "stop"
6687 error caused VM to be stopped
6688 Since: 2.1
6690 BLOCK_IMAGE_CORRUPTED (Event) Emitted when a disk image is being
6692 marked corrupt. The image can be identified by its device or node name.
6693 The 'device' field is always present for compatibility reasons, but it
6694 can be empty ("") if the image does not have a device name associated.
6695 Arguments:
6697 "device: string"
6699 device name. This is always present for compatibility reasons, but
6700 it can be empty ("") if the image does not have a device name
6701 associated.
6702 "node-name: string" (optional)
6704 node name (Since: 2.4)
6705 "msg: string"
6707 informative message for human consumption, such as the kind of
6708 corruption being detected. It should not be parsed by machine as it
6709 is not guaranteed to be stable
6710 "offset: int" (optional)
6712 if the corruption resulted from an image access, this is the host's
6713 access offset into the image
6714 "size: int" (optional)
6716 if the corruption resulted from an image access, this is the access
6717 size
6718 "fatal: boolean"
6720 if set, the image is marked corrupt and therefore unusable after
6721 this event and must be repaired (Since 2.2; before, every
6722 BLOCK_IMAGE_CORRUPTED event was fatal)
6723 Note: If action is "stop", a STOP event will eventually follow the
6725 BLOCK_IO_ERROR event.
6726 Example:
6728 <- { "event": "BLOCK_IMAGE_CORRUPTED",
6730 "data": { "device": "ide0-hd0", "node-name": "node0",
6731 "msg": "Prevented active L1 table overwrite", "offset": 196608,
6732 "size": 65536 },
6733 "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
6734 Since: 1.7
6736 BLOCK_IO_ERROR (Event) Emitted when a disk I/O error occurs
6738 Arguments:
6740 "device: string"
6742 device name. This is always present for compatibility reasons, but
6743 it can be empty ("") if the image does not have a device name
6744 associated.
6745 "node-name: string" (optional)
6747 node name. Note that errors may be reported for the root node that
6748 is directly attached to a guest device rather than for the node
6749 where the error occurred. The node name is not present if the drive
6750 is empty. (Since: 2.8)
6751 "operation: IoOperationType"
6753 I/O operation
6754 "action: BlockErrorAction"
6756 action that has been taken
6757 "nospace: boolean" (optional)
6759 true if I/O error was caused due to a no-space condition. This key
6760 is only present if query-block's io-status is present, please see
6761 query-block documentation for more information (since: 2.2)
6762 "reason: string"
6764 human readable string describing the error cause. (This field is a
6765 debugging aid for humans, it should not be parsed by applications)
6766 (since: 2.2)
6767 Note: If action is "stop", a STOP event will eventually follow the
6769 BLOCK_IO_ERROR event
6770 Since: 0.13.0
6772 Example:
6774 <- { "event": "BLOCK_IO_ERROR",
6776 "data": { "device": "ide0-hd1",
6777 "node-name": "#block212",
6778 "operation": "write",
6779 "action": "stop" },
6780 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6781 BLOCK_JOB_COMPLETED (Event) Emitted when a block job has completed
6783 Arguments:
6785 "type: JobType"
6787 job type
6788 "device: string"
6790 The job identifier. Originally the device name but other values are
6791 allowed since QEMU 2.7
6792 "len: int"
6794 maximum progress value
6795 "offset: int"
6797 current progress value. On success this is equal to len. On
6798 failure this is less than len
6799 "speed: int"
6801 rate limit, bytes per second
6802 "error: string" (optional)
6804 error message. Only present on failure. This field contains a
6805 human-readable error message. There are no semantics other than
6806 that streaming has failed and clients should not try to interpret
6807 the error string
6808 Since: 1.1
6810 Example:
6812 <- { "event": "BLOCK_JOB_COMPLETED",
6814 "data": { "type": "stream", "device": "virtio-disk0",
6815 "len": 10737418240, "offset": 10737418240,
6816 "speed": 0 },
6817 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6818 BLOCK_JOB_CANCELLED (Event) Emitted when a block job has been
6820 cancelled
6821 Arguments:
6823 "type: JobType"
6825 job type
6826 "device: string"
6828 The job identifier. Originally the device name but other values are
6829 allowed since QEMU 2.7
6830 "len: int"
6832 maximum progress value
6833 "offset: int"
6835 current progress value. On success this is equal to len. On
6836 failure this is less than len
6837 "speed: int"
6839 rate limit, bytes per second
6840 Since: 1.1
6842 Example:
6844 <- { "event": "BLOCK_JOB_CANCELLED",
6846 "data": { "type": "stream", "device": "virtio-disk0",
6847 "len": 10737418240, "offset": 134217728,
6848 "speed": 0 },
6849 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6850 BLOCK_JOB_ERROR (Event) Emitted when a block job encounters an error
6852 Arguments:
6854 "device: string"
6856 The job identifier. Originally the device name but other values are
6857 allowed since QEMU 2.7
6858 "operation: IoOperationType"
6860 I/O operation
6861 "action: BlockErrorAction"
6863 action that has been taken
6864 Since: 1.3
6866 Example:
6868 <- { "event": "BLOCK_JOB_ERROR",
6870 "data": { "device": "ide0-hd1",
6871 "operation": "write",
6872 "action": "stop" },
6873 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6874 BLOCK_JOB_READY (Event) Emitted when a block job is ready to complete
6876 Arguments:
6878 "type: JobType"
6880 job type
6881 "device: string"
6883 The job identifier. Originally the device name but other values are
6884 allowed since QEMU 2.7
6885 "len: int"
6887 maximum progress value
6888 "offset: int"
6890 current progress value. On success this is equal to len. On
6891 failure this is less than len
6892 "speed: int"
6894 rate limit, bytes per second
6895 Note: The "ready to complete" status is always reset by a
6897 "BLOCK_JOB_ERROR" event
6898 Since: 1.3
6900 Example:
6902 <- { "event": "BLOCK_JOB_READY",
6904 "data": { "device": "drive0", "type": "mirror", "speed": 0,
6905 "len": 2097152, "offset": 2097152 }
6906 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6907 BLOCK_JOB_PENDING (Event) Emitted when a block job is awaiting
6909 explicit authorization to finalize graph changes via
6910 "block-job-finalize". If this job is part of a transaction, it will not
6911 emit this event until the transaction has converged first.
6912 Arguments:
6914 "type: JobType"
6916 job type
6917 "id: string"
6919 The job identifier.
6920 Since: 2.12
6922 Example:
6924 <- { "event": "BLOCK_JOB_WAITING",
6926 "data": { "device": "drive0", "type": "mirror" },
6927 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6928 PreallocMode (Enum)
6930 Preallocation mode of QEMU image file
6932 Values:
6934 "off"
6936 no preallocation
6937 "metadata"
6939 preallocate only for metadata
6940 "falloc"
6942 like "full" preallocation but allocate disk space by
6943 posix_fallocate() rather than writing zeros.
6944 "full"
6946 preallocate all data by writing zeros to device to ensure disk
6947 space is really available. "full" preallocation also sets up
6948 metadata correctly.
6949 Since: 2.2
6951 BLOCK_WRITE_THRESHOLD (Event) Emitted when writes on block device
6953 reaches or exceeds the configured write threshold. For thin-provisioned
6954 devices, this means the device should be extended to avoid pausing for
6955 disk exhaustion. The event is one shot. Once triggered, it needs to be
6956 re-registered with another block-set-write-threshold command.
6957 Arguments:
6959 "node-name: string"
6961 graph node name on which the threshold was exceeded.
6962 "amount-exceeded: int"
6964 amount of data which exceeded the threshold, in bytes.
6965 "write-threshold: int"
6967 last configured threshold, in bytes.
6968 Since: 2.3
6970 block-set-write-threshold (Command) Change the write threshold for a
6972 block drive. An event will be delivered if a write to this block drive
6973 crosses the configured threshold. The threshold is an offset, thus
6974 must be non-negative. Default is no write threshold. Setting the
6975 threshold to zero disables it.
6976 This is useful to transparently resize thin-provisioned drives without
6978 the guest OS noticing.
6979 Arguments:
6981 "node-name: string"
6983 graph node name on which the threshold must be set.
6984 "write-threshold: int"
6986 configured threshold for the block device, bytes. Use 0 to disable
6987 the threshold.
6988 Since: 2.3
6990 Example:
6992 -> { "execute": "block-set-write-threshold",
6994 "arguments": { "node-name": "mydev",
6995 "write-threshold": 17179869184 } }
6996 <- { "return": {} }
6997 x-blockdev-change (Command) Dynamically reconfigure the block driver
6999 state graph. It can be used to add, remove, insert or replace a graph
7000 node. Currently only the Quorum driver implements this feature to add
7001 or remove its child. This is useful to fix a broken quorum child.
7002 If "node" is specified, it will be inserted under "parent". "child" may
7004 not be specified in this case. If both "parent" and "child" are
7005 specified but "node" is not, "child" will be detached from "parent".
7006 Arguments:
7008 "parent: string"
7010 the id or name of the parent node.
7011 "child: string" (optional)
7013 the name of a child under the given parent node.
7014 "node: string" (optional)
7016 the name of the node that will be added.
7017 Note: this command is experimental, and its API is not stable. It does
7019 not support all kinds of operations, all kinds of children, nor all
7020 block drivers.
7021 FIXME Removing children from a quorum node means introducing gaps in
7023 the child indices. This cannot be represented in the 'children' list of
7024 BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename().
7025 Warning: The data in a new quorum child MUST be consistent with that of
7027 the rest of the array.
7028 Since: 2.7
7030 Example:
7032 1. Add a new node to a quorum
7034 -> { "execute": "blockdev-add",
7035 "arguments": {
7036 "driver": "raw",
7037 "node-name": "new_node",
7038 "file": { "driver": "file",
7039 "filename": "test.raw" } } }
7040 <- { "return": {} }
7041 -> { "execute": "x-blockdev-change",
7042 "arguments": { "parent": "disk1",
7043 "node": "new_node" } }
7044 <- { "return": {} }
7045 2. Delete a quorum's node
7047 -> { "execute": "x-blockdev-change",
7048 "arguments": { "parent": "disk1",
7049 "child": "children.1" } }
7050 <- { "return": {} }
7051 x-blockdev-set-iothread (Command) Move "node" and its children into
7053 the "iothread". If "iothread" is null then move "node" and its
7054 children into the main loop.
7055 The node must not be attached to a BlockBackend.
7057 Arguments:
7059 "node-name: string"
7061 the name of the block driver node
7062 "iothread: StrOrNull"
7064 the name of the IOThread object or null for the main loop
7065 "force: boolean" (optional)
7067 true if the node and its children should be moved when a
7068 BlockBackend is already attached
7069 Note: this command is experimental and intended for test cases that
7071 need control over IOThreads only.
7072 Since: 2.12
7074 Example:
7076 1. Move a node into an IOThread
7078 -> { "execute": "x-blockdev-set-iothread",
7079 "arguments": { "node-name": "disk1",
7080 "iothread": "iothread0" } }
7081 <- { "return": {} }
7082 2. Move a node into the main loop
7084 -> { "execute": "x-blockdev-set-iothread",
7085 "arguments": { "node-name": "disk1",
7086 "iothread": null } }
7087 <- { "return": {} }
7088 Additional block stuff (VM related)
7090 BiosAtaTranslation (Enum)
7092 Policy that BIOS should use to interpret cylinder/head/sector
7094 addresses. Note that Bochs BIOS and SeaBIOS will not actually
7095 translate logical CHS to physical; instead, they will use logical block
7096 addressing.
7097 Values:
7099 "auto"
7101 If cylinder/heads/sizes are passed, choose between none and LBA
7102 depending on the size of the disk. If they are not passed, choose
7103 none if QEMU can guess that the disk had 16 or fewer heads, large
7104 if QEMU can guess that the disk had 131072 or fewer tracks across
7105 all heads (i.e. cylinders*heads<131072), otherwise LBA.
7106 "none"
7108 The physical disk geometry is equal to the logical geometry.
7109 "lba"
7111 Assume 63 sectors per track and one of 16, 32, 64, 128 or 255 heads
7112 (if fewer than 255 are enough to cover the whole disk with 1024
7113 cylinders/head). The number of cylinders/head is then computed
7114 based on the number of sectors and heads.
7115 "large"
7117 The number of cylinders per head is scaled down to 1024 by
7118 correspondingly scaling up the number of heads.
7119 "rechs"
7121 Same as "large", but first convert a 16-head geometry to 15-head,
7122 by proportionally scaling up the number of cylinders/head.
7123 Since: 2.0
7125 FloppyDriveType (Enum)
7127 Type of Floppy drive to be emulated by the Floppy Disk Controller.
7129 Values:
7131 144 1.44MB 3.5" drive
7133 288 2.88MB 3.5" drive
7135 120 1.2MB 5.25" drive
7137 "none"
7139 No drive connected
7140 "auto"
7142 Automatically determined by inserted media at boot
7143 Since: 2.6
7145 BlockdevSnapshotInternal (Object)
7147 Members:
7149 "device: string"
7151 the device name or node-name of a root node to generate the
7152 snapshot from
7153 "name: string"
7155 the name of the internal snapshot to be created
7156 Notes: In transaction, if "name" is empty, or any snapshot matching
7158 "name" exists, the operation will fail. Only some image formats support
7159 it, for example, qcow2, rbd, and sheepdog.
7160 Since: 1.7
7162 PRManagerInfo (Object)
7164 Information about a persistent reservation manager
7166 Members:
7168 "id: string"
7170 the identifier of the persistent reservation manager
7171 "connected: boolean"
7173 true if the persistent reservation manager is connected to the
7174 underlying storage or helper
7175 Since: 3.0
7177 query-pr-managers (Command) Returns a list of information about each
7179 persistent reservation manager.
7180 Returns: a list of "PRManagerInfo" for each persistent reservation
7182 manager
7183 Since: 3.0
7185 blockdev-snapshot-internal-sync (Command) Synchronously take an
7187 internal snapshot of a block device, when the format of the image used
7188 supports it. If the name is an empty string, or a snapshot with name
7189 already exists, the operation will fail.
7190 For the arguments, see the documentation of BlockdevSnapshotInternal.
7192 Returns: nothing on success
7194 If "device" is not a valid block device, GenericError
7196 If any snapshot matching "name" exists, or "name" is empty,
7198 GenericError
7199 If the format of the image used does not support it,
7201 BlockFormatFeatureNotSupported
7202 Since: 1.7
7204 Example:
7206 -> { "execute": "blockdev-snapshot-internal-sync",
7208 "arguments": { "device": "ide-hd0",
7209 "name": "snapshot0" }
7210 }
7211 <- { "return": {} }
7212 blockdev-snapshot-delete-internal-sync (Command) Synchronously delete
7214 an internal snapshot of a block device, when the format of the image
7215 used support it. The snapshot is identified by name or id or both. One
7216 of the name or id is required. Return SnapshotInfo for the successfully
7217 deleted snapshot.
7218 Arguments:
7220 "device: string"
7222 the device name or node-name of a root node to delete the snapshot
7223 from
7224 "id: string" (optional)
7226 optional the snapshot's ID to be deleted
7227 "name: string" (optional)
7229 optional the snapshot's name to be deleted
7230 Returns: SnapshotInfo on success If "device" is not a valid block
7232 device, GenericError If snapshot not found, GenericError If the format
7233 of the image used does not support it, BlockFormatFeatureNotSupported
7234 If "id" and "name" are both not specified, GenericError
7235 Since: 1.7
7237 Example:
7239 -> { "execute": "blockdev-snapshot-delete-internal-sync",
7241 "arguments": { "device": "ide-hd0",
7242 "name": "snapshot0" }
7243 }
7244 <- { "return": {
7245 "id": "1",
7246 "name": "snapshot0",
7247 "vm-state-size": 0,
7248 "date-sec": 1000012,
7249 "date-nsec": 10,
7250 "vm-clock-sec": 100,
7251 "vm-clock-nsec": 20
7252 }
7253 }
7254 eject (Command) Ejects a device from a removable drive.
7256 Arguments:
7258 "device: string" (optional)
7260 Block device name (deprecated, use "id" instead)
7261 "id: string" (optional)
7263 The name or QOM path of the guest device (since: 2.8)
7264 "force: boolean" (optional)
7266 If true, eject regardless of whether the drive is locked. If not
7267 specified, the default value is false.
7268 Returns: Nothing on success
7270 If "device" is not a valid block device, DeviceNotFound
7272 Notes: Ejecting a device with no media results in success
7274 Since: 0.14.0
7276 Example:
7278 -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
7280 <- { "return": {} }
7281 nbd-server-start (Command) Start an NBD server listening on the given
7283 host and port. Block devices can then be exported using
7284 "nbd-server-add". The NBD server will present them as named exports;
7285 for example, another QEMU instance could refer to them as
7286 "nbd:HOST:PORT:exportname=NAME".
7287 Arguments:
7289 "addr: SocketAddressLegacy"
7291 Address on which to listen.
7292 "tls-creds: string" (optional)
7294 ID of the TLS credentials object (since 2.6).
7295 "tls-authz: string" (optional)
7297 ID of the QAuthZ authorization object used to validate the client's
7298 x509 distinguished name. This object is is only resolved at time of
7299 use, so can be deleted and recreated on the fly while the NBD
7300 server is active. If missing, it will default to denying access
7301 (since 4.0).
7302 Returns: error if the server is already running.
7304 Since: 1.3.0
7306 nbd-server-add (Command) Export a block node to QEMU's embedded NBD
7308 server.
7309 Arguments:
7311 "device: string"
7313 The device name or node name of the node to be exported
7314 "name: string" (optional)
7316 Export name. If unspecified, the "device" parameter is used as the
7317 export name. (Since 2.12)
7318 "writable: boolean" (optional)
7320 Whether clients should be able to write to the device via the NBD
7321 connection (default false).
7322 "bitmap: string" (optional)
7324 Also export the dirty bitmap reachable from "device", so the NBD
7325 client can use NBD_OPT_SET_META_CONTEXT with
7326 "qemu:dirty-bitmap:NAME" to inspect the bitmap. (since 4.0)
7327 Returns: error if the server is not running, or export with the same
7329 name already exists.
7330 Since: 1.3.0
7332 NbdServerRemoveMode (Enum)
7334 Mode for removing an NBD export.
7336 Values:
7338 "safe"
7340 Remove export if there are no existing connections, fail otherwise.
7341 "hard"
7343 Drop all connections immediately and remove export.
7344 Potential additional modes to be added in the future:
7346 hide: Just hide export from new clients, leave existing connections as
7348 is. Remove export after all clients are disconnected.
7349 soft: Hide export from new clients, answer with ESHUTDOWN for all
7351 further requests from existing clients.
7352 Since: 2.12
7354 nbd-server-remove (Command) Remove NBD export by name.
7356 Arguments:
7358 "name: string"
7360 Export name.
7361 "mode: NbdServerRemoveMode" (optional)
7363 Mode of command operation. See "NbdServerRemoveMode" description.
7364 Default is 'safe'.
7365 Returns: error if
7367 - the server is not running
7369 - export is not found
7371 - mode is 'safe' and there are existing connections
7373 Since: 2.12
7375 nbd-server-stop (Command) Stop QEMU's embedded NBD server, and
7377 unregister all devices previously added via "nbd-server-add".
7378 Since: 1.3.0
7380 DEVICE_TRAY_MOVED (Event) Emitted whenever the tray of a removable
7382 device is moved by the guest or by HMP/QMP commands
7383 Arguments:
7385 "device: string"
7387 Block device name. This is always present for compatibility
7388 reasons, but it can be empty ("") if the image does not have a
7389 device name associated.
7390 "id: string"
7392 The name or QOM path of the guest device (since 2.8)
7393 "tray-open: boolean"
7395 true if the tray has been opened or false if it has been closed
7396 Since: 1.1
7398 Example:
7400 <- { "event": "DEVICE_TRAY_MOVED",
7402 "data": { "device": "ide1-cd0",
7403 "id": "/machine/unattached/device[22]",
7404 "tray-open": true
7405 },
7406 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7407 PR_MANAGER_STATUS_CHANGED (Event) Emitted whenever the connected
7409 status of a persistent reservation manager changes.
7410 Arguments:
7412 "id: string"
7414 The id of the PR manager object
7415 "connected: boolean"
7417 true if the PR manager is connected to a backend
7418 Since: 3.0
7420 Example:
7422 <- { "event": "PR_MANAGER_STATUS_CHANGED",
7424 "data": { "id": "pr-helper0",
7425 "connected": true
7426 },
7427 "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
7428 QuorumOpType (Enum)
7430 An enumeration of the quorum operation types
7432 Values:
7434 "read"
7436 read operation
7437 "write"
7439 write operation
7440 "flush"
7442 flush operation
7443 Since: 2.6
7445 QUORUM_FAILURE (Event) Emitted by the Quorum block driver if it fails
7447 to establish a quorum
7448 Arguments:
7450 "reference: string"
7452 device name if defined else node name
7453 "sector-num: int"
7455 number of the first sector of the failed read operation
7456 "sectors-count: int"
7458 failed read operation sector count
7459 Note: This event is rate-limited.
7461 Since: 2.0
7463 Example:
7465 <- { "event": "QUORUM_FAILURE",
7467 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
7468 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7469 QUORUM_REPORT_BAD (Event) Emitted to report a corruption of a Quorum
7471 file
7472 Arguments:
7474 "type: QuorumOpType"
7476 quorum operation type (Since 2.6)
7477 "error: string" (optional)
7479 error message. Only present on failure. This field contains a
7480 human-readable error message. There are no semantics other than
7481 that the block layer reported an error and clients should not try
7482 to interpret the error string.
7483 "node-name: string"
7485 the graph node name of the block driver state
7486 "sector-num: int"
7488 number of the first sector of the failed read operation
7489 "sectors-count: int"
7491 failed read operation sector count
7492 Note: This event is rate-limited.
7494 Since: 2.0
7496 Example:
7498 1. Read operation
7500 { "event": "QUORUM_REPORT_BAD",
7502 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
7503 "type": "read" },
7504 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7505 2. Flush operation
7507 { "event": "QUORUM_REPORT_BAD",
7509 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
7510 "type": "flush", "error": "Broken pipe" },
7511 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
7512 Character devices
7514 ChardevInfo (Object)
7515 Information about a character device.
7517 Members:
7519 "label: string"
7521 the label of the character device
7522 "filename: string"
7524 the filename of the character device
7525 "frontend-open: boolean"
7527 shows whether the frontend device attached to this backend (eg.
7528 with the chardev=... option) is in open or closed state (since 2.1)
7529 Notes: "filename" is encoded using the QEMU command line character
7531 device encoding. See the QEMU man page for details.
7532 Since: 0.14.0
7534 query-chardev (Command) Returns information about current character
7536 devices.
7537 Returns: a list of "ChardevInfo"
7539 Since: 0.14.0
7541 Example:
7543 -> { "execute": "query-chardev" }
7545 <- {
7546 "return": [
7547 {
7548 "label": "charchannel0",
7549 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
7550 "frontend-open": false
7551 },
7552 {
7553 "label": "charmonitor",
7554 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
7555 "frontend-open": true
7556 },
7557 {
7558 "label": "charserial0",
7559 "filename": "pty:/dev/pts/2",
7560 "frontend-open": true
7561 }
7562 ]
7563 }
7564 ChardevBackendInfo (Object)
7566 Information about a character device backend
7568 Members:
7570 "name: string"
7572 The backend name
7573 Since: 2.0
7575 query-chardev-backends (Command) Returns information about character
7577 device backends.
7578 Returns: a list of "ChardevBackendInfo"
7580 Since: 2.0
7582 Example:
7584 -> { "execute": "query-chardev-backends" }
7586 <- {
7587 "return":[
7588 {
7589 "name":"udp"
7590 },
7591 {
7592 "name":"tcp"
7593 },
7594 {
7595 "name":"unix"
7596 },
7597 {
7598 "name":"spiceport"
7599 }
7600 ]
7601 }
7602 DataFormat (Enum)
7604 An enumeration of data format.
7606 Values:
7608 "utf8"
7610 Data is a UTF-8 string (RFC 3629)
7611 "base64"
7613 Data is Base64 encoded binary (RFC 3548)
7614 Since: 1.4
7616 ringbuf-write (Command) Write to a ring buffer character device.
7618 Arguments:
7620 "device: string"
7622 the ring buffer character device name
7623 "data: string"
7625 data to write
7626 "format: DataFormat" (optional)
7628 data encoding (default 'utf8').
7629 - base64: data must be base64 encoded text. Its binary decoding
7631 gets written.
7632 - utf8: data's UTF-8 encoding is written
7634 - data itself is always Unicode regardless of format, like any
7636 other string.
7637 Returns: Nothing on success
7639 Since: 1.4
7641 Example:
7643 -> { "execute": "ringbuf-write",
7645 "arguments": { "device": "foo",
7646 "data": "abcdefgh",
7647 "format": "utf8" } }
7648 <- { "return": {} }
7649 ringbuf-read (Command) Read from a ring buffer character device.
7651 Arguments:
7653 "device: string"
7655 the ring buffer character device name
7656 "size: int"
7658 how many bytes to read at most
7659 "format: DataFormat" (optional)
7661 data encoding (default 'utf8').
7662 - base64: the data read is returned in base64 encoding.
7664 - utf8: the data read is interpreted as UTF-8. Bug: can screw up
7666 when the buffer contains invalid UTF-8 sequences, NUL
7667 characters, after the ring buffer lost data, and when reading
7668 stops because the size limit is reached.
7669 - The return value is always Unicode regardless of format, like
7671 any other string.
7672 Returns: data read from the device
7674 Since: 1.4
7676 Example:
7678 -> { "execute": "ringbuf-read",
7680 "arguments": { "device": "foo",
7681 "size": 1000,
7682 "format": "utf8" } }
7683 <- { "return": "abcdefgh" }
7684 ChardevCommon (Object)
7686 Configuration shared across all chardev backends
7688 Members:
7690 "logfile: string" (optional)
7692 The name of a logfile to save output
7693 "logappend: boolean" (optional)
7695 true to append instead of truncate (default to false to truncate)
7696 Since: 2.6
7698 ChardevFile (Object)
7700 Configuration info for file chardevs.
7702 Members:
7704 "in: string" (optional)
7706 The name of the input file
7707 "out: string"
7709 The name of the output file
7710 "append: boolean" (optional)
7712 Open the file in append mode (default false to truncate) (Since
7713 2.6)
7714 The members of "ChardevCommon"
7716 Since: 1.4
7718 ChardevHostdev (Object)
7720 Configuration info for device and pipe chardevs.
7722 Members:
7724 "device: string"
7726 The name of the special file for the device, i.e. /dev/ttyS0 on
7727 Unix or COM1: on Windows
7728 The members of "ChardevCommon"
7730 Since: 1.4
7732 ChardevSocket (Object)
7734 Configuration info for (stream) socket chardevs.
7736 Members:
7738 "addr: SocketAddressLegacy"
7740 socket address to listen on (server=true) or connect to
7741 (server=false)
7742 "tls-creds: string" (optional)
7744 the ID of the TLS credentials object (since 2.6)
7745 "tls-authz: string" (optional)
7747 the ID of the QAuthZ authorization object against which the
7748 client's x509 distinguished name will be validated. This object is
7749 only resolved at time of use, so can be deleted and recreated on
7750 the fly while the chardev server is active. If missing, it will
7751 default to denying access (since 4.0)
7752 "server: boolean" (optional)
7754 create server socket (default: true)
7755 "wait: boolean" (optional)
7757 wait for incoming connection on server sockets (default: false).
7758 "nodelay: boolean" (optional)
7760 set TCP_NODELAY socket option (default: false)
7761 "telnet: boolean" (optional)
7763 enable telnet protocol on server sockets (default: false)
7764 "tn3270: boolean" (optional)
7766 enable tn3270 protocol on server sockets (default: false) (Since:
7767 2.10)
7768 "websocket: boolean" (optional)
7770 enable websocket protocol on server sockets (default: false)
7771 (Since: 3.1)
7772 "reconnect: int" (optional)
7774 For a client socket, if a socket is disconnected, then attempt a
7775 reconnect after the given number of seconds. Setting this to zero
7776 disables this function. (default: 0) (Since: 2.2)
7777 The members of "ChardevCommon"
7779 Since: 1.4
7781 ChardevUdp (Object)
7783 Configuration info for datagram socket chardevs.
7785 Members:
7787 "remote: SocketAddressLegacy"
7789 remote address
7790 "local: SocketAddressLegacy" (optional)
7792 local address
7793 The members of "ChardevCommon"
7795 Since: 1.5
7797 ChardevMux (Object)
7799 Configuration info for mux chardevs.
7801 Members:
7803 "chardev: string"
7805 name of the base chardev.
7806 The members of "ChardevCommon"
7808 Since: 1.5
7810 ChardevStdio (Object)
7812 Configuration info for stdio chardevs.
7814 Members:
7816 "signal: boolean" (optional)
7818 Allow signals (such as SIGINT triggered by ^C) be delivered to
7819 qemu. Default: true in -nographic mode, false otherwise.
7820 The members of "ChardevCommon"
7822 Since: 1.5
7824 ChardevSpiceChannel (Object)
7826 Configuration info for spice vm channel chardevs.
7828 Members:
7830 "type: string"
7832 kind of channel (for example vdagent).
7833 The members of "ChardevCommon"
7835 Since: 1.5
7837 If: "defined(CONFIG_SPICE)"
7839 ChardevSpicePort (Object)
7841 Configuration info for spice port chardevs.
7843 Members:
7845 "fqdn: string"
7847 name of the channel (see docs/spice-port-fqdn.txt)
7848 The members of "ChardevCommon"
7850 Since: 1.5
7852 If: "defined(CONFIG_SPICE)"
7854 ChardevVC (Object)
7856 Configuration info for virtual console chardevs.
7858 Members:
7860 "width: int" (optional)
7862 console width, in pixels
7863 "height: int" (optional)
7865 console height, in pixels
7866 "cols: int" (optional)
7868 console width, in chars
7869 "rows: int" (optional)
7871 console height, in chars
7872 The members of "ChardevCommon"
7874 Since: 1.5
7876 ChardevRingbuf (Object)
7878 Configuration info for ring buffer chardevs.
7880 Members:
7882 "size: int" (optional)
7884 ring buffer size, must be power of two, default is 65536
7885 The members of "ChardevCommon"
7887 Since: 1.5
7889 ChardevBackend (Object)
7891 Configuration info for the new chardev backend.
7893 Members:
7895 "type"
7897 One of "file", "serial", "parallel", "pipe", "socket", "udp",
7898 "pty", "null", "mux", "msmouse", "wctablet", "braille", "testdev",
7899 "stdio", "console", "spicevmc", "spiceport", "vc", "ringbuf",
7900 "memory"
7901 "data: ChardevFile" when "type" is "file"
7903 "data: ChardevHostdev" when "type" is "serial"
7904 "data: ChardevHostdev" when "type" is "parallel"
7905 "data: ChardevHostdev" when "type" is "pipe"
7906 "data: ChardevSocket" when "type" is "socket"
7907 "data: ChardevUdp" when "type" is "udp"
7908 "data: ChardevCommon" when "type" is "pty"
7909 "data: ChardevCommon" when "type" is "null"
7910 "data: ChardevMux" when "type" is "mux"
7911 "data: ChardevCommon" when "type" is "msmouse"
7912 "data: ChardevCommon" when "type" is "wctablet"
7913 "data: ChardevCommon" when "type" is "braille"
7914 "data: ChardevCommon" when "type" is "testdev"
7915 "data: ChardevStdio" when "type" is "stdio"
7916 "data: ChardevCommon" when "type" is "console"
7917 "data: ChardevSpiceChannel" when "type" is "spicevmc" (If:
7918 "defined(CONFIG_SPICE)")
7919 "data: ChardevSpicePort" when "type" is "spiceport" (If:
7920 "defined(CONFIG_SPICE)")
7921 "data: ChardevVC" when "type" is "vc"
7922 "data: ChardevRingbuf" when "type" is "ringbuf"
7923 "data: ChardevRingbuf" when "type" is "memory"
7924 Since: 1.4 (testdev since 2.2, wctablet since 2.9)
7926 ChardevReturn (Object)
7928 Return info about the chardev backend just created.
7930 Members:
7932 "pty: string" (optional)
7934 name of the slave pseudoterminal device, present if and only if a
7935 chardev of type 'pty' was created
7936 Since: 1.4
7938 chardev-add (Command) Add a character device backend
7940 Arguments:
7942 "id: string"
7944 the chardev's ID, must be unique
7945 "backend: ChardevBackend"
7947 backend type and parameters
7948 Returns: ChardevReturn.
7950 Since: 1.4
7952 Example:
7954 -> { "execute" : "chardev-add",
7956 "arguments" : { "id" : "foo",
7957 "backend" : { "type" : "null", "data" : {} } } }
7958 <- { "return": {} }
7959 -> { "execute" : "chardev-add",
7961 "arguments" : { "id" : "bar",
7962 "backend" : { "type" : "file",
7963 "data" : { "out" : "/tmp/bar.log" } } } }
7964 <- { "return": {} }
7965 -> { "execute" : "chardev-add",
7967 "arguments" : { "id" : "baz",
7968 "backend" : { "type" : "pty", "data" : {} } } }
7969 <- { "return": { "pty" : "/dev/pty/42" } }
7970 chardev-change (Command) Change a character device backend
7972 Arguments:
7974 "id: string"
7976 the chardev's ID, must exist
7977 "backend: ChardevBackend"
7979 new backend type and parameters
7980 Returns: ChardevReturn.
7982 Since: 2.10
7984 Example:
7986 -> { "execute" : "chardev-change",
7988 "arguments" : { "id" : "baz",
7989 "backend" : { "type" : "pty", "data" : {} } } }
7990 <- { "return": { "pty" : "/dev/pty/42" } }
7991 -> {"execute" : "chardev-change",
7993 "arguments" : {
7994 "id" : "charchannel2",
7995 "backend" : {
7996 "type" : "socket",
7997 "data" : {
7998 "addr" : {
7999 "type" : "unix" ,
8000 "data" : {
8001 "path" : "/tmp/charchannel2.socket"
8002 }
8003 },
8004 "server" : true,
8005 "wait" : false }}}}
8006 <- {"return": {}}
8007 chardev-remove (Command) Remove a character device backend
8009 Arguments:
8011 "id: string"
8013 the chardev's ID, must exist and not be in use
8014 Returns: Nothing on success
8016 Since: 1.4
8018 Example:
8020 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
8022 <- { "return": {} }
8023 chardev-send-break (Command) Send a break to a character device
8025 Arguments:
8027 "id: string"
8029 the chardev's ID, must exist
8030 Returns: Nothing on success
8032 Since: 2.10
8034 Example:
8036 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
8038 <- { "return": {} }
8039 VSERPORT_CHANGE (Event) Emitted when the guest opens or closes a
8041 virtio-serial port.
8042 Arguments:
8044 "id: string"
8046 device identifier of the virtio-serial port
8047 "open: boolean"
8049 true if the guest has opened the virtio-serial port
8050 Since: 2.1
8052 Example:
8054 <- { "event": "VSERPORT_CHANGE",
8056 "data": { "id": "channel0", "open": true },
8057 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
8058 Dump guest memory
8060 DumpGuestMemoryFormat (Enum)
8061 An enumeration of guest-memory-dump's format.
8063 Values:
8065 "elf"
8067 elf format
8068 "kdump-zlib"
8070 kdump-compressed format with zlib-compressed
8071 "kdump-lzo"
8073 kdump-compressed format with lzo-compressed
8074 "kdump-snappy"
8076 kdump-compressed format with snappy-compressed
8077 "win-dmp"
8079 Windows full crashdump format, can be used instead of ELF
8080 converting (since 2.13)
8081 Since: 2.0
8083 dump-guest-memory (Command) Dump guest's memory to vmcore. It is a
8085 synchronous operation that can take very long depending on the amount
8086 of guest memory.
8087 Arguments:
8089 "paging: boolean"
8091 if true, do paging to get guest's memory mapping. This allows using
8092 gdb to process the core file.
8093 IMPORTANT: this option can make QEMU allocate several gigabytes of
8095 RAM. This can happen for a large guest, or a malicious guest
8096 pretending to be large.
8097 Also, paging=true has the following limitations:
8099 1. The guest may be in a catastrophic state or can have corrupted
8101 memory, which cannot be trusted
8102 2. The guest can be in real-mode even if paging is enabled. For
8104 example, the guest uses ACPI to sleep, and ACPI sleep state
8105 goes in real-mode
8106 3. Currently only supported on i386 and x86_64.
8108 "protocol: string"
8110 the filename or file descriptor of the vmcore. The supported
8111 protocols are:
8112 1. file: the protocol starts with "file:", and the following
8114 string is the file's path.
8115 2. fd: the protocol starts with "fd:", and the following string is
8117 the fd's name.
8118 "detach: boolean" (optional)
8120 if true, QMP will return immediately rather than waiting for the
8121 dump to finish. The user can track progress using "query-dump".
8122 (since 2.6).
8123 "begin: int" (optional)
8125 if specified, the starting physical address.
8126 "length: int" (optional)
8128 if specified, the memory size, in bytes. If you don't want to dump
8129 all guest's memory, please specify the start "begin" and "length"
8130 "format: DumpGuestMemoryFormat" (optional)
8132 if specified, the format of guest memory dump. But non-elf format
8133 is conflict with paging and filter, ie. "paging", "begin" and
8134 "length" is not allowed to be specified with non-elf "format" at
8135 the same time (since 2.0)
8136 Note: All boolean arguments default to false
8138 Returns: nothing on success
8140 Since: 1.2
8142 Example:
8144 -> { "execute": "dump-guest-memory",
8146 "arguments": { "protocol": "fd:dump" } }
8147 <- { "return": {} }
8148 DumpStatus (Enum)
8150 Describe the status of a long-running background guest memory dump.
8152 Values:
8154 "none"
8156 no dump-guest-memory has started yet.
8157 "active"
8159 there is one dump running in background.
8160 "completed"
8162 the last dump has finished successfully.
8163 "failed"
8165 the last dump has failed.
8166 Since: 2.6
8168 DumpQueryResult (Object)
8170 The result format for 'query-dump'.
8172 Members:
8174 "status: DumpStatus"
8176 enum of "DumpStatus", which shows current dump status
8177 "completed: int"
8179 bytes written in latest dump (uncompressed)
8180 "total: int"
8182 total bytes to be written in latest dump (uncompressed)
8183 Since: 2.6
8185 query-dump (Command) Query latest dump status.
8187 Returns: A "DumpStatus" object showing the dump status.
8189 Since: 2.6
8191 Example:
8193 -> { "execute": "query-dump" }
8195 <- { "return": { "status": "active", "completed": 1024000,
8196 "total": 2048000 } }
8197 DUMP_COMPLETED (Event) Emitted when background dump has completed
8199 Arguments:
8201 "result: DumpQueryResult"
8203 final dump status
8204 "error: string" (optional)
8206 human-readable error string that provides hint on why dump failed.
8207 Only presents on failure. The user should not try to interpret the
8208 error string.
8209 Since: 2.6
8211 Example:
8213 { "event": "DUMP_COMPLETED",
8215 "data": {"result": {"total": 1090650112, "status": "completed",
8216 "completed": 1090650112} } }
8217 DumpGuestMemoryCapability (Object)
8219 A list of the available formats for dump-guest-memory
8221 Members:
8223 "formats: array of DumpGuestMemoryFormat"
8225 Not documented
8226 Since: 2.0
8228 query-dump-guest-memory-capability (Command) Returns the available
8230 formats for dump-guest-memory
8231 Returns: A "DumpGuestMemoryCapability" object listing available formats
8233 for dump-guest-memory
8234 Since: 2.0
8236 Example:
8238 -> { "execute": "query-dump-guest-memory-capability" }
8240 <- { "return": { "formats":
8241 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
8242 Net devices
8244 set_link (Command) Sets the link status of a virtual network adapter.
8245 Arguments:
8247 "name: string"
8249 the device name of the virtual network adapter
8250 "up: boolean"
8252 true to set the link status to be up
8253 Returns: Nothing on success If "name" is not a valid network device,
8255 DeviceNotFound
8256 Since: 0.14.0
8258 Notes: Not all network adapters support setting link status. This
8260 command will succeed even if the network adapter does not support link
8261 status notification.
8262 Example:
8264 -> { "execute": "set_link",
8266 "arguments": { "name": "e1000.0", "up": false } }
8267 <- { "return": {} }
8268 netdev_add (Command) Add a network backend.
8270 Arguments:
8272 "type: string"
8274 the type of network backend. Possible values are listed in
8275 NetClientDriver (excluding 'none' and 'nic')
8276 "id: string"
8278 the name of the new network backend
8279 Additional arguments depend on the type.
8281 TODO: This command effectively bypasses QAPI completely due to its
8283 "additional arguments" business. It shouldn't have been added to the
8284 schema in this form. It should be qapified properly, or replaced by a
8285 properly qapified command.
8286 Since: 0.14.0
8288 Returns: Nothing on success If "type" is not a valid network backend,
8290 DeviceNotFound
8291 Example:
8293 -> { "execute": "netdev_add",
8295 "arguments": { "type": "user", "id": "netdev1",
8296 "dnssearch": "example.org" } }
8297 <- { "return": {} }
8298 netdev_del (Command) Remove a network backend.
8300 Arguments:
8302 "id: string"
8304 the name of the network backend to remove
8305 Returns: Nothing on success If "id" is not a valid network backend,
8307 DeviceNotFound
8308 Since: 0.14.0
8310 Example:
8312 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
8314 <- { "return": {} }
8315 NetLegacyNicOptions (Object)
8317 Create a new Network Interface Card.
8319 Members:
8321 "netdev: string" (optional)
8323 id of -netdev to connect to
8324 "macaddr: string" (optional)
8326 MAC address
8327 "model: string" (optional)
8329 device model (e1000, rtl8139, virtio etc.)
8330 "addr: string" (optional)
8332 PCI device address
8333 "vectors: int" (optional)
8335 number of MSI-x vectors, 0 to disable MSI-X
8336 Since: 1.2
8338 NetdevUserOptions (Object)
8340 Use the user mode network stack which requires no administrator
8342 privilege to run.
8343 Members:
8345 "hostname: string" (optional)
8347 client hostname reported by the builtin DHCP server
8348 "restrict: boolean" (optional)
8350 isolate the guest from the host
8351 "ipv4: boolean" (optional)
8353 whether to support IPv4, default true for enabled (since 2.6)
8354 "ipv6: boolean" (optional)
8356 whether to support IPv6, default true for enabled (since 2.6)
8357 "ip: string" (optional)
8359 legacy parameter, use net= instead
8360 "net: string" (optional)
8362 IP network address that the guest will see, in the form
8363 addr[/netmask] The netmask is optional, and can be either in the
8364 form a.b.c.d or as a number of valid top-most bits. Default is
8365 10.0.2.0/24.
8366 "host: string" (optional)
8368 guest-visible address of the host
8369 "tftp: string" (optional)
8371 root directory of the built-in TFTP server
8372 "bootfile: string" (optional)
8374 BOOTP filename, for use with tftp=
8375 "dhcpstart: string" (optional)
8377 the first of the 16 IPs the built-in DHCP server can assign
8378 "dns: string" (optional)
8380 guest-visible address of the virtual nameserver
8381 "dnssearch: array of String" (optional)
8383 list of DNS suffixes to search, passed as DHCP option to the guest
8384 "domainname: string" (optional)
8386 guest-visible domain name of the virtual nameserver (since 3.0)
8387 "ipv6-prefix: string" (optional)
8389 IPv6 network prefix (default is fec0::) (since 2.6). The network
8390 prefix is given in the usual hexadecimal IPv6 address notation.
8391 "ipv6-prefixlen: int" (optional)
8393 IPv6 network prefix length (default is 64) (since 2.6)
8394 "ipv6-host: string" (optional)
8396 guest-visible IPv6 address of the host (since 2.6)
8397 "ipv6-dns: string" (optional)
8399 guest-visible IPv6 address of the virtual nameserver (since 2.6)
8400 "smb: string" (optional)
8402 root directory of the built-in SMB server
8403 "smbserver: string" (optional)
8405 IP address of the built-in SMB server
8406 "hostfwd: array of String" (optional)
8408 redirect incoming TCP or UDP host connections to guest endpoints
8409 "guestfwd: array of String" (optional)
8411 forward guest TCP connections
8412 "tftp-server-name: string" (optional)
8414 RFC2132 "TFTP server name" string (Since 3.1)
8415 Since: 1.2
8417 NetdevTapOptions (Object)
8419 Used to configure a host TAP network interface backend.
8421 Members:
8423 "ifname: string" (optional)
8425 interface name
8426 "fd: string" (optional)
8428 file descriptor of an already opened tap
8429 "fds: string" (optional)
8431 multiple file descriptors of already opened multiqueue capable tap
8432 "script: string" (optional)
8434 script to initialize the interface
8435 "downscript: string" (optional)
8437 script to shut down the interface
8438 "br: string" (optional)
8440 bridge name (since 2.8)
8441 "helper: string" (optional)
8443 command to execute to configure bridge
8444 "sndbuf: int" (optional)
8446 send buffer limit. Understands [TGMKkb] suffixes.
8447 "vnet_hdr: boolean" (optional)
8449 enable the IFF_VNET_HDR flag on the tap interface
8450 "vhost: boolean" (optional)
8452 enable vhost-net network accelerator
8453 "vhostfd: string" (optional)
8455 file descriptor of an already opened vhost net device
8456 "vhostfds: string" (optional)
8458 file descriptors of multiple already opened vhost net devices
8459 "vhostforce: boolean" (optional)
8461 vhost on for non-MSIX virtio guests
8462 "queues: int" (optional)
8464 number of queues to be created for multiqueue capable tap
8465 "poll-us: int" (optional)
8467 maximum number of microseconds that could be spent on busy polling
8468 for tap (since 2.7)
8469 Since: 1.2
8471 NetdevSocketOptions (Object)
8473 Socket netdevs are used to establish a network connection to another
8475 QEMU virtual machine via a TCP socket.
8476 Members:
8478 "fd: string" (optional)
8480 file descriptor of an already opened socket
8481 "listen: string" (optional)
8483 port number, and optional hostname, to listen on
8484 "connect: string" (optional)
8486 port number, and optional hostname, to connect to
8487 "mcast: string" (optional)
8489 UDP multicast address and port number
8490 "localaddr: string" (optional)
8492 source address and port for multicast and udp packets
8493 "udp: string" (optional)
8495 UDP unicast address and port number
8496 Since: 1.2
8498 NetdevL2TPv3Options (Object)
8500 Configure an Ethernet over L2TPv3 tunnel.
8502 Members:
8504 "src: string"
8506 source address
8507 "dst: string"
8509 destination address
8510 "srcport: string" (optional)
8512 source port - mandatory for udp, optional for ip
8513 "dstport: string" (optional)
8515 destination port - mandatory for udp, optional for ip
8516 "ipv6: boolean" (optional)
8518 force the use of ipv6
8519 "udp: boolean" (optional)
8521 use the udp version of l2tpv3 encapsulation
8522 "cookie64: boolean" (optional)
8524 use 64 bit coookies
8525 "counter: boolean" (optional)
8527 have sequence counter
8528 "pincounter: boolean" (optional)
8530 pin sequence counter to zero - workaround for buggy implementations
8531 or networks with packet reorder
8532 "txcookie: int" (optional)
8534 32 or 64 bit transmit cookie
8535 "rxcookie: int" (optional)
8537 32 or 64 bit receive cookie
8538 "txsession: int"
8540 32 bit transmit session
8541 "rxsession: int" (optional)
8543 32 bit receive session - if not specified set to the same value as
8544 transmit
8545 "offset: int" (optional)
8547 additional offset - allows the insertion of additional application-
8548 specific data before the packet payload
8549 Since: 2.1
8551 NetdevVdeOptions (Object)
8553 Connect to a vde switch running on the host.
8555 Members:
8557 "sock: string" (optional)
8559 socket path
8560 "port: int" (optional)
8562 port number
8563 "group: string" (optional)
8565 group owner of socket
8566 "mode: int" (optional)
8568 permissions for socket
8569 Since: 1.2
8571 NetdevBridgeOptions (Object)
8573 Connect a host TAP network interface to a host bridge device.
8575 Members:
8577 "br: string" (optional)
8579 bridge name
8580 "helper: string" (optional)
8582 command to execute to configure bridge
8583 Since: 1.2
8585 NetdevHubPortOptions (Object)
8587 Connect two or more net clients through a software hub.
8589 Members:
8591 "hubid: int"
8593 hub identifier number
8594 "netdev: string" (optional)
8596 used to connect hub to a netdev instead of a device (since 2.12)
8597 Since: 1.2
8599 NetdevNetmapOptions (Object)
8601 Connect a client to a netmap-enabled NIC or to a VALE switch port
8603 Members:
8605 "ifname: string"
8607 Either the name of an existing network interface supported by
8608 netmap, or the name of a VALE port (created on the fly). A VALE
8609 port name is in the form 'valeXXX:YYY', where XXX and YYY are non-
8610 negative integers. XXX identifies a switch and YYY identifies a
8611 port of the switch. VALE ports having the same XXX are therefore
8612 connected to the same switch.
8613 "devname: string" (optional)
8615 path of the netmap device (default: '/dev/netmap').
8616 Since: 2.0
8618 NetdevVhostUserOptions (Object)
8620 Vhost-user network backend
8622 Members:
8624 "chardev: string"
8626 name of a unix socket chardev
8627 "vhostforce: boolean" (optional)
8629 vhost on for non-MSIX virtio guests (default: false).
8630 "queues: int" (optional)
8632 number of queues to be created for multiqueue vhost-user (default:
8633 1) (Since 2.5)
8634 Since: 2.1
8636 NetClientDriver (Enum)
8638 Available netdev drivers.
8640 Values:
8642 "none"
8644 Not documented
8645 "nic"
8647 Not documented
8648 "user"
8650 Not documented
8651 "tap"
8653 Not documented
8654 "l2tpv3"
8656 Not documented
8657 "socket"
8659 Not documented
8660 "vde"
8662 Not documented
8663 "bridge"
8665 Not documented
8666 "hubport"
8668 Not documented
8669 "netmap"
8671 Not documented
8672 "vhost-user"
8674 Not documented
8675 Since: 2.7
8677 'dump': dropped in 2.12
8679 Netdev (Object)
8681 Captures the configuration of a network device.
8683 Members:
8685 "id: string"
8687 identifier for monitor commands.
8688 "type: NetClientDriver"
8690 Specify the driver used for interpreting remaining arguments.
8691 The members of "NetLegacyNicOptions" when "type" is "nic"
8693 The members of "NetdevUserOptions" when "type" is "user"
8694 The members of "NetdevTapOptions" when "type" is "tap"
8695 The members of "NetdevL2TPv3Options" when "type" is "l2tpv3"
8696 The members of "NetdevSocketOptions" when "type" is "socket"
8697 The members of "NetdevVdeOptions" when "type" is "vde"
8698 The members of "NetdevBridgeOptions" when "type" is "bridge"
8699 The members of "NetdevHubPortOptions" when "type" is "hubport"
8700 The members of "NetdevNetmapOptions" when "type" is "netmap"
8701 The members of "NetdevVhostUserOptions" when "type" is "vhost-user"
8702 Since: 1.2
8704 'l2tpv3' - since 2.1
8706 NetLegacy (Object)
8708 Captures the configuration of a network device; legacy.
8710 Members:
8712 "id: string" (optional)
8714 identifier for monitor commands
8715 "name: string" (optional)
8717 identifier for monitor commands, ignored if "id" is present
8718 "opts: NetLegacyOptions"
8720 device type specific properties (legacy)
8721 Since: 1.2
8723 'vlan': dropped in 3.0
8725 NetLegacyOptionsType (Enum)
8727 Values:
8729 "none"
8731 Not documented
8732 "nic"
8734 Not documented
8735 "user"
8737 Not documented
8738 "tap"
8740 Not documented
8741 "l2tpv3"
8743 Not documented
8744 "socket"
8746 Not documented
8747 "vde"
8749 Not documented
8750 "bridge"
8752 Not documented
8753 "netmap"
8755 Not documented
8756 "vhost-user"
8758 Not documented
8759 Since: 1.2
8761 NetLegacyOptions (Object)
8763 Like Netdev, but for use only by the legacy command line options
8765 Members:
8767 "type: NetLegacyOptionsType"
8769 Not documented
8770 The members of "NetLegacyNicOptions" when "type" is "nic"
8772 The members of "NetdevUserOptions" when "type" is "user"
8773 The members of "NetdevTapOptions" when "type" is "tap"
8774 The members of "NetdevL2TPv3Options" when "type" is "l2tpv3"
8775 The members of "NetdevSocketOptions" when "type" is "socket"
8776 The members of "NetdevVdeOptions" when "type" is "vde"
8777 The members of "NetdevBridgeOptions" when "type" is "bridge"
8778 The members of "NetdevNetmapOptions" when "type" is "netmap"
8779 The members of "NetdevVhostUserOptions" when "type" is "vhost-user"
8780 Since: 1.2
8782 NetFilterDirection (Enum)
8784 Indicates whether a netfilter is attached to a netdev's transmit queue
8786 or receive queue or both.
8787 Values:
8789 "all"
8791 the filter is attached both to the receive and the transmit queue
8792 of the netdev (default).
8793 "rx"
8795 the filter is attached to the receive queue of the netdev, where it
8796 will receive packets sent to the netdev.
8797 "tx"
8799 the filter is attached to the transmit queue of the netdev, where
8800 it will receive packets sent by the netdev.
8801 Since: 2.5
8803 RxState (Enum)
8805 Packets receiving state
8807 Values:
8809 "normal"
8811 filter assigned packets according to the mac-table
8812 "none"
8814 don't receive any assigned packet
8815 "all"
8817 receive all assigned packets
8818 Since: 1.6
8820 RxFilterInfo (Object)
8822 Rx-filter information for a NIC.
8824 Members:
8826 "name: string"
8828 net client name
8829 "promiscuous: boolean"
8831 whether promiscuous mode is enabled
8832 "multicast: RxState"
8834 multicast receive state
8835 "unicast: RxState"
8837 unicast receive state
8838 "vlan: RxState"
8840 vlan receive state (Since 2.0)
8841 "broadcast-allowed: boolean"
8843 whether to receive broadcast
8844 "multicast-overflow: boolean"
8846 multicast table is overflowed or not
8847 "unicast-overflow: boolean"
8849 unicast table is overflowed or not
8850 "main-mac: string"
8852 the main macaddr string
8853 "vlan-table: array of int"
8855 a list of active vlan id
8856 "unicast-table: array of string"
8858 a list of unicast macaddr string
8859 "multicast-table: array of string"
8861 a list of multicast macaddr string
8862 Since: 1.6
8864 query-rx-filter (Command) Return rx-filter information for all NICs
8866 (or for the given NIC).
8867 Arguments:
8869 "name: string" (optional)
8871 net client name
8872 Returns: list of "RxFilterInfo" for all NICs (or for the given NIC).
8874 Returns an error if the given "name" doesn't exist, or given NIC
8875 doesn't support rx-filter querying, or given net client isn't a NIC.
8876 Since: 1.6
8878 Example:
8880 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
8882 <- { "return": [
8883 {
8884 "promiscuous": true,
8885 "name": "vnet0",
8886 "main-mac": "52:54:00:12:34:56",
8887 "unicast": "normal",
8888 "vlan": "normal",
8889 "vlan-table": [
8890 4,
8891 0
8892 ],
8893 "unicast-table": [
8894 ],
8895 "multicast": "normal",
8896 "multicast-overflow": false,
8897 "unicast-overflow": false,
8898 "multicast-table": [
8899 "01:00:5e:00:00:01",
8900 "33:33:00:00:00:01",
8901 "33:33:ff:12:34:56"
8902 ],
8903 "broadcast-allowed": false
8904 }
8905 ]
8906 }
8907 NIC_RX_FILTER_CHANGED (Event) Emitted once until the 'query-rx-filter'
8909 command is executed, the first event will always be emitted
8910 Arguments:
8912 "name: string" (optional)
8914 net client name
8915 "path: string"
8917 device path
8918 Since: 1.6
8920 Example:
8922 <- { "event": "NIC_RX_FILTER_CHANGED",
8924 "data": { "name": "vnet0",
8925 "path": "/machine/peripheral/vnet0/virtio-backend" },
8926 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
8927 }
8928 AnnounceParameters (Object)
8930 Parameters for self-announce timers
8932 Members:
8934 "initial: int"
8936 Initial delay (in ms) before sending the first GARP/RARP
8937 announcement
8938 "max: int"
8940 Maximum delay (in ms) between GARP/RARP announcement packets
8941 "rounds: int"
8943 Number of self-announcement attempts
8944 "step: int"
8946 Delay increase (in ms) after each self-announcement attempt
8947 "interfaces: array of string" (optional)
8949 An optional list of interface names, which restricts the
8950 announcement to the listed interfaces. (Since 4.1)
8951 "id: string" (optional)
8953 A name to be used to identify an instance of announce-timers and to
8954 allow it to modified later. Not for use as part of the migration
8955 parameters. (Since 4.1)
8956 Since: 4.0
8958 announce-self (Command) Trigger generation of broadcast RARP frames to
8960 update network switches. This can be useful when network bonds fail-
8961 over the active slave.
8962 Arguments: the members of "AnnounceParameters"
8964 Example:
8966 -> { "execute": "announce-self",
8968 "arguments": {
8969 "initial": 50, "max": 550, "rounds": 10, "step": 50,
8970 "interfaces": ["vn2", "vn3"], "id": "bob" } }
8971 <- { "return": {} }
8972 Since: 4.0
8974 RDMA device
8976 RDMA_GID_STATUS_CHANGED (Event) Emitted when guest driver adds/deletes
8977 GID to/from device
8978 Arguments:
8980 "netdev: string"
8982 RoCE Network Device name
8983 "gid-status: boolean"
8985 Add or delete indication
8986 "subnet-prefix: int"
8988 Subnet Prefix
8989 "interface-id: int"
8991 Not documented
8992 "interface-id" : Interface ID
8994 Since: 4.0
8996 Example:
8998 <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760},
9000 "event": "RDMA_GID_STATUS_CHANGED",
9001 "data":
9002 {"netdev": "bridge0",
9003 "interface-id": 15880512517475447892,
9004 "gid-status": true,
9005 "subnet-prefix": 33022}}
9006 Rocker switch device
9008 RockerSwitch (Object)
9009 Rocker switch information.
9011 Members:
9013 "name: string"
9015 switch name
9016 "id: int"
9018 switch ID
9019 "ports: int"
9021 number of front-panel ports
9022 Since: 2.4
9024 query-rocker (Command) Return rocker switch information.
9026 Arguments:
9028 "name: string"
9030 Not documented
9031 Returns: "Rocker" information
9033 Since: 2.4
9035 Example:
9037 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
9039 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
9040 RockerPortDuplex (Enum)
9042 An eumeration of port duplex states.
9044 Values:
9046 "half"
9048 half duplex
9049 "full"
9051 full duplex
9052 Since: 2.4
9054 RockerPortAutoneg (Enum)
9056 An eumeration of port autoneg states.
9058 Values:
9060 "off"
9062 autoneg is off
9063 "on"
9065 autoneg is on
9066 Since: 2.4
9068 RockerPort (Object)
9070 Rocker switch port information.
9072 Members:
9074 "name: string"
9076 port name
9077 "enabled: boolean"
9079 port is enabled for I/O
9080 "link-up: boolean"
9082 physical link is UP on port
9083 "speed: int"
9085 port link speed in Mbps
9086 "duplex: RockerPortDuplex"
9088 port link duplex
9089 "autoneg: RockerPortAutoneg"
9091 port link autoneg
9092 Since: 2.4
9094 query-rocker-ports (Command) Return rocker switch port information.
9096 Arguments:
9098 "name: string"
9100 Not documented
9101 Returns: a list of "RockerPort" information
9103 Since: 2.4
9105 Example:
9107 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
9109 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
9110 "autoneg": "off", "link-up": true, "speed": 10000},
9111 {"duplex": "full", "enabled": true, "name": "sw1.2",
9112 "autoneg": "off", "link-up": true, "speed": 10000}
9113 ]}
9114 RockerOfDpaFlowKey (Object)
9116 Rocker switch OF-DPA flow key
9118 Members:
9120 "priority: int"
9122 key priority, 0 being lowest priority
9123 "tbl-id: int"
9125 flow table ID
9126 "in-pport: int" (optional)
9128 physical input port
9129 "tunnel-id: int" (optional)
9131 tunnel ID
9132 "vlan-id: int" (optional)
9134 VLAN ID
9135 "eth-type: int" (optional)
9137 Ethernet header type
9138 "eth-src: string" (optional)
9140 Ethernet header source MAC address
9141 "eth-dst: string" (optional)
9143 Ethernet header destination MAC address
9144 "ip-proto: int" (optional)
9146 IP Header protocol field
9147 "ip-tos: int" (optional)
9149 IP header TOS field
9150 "ip-dst: string" (optional)
9152 IP header destination address
9153 Note: optional members may or may not appear in the flow key depending
9155 if they're relevant to the flow key.
9156 Since: 2.4
9158 RockerOfDpaFlowMask (Object)
9160 Rocker switch OF-DPA flow mask
9162 Members:
9164 "in-pport: int" (optional)
9166 physical input port
9167 "tunnel-id: int" (optional)
9169 tunnel ID
9170 "vlan-id: int" (optional)
9172 VLAN ID
9173 "eth-src: string" (optional)
9175 Ethernet header source MAC address
9176 "eth-dst: string" (optional)
9178 Ethernet header destination MAC address
9179 "ip-proto: int" (optional)
9181 IP Header protocol field
9182 "ip-tos: int" (optional)
9184 IP header TOS field
9185 Note: optional members may or may not appear in the flow mask depending
9187 if they're relevant to the flow mask.
9188 Since: 2.4
9190 RockerOfDpaFlowAction (Object)
9192 Rocker switch OF-DPA flow action
9194 Members:
9196 "goto-tbl: int" (optional)
9198 next table ID
9199 "group-id: int" (optional)
9201 group ID
9202 "tunnel-lport: int" (optional)
9204 tunnel logical port ID
9205 "vlan-id: int" (optional)
9207 VLAN ID
9208 "new-vlan-id: int" (optional)
9210 new VLAN ID
9211 "out-pport: int" (optional)
9213 physical output port
9214 Note: optional members may or may not appear in the flow action
9216 depending if they're relevant to the flow action.
9217 Since: 2.4
9219 RockerOfDpaFlow (Object)
9221 Rocker switch OF-DPA flow
9223 Members:
9225 "cookie: int"
9227 flow unique cookie ID
9228 "hits: int"
9230 count of matches (hits) on flow
9231 "key: RockerOfDpaFlowKey"
9233 flow key
9234 "mask: RockerOfDpaFlowMask"
9236 flow mask
9237 "action: RockerOfDpaFlowAction"
9239 flow action
9240 Since: 2.4
9242 query-rocker-of-dpa-flows (Command) Return rocker OF-DPA flow
9244 information.
9245 Arguments:
9247 "name: string"
9249 switch name
9250 "tbl-id: int" (optional)
9252 flow table ID. If tbl-id is not specified, returns flow
9253 information for all tables.
9254 Returns: rocker OF-DPA flow information
9256 Since: 2.4
9258 Example:
9260 -> { "execute": "query-rocker-of-dpa-flows",
9262 "arguments": { "name": "sw1" } }
9263 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
9264 "hits": 138,
9265 "cookie": 0,
9266 "action": {"goto-tbl": 10},
9267 "mask": {"in-pport": 4294901760}
9268 },
9269 {...more...},
9270 ]}
9271 RockerOfDpaGroup (Object)
9273 Rocker switch OF-DPA group
9275 Members:
9277 "id: int"
9279 group unique ID
9280 "type: int"
9282 group type
9283 "vlan-id: int" (optional)
9285 VLAN ID
9286 "pport: int" (optional)
9288 physical port number
9289 "index: int" (optional)
9291 group index, unique with group type
9292 "out-pport: int" (optional)
9294 output physical port number
9295 "group-id: int" (optional)
9297 next group ID
9298 "set-vlan-id: int" (optional)
9300 VLAN ID to set
9301 "pop-vlan: int" (optional)
9303 pop VLAN headr from packet
9304 "group-ids: array of int" (optional)
9306 list of next group IDs
9307 "set-eth-src: string" (optional)
9309 set source MAC address in Ethernet header
9310 "set-eth-dst: string" (optional)
9312 set destination MAC address in Ethernet header
9313 "ttl-check: int" (optional)
9315 perform TTL check
9316 Note: optional members may or may not appear in the group depending if
9318 they're relevant to the group type.
9319 Since: 2.4
9321 query-rocker-of-dpa-groups (Command) Return rocker OF-DPA group
9323 information.
9324 Arguments:
9326 "name: string"
9328 switch name
9329 "type: int" (optional)
9331 group type. If type is not specified, returns group information
9332 for all group types.
9333 Returns: rocker OF-DPA group information
9335 Since: 2.4
9337 Example:
9339 -> { "execute": "query-rocker-of-dpa-groups",
9341 "arguments": { "name": "sw1" } }
9342 <- { "return": [ {"type": 0, "out-pport": 2,
9343 "pport": 2, "vlan-id": 3841,
9344 "pop-vlan": 1, "id": 251723778},
9345 {"type": 0, "out-pport": 0,
9346 "pport": 0, "vlan-id": 3841,
9347 "pop-vlan": 1, "id": 251723776},
9348 {"type": 0, "out-pport": 1,
9349 "pport": 1, "vlan-id": 3840,
9350 "pop-vlan": 1, "id": 251658241},
9351 {"type": 0, "out-pport": 0,
9352 "pport": 0, "vlan-id": 3840,
9353 "pop-vlan": 1, "id": 251658240}
9354 ]}
9355 TPM (trusted platform module) devices
9357 TpmModel (Enum)
9358 An enumeration of TPM models
9360 Values:
9362 "tpm-tis"
9364 TPM TIS model
9365 "tpm-crb"
9367 TPM CRB model (since 2.12)
9368 Since: 1.5
9370 query-tpm-models (Command) Return a list of supported TPM models
9372 Returns: a list of TpmModel
9374 Since: 1.5
9376 Example:
9378 -> { "execute": "query-tpm-models" }
9380 <- { "return": [ "tpm-tis", "tpm-crb" ] }
9381 TpmType (Enum)
9383 An enumeration of TPM types
9385 Values:
9387 "passthrough"
9389 TPM passthrough type
9390 "emulator"
9392 Software Emulator TPM type Since: 2.11
9393 Since: 1.5
9395 query-tpm-types (Command) Return a list of supported TPM types
9397 Returns: a list of TpmType
9399 Since: 1.5
9401 Example:
9403 -> { "execute": "query-tpm-types" }
9405 <- { "return": [ "passthrough", "emulator" ] }
9406 TPMPassthroughOptions (Object)
9408 Information about the TPM passthrough type
9410 Members:
9412 "path: string" (optional)
9414 string describing the path used for accessing the TPM device
9415 "cancel-path: string" (optional)
9417 string showing the TPM's sysfs cancel file for cancellation of TPM
9418 commands while they are executing
9419 Since: 1.5
9421 TPMEmulatorOptions (Object)
9423 Information about the TPM emulator type
9425 Members:
9427 "chardev: string"
9429 Name of a unix socket chardev
9430 Since: 2.11
9432 TpmTypeOptions (Object)
9434 A union referencing different TPM backend types' configuration options
9436 Members:
9438 "type"
9440 'passthrough' The configuration options for the TPM passthrough
9441 type 'emulator' The configuration options for TPM emulator backend
9442 type
9443 "data: TPMPassthroughOptions" when "type" is "passthrough"
9445 "data: TPMEmulatorOptions" when "type" is "emulator"
9446 Since: 1.5
9448 TPMInfo (Object)
9450 Information about the TPM
9452 Members:
9454 "id: string"
9456 The Id of the TPM
9457 "model: TpmModel"
9459 The TPM frontend model
9460 "options: TpmTypeOptions"
9462 The TPM (backend) type configuration options
9463 Since: 1.5
9465 query-tpm (Command) Return information about the TPM device
9467 Returns: "TPMInfo" on success
9469 Since: 1.5
9471 Example:
9473 -> { "execute": "query-tpm" }
9475 <- { "return":
9476 [
9477 { "model": "tpm-tis",
9478 "options":
9479 { "type": "passthrough",
9480 "data":
9481 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
9482 "path": "/dev/tpm0"
9483 }
9484 },
9485 "id": "tpm0"
9486 }
9487 ]
9488 }
9489 Remote desktop
9491 set_password (Command) Sets the password of a remote display session.
9492 Arguments:
9494 "protocol: string"
9496 `vnc' to modify the VNC server password `spice' to modify the Spice
9497 server password
9498 "password: string"
9500 the new password
9501 "connected: string" (optional)
9503 how to handle existing clients when changing the password. If
9504 nothing is specified, defaults to `keep' `fail' to fail the command
9505 if clients are connected `disconnect' to disconnect existing
9506 clients `keep' to maintain existing clients
9507 Returns: Nothing on success If Spice is not enabled, DeviceNotFound
9509 Since: 0.14.0
9511 Example:
9513 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
9515 "password": "secret" } }
9516 <- { "return": {} }
9517 expire_password (Command) Expire the password of a remote display
9519 server.
9520 Arguments:
9522 "protocol: string"
9524 the name of the remote display protocol `vnc' or `spice'
9525 "time: string"
9527 when to expire the password. `now' to expire the password
9528 immediately `never' to cancel password expiration `+INT' where INT
9529 is the number of seconds from now (integer) `INT' where INT is the
9530 absolute time in seconds
9531 Returns: Nothing on success If "protocol" is `spice' and Spice is not
9533 active, DeviceNotFound
9534 Since: 0.14.0
9536 Notes: Time is relative to the server and currently there is no way to
9538 coordinate server time with client time. It is not recommended to use
9539 the absolute time version of the "time" parameter unless you're sure
9540 you are on the same machine as the QEMU instance.
9541 Example:
9543 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
9545 "time": "+60" } }
9546 <- { "return": {} }
9547 screendump (Command) Write a PPM of the VGA screen to a file.
9549 Arguments:
9551 "filename: string"
9553 the path of a new PPM file to store the image
9554 "device: string" (optional)
9556 ID of the display device that should be dumped. If this parameter
9557 is missing, the primary display will be used. (Since 2.12)
9558 "head: int" (optional)
9560 head to use in case the device supports multiple heads. If this
9561 parameter is missing, head #0 will be used. Also note that the head
9562 can only be specified in conjunction with the device ID. (Since
9563 2.12)
9564 Returns: Nothing on success
9566 Since: 0.14.0
9568 Example:
9570 -> { "execute": "screendump",
9572 "arguments": { "filename": "/tmp/image" } }
9573 <- { "return": {} }
9574 Spice
9576 SpiceBasicInfo (Object)
9578 The basic information for SPICE network connection
9580 Members:
9582 "host: string"
9584 IP address
9585 "port: string"
9587 port number
9588 "family: NetworkAddressFamily"
9590 address family
9591 Since: 2.1
9593 If: "defined(CONFIG_SPICE)"
9595 SpiceServerInfo (Object)
9597 Information about a SPICE server
9599 Members:
9601 "auth: string" (optional)
9603 authentication method
9604 The members of "SpiceBasicInfo"
9606 Since: 2.1
9608 If: "defined(CONFIG_SPICE)"
9610 SpiceChannel (Object)
9612 Information about a SPICE client channel.
9614 Members:
9616 "connection-id: int"
9618 SPICE connection id number. All channels with the same id belong
9619 to the same SPICE session.
9620 "channel-type: int"
9622 SPICE channel type number. "1" is the main control channel, filter
9623 for this one if you want to track spice sessions only
9624 "channel-id: int"
9626 SPICE channel ID number. Usually "0", might be different when
9627 multiple channels of the same type exist, such as multiple display
9628 channels in a multihead setup
9629 "tls: boolean"
9631 true if the channel is encrypted, false otherwise.
9632 The members of "SpiceBasicInfo"
9634 Since: 0.14.0
9636 If: "defined(CONFIG_SPICE)"
9638 SpiceQueryMouseMode (Enum)
9640 An enumeration of Spice mouse states.
9642 Values:
9644 "client"
9646 Mouse cursor position is determined by the client.
9647 "server"
9649 Mouse cursor position is determined by the server.
9650 "unknown"
9652 No information is available about mouse mode used by the spice
9653 server.
9654 Note: spice/enums.h has a SpiceMouseMode already, hence the name.
9656 Since: 1.1
9658 If: "defined(CONFIG_SPICE)"
9660 SpiceInfo (Object)
9662 Information about the SPICE session.
9664 Members:
9666 "enabled: boolean"
9668 true if the SPICE server is enabled, false otherwise
9669 "migrated: boolean"
9671 true if the last guest migration completed and spice migration had
9672 completed as well. false otherwise. (since 1.4)
9673 "host: string" (optional)
9675 The hostname the SPICE server is bound to. This depends on the
9676 name resolution on the host and may be an IP address.
9677 "port: int" (optional)
9679 The SPICE server's port number.
9680 "compiled-version: string" (optional)
9682 SPICE server version.
9683 "tls-port: int" (optional)
9685 The SPICE server's TLS port number.
9686 "auth: string" (optional)
9688 the current authentication type used by the server 'none' if no
9689 authentication is being used 'spice' uses SASL or direct TLS
9690 authentication, depending on command line options
9691 "mouse-mode: SpiceQueryMouseMode"
9693 The mode in which the mouse cursor is displayed currently. Can be
9694 determined by the client or the server, or unknown if spice server
9695 doesn't provide this information. (since: 1.1)
9696 "channels: array of SpiceChannel" (optional)
9698 a list of "SpiceChannel" for each active spice channel
9699 Since: 0.14.0
9701 If: "defined(CONFIG_SPICE)"
9703 query-spice (Command) Returns information about the current SPICE
9705 server
9706 Returns: "SpiceInfo"
9708 Since: 0.14.0
9710 Example:
9712 -> { "execute": "query-spice" }
9714 <- { "return": {
9715 "enabled": true,
9716 "auth": "spice",
9717 "port": 5920,
9718 "tls-port": 5921,
9719 "host": "0.0.0.0",
9720 "channels": [
9721 {
9722 "port": "54924",
9723 "family": "ipv4",
9724 "channel-type": 1,
9725 "connection-id": 1804289383,
9726 "host": "127.0.0.1",
9727 "channel-id": 0,
9728 "tls": true
9729 },
9730 {
9731 "port": "36710",
9732 "family": "ipv4",
9733 "channel-type": 4,
9734 "connection-id": 1804289383,
9735 "host": "127.0.0.1",
9736 "channel-id": 0,
9737 "tls": false
9738 },
9739 [ ... more channels follow ... ]
9740 ]
9741 }
9742 }
9743 If: "defined(CONFIG_SPICE)"
9745 SPICE_CONNECTED (Event) Emitted when a SPICE client establishes a
9747 connection
9748 Arguments:
9750 "server: SpiceBasicInfo"
9752 server information
9753 "client: SpiceBasicInfo"
9755 client information
9756 Since: 0.14.0
9758 Example:
9760 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
9762 "event": "SPICE_CONNECTED",
9763 "data": {
9764 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
9765 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
9766 }}
9767 If: "defined(CONFIG_SPICE)"
9769 SPICE_INITIALIZED (Event) Emitted after initial handshake and
9771 authentication takes place (if any) and the SPICE channel is up and
9772 running
9773 Arguments:
9775 "server: SpiceServerInfo"
9777 server information
9778 "client: SpiceChannel"
9780 client information
9781 Since: 0.14.0
9783 Example:
9785 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
9787 "event": "SPICE_INITIALIZED",
9788 "data": {"server": {"auth": "spice", "port": "5921",
9789 "family": "ipv4", "host": "127.0.0.1"},
9790 "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
9791 "connection-id": 1804289383, "host": "127.0.0.1",
9792 "channel-id": 0, "tls": true}
9793 }}
9794 If: "defined(CONFIG_SPICE)"
9796 SPICE_DISCONNECTED (Event) Emitted when the SPICE connection is closed
9798 Arguments:
9800 "server: SpiceBasicInfo"
9802 server information
9803 "client: SpiceBasicInfo"
9805 client information
9806 Since: 0.14.0
9808 Example:
9810 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
9812 "event": "SPICE_DISCONNECTED",
9813 "data": {
9814 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
9815 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
9816 }}
9817 If: "defined(CONFIG_SPICE)"
9819 SPICE_MIGRATE_COMPLETED (Event) Emitted when SPICE migration has
9821 completed
9822 Since: 1.3
9824 Example:
9826 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
9828 "event": "SPICE_MIGRATE_COMPLETED" }
9829 If: "defined(CONFIG_SPICE)"
9831 VNC
9833 VncBasicInfo (Object)
9835 The basic information for vnc network connection
9837 Members:
9839 "host: string"
9841 IP address
9842 "service: string"
9844 The service name of the vnc port. This may depend on the host
9845 system's service database so symbolic names should not be relied
9846 on.
9847 "family: NetworkAddressFamily"
9849 address family
9850 "websocket: boolean"
9852 true in case the socket is a websocket (since 2.3).
9853 Since: 2.1
9855 If: "defined(CONFIG_VNC)"
9857 VncServerInfo (Object)
9859 The network connection information for server
9861 Members:
9863 "auth: string" (optional)
9865 authentication method used for the plain (non-websocket) VNC server
9866 The members of "VncBasicInfo"
9868 Since: 2.1
9870 If: "defined(CONFIG_VNC)"
9872 VncClientInfo (Object)
9874 Information about a connected VNC client.
9876 Members:
9878 "x509_dname: string" (optional)
9880 If x509 authentication is in use, the Distinguished Name of the
9881 client.
9882 "sasl_username: string" (optional)
9884 If SASL authentication is in use, the SASL username used for
9885 authentication.
9886 The members of "VncBasicInfo"
9888 Since: 0.14.0
9890 If: "defined(CONFIG_VNC)"
9892 VncInfo (Object)
9894 Information about the VNC session.
9896 Members:
9898 "enabled: boolean"
9900 true if the VNC server is enabled, false otherwise
9901 "host: string" (optional)
9903 The hostname the VNC server is bound to. This depends on the name
9904 resolution on the host and may be an IP address.
9905 "family: NetworkAddressFamily" (optional)
9907 'ipv6' if the host is listening for IPv6 connections 'ipv4' if the
9908 host is listening for IPv4 connections 'unix' if the host is
9909 listening on a unix domain socket 'unknown' otherwise
9910 "service: string" (optional)
9912 The service name of the server's port. This may depends on the
9913 host system's service database so symbolic names should not be
9914 relied on.
9915 "auth: string" (optional)
9917 the current authentication type used by the server 'none' if no
9918 authentication is being used 'vnc' if VNC authentication is being
9919 used 'vencrypt+plain' if VEncrypt is used with plain text
9920 authentication 'vencrypt+tls+none' if VEncrypt is used with TLS and
9921 no authentication 'vencrypt+tls+vnc' if VEncrypt is used with TLS
9922 and VNC authentication 'vencrypt+tls+plain' if VEncrypt is used
9923 with TLS and plain text auth 'vencrypt+x509+none' if VEncrypt is
9924 used with x509 and no auth 'vencrypt+x509+vnc' if VEncrypt is used
9925 with x509 and VNC auth 'vencrypt+x509+plain' if VEncrypt is used
9926 with x509 and plain text auth 'vencrypt+tls+sasl' if VEncrypt is
9927 used with TLS and SASL auth 'vencrypt+x509+sasl' if VEncrypt is
9928 used with x509 and SASL auth
9929 "clients: array of VncClientInfo" (optional)
9931 a list of "VncClientInfo" of all currently connected clients
9932 Since: 0.14.0
9934 If: "defined(CONFIG_VNC)"
9936 VncPrimaryAuth (Enum)
9938 vnc primary authentication method.
9940 Values:
9942 "none"
9944 Not documented
9945 "vnc"
9947 Not documented
9948 "ra2"
9950 Not documented
9951 "ra2ne"
9953 Not documented
9954 "tight"
9956 Not documented
9957 "ultra"
9959 Not documented
9960 "tls"
9962 Not documented
9963 "vencrypt"
9965 Not documented
9966 "sasl"
9968 Not documented
9969 Since: 2.3
9971 If: "defined(CONFIG_VNC)"
9973 VncVencryptSubAuth (Enum)
9975 vnc sub authentication method with vencrypt.
9977 Values:
9979 "plain"
9981 Not documented
9982 "tls-none"
9984 Not documented
9985 "x509-none"
9987 Not documented
9988 "tls-vnc"
9990 Not documented
9991 "x509-vnc"
9993 Not documented
9994 "tls-plain"
9996 Not documented
9997 "x509-plain"
9999 Not documented
10000 "tls-sasl"
10002 Not documented
10003 "x509-sasl"
10005 Not documented
10006 Since: 2.3
10008 If: "defined(CONFIG_VNC)"
10010 VncServerInfo2 (Object)
10012 The network connection information for server
10014 Members:
10016 "auth: VncPrimaryAuth"
10018 The current authentication type used by the servers
10019 "vencrypt: VncVencryptSubAuth" (optional)
10021 The vencrypt sub authentication type used by the servers, only
10022 specified in case auth == vencrypt.
10023 The members of "VncBasicInfo"
10025 Since: 2.9
10027 If: "defined(CONFIG_VNC)"
10029 VncInfo2 (Object)
10031 Information about a vnc server
10033 Members:
10035 "id: string"
10037 vnc server name.
10038 "server: array of VncServerInfo2"
10040 A list of "VncBasincInfo" describing all listening sockets. The
10041 list can be empty (in case the vnc server is disabled). It also
10042 may have multiple entries: normal + websocket, possibly also ipv4 +
10043 ipv6 in the future.
10044 "clients: array of VncClientInfo"
10046 A list of "VncClientInfo" of all currently connected clients. The
10047 list can be empty, for obvious reasons.
10048 "auth: VncPrimaryAuth"
10050 The current authentication type used by the non-websockets servers
10051 "vencrypt: VncVencryptSubAuth" (optional)
10053 The vencrypt authentication type used by the servers, only
10054 specified in case auth == vencrypt.
10055 "display: string" (optional)
10057 The display device the vnc server is linked to.
10058 Since: 2.3
10060 If: "defined(CONFIG_VNC)"
10062 query-vnc (Command) Returns information about the current VNC server
10064 Returns: "VncInfo"
10066 Since: 0.14.0
10068 Example:
10070 -> { "execute": "query-vnc" }
10072 <- { "return": {
10073 "enabled":true,
10074 "host":"0.0.0.0",
10075 "service":"50402",
10076 "auth":"vnc",
10077 "family":"ipv4",
10078 "clients":[
10079 {
10080 "host":"127.0.0.1",
10081 "service":"50401",
10082 "family":"ipv4"
10083 }
10084 ]
10085 }
10086 }
10087 If: "defined(CONFIG_VNC)"
10089 query-vnc-servers (Command) Returns a list of vnc servers. The list
10091 can be empty.
10092 Returns: a list of "VncInfo2"
10094 Since: 2.3
10096 If: "defined(CONFIG_VNC)"
10098 change-vnc-password (Command) Change the VNC server password.
10100 Arguments:
10102 "password: string"
10104 the new password to use with VNC authentication
10105 Since: 1.1
10107 Notes: An empty password in this command will set the password to the
10109 empty string. Existing clients are unaffected by executing this
10110 command.
10111 If: "defined(CONFIG_VNC)"
10113 VNC_CONNECTED (Event) Emitted when a VNC client establishes a
10115 connection
10116 Arguments:
10118 "server: VncServerInfo"
10120 server information
10121 "client: VncBasicInfo"
10123 client information
10124 Note: This event is emitted before any authentication takes place, thus
10126 the authentication ID is not provided
10127 Since: 0.13.0
10129 Example:
10131 <- { "event": "VNC_CONNECTED",
10133 "data": {
10134 "server": { "auth": "sasl", "family": "ipv4",
10135 "service": "5901", "host": "0.0.0.0" },
10136 "client": { "family": "ipv4", "service": "58425",
10137 "host": "127.0.0.1" } },
10138 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
10139 If: "defined(CONFIG_VNC)"
10141 VNC_INITIALIZED (Event) Emitted after authentication takes place (if
10143 any) and the VNC session is made active
10144 Arguments:
10146 "server: VncServerInfo"
10148 server information
10149 "client: VncClientInfo"
10151 client information
10152 Since: 0.13.0
10154 Example:
10156 <- { "event": "VNC_INITIALIZED",
10158 "data": {
10159 "server": { "auth": "sasl", "family": "ipv4",
10160 "service": "5901", "host": "0.0.0.0"},
10161 "client": { "family": "ipv4", "service": "46089",
10162 "host": "127.0.0.1", "sasl_username": "luiz" } },
10163 "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
10164 If: "defined(CONFIG_VNC)"
10166 VNC_DISCONNECTED (Event) Emitted when the connection is closed
10168 Arguments:
10170 "server: VncServerInfo"
10172 server information
10173 "client: VncClientInfo"
10175 client information
10176 Since: 0.13.0
10178 Example:
10180 <- { "event": "VNC_DISCONNECTED",
10182 "data": {
10183 "server": { "auth": "sasl", "family": "ipv4",
10184 "service": "5901", "host": "0.0.0.0" },
10185 "client": { "family": "ipv4", "service": "58425",
10186 "host": "127.0.0.1", "sasl_username": "luiz" } },
10187 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
10188 If: "defined(CONFIG_VNC)"
10190 Input
10192 MouseInfo (Object)
10193 Information about a mouse device.
10195 Members:
10197 "name: string"
10199 the name of the mouse device
10200 "index: int"
10202 the index of the mouse device
10203 "current: boolean"
10205 true if this device is currently receiving mouse events
10206 "absolute: boolean"
10208 true if this device supports absolute coordinates as input
10209 Since: 0.14.0
10211 query-mice (Command) Returns information about each active mouse
10213 device
10214 Returns: a list of "MouseInfo" for each device
10216 Since: 0.14.0
10218 Example:
10220 -> { "execute": "query-mice" }
10222 <- { "return": [
10223 {
10224 "name":"QEMU Microsoft Mouse",
10225 "index":0,
10226 "current":false,
10227 "absolute":false
10228 },
10229 {
10230 "name":"QEMU PS/2 Mouse",
10231 "index":1,
10232 "current":true,
10233 "absolute":true
10234 }
10235 ]
10236 }
10237 QKeyCode (Enum)
10239 An enumeration of key name.
10241 This is used by the "send-key" command.
10243 Values:
10245 "unmapped"
10247 since 2.0
10248 "pause"
10250 since 2.0
10251 "ro"
10253 since 2.4
10254 "kp_comma"
10256 since 2.4
10257 "kp_equals"
10259 since 2.6
10260 "power"
10262 since 2.6
10263 "hiragana"
10265 since 2.9
10266 "henkan"
10268 since 2.9
10269 "yen"
10271 since 2.9
10272 "sleep"
10274 since 2.10
10275 "wake"
10277 since 2.10
10278 "audionext"
10280 since 2.10
10281 "audioprev"
10283 since 2.10
10284 "audiostop"
10286 since 2.10
10287 "audioplay"
10289 since 2.10
10290 "audiomute"
10292 since 2.10
10293 "volumeup"
10295 since 2.10
10296 "volumedown"
10298 since 2.10
10299 "mediaselect"
10301 since 2.10
10302 "mail"
10304 since 2.10
10305 "calculator"
10307 since 2.10
10308 "computer"
10310 since 2.10
10311 "ac_home"
10313 since 2.10
10314 "ac_back"
10316 since 2.10
10317 "ac_forward"
10319 since 2.10
10320 "ac_refresh"
10322 since 2.10
10323 "ac_bookmarks"
10325 since 2.10 altgr, altgr_r: dropped in 2.10
10326 "muhenkan"
10328 since 2.12
10329 "katakanahiragana"
10331 since 2.12
10332 "shift"
10334 Not documented
10335 "shift_r"
10337 Not documented
10338 "alt"
10340 Not documented
10341 "alt_r"
10343 Not documented
10344 "ctrl"
10346 Not documented
10347 "ctrl_r"
10349 Not documented
10350 "menu"
10352 Not documented
10353 "esc"
10355 Not documented
10356 1 Not documented
10358 2 Not documented
10360 3 Not documented
10362 4 Not documented
10364 5 Not documented
10366 6 Not documented
10368 7 Not documented
10370 8 Not documented
10372 9 Not documented
10374 0 Not documented
10376 "minus"
10378 Not documented
10379 "equal"
10381 Not documented
10382 "backspace"
10384 Not documented
10385 "tab"
10387 Not documented
10388 "q" Not documented
10390 "w" Not documented
10392 "e" Not documented
10394 "r" Not documented
10396 "t" Not documented
10398 "y" Not documented
10400 "u" Not documented
10402 "i" Not documented
10404 "o" Not documented
10406 "p" Not documented
10408 "bracket_left"
10410 Not documented
10411 "bracket_right"
10413 Not documented
10414 "ret"
10416 Not documented
10417 "a" Not documented
10419 "s" Not documented
10421 "d" Not documented
10423 "f" Not documented
10425 "g" Not documented
10427 "h" Not documented
10429 "j" Not documented
10431 "k" Not documented
10433 "l" Not documented
10435 "semicolon"
10437 Not documented
10438 "apostrophe"
10440 Not documented
10441 "grave_accent"
10443 Not documented
10444 "backslash"
10446 Not documented
10447 "z" Not documented
10449 "x" Not documented
10451 "c" Not documented
10453 "v" Not documented
10455 "b" Not documented
10457 "n" Not documented
10459 "m" Not documented
10461 "comma"
10463 Not documented
10464 "dot"
10466 Not documented
10467 "slash"
10469 Not documented
10470 "asterisk"
10472 Not documented
10473 "spc"
10475 Not documented
10476 "caps_lock"
10478 Not documented
10479 "f1"
10481 Not documented
10482 "f2"
10484 Not documented
10485 "f3"
10487 Not documented
10488 "f4"
10490 Not documented
10491 "f5"
10493 Not documented
10494 "f6"
10496 Not documented
10497 "f7"
10499 Not documented
10500 "f8"
10502 Not documented
10503 "f9"
10505 Not documented
10506 "f10"
10508 Not documented
10509 "num_lock"
10511 Not documented
10512 "scroll_lock"
10514 Not documented
10515 "kp_divide"
10517 Not documented
10518 "kp_multiply"
10520 Not documented
10521 "kp_subtract"
10523 Not documented
10524 "kp_add"
10526 Not documented
10527 "kp_enter"
10529 Not documented
10530 "kp_decimal"
10532 Not documented
10533 "sysrq"
10535 Not documented
10536 "kp_0"
10538 Not documented
10539 "kp_1"
10541 Not documented
10542 "kp_2"
10544 Not documented
10545 "kp_3"
10547 Not documented
10548 "kp_4"
10550 Not documented
10551 "kp_5"
10553 Not documented
10554 "kp_6"
10556 Not documented
10557 "kp_7"
10559 Not documented
10560 "kp_8"
10562 Not documented
10563 "kp_9"
10565 Not documented
10566 "less"
10568 Not documented
10569 "f11"
10571 Not documented
10572 "f12"
10574 Not documented
10575 "print"
10577 Not documented
10578 "home"
10580 Not documented
10581 "pgup"
10583 Not documented
10584 "pgdn"
10586 Not documented
10587 "end"
10589 Not documented
10590 "left"
10592 Not documented
10593 "up"
10595 Not documented
10596 "down"
10598 Not documented
10599 "right"
10601 Not documented
10602 "insert"
10604 Not documented
10605 "delete"
10607 Not documented
10608 "stop"
10610 Not documented
10611 "again"
10613 Not documented
10614 "props"
10616 Not documented
10617 "undo"
10619 Not documented
10620 "front"
10622 Not documented
10623 "copy"
10625 Not documented
10626 "open"
10628 Not documented
10629 "paste"
10631 Not documented
10632 "find"
10634 Not documented
10635 "cut"
10637 Not documented
10638 "lf"
10640 Not documented
10641 "help"
10643 Not documented
10644 "meta_l"
10646 Not documented
10647 "meta_r"
10649 Not documented
10650 "compose"
10652 Not documented
10653 'sysrq' was mistakenly added to hack around the fact that the ps2
10655 driver was not generating correct scancodes sequences when 'alt+print'
10656 was pressed. This flaw is now fixed and the 'sysrq' key serves no
10657 further purpose. Any further use of 'sysrq' will be transparently
10658 changed to 'print', so they are effectively synonyms.
10659 Since: 1.3.0
10661 KeyValue (Object)
10663 Represents a keyboard key.
10665 Members:
10667 "type"
10669 One of "number", "qcode"
10670 "data: int" when "type" is "number"
10672 "data: QKeyCode" when "type" is "qcode"
10673 Since: 1.3.0
10675 send-key (Command) Send keys to guest.
10677 Arguments:
10679 "keys: array of KeyValue"
10681 An array of "KeyValue" elements. All "KeyValues" in this array are
10682 simultaneously sent to the guest. A "KeyValue".number value is sent
10683 directly to the guest, while "KeyValue".qcode must be a valid
10684 "QKeyCode" value
10685 "hold-time: int" (optional)
10687 time to delay key up events, milliseconds. Defaults to 100
10688 Returns: Nothing on success If key is unknown or redundant,
10690 InvalidParameter
10691 Since: 1.3.0
10693 Example:
10695 -> { "execute": "send-key",
10697 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
10698 { "type": "qcode", "data": "alt" },
10699 { "type": "qcode", "data": "delete" } ] } }
10700 <- { "return": {} }
10701 InputButton (Enum)
10703 Button of a pointer input device (mouse, tablet).
10705 Values:
10707 "side"
10709 front side button of a 5-button mouse (since 2.9)
10710 "extra"
10712 rear side button of a 5-button mouse (since 2.9)
10713 "left"
10715 Not documented
10716 "middle"
10718 Not documented
10719 "right"
10721 Not documented
10722 "wheel-up"
10724 Not documented
10725 "wheel-down"
10727 Not documented
10728 Since: 2.0
10730 InputAxis (Enum)
10732 Position axis of a pointer input device (mouse, tablet).
10734 Values:
10736 "x" Not documented
10738 "y" Not documented
10740 Since: 2.0
10742 InputKeyEvent (Object)
10744 Keyboard input event.
10746 Members:
10748 "key: KeyValue"
10750 Which key this event is for.
10751 "down: boolean"
10753 True for key-down and false for key-up events.
10754 Since: 2.0
10756 InputBtnEvent (Object)
10758 Pointer button input event.
10760 Members:
10762 "button: InputButton"
10764 Which button this event is for.
10765 "down: boolean"
10767 True for key-down and false for key-up events.
10768 Since: 2.0
10770 InputMoveEvent (Object)
10772 Pointer motion input event.
10774 Members:
10776 "axis: InputAxis"
10778 Which axis is referenced by "value".
10779 "value: int"
10781 Pointer position. For absolute coordinates the valid range is 0 ->
10782 0x7ffff
10783 Since: 2.0
10785 InputEvent (Object)
10787 Input event union.
10789 Members:
10791 "type"
10793 the input type, one of:
10794 - 'key': Input event of Keyboard
10796 - 'btn': Input event of pointer buttons
10798 - 'rel': Input event of relative pointer motion
10800 - 'abs': Input event of absolute pointer motion
10802 "data: InputKeyEvent" when "type" is "key"
10804 "data: InputBtnEvent" when "type" is "btn"
10805 "data: InputMoveEvent" when "type" is "rel"
10806 "data: InputMoveEvent" when "type" is "abs"
10807 Since: 2.0
10809 input-send-event (Command) Send input event(s) to guest.
10811 Arguments:
10813 "device: string" (optional)
10815 display device to send event(s) to.
10816 "head: int" (optional)
10818 head to send event(s) to, in case the display device supports
10819 multiple scanouts.
10820 "events: array of InputEvent"
10822 List of InputEvent union.
10823 Returns: Nothing on success.
10825 The "device" and "head" parameters can be used to send the input event
10827 to specific input devices in case (a) multiple input devices of the
10828 same kind are added to the virtual machine and (b) you have configured
10829 input routing (see docs/multiseat.txt) for those input devices. The
10830 parameters work exactly like the device and head properties of input
10831 devices. If "device" is missing, only devices that have no input
10832 routing config are admissible. If "device" is specified, both input
10833 devices with and without input routing config are admissible, but
10834 devices with input routing config take precedence.
10835 Since: 2.6
10837 Note: The consoles are visible in the qom tree, under
10839 /backend/console[$index]. They have a device link and head property, so
10840 it is possible to map which console belongs to which device and
10841 display.
10842 Example:
10844 1. Press left mouse button.
10846 -> { "execute": "input-send-event",
10848 "arguments": { "device": "video0",
10849 "events": [ { "type": "btn",
10850 "data" : { "down": true, "button": "left" } } ] } }
10851 <- { "return": {} }
10852 -> { "execute": "input-send-event",
10854 "arguments": { "device": "video0",
10855 "events": [ { "type": "btn",
10856 "data" : { "down": false, "button": "left" } } ] } }
10857 <- { "return": {} }
10858 2. Press ctrl-alt-del.
10860 -> { "execute": "input-send-event",
10862 "arguments": { "events": [
10863 { "type": "key", "data" : { "down": true,
10864 "key": {"type": "qcode", "data": "ctrl" } } },
10865 { "type": "key", "data" : { "down": true,
10866 "key": {"type": "qcode", "data": "alt" } } },
10867 { "type": "key", "data" : { "down": true,
10868 "key": {"type": "qcode", "data": "delete" } } } ] } }
10869 <- { "return": {} }
10870 3. Move mouse pointer to absolute coordinates (20000, 400).
10872 -> { "execute": "input-send-event" ,
10874 "arguments": { "events": [
10875 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
10876 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
10877 <- { "return": {} }
10878 GrabToggleKeys (Enum)
10880 Keys to toggle input-linux between host and guest.
10882 Values:
10884 "ctrl-ctrl"
10886 Not documented
10887 "alt-alt"
10889 Not documented
10890 "meta-meta"
10892 Not documented
10893 "scrolllock"
10895 Not documented
10896 "ctrl-scrolllock"
10898 Not documented
10899 Since: 4.0
10901 DisplayGTK (Object)
10903 GTK display options.
10905 Members:
10907 "grab-on-hover: boolean" (optional)
10909 Grab keyboard input on mouse hover.
10910 "zoom-to-fit: boolean" (optional)
10912 Zoom guest display to fit into the host window. When turned off
10913 the host window will be resized instead. In case the display
10914 device can notify the guest on window resizes (virtio-gpu) this
10915 will default to "on", assuming the guest will resize the display to
10916 match the window size then. Otherwise it defaults to "off". Since
10917 3.1
10918 Since: 2.12
10920 DisplayEGLHeadless (Object)
10922 EGL headless display options.
10924 Members:
10926 "rendernode: string" (optional)
10928 Which DRM render node should be used. Default is the first
10929 available node on the host.
10930 Since: 3.1
10932 DisplayGLMode (Enum)
10934 Display OpenGL mode.
10936 Values:
10938 "off"
10940 Disable OpenGL (default).
10941 "on"
10943 Use OpenGL, pick context type automatically. Would better be named
10944 'auto' but is called 'on' for backward compatibility with bool
10945 type.
10946 "core"
10948 Use OpenGL with Core (desktop) Context.
10949 "es"
10951 Use OpenGL with ES (embedded systems) Context.
10952 Since: 3.0
10954 DisplayCurses (Object)
10956 Curses display options.
10958 Members:
10960 "charset: string" (optional)
10962 Font charset used by guest (default: CP437).
10963 Since: 4.0
10965 DisplayType (Enum)
10967 Display (user interface) type.
10969 Values:
10971 "default"
10973 The default user interface, selecting from the first available of
10974 gtk, sdl, cocoa, and vnc.
10975 "none"
10977 No user interface or video output display. The guest will still see
10978 an emulated graphics card, but its output will not be displayed to
10979 the QEMU user.
10980 "gtk"
10982 The GTK user interface.
10983 "sdl"
10985 The SDL user interface.
10986 "egl-headless"
10988 No user interface, offload GL operations to a local DRI device.
10989 Graphical display need to be paired with VNC or Spice. (Since 3.1)
10990 "curses"
10992 Display video output via curses. For graphics device models which
10993 support a text mode, QEMU can display this output using a
10994 curses/ncurses interface. Nothing is displayed when the graphics
10995 device is in graphical mode or if the graphics device does not
10996 support a text mode. Generally only the VGA device models support
10997 text mode.
10998 "cocoa"
11000 The Cocoa user interface.
11001 "spice-app"
11003 Set up a Spice server and run the default associated application to
11004 connect to it. The server will redirect the serial console and QEMU
11005 monitors. (Since 4.0)
11006 Since: 2.12
11008 DisplayOptions (Object)
11010 Display (user interface) options.
11012 Members:
11014 "type: DisplayType"
11016 Which DisplayType qemu should use.
11017 "full-screen: boolean" (optional)
11019 Start user interface in fullscreen mode (default: off).
11020 "window-close: boolean" (optional)
11022 Allow to quit qemu with window close button (default: on).
11023 "gl: DisplayGLMode" (optional)
11025 Enable OpenGL support (default: off).
11026 The members of "DisplayGTK" when "type" is "gtk"
11028 The members of "DisplayCurses" when "type" is "curses"
11029 The members of "DisplayEGLHeadless" when "type" is "egl-headless"
11030 Since: 2.12
11032 query-display-options (Command) Returns information about display
11034 configuration
11035 Returns: "DisplayOptions"
11037 Since: 3.1
11039 QAuthZListPolicy (Enum)
11041 The authorization policy result
11043 Values:
11045 "deny"
11047 deny access
11048 "allow"
11050 allow access
11051 Since: 4.0
11053 QAuthZListFormat (Enum)
11055 The authorization policy match format
11057 Values:
11059 "exact"
11061 an exact string match
11062 "glob"
11064 string with ? and * shell wildcard support
11065 Since: 4.0
11067 QAuthZListRule (Object)
11069 A single authorization rule.
11071 Members:
11073 "match: string"
11075 a string or glob to match against a user identity
11076 "policy: QAuthZListPolicy"
11078 the result to return if "match" evaluates to true
11079 "format: QAuthZListFormat" (optional)
11081 the format of the "match" rule (default 'exact')
11082 Since: 4.0
11084 QAuthZListRuleListHack (Object)
11086 Not exposed via QMP; hack to generate QAuthZListRuleList for use
11088 internally by the code.
11089 Members:
11091 "unused: array of QAuthZListRule"
11093 Not documented
11094 Since: 4.0
11096 Migration
11098 MigrationStats (Object)
11099 Detailed migration status.
11101 Members:
11103 "transferred: int"
11105 amount of bytes already transferred to the target VM
11106 "remaining: int"
11108 amount of bytes remaining to be transferred to the target VM
11109 "total: int"
11111 total amount of bytes involved in the migration process
11112 "duplicate: int"
11114 number of duplicate (zero) pages (since 1.2)
11115 "skipped: int"
11117 number of skipped zero pages (since 1.5)
11118 "normal: int"
11120 number of normal pages (since 1.2)
11121 "normal-bytes: int"
11123 number of normal bytes sent (since 1.2)
11124 "dirty-pages-rate: int"
11126 number of pages dirtied by second by the guest (since 1.3)
11127 "mbps: number"
11129 throughput in megabits/sec. (since 1.6)
11130 "dirty-sync-count: int"
11132 number of times that dirty ram was synchronized (since 2.1)
11133 "postcopy-requests: int"
11135 The number of page requests received from the destination (since
11136 2.7)
11137 "page-size: int"
11139 The number of bytes per page for the various page-based statistics
11140 (since 2.10)
11141 "multifd-bytes: int"
11143 The number of bytes sent through multifd (since 3.0)
11144 "pages-per-second: int"
11146 the number of memory pages transferred per second (Since 4.0)
11147 Since: 0.14.0
11149 XBZRLECacheStats (Object)
11151 Detailed XBZRLE migration cache statistics
11153 Members:
11155 "cache-size: int"
11157 XBZRLE cache size
11158 "bytes: int"
11160 amount of bytes already transferred to the target VM
11161 "pages: int"
11163 amount of pages transferred to the target VM
11164 "cache-miss: int"
11166 number of cache miss
11167 "cache-miss-rate: number"
11169 rate of cache miss (since 2.1)
11170 "overflow: int"
11172 number of overflows
11173 Since: 1.2
11175 CompressionStats (Object)
11177 Detailed migration compression statistics
11179 Members:
11181 "pages: int"
11183 amount of pages compressed and transferred to the target VM
11184 "busy: int"
11186 count of times that no free thread was available to compress data
11187 "busy-rate: number"
11189 rate of thread busy
11190 "compressed-size: int"
11192 amount of bytes after compression
11193 "compression-rate: number"
11195 rate of compressed size
11196 Since: 3.1
11198 MigrationStatus (Enum)
11200 An enumeration of migration status.
11202 Values:
11204 "none"
11206 no migration has ever happened.
11207 "setup"
11209 migration process has been initiated.
11210 "cancelling"
11212 in the process of cancelling migration.
11213 "cancelled"
11215 cancelling migration is finished.
11216 "active"
11218 in the process of doing migration.
11219 "postcopy-active"
11221 like active, but now in postcopy mode. (since 2.5)
11222 "postcopy-paused"
11224 during postcopy but paused. (since 3.0)
11225 "postcopy-recover"
11227 trying to recover from a paused postcopy. (since 3.0)
11228 "completed"
11230 migration is finished.
11231 "failed"
11233 some error occurred during migration process.
11234 "colo"
11236 VM is in the process of fault tolerance, VM can not get into this
11237 state unless colo capability is enabled for migration. (since 2.8)
11238 "pre-switchover"
11240 Paused before device serialisation. (since 2.11)
11241 "device"
11243 During device serialisation when pause-before-switchover is enabled
11244 (since 2.11)
11245 Since: 2.3
11247 MigrationInfo (Object)
11249 Information about current migration process.
11251 Members:
11253 "status: MigrationStatus" (optional)
11255 "MigrationStatus" describing the current migration status. If this
11256 field is not returned, no migration process has been initiated
11257 "ram: MigrationStats" (optional)
11259 "MigrationStats" containing detailed migration status, only
11260 returned if status is 'active' or 'completed'(since 1.2)
11261 "disk: MigrationStats" (optional)
11263 "MigrationStats" containing detailed disk migration status, only
11264 returned if status is 'active' and it is a block migration
11265 "xbzrle-cache: XBZRLECacheStats" (optional)
11267 "XBZRLECacheStats" containing detailed XBZRLE migration statistics,
11268 only returned if XBZRLE feature is on and status is 'active' or
11269 'completed' (since 1.2)
11270 "total-time: int" (optional)
11272 total amount of milliseconds since migration started. If migration
11273 has ended, it returns the total migration time. (since 1.2)
11274 "downtime: int" (optional)
11276 only present when migration finishes correctly total downtime in
11277 milliseconds for the guest. (since 1.3)
11278 "expected-downtime: int" (optional)
11280 only present while migration is active expected downtime in
11281 milliseconds for the guest in last walk of the dirty bitmap. (since
11282 1.3)
11283 "setup-time: int" (optional)
11285 amount of setup time in milliseconds before the iterations begin
11286 but after the QMP command is issued. This is designed to provide an
11287 accounting of any activities (such as RDMA pinning) which may be
11288 expensive, but do not actually occur during the iterative migration
11289 rounds themselves. (since 1.6)
11290 "cpu-throttle-percentage: int" (optional)
11292 percentage of time guest cpus are being throttled during auto-
11293 converge. This is only present when auto-converge has started
11294 throttling guest cpus. (Since 2.7)
11295 "error-desc: string" (optional)
11297 the human readable error description string, when "status" is
11298 'failed'. Clients should not attempt to parse the error strings.
11299 (Since 2.7)
11300 "postcopy-blocktime: int" (optional)
11302 total time when all vCPU were blocked during postcopy live
11303 migration. This is only present when the postcopy-blocktime
11304 migration capability is enabled. (Since 3.0)
11305 "postcopy-vcpu-blocktime: array of int" (optional)
11307 list of the postcopy blocktime per vCPU. This is only present when
11308 the postcopy-blocktime migration capability is enabled. (Since 3.0)
11309 "compression: CompressionStats" (optional)
11311 migration compression statistics, only returned if compression
11312 feature is on and status is 'active' or 'completed' (Since 3.1)
11313 "socket-address: array of SocketAddress" (optional)
11315 Only used for tcp, to know what the real port is (Since 4.0)
11316 Since: 0.14.0
11318 query-migrate (Command) Returns information about current migration
11320 process. If migration is active there will be another json-object with
11321 RAM migration status and if block migration is active another one with
11322 block migration status.
11323 Returns: "MigrationInfo"
11325 Since: 0.14.0
11327 Example:
11329 1. Before the first migration
11331 -> { "execute": "query-migrate" }
11333 <- { "return": {} }
11334 2. Migration is done and has succeeded
11336 -> { "execute": "query-migrate" }
11338 <- { "return": {
11339 "status": "completed",
11340 "total-time":12345,
11341 "setup-time":12345,
11342 "downtime":12345,
11343 "ram":{
11344 "transferred":123,
11345 "remaining":123,
11346 "total":246,
11347 "duplicate":123,
11348 "normal":123,
11349 "normal-bytes":123456,
11350 "dirty-sync-count":15
11351 }
11352 }
11353 }
11354 3. Migration is done and has failed
11356 -> { "execute": "query-migrate" }
11358 <- { "return": { "status": "failed" } }
11359 4. Migration is being performed and is not a block migration:
11361 -> { "execute": "query-migrate" }
11363 <- {
11364 "return":{
11365 "status":"active",
11366 "total-time":12345,
11367 "setup-time":12345,
11368 "expected-downtime":12345,
11369 "ram":{
11370 "transferred":123,
11371 "remaining":123,
11372 "total":246,
11373 "duplicate":123,
11374 "normal":123,
11375 "normal-bytes":123456,
11376 "dirty-sync-count":15
11377 }
11378 }
11379 }
11380 5. Migration is being performed and is a block migration:
11382 -> { "execute": "query-migrate" }
11384 <- {
11385 "return":{
11386 "status":"active",
11387 "total-time":12345,
11388 "setup-time":12345,
11389 "expected-downtime":12345,
11390 "ram":{
11391 "total":1057024,
11392 "remaining":1053304,
11393 "transferred":3720,
11394 "duplicate":123,
11395 "normal":123,
11396 "normal-bytes":123456,
11397 "dirty-sync-count":15
11398 },
11399 "disk":{
11400 "total":20971520,
11401 "remaining":20880384,
11402 "transferred":91136
11403 }
11404 }
11405 }
11406 6. Migration is being performed and XBZRLE is active:
11408 -> { "execute": "query-migrate" }
11410 <- {
11411 "return":{
11412 "status":"active",
11413 "total-time":12345,
11414 "setup-time":12345,
11415 "expected-downtime":12345,
11416 "ram":{
11417 "total":1057024,
11418 "remaining":1053304,
11419 "transferred":3720,
11420 "duplicate":10,
11421 "normal":3333,
11422 "normal-bytes":3412992,
11423 "dirty-sync-count":15
11424 },
11425 "xbzrle-cache":{
11426 "cache-size":67108864,
11427 "bytes":20971520,
11428 "pages":2444343,
11429 "cache-miss":2244,
11430 "cache-miss-rate":0.123,
11431 "overflow":34434
11432 }
11433 }
11434 }
11435 MigrationCapability (Enum)
11437 Migration capabilities enumeration
11439 Values:
11441 "xbzrle"
11443 Migration supports xbzrle (Xor Based Zero Run Length Encoding).
11444 This feature allows us to minimize migration traffic for certain
11445 work loads, by sending compressed difference of the pages
11446 "rdma-pin-all"
11448 Controls whether or not the entire VM memory footprint is mlock()'d
11449 on demand or all at once. Refer to docs/rdma.txt for usage.
11450 Disabled by default. (since 2.0)
11451 "zero-blocks"
11453 During storage migration encode blocks of zeroes efficiently. This
11454 essentially saves 1MB of zeroes per block on the wire. Enabling
11455 requires source and target VM to support this feature. To enable it
11456 is sufficient to enable the capability on the source VM. The
11457 feature is disabled by default. (since 1.6)
11458 "compress"
11460 Use multiple compression threads to accelerate live migration.
11461 This feature can help to reduce the migration traffic, by sending
11462 compressed pages. Please note that if compress and xbzrle are both
11463 on, compress only takes effect in the ram bulk stage, after that,
11464 it will be disabled and only xbzrle takes effect, this can help to
11465 minimize migration traffic. The feature is disabled by default.
11466 (since 2.4 )
11467 "events"
11469 generate events for each migration state change (since 2.4 )
11470 "auto-converge"
11472 If enabled, QEMU will automatically throttle down the guest to
11473 speed up convergence of RAM migration. (since 1.6)
11474 "postcopy-ram"
11476 Start executing on the migration target before all of RAM has been
11477 migrated, pulling the remaining pages along as needed. The capacity
11478 must have the same setting on both source and target or migration
11479 will not even start. NOTE: If the migration fails during postcopy
11480 the VM will fail. (since 2.6)
11481 "x-colo"
11483 If enabled, migration will never end, and the state of the VM on
11484 the primary side will be migrated continuously to the VM on
11485 secondary side, this process is called COarse-Grain LOck Stepping
11486 (COLO) for Non-stop Service. (since 2.8)
11487 "release-ram"
11489 if enabled, qemu will free the migrated ram pages on the source
11490 during postcopy-ram migration. (since 2.9)
11491 "block"
11493 If enabled, QEMU will also migrate the contents of all block
11494 devices. Default is disabled. A possible alternative uses mirror
11495 jobs to a builtin NBD server on the destination, which offers more
11496 flexibility. (Since 2.10)
11497 "return-path"
11499 If enabled, migration will use the return path even for precopy.
11500 (since 2.10)
11501 "pause-before-switchover"
11503 Pause outgoing migration before serialising device state and before
11504 disabling block IO (since 2.11)
11505 "multifd"
11507 Use more than one fd for migration (since 4.0)
11508 "dirty-bitmaps"
11510 If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
11511 "postcopy-blocktime"
11513 Calculate downtime for postcopy live migration (since 3.0)
11514 "late-block-activate"
11516 If enabled, the destination will not activate block devices (and
11517 thus take locks) immediately at the end of migration. (since 3.0)
11518 "x-ignore-shared"
11520 If enabled, QEMU will not migrate shared memory (since 4.0)
11521 Since: 1.2
11523 MigrationCapabilityStatus (Object)
11525 Migration capability information
11527 Members:
11529 "capability: MigrationCapability"
11531 capability enum
11532 "state: boolean"
11534 capability state bool
11535 Since: 1.2
11537 migrate-set-capabilities (Command) Enable/Disable the following
11539 migration capabilities (like xbzrle)
11540 Arguments:
11542 "capabilities: array of MigrationCapabilityStatus"
11544 json array of capability modifications to make
11545 Since: 1.2
11547 Example:
11549 -> { "execute": "migrate-set-capabilities" , "arguments":
11551 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
11552 query-migrate-capabilities (Command) Returns information about the
11554 current migration capabilities status
11555 Returns: "MigrationCapabilitiesStatus"
11557 Since: 1.2
11559 Example:
11561 -> { "execute": "query-migrate-capabilities" }
11563 <- { "return": [
11564 {"state": false, "capability": "xbzrle"},
11565 {"state": false, "capability": "rdma-pin-all"},
11566 {"state": false, "capability": "auto-converge"},
11567 {"state": false, "capability": "zero-blocks"},
11568 {"state": false, "capability": "compress"},
11569 {"state": true, "capability": "events"},
11570 {"state": false, "capability": "postcopy-ram"},
11571 {"state": false, "capability": "x-colo"}
11572 ]}
11573 MigrationParameter (Enum)
11575 Migration parameters enumeration
11577 Values:
11579 "announce-initial"
11581 Initial delay (in milliseconds) before sending the first announce
11582 (Since 4.0)
11583 "announce-max"
11585 Maximum delay (in milliseconds) between packets in the announcement
11586 (Since 4.0)
11587 "announce-rounds"
11589 Number of self-announce packets sent after migration (Since 4.0)
11590 "announce-step"
11592 Increase in delay (in milliseconds) between subsequent packets in
11593 the announcement (Since 4.0)
11594 "compress-level"
11596 Set the compression level to be used in live migration, the
11597 compression level is an integer between 0 and 9, where 0 means no
11598 compression, 1 means the best compression speed, and 9 means best
11599 compression ratio which will consume more CPU.
11600 "compress-threads"
11602 Set compression thread count to be used in live migration, the
11603 compression thread count is an integer between 1 and 255.
11604 "compress-wait-thread"
11606 Controls behavior when all compression threads are currently busy.
11607 If true (default), wait for a free compression thread to become
11608 available; otherwise, send the page uncompressed. (Since 3.1)
11609 "decompress-threads"
11611 Set decompression thread count to be used in live migration, the
11612 decompression thread count is an integer between 1 and 255.
11613 Usually, decompression is at least 4 times as fast as compression,
11614 so set the decompress-threads to the number about 1/4 of compress-
11615 threads is adequate.
11616 "cpu-throttle-initial"
11618 Initial percentage of time guest cpus are throttled when migration
11619 auto-converge is activated. The default value is 20. (Since 2.7)
11620 "cpu-throttle-increment"
11622 throttle percentage increase each time auto-converge detects that
11623 migration is not making progress. The default value is 10. (Since
11624 2.7)
11625 "tls-creds"
11627 ID of the 'tls-creds' object that provides credentials for
11628 establishing a TLS connection over the migration data channel. On
11629 the outgoing side of the migration, the credentials must be for a
11630 'client' endpoint, while for the incoming side the credentials must
11631 be for a 'server' endpoint. Setting this will enable TLS for all
11632 migrations. The default is unset, resulting in unsecured migration
11633 at the QEMU level. (Since 2.7)
11634 "tls-hostname"
11636 hostname of the target host for the migration. This is required
11637 when using x509 based TLS credentials and the migration URI does
11638 not already include a hostname. For example if using fd: or exec:
11639 based migration, the hostname must be provided so that the server's
11640 x509 certificate identity can be validated. (Since 2.7)
11641 "tls-authz"
11643 ID of the 'authz' object subclass that provides access control
11644 checking of the TLS x509 certificate distinguished name. This
11645 object is only resolved at time of use, so can be deleted and
11646 recreated on the fly while the migration server is active. If
11647 missing, it will default to denying access (Since 4.0)
11648 "max-bandwidth"
11650 to set maximum speed for migration. maximum speed in bytes per
11651 second. (Since 2.8)
11652 "downtime-limit"
11654 set maximum tolerated downtime for migration. maximum downtime in
11655 milliseconds (Since 2.8)
11656 "x-checkpoint-delay"
11658 The delay time (in ms) between two COLO checkpoints in periodic
11659 mode. (Since 2.8)
11660 "block-incremental"
11662 Affects how much storage is migrated when the block migration
11663 capability is enabled. When false, the entire storage backing
11664 chain is migrated into a flattened image at the destination; when
11665 true, only the active qcow2 layer is migrated and the destination
11666 must already have access to the same backing chain as was used on
11667 the source. (since 2.10)
11668 "multifd-channels"
11670 Number of channels used to migrate data in parallel. This is the
11671 same number that the number of sockets used for migration. The
11672 default value is 2 (since 4.0)
11673 "xbzrle-cache-size"
11675 cache size to be used by XBZRLE migration. It needs to be a
11676 multiple of the target page size and a power of 2 (Since 2.11)
11677 "max-postcopy-bandwidth"
11679 Background transfer bandwidth during postcopy. Defaults to 0
11680 (unlimited). In bytes per second. (Since 3.0)
11681 "max-cpu-throttle"
11683 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
11684 Since: 2.4
11686 MigrateSetParameters (Object)
11688 Members:
11690 "announce-initial: int" (optional)
11692 Initial delay (in milliseconds) before sending the first announce
11693 (Since 4.0)
11694 "announce-max: int" (optional)
11696 Maximum delay (in milliseconds) between packets in the announcement
11697 (Since 4.0)
11698 "announce-rounds: int" (optional)
11700 Number of self-announce packets sent after migration (Since 4.0)
11701 "announce-step: int" (optional)
11703 Increase in delay (in milliseconds) between subsequent packets in
11704 the announcement (Since 4.0)
11705 "compress-level: int" (optional)
11707 compression level
11708 "compress-threads: int" (optional)
11710 compression thread count
11711 "compress-wait-thread: boolean" (optional)
11713 Controls behavior when all compression threads are currently busy.
11714 If true (default), wait for a free compression thread to become
11715 available; otherwise, send the page uncompressed. (Since 3.1)
11716 "decompress-threads: int" (optional)
11718 decompression thread count
11719 "cpu-throttle-initial: int" (optional)
11721 Initial percentage of time guest cpus are throttled when migration
11722 auto-converge is activated. The default value is 20. (Since 2.7)
11723 "cpu-throttle-increment: int" (optional)
11725 throttle percentage increase each time auto-converge detects that
11726 migration is not making progress. The default value is 10. (Since
11727 2.7)
11728 "tls-creds: StrOrNull" (optional)
11730 ID of the 'tls-creds' object that provides credentials for
11731 establishing a TLS connection over the migration data channel. On
11732 the outgoing side of the migration, the credentials must be for a
11733 'client' endpoint, while for the incoming side the credentials must
11734 be for a 'server' endpoint. Setting this to a non-empty string
11735 enables TLS for all migrations. An empty string means that QEMU
11736 will use plain text mode for migration, rather than TLS (Since 2.9)
11737 Previously (since 2.7), this was reported by omitting tls-creds
11738 instead.
11739 "tls-hostname: StrOrNull" (optional)
11741 hostname of the target host for the migration. This is required
11742 when using x509 based TLS credentials and the migration URI does
11743 not already include a hostname. For example if using fd: or exec:
11744 based migration, the hostname must be provided so that the server's
11745 x509 certificate identity can be validated. (Since 2.7) An empty
11746 string means that QEMU will use the hostname associated with the
11747 migration URI, if any. (Since 2.9) Previously (since 2.7), this was
11748 reported by omitting tls-hostname instead.
11749 "max-bandwidth: int" (optional)
11751 to set maximum speed for migration. maximum speed in bytes per
11752 second. (Since 2.8)
11753 "downtime-limit: int" (optional)
11755 set maximum tolerated downtime for migration. maximum downtime in
11756 milliseconds (Since 2.8)
11757 "x-checkpoint-delay: int" (optional)
11759 the delay time between two COLO checkpoints. (Since 2.8)
11760 "block-incremental: boolean" (optional)
11762 Affects how much storage is migrated when the block migration
11763 capability is enabled. When false, the entire storage backing
11764 chain is migrated into a flattened image at the destination; when
11765 true, only the active qcow2 layer is migrated and the destination
11766 must already have access to the same backing chain as was used on
11767 the source. (since 2.10)
11768 "multifd-channels: int" (optional)
11770 Number of channels used to migrate data in parallel. This is the
11771 same number that the number of sockets used for migration. The
11772 default value is 2 (since 4.0)
11773 "xbzrle-cache-size: int" (optional)
11775 cache size to be used by XBZRLE migration. It needs to be a
11776 multiple of the target page size and a power of 2 (Since 2.11)
11777 "max-postcopy-bandwidth: int" (optional)
11779 Background transfer bandwidth during postcopy. Defaults to 0
11780 (unlimited). In bytes per second. (Since 3.0)
11781 "max-cpu-throttle: int" (optional)
11783 maximum cpu throttle percentage. The default value is 99. (Since
11784 3.1)
11785 "tls-authz: StrOrNull" (optional)
11787 Not documented
11788 Since: 2.4
11790 migrate-set-parameters (Command) Set various migration parameters.
11792 Arguments: the members of "MigrateSetParameters"
11794 Since: 2.4
11796 Example:
11798 -> { "execute": "migrate-set-parameters" ,
11800 "arguments": { "compress-level": 1 } }
11801 MigrationParameters (Object)
11803 The optional members aren't actually optional.
11805 Members:
11807 "announce-initial: int" (optional)
11809 Initial delay (in milliseconds) before sending the first announce
11810 (Since 4.0)
11811 "announce-max: int" (optional)
11813 Maximum delay (in milliseconds) between packets in the announcement
11814 (Since 4.0)
11815 "announce-rounds: int" (optional)
11817 Number of self-announce packets sent after migration (Since 4.0)
11818 "announce-step: int" (optional)
11820 Increase in delay (in milliseconds) between subsequent packets in
11821 the announcement (Since 4.0)
11822 "compress-level: int" (optional)
11824 compression level
11825 "compress-threads: int" (optional)
11827 compression thread count
11828 "compress-wait-thread: boolean" (optional)
11830 Controls behavior when all compression threads are currently busy.
11831 If true (default), wait for a free compression thread to become
11832 available; otherwise, send the page uncompressed. (Since 3.1)
11833 "decompress-threads: int" (optional)
11835 decompression thread count
11836 "cpu-throttle-initial: int" (optional)
11838 Initial percentage of time guest cpus are throttled when migration
11839 auto-converge is activated. (Since 2.7)
11840 "cpu-throttle-increment: int" (optional)
11842 throttle percentage increase each time auto-converge detects that
11843 migration is not making progress. (Since 2.7)
11844 "tls-creds: string" (optional)
11846 ID of the 'tls-creds' object that provides credentials for
11847 establishing a TLS connection over the migration data channel. On
11848 the outgoing side of the migration, the credentials must be for a
11849 'client' endpoint, while for the incoming side the credentials must
11850 be for a 'server' endpoint. An empty string means that QEMU will
11851 use plain text mode for migration, rather than TLS (Since 2.7)
11852 Note: 2.8 reports this by omitting tls-creds instead.
11853 "tls-hostname: string" (optional)
11855 hostname of the target host for the migration. This is required
11856 when using x509 based TLS credentials and the migration URI does
11857 not already include a hostname. For example if using fd: or exec:
11858 based migration, the hostname must be provided so that the server's
11859 x509 certificate identity can be validated. (Since 2.7) An empty
11860 string means that QEMU will use the hostname associated with the
11861 migration URI, if any. (Since 2.9) Note: 2.8 reports this by
11862 omitting tls-hostname instead.
11863 "tls-authz: string" (optional)
11865 ID of the 'authz' object subclass that provides access control
11866 checking of the TLS x509 certificate distinguished name. (Since
11867 4.0)
11868 "max-bandwidth: int" (optional)
11870 to set maximum speed for migration. maximum speed in bytes per
11871 second. (Since 2.8)
11872 "downtime-limit: int" (optional)
11874 set maximum tolerated downtime for migration. maximum downtime in
11875 milliseconds (Since 2.8)
11876 "x-checkpoint-delay: int" (optional)
11878 the delay time between two COLO checkpoints. (Since 2.8)
11879 "block-incremental: boolean" (optional)
11881 Affects how much storage is migrated when the block migration
11882 capability is enabled. When false, the entire storage backing
11883 chain is migrated into a flattened image at the destination; when
11884 true, only the active qcow2 layer is migrated and the destination
11885 must already have access to the same backing chain as was used on
11886 the source. (since 2.10)
11887 "multifd-channels: int" (optional)
11889 Number of channels used to migrate data in parallel. This is the
11890 same number that the number of sockets used for migration. The
11891 default value is 2 (since 4.0)
11892 "xbzrle-cache-size: int" (optional)
11894 cache size to be used by XBZRLE migration. It needs to be a
11895 multiple of the target page size and a power of 2 (Since 2.11)
11896 "max-postcopy-bandwidth: int" (optional)
11898 Background transfer bandwidth during postcopy. Defaults to 0
11899 (unlimited). In bytes per second. (Since 3.0)
11900 "max-cpu-throttle: int" (optional)
11902 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
11903 Since: 2.4
11905 query-migrate-parameters (Command) Returns information about the
11907 current migration parameters
11908 Returns: "MigrationParameters"
11910 Since: 2.4
11912 Example:
11914 -> { "execute": "query-migrate-parameters" }
11916 <- { "return": {
11917 "decompress-threads": 2,
11918 "cpu-throttle-increment": 10,
11919 "compress-threads": 8,
11920 "compress-level": 1,
11921 "cpu-throttle-initial": 20,
11922 "max-bandwidth": 33554432,
11923 "downtime-limit": 300
11924 }
11925 }
11926 client_migrate_info (Command) Set migration information for remote
11928 display. This makes the server ask the client to automatically
11929 reconnect using the new parameters once migration finished
11930 successfully. Only implemented for SPICE.
11931 Arguments:
11933 "protocol: string"
11935 must be "spice"
11936 "hostname: string"
11938 migration target hostname
11939 "port: int" (optional)
11941 spice tcp port for plaintext channels
11942 "tls-port: int" (optional)
11944 spice tcp port for tls-secured channels
11945 "cert-subject: string" (optional)
11947 server certificate subject
11948 Since: 0.14.0
11950 Example:
11952 -> { "execute": "client_migrate_info",
11954 "arguments": { "protocol": "spice",
11955 "hostname": "virt42.lab.kraxel.org",
11956 "port": 1234 } }
11957 <- { "return": {} }
11958 migrate-start-postcopy (Command) Followup to a migration command to
11960 switch the migration to postcopy mode. The postcopy-ram capability
11961 must be set on both source and destination before the original
11962 migration command.
11963 Since: 2.5
11965 Example:
11967 -> { "execute": "migrate-start-postcopy" }
11969 <- { "return": {} }
11970 MIGRATION (Event) Emitted when a migration event happens
11972 Arguments:
11974 "status: MigrationStatus"
11976 "MigrationStatus" describing the current migration status.
11977 Since: 2.4
11979 Example:
11981 <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
11983 "event": "MIGRATION",
11984 "data": {"status": "completed"} }
11985 MIGRATION_PASS (Event) Emitted from the source side of a migration at
11987 the start of each pass (when it syncs the dirty bitmap)
11988 Arguments:
11990 "pass: int"
11992 An incrementing count (starting at 1 on the first pass)
11993 Since: 2.6
11995 Example:
11997 { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
11999 "event": "MIGRATION_PASS", "data": {"pass": 2} }
12000 COLOMessage (Enum)
12002 The message transmission between Primary side and Secondary side.
12004 Values:
12006 "checkpoint-ready"
12008 Secondary VM (SVM) is ready for checkpointing
12009 "checkpoint-request"
12011 Primary VM (PVM) tells SVM to prepare for checkpointing
12012 "checkpoint-reply"
12014 SVM gets PVM's checkpoint request
12015 "vmstate-send"
12017 VM's state will be sent by PVM.
12018 "vmstate-size"
12020 The total size of VMstate.
12021 "vmstate-received"
12023 VM's state has been received by SVM.
12024 "vmstate-loaded"
12026 VM's state has been loaded by SVM.
12027 Since: 2.8
12029 COLOMode (Enum)
12031 The COLO current mode.
12033 Values:
12035 "none"
12037 COLO is disabled.
12038 "primary"
12040 COLO node in primary side.
12041 "secondary"
12043 COLO node in slave side.
12044 Since: 2.8
12046 FailoverStatus (Enum)
12048 An enumeration of COLO failover status
12050 Values:
12052 "none"
12054 no failover has ever happened
12055 "require"
12057 got failover requirement but not handled
12058 "active"
12060 in the process of doing failover
12061 "completed"
12063 finish the process of failover
12064 "relaunch"
12066 restart the failover process, from 'none' -> 'completed' (Since
12067 2.9)
12068 Since: 2.8
12070 COLO_EXIT (Event) Emitted when VM finishes COLO mode due to some
12072 errors happening or at the request of users.
12073 Arguments:
12075 "mode: COLOMode"
12077 report COLO mode when COLO exited.
12078 "reason: COLOExitReason"
12080 describes the reason for the COLO exit.
12081 Since: 3.1
12083 Example:
12085 <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
12087 "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
12088 COLOExitReason (Enum)
12090 The reason for a COLO exit.
12092 Values:
12094 "none"
12096 failover has never happened. This state does not occur in the
12097 COLO_EXIT event, and is only visible in the result of query-colo-
12098 status.
12099 "request"
12101 COLO exit is due to an external request.
12102 "error"
12104 COLO exit is due to an internal error.
12105 "processing"
12107 COLO is currently handling a failover (since 4.0).
12108 Since: 3.1
12110 x-colo-lost-heartbeat (Command) Tell qemu that heartbeat is lost,
12112 request it to do takeover procedures. If this command is sent to the
12113 PVM, the Primary side will exit COLO mode. If sent to the Secondary,
12114 the Secondary side will run failover work, then takes over server
12115 operation to become the service VM.
12116 Since: 2.8
12118 Example:
12120 -> { "execute": "x-colo-lost-heartbeat" }
12122 <- { "return": {} }
12123 migrate_cancel (Command) Cancel the current executing migration
12125 process.
12126 Returns: nothing on success
12128 Notes: This command succeeds even if there is no migration process
12130 running.
12131 Since: 0.14.0
12133 Example:
12135 -> { "execute": "migrate_cancel" }
12137 <- { "return": {} }
12138 migrate-continue (Command) Continue migration when it's in a paused
12140 state.
12141 Arguments:
12143 "state: MigrationStatus"
12145 The state the migration is currently expected to be in
12146 Returns: nothing on success
12148 Since: 2.11
12150 Example:
12152 -> { "execute": "migrate-continue" , "arguments":
12154 { "state": "pre-switchover" } }
12155 <- { "return": {} }
12156 migrate_set_downtime (Command) Set maximum tolerated downtime for
12158 migration.
12159 Arguments:
12161 "value: number"
12163 maximum downtime in seconds
12164 Returns: nothing on success
12166 Notes: This command is deprecated in favor of 'migrate-set-parameters'
12168 Since: 0.14.0
12170 Example:
12172 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
12174 <- { "return": {} }
12175 migrate_set_speed (Command) Set maximum speed for migration.
12177 Arguments:
12179 "value: int"
12181 maximum speed in bytes per second.
12182 Returns: nothing on success
12184 Notes: This command is deprecated in favor of 'migrate-set-parameters'
12186 Since: 0.14.0
12188 Example:
12190 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
12192 <- { "return": {} }
12193 migrate-set-cache-size (Command) Set cache size to be used by XBZRLE
12195 migration
12196 Arguments:
12198 "value: int"
12200 cache size in bytes
12201 The size will be rounded down to the nearest power of 2. The cache
12203 size can be modified before and during ongoing migration
12204 Returns: nothing on success
12206 Notes: This command is deprecated in favor of 'migrate-set-parameters'
12208 Since: 1.2
12210 Example:
12212 -> { "execute": "migrate-set-cache-size",
12214 "arguments": { "value": 536870912 } }
12215 <- { "return": {} }
12216 query-migrate-cache-size (Command) Query migration XBZRLE cache size
12218 Returns: XBZRLE cache size in bytes
12220 Notes: This command is deprecated in favor of
12222 'query-migrate-parameters'
12223 Since: 1.2
12225 Example:
12227 -> { "execute": "query-migrate-cache-size" }
12229 <- { "return": 67108864 }
12230 migrate (Command) Migrates the current running guest to another
12232 Virtual Machine.
12233 Arguments:
12235 "uri: string"
12237 the Uniform Resource Identifier of the destination VM
12238 "blk: boolean" (optional)
12240 do block migration (full disk copy)
12241 "inc: boolean" (optional)
12243 incremental disk copy migration
12244 "detach: boolean" (optional)
12246 this argument exists only for compatibility reasons and is ignored
12247 by QEMU
12248 "resume: boolean" (optional)
12250 resume one paused migration, default "off". (since 3.0)
12251 Returns: nothing on success
12253 Since: 0.14.0
12255 Notes:
12257 1. The 'query-migrate' command should be used to check migration's
12259 progress and final result (this information is provided by the
12260 'status' member)
12261 2. All boolean arguments default to false
12263 3. The user Monitor's "detach" argument is invalid in QMP and should
12265 not be used
12266 Example:
12268 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
12270 <- { "return": {} }
12271 migrate-incoming (Command) Start an incoming migration, the qemu must
12273 have been started with -incoming defer
12274 Arguments:
12276 "uri: string"
12278 The Uniform Resource Identifier identifying the source or address
12279 to listen on
12280 Returns: nothing on success
12282 Since: 2.3
12284 Notes:
12286 1. It's a bad idea to use a string for the uri, but it needs to stay
12288 compatible with -incoming and the format of the uri is already
12289 exposed above libvirt.
12290 2. QEMU must be started with -incoming defer to allow migrate-incoming
12292 to be used.
12293 3. The uri format is the same as for -incoming
12295 Example:
12297 -> { "execute": "migrate-incoming",
12299 "arguments": { "uri": "tcp::4446" } }
12300 <- { "return": {} }
12301 xen-save-devices-state (Command) Save the state of all devices to
12303 file. The RAM and the block devices of the VM are not saved by this
12304 command.
12305 Arguments:
12307 "filename: string"
12309 the file to save the state of the devices to as binary data. See
12310 xen-save-devices-state.txt for a description of the binary format.
12311 "live: boolean" (optional)
12313 Optional argument to ask QEMU to treat this command as part of a
12314 live migration. Default to true. (since 2.11)
12315 Returns: Nothing on success
12317 Since: 1.1
12319 Example:
12321 -> { "execute": "xen-save-devices-state",
12323 "arguments": { "filename": "/tmp/save" } }
12324 <- { "return": {} }
12325 xen-set-replication (Command) Enable or disable replication.
12327 Arguments:
12329 "enable: boolean"
12331 true to enable, false to disable.
12332 "primary: boolean"
12334 true for primary or false for secondary.
12335 "failover: boolean" (optional)
12337 true to do failover, false to stop. but cannot be specified if
12338 'enable' is true. default value is false.
12339 Returns: nothing.
12341 Example:
12343 -> { "execute": "xen-set-replication",
12345 "arguments": {"enable": true, "primary": false} }
12346 <- { "return": {} }
12347 Since: 2.9
12349 If: "defined(CONFIG_REPLICATION)"
12351 ReplicationStatus (Object)
12353 The result format for 'query-xen-replication-status'.
12355 Members:
12357 "error: boolean"
12359 true if an error happened, false if replication is normal.
12360 "desc: string" (optional)
12362 the human readable error description string, when "error" is
12363 'true'.
12364 Since: 2.9
12366 If: "defined(CONFIG_REPLICATION)"
12368 query-xen-replication-status (Command) Query replication status while
12370 the vm is running.
12371 Returns: A "ReplicationResult" object showing the status.
12373 Example:
12375 -> { "execute": "query-xen-replication-status" }
12377 <- { "return": { "error": false } }
12378 Since: 2.9
12380 If: "defined(CONFIG_REPLICATION)"
12382 xen-colo-do-checkpoint (Command) Xen uses this command to notify
12384 replication to trigger a checkpoint.
12385 Returns: nothing.
12387 Example:
12389 -> { "execute": "xen-colo-do-checkpoint" }
12391 <- { "return": {} }
12392 Since: 2.9
12394 If: "defined(CONFIG_REPLICATION)"
12396 COLOStatus (Object)
12398 The result format for 'query-colo-status'.
12400 Members:
12402 "mode: COLOMode"
12404 COLO running mode. If COLO is running, this field will return
12405 'primary' or 'secondary'.
12406 "last-mode: COLOMode"
12408 COLO last running mode. If COLO is running, this field will return
12409 same like mode field, after failover we can use this field to get
12410 last colo mode. (since 4.0)
12411 "reason: COLOExitReason"
12413 describes the reason for the COLO exit.
12414 Since: 3.1
12416 query-colo-status (Command) Query COLO status while the vm is running.
12418 Returns: A "COLOStatus" object showing the status.
12420 Example:
12422 -> { "execute": "query-colo-status" }
12424 <- { "return": { "mode": "primary", "reason": "request" } }
12425 Since: 3.1
12427 migrate-recover (Command) Provide a recovery migration stream URI.
12429 Arguments:
12431 "uri: string"
12433 the URI to be used for the recovery of migration stream.
12434 Returns: nothing.
12436 Example:
12438 -> { "execute": "migrate-recover",
12440 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
12441 <- { "return": {} }
12442 Since: 3.0
12444 migrate-pause (Command) Pause a migration. Currently it only supports
12446 postcopy.
12447 Returns: nothing.
12449 Example:
12451 -> { "execute": "migrate-pause" }
12453 <- { "return": {} }
12454 Since: 3.0
12456 Transactions
12458 Abort (Object)
12459 This action can be used to test transaction failure.
12461 Since: 1.6
12463 ActionCompletionMode (Enum)
12465 An enumeration of Transactional completion modes.
12467 Values:
12469 "individual"
12471 Do not attempt to cancel any other Actions if any Actions fail
12472 after the Transaction request succeeds. All Actions that can
12473 complete successfully will do so without waiting on others. This
12474 is the default.
12475 "grouped"
12477 If any Action fails after the Transaction succeeds, cancel all
12478 Actions. Actions do not complete until all Actions are ready to
12479 complete. May be rejected by Actions that do not support this
12480 completion mode.
12481 Since: 2.5
12483 TransactionAction (Object)
12485 A discriminated record of operations that can be performed with
12487 "transaction". Action "type" can be:
12488 - "abort": since 1.6
12490 - "block-dirty-bitmap-add": since 2.5
12492 - "block-dirty-bitmap-clear": since 2.5
12494 - "block-dirty-bitmap-enable": since 4.0
12496 - "block-dirty-bitmap-disable": since 4.0
12498 - "block-dirty-bitmap-merge": since 4.0
12500 - "blockdev-backup": since 2.3
12502 - "blockdev-snapshot": since 2.5
12504 - "blockdev-snapshot-internal-sync": since 1.7
12506 - "blockdev-snapshot-sync": since 1.1
12508 - "drive-backup": since 1.6
12510 Members:
12512 "type"
12514 One of "abort", "block-dirty-bitmap-add", "block-dirty-bitmap-
12515 clear", "block-dirty-bitmap-enable", "block-dirty-bitmap-disable",
12516 "block-dirty-bitmap-merge", "blockdev-backup", "blockdev-snapshot",
12517 "blockdev-snapshot-internal-sync", "blockdev-snapshot-sync",
12518 "drive-backup"
12519 "data: Abort" when "type" is "abort"
12521 "data: BlockDirtyBitmapAdd" when "type" is "block-dirty-bitmap-add"
12522 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-clear"
12523 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-enable"
12524 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-disable"
12525 "data: BlockDirtyBitmapMerge" when "type" is "block-dirty-bitmap-merge"
12526 "data: BlockdevBackup" when "type" is "blockdev-backup"
12527 "data: BlockdevSnapshot" when "type" is "blockdev-snapshot"
12528 "data: BlockdevSnapshotInternal" when "type" is "blockdev-snapshot-
12529 internal-sync"
12530 "data: BlockdevSnapshotSync" when "type" is "blockdev-snapshot-sync"
12531 "data: DriveBackup" when "type" is "drive-backup"
12532 Since: 1.1
12534 TransactionProperties (Object)
12536 Optional arguments to modify the behavior of a Transaction.
12538 Members:
12540 "completion-mode: ActionCompletionMode" (optional)
12542 Controls how jobs launched asynchronously by Actions will complete
12543 or fail as a group. See "ActionCompletionMode" for details.
12544 Since: 2.5
12546 transaction (Command) Executes a number of transactionable QMP
12548 commands atomically. If any operation fails, then the entire set of
12549 actions will be abandoned and the appropriate error returned.
12550 For external snapshots, the dictionary contains the device, the file to
12552 use for the new snapshot, and the format. The default format, if not
12553 specified, is qcow2.
12554 Each new snapshot defaults to being created by QEMU (wiping any
12556 contents if the file already exists), but it is also possible to reuse
12557 an externally-created file. In the latter case, you should ensure that
12558 the new image file has the same contents as the current one; QEMU
12559 cannot perform any meaningful check. Typically this is achieved by
12560 using the current image file as the backing file for the new image.
12561 On failure, the original disks pre-snapshot attempt will be used.
12563 For internal snapshots, the dictionary contains the device and the
12565 snapshot's name. If an internal snapshot matching name already exists,
12566 the request will be rejected. Only some image formats support it, for
12567 example, qcow2, rbd, and sheepdog.
12568 On failure, qemu will try delete the newly created internal snapshot in
12570 the transaction. When an I/O error occurs during deletion, the user
12571 needs to fix it later with qemu-img or other command.
12572 Arguments:
12574 "actions: array of TransactionAction"
12576 List of "TransactionAction"; information needed for the respective
12577 operations.
12578 "properties: TransactionProperties" (optional)
12580 structure of additional options to control the execution of the
12581 transaction. See "TransactionProperties" for additional detail.
12582 Returns: nothing on success
12584 Errors depend on the operations of the transaction
12586 Note: The transaction aborts on the first failure. Therefore, there
12588 will be information on only one failed operation returned in an error
12589 condition, and subsequent actions will not have been attempted.
12590 Since: 1.1
12592 Example:
12594 -> { "execute": "transaction",
12596 "arguments": { "actions": [
12597 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
12598 "snapshot-file": "/some/place/my-image",
12599 "format": "qcow2" } },
12600 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
12601 "snapshot-file": "/some/place/my-image2",
12602 "snapshot-node-name": "node3432",
12603 "mode": "existing",
12604 "format": "qcow2" } },
12605 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
12606 "snapshot-file": "/some/place/my-image2",
12607 "mode": "existing",
12608 "format": "qcow2" } },
12609 { "type": "blockdev-snapshot-internal-sync", "data" : {
12610 "device": "ide-hd2",
12611 "name": "snapshot0" } } ] } }
12612 <- { "return": {} }
12613 Tracing
12615 TraceEventState (Enum)
12616 State of a tracing event.
12618 Values:
12620 "unavailable"
12622 The event is statically disabled.
12623 "disabled"
12625 The event is dynamically disabled.
12626 "enabled"
12628 The event is dynamically enabled.
12629 Since: 2.2
12631 TraceEventInfo (Object)
12633 Information of a tracing event.
12635 Members:
12637 "name: string"
12639 Event name.
12640 "state: TraceEventState"
12642 Tracing state.
12643 "vcpu: boolean"
12645 Whether this is a per-vCPU event (since 2.7).
12646 An event is per-vCPU if it has the "vcpu" property in the "trace-
12648 events" files.
12649 Since: 2.2
12651 trace-event-get-state (Command) Query the state of events.
12653 Arguments:
12655 "name: string"
12657 Event name pattern (case-sensitive glob).
12658 "vcpu: int" (optional)
12660 The vCPU to query (any by default; since 2.7).
12661 Returns: a list of "TraceEventInfo" for the matching events
12663 An event is returned if:
12665 - its name matches the "name" pattern, and
12667 - if "vcpu" is given, the event has the "vcpu" property.
12669 Therefore, if "vcpu" is given, the operation will only match per-vCPU
12671 events, returning their state on the specified vCPU. Special case: if
12672 "name" is an exact match, "vcpu" is given and the event does not have
12673 the "vcpu" property, an error is returned.
12674 Since: 2.2
12676 Example:
12678 -> { "execute": "trace-event-get-state",
12680 "arguments": { "name": "qemu_memalign" } }
12681 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
12682 trace-event-set-state (Command) Set the dynamic tracing state of
12684 events.
12685 Arguments:
12687 "name: string"
12689 Event name pattern (case-sensitive glob).
12690 "enable: boolean"
12692 Whether to enable tracing.
12693 "ignore-unavailable: boolean" (optional)
12695 Do not match unavailable events with "name".
12696 "vcpu: int" (optional)
12698 The vCPU to act upon (all by default; since 2.7).
12699 An event's state is modified if:
12701 - its name matches the "name" pattern, and
12703 - if "vcpu" is given, the event has the "vcpu" property.
12705 Therefore, if "vcpu" is given, the operation will only match per-vCPU
12707 events, setting their state on the specified vCPU. Special case: if
12708 "name" is an exact match, "vcpu" is given and the event does not have
12709 the "vcpu" property, an error is returned.
12710 Since: 2.2
12712 Example:
12714 -> { "execute": "trace-event-set-state",
12716 "arguments": { "name": "qemu_memalign", "enable": "true" } }
12717 <- { "return": {} }
12718 QMP introspection
12720 query-qmp-schema (Command) Command query-qmp-schema exposes the QMP
12721 wire ABI as an array of SchemaInfo. This lets QMP clients figure out
12722 what commands and events are available in this QEMU, and their
12723 parameters and results.
12724 However, the SchemaInfo can't reflect all the rules and restrictions
12726 that apply to QMP. It's interface introspection (figuring out what's
12727 there), not interface specification. The specification is in the QAPI
12728 schema.
12729 Furthermore, while we strive to keep the QMP wire format backwards-
12731 compatible across qemu versions, the introspection output is not
12732 guaranteed to have the same stability. For example, one version of
12733 qemu may list an object member as an optional non-variant, while
12734 another lists the same member only through the object's variants; or
12735 the type of a member may change from a generic string into a specific
12736 enum or from one specific type into an alternate that includes the
12737 original type alongside something else.
12738 Returns: array of "SchemaInfo", where each element describes an entity
12740 in the ABI: command, event, type, ...
12741 The order of the various SchemaInfo is unspecified; however, all names
12743 are guaranteed to be unique (no name will be duplicated with different
12744 meta-types).
12745 Note: the QAPI schema is also used to help define internal interfaces,
12747 by defining QAPI types. These are not part of the QMP wire ABI, and
12748 therefore not returned by this command.
12749 Since: 2.5
12751 SchemaMetaType (Enum)
12753 This is a "SchemaInfo"'s meta type, i.e. the kind of entity it
12755 describes.
12756 Values:
12758 "builtin"
12760 a predefined type such as 'int' or 'bool'.
12761 "enum"
12763 an enumeration type
12764 "array"
12766 an array type
12767 "object"
12769 an object type (struct or union)
12770 "alternate"
12772 an alternate type
12773 "command"
12775 a QMP command
12776 "event"
12778 a QMP event
12779 Since: 2.5
12781 SchemaInfo (Object)
12783 Members:
12785 "name: string"
12787 the entity's name, inherited from "base". The SchemaInfo is always
12788 referenced by this name. Commands and events have the name defined
12789 in the QAPI schema. Unlike command and event names, type names are
12790 not part of the wire ABI. Consequently, type names are meaningless
12791 strings here, although they are still guaranteed unique regardless
12792 of "meta-type".
12793 "meta-type: SchemaMetaType"
12795 the entity's meta type, inherited from "base".
12796 The members of "SchemaInfoBuiltin" when "meta-type" is "builtin"
12798 The members of "SchemaInfoEnum" when "meta-type" is "enum"
12799 The members of "SchemaInfoArray" when "meta-type" is "array"
12800 The members of "SchemaInfoObject" when "meta-type" is "object"
12801 The members of "SchemaInfoAlternate" when "meta-type" is "alternate"
12802 The members of "SchemaInfoCommand" when "meta-type" is "command"
12803 The members of "SchemaInfoEvent" when "meta-type" is "event"
12804 Additional members depend on the value of "meta-type".
12806 Since: 2.5
12808 SchemaInfoBuiltin (Object)
12810 Additional SchemaInfo members for meta-type 'builtin'.
12812 Members:
12814 "json-type: JSONType"
12816 the JSON type used for this type on the wire.
12817 Since: 2.5
12819 JSONType (Enum)
12821 The four primitive and two structured types according to RFC 8259
12823 section 1, plus 'int' (split off 'number'), plus the obvious top type
12824 'value'.
12825 Values:
12827 "string"
12829 Not documented
12830 "number"
12832 Not documented
12833 "int"
12835 Not documented
12836 "boolean"
12838 Not documented
12839 "null"
12841 Not documented
12842 "object"
12844 Not documented
12845 "array"
12847 Not documented
12848 "value"
12850 Not documented
12851 Since: 2.5
12853 SchemaInfoEnum (Object)
12855 Additional SchemaInfo members for meta-type 'enum'.
12857 Members:
12859 "values: array of string"
12861 the enumeration type's values, in no particular order.
12862 Values of this type are JSON string on the wire.
12864 Since: 2.5
12866 SchemaInfoArray (Object)
12868 Additional SchemaInfo members for meta-type 'array'.
12870 Members:
12872 "element-type: string"
12874 the array type's element type.
12875 Values of this type are JSON array on the wire.
12877 Since: 2.5
12879 SchemaInfoObject (Object)
12881 Additional SchemaInfo members for meta-type 'object'.
12883 Members:
12885 "members: array of SchemaInfoObjectMember"
12887 the object type's (non-variant) members, in no particular order.
12888 "tag: string" (optional)
12890 the name of the member serving as type tag. An element of
12891 "members" with this name must exist.
12892 "variants: array of SchemaInfoObjectVariant" (optional)
12894 variant members, i.e. additional members that depend on the type
12895 tag's value. Present exactly when "tag" is present. The variants
12896 are in no particular order, and may even differ from the order of
12897 the values of the enum type of the "tag".
12898 "features: array of string" (optional)
12900 names of features associated with the type, in no particular order.
12901 (since: 4.1)
12902 Values of this type are JSON object on the wire.
12904 Since: 2.5
12906 SchemaInfoObjectMember (Object)
12908 An object member.
12910 Members:
12912 "name: string"
12914 the member's name, as defined in the QAPI schema.
12915 "type: string"
12917 the name of the member's type.
12918 "default: value" (optional)
12920 default when used as command parameter. If absent, the parameter
12921 is mandatory. If present, the value must be null. The parameter
12922 is optional, and behavior when it's missing is not specified here.
12923 Future extension: if present and non-null, the parameter is
12924 optional, and defaults to this value.
12925 Since: 2.5
12927 SchemaInfoObjectVariant (Object)
12929 The variant members for a value of the type tag.
12931 Members:
12933 "case: string"
12935 a value of the type tag.
12936 "type: string"
12938 the name of the object type that provides the variant members when
12939 the type tag has value "case".
12940 Since: 2.5
12942 SchemaInfoAlternate (Object)
12944 Additional SchemaInfo members for meta-type 'alternate'.
12946 Members:
12948 "members: array of SchemaInfoAlternateMember"
12950 the alternate type's members, in no particular order. The members'
12951 wire encoding is distinct, see docs/devel/qapi-code-gen.txt section
12952 Alternate types.
12953 On the wire, this can be any of the members.
12955 Since: 2.5
12957 SchemaInfoAlternateMember (Object)
12959 An alternate member.
12961 Members:
12963 "type: string"
12965 the name of the member's type.
12966 Since: 2.5
12968 SchemaInfoCommand (Object)
12970 Additional SchemaInfo members for meta-type 'command'.
12972 Members:
12974 "arg-type: string"
12976 the name of the object type that provides the command's parameters.
12977 "ret-type: string"
12979 the name of the command's result type.
12980 "allow-oob: boolean" (optional)
12982 whether the command allows out-of-band execution, defaults to false
12983 (Since: 2.12)
12984 TODO: "success-response" (currently irrelevant, because it's QGA, not
12986 QMP)
12987 Since: 2.5
12989 SchemaInfoEvent (Object)
12991 Additional SchemaInfo members for meta-type 'event'.
12993 Members:
12995 "arg-type: string"
12997 the name of the object type that provides the event's parameters.
12998 Since: 2.5
13000 QEMU Object Model (QOM)
13002 ObjectPropertyInfo (Object)
13003 Members:
13005 "name: string"
13007 the name of the property
13008 "type: string"
13010 the type of the property. This will typically come in one of four
13011 forms:
13012 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or
13014 'double'. These types are mapped to the appropriate JSON type.
13015 2) A child type in the form 'child<subtype>' where subtype is a
13017 qdev device type name. Child properties create the composition
13018 tree.
13019 3) A link type in the form 'link<subtype>' where subtype is a qdev
13021 device type name. Link properties form the device model graph.
13022 "description: string" (optional)
13024 if specified, the description of the property.
13025 Since: 1.2
13027 qom-list (Command) This command will list any properties of a object
13029 given a path in the object model.
13030 Arguments:
13032 "path: string"
13034 the path within the object model. See "qom-get" for a description
13035 of this parameter.
13036 Returns: a list of "ObjectPropertyInfo" that describe the properties of
13038 the object.
13039 Since: 1.2
13041 Example:
13043 -> { "execute": "qom-list",
13045 "arguments": { "path": "/chardevs" } }
13046 <- { "return": [ { "name": "type", "type": "string" },
13047 { "name": "parallel0", "type": "child<chardev-vc>" },
13048 { "name": "serial0", "type": "child<chardev-vc>" },
13049 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
13050 qom-get (Command) This command will get a property from a object model
13052 path and return the value.
13053 Arguments:
13055 "path: string"
13057 The path within the object model. There are two forms of supported
13058 paths--absolute and partial paths.
13059 Absolute paths are derived from the root object and can follow
13061 child<> or link<> properties. Since they can follow link<>
13062 properties, they can be arbitrarily long. Absolute paths look like
13063 absolute filenames and are prefixed with a leading slash.
13064 Partial paths look like relative filenames. They do not begin with
13066 a prefix. The matching rules for partial paths are subtle but
13067 designed to make specifying objects easy. At each level of the
13068 composition tree, the partial path is matched as an absolute path.
13069 The first match is not returned. At least two matches are searched
13070 for. A successful result is only returned if only one match is
13071 found. If more than one match is found, a flag is return to
13072 indicate that the match was ambiguous.
13073 "property: string"
13075 The property name to read
13076 Returns: The property value. The type depends on the property type.
13078 child<> and link<> properties are returned as #str pathnames. All
13079 integer property types (u8, u16, etc) are returned as #int.
13080 Since: 1.2
13082 Example:
13084 1. Use absolute path
13086 -> { "execute": "qom-get",
13088 "arguments": { "path": "/machine/unattached/device[0]",
13089 "property": "hotplugged" } }
13090 <- { "return": false }
13091 2. Use partial path
13093 -> { "execute": "qom-get",
13095 "arguments": { "path": "unattached/sysbus",
13096 "property": "type" } }
13097 <- { "return": "System" }
13098 qom-set (Command) This command will set a property from a object model
13100 path.
13101 Arguments:
13103 "path: string"
13105 see "qom-get" for a description of this parameter
13106 "property: string"
13108 the property name to set
13109 "value: value"
13111 a value who's type is appropriate for the property type. See
13112 "qom-get" for a description of type mapping.
13113 Since: 1.2
13115 Example:
13117 -> { "execute": "qom-set",
13119 "arguments": { "path": "/machine",
13120 "property": "graphics",
13121 "value": false } }
13122 <- { "return": {} }
13123 ObjectTypeInfo (Object)
13125 This structure describes a search result from "qom-list-types"
13127 Members:
13129 "name: string"
13131 the type name found in the search
13132 "abstract: boolean" (optional)
13134 the type is abstract and can't be directly instantiated. Omitted
13135 if false. (since 2.10)
13136 "parent: string" (optional)
13138 Name of parent type, if any (since 2.10)
13139 Since: 1.1
13141 qom-list-types (Command) This command will return a list of types
13143 given search parameters
13144 Arguments:
13146 "implements: string" (optional)
13148 if specified, only return types that implement this type name
13149 "abstract: boolean" (optional)
13151 if true, include abstract types in the results
13152 Returns: a list of "ObjectTypeInfo" or an empty list if no results are
13154 found
13155 Since: 1.1
13157 qom-list-properties (Command) List properties associated with a QOM
13159 object.
13160 Arguments:
13162 "typename: string"
13164 the type name of an object
13165 Note: objects can create properties at runtime, for example to describe
13167 links between different devices and/or objects. These properties are
13168 not included in the output of this command.
13169 Returns: a list of ObjectPropertyInfo describing object properties
13171 Since: 2.12
13173 object-add (Command) Create a QOM object.
13175 Arguments:
13177 "qom-type: string"
13179 the class name for the object to be created
13180 "id: string"
13182 the name of the new object
13183 "props: value" (optional)
13185 a dictionary of properties to be passed to the backend
13186 Returns: Nothing on success Error if "qom-type" is not a valid class
13188 name
13189 Since: 2.0
13191 Example:
13193 -> { "execute": "object-add",
13195 "arguments": { "qom-type": "rng-random", "id": "rng1",
13196 "props": { "filename": "/dev/hwrng" } } }
13197 <- { "return": {} }
13198 object-del (Command) Remove a QOM object.
13200 Arguments:
13202 "id: string"
13204 the name of the QOM object to remove
13205 Returns: Nothing on success Error if "id" is not a valid id for a QOM
13207 object
13208 Since: 2.0
13210 Example:
13212 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
13214 <- { "return": {} }
13215 Device infrastructure (qdev)
13217 device-list-properties (Command) List properties associated with a
13218 device.
13219 Arguments:
13221 "typename: string"
13223 the type name of a device
13224 Returns: a list of ObjectPropertyInfo describing a devices properties
13226 Note: objects can create properties at runtime, for example to describe
13228 links between different devices and/or objects. These properties are
13229 not included in the output of this command.
13230 Since: 1.2
13232 device_add (Command)
13234 Arguments:
13236 "driver: string"
13238 the name of the new device's driver
13239 "bus: string" (optional)
13241 the device's parent bus (device tree path)
13242 "id: string" (optional)
13244 the device's ID, must be unique
13245 Additional arguments depend on the type.
13247 Add a device.
13249 Notes:
13251 1. For detailed information about this command, please refer to the
13253 'docs/qdev-device-use.txt' file.
13254 2. It's possible to list device properties by running QEMU with the
13256 "-device DEVICE,help" command-line argument, where DEVICE is the
13257 device's name
13258 Example:
13260 -> { "execute": "device_add",
13262 "arguments": { "driver": "e1000", "id": "net1",
13263 "bus": "pci.0",
13264 "mac": "52:54:00:12:34:56" } }
13265 <- { "return": {} }
13266 TODO: This command effectively bypasses QAPI completely due to its
13268 "additional arguments" business. It shouldn't have been added to the
13269 schema in this form. It should be qapified properly, or replaced by a
13270 properly qapified command.
13271 Since: 0.13
13273 device_del (Command) Remove a device from a guest
13275 Arguments:
13277 "id: string"
13279 the device's ID or QOM path
13280 Returns: Nothing on success If "id" is not a valid device,
13282 DeviceNotFound
13283 Notes: When this command completes, the device may not be removed from
13285 the guest. Hot removal is an operation that requires guest
13286 cooperation. This command merely requests that the guest begin the hot
13287 removal process. Completion of the device removal process is signaled
13288 with a DEVICE_DELETED event. Guest reset will automatically complete
13289 removal for all devices.
13290 Since: 0.14.0
13292 Example:
13294 -> { "execute": "device_del",
13296 "arguments": { "id": "net1" } }
13297 <- { "return": {} }
13298 -> { "execute": "device_del",
13300 "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
13301 <- { "return": {} }
13302 DEVICE_DELETED (Event) Emitted whenever the device removal completion
13304 is acknowledged by the guest. At this point, it's safe to reuse the
13305 specified device ID. Device removal can be initiated by the guest or by
13306 HMP/QMP commands.
13307 Arguments:
13309 "device: string" (optional)
13311 device name
13312 "path: string"
13314 device path
13315 Since: 1.5
13317 Example:
13319 <- { "event": "DEVICE_DELETED",
13321 "data": { "device": "virtio-net-pci-0",
13322 "path": "/machine/peripheral/virtio-net-pci-0" },
13323 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
13324 Machines
13326 CpuInfoArch (Enum)
13327 An enumeration of cpu types that enable additional information during
13329 "query-cpus" and "query-cpus-fast".
13330 Values:
13332 "s390"
13334 since 2.12
13335 "riscv"
13337 since 2.12
13338 "x86"
13340 Not documented
13341 "sparc"
13343 Not documented
13344 "ppc"
13346 Not documented
13347 "mips"
13349 Not documented
13350 "tricore"
13352 Not documented
13353 "other"
13355 Not documented
13356 Since: 2.6
13358 CpuInfo (Object)
13360 Information about a virtual CPU
13362 Members:
13364 "CPU: int"
13366 the index of the virtual CPU
13367 "current: boolean"
13369 this only exists for backwards compatibility and should be ignored
13370 "halted: boolean"
13372 true if the virtual CPU is in the halt state. Halt usually refers
13373 to a processor specific low power mode.
13374 "qom_path: string"
13376 path to the CPU object in the QOM tree (since 2.4)
13377 "thread_id: int"
13379 ID of the underlying host thread
13380 "props: CpuInstanceProperties" (optional)
13382 properties describing to which node/socket/core/thread virtual CPU
13383 belongs to, provided if supported by board (since 2.10)
13384 "arch: CpuInfoArch"
13386 architecture of the cpu, which determines which additional fields
13387 will be listed (since 2.6)
13388 The members of "CpuInfoX86" when "arch" is "x86"
13390 The members of "CpuInfoSPARC" when "arch" is "sparc"
13391 The members of "CpuInfoPPC" when "arch" is "ppc"
13392 The members of "CpuInfoMIPS" when "arch" is "mips"
13393 The members of "CpuInfoTricore" when "arch" is "tricore"
13394 The members of "CpuInfoS390" when "arch" is "s390"
13395 The members of "CpuInfoRISCV" when "arch" is "riscv"
13396 Since: 0.14.0
13398 Notes: "halted" is a transient state that changes frequently. By the
13400 time the data is sent to the client, the guest may no longer be halted.
13401 CpuInfoX86 (Object)
13403 Additional information about a virtual i386 or x86_64 CPU
13405 Members:
13407 "pc: int"
13409 the 64-bit instruction pointer
13410 Since: 2.6
13412 CpuInfoSPARC (Object)
13414 Additional information about a virtual SPARC CPU
13416 Members:
13418 "pc: int"
13420 the PC component of the instruction pointer
13421 "npc: int"
13423 the NPC component of the instruction pointer
13424 Since: 2.6
13426 CpuInfoPPC (Object)
13428 Additional information about a virtual PPC CPU
13430 Members:
13432 "nip: int"
13434 the instruction pointer
13435 Since: 2.6
13437 CpuInfoMIPS (Object)
13439 Additional information about a virtual MIPS CPU
13441 Members:
13443 "PC: int"
13445 the instruction pointer
13446 Since: 2.6
13448 CpuInfoTricore (Object)
13450 Additional information about a virtual Tricore CPU
13452 Members:
13454 "PC: int"
13456 the instruction pointer
13457 Since: 2.6
13459 CpuInfoRISCV (Object)
13461 Additional information about a virtual RISCV CPU
13463 Members:
13465 "pc: int"
13467 the instruction pointer
13468 Since 2.12
13470 CpuS390State (Enum)
13472 An enumeration of cpu states that can be assumed by a virtual S390 CPU
13474 Values:
13476 "uninitialized"
13478 Not documented
13479 "stopped"
13481 Not documented
13482 "check-stop"
13484 Not documented
13485 "operating"
13487 Not documented
13488 "load"
13490 Not documented
13491 Since: 2.12
13493 CpuInfoS390 (Object)
13495 Additional information about a virtual S390 CPU
13497 Members:
13499 "cpu-state: CpuS390State"
13501 the virtual CPU's state
13502 Since: 2.12
13504 query-cpus (Command) Returns a list of information about each virtual
13506 CPU.
13507 This command causes vCPU threads to exit to userspace, which causes a
13509 small interruption to guest CPU execution. This will have a negative
13510 impact on realtime guests and other latency sensitive guest workloads.
13511 It is recommended to use "query-cpus-fast" instead of this command to
13512 avoid the vCPU interruption.
13513 Returns: a list of "CpuInfo" for each virtual CPU
13515 Since: 0.14.0
13517 Example:
13519 -> { "execute": "query-cpus" }
13521 <- { "return": [
13522 {
13523 "CPU":0,
13524 "current":true,
13525 "halted":false,
13526 "qom_path":"/machine/unattached/device[0]",
13527 "arch":"x86",
13528 "pc":3227107138,
13529 "thread_id":3134
13530 },
13531 {
13532 "CPU":1,
13533 "current":false,
13534 "halted":true,
13535 "qom_path":"/machine/unattached/device[2]",
13536 "arch":"x86",
13537 "pc":7108165,
13538 "thread_id":3135
13539 }
13540 ]
13541 }
13542 Notes: This interface is deprecated (since 2.12.0), and it is strongly
13544 recommended that you avoid using it. Use "query-cpus-fast" to obtain
13545 information about virtual CPUs.
13546 CpuInfoFast (Object)
13548 Information about a virtual CPU
13550 Members:
13552 "cpu-index: int"
13554 index of the virtual CPU
13555 "qom-path: string"
13557 path to the CPU object in the QOM tree
13558 "thread-id: int"
13560 ID of the underlying host thread
13561 "props: CpuInstanceProperties" (optional)
13563 properties describing to which node/socket/core/thread virtual CPU
13564 belongs to, provided if supported by board
13565 "arch: CpuInfoArch"
13567 base architecture of the cpu; deprecated since 3.0.0 in favor of
13568 "target"
13569 "target: SysEmuTarget"
13571 the QEMU system emulation target, which determines which additional
13572 fields will be listed (since 3.0)
13573 The members of "CpuInfoS390" when "target" is "s390x"
13575 Since: 2.12
13577 query-cpus-fast (Command) Returns information about all virtual CPUs.
13579 This command does not incur a performance penalty and should be used in
13580 production instead of query-cpus.
13581 Returns: list of "CpuInfoFast"
13583 Since: 2.12
13585 Example:
13587 -> { "execute": "query-cpus-fast" }
13589 <- { "return": [
13590 {
13591 "thread-id": 25627,
13592 "props": {
13593 "core-id": 0,
13594 "thread-id": 0,
13595 "socket-id": 0
13596 },
13597 "qom-path": "/machine/unattached/device[0]",
13598 "arch":"x86",
13599 "target":"x86_64",
13600 "cpu-index": 0
13601 },
13602 {
13603 "thread-id": 25628,
13604 "props": {
13605 "core-id": 0,
13606 "thread-id": 0,
13607 "socket-id": 1
13608 },
13609 "qom-path": "/machine/unattached/device[2]",
13610 "arch":"x86",
13611 "target":"x86_64",
13612 "cpu-index": 1
13613 }
13614 ]
13615 }
13616 cpu-add (Command) Adds CPU with specified ID.
13618 Arguments:
13620 "id: int"
13622 ID of CPU to be created, valid values [0..max_cpus)
13623 Returns: Nothing on success
13625 Since: 1.5
13627 Note: This command is deprecated. The `device_add` command should be
13629 used instead. See the `query-hotpluggable-cpus` command for details.
13630 Example:
13632 -> { "execute": "cpu-add", "arguments": { "id": 2 } }
13634 <- { "return": {} }
13635 MachineInfo (Object)
13637 Information describing a machine.
13639 Members:
13641 "name: string"
13643 the name of the machine
13644 "alias: string" (optional)
13646 an alias for the machine name
13647 "is-default: boolean" (optional)
13649 whether the machine is default
13650 "cpu-max: int"
13652 maximum number of CPUs supported by the machine type (since 1.5.0)
13653 "hotpluggable-cpus: boolean"
13655 cpu hotplug via -device is supported (since 2.7.0)
13656 "numa-mem-supported: boolean"
13658 true if '-numa node,mem' option is supported by the machine type
13659 and false otherwise (since 4.1)
13660 "deprecated: boolean"
13662 if true, the machine type is deprecated and may be removed in
13663 future versions of QEMU according to the QEMU deprecation policy
13664 (since 4.1.0)
13665 Since: 1.2.0
13667 query-machines (Command) Return a list of supported machines
13669 Returns: a list of MachineInfo
13671 Since: 1.2.0
13673 CurrentMachineParams (Object)
13675 Information describing the running machine parameters.
13677 Members:
13679 "wakeup-suspend-support: boolean"
13681 true if the machine supports wake up from suspend
13682 Since: 4.0
13684 query-current-machine (Command) Return information on the current
13686 virtual machine.
13687 Returns: CurrentMachineParams
13689 Since: 4.0
13691 NumaOptionsType (Enum)
13693 Values:
13695 "node"
13697 NUMA nodes configuration
13698 "dist"
13700 NUMA distance configuration (since 2.10)
13701 "cpu"
13703 property based CPU(s) to node mapping (Since: 2.10)
13704 Since: 2.1
13706 NumaOptions (Object)
13708 A discriminated record of NUMA options. (for OptsVisitor)
13710 Members:
13712 "type: NumaOptionsType"
13714 Not documented
13715 The members of "NumaNodeOptions" when "type" is "node"
13717 The members of "NumaDistOptions" when "type" is "dist"
13718 The members of "NumaCpuOptions" when "type" is "cpu"
13719 Since: 2.1
13721 NumaNodeOptions (Object)
13723 Create a guest NUMA node. (for OptsVisitor)
13725 Members:
13727 "nodeid: int" (optional)
13729 NUMA node ID (increase by 1 from 0 if omitted)
13730 "cpus: array of int" (optional)
13732 VCPUs belonging to this node (assign VCPUS round-robin if omitted)
13733 "mem: int" (optional)
13735 memory size of this node; mutually exclusive with "memdev".
13736 Equally divide total memory among nodes if both "mem" and "memdev"
13737 are omitted.
13738 "memdev: string" (optional)
13740 memory backend object. If specified for one node, it must be
13741 specified for all nodes.
13742 Since: 2.1
13744 NumaDistOptions (Object)
13746 Set the distance between 2 NUMA nodes.
13748 Members:
13750 "src: int"
13752 source NUMA node.
13753 "dst: int"
13755 destination NUMA node.
13756 "val: int"
13758 NUMA distance from source node to destination node. When a node is
13759 unreachable from another node, set the distance between them to
13760 255.
13761 Since: 2.10
13763 X86CPURegister32 (Enum)
13765 A X86 32-bit register
13767 Values:
13769 "EAX"
13771 Not documented
13772 "EBX"
13774 Not documented
13775 "ECX"
13777 Not documented
13778 "EDX"
13780 Not documented
13781 "ESP"
13783 Not documented
13784 "EBP"
13786 Not documented
13787 "ESI"
13789 Not documented
13790 "EDI"
13792 Not documented
13793 Since: 1.5
13795 X86CPUFeatureWordInfo (Object)
13797 Information about a X86 CPU feature word
13799 Members:
13801 "cpuid-input-eax: int"
13803 Input EAX value for CPUID instruction for that feature word
13804 "cpuid-input-ecx: int" (optional)
13806 Input ECX value for CPUID instruction for that feature word
13807 "cpuid-register: X86CPURegister32"
13809 Output register containing the feature bits
13810 "features: int"
13812 value of output register, containing the feature bits
13813 Since: 1.5
13815 DummyForceArrays (Object)
13817 Not used by QMP; hack to let us use X86CPUFeatureWordInfoList
13819 internally
13820 Members:
13822 "unused: array of X86CPUFeatureWordInfo"
13824 Not documented
13825 Since: 2.5
13827 NumaCpuOptions (Object)
13829 Option "-numa cpu" overrides default cpu to node mapping. It accepts
13831 the same set of cpu properties as returned by
13832 query-hotpluggable-cpus[].props, where node-id could be used to
13833 override default node mapping.
13834 Members:
13836 The members of "CpuInstanceProperties"
13838 Since: 2.10
13840 HostMemPolicy (Enum)
13842 Host memory policy types
13844 Values:
13846 "default"
13848 restore default policy, remove any nondefault policy
13849 "preferred"
13851 set the preferred host nodes for allocation
13852 "bind"
13854 a strict policy that restricts memory allocation to the host nodes
13855 specified
13856 "interleave"
13858 memory allocations are interleaved across the set of host nodes
13859 specified
13860 Since: 2.1
13862 Memdev (Object)
13864 Information about memory backend
13866 Members:
13868 "id: string" (optional)
13870 backend's ID if backend has 'id' property (since 2.9)
13871 "size: int"
13873 memory backend size
13874 "merge: boolean"
13876 enables or disables memory merge support
13877 "dump: boolean"
13879 includes memory backend's memory in a core dump or not
13880 "prealloc: boolean"
13882 enables or disables memory preallocation
13883 "host-nodes: array of int"
13885 host nodes for its memory policy
13886 "policy: HostMemPolicy"
13888 memory policy of memory backend
13889 Since: 2.1
13891 query-memdev (Command) Returns information for all memory backends.
13893 Returns: a list of "Memdev".
13895 Since: 2.1
13897 Example:
13899 -> { "execute": "query-memdev" }
13901 <- { "return": [
13902 {
13903 "id": "mem1",
13904 "size": 536870912,
13905 "merge": false,
13906 "dump": true,
13907 "prealloc": false,
13908 "host-nodes": [0, 1],
13909 "policy": "bind"
13910 },
13911 {
13912 "size": 536870912,
13913 "merge": false,
13914 "dump": true,
13915 "prealloc": true,
13916 "host-nodes": [2, 3],
13917 "policy": "preferred"
13918 }
13919 ]
13920 }
13921 CpuInstanceProperties (Object)
13923 List of properties to be used for hotplugging a CPU instance, it should
13925 be passed by management with device_add command when a CPU is being
13926 hotplugged.
13927 Members:
13929 "node-id: int" (optional)
13931 NUMA node ID the CPU belongs to
13932 "socket-id: int" (optional)
13934 socket number within node/board the CPU belongs to
13935 "die-id: int" (optional)
13937 die number within node/board the CPU belongs to (Since 4.1)
13938 "core-id: int" (optional)
13940 core number within die the CPU belongs to# "thread-id": thread
13941 number within core the CPU belongs to
13942 "thread-id: int" (optional)
13944 Not documented
13945 Note: currently there are 5 properties that could be present but
13947 management should be prepared to pass through other properties with
13948 device_add command to allow for future interface extension. This also
13949 requires the filed names to be kept in sync with the properties passed
13950 to -device/device_add.
13951 Since: 2.7
13953 HotpluggableCPU (Object)
13955 Members:
13957 "type: string"
13959 CPU object type for usage with device_add command
13960 "props: CpuInstanceProperties"
13962 list of properties to be used for hotplugging CPU
13963 "vcpus-count: int"
13965 number of logical VCPU threads "HotpluggableCPU" provides
13966 "qom-path: string" (optional)
13968 link to existing CPU object if CPU is present or omitted if CPU is
13969 not present.
13970 Since: 2.7
13972 query-hotpluggable-cpus (Command)
13974 TODO: Better documentation; currently there is none.
13976 Returns: a list of HotpluggableCPU objects.
13978 Since: 2.7
13980 Example:
13982 For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
13984 -> { "execute": "query-hotpluggable-cpus" }
13986 <- {"return": [
13987 { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
13988 "vcpus-count": 1 },
13989 { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
13990 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
13991 ]}'
13992 For pc machine type started with -smp 1,maxcpus=2:
13994 -> { "execute": "query-hotpluggable-cpus" }
13996 <- {"return": [
13997 {
13998 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
13999 "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
14000 },
14001 {
14002 "qom-path": "/machine/unattached/device[0]",
14003 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
14004 "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
14005 }
14006 ]}
14007 For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
14009 (Since: 2.11):
14010 -> { "execute": "query-hotpluggable-cpus" }
14012 <- {"return": [
14013 {
14014 "type": "qemu-s390x-cpu", "vcpus-count": 1,
14015 "props": { "core-id": 1 }
14016 },
14017 {
14018 "qom-path": "/machine/unattached/device[0]",
14019 "type": "qemu-s390x-cpu", "vcpus-count": 1,
14020 "props": { "core-id": 0 }
14021 }
14022 ]}
14023 set-numa-node (Command) Runtime equivalent of '-numa' CLI option,
14025 available at preconfigure stage to configure numa mapping before
14026 initializing machine.
14027 Since 3.0
14029 Arguments: the members of "NumaOptions"
14031 CpuModelInfo (Object)
14033 Virtual CPU model.
14035 A CPU model consists of the name of a CPU definition, to which delta
14037 changes are applied (e.g. features added/removed). Most magic values
14038 that an architecture might require should be hidden behind the name.
14039 However, if required, architectures can expose relevant properties.
14040 Members:
14042 "name: string"
14044 the name of the CPU definition the model is based on
14045 "props: value" (optional)
14047 a dictionary of QOM properties to be applied
14048 Since: 2.8.0
14050 CpuModelExpansionType (Enum)
14052 An enumeration of CPU model expansion types.
14054 Values:
14056 "static"
14058 Expand to a static CPU model, a combination of a static base model
14059 name and property delta changes. As the static base model will
14060 never change, the expanded CPU model will be the same, independent
14061 of QEMU version, machine type, machine options, and accelerator
14062 options. Therefore, the resulting model can be used by tooling
14063 without having to specify a compatibility machine - e.g. when
14064 displaying the "host" model. The "static" CPU models are migration-
14065 safe.
14066 "full"
14068 Expand all properties. The produced model is not guaranteed to be
14069 migration-safe, but allows tooling to get an insight and work with
14070 model details.
14071 Note: When a non-migration-safe CPU model is expanded in static mode,
14073 some features enabled by the CPU model may be omitted, because they
14074 can't be implemented by a static CPU model definition (e.g. cache info
14075 passthrough and PMU passthrough in x86). If you need an accurate
14076 representation of the features enabled by a non-migration-safe CPU
14077 model, use "full". If you need a static representation that will keep
14078 ABI compatibility even when changing QEMU version or machine-type, use
14079 "static" (but keep in mind that some features may be omitted).
14080 Since: 2.8.0
14082 CpuModelCompareResult (Enum)
14084 An enumeration of CPU model comparison results. The result is usually
14086 calculated using e.g. CPU features or CPU generations.
14087 Values:
14089 "incompatible"
14091 If model A is incompatible to model B, model A is not guaranteed to
14092 run where model B runs and the other way around.
14093 "identical"
14095 If model A is identical to model B, model A is guaranteed to run
14096 where model B runs and the other way around.
14097 "superset"
14099 If model A is a superset of model B, model B is guaranteed to run
14100 where model A runs. There are no guarantees about the other way.
14101 "subset"
14103 If model A is a subset of model B, model A is guaranteed to run
14104 where model B runs. There are no guarantees about the other way.
14105 Since: 2.8.0
14107 CpuModelBaselineInfo (Object)
14109 The result of a CPU model baseline.
14111 Members:
14113 "model: CpuModelInfo"
14115 the baselined CpuModelInfo.
14116 Since: 2.8.0
14118 If: "defined(TARGET_S390X)"
14120 CpuModelCompareInfo (Object)
14122 The result of a CPU model comparison.
14124 Members:
14126 "result: CpuModelCompareResult"
14128 The result of the compare operation.
14129 "responsible-properties: array of string"
14131 List of properties that led to the comparison result not being
14132 identical.
14133 "responsible-properties" is a list of QOM property names that led to
14135 both CPUs not being detected as identical. For identical models, this
14136 list is empty. If a QOM property is read-only, that means there's no
14137 known way to make the CPU models identical. If the special property
14138 name "type" is included, the models are by definition not identical and
14139 cannot be made identical.
14140 Since: 2.8.0
14142 If: "defined(TARGET_S390X)"
14144 query-cpu-model-comparison (Command) Compares two CPU models,
14146 returning how they compare in a specific configuration. The results
14147 indicates how both models compare regarding runnability. This result
14148 can be used by tooling to make decisions if a certain CPU model will
14149 run in a certain configuration or if a compatible CPU model has to be
14150 created by baselining.
14151 Usually, a CPU model is compared against the maximum possible CPU model
14153 of a certain configuration (e.g. the "host" model for KVM). If that CPU
14154 model is identical or a subset, it will run in that configuration.
14155 The result returned by this command may be affected by:
14157 · QEMU version: CPU models may look different depending on the QEMU
14159 version. (Except for CPU models reported as "static" in query-cpu-
14160 definitions.)
14161 · machine-type: CPU model may look different depending on the
14163 machine-type. (Except for CPU models reported as "static" in
14164 query-cpu-definitions.)
14165 · machine options (including accelerator): in some architectures, CPU
14167 models may look different depending on machine and accelerator
14168 options. (Except for CPU models reported as "static" in query-cpu-
14169 definitions.)
14170 · "-cpu" arguments and global properties: arguments to the -cpu
14172 option and global properties may affect expansion of CPU models.
14173 Using query-cpu-model-expansion while using these is not advised.
14174 Some architectures may not support comparing CPU models. s390x supports
14176 comparing CPU models.
14177 Arguments:
14179 "modela: CpuModelInfo"
14181 Not documented
14182 "modelb: CpuModelInfo"
14184 Not documented
14185 Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU
14187 models is not supported, if a model cannot be used, if a model contains
14188 an unknown cpu definition name, unknown properties or properties with
14189 wrong types.
14190 Note: this command isn't specific to s390x, but is only implemented on
14192 this architecture currently.
14193 Since: 2.8.0
14195 If: "defined(TARGET_S390X)"
14197 query-cpu-model-baseline (Command) Baseline two CPU models, creating a
14199 compatible third model. The created model will always be a static,
14200 migration-safe CPU model (see "static" CPU model expansion for
14201 details).
14202 This interface can be used by tooling to create a compatible CPU model
14204 out two CPU models. The created CPU model will be identical to or a
14205 subset of both CPU models when comparing them. Therefore, the created
14206 CPU model is guaranteed to run where the given CPU models run.
14207 The result returned by this command may be affected by:
14209 · QEMU version: CPU models may look different depending on the QEMU
14211 version. (Except for CPU models reported as "static" in query-cpu-
14212 definitions.)
14213 · machine-type: CPU model may look different depending on the
14215 machine-type. (Except for CPU models reported as "static" in
14216 query-cpu-definitions.)
14217 · machine options (including accelerator): in some architectures, CPU
14219 models may look different depending on machine and accelerator
14220 options. (Except for CPU models reported as "static" in query-cpu-
14221 definitions.)
14222 · "-cpu" arguments and global properties: arguments to the -cpu
14224 option and global properties may affect expansion of CPU models.
14225 Using query-cpu-model-expansion while using these is not advised.
14226 Some architectures may not support baselining CPU models. s390x
14228 supports baselining CPU models.
14229 Arguments:
14231 "modela: CpuModelInfo"
14233 Not documented
14234 "modelb: CpuModelInfo"
14236 Not documented
14237 Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU
14239 models is not supported, if a model cannot be used, if a model contains
14240 an unknown cpu definition name, unknown properties or properties with
14241 wrong types.
14242 Note: this command isn't specific to s390x, but is only implemented on
14244 this architecture currently.
14245 Since: 2.8.0
14247 If: "defined(TARGET_S390X)"
14249 CpuModelExpansionInfo (Object)
14251 The result of a cpu model expansion.
14253 Members:
14255 "model: CpuModelInfo"
14257 the expanded CpuModelInfo.
14258 Since: 2.8.0
14260 If: "defined(TARGET_S390X) || defined(TARGET_I386)"
14262 query-cpu-model-expansion (Command) Expands a given CPU model (or a
14264 combination of CPU model + additional options) to different
14265 granularities, allowing tooling to get an understanding what a specific
14266 CPU model looks like in QEMU under a certain configuration.
14267 This interface can be used to query the "host" CPU model.
14269 The data returned by this command may be affected by:
14271 · QEMU version: CPU models may look different depending on the QEMU
14273 version. (Except for CPU models reported as "static" in query-cpu-
14274 definitions.)
14275 · machine-type: CPU model may look different depending on the
14277 machine-type. (Except for CPU models reported as "static" in
14278 query-cpu-definitions.)
14279 · machine options (including accelerator): in some architectures, CPU
14281 models may look different depending on machine and accelerator
14282 options. (Except for CPU models reported as "static" in query-cpu-
14283 definitions.)
14284 · "-cpu" arguments and global properties: arguments to the -cpu
14286 option and global properties may affect expansion of CPU models.
14287 Using query-cpu-model-expansion while using these is not advised.
14288 Some architectures may not support all expansion types. s390x supports
14290 "full" and "static".
14291 Arguments:
14293 "type: CpuModelExpansionType"
14295 Not documented
14296 "model: CpuModelInfo"
14298 Not documented
14299 Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU
14301 models is not supported, if the model cannot be expanded, if the model
14302 contains an unknown CPU definition name, unknown properties or
14303 properties with a wrong type. Also returns an error if an expansion
14304 type is not supported.
14305 Since: 2.8.0
14307 If: "defined(TARGET_S390X) || defined(TARGET_I386)"
14309 CpuDefinitionInfo (Object)
14311 Virtual CPU definition.
14313 Members:
14315 "name: string"
14317 the name of the CPU definition
14318 "migration-safe: boolean" (optional)
14320 whether a CPU definition can be safely used for migration in
14321 combination with a QEMU compatibility machine when migrating
14322 between different QEMU versions and between hosts with different
14323 sets of (hardware or software) capabilities. If not provided,
14324 information is not available and callers should not assume the CPU
14325 definition to be migration-safe. (since 2.8)
14326 "static: boolean"
14328 whether a CPU definition is static and will not change depending on
14329 QEMU version, machine type, machine options and accelerator
14330 options. A static model is always migration-safe. (since 2.8)
14331 "unavailable-features: array of string" (optional)
14333 List of properties that prevent the CPU model from running in the
14334 current host. (since 2.8)
14335 "typename: string"
14337 Type name that can be used as argument to "device-list-properties",
14338 to introspect properties configurable using -cpu or -global.
14339 (since 2.9)
14340 "alias-of: string" (optional)
14342 Name of CPU model this model is an alias for. The target of the
14343 CPU model alias may change depending on the machine type.
14344 Management software is supposed to translate CPU model aliases in
14345 the VM configuration, because aliases may stop being migration-safe
14346 in the future (since 4.1)
14347 "unavailable-features" is a list of QOM property names that represent
14349 CPU model attributes that prevent the CPU from running. If the QOM
14350 property is read-only, that means there's no known way to make the CPU
14351 model run in the current host. Implementations that choose not to
14352 provide specific information return the property name "type". If the
14353 property is read-write, it means that it MAY be possible to run the CPU
14354 model in the current host if that property is changed. Management
14355 software can use it as hints to suggest or choose an alternative for
14356 the user, or just to generate meaningful error messages explaining why
14357 the CPU model can't be used. If "unavailable-features" is an empty
14358 list, the CPU model is runnable using the current host and machine-
14359 type. If "unavailable-features" is not present, runnability
14360 information for the CPU is not available.
14361 Since: 1.2.0
14363 If: "defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386)
14365 || defined(TARGET_S390X) || defined(TARGET_MIPS)"
14366 query-cpu-definitions (Command) Return a list of supported virtual CPU
14368 definitions
14369 Returns: a list of CpuDefInfo
14371 Since: 1.2.0
14373 If: "defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386)
14375 || defined(TARGET_S390X) || defined(TARGET_MIPS)"
14376 Miscellanea
14378 qmp_capabilities (Command) Enable QMP capabilities.
14379 Arguments:
14381 Arguments:
14383 "enable: array of QMPCapability" (optional)
14385 An optional list of QMPCapability values to enable. The client
14386 must not enable any capability that is not mentioned in the QMP
14387 greeting message. If the field is not provided, it means no QMP
14388 capabilities will be enabled. (since 2.12)
14389 Example:
14391 -> { "execute": "qmp_capabilities",
14393 "arguments": { "enable": [ "oob" ] } }
14394 <- { "return": {} }
14395 Notes: This command is valid exactly when first connecting: it must be
14397 issued before any other command will be accepted, and will fail once
14398 the monitor is accepting other commands. (see qemu
14399 docs/interop/qmp-spec.txt)
14400 The QMP client needs to explicitly enable QMP capabilities, otherwise
14402 all the QMP capabilities will be turned off by default.
14403 Since: 0.13
14405 QMPCapability (Enum)
14407 Enumeration of capabilities to be advertised during initial client
14409 connection, used for agreeing on particular QMP extension behaviors.
14410 Values:
14412 "oob"
14414 QMP ability to support out-of-band requests. (Please refer to
14415 qmp-spec.txt for more information on OOB)
14416 Since: 2.12
14418 VersionTriple (Object)
14420 A three-part version number.
14422 Members:
14424 "major: int"
14426 The major version number.
14427 "minor: int"
14429 The minor version number.
14430 "micro: int"
14432 The micro version number.
14433 Since: 2.4
14435 VersionInfo (Object)
14437 A description of QEMU's version.
14439 Members:
14441 "qemu: VersionTriple"
14443 The version of QEMU. By current convention, a micro version of 50
14444 signifies a development branch. A micro version greater than or
14445 equal to 90 signifies a release candidate for the next minor
14446 version. A micro version of less than 50 signifies a stable
14447 release.
14448 "package: string"
14450 QEMU will always set this field to an empty string. Downstream
14451 versions of QEMU should set this to a non-empty string. The exact
14452 format depends on the downstream however it highly recommended that
14453 a unique name is used.
14454 Since: 0.14.0
14456 query-version (Command) Returns the current version of QEMU.
14458 Returns: A "VersionInfo" object describing the current version of QEMU.
14460 Since: 0.14.0
14462 Example:
14464 -> { "execute": "query-version" }
14466 <- {
14467 "return":{
14468 "qemu":{
14469 "major":0,
14470 "minor":11,
14471 "micro":5
14472 },
14473 "package":""
14474 }
14475 }
14476 CommandInfo (Object)
14478 Information about a QMP command
14480 Members:
14482 "name: string"
14484 The command name
14485 Since: 0.14.0
14487 query-commands (Command) Return a list of supported QMP commands by
14489 this server
14490 Returns: A list of "CommandInfo" for all supported commands
14492 Since: 0.14.0
14494 Example:
14496 -> { "execute": "query-commands" }
14498 <- {
14499 "return":[
14500 {
14501 "name":"query-balloon"
14502 },
14503 {
14504 "name":"system_powerdown"
14505 }
14506 ]
14507 }
14508 Note: This example has been shortened as the real response is too long.
14510 LostTickPolicy (Enum)
14512 Policy for handling lost ticks in timer devices.
14514 Values:
14516 "discard"
14518 throw away the missed tick(s) and continue with future injection
14519 normally. Guest time may be delayed, unless the OS has explicit
14520 handling of lost ticks
14521 "delay"
14523 continue to deliver ticks at the normal rate. Guest time will be
14524 delayed due to the late tick
14525 "slew"
14527 deliver ticks at a higher rate to catch up with the missed tick.
14528 The guest time should not be delayed once catchup is complete.
14529 Since: 2.0
14531 add_client (Command) Allow client connections for VNC, Spice and
14533 socket based character devices to be passed in to QEMU via SCM_RIGHTS.
14534 Arguments:
14536 "protocol: string"
14538 protocol name. Valid names are "vnc", "spice" or the name of a
14539 character device (eg. from -chardev id=XXXX)
14540 "fdname: string"
14542 file descriptor name previously passed via 'getfd' command
14543 "skipauth: boolean" (optional)
14545 whether to skip authentication. Only applies to "vnc" and "spice"
14546 protocols
14547 "tls: boolean" (optional)
14549 whether to perform TLS. Only applies to the "spice" protocol
14550 Returns: nothing on success.
14552 Since: 0.14.0
14554 Example:
14556 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
14558 "fdname": "myclient" } }
14559 <- { "return": {} }
14560 NameInfo (Object)
14562 Guest name information.
14564 Members:
14566 "name: string" (optional)
14568 The name of the guest
14569 Since: 0.14.0
14571 query-name (Command) Return the name information of a guest.
14573 Returns: "NameInfo" of the guest
14575 Since: 0.14.0
14577 Example:
14579 -> { "execute": "query-name" }
14581 <- { "return": { "name": "qemu-name" } }
14582 KvmInfo (Object)
14584 Information about support for KVM acceleration
14586 Members:
14588 "enabled: boolean"
14590 true if KVM acceleration is active
14591 "present: boolean"
14593 true if KVM acceleration is built into this executable
14594 Since: 0.14.0
14596 query-kvm (Command) Returns information about KVM acceleration
14598 Returns: "KvmInfo"
14600 Since: 0.14.0
14602 Example:
14604 -> { "execute": "query-kvm" }
14606 <- { "return": { "enabled": true, "present": true } }
14607 UuidInfo (Object)
14609 Guest UUID information (Universally Unique Identifier).
14611 Members:
14613 "UUID: string"
14615 the UUID of the guest
14616 Since: 0.14.0
14618 Notes: If no UUID was specified for the guest, a null UUID is returned.
14620 query-uuid (Command) Query the guest UUID information.
14622 Returns: The "UuidInfo" for the guest
14624 Since: 0.14.0
14626 Example:
14628 -> { "execute": "query-uuid" }
14630 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
14631 EventInfo (Object)
14633 Information about a QMP event
14635 Members:
14637 "name: string"
14639 The event name
14640 Since: 1.2.0
14642 query-events (Command) Return information on QMP events.
14644 Returns: A list of "EventInfo".
14646 Since: 1.2.0
14648 Note: This command is deprecated, because its output doesn't reflect
14650 compile-time configuration. Use query-qmp-schema instead.
14651 Example:
14653 -> { "execute": "query-events" }
14655 <- {
14656 "return": [
14657 {
14658 "name":"SHUTDOWN"
14659 },
14660 {
14661 "name":"RESET"
14662 }
14663 ]
14664 }
14665 Note: This example has been shortened as the real response is too long.
14667 IOThreadInfo (Object)
14669 Information about an iothread
14671 Members:
14673 "id: string"
14675 the identifier of the iothread
14676 "thread-id: int"
14678 ID of the underlying host thread
14679 "poll-max-ns: int"
14681 maximum polling time in ns, 0 means polling is disabled (since 2.9)
14682 "poll-grow: int"
14684 how many ns will be added to polling time, 0 means that it's not
14685 configured (since 2.9)
14686 "poll-shrink: int"
14688 how many ns will be removed from polling time, 0 means that it's
14689 not configured (since 2.9)
14690 Since: 2.0
14692 query-iothreads (Command) Returns a list of information about each
14694 iothread.
14695 Note: this list excludes the QEMU main loop thread, which is not
14697 declared using the -object iothread command-line option. It is always
14698 the main thread of the process.
14699 Returns: a list of "IOThreadInfo" for each iothread
14701 Since: 2.0
14703 Example:
14705 -> { "execute": "query-iothreads" }
14707 <- { "return": [
14708 {
14709 "id":"iothread0",
14710 "thread-id":3134
14711 },
14712 {
14713 "id":"iothread1",
14714 "thread-id":3135
14715 }
14716 ]
14717 }
14718 BalloonInfo (Object)
14720 Information about the guest balloon device.
14722 Members:
14724 "actual: int"
14726 the number of bytes the balloon currently contains
14727 Since: 0.14.0
14729 query-balloon (Command) Return information about the balloon device.
14731 Returns: "BalloonInfo" on success
14733 If the balloon driver is enabled but not functional because the KVM
14735 kernel module cannot support it, KvmMissingCap
14736 If no balloon device is present, DeviceNotActive
14738 Since: 0.14.0
14740 Example:
14742 -> { "execute": "query-balloon" }
14744 <- { "return": {
14745 "actual": 1073741824,
14746 }
14747 }
14748 BALLOON_CHANGE (Event) Emitted when the guest changes the actual
14750 BALLOON level. This value is equivalent to the "actual" field return by
14751 the 'query-balloon' command
14752 Arguments:
14754 "actual: int"
14756 actual level of the guest memory balloon in bytes
14757 Note: this event is rate-limited.
14759 Since: 1.2
14761 Example:
14763 <- { "event": "BALLOON_CHANGE",
14765 "data": { "actual": 944766976 },
14766 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
14767 PciMemoryRange (Object)
14769 A PCI device memory region
14771 Members:
14773 "base: int"
14775 the starting address (guest physical)
14776 "limit: int"
14778 the ending address (guest physical)
14779 Since: 0.14.0
14781 PciMemoryRegion (Object)
14783 Information about a PCI device I/O region.
14785 Members:
14787 "bar: int"
14789 the index of the Base Address Register for this region
14790 "type: string"
14792 'io' if the region is a PIO region 'memory' if the region is a MMIO
14793 region
14794 "size: int"
14796 memory size
14797 "prefetch: boolean" (optional)
14799 if "type" is 'memory', true if the memory is prefetchable
14800 "mem_type_64: boolean" (optional)
14802 if "type" is 'memory', true if the BAR is 64-bit
14803 "address: int"
14805 Not documented
14806 Since: 0.14.0
14808 PciBusInfo (Object)
14810 Information about a bus of a PCI Bridge device
14812 Members:
14814 "number: int"
14816 primary bus interface number. This should be the number of the bus
14817 the device resides on.
14818 "secondary: int"
14820 secondary bus interface number. This is the number of the main bus
14821 for the bridge
14822 "subordinate: int"
14824 This is the highest number bus that resides below the bridge.
14825 "io_range: PciMemoryRange"
14827 The PIO range for all devices on this bridge
14828 "memory_range: PciMemoryRange"
14830 The MMIO range for all devices on this bridge
14831 "prefetchable_range: PciMemoryRange"
14833 The range of prefetchable MMIO for all devices on this bridge
14834 Since: 2.4
14836 PciBridgeInfo (Object)
14838 Information about a PCI Bridge device
14840 Members:
14842 "bus: PciBusInfo"
14844 information about the bus the device resides on
14845 "devices: array of PciDeviceInfo" (optional)
14847 a list of "PciDeviceInfo" for each device on this bridge
14848 Since: 0.14.0
14850 PciDeviceClass (Object)
14852 Information about the Class of a PCI device
14854 Members:
14856 "desc: string" (optional)
14858 a string description of the device's class
14859 "class: int"
14861 the class code of the device
14862 Since: 2.4
14864 PciDeviceId (Object)
14866 Information about the Id of a PCI device
14868 Members:
14870 "device: int"
14872 the PCI device id
14873 "vendor: int"
14875 the PCI vendor id
14876 "subsystem: int" (optional)
14878 the PCI subsystem id (since 3.1)
14879 "subsystem-vendor: int" (optional)
14881 the PCI subsystem vendor id (since 3.1)
14882 Since: 2.4
14884 PciDeviceInfo (Object)
14886 Information about a PCI device
14888 Members:
14890 "bus: int"
14892 the bus number of the device
14893 "slot: int"
14895 the slot the device is located in
14896 "function: int"
14898 the function of the slot used by the device
14899 "class_info: PciDeviceClass"
14901 the class of the device
14902 "id: PciDeviceId"
14904 the PCI device id
14905 "irq: int" (optional)
14907 if an IRQ is assigned to the device, the IRQ number
14908 "qdev_id: string"
14910 the device name of the PCI device
14911 "pci_bridge: PciBridgeInfo" (optional)
14913 if the device is a PCI bridge, the bridge information
14914 "regions: array of PciMemoryRegion"
14916 a list of the PCI I/O regions associated with the device
14917 Notes: the contents of "class_info".desc are not stable and should only
14919 be treated as informational.
14920 Since: 0.14.0
14922 PciInfo (Object)
14924 Information about a PCI bus
14926 Members:
14928 "bus: int"
14930 the bus index
14931 "devices: array of PciDeviceInfo"
14933 a list of devices on this bus
14934 Since: 0.14.0
14936 query-pci (Command) Return information about the PCI bus topology of
14938 the guest.
14939 Returns: a list of "PciInfo" for each PCI bus. Each bus is represented
14941 by a json-object, which has a key with a json-array of all PCI devices
14942 attached to it. Each device is represented by a json-object.
14943 Since: 0.14.0
14945 Example:
14947 -> { "execute": "query-pci" }
14949 <- { "return": [
14950 {
14951 "bus": 0,
14952 "devices": [
14953 {
14954 "bus": 0,
14955 "qdev_id": "",
14956 "slot": 0,
14957 "class_info": {
14958 "class": 1536,
14959 "desc": "Host bridge"
14960 },
14961 "id": {
14962 "device": 32902,
14963 "vendor": 4663
14964 },
14965 "function": 0,
14966 "regions": [
14967 ]
14968 },
14969 {
14970 "bus": 0,
14971 "qdev_id": "",
14972 "slot": 1,
14973 "class_info": {
14974 "class": 1537,
14975 "desc": "ISA bridge"
14976 },
14977 "id": {
14978 "device": 32902,
14979 "vendor": 28672
14980 },
14981 "function": 0,
14982 "regions": [
14983 ]
14984 },
14985 {
14986 "bus": 0,
14987 "qdev_id": "",
14988 "slot": 1,
14989 "class_info": {
14990 "class": 257,
14991 "desc": "IDE controller"
14992 },
14993 "id": {
14994 "device": 32902,
14995 "vendor": 28688
14996 },
14997 "function": 1,
14998 "regions": [
14999 {
15000 "bar": 4,
15001 "size": 16,
15002 "address": 49152,
15003 "type": "io"
15004 }
15005 ]
15006 },
15007 {
15008 "bus": 0,
15009 "qdev_id": "",
15010 "slot": 2,
15011 "class_info": {
15012 "class": 768,
15013 "desc": "VGA controller"
15014 },
15015 "id": {
15016 "device": 4115,
15017 "vendor": 184
15018 },
15019 "function": 0,
15020 "regions": [
15021 {
15022 "prefetch": true,
15023 "mem_type_64": false,
15024 "bar": 0,
15025 "size": 33554432,
15026 "address": 4026531840,
15027 "type": "memory"
15028 },
15029 {
15030 "prefetch": false,
15031 "mem_type_64": false,
15032 "bar": 1,
15033 "size": 4096,
15034 "address": 4060086272,
15035 "type": "memory"
15036 },
15037 {
15038 "prefetch": false,
15039 "mem_type_64": false,
15040 "bar": 6,
15041 "size": 65536,
15042 "address": -1,
15043 "type": "memory"
15044 }
15045 ]
15046 },
15047 {
15048 "bus": 0,
15049 "qdev_id": "",
15050 "irq": 11,
15051 "slot": 4,
15052 "class_info": {
15053 "class": 1280,
15054 "desc": "RAM controller"
15055 },
15056 "id": {
15057 "device": 6900,
15058 "vendor": 4098
15059 },
15060 "function": 0,
15061 "regions": [
15062 {
15063 "bar": 0,
15064 "size": 32,
15065 "address": 49280,
15066 "type": "io"
15067 }
15068 ]
15069 }
15070 ]
15071 }
15072 ]
15073 }
15074 Note: This example has been shortened as the real response is too long.
15076 quit (Command) This command will cause the QEMU process to exit
15078 gracefully. While every attempt is made to send the QMP response
15079 before terminating, this is not guaranteed. When using this interface,
15080 a premature EOF would not be unexpected.
15081 Since: 0.14.0
15083 Example:
15085 -> { "execute": "quit" }
15087 <- { "return": {} }
15088 stop (Command) Stop all guest VCPU execution.
15090 Since: 0.14.0
15092 Notes: This function will succeed even if the guest is already in the
15094 stopped state. In "inmigrate" state, it will ensure that the guest
15095 remains paused once migration finishes, as if the -S option was passed
15096 on the command line.
15097 Example:
15099 -> { "execute": "stop" }
15101 <- { "return": {} }
15102 system_reset (Command) Performs a hard reset of a guest.
15104 Since: 0.14.0
15106 Example:
15108 -> { "execute": "system_reset" }
15110 <- { "return": {} }
15111 system_powerdown (Command) Requests that a guest perform a powerdown
15113 operation.
15114 Since: 0.14.0
15116 Notes: A guest may or may not respond to this command. This command
15118 returning does not indicate that a guest has accepted the request or
15119 that it has shut down. Many guests will respond to this command by
15120 prompting the user in some way.
15121 Example:
15123 -> { "execute": "system_powerdown" }
15125 <- { "return": {} }
15126 memsave (Command) Save a portion of guest memory to a file.
15128 Arguments:
15130 "val: int"
15132 the virtual address of the guest to start from
15133 "size: int"
15135 the size of memory region to save
15136 "filename: string"
15138 the file to save the memory to as binary data
15139 "cpu-index: int" (optional)
15141 the index of the virtual CPU to use for translating the virtual
15142 address (defaults to CPU 0)
15143 Returns: Nothing on success
15145 Since: 0.14.0
15147 Notes: Errors were not reliably returned until 1.1
15149 Example:
15151 -> { "execute": "memsave",
15153 "arguments": { "val": 10,
15154 "size": 100,
15155 "filename": "/tmp/virtual-mem-dump" } }
15156 <- { "return": {} }
15157 pmemsave (Command) Save a portion of guest physical memory to a file.
15159 Arguments:
15161 "val: int"
15163 the physical address of the guest to start from
15164 "size: int"
15166 the size of memory region to save
15167 "filename: string"
15169 the file to save the memory to as binary data
15170 Returns: Nothing on success
15172 Since: 0.14.0
15174 Notes: Errors were not reliably returned until 1.1
15176 Example:
15178 -> { "execute": "pmemsave",
15180 "arguments": { "val": 10,
15181 "size": 100,
15182 "filename": "/tmp/physical-mem-dump" } }
15183 <- { "return": {} }
15184 cont (Command) Resume guest VCPU execution.
15186 Since: 0.14.0
15188 Returns: If successful, nothing
15190 Notes: This command will succeed if the guest is currently running. It
15192 will also succeed if the guest is in the "inmigrate" state; in this
15193 case, the effect of the command is to make sure the guest starts once
15194 migration finishes, removing the effect of the -S command line option
15195 if it was passed.
15196 Example:
15198 -> { "execute": "cont" }
15200 <- { "return": {} }
15201 x-exit-preconfig (Command) Exit from "preconfig" state
15203 This command makes QEMU exit the preconfig state and proceed with VM
15205 initialization using configuration data provided on the command line
15206 and via the QMP monitor during the preconfig state. The command is only
15207 available during the preconfig state (i.e. when the --preconfig command
15208 line option was in use).
15209 Since 3.0
15211 Returns: nothing
15213 Example:
15215 -> { "execute": "x-exit-preconfig" }
15217 <- { "return": {} }
15218 system_wakeup (Command) Wake up guest from suspend. If the guest has
15220 wake-up from suspend support enabled (wakeup-suspend-support flag from
15221 query-current-machine), wake-up guest from suspend if the guest is in
15222 SUSPENDED state. Return an error otherwise.
15223 Since: 1.1
15225 Returns: nothing.
15227 Note: prior to 4.0, this command does nothing in case the guest isn't
15229 suspended.
15230 Example:
15232 -> { "execute": "system_wakeup" }
15234 <- { "return": {} }
15235 inject-nmi (Command) Injects a Non-Maskable Interrupt into the default
15237 CPU (x86/s390) or all CPUs (ppc64). The command fails when the guest
15238 doesn't support injecting.
15239 Returns: If successful, nothing
15241 Since: 0.14.0
15243 Note: prior to 2.1, this command was only supported for x86 and s390
15245 VMs
15246 Example:
15248 -> { "execute": "inject-nmi" }
15250 <- { "return": {} }
15251 balloon (Command) Request the balloon driver to change its balloon
15253 size.
15254 Arguments:
15256 "value: int"
15258 the target size of the balloon in bytes
15259 Returns: Nothing on success If the balloon driver is enabled but not
15261 functional because the KVM kernel module cannot support it,
15262 KvmMissingCap If no balloon device is present, DeviceNotActive
15263 Notes: This command just issues a request to the guest. When it
15265 returns, the balloon size may not have changed. A guest can change the
15266 balloon size independent of this command.
15267 Since: 0.14.0
15269 Example:
15271 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
15273 <- { "return": {} }
15274 human-monitor-command (Command) Execute a command on the human monitor
15276 and return the output.
15277 Arguments:
15279 "command-line: string"
15281 the command to execute in the human monitor
15282 "cpu-index: int" (optional)
15284 The CPU to use for commands that require an implicit CPU
15285 Returns: the output of the command as a string
15287 Since: 0.14.0
15289 Notes: This command only exists as a stop-gap. Its use is highly
15291 discouraged. The semantics of this command are not guaranteed: this
15292 means that command names, arguments and responses can change or be
15293 removed at ANY time. Applications that rely on long term stability
15294 guarantees should NOT use this command.
15295 Known limitations:
15297 · This command is stateless, this means that commands that depend on
15299 state information (such as getfd) might not work
15300 · Commands that prompt the user for data don't currently work
15302 Example:
15304 -> { "execute": "human-monitor-command",
15306 "arguments": { "command-line": "info kvm" } }
15307 <- { "return": "kvm support: enabled\r\n" }
15308 change (Command) This command is multiple commands multiplexed
15310 together.
15311 Arguments:
15313 "device: string"
15315 This is normally the name of a block device but it may also be
15316 'vnc'. when it's 'vnc', then sub command depends on "target"
15317 "target: string"
15319 If "device" is a block device, then this is the new filename. If
15320 "device" is 'vnc', then if the value 'password' selects the vnc
15321 change password command. Otherwise, this specifies a new server
15322 URI address to listen to for VNC connections.
15323 "arg: string" (optional)
15325 If "device" is a block device, then this is an optional format to
15326 open the device with. If "device" is 'vnc' and "target" is
15327 'password', this is the new VNC password to set. See change-vnc-
15328 password for additional notes.
15329 Returns: Nothing on success. If "device" is not a valid block device,
15331 DeviceNotFound
15332 Notes: This interface is deprecated, and it is strongly recommended
15334 that you avoid using it. For changing block devices, use blockdev-
15335 change-medium; for changing VNC parameters, use change-vnc-password.
15336 Since: 0.14.0
15338 Example:
15340 1. Change a removable medium
15342 -> { "execute": "change",
15344 "arguments": { "device": "ide1-cd0",
15345 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
15346 <- { "return": {} }
15347 2. Change VNC password
15349 -> { "execute": "change",
15351 "arguments": { "device": "vnc", "target": "password",
15352 "arg": "foobar1" } }
15353 <- { "return": {} }
15354 xen-set-global-dirty-log (Command) Enable or disable the global dirty
15356 log mode.
15357 Arguments:
15359 "enable: boolean"
15361 true to enable, false to disable.
15362 Returns: nothing
15364 Since: 1.3
15366 Example:
15368 -> { "execute": "xen-set-global-dirty-log",
15370 "arguments": { "enable": true } }
15371 <- { "return": {} }
15372 getfd (Command) Receive a file descriptor via SCM rights and assign it
15374 a name
15375 Arguments:
15377 "fdname: string"
15379 file descriptor name
15380 Returns: Nothing on success
15382 Since: 0.14.0
15384 Notes: If "fdname" already exists, the file descriptor assigned to it
15386 will be closed and replaced by the received file descriptor.
15387 The 'closefd' command can be used to explicitly close the file
15389 descriptor when it is no longer needed.
15390 Example:
15392 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
15394 <- { "return": {} }
15395 closefd (Command) Close a file descriptor previously passed via SCM
15397 rights
15398 Arguments:
15400 "fdname: string"
15402 file descriptor name
15403 Returns: Nothing on success
15405 Since: 0.14.0
15407 Example:
15409 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
15411 <- { "return": {} }
15412 MemoryInfo (Object)
15414 Actual memory information in bytes.
15416 Members:
15418 "base-memory: int"
15420 size of "base" memory specified with command line option -m.
15421 "plugged-memory: int" (optional)
15423 size of memory that can be hot-unplugged. This field is omitted if
15424 target doesn't support memory hotplug (i.e. CONFIG_MEM_DEVICE not
15425 defined at build time).
15426 Since: 2.11.0
15428 query-memory-size-summary (Command) Return the amount of initially
15430 allocated and present hotpluggable (if enabled) memory in bytes.
15431 Example:
15433 -> { "execute": "query-memory-size-summary" }
15435 <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
15436 Since: 2.11.0
15438 AddfdInfo (Object)
15440 Information about a file descriptor that was added to an fd set.
15442 Members:
15444 "fdset-id: int"
15446 The ID of the fd set that "fd" was added to.
15447 "fd: int"
15449 The file descriptor that was received via SCM rights and added to
15450 the fd set.
15451 Since: 1.2.0
15453 add-fd (Command) Add a file descriptor, that was passed via SCM
15455 rights, to an fd set.
15456 Arguments:
15458 "fdset-id: int" (optional)
15460 The ID of the fd set to add the file descriptor to.
15461 "opaque: string" (optional)
15463 A free-form string that can be used to describe the fd.
15464 Returns: "AddfdInfo" on success
15466 If file descriptor was not received, FdNotSupplied
15468 If "fdset-id" is a negative value, InvalidParameterValue
15470 Notes: The list of fd sets is shared by all monitor connections.
15472 If "fdset-id" is not specified, a new fd set will be created.
15474 Since: 1.2.0
15476 Example:
15478 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
15480 <- { "return": { "fdset-id": 1, "fd": 3 } }
15481 remove-fd (Command) Remove a file descriptor from an fd set.
15483 Arguments:
15485 "fdset-id: int"
15487 The ID of the fd set that the file descriptor belongs to.
15488 "fd: int" (optional)
15490 The file descriptor that is to be removed.
15491 Returns: Nothing on success If "fdset-id" or "fd" is not found,
15493 FdNotFound
15494 Since: 1.2.0
15496 Notes: The list of fd sets is shared by all monitor connections.
15498 If "fd" is not specified, all file descriptors in "fdset-id" will be
15500 removed.
15501 Example:
15503 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
15505 <- { "return": {} }
15506 FdsetFdInfo (Object)
15508 Information about a file descriptor that belongs to an fd set.
15510 Members:
15512 "fd: int"
15514 The file descriptor value.
15515 "opaque: string" (optional)
15517 A free-form string that can be used to describe the fd.
15518 Since: 1.2.0
15520 FdsetInfo (Object)
15522 Information about an fd set.
15524 Members:
15526 "fdset-id: int"
15528 The ID of the fd set.
15529 "fds: array of FdsetFdInfo"
15531 A list of file descriptors that belong to this fd set.
15532 Since: 1.2.0
15534 query-fdsets (Command) Return information describing all fd sets.
15536 Returns: A list of "FdsetInfo"
15538 Since: 1.2.0
15540 Note: The list of fd sets is shared by all monitor connections.
15542 Example:
15544 -> { "execute": "query-fdsets" }
15546 <- { "return": [
15547 {
15548 "fds": [
15549 {
15550 "fd": 30,
15551 "opaque": "rdonly:/path/to/file"
15552 },
15553 {
15554 "fd": 24,
15555 "opaque": "rdwr:/path/to/file"
15556 }
15557 ],
15558 "fdset-id": 1
15559 },
15560 {
15561 "fds": [
15562 {
15563 "fd": 28
15564 },
15565 {
15566 "fd": 29
15567 }
15568 ],
15569 "fdset-id": 0
15570 }
15571 ]
15572 }
15573 TargetInfo (Object)
15575 Information describing the QEMU target.
15577 Members:
15579 "arch: SysEmuTarget"
15581 the target architecture
15582 Since: 1.2.0
15584 query-target (Command) Return information about the target for this
15586 QEMU
15587 Returns: TargetInfo
15589 Since: 1.2.0
15591 AcpiTableOptions (Object)
15593 Specify an ACPI table on the command line to load.
15595 At most one of "file" and "data" can be specified. The list of files
15597 specified by any one of them is loaded and concatenated in order. If
15598 both are omitted, "data" is implied.
15599 Other fields / optargs can be used to override fields of the generic
15601 ACPI table header; refer to the ACPI specification 5.0, section 5.2.6
15602 System Description Table Header. If a header field is not overridden,
15603 then the corresponding value from the concatenated blob is used (in
15604 case of "file"), or it is filled in with a hard-coded value (in case of
15605 "data").
15606 String fields are copied into the matching ACPI member from lowest
15608 address upwards, and silently truncated / NUL-padded to length.
15609 Members:
15611 "sig: string" (optional)
15613 table signature / identifier (4 bytes)
15614 "rev: int" (optional)
15616 table revision number (dependent on signature, 1 byte)
15617 "oem_id: string" (optional)
15619 OEM identifier (6 bytes)
15620 "oem_table_id: string" (optional)
15622 OEM table identifier (8 bytes)
15623 "oem_rev: int" (optional)
15625 OEM-supplied revision number (4 bytes)
15626 "asl_compiler_id: string" (optional)
15628 identifier of the utility that created the table (4 bytes)
15629 "asl_compiler_rev: int" (optional)
15631 revision number of the utility that created the table (4 bytes)
15632 "file: string" (optional)
15634 colon (:) separated list of pathnames to load and concatenate as
15635 table data. The resultant binary blob is expected to have an ACPI
15636 table header. At least one file is required. This field excludes
15637 "data".
15638 "data: string" (optional)
15640 colon (:) separated list of pathnames to load and concatenate as
15641 table data. The resultant binary blob must not have an ACPI table
15642 header. At least one file is required. This field excludes "file".
15643 Since: 1.5
15645 CommandLineParameterType (Enum)
15647 Possible types for an option parameter.
15649 Values:
15651 "string"
15653 accepts a character string
15654 "boolean"
15656 accepts "on" or "off"
15657 "number"
15659 accepts a number
15660 "size"
15662 accepts a number followed by an optional suffix (K)ilo, (M)ega,
15663 (G)iga, (T)era
15664 Since: 1.5
15666 CommandLineParameterInfo (Object)
15668 Details about a single parameter of a command line option.
15670 Members:
15672 "name: string"
15674 parameter name
15675 "type: CommandLineParameterType"
15677 parameter "CommandLineParameterType"
15678 "help: string" (optional)
15680 human readable text string, not suitable for parsing.
15681 "default: string" (optional)
15683 default value string (since 2.1)
15684 Since: 1.5
15686 CommandLineOptionInfo (Object)
15688 Details about a command line option, including its list of parameter
15690 details
15691 Members:
15693 "option: string"
15695 option name
15696 "parameters: array of CommandLineParameterInfo"
15698 an array of "CommandLineParameterInfo"
15699 Since: 1.5
15701 query-command-line-options (Command) Query command line option schema.
15703 Arguments:
15705 "option: string" (optional)
15707 option name
15708 Returns: list of "CommandLineOptionInfo" for all options (or for the
15710 given "option"). Returns an error if the given "option" doesn't exist.
15711 Since: 1.5
15713 Example:
15715 -> { "execute": "query-command-line-options",
15717 "arguments": { "option": "option-rom" } }
15718 <- { "return": [
15719 {
15720 "parameters": [
15721 {
15722 "name": "romfile",
15723 "type": "string"
15724 },
15725 {
15726 "name": "bootindex",
15727 "type": "number"
15728 }
15729 ],
15730 "option": "option-rom"
15731 }
15732 ]
15733 }
15734 PCDIMMDeviceInfo (Object)
15736 PCDIMMDevice state information
15738 Members:
15740 "id: string" (optional)
15742 device's ID
15743 "addr: int"
15745 physical address, where device is mapped
15746 "size: int"
15748 size of memory that the device provides
15749 "slot: int"
15751 slot number at which device is plugged in
15752 "node: int"
15754 NUMA node number where device is plugged in
15755 "memdev: string"
15757 memory backend linked with device
15758 "hotplugged: boolean"
15760 true if device was hotplugged
15761 "hotpluggable: boolean"
15763 true if device if could be added/removed while machine is running
15764 Since: 2.1
15766 VirtioPMEMDeviceInfo (Object)
15768 VirtioPMEM state information
15770 Members:
15772 "id: string" (optional)
15774 device's ID
15775 "memaddr: int"
15777 physical address in memory, where device is mapped
15778 "size: int"
15780 size of memory that the device provides
15781 "memdev: string"
15783 memory backend linked with device
15784 Since: 4.1
15786 MemoryDeviceInfo (Object)
15788 Union containing information about a memory device
15790 nvdimm is included since 2.12. virtio-pmem is included since 4.1.
15792 Members:
15794 "type"
15796 One of "dimm", "nvdimm", "virtio-pmem"
15797 "data: PCDIMMDeviceInfo" when "type" is "dimm"
15799 "data: PCDIMMDeviceInfo" when "type" is "nvdimm"
15800 "data: VirtioPMEMDeviceInfo" when "type" is "virtio-pmem"
15801 Since: 2.1
15803 query-memory-devices (Command) Lists available memory devices and
15805 their state
15806 Since: 2.1
15808 Example:
15810 -> { "execute": "query-memory-devices" }
15812 <- { "return": [ { "data":
15813 { "addr": 5368709120,
15814 "hotpluggable": true,
15815 "hotplugged": true,
15816 "id": "d1",
15817 "memdev": "/objects/memX",
15818 "node": 0,
15819 "size": 1073741824,
15820 "slot": 0},
15821 "type": "dimm"
15822 } ] }
15823 MEM_UNPLUG_ERROR (Event) Emitted when memory hot unplug error occurs.
15825 Arguments:
15827 "device: string"
15829 device name
15830 "msg: string"
15832 Informative message
15833 Since: 2.4
15835 Example:
15837 <- { "event": "MEM_UNPLUG_ERROR"
15839 "data": { "device": "dimm1",
15840 "msg": "acpi: device unplug for unsupported device"
15841 },
15842 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
15843 ACPISlotType (Enum)
15845 Values:
15847 "DIMM"
15849 memory slot
15850 "CPU"
15852 logical CPU slot (since 2.7)
15853 ACPIOSTInfo (Object)
15855 OSPM Status Indication for a device For description of possible values
15857 of "source" and "status" fields see "_OST (OSPM Status Indication)"
15858 chapter of ACPI5.0 spec.
15859 Members:
15861 "device: string" (optional)
15863 device ID associated with slot
15864 "slot: string"
15866 slot ID, unique per slot of a given "slot-type"
15867 "slot-type: ACPISlotType"
15869 type of the slot
15870 "source: int"
15872 an integer containing the source event
15873 "status: int"
15875 an integer containing the status code
15876 Since: 2.1
15878 query-acpi-ospm-status (Command) Return a list of ACPIOSTInfo for
15880 devices that support status reporting via ACPI _OST method.
15881 Since: 2.1
15883 Example:
15885 -> { "execute": "query-acpi-ospm-status" }
15887 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
15888 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
15889 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
15890 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
15891 ]}
15892 ACPI_DEVICE_OST (Event) Emitted when guest executes ACPI _OST method.
15894 Arguments:
15896 "info: ACPIOSTInfo"
15898 OSPM Status Indication
15899 Since: 2.1
15901 Example:
15903 <- { "event": "ACPI_DEVICE_OST",
15905 "data": { "device": "d1", "slot": "0",
15906 "slot-type": "DIMM", "source": 1, "status": 0 } }
15907 ReplayMode (Enum)
15909 Mode of the replay subsystem.
15911 Values:
15913 "none"
15915 normal execution mode. Replay or record are not enabled.
15916 "record"
15918 record mode. All non-deterministic data is written into the replay
15919 log.
15920 "play"
15922 replay mode. Non-deterministic data required for system execution
15923 is read from the log.
15924 Since: 2.5
15926 xen-load-devices-state (Command) Load the state of all devices from
15928 file. The RAM and the block devices of the VM are not loaded by this
15929 command.
15930 Arguments:
15932 "filename: string"
15934 the file to load the state of the devices from as binary data. See
15935 xen-save-devices-state.txt for a description of the binary format.
15936 Since: 2.7
15938 Example:
15940 -> { "execute": "xen-load-devices-state",
15942 "arguments": { "filename": "/tmp/resume" } }
15943 <- { "return": {} }
15944 GuidInfo (Object)
15946 GUID information.
15948 Members:
15950 "guid: string"
15952 the globally unique identifier
15953 Since: 2.9
15955 query-vm-generation-id (Command) Show Virtual Machine Generation ID
15957 Since: 2.9
15959 RTC_CHANGE (Event) Emitted when the guest changes the RTC time.
15961 Arguments:
15963 "offset: int"
15965 offset between base RTC clock (as specified by -rtc base), and new
15966 RTC clock value
15967 Note: This event is rate-limited.
15969 Since: 0.13.0
15971 Example:
15973 <- { "event": "RTC_CHANGE",
15975 "data": { "offset": 78 },
15976 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
15977 If: "defined(TARGET_ALPHA) || defined(TARGET_ARM) ||
15979 defined(TARGET_HPPA) || defined(TARGET_I386) || defined(TARGET_MIPS) ||
15980 defined(TARGET_MIPS64) || defined(TARGET_MOXIE) || defined(TARGET_PPC)
15981 || defined(TARGET_PPC64) || defined(TARGET_S390X) ||
15982 defined(TARGET_SH4) || defined(TARGET_SPARC)"
15983 rtc-reset-reinjection (Command) This command will reset the RTC
15985 interrupt reinjection backlog. Can be used if another mechanism to
15986 synchronize guest time is in effect, for example QEMU guest agent's
15987 guest-set-time command.
15988 Since: 2.1
15990 Example:
15992 -> { "execute": "rtc-reset-reinjection" }
15994 <- { "return": {} }
15995 If: "defined(TARGET_I386)"
15997 SevState (Enum)
15999 An enumeration of SEV state information used during "query-sev".
16001 Values:
16003 "uninit"
16005 The guest is uninitialized.
16006 "launch-update"
16008 The guest is currently being launched; plaintext data and register
16009 state is being imported.
16010 "launch-secret"
16012 The guest is currently being launched; ciphertext data is being
16013 imported.
16014 "running"
16016 The guest is fully launched or migrated in.
16017 "send-update"
16019 The guest is currently being migrated out to another machine.
16020 "receive-update"
16022 The guest is currently being migrated from another machine.
16023 Since: 2.12
16025 If: "defined(TARGET_I386)"
16027 SevInfo (Object)
16029 Information about Secure Encrypted Virtualization (SEV) support
16031 Members:
16033 "enabled: boolean"
16035 true if SEV is active
16036 "api-major: int"
16038 SEV API major version
16039 "api-minor: int"
16041 SEV API minor version
16042 "build-id: int"
16044 SEV FW build id
16045 "policy: int"
16047 SEV policy value
16048 "state: SevState"
16050 SEV guest state
16051 "handle: int"
16053 SEV firmware handle
16054 Since: 2.12
16056 If: "defined(TARGET_I386)"
16058 query-sev (Command) Returns information about SEV
16060 Returns: "SevInfo"
16062 Since: 2.12
16064 Example:
16066 -> { "execute": "query-sev" }
16068 <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
16069 "build-id" : 0, "policy" : 0, "state" : "running",
16070 "handle" : 1 } }
16071 If: "defined(TARGET_I386)"
16073 SevLaunchMeasureInfo (Object)
16075 SEV Guest Launch measurement information
16077 Members:
16079 "data: string"
16081 the measurement value encoded in base64
16082 Since: 2.12
16084 If: "defined(TARGET_I386)"
16086 query-sev-launch-measure (Command) Query the SEV guest launch
16088 information.
16089 Returns: The "SevLaunchMeasureInfo" for the guest
16091 Since: 2.12
16093 Example:
16095 -> { "execute": "query-sev-launch-measure" }
16097 <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
16098 If: "defined(TARGET_I386)"
16100 SevCapability (Object)
16102 The struct describes capability for a Secure Encrypted Virtualization
16104 feature.
16105 Members:
16107 "pdh: string"
16109 Platform Diffie-Hellman key (base64 encoded)
16110 "cert-chain: string"
16112 PDH certificate chain (base64 encoded)
16113 "cbitpos: int"
16115 C-bit location in page table entry
16116 "reduced-phys-bits: int"
16118 Number of physical Address bit reduction when SEV is enabled
16119 Since: 2.12
16121 If: "defined(TARGET_I386)"
16123 query-sev-capabilities (Command) This command is used to get the SEV
16125 capabilities, and is supported on AMD X86 platforms only.
16126 Returns: SevCapability objects.
16128 Since: 2.12
16130 Example:
16132 -> { "execute": "query-sev-capabilities" }
16134 <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
16135 "cbitpos": 47, "reduced-phys-bits": 5}}
16136 If: "defined(TARGET_I386)"
16138 dump-skeys (Command) Dump guest's storage keys
16140 Arguments:
16142 "filename: string"
16144 the path to the file to dump to
16145 This command is only supported on s390 architecture.
16147 Since: 2.5
16149 Example:
16151 -> { "execute": "dump-skeys",
16153 "arguments": { "filename": "/tmp/skeys" } }
16154 <- { "return": {} }
16155 If: "defined(TARGET_S390X)"
16157 GICCapability (Object)
16159 The struct describes capability for a specific GIC (Generic Interrupt
16161 Controller) version. These bits are not only decided by QEMU/KVM
16162 software version, but also decided by the hardware that the program is
16163 running upon.
16164 Members:
16166 "version: int"
16168 version of GIC to be described. Currently, only 2 and 3 are
16169 supported.
16170 "emulated: boolean"
16172 whether current QEMU/hardware supports emulated GIC device in user
16173 space.
16174 "kernel: boolean"
16176 whether current QEMU/hardware supports hardware accelerated GIC
16177 device in kernel.
16178 Since: 2.6
16180 If: "defined(TARGET_ARM)"
16182 query-gic-capabilities (Command) This command is ARM-only. It will
16184 return a list of GICCapability objects that describe its capability
16185 bits.
16186 Returns: a list of GICCapability objects.
16188 Since: 2.6
16190 Example:
16192 -> { "execute": "query-gic-capabilities" }
16194 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
16195 { "version": 3, "emulated": false, "kernel": true } ] }
16196 If: "defined(TARGET_ARM)"
16198 AudiodevPerDirectionOptions (Object)
16200 General audio backend options that are used for both playback and
16202 recording.
16203 Members:
16205 "fixed-settings: boolean" (optional)
16207 use fixed settings for host input/output. When off, frequency,
16208 channels and format must not be specified (default true)
16209 "frequency: int" (optional)
16211 frequency to use when using fixed settings (default 44100)
16212 "channels: int" (optional)
16214 number of channels when using fixed settings (default 2)
16215 "voices: int" (optional)
16217 number of voices to use (default 1)
16218 "format: AudioFormat" (optional)
16220 sample format to use when using fixed settings (default s16)
16221 "buffer-length: int" (optional)
16223 the buffer length in microseconds
16224 Since: 4.0
16226 AudiodevGenericOptions (Object)
16228 Generic driver-specific options.
16230 Members:
16232 "in: AudiodevPerDirectionOptions" (optional)
16234 options of the capture stream
16235 "out: AudiodevPerDirectionOptions" (optional)
16237 options of the playback stream
16238 Since: 4.0
16240 AudiodevAlsaPerDirectionOptions (Object)
16242 Options of the ALSA backend that are used for both playback and
16244 recording.
16245 Members:
16247 "dev: string" (optional)
16249 the name of the ALSA device to use (default 'default')
16250 "period-length: int" (optional)
16252 the period length in microseconds
16253 "try-poll: boolean" (optional)
16255 attempt to use poll mode, falling back to non-polling access on
16256 failure (default true)
16257 The members of "AudiodevPerDirectionOptions"
16259 Since: 4.0
16261 AudiodevAlsaOptions (Object)
16263 Options of the ALSA audio backend.
16265 Members:
16267 "in: AudiodevAlsaPerDirectionOptions" (optional)
16269 options of the capture stream
16270 "out: AudiodevAlsaPerDirectionOptions" (optional)
16272 options of the playback stream
16273 "threshold: int" (optional)
16275 set the threshold (in microseconds) when playback starts
16276 Since: 4.0
16278 AudiodevCoreaudioPerDirectionOptions (Object)
16280 Options of the Core Audio backend that are used for both playback and
16282 recording.
16283 Members:
16285 "buffer-count: int" (optional)
16287 number of buffers
16288 The members of "AudiodevPerDirectionOptions"
16290 Since: 4.0
16292 AudiodevCoreaudioOptions (Object)
16294 Options of the coreaudio audio backend.
16296 Members:
16298 "in: AudiodevCoreaudioPerDirectionOptions" (optional)
16300 options of the capture stream
16301 "out: AudiodevCoreaudioPerDirectionOptions" (optional)
16303 options of the playback stream
16304 Since: 4.0
16306 AudiodevDsoundOptions (Object)
16308 Options of the DirectSound audio backend.
16310 Members:
16312 "in: AudiodevPerDirectionOptions" (optional)
16314 options of the capture stream
16315 "out: AudiodevPerDirectionOptions" (optional)
16317 options of the playback stream
16318 "latency: int" (optional)
16320 add extra latency to playback in microseconds (default 10000)
16321 Since: 4.0
16323 AudiodevOssPerDirectionOptions (Object)
16325 Options of the OSS backend that are used for both playback and
16327 recording.
16328 Members:
16330 "dev: string" (optional)
16332 file name of the OSS device (default '/dev/dsp')
16333 "buffer-count: int" (optional)
16335 number of buffers
16336 "try-poll: boolean" (optional)
16338 attempt to use poll mode, falling back to non-polling access on
16339 failure (default true)
16340 The members of "AudiodevPerDirectionOptions"
16342 Since: 4.0
16344 AudiodevOssOptions (Object)
16346 Options of the OSS audio backend.
16348 Members:
16350 "in: AudiodevOssPerDirectionOptions" (optional)
16352 options of the capture stream
16353 "out: AudiodevOssPerDirectionOptions" (optional)
16355 options of the playback stream
16356 "try-mmap: boolean" (optional)
16358 try using memory-mapped access, falling back to non-memory-mapped
16359 access on failure (default true)
16360 "exclusive: boolean" (optional)
16362 open device in exclusive mode (vmix won't work) (default false)
16363 "dsp-policy: int" (optional)
16365 set the timing policy of the device (between 0 and 10, where
16366 smaller number means smaller latency but higher CPU usage) or -1 to
16367 use fragment mode (option ignored on some platforms) (default 5)
16368 Since: 4.0
16370 AudiodevPaPerDirectionOptions (Object)
16372 Options of the Pulseaudio backend that are used for both playback and
16374 recording.
16375 Members:
16377 "name: string" (optional)
16379 name of the sink/source to use
16380 "latency: int" (optional)
16382 latency you want PulseAudio to achieve in microseconds (default
16383 15000)
16384 The members of "AudiodevPerDirectionOptions"
16386 Since: 4.0
16388 AudiodevPaOptions (Object)
16390 Options of the PulseAudio audio backend.
16392 Members:
16394 "in: AudiodevPaPerDirectionOptions" (optional)
16396 options of the capture stream
16397 "out: AudiodevPaPerDirectionOptions" (optional)
16399 options of the playback stream
16400 "server: string" (optional)
16402 PulseAudio server address (default: let PulseAudio choose)
16403 Since: 4.0
16405 AudiodevWavOptions (Object)
16407 Options of the wav audio backend.
16409 Members:
16411 "in: AudiodevPerDirectionOptions" (optional)
16413 options of the capture stream
16414 "out: AudiodevPerDirectionOptions" (optional)
16416 options of the playback stream
16417 "path: string" (optional)
16419 name of the wav file to record (default 'qemu.wav')
16420 Since: 4.0
16422 AudioFormat (Enum)
16424 An enumeration of possible audio formats.
16426 Values:
16428 "u8"
16430 Not documented
16431 "s8"
16433 Not documented
16434 "u16"
16436 Not documented
16437 "s16"
16439 Not documented
16440 "u32"
16442 Not documented
16443 "s32"
16445 Not documented
16446 Since: 4.0
16448 AudiodevDriver (Enum)
16450 An enumeration of possible audio backend drivers.
16452 Values:
16454 "none"
16456 Not documented
16457 "alsa"
16459 Not documented
16460 "coreaudio"
16462 Not documented
16463 "dsound"
16465 Not documented
16466 "oss"
16468 Not documented
16469 "pa"
16471 Not documented
16472 "sdl"
16474 Not documented
16475 "spice"
16477 Not documented
16478 "wav"
16480 Not documented
16481 Since: 4.0
16483 Audiodev (Object)
16485 Options of an audio backend.
16487 Members:
16489 "id: string"
16491 identifier of the backend
16492 "driver: AudiodevDriver"
16494 the backend driver to use
16495 "timer-period: int" (optional)
16497 timer period (in microseconds, 0: use lowest possible)
16498 The members of "AudiodevGenericOptions" when "driver" is "none"
16500 The members of "AudiodevAlsaOptions" when "driver" is "alsa"
16501 The members of "AudiodevCoreaudioOptions" when "driver" is "coreaudio"
16502 The members of "AudiodevDsoundOptions" when "driver" is "dsound"
16503 The members of "AudiodevOssOptions" when "driver" is "oss"
16504 The members of "AudiodevPaOptions" when "driver" is "pa"
16505 The members of "AudiodevGenericOptions" when "driver" is "sdl"
16506 The members of "AudiodevGenericOptions" when "driver" is "spice"
16507 The members of "AudiodevWavOptions" when "driver" is "wav"
16508 Since: 4.0
16510 2019-11-15 QEMU-QMP-REF.7(7)