1QEMU-QMP-REF.7(7) QEMU-QMP-REF.7(7)
2
6 qemu-qmp-ref - QEMU QMP Reference Manual
7
9 Introduction
10 This document describes all commands currently supported by QMP.
11 Most of the time their usage is exactly the same as in the user
13 Monitor, this means that any other document which also describe
14 commands (the manpage, QEMU's manual, etc) can and should be consulted.
15 QMP has two types of commands: regular and query commands. Regular
17 commands usually change the Virtual Machine's state someway, while
18 query commands just return information. The sections below are divided
19 accordingly.
20 It's important to observe that all communication examples are formatted
22 in a reader-friendly way, so that they're easier to understand.
23 However, in real protocol usage, they're emitted as a single line.
24 Also, the following notation is used to denote data flow:
26 Example:
28 -> data issued by the Client
30 <- Server data response
34 Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
36 detailed information on the Server command and response formats.
37 Stability Considerations
39 The current QMP command set (described in this file) may be useful for
40 a number of use cases, however it's limited and several commands have
41 bad defined semantics, specially with regard to command completion.
42 These problems are going to be solved incrementally in the next QEMU
44 releases and we're going to establish a deprecation policy for badly
45 defined commands.
46 If you're planning to adopt QMP, please observe the following:
48 1. The deprecation policy will take effect and be documented soon,
50 please check the documentation of each used command as soon as a
51 new release of QEMU is available
52 2. DO NOT rely on anything which is not explicit documented
54 3. Errors, in special, are not documented. Applications should NOT
56 check for specific errors classes or data (it's strongly
57 recommended to only check for the "error" key)
58 Common data types
60 QapiErrorClass (Enum)
61 QEMU error classes
63 Values:
65 "GenericError"
67 this is used for errors that don't require a specific error class.
68 This should be the default case for most errors
69 "CommandNotFound"
71 the requested command has not been found
72 "DeviceNotActive"
74 a device has failed to be become active
75 "DeviceNotFound"
77 the requested device has not been found
78 "KVMMissingCap"
80 the requested operation can't be fulfilled because a required KVM
81 capability is missing
82 Since: 1.2
84 IoOperationType (Enum)
86 An enumeration of the I/O operation types
88 Values:
90 "read"
92 read operation
93 "write"
95 write operation
96 Since: 2.1
98 OnOffAuto (Enum)
100 An enumeration of three options: on, off, and auto
102 Values:
104 "auto"
106 QEMU selects the value between on and off
107 "on"
109 Enabled
110 "off"
112 Disabled
113 Since: 2.2
115 OnOffSplit (Enum)
117 An enumeration of three values: on, off, and split
119 Values:
121 "on"
123 Enabled
124 "off"
126 Disabled
127 "split"
129 Mixed
130 Since: 2.6
132 String (Object)
134 A fat type wrapping 'str', to be embedded in lists.
136 Members:
138 "str: string"
140 Not documented
141 Since: 1.2
143 StrOrNull (Alternate)
145 This is a string value or the explicit lack of a string (null pointer
147 in C). Intended for cases when 'optional absent' already has a
148 different meaning.
149 Members:
151 "s: string"
153 the string value
154 "n: null"
156 no string value
157 Since: 2.10
159 OffAutoPCIBAR (Enum)
161 An enumeration of options for specifying a PCI BAR
163 Values:
165 "off"
167 The specified feature is disabled
168 "auto"
170 The PCI BAR for the feature is automatically selected
171 "bar0"
173 PCI BAR0 is used for the feature
174 "bar1"
176 PCI BAR1 is used for the feature
177 "bar2"
179 PCI BAR2 is used for the feature
180 "bar3"
182 PCI BAR3 is used for the feature
183 "bar4"
185 PCI BAR4 is used for the feature
186 "bar5"
188 PCI BAR5 is used for the feature
189 Since: 2.12
191 SysEmuTarget (Enum)
193 The comprehensive enumeration of QEMU system emulation ("softmmu")
195 targets. Run "./configure --help" in the project root directory, and
196 look for the *-softmmu targets near the "--target-list" option. The
197 individual target constants are not documented here, for the time
198 being.
199 Values:
201 "aarch64"
203 Not documented
204 "alpha"
206 Not documented
207 "arm"
209 Not documented
210 "cris"
212 Not documented
213 "hppa"
215 Not documented
216 "i386"
218 Not documented
219 "lm32"
221 Not documented
222 "m68k"
224 Not documented
225 "microblaze"
227 Not documented
228 "microblazeel"
230 Not documented
231 "mips"
233 Not documented
234 "mips64"
236 Not documented
237 "mips64el"
239 Not documented
240 "mipsel"
242 Not documented
243 "moxie"
245 Not documented
246 "nios2"
248 Not documented
249 "or1k"
251 Not documented
252 "ppc"
254 Not documented
255 "ppc64"
257 Not documented
258 "ppcemb"
260 Not documented
261 "riscv32"
263 Not documented
264 "riscv64"
266 Not documented
267 "s390x"
269 Not documented
270 "sh4"
272 Not documented
273 "sh4eb"
275 Not documented
276 "sparc"
278 Not documented
279 "sparc64"
281 Not documented
282 "tricore"
284 Not documented
285 "unicore32"
287 Not documented
288 "x86_64"
290 Not documented
291 "xtensa"
293 Not documented
294 "xtensaeb"
296 Not documented
297 Notes: The resulting QMP strings can be appended to the "qemu-system-"
299 prefix to produce the corresponding QEMU executable name. This is true
300 even for "qemu-system-x86_64".
301 Since: 3.0
303 Socket data types
305 NetworkAddressFamily (Enum)
306 The network address family
308 Values:
310 "ipv4"
312 IPV4 family
313 "ipv6"
315 IPV6 family
316 "unix"
318 unix socket
319 "vsock"
321 vsock family (since 2.8)
322 "unknown"
324 otherwise
325 Since: 2.1
327 InetSocketAddressBase (Object)
329 Members:
331 "host: string"
333 host part of the address
334 "port: string"
336 port part of the address
337 InetSocketAddress (Object)
339 Captures a socket address or address range in the Internet namespace.
341 Members:
343 "numeric: boolean" (optional)
345 true if the host/port are guaranteed to be numeric, false if name
346 resolution should be attempted. Defaults to false. (Since 2.9)
347 "to: int" (optional)
349 If present, this is range of possible addresses, with port between
350 "port" and "to".
351 "ipv4: boolean" (optional)
353 whether to accept IPv4 addresses, default try both IPv4 and IPv6
354 "ipv6: boolean" (optional)
356 whether to accept IPv6 addresses, default try both IPv4 and IPv6
357 The members of "InetSocketAddressBase"
359 Since: 1.3
361 UnixSocketAddress (Object)
363 Captures a socket address in the local ("Unix socket") namespace.
365 Members:
367 "path: string"
369 filesystem path to use
370 Since: 1.3
372 VsockSocketAddress (Object)
374 Captures a socket address in the vsock namespace.
376 Members:
378 "cid: string"
380 unique host identifier
381 "port: string"
383 port
384 Note: string types are used to allow for possible future hostname or
386 service resolution support.
387 Since: 2.8
389 SocketAddressLegacy (Object)
391 Captures the address of a socket, which could also be a named file
393 descriptor
394 Members:
396 "type"
398 One of "inet", "unix", "vsock", "fd"
399 "data: InetSocketAddress" when "type" is "inet"
401 "data: UnixSocketAddress" when "type" is "unix"
402 "data: VsockSocketAddress" when "type" is "vsock"
403 "data: String" when "type" is "fd"
404 Note: This type is deprecated in favor of SocketAddress. The
406 difference between SocketAddressLegacy and SocketAddress is that the
407 latter is a flat union rather than a simple union. Flat is nicer
408 because it avoids nesting on the wire, i.e. that form has fewer {}.
409 Since: 1.3
411 SocketAddressType (Enum)
413 Available SocketAddress types
415 Values:
417 "inet"
419 Internet address
420 "unix"
422 Unix domain socket
423 "vsock"
425 VMCI address
426 "fd"
428 decimal is for file descriptor number, otherwise a file descriptor
429 name. Named file descriptors are permitted in monitor commands, in
430 combination with the 'getfd' command. Decimal file descriptors are
431 permitted at startup or other contexts where no monitor context is
432 active.
433 Since: 2.9
435 SocketAddress (Object)
437 Captures the address of a socket, which could also be a named file
439 descriptor
440 Members:
442 "type: SocketAddressType"
444 Transport type
445 The members of "InetSocketAddress" when "type" is "inet"
447 The members of "UnixSocketAddress" when "type" is "unix"
448 The members of "VsockSocketAddress" when "type" is "vsock"
449 The members of "String" when "type" is "fd"
450 Since: 2.9
452 VM run state
454 RunState (Enum)
455 An enumeration of VM run states.
457 Values:
459 "debug"
461 QEMU is running on a debugger
462 "finish-migrate"
464 guest is paused to finish the migration process
465 "inmigrate"
467 guest is paused waiting for an incoming migration. Note that this
468 state does not tell whether the machine will start at the end of
469 the migration. This depends on the command-line -S option and any
470 invocation of 'stop' or 'cont' that has happened since QEMU was
471 started.
472 "internal-error"
474 An internal error that prevents further guest execution has
475 occurred
476 "io-error"
478 the last IOP has failed and the device is configured to pause on
479 I/O errors
480 "paused"
482 guest has been paused via the 'stop' command
483 "postmigrate"
485 guest is paused following a successful 'migrate'
486 "prelaunch"
488 QEMU was started with -S and guest has not started
489 "restore-vm"
491 guest is paused to restore VM state
492 "running"
494 guest is actively running
495 "save-vm"
497 guest is paused to save the VM state
498 "shutdown"
500 guest is shut down (and -no-shutdown is in use)
501 "suspended"
503 guest is suspended (ACPI S3)
504 "watchdog"
506 the watchdog action is configured to pause and has been triggered
507 "guest-panicked"
509 guest has been panicked as a result of guest OS panic
510 "colo"
512 guest is paused to save/restore VM state under colo checkpoint, VM
513 can not get into this state unless colo capability is enabled for
514 migration. (since 2.8)
515 "preconfig"
517 QEMU is paused before board specific init callback is executed.
518 The state is reachable only if the --preconfig CLI option is used.
519 (Since 3.0)
520 StatusInfo (Object)
522 Information about VCPU run state
524 Members:
526 "running: boolean"
528 true if all VCPUs are runnable, false if not runnable
529 "singlestep: boolean"
531 true if VCPUs are in single-step mode
532 "status: RunState"
534 the virtual machine "RunState"
535 Since: 0.14.0
537 Notes: "singlestep" is enabled through the GDB stub
539 query-status (Command) Query the run status of all VCPUs
541 Returns: "StatusInfo" reflecting all VCPUs
543 Since: 0.14.0
545 Example:
547 -> { "execute": "query-status" }
549 <- { "return": { "running": true,
550 "singlestep": false,
551 "status": "running" } }
552 SHUTDOWN (Event) Emitted when the virtual machine has shut down,
554 indicating that qemu is about to exit.
555 Arguments:
557 "guest: boolean"
559 If true, the shutdown was triggered by a guest request (such as a
560 guest-initiated ACPI shutdown request or other hardware-specific
561 action) rather than a host request (such as sending qemu a SIGINT).
562 (since 2.10)
563 Note: If the command-line option "-no-shutdown" has been specified,
565 qemu will not exit, and a STOP event will eventually follow the
566 SHUTDOWN event
567 Since: 0.12.0
569 Example:
571 <- { "event": "SHUTDOWN", "data": { "guest": true },
573 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
574 POWERDOWN (Event) Emitted when the virtual machine is powered down
576 through the power control system, such as via ACPI.
577 Since: 0.12.0
579 Example:
581 <- { "event": "POWERDOWN",
583 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
584 RESET (Event) Emitted when the virtual machine is reset
586 Arguments:
588 "guest: boolean"
590 If true, the reset was triggered by a guest request (such as a
591 guest-initiated ACPI reboot request or other hardware-specific
592 action) rather than a host request (such as the QMP command
593 system_reset). (since 2.10)
594 Since: 0.12.0
596 Example:
598 <- { "event": "RESET", "data": { "guest": false },
600 "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
601 STOP (Event) Emitted when the virtual machine is stopped
603 Since: 0.12.0
605 Example:
607 <- { "event": "STOP",
609 "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
610 RESUME (Event) Emitted when the virtual machine resumes execution
612 Since: 0.12.0
614 Example:
616 <- { "event": "RESUME",
618 "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
619 SUSPEND (Event) Emitted when guest enters a hardware suspension state,
621 for example, S3 state, which is sometimes called standby state
622 Since: 1.1
624 Example:
626 <- { "event": "SUSPEND",
628 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
629 SUSPEND_DISK (Event) Emitted when guest enters a hardware suspension
631 state with data saved on disk, for example, S4 state, which is
632 sometimes called hibernate state
633 Note: QEMU shuts down (similar to event "SHUTDOWN") when entering this
635 state
636 Since: 1.2
638 Example:
640 <- { "event": "SUSPEND_DISK",
642 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
643 WAKEUP (Event) Emitted when the guest has woken up from suspend state
645 and is running
646 Since: 1.1
648 Example:
650 <- { "event": "WAKEUP",
652 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
653 WATCHDOG (Event) Emitted when the watchdog device's timer is expired
655 Arguments:
657 "action: WatchdogAction"
659 action that has been taken
660 Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event
662 is followed respectively by the RESET, SHUTDOWN, or STOP events
663 Note: This event is rate-limited.
665 Since: 0.13.0
667 Example:
669 <- { "event": "WATCHDOG",
671 "data": { "action": "reset" },
672 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
673 WatchdogAction (Enum)
675 An enumeration of the actions taken when the watchdog device's timer is
677 expired
678 Values:
680 "reset"
682 system resets
683 "shutdown"
685 system shutdown, note that it is similar to "powerdown", which
686 tries to set to system status and notify guest
687 "poweroff"
689 system poweroff, the emulator program exits
690 "pause"
692 system pauses, similar to "stop"
693 "debug"
695 system enters debug state
696 "none"
698 nothing is done
699 "inject-nmi"
701 a non-maskable interrupt is injected into the first VCPU (all VCPUS
702 on x86) (since 2.4)
703 Since: 2.1
705 watchdog-set-action (Command) Set watchdog action
707 Arguments:
709 "action: WatchdogAction"
711 Not documented
712 Since: 2.11
714 GUEST_PANICKED (Event) Emitted when guest OS panic is detected
716 Arguments:
718 "action: GuestPanicAction"
720 action that has been taken, currently always "pause"
721 "info: GuestPanicInformation" (optional)
723 information about a panic (since 2.9)
724 Since: 1.5
726 Example:
728 <- { "event": "GUEST_PANICKED",
730 "data": { "action": "pause" } }
731 GuestPanicAction (Enum)
733 An enumeration of the actions taken when guest OS panic is detected
735 Values:
737 "pause"
739 system pauses
740 "poweroff"
742 Not documented
743 Since: 2.1 (poweroff since 2.8)
745 GuestPanicInformationType (Enum)
747 An enumeration of the guest panic information types
749 Values:
751 "hyper-v"
753 hyper-v guest panic information type
754 "s390"
756 s390 guest panic information type (Since: 2.12)
757 Since: 2.9
759 GuestPanicInformation (Object)
761 Information about a guest panic
763 Members:
765 "type: GuestPanicInformationType"
767 Crash type that defines the hypervisor specific information
768 The members of "GuestPanicInformationHyperV" when "type" is "hyper-v"
770 The members of "GuestPanicInformationS390" when "type" is "s390"
771 Since: 2.9
773 GuestPanicInformationHyperV (Object)
775 Hyper-V specific guest panic information (HV crash MSRs)
777 Members:
779 "arg1: int"
781 Not documented
782 "arg2: int"
784 Not documented
785 "arg3: int"
787 Not documented
788 "arg4: int"
790 Not documented
791 "arg5: int"
793 Not documented
794 Since: 2.9
796 S390CrashReason (Enum)
798 Reason why the CPU is in a crashed state.
800 Values:
802 "unknown"
804 no crash reason was set
805 "disabled-wait"
807 the CPU has entered a disabled wait state
808 "extint-loop"
810 clock comparator or cpu timer interrupt with new PSW enabled for
811 external interrupts
812 "pgmint-loop"
814 program interrupt with BAD new PSW
815 "opint-loop"
817 operation exception interrupt with invalid code at the program
818 interrupt new PSW
819 Since: 2.12
821 GuestPanicInformationS390 (Object)
823 S390 specific guest panic information (PSW)
825 Members:
827 "core: int"
829 core id of the CPU that crashed
830 "psw-mask: int"
832 control fields of guest PSW
833 "psw-addr: int"
835 guest instruction address
836 "reason: S390CrashReason"
838 guest crash reason
839 Since: 2.12
841 Cryptography
843 QCryptoTLSCredsEndpoint (Enum)
844 The type of network endpoint that will be using the credentials. Most
846 types of credential require different setup / structures depending on
847 whether they will be used in a server versus a client.
848 Values:
850 "client"
852 the network endpoint is acting as the client
853 "server"
855 the network endpoint is acting as the server
856 Since: 2.5
858 QCryptoSecretFormat (Enum)
860 The data format that the secret is provided in
862 Values:
864 "raw"
866 raw bytes. When encoded in JSON only valid UTF-8 sequences can be
867 used
868 "base64"
870 arbitrary base64 encoded binary data
871 Since: 2.6
873 QCryptoHashAlgorithm (Enum)
875 The supported algorithms for computing content digests
877 Values:
879 "md5"
881 MD5. Should not be used in any new code, legacy compat only
882 "sha1"
884 SHA-1. Should not be used in any new code, legacy compat only
885 "sha224"
887 SHA-224. (since 2.7)
888 "sha256"
890 SHA-256. Current recommended strong hash.
891 "sha384"
893 SHA-384. (since 2.7)
894 "sha512"
896 SHA-512. (since 2.7)
897 "ripemd160"
899 RIPEMD-160. (since 2.7)
900 Since: 2.6
902 QCryptoCipherAlgorithm (Enum)
904 The supported algorithms for content encryption ciphers
906 Values:
908 "aes-128"
910 AES with 128 bit / 16 byte keys
911 "aes-192"
913 AES with 192 bit / 24 byte keys
914 "aes-256"
916 AES with 256 bit / 32 byte keys
917 "des-rfb"
919 RFB specific variant of single DES. Do not use except in VNC.
920 "3des"
922 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
923 "cast5-128"
925 Cast5 with 128 bit / 16 byte keys
926 "serpent-128"
928 Serpent with 128 bit / 16 byte keys
929 "serpent-192"
931 Serpent with 192 bit / 24 byte keys
932 "serpent-256"
934 Serpent with 256 bit / 32 byte keys
935 "twofish-128"
937 Twofish with 128 bit / 16 byte keys
938 "twofish-192"
940 Twofish with 192 bit / 24 byte keys
941 "twofish-256"
943 Twofish with 256 bit / 32 byte keys
944 Since: 2.6
946 QCryptoCipherMode (Enum)
948 The supported modes for content encryption ciphers
950 Values:
952 "ecb"
954 Electronic Code Book
955 "cbc"
957 Cipher Block Chaining
958 "xts"
960 XEX with tweaked code book and ciphertext stealing
961 "ctr"
963 Counter (Since 2.8)
964 Since: 2.6
966 QCryptoIVGenAlgorithm (Enum)
968 The supported algorithms for generating initialization vectors for full
970 disk encryption. The 'plain' generator should not be used for disks
971 with sector numbers larger than 2^32, except where compatibility with
972 pre-existing Linux dm-crypt volumes is required.
973 Values:
975 "plain"
977 64-bit sector number truncated to 32-bits
978 "plain64"
980 64-bit sector number
981 "essiv"
983 64-bit sector number encrypted with a hash of the encryption key
984 Since: 2.6
986 QCryptoBlockFormat (Enum)
988 The supported full disk encryption formats
990 Values:
992 "qcow"
994 QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
995 data from old images.
996 "luks"
998 LUKS encryption format. Recommended for new images
999 Since: 2.6
1001 QCryptoBlockOptionsBase (Object)
1003 The common options that apply to all full disk encryption formats
1005 Members:
1007 "format: QCryptoBlockFormat"
1009 the encryption format
1010 Since: 2.6
1012 QCryptoBlockOptionsQCow (Object)
1014 The options that apply to QCow/QCow2 AES-CBC encryption format
1016 Members:
1018 "key-secret: string" (optional)
1020 the ID of a QCryptoSecret object providing the decryption key.
1021 Mandatory except when probing image for metadata only.
1022 Since: 2.6
1024 QCryptoBlockOptionsLUKS (Object)
1026 The options that apply to LUKS encryption format
1028 Members:
1030 "key-secret: string" (optional)
1032 the ID of a QCryptoSecret object providing the decryption key.
1033 Mandatory except when probing image for metadata only.
1034 Since: 2.6
1036 QCryptoBlockCreateOptionsLUKS (Object)
1038 The options that apply to LUKS encryption format initialization
1040 Members:
1042 "cipher-alg: QCryptoCipherAlgorithm" (optional)
1044 the cipher algorithm for data encryption Currently defaults to
1045 'aes'.
1046 "cipher-mode: QCryptoCipherMode" (optional)
1048 the cipher mode for data encryption Currently defaults to 'cbc'
1049 "ivgen-alg: QCryptoIVGenAlgorithm" (optional)
1051 the initialization vector generator Currently defaults to 'essiv'
1052 "ivgen-hash-alg: QCryptoHashAlgorithm" (optional)
1054 the initialization vector generator hash Currently defaults to
1055 'sha256'
1056 "hash-alg: QCryptoHashAlgorithm" (optional)
1058 the master key hash algorithm Currently defaults to 'sha256'
1059 "iter-time: int" (optional)
1061 number of milliseconds to spend in PBKDF passphrase processing.
1062 Currently defaults to 2000. (since 2.8)
1063 The members of "QCryptoBlockOptionsLUKS"
1065 Since: 2.6
1067 QCryptoBlockOpenOptions (Object)
1069 The options that are available for all encryption formats when opening
1071 an existing volume
1072 Members:
1074 The members of "QCryptoBlockOptionsBase"
1076 The members of "QCryptoBlockOptionsQCow" when "format" is "qcow"
1077 The members of "QCryptoBlockOptionsLUKS" when "format" is "luks"
1078 Since: 2.6
1080 QCryptoBlockCreateOptions (Object)
1082 The options that are available for all encryption formats when
1084 initializing a new volume
1085 Members:
1087 The members of "QCryptoBlockOptionsBase"
1089 The members of "QCryptoBlockOptionsQCow" when "format" is "qcow"
1090 The members of "QCryptoBlockCreateOptionsLUKS" when "format" is "luks"
1091 Since: 2.6
1093 QCryptoBlockInfoBase (Object)
1095 The common information that applies to all full disk encryption formats
1097 Members:
1099 "format: QCryptoBlockFormat"
1101 the encryption format
1102 Since: 2.7
1104 QCryptoBlockInfoLUKSSlot (Object)
1106 Information about the LUKS block encryption key slot options
1108 Members:
1110 "active: boolean"
1112 whether the key slot is currently in use
1113 "key-offset: int"
1115 offset to the key material in bytes
1116 "iters: int" (optional)
1118 number of PBKDF2 iterations for key material
1119 "stripes: int" (optional)
1121 number of stripes for splitting key material
1122 Since: 2.7
1124 QCryptoBlockInfoLUKS (Object)
1126 Information about the LUKS block encryption options
1128 Members:
1130 "cipher-alg: QCryptoCipherAlgorithm"
1132 the cipher algorithm for data encryption
1133 "cipher-mode: QCryptoCipherMode"
1135 the cipher mode for data encryption
1136 "ivgen-alg: QCryptoIVGenAlgorithm"
1138 the initialization vector generator
1139 "ivgen-hash-alg: QCryptoHashAlgorithm" (optional)
1141 the initialization vector generator hash
1142 "hash-alg: QCryptoHashAlgorithm"
1144 the master key hash algorithm
1145 "payload-offset: int"
1147 offset to the payload data in bytes
1148 "master-key-iters: int"
1150 number of PBKDF2 iterations for key material
1151 "uuid: string"
1153 unique identifier for the volume
1154 "slots: array of QCryptoBlockInfoLUKSSlot"
1156 information about each key slot
1157 Since: 2.7
1159 QCryptoBlockInfo (Object)
1161 Information about the block encryption options
1163 Members:
1165 The members of "QCryptoBlockInfoBase"
1167 The members of "QCryptoBlockInfoLUKS" when "format" is "luks"
1168 Since: 2.7
1170 Block devices
1172 Block core (VM unrelated)
1173 Background jobs
1175 JobType (Enum)
1177 Type of a background job.
1179 Values:
1181 "commit"
1183 block commit job type, see "block-commit"
1184 "stream"
1186 block stream job type, see "block-stream"
1187 "mirror"
1189 drive mirror job type, see "drive-mirror"
1190 "backup"
1192 drive backup job type, see "drive-backup"
1193 "create"
1195 image creation job type, see "blockdev-create" (since 3.0)
1196 Since: 1.7
1198 JobStatus (Enum)
1200 Indicates the present state of a given job in its lifetime.
1202 Values:
1204 "undefined"
1206 Erroneous, default state. Should not ever be visible.
1207 "created"
1209 The job has been created, but not yet started.
1210 "running"
1212 The job is currently running.
1213 "paused"
1215 The job is running, but paused. The pause may be requested by
1216 either the QMP user or by internal processes.
1217 "ready"
1219 The job is running, but is ready for the user to signal completion.
1220 This is used for long-running jobs like mirror that are designed to
1221 run indefinitely.
1222 "standby"
1224 The job is ready, but paused. This is nearly identical to "paused".
1225 The job may return to "ready" or otherwise be canceled.
1226 "waiting"
1228 The job is waiting for other jobs in the transaction to converge to
1229 the waiting state. This status will likely not be visible for the
1230 last job in a transaction.
1231 "pending"
1233 The job has finished its work, but has finalization steps that it
1234 needs to make prior to completing. These changes will require
1235 manual intervention via "job-finalize" if auto-finalize was set to
1236 false. These pending changes may still fail.
1237 "aborting"
1239 The job is in the process of being aborted, and will finish with an
1240 error. The job will afterwards report that it is "concluded". This
1241 status may not be visible to the management process.
1242 "concluded"
1244 The job has finished all work. If auto-dismiss was set to false,
1245 the job will remain in the query list until it is dismissed via
1246 "job-dismiss".
1247 "null"
1249 The job is in the process of being dismantled. This state should
1250 not ever be visible externally.
1251 Since: 2.12
1253 JobVerb (Enum)
1255 Represents command verbs that can be applied to a job.
1257 Values:
1259 "cancel"
1261 see "job-cancel"
1262 "pause"
1264 see "job-pause"
1265 "resume"
1267 see "job-resume"
1268 "set-speed"
1270 see "block-job-set-speed"
1271 "complete"
1273 see "job-complete"
1274 "dismiss"
1276 see "job-dismiss"
1277 "finalize"
1279 see "job-finalize"
1280 Since: 2.12
1282 JOB_STATUS_CHANGE (Event) Emitted when a job transitions to a
1284 different status.
1285 Arguments:
1287 "id: string"
1289 The job identifier
1290 "status: JobStatus"
1292 The new job status
1293 Since: 3.0
1295 job-pause (Command) Pause an active job.
1297 This command returns immediately after marking the active job for
1299 pausing. Pausing an already paused job is an error.
1300 The job will pause as soon as possible, which means transitioning into
1302 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
1303 The corresponding JOB_STATUS_CHANGE event will be emitted.
1304 Cancelling a paused job automatically resumes it.
1306 Arguments:
1308 "id: string"
1310 The job identifier.
1311 Since: 3.0
1313 job-resume (Command) Resume a paused job.
1315 This command returns immediately after resuming a paused job. Resuming
1317 an already running job is an error.
1318 "id" : The job identifier.
1320 Arguments:
1322 "id: string"
1324 Not documented
1325 Since: 3.0
1327 job-cancel (Command) Instruct an active background job to cancel at
1329 the next opportunity. This command returns immediately after marking
1330 the active job for cancellation.
1331 The job will cancel as soon as possible and then emit a
1333 JOB_STATUS_CHANGE event. Usually, the status will change to ABORTING,
1334 but it is possible that a job successfully completes (e.g. because it
1335 was almost done and there was no opportunity to cancel earlier than
1336 completing the job) and transitions to PENDING instead.
1337 Arguments:
1339 "id: string"
1341 The job identifier.
1342 Since: 3.0
1344 job-complete (Command) Manually trigger completion of an active job in
1346 the READY state.
1347 Arguments:
1349 "id: string"
1351 The job identifier.
1352 Since: 3.0
1354 job-dismiss (Command) Deletes a job that is in the CONCLUDED state.
1356 This command only needs to be run explicitly for jobs that don't have
1357 automatic dismiss enabled.
1358 This command will refuse to operate on any job that has not yet reached
1360 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
1361 JOB_READY event, job-cancel or job-complete will still need to be used
1362 as appropriate.
1363 Arguments:
1365 "id: string"
1367 The job identifier.
1368 Since: 3.0
1370 job-finalize (Command) Instructs all jobs in a transaction (or a
1372 single job if it is not part of any transaction) to finalize any graph
1373 changes and do any necessary cleanup. This command requires that all
1374 involved jobs are in the PENDING state.
1375 For jobs in a transaction, instructing one job to finalize will force
1377 ALL jobs in the transaction to finalize, so it is only necessary to
1378 instruct a single member job to finalize.
1379 Arguments:
1381 "id: string"
1383 The identifier of any job in the transaction, or of a job that is
1384 not part of any transaction.
1385 Since: 3.0
1387 JobInfo (Object)
1389 Information about a job.
1391 Members:
1393 "id: string"
1395 The job identifier
1396 "type: JobType"
1398 The kind of job that is being performed
1399 "status: JobStatus"
1401 Current job state/status
1402 "current-progress: int"
1404 Progress made until now. The unit is arbitrary and the value can
1405 only meaningfully be used for the ratio of "current-progress" to
1406 "total-progress". The value is monotonically increasing.
1407 "total-progress: int"
1409 Estimated "current-progress" value at the completion of the job.
1410 This value can arbitrarily change while the job is running, in both
1411 directions.
1412 "error: string" (optional)
1414 If this field is present, the job failed; if it is still missing in
1415 the CONCLUDED state, this indicates successful completion.
1416 The value is a human-readable error message to describe the reason
1418 for the job failure. It should not be parsed by applications.
1419 Since: 3.0
1421 query-jobs (Command) Return information about jobs.
1423 Returns: a list with a "JobInfo" for each active job
1425 Since: 3.0
1427 SnapshotInfo (Object)
1429 Members:
1431 "id: string"
1433 unique snapshot id
1434 "name: string"
1436 user chosen name
1437 "vm-state-size: int"
1439 size of the VM state
1440 "date-sec: int"
1442 UTC date of the snapshot in seconds
1443 "date-nsec: int"
1445 fractional part in nano seconds to be used with date-sec
1446 "vm-clock-sec: int"
1448 VM clock relative to boot in seconds
1449 "vm-clock-nsec: int"
1451 fractional part in nano seconds to be used with vm-clock-sec
1452 Since: 1.3
1454 ImageInfoSpecificQCow2EncryptionBase (Object)
1456 Members:
1458 "format: BlockdevQcow2EncryptionFormat"
1460 The encryption format
1461 Since: 2.10
1463 ImageInfoSpecificQCow2Encryption (Object)
1465 Members:
1467 The members of "ImageInfoSpecificQCow2EncryptionBase"
1469 The members of "QCryptoBlockInfoLUKS" when "format" is "luks"
1470 Since: 2.10
1472 ImageInfoSpecificQCow2 (Object)
1474 Members:
1476 "compat: string"
1478 compatibility level
1479 "lazy-refcounts: boolean" (optional)
1481 on or off; only valid for compat >= 1.1
1482 "corrupt: boolean" (optional)
1484 true if the image has been marked corrupt; only valid for compat >=
1485 1.1 (since 2.2)
1486 "refcount-bits: int"
1488 width of a refcount entry in bits (since 2.3)
1489 "encrypt: ImageInfoSpecificQCow2Encryption" (optional)
1491 details about encryption parameters; only set if image is encrypted
1492 (since 2.10)
1493 Since: 1.7
1495 ImageInfoSpecificVmdk (Object)
1497 Members:
1499 "create-type: string"
1501 The create type of VMDK image
1502 "cid: int"
1504 Content id of image
1505 "parent-cid: int"
1507 Parent VMDK image's cid
1508 "extents: array of ImageInfo"
1510 List of extent files
1511 Since: 1.7
1513 ImageInfoSpecific (Object)
1515 A discriminated record of image format specific information structures.
1517 Members:
1519 "type"
1521 One of "qcow2", "vmdk", "luks"
1522 "data: ImageInfoSpecificQCow2" when "type" is "qcow2"
1524 "data: ImageInfoSpecificVmdk" when "type" is "vmdk"
1525 "data: QCryptoBlockInfoLUKS" when "type" is "luks"
1526 Since: 1.7
1528 ImageInfo (Object)
1530 Information about a QEMU image file
1532 Members:
1534 "filename: string"
1536 name of the image file
1537 "format: string"
1539 format of the image file
1540 "virtual-size: int"
1542 maximum capacity in bytes of the image
1543 "actual-size: int" (optional)
1545 actual size on disk in bytes of the image
1546 "dirty-flag: boolean" (optional)
1548 true if image is not cleanly closed
1549 "cluster-size: int" (optional)
1551 size of a cluster in bytes
1552 "encrypted: boolean" (optional)
1554 true if the image is encrypted
1555 "compressed: boolean" (optional)
1557 true if the image is compressed (Since 1.7)
1558 "backing-filename: string" (optional)
1560 name of the backing file
1561 "full-backing-filename: string" (optional)
1563 full path of the backing file
1564 "backing-filename-format: string" (optional)
1566 the format of the backing file
1567 "snapshots: array of SnapshotInfo" (optional)
1569 list of VM snapshots
1570 "backing-image: ImageInfo" (optional)
1572 info of the backing image (since 1.6)
1573 "format-specific: ImageInfoSpecific" (optional)
1575 structure supplying additional format-specific information (since
1576 1.7)
1577 Since: 1.3
1579 ImageCheck (Object)
1581 Information about a QEMU image file check
1583 Members:
1585 "filename: string"
1587 name of the image file checked
1588 "format: string"
1590 format of the image file checked
1591 "check-errors: int"
1593 number of unexpected errors occurred during check
1594 "image-end-offset: int" (optional)
1596 offset (in bytes) where the image ends, this field is present if
1597 the driver for the image format supports it
1598 "corruptions: int" (optional)
1600 number of corruptions found during the check if any
1601 "leaks: int" (optional)
1603 number of leaks found during the check if any
1604 "corruptions-fixed: int" (optional)
1606 number of corruptions fixed during the check if any
1607 "leaks-fixed: int" (optional)
1609 number of leaks fixed during the check if any
1610 "total-clusters: int" (optional)
1612 total number of clusters, this field is present if the driver for
1613 the image format supports it
1614 "allocated-clusters: int" (optional)
1616 total number of allocated clusters, this field is present if the
1617 driver for the image format supports it
1618 "fragmented-clusters: int" (optional)
1620 total number of fragmented clusters, this field is present if the
1621 driver for the image format supports it
1622 "compressed-clusters: int" (optional)
1624 total number of compressed clusters, this field is present if the
1625 driver for the image format supports it
1626 Since: 1.4
1628 MapEntry (Object)
1630 Mapping information from a virtual block range to a host file range
1632 Members:
1634 "start: int"
1636 the start byte of the mapped virtual range
1637 "length: int"
1639 the number of bytes of the mapped virtual range
1640 "data: boolean"
1642 whether the mapped range has data
1643 "zero: boolean"
1645 whether the virtual blocks are zeroed
1646 "depth: int"
1648 the depth of the mapping
1649 "offset: int" (optional)
1651 the offset in file that the virtual sectors are mapped to
1652 "filename: string" (optional)
1654 filename that is referred to by "offset"
1655 Since: 2.6
1657 BlockdevCacheInfo (Object)
1659 Cache mode information for a block device
1661 Members:
1663 "writeback: boolean"
1665 true if writeback mode is enabled
1666 "direct: boolean"
1668 true if the host page cache is bypassed (O_DIRECT)
1669 "no-flush: boolean"
1671 true if flush requests are ignored for the device
1672 Since: 2.3
1674 BlockDeviceInfo (Object)
1676 Information about the backing device for a block device.
1678 Members:
1680 "file: string"
1682 the filename of the backing device
1683 "node-name: string" (optional)
1685 the name of the block driver node (Since 2.0)
1686 "ro: boolean"
1688 true if the backing device was open read-only
1689 "drv: string"
1691 the name of the block format used to open the backing device. As of
1692 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
1693 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device', 'http',
1694 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2', 'raw', 'vdi',
1695 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added, 'cow' dropped 2.3:
1696 'host_floppy' deprecated 2.5: 'host_floppy' dropped 2.6: 'luks'
1697 added 2.8: 'replication' added, 'tftp' dropped 2.9: 'archipelago'
1698 dropped
1699 "backing_file: string" (optional)
1701 the name of the backing file (for copy-on-write)
1702 "backing_file_depth: int"
1704 number of files in the backing file chain (since: 1.2)
1705 "encrypted: boolean"
1707 true if the backing device is encrypted
1708 "encryption_key_missing: boolean"
1710 Deprecated; always false
1711 "detect_zeroes: BlockdevDetectZeroesOptions"
1713 detect and optimize zero writes (Since 2.1)
1714 "bps: int"
1716 total throughput limit in bytes per second is specified
1717 "bps_rd: int"
1719 read throughput limit in bytes per second is specified
1720 "bps_wr: int"
1722 write throughput limit in bytes per second is specified
1723 "iops: int"
1725 total I/O operations per second is specified
1726 "iops_rd: int"
1728 read I/O operations per second is specified
1729 "iops_wr: int"
1731 write I/O operations per second is specified
1732 "image: ImageInfo"
1734 the info of image used (since: 1.6)
1735 "bps_max: int" (optional)
1737 total throughput limit during bursts, in bytes (Since 1.7)
1738 "bps_rd_max: int" (optional)
1740 read throughput limit during bursts, in bytes (Since 1.7)
1741 "bps_wr_max: int" (optional)
1743 write throughput limit during bursts, in bytes (Since 1.7)
1744 "iops_max: int" (optional)
1746 total I/O operations per second during bursts, in bytes (Since 1.7)
1747 "iops_rd_max: int" (optional)
1749 read I/O operations per second during bursts, in bytes (Since 1.7)
1750 "iops_wr_max: int" (optional)
1752 write I/O operations per second during bursts, in bytes (Since 1.7)
1753 "bps_max_length: int" (optional)
1755 maximum length of the "bps_max" burst period, in seconds. (Since
1756 2.6)
1757 "bps_rd_max_length: int" (optional)
1759 maximum length of the "bps_rd_max" burst period, in seconds. (Since
1760 2.6)
1761 "bps_wr_max_length: int" (optional)
1763 maximum length of the "bps_wr_max" burst period, in seconds. (Since
1764 2.6)
1765 "iops_max_length: int" (optional)
1767 maximum length of the "iops" burst period, in seconds. (Since 2.6)
1768 "iops_rd_max_length: int" (optional)
1770 maximum length of the "iops_rd_max" burst period, in seconds.
1771 (Since 2.6)
1772 "iops_wr_max_length: int" (optional)
1774 maximum length of the "iops_wr_max" burst period, in seconds.
1775 (Since 2.6)
1776 "iops_size: int" (optional)
1778 an I/O size in bytes (Since 1.7)
1779 "group: string" (optional)
1781 throttle group name (Since 2.4)
1782 "cache: BlockdevCacheInfo"
1784 the cache mode used for the block device (since: 2.3)
1785 "write_threshold: int"
1787 configured write threshold for the device. 0 if disabled. (Since
1788 2.3)
1789 Since: 0.14.0
1791 BlockDeviceIoStatus (Enum)
1793 An enumeration of block device I/O status.
1795 Values:
1797 "ok"
1799 The last I/O operation has succeeded
1800 "failed"
1802 The last I/O operation has failed
1803 "nospace"
1805 The last I/O operation has failed due to a no-space condition
1806 Since: 1.0
1808 BlockDeviceMapEntry (Object)
1810 Entry in the metadata map of the device (returned by "qemu-img map")
1812 Members:
1814 "start: int"
1816 Offset in the image of the first byte described by this entry (in
1817 bytes)
1818 "length: int"
1820 Length of the range described by this entry (in bytes)
1821 "depth: int"
1823 Number of layers (0 = top image, 1 = top image's backing file,
1824 etc.) before reaching one for which the range is allocated. The
1825 value is in the range 0 to the depth of the image chain - 1.
1826 "zero: boolean"
1828 the sectors in this range read as zeros
1829 "data: boolean"
1831 reading the image will actually read data from a file (in
1832 particular, if "offset" is present this means that the sectors are
1833 not simply preallocated, but contain actual data in raw format)
1834 "offset: int" (optional)
1836 if present, the image file stores the data for this range in raw
1837 format at the given offset.
1838 Since: 1.7
1840 DirtyBitmapStatus (Enum)
1842 An enumeration of possible states that a dirty bitmap can report to the
1844 user.
1845 Values:
1847 "frozen"
1849 The bitmap is currently in-use by a backup operation or block job,
1850 and is immutable.
1851 "disabled"
1853 The bitmap is currently in-use by an internal operation and is
1854 read-only. It can still be deleted.
1855 "active"
1857 The bitmap is actively monitoring for new writes, and can be
1858 cleared, deleted, or used for backup operations.
1859 "locked"
1861 The bitmap is currently in-use by some operation and can not be
1862 cleared, deleted, or used for backup operations. (Since 2.12)
1863 Since: 2.4
1865 BlockDirtyInfo (Object)
1867 Block dirty bitmap information.
1869 Members:
1871 "name: string" (optional)
1873 the name of the dirty bitmap (Since 2.4)
1874 "count: int"
1876 number of dirty bytes according to the dirty bitmap
1877 "granularity: int"
1879 granularity of the dirty bitmap in bytes (since 1.4)
1880 "status: DirtyBitmapStatus"
1882 current status of the dirty bitmap (since 2.4)
1883 Since: 1.3
1885 BlockLatencyHistogramInfo (Object)
1887 Block latency histogram.
1889 Members:
1891 "boundaries: array of int"
1893 list of interval boundary values in nanoseconds, all greater than
1894 zero and in ascending order. For example, the list [10, 50, 100]
1895 produces the following histogram intervals: [0, 10), [10, 50), [50,
1896 100), [100, +inf).
1897 "bins: array of int"
1899 list of io request counts corresponding to histogram intervals.
1900 len("bins") = len("boundaries") + 1 For the example above, "bins"
1901 may be something like [3, 1, 5, 2], and corresponding histogram
1902 looks like:
1903 5| * 4| * 3| 2| * 1|
1905 +------------------ 10 50 100
1906 Since: 2.12
1908 x-block-latency-histogram-set (Command) Manage read, write and flush
1910 latency histograms for the device.
1911 If only "device" parameter is specified, remove all present latency
1913 histograms for the device. Otherwise, add/reset some of (or all)
1914 latency histograms.
1915 Arguments:
1917 "device: string"
1919 device name to set latency histogram for.
1920 "boundaries: array of int" (optional)
1922 list of interval boundary values (see description in
1923 BlockLatencyHistogramInfo definition). If specified, all latency
1924 histograms are removed, and empty ones created for all io types
1925 with intervals corresponding to "boundaries" (except for io types,
1926 for which specific boundaries are set through the following
1927 parameters).
1928 "boundaries-read: array of int" (optional)
1930 list of interval boundary values for read latency histogram. If
1931 specified, old read latency histogram is removed, and empty one
1932 created with intervals corresponding to "boundaries-read". The
1933 parameter has higher priority then "boundaries".
1934 "boundaries-write: array of int" (optional)
1936 list of interval boundary values for write latency histogram.
1937 "boundaries-flush: array of int" (optional)
1939 list of interval boundary values for flush latency histogram.
1940 Returns: error if device is not found or any boundary arrays are
1942 invalid.
1943 Since: 2.12
1945 Example:
1947 set new histograms for all io types with intervals
1949 [0, 10), [10, 50), [50, 100), [100, +inf):
1950 -> { "execute": "block-latency-histogram-set",
1952 "arguments": { "device": "drive0",
1953 "boundaries": [10, 50, 100] } }
1954 <- { "return": {} }
1955 Example:
1957 set new histogram only for write, other histograms will remain
1959 not changed (or not created):
1960 -> { "execute": "block-latency-histogram-set",
1962 "arguments": { "device": "drive0",
1963 "boundaries-write": [10, 50, 100] } }
1964 <- { "return": {} }
1965 Example:
1967 set new histograms with the following intervals:
1969 read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
1970 write: [0, 1000), [1000, 5000), [5000, +inf)
1971 -> { "execute": "block-latency-histogram-set",
1973 "arguments": { "device": "drive0",
1974 "boundaries": [10, 50, 100],
1975 "boundaries-write": [1000, 5000] } }
1976 <- { "return": {} }
1977 Example:
1979 remove all latency histograms:
1981 -> { "execute": "block-latency-histogram-set",
1983 "arguments": { "device": "drive0" } }
1984 <- { "return": {} }
1985 BlockInfo (Object)
1987 Block device information. This structure describes a virtual device
1989 and the backing device associated with it.
1990 Members:
1992 "device: string"
1994 The device name associated with the virtual device.
1995 "qdev: string" (optional)
1997 The qdev ID, or if no ID is assigned, the QOM path of the block
1998 device. (since 2.10)
1999 "type: string"
2001 This field is returned only for compatibility reasons, it should
2002 not be used (always returns 'unknown')
2003 "removable: boolean"
2005 True if the device supports removable media.
2006 "locked: boolean"
2008 True if the guest has locked this device from having its media
2009 removed
2010 "tray_open: boolean" (optional)
2012 True if the device's tray is open (only present if it has a tray)
2013 "dirty-bitmaps: array of BlockDirtyInfo" (optional)
2015 dirty bitmaps information (only present if the driver has one or
2016 more dirty bitmaps) (Since 2.0)
2017 "io-status: BlockDeviceIoStatus" (optional)
2019 "BlockDeviceIoStatus". Only present if the device supports it and
2020 the VM is configured to stop on errors (supported device models:
2021 virtio-blk, IDE, SCSI except scsi-generic)
2022 "inserted: BlockDeviceInfo" (optional)
2024 "BlockDeviceInfo" describing the device if media is present
2025 Since: 0.14.0
2027 BlockMeasureInfo (Object)
2029 Image file size calculation information. This structure describes the
2031 size requirements for creating a new image file.
2032 The size requirements depend on the new image file format. File size
2034 always equals virtual disk size for the 'raw' format, even for sparse
2035 POSIX files. Compact formats such as 'qcow2' represent unallocated and
2036 zero regions efficiently so file size may be smaller than virtual disk
2037 size.
2038 The values are upper bounds that are guaranteed to fit the new image
2040 file. Subsequent modification, such as internal snapshot or bitmap
2041 creation, may require additional space and is not covered here.
2042 Members:
2044 "required: int"
2046 Size required for a new image file, in bytes.
2047 "fully-allocated: int"
2049 Image file size, in bytes, once data has been written to all
2050 sectors.
2051 Since: 2.10
2053 query-block (Command) Get a list of BlockInfo for all virtual block
2055 devices.
2056 Returns: a list of "BlockInfo" describing each virtual block device.
2058 Filter nodes that were created implicitly are skipped over.
2059 Since: 0.14.0
2061 Example:
2063 -> { "execute": "query-block" }
2065 <- {
2066 "return":[
2067 {
2068 "io-status": "ok",
2069 "device":"ide0-hd0",
2070 "locked":false,
2071 "removable":false,
2072 "inserted":{
2073 "ro":false,
2074 "drv":"qcow2",
2075 "encrypted":false,
2076 "file":"disks/test.qcow2",
2077 "backing_file_depth":1,
2078 "bps":1000000,
2079 "bps_rd":0,
2080 "bps_wr":0,
2081 "iops":1000000,
2082 "iops_rd":0,
2083 "iops_wr":0,
2084 "bps_max": 8000000,
2085 "bps_rd_max": 0,
2086 "bps_wr_max": 0,
2087 "iops_max": 0,
2088 "iops_rd_max": 0,
2089 "iops_wr_max": 0,
2090 "iops_size": 0,
2091 "detect_zeroes": "on",
2092 "write_threshold": 0,
2093 "image":{
2094 "filename":"disks/test.qcow2",
2095 "format":"qcow2",
2096 "virtual-size":2048000,
2097 "backing_file":"base.qcow2",
2098 "full-backing-filename":"disks/base.qcow2",
2099 "backing-filename-format":"qcow2",
2100 "snapshots":[
2101 {
2102 "id": "1",
2103 "name": "snapshot1",
2104 "vm-state-size": 0,
2105 "date-sec": 10000200,
2106 "date-nsec": 12,
2107 "vm-clock-sec": 206,
2108 "vm-clock-nsec": 30
2109 }
2110 ],
2111 "backing-image":{
2112 "filename":"disks/base.qcow2",
2113 "format":"qcow2",
2114 "virtual-size":2048000
2115 }
2116 }
2117 },
2118 "qdev": "ide_disk",
2119 "type":"unknown"
2120 },
2121 {
2122 "io-status": "ok",
2123 "device":"ide1-cd0",
2124 "locked":false,
2125 "removable":true,
2126 "qdev": "/machine/unattached/device[23]",
2127 "tray_open": false,
2128 "type":"unknown"
2129 },
2130 {
2131 "device":"floppy0",
2132 "locked":false,
2133 "removable":true,
2134 "qdev": "/machine/unattached/device[20]",
2135 "type":"unknown"
2136 },
2137 {
2138 "device":"sd0",
2139 "locked":false,
2140 "removable":true,
2141 "type":"unknown"
2142 }
2143 ]
2144 }
2145 BlockDeviceTimedStats (Object)
2147 Statistics of a block device during a given interval of time.
2149 Members:
2151 "interval_length: int"
2153 Interval used for calculating the statistics, in seconds.
2154 "min_rd_latency_ns: int"
2156 Minimum latency of read operations in the defined interval, in
2157 nanoseconds.
2158 "min_wr_latency_ns: int"
2160 Minimum latency of write operations in the defined interval, in
2161 nanoseconds.
2162 "min_flush_latency_ns: int"
2164 Minimum latency of flush operations in the defined interval, in
2165 nanoseconds.
2166 "max_rd_latency_ns: int"
2168 Maximum latency of read operations in the defined interval, in
2169 nanoseconds.
2170 "max_wr_latency_ns: int"
2172 Maximum latency of write operations in the defined interval, in
2173 nanoseconds.
2174 "max_flush_latency_ns: int"
2176 Maximum latency of flush operations in the defined interval, in
2177 nanoseconds.
2178 "avg_rd_latency_ns: int"
2180 Average latency of read operations in the defined interval, in
2181 nanoseconds.
2182 "avg_wr_latency_ns: int"
2184 Average latency of write operations in the defined interval, in
2185 nanoseconds.
2186 "avg_flush_latency_ns: int"
2188 Average latency of flush operations in the defined interval, in
2189 nanoseconds.
2190 "avg_rd_queue_depth: number"
2192 Average number of pending read operations in the defined interval.
2193 "avg_wr_queue_depth: number"
2195 Average number of pending write operations in the defined interval.
2196 Since: 2.5
2198 BlockDeviceStats (Object)
2200 Statistics of a virtual block device or a block backing device.
2202 Members:
2204 "rd_bytes: int"
2206 The number of bytes read by the device.
2207 "wr_bytes: int"
2209 The number of bytes written by the device.
2210 "rd_operations: int"
2212 The number of read operations performed by the device.
2213 "wr_operations: int"
2215 The number of write operations performed by the device.
2216 "flush_operations: int"
2218 The number of cache flush operations performed by the device (since
2219 0.15.0)
2220 "flush_total_time_ns: int"
2222 Total time spend on cache flushes in nano-seconds (since 0.15.0).
2223 "wr_total_time_ns: int"
2225 Total time spend on writes in nano-seconds (since 0.15.0).
2226 "rd_total_time_ns: int"
2228 Total_time_spend on reads in nano-seconds (since 0.15.0).
2229 "wr_highest_offset: int"
2231 The offset after the greatest byte written to the device. The
2232 intended use of this information is for growable sparse files (like
2233 qcow2) that are used on top of a physical device.
2234 "rd_merged: int"
2236 Number of read requests that have been merged into another request
2237 (Since 2.3).
2238 "wr_merged: int"
2240 Number of write requests that have been merged into another request
2241 (Since 2.3).
2242 "idle_time_ns: int" (optional)
2244 Time since the last I/O operation, in nanoseconds. If the field is
2245 absent it means that there haven't been any operations yet (Since
2246 2.5).
2247 "failed_rd_operations: int"
2249 The number of failed read operations performed by the device (Since
2250 2.5)
2251 "failed_wr_operations: int"
2253 The number of failed write operations performed by the device
2254 (Since 2.5)
2255 "failed_flush_operations: int"
2257 The number of failed flush operations performed by the device
2258 (Since 2.5)
2259 "invalid_rd_operations: int"
2261 The number of invalid read operations performed by the device
2262 (Since 2.5)
2263 "invalid_wr_operations: int"
2265 The number of invalid write operations performed by the device
2266 (Since 2.5)
2267 "invalid_flush_operations: int"
2269 The number of invalid flush operations performed by the device
2270 (Since 2.5)
2271 "account_invalid: boolean"
2273 Whether invalid operations are included in the last access
2274 statistics (Since 2.5)
2275 "account_failed: boolean"
2277 Whether failed operations are included in the latency and last
2278 access statistics (Since 2.5)
2279 "timed_stats: array of BlockDeviceTimedStats"
2281 Statistics specific to the set of previously defined intervals of
2282 time (Since 2.5)
2283 "x_rd_latency_histogram: BlockLatencyHistogramInfo" (optional)
2285 "BlockLatencyHistogramInfo". (Since 2.12)
2286 "x_wr_latency_histogram: BlockLatencyHistogramInfo" (optional)
2288 "BlockLatencyHistogramInfo". (Since 2.12)
2289 "x_flush_latency_histogram: BlockLatencyHistogramInfo" (optional)
2291 "BlockLatencyHistogramInfo". (Since 2.12)
2292 Since: 0.14.0
2294 BlockStats (Object)
2296 Statistics of a virtual block device or a block backing device.
2298 Members:
2300 "device: string" (optional)
2302 If the stats are for a virtual block device, the name corresponding
2303 to the virtual block device.
2304 "node-name: string" (optional)
2306 The node name of the device. (Since 2.3)
2307 "qdev: string" (optional)
2309 The qdev ID, or if no ID is assigned, the QOM path of the block
2310 device. (since 3.0)
2311 "stats: BlockDeviceStats"
2313 A "BlockDeviceStats" for the device.
2314 "parent: BlockStats" (optional)
2316 This describes the file block device if it has one. Contains
2317 recursively the statistics of the underlying protocol (e.g. the
2318 host file for a qcow2 image). If there is no underlying protocol,
2319 this field is omitted
2320 "backing: BlockStats" (optional)
2322 This describes the backing block device if it has one. (Since 2.0)
2323 Since: 0.14.0
2325 query-blockstats (Command) Query the "BlockStats" for all virtual
2327 block devices.
2328 Arguments:
2330 "query-nodes: boolean" (optional)
2332 If true, the command will query all the block nodes that have a
2333 node name, in a list which will include "parent" information, but
2334 not "backing". If false or omitted, the behavior is as before -
2335 query all the device backends, recursively including their "parent"
2336 and "backing". Filter nodes that were created implicitly are
2337 skipped over in this mode. (Since 2.3)
2338 Returns: A list of "BlockStats" for each virtual block devices.
2340 Since: 0.14.0
2342 Example:
2344 -> { "execute": "query-blockstats" }
2346 <- {
2347 "return":[
2348 {
2349 "device":"ide0-hd0",
2350 "parent":{
2351 "stats":{
2352 "wr_highest_offset":3686448128,
2353 "wr_bytes":9786368,
2354 "wr_operations":751,
2355 "rd_bytes":122567168,
2356 "rd_operations":36772
2357 "wr_total_times_ns":313253456
2358 "rd_total_times_ns":3465673657
2359 "flush_total_times_ns":49653
2360 "flush_operations":61,
2361 "rd_merged":0,
2362 "wr_merged":0,
2363 "idle_time_ns":2953431879,
2364 "account_invalid":true,
2365 "account_failed":false
2366 }
2367 },
2368 "stats":{
2369 "wr_highest_offset":2821110784,
2370 "wr_bytes":9786368,
2371 "wr_operations":692,
2372 "rd_bytes":122739200,
2373 "rd_operations":36604
2374 "flush_operations":51,
2375 "wr_total_times_ns":313253456
2376 "rd_total_times_ns":3465673657
2377 "flush_total_times_ns":49653,
2378 "rd_merged":0,
2379 "wr_merged":0,
2380 "idle_time_ns":2953431879,
2381 "account_invalid":true,
2382 "account_failed":false
2383 },
2384 "qdev": "/machine/unattached/device[23]"
2385 },
2386 {
2387 "device":"ide1-cd0",
2388 "stats":{
2389 "wr_highest_offset":0,
2390 "wr_bytes":0,
2391 "wr_operations":0,
2392 "rd_bytes":0,
2393 "rd_operations":0
2394 "flush_operations":0,
2395 "wr_total_times_ns":0
2396 "rd_total_times_ns":0
2397 "flush_total_times_ns":0,
2398 "rd_merged":0,
2399 "wr_merged":0,
2400 "account_invalid":false,
2401 "account_failed":false
2402 },
2403 "qdev": "/machine/unattached/device[24]"
2404 },
2405 {
2406 "device":"floppy0",
2407 "stats":{
2408 "wr_highest_offset":0,
2409 "wr_bytes":0,
2410 "wr_operations":0,
2411 "rd_bytes":0,
2412 "rd_operations":0
2413 "flush_operations":0,
2414 "wr_total_times_ns":0
2415 "rd_total_times_ns":0
2416 "flush_total_times_ns":0,
2417 "rd_merged":0,
2418 "wr_merged":0,
2419 "account_invalid":false,
2420 "account_failed":false
2421 },
2422 "qdev": "/machine/unattached/device[16]"
2423 },
2424 {
2425 "device":"sd0",
2426 "stats":{
2427 "wr_highest_offset":0,
2428 "wr_bytes":0,
2429 "wr_operations":0,
2430 "rd_bytes":0,
2431 "rd_operations":0
2432 "flush_operations":0,
2433 "wr_total_times_ns":0
2434 "rd_total_times_ns":0
2435 "flush_total_times_ns":0,
2436 "rd_merged":0,
2437 "wr_merged":0,
2438 "account_invalid":false,
2439 "account_failed":false
2440 }
2441 }
2442 ]
2443 }
2444 BlockdevOnError (Enum)
2446 An enumeration of possible behaviors for errors on I/O operations. The
2448 exact meaning depends on whether the I/O was initiated by a guest or by
2449 a block job
2450 Values:
2452 "report"
2454 for guest operations, report the error to the guest; for jobs,
2455 cancel the job
2456 "ignore"
2458 ignore the error, only report a QMP event (BLOCK_IO_ERROR or
2459 BLOCK_JOB_ERROR)
2460 "enospc"
2462 same as "stop" on ENOSPC, same as "report" otherwise.
2463 "stop"
2465 for guest operations, stop the virtual machine; for jobs, pause the
2466 job
2467 "auto"
2469 inherit the error handling policy of the backend (since: 2.7)
2470 Since: 1.3
2472 MirrorSyncMode (Enum)
2474 An enumeration of possible behaviors for the initial synchronization
2476 phase of storage mirroring.
2477 Values:
2479 "top"
2481 copies data in the topmost image to the destination
2482 "full"
2484 copies data from all images to the destination
2485 "none"
2487 only copy data written from now on
2488 "incremental"
2490 only copy data described by the dirty bitmap. Since: 2.4
2491 Since: 1.3
2493 MirrorCopyMode (Enum)
2495 An enumeration whose values tell the mirror block job when to trigger
2497 writes to the target.
2498 Values:
2500 "background"
2502 copy data in background only.
2503 "write-blocking"
2505 when data is written to the source, write it (synchronously) to the
2506 target as well. In addition, data is copied in background just
2507 like in "background" mode.
2508 Since: 3.0
2510 BlockJobInfo (Object)
2512 Information about a long-running block device operation.
2514 Members:
2516 "type: string"
2518 the job type ('stream' for image streaming)
2519 "device: string"
2521 The job identifier. Originally the device name but other values are
2522 allowed since QEMU 2.7
2523 "len: int"
2525 Estimated "offset" value at the completion of the job. This value
2526 can arbitrarily change while the job is running, in both
2527 directions.
2528 "offset: int"
2530 Progress made until now. The unit is arbitrary and the value can
2531 only meaningfully be used for the ratio of "offset" to "len". The
2532 value is monotonically increasing.
2533 "busy: boolean"
2535 false if the job is known to be in a quiescent state, with no
2536 pending I/O. Since 1.3.
2537 "paused: boolean"
2539 whether the job is paused or, if "busy" is true, will pause itself
2540 as soon as possible. Since 1.3.
2541 "speed: int"
2543 the rate limit, bytes per second
2544 "io-status: BlockDeviceIoStatus"
2546 the status of the job (since 1.3)
2547 "ready: boolean"
2549 true if the job may be completed (since 2.2)
2550 "status: JobStatus"
2552 Current job state/status (since 2.12)
2553 "auto-finalize: boolean"
2555 Job will finalize itself when PENDING, moving to the CONCLUDED
2556 state. (since 2.12)
2557 "auto-dismiss: boolean"
2559 Job will dismiss itself when CONCLUDED, moving to the NULL state
2560 and disappearing from the query list. (since 2.12)
2561 "error: string" (optional)
2563 Error information if the job did not complete successfully. Not
2564 set if the job completed successfully. (since 2.12.1)
2565 Since: 1.1
2567 query-block-jobs (Command) Return information about long-running block
2569 device operations.
2570 Returns: a list of "BlockJobInfo" for each active block job
2572 Since: 1.1
2574 block_passwd (Command) This command sets the password of a block
2576 device that has not been open with a password and requires one.
2577 This command is now obsolete and will always return an error since 2.10
2579 Arguments:
2581 "device: string" (optional)
2583 Not documented
2584 "node-name: string" (optional)
2586 Not documented
2587 "password: string"
2589 Not documented
2590 block_resize (Command) Resize a block image while a guest is running.
2592 Either "device" or "node-name" must be set but not both.
2594 Arguments:
2596 "device: string" (optional)
2598 the name of the device to get the image resized
2599 "node-name: string" (optional)
2601 graph node name to get the image resized (Since 2.0)
2602 "size: int"
2604 new image size in bytes
2605 Returns: nothing on success If "device" is not a valid block device,
2607 DeviceNotFound
2608 Since: 0.14.0
2610 Example:
2612 -> { "execute": "block_resize",
2614 "arguments": { "device": "scratch", "size": 1073741824 } }
2615 <- { "return": {} }
2616 NewImageMode (Enum)
2618 An enumeration that tells QEMU how to set the backing file path in a
2620 new image file.
2621 Values:
2623 "existing"
2625 QEMU should look for an existing image file.
2626 "absolute-paths"
2628 QEMU should create a new image with absolute paths for the backing
2629 file. If there is no backing file available, the new image will not
2630 be backed either.
2631 Since: 1.1
2633 BlockdevSnapshotSync (Object)
2635 Either "device" or "node-name" must be set but not both.
2637 Members:
2639 "device: string" (optional)
2641 the name of the device to generate the snapshot from.
2642 "node-name: string" (optional)
2644 graph node name to generate the snapshot from (Since 2.0)
2645 "snapshot-file: string"
2647 the target of the new image. If the file exists, or if it is a
2648 device, the snapshot will be created in the existing file/device.
2649 Otherwise, a new file will be created.
2650 "snapshot-node-name: string" (optional)
2652 the graph node name of the new image (Since 2.0)
2653 "format: string" (optional)
2655 the format of the snapshot image, default is 'qcow2'.
2656 "mode: NewImageMode" (optional)
2658 whether and how QEMU should create a new image, default is
2659 'absolute-paths'.
2660 BlockdevSnapshot (Object)
2662 Members:
2664 "node: string"
2666 device or node name that will have a snapshot created.
2667 "overlay: string"
2669 reference to the existing block device that will become the overlay
2670 of "node", as part of creating the snapshot. It must not have a
2671 current backing file (this can be achieved by passing "backing":
2672 null to blockdev-add).
2673 Since: 2.5
2675 DriveBackup (Object)
2677 Members:
2679 "job-id: string" (optional)
2681 identifier for the newly-created block job. If omitted, the device
2682 name will be used. (Since 2.7)
2683 "device: string"
2685 the device name or node-name of a root node which should be copied.
2686 "target: string"
2688 the target of the new image. If the file exists, or if it is a
2689 device, the existing file/device will be used as the new
2690 destination. If it does not exist, a new file will be created.
2691 "format: string" (optional)
2693 the format of the new destination, default is to probe if "mode" is
2694 'existing', else the format of the source
2695 "sync: MirrorSyncMode"
2697 what parts of the disk image should be copied to the destination
2698 (all the disk, only the sectors allocated in the topmost image,
2699 from a dirty bitmap, or only new I/O).
2700 "mode: NewImageMode" (optional)
2702 whether and how QEMU should create a new image, default is
2703 'absolute-paths'.
2704 "speed: int" (optional)
2706 the maximum speed, in bytes per second
2707 "bitmap: string" (optional)
2709 the name of dirty bitmap if sync is "incremental". Must be present
2710 if sync is "incremental", must NOT be present otherwise. (Since
2711 2.4)
2712 "compress: boolean" (optional)
2714 true to compress data, if the target format supports it. (default:
2715 false) (since 2.8)
2716 "on-source-error: BlockdevOnError" (optional)
2718 the action to take on an error on the source, default 'report'.
2719 'stop' and 'enospc' can only be used if the block device supports
2720 io-status (see BlockInfo).
2721 "on-target-error: BlockdevOnError" (optional)
2723 the action to take on an error on the target, default 'report' (no
2724 limitations, since this applies to a different block device than
2725 "device").
2726 "auto-finalize: boolean" (optional)
2728 When false, this job will wait in a PENDING state after it has
2729 finished its work, waiting for "block-job-finalize". When true,
2730 this job will automatically perform its abort or commit actions.
2731 Defaults to true. (Since 2.12)
2732 "auto-dismiss: boolean" (optional)
2734 When false, this job will wait in a CONCLUDED state after it has
2735 completed ceased all work, and wait for "block-job-dismiss". When
2736 true, this job will automatically disappear from the query list
2737 without user intervention. Defaults to true. (Since 2.12)
2738 Note: "on-source-error" and "on-target-error" only affect background
2740 I/O. If an error occurs during a guest write request, the device's
2741 rerror/werror actions will be used.
2742 Since: 1.6
2744 BlockdevBackup (Object)
2746 Members:
2748 "job-id: string" (optional)
2750 identifier for the newly-created block job. If omitted, the device
2751 name will be used. (Since 2.7)
2752 "device: string"
2754 the device name or node-name of a root node which should be copied.
2755 "target: string"
2757 the device name or node-name of the backup target node.
2758 "sync: MirrorSyncMode"
2760 what parts of the disk image should be copied to the destination
2761 (all the disk, only the sectors allocated in the topmost image, or
2762 only new I/O).
2763 "speed: int" (optional)
2765 the maximum speed, in bytes per second. The default is 0, for
2766 unlimited.
2767 "compress: boolean" (optional)
2769 true to compress data, if the target format supports it. (default:
2770 false) (since 2.8)
2771 "on-source-error: BlockdevOnError" (optional)
2773 the action to take on an error on the source, default 'report'.
2774 'stop' and 'enospc' can only be used if the block device supports
2775 io-status (see BlockInfo).
2776 "on-target-error: BlockdevOnError" (optional)
2778 the action to take on an error on the target, default 'report' (no
2779 limitations, since this applies to a different block device than
2780 "device").
2781 "auto-finalize: boolean" (optional)
2783 When false, this job will wait in a PENDING state after it has
2784 finished its work, waiting for "block-job-finalize". When true,
2785 this job will automatically perform its abort or commit actions.
2786 Defaults to true. (Since 2.12)
2787 "auto-dismiss: boolean" (optional)
2789 When false, this job will wait in a CONCLUDED state after it has
2790 completed ceased all work, and wait for "block-job-dismiss". When
2791 true, this job will automatically disappear from the query list
2792 without user intervention. Defaults to true. (Since 2.12)
2793 Note: "on-source-error" and "on-target-error" only affect background
2795 I/O. If an error occurs during a guest write request, the device's
2796 rerror/werror actions will be used.
2797 Since: 2.3
2799 blockdev-snapshot-sync (Command) Generates a synchronous snapshot of a
2801 block device.
2802 For the arguments, see the documentation of BlockdevSnapshotSync.
2804 Returns: nothing on success If "device" is not a valid block device,
2806 DeviceNotFound
2807 Since: 0.14.0
2809 Example:
2811 -> { "execute": "blockdev-snapshot-sync",
2813 "arguments": { "device": "ide-hd0",
2814 "snapshot-file":
2815 "/some/place/my-image",
2816 "format": "qcow2" } }
2817 <- { "return": {} }
2818 blockdev-snapshot (Command) Generates a snapshot of a block device.
2820 Create a snapshot, by installing 'node' as the backing image of
2822 'overlay'. Additionally, if 'node' is associated with a block device,
2823 the block device changes to using 'overlay' as its new active image.
2824 For the arguments, see the documentation of BlockdevSnapshot.
2826 Since: 2.5
2828 Example:
2830 -> { "execute": "blockdev-add",
2832 "arguments": { "driver": "qcow2",
2833 "node-name": "node1534",
2834 "file": { "driver": "file",
2835 "filename": "hd1.qcow2" },
2836 "backing": null } }
2837 <- { "return": {} }
2839 -> { "execute": "blockdev-snapshot",
2841 "arguments": { "node": "ide-hd0",
2842 "overlay": "node1534" } }
2843 <- { "return": {} }
2844 change-backing-file (Command) Change the backing file in the image
2846 file metadata. This does not cause QEMU to reopen the image file to
2847 reparse the backing filename (it may, however, perform a reopen to
2848 change permissions from r/o -> r/w -> r/o, if needed). The new backing
2849 file string is written into the image file metadata, and the QEMU
2850 internal strings are updated.
2851 Arguments:
2853 "image-node-name: string"
2855 The name of the block driver state node of the image to modify. The
2856 "device" argument is used to verify "image-node-name" is in the
2857 chain described by "device".
2858 "device: string"
2860 The device name or node-name of the root node that owns image-node-
2861 name.
2862 "backing-file: string"
2864 The string to write as the backing file. This string is not
2865 validated, so care should be taken when specifying the string or
2866 the image chain may not be able to be reopened again.
2867 Returns: Nothing on success
2869 If "device" does not exist or cannot be determined, DeviceNotFound
2871 Since: 2.1
2873 block-commit (Command) Live commit of data from overlay image nodes
2875 into backing nodes - i.e., writes data between 'top' and 'base' into
2876 'base'.
2877 Arguments:
2879 "job-id: string" (optional)
2881 identifier for the newly-created block job. If omitted, the device
2882 name will be used. (Since 2.7)
2883 "device: string"
2885 the device name or node-name of a root node
2886 "base: string" (optional)
2888 The file name of the backing image to write data into. If not
2889 specified, this is the deepest backing image.
2890 "top: string" (optional)
2892 The file name of the backing image within the image chain, which
2893 contains the topmost data to be committed down. If not specified,
2894 this is the active layer.
2895 "backing-file: string" (optional)
2897 The backing file string to write into the overlay image of 'top'.
2898 If 'top' is the active layer, specifying a backing file string is
2899 an error. This filename is not validated.
2900 If a pathname string is such that it cannot be resolved by QEMU,
2902 that means that subsequent QMP or HMP commands must use node-names
2903 for the image in question, as filename lookup methods will fail.
2904 If not specified, QEMU will automatically determine the backing
2906 file string to use, or error out if there is no obvious choice.
2907 Care should be taken when specifying the string, to specify a valid
2908 filename or protocol. (Since 2.1)
2909 If top == base, that is an error. If top == active, the job will
2911 not be completed by itself, user needs to complete the job with the
2912 block-job-complete command after getting the ready event. (Since
2913 2.0)
2914 If the base image is smaller than top, then the base image will be
2916 resized to be the same size as top. If top is smaller than the
2917 base image, the base will not be truncated. If you want the base
2918 image size to match the size of the smaller top, you can safely
2919 truncate it yourself once the commit operation successfully
2920 completes.
2921 "speed: int" (optional)
2923 the maximum speed, in bytes per second
2924 "filter-node-name: string" (optional)
2926 the node name that should be assigned to the filter driver that the
2927 commit job inserts into the graph above "top". If this option is
2928 not given, a node name is autogenerated. (Since: 2.9)
2929 Returns: Nothing on success If commit or stream is already active on
2931 this device, DeviceInUse If "device" does not exist, DeviceNotFound If
2932 image commit is not supported by this device, NotSupported If "base" or
2933 "top" is invalid, a generic error is returned If "speed" is invalid,
2934 InvalidParameter
2935 Since: 1.3
2937 Example:
2939 -> { "execute": "block-commit",
2941 "arguments": { "device": "virtio0",
2942 "top": "/tmp/snap1.qcow2" } }
2943 <- { "return": {} }
2944 drive-backup (Command) Start a point-in-time copy of a block device to
2946 a new destination. The status of ongoing drive-backup operations can
2947 be checked with query-block-jobs where the BlockJobInfo.type field has
2948 the value 'backup'. The operation can be stopped before it has
2949 completed using the block-job-cancel command.
2950 Arguments: the members of "DriveBackup"
2952 Returns: nothing on success If "device" is not a valid block device,
2954 GenericError
2955 Since: 1.6
2957 Example:
2959 -> { "execute": "drive-backup",
2961 "arguments": { "device": "drive0",
2962 "sync": "full",
2963 "target": "backup.img" } }
2964 <- { "return": {} }
2965 blockdev-backup (Command) Start a point-in-time copy of a block device
2967 to a new destination. The status of ongoing blockdev-backup operations
2968 can be checked with query-block-jobs where the BlockJobInfo.type field
2969 has the value 'backup'. The operation can be stopped before it has
2970 completed using the block-job-cancel command.
2971 Arguments: the members of "BlockdevBackup"
2973 Returns: nothing on success If "device" is not a valid block device,
2975 DeviceNotFound
2976 Since: 2.3
2978 Example:
2980 -> { "execute": "blockdev-backup",
2982 "arguments": { "device": "src-id",
2983 "sync": "full",
2984 "target": "tgt-id" } }
2985 <- { "return": {} }
2986 query-named-block-nodes (Command) Get the named block driver list
2988 Returns: the list of BlockDeviceInfo
2990 Since: 2.0
2992 Example:
2994 -> { "execute": "query-named-block-nodes" }
2996 <- { "return": [ { "ro":false,
2997 "drv":"qcow2",
2998 "encrypted":false,
2999 "file":"disks/test.qcow2",
3000 "node-name": "my-node",
3001 "backing_file_depth":1,
3002 "bps":1000000,
3003 "bps_rd":0,
3004 "bps_wr":0,
3005 "iops":1000000,
3006 "iops_rd":0,
3007 "iops_wr":0,
3008 "bps_max": 8000000,
3009 "bps_rd_max": 0,
3010 "bps_wr_max": 0,
3011 "iops_max": 0,
3012 "iops_rd_max": 0,
3013 "iops_wr_max": 0,
3014 "iops_size": 0,
3015 "write_threshold": 0,
3016 "image":{
3017 "filename":"disks/test.qcow2",
3018 "format":"qcow2",
3019 "virtual-size":2048000,
3020 "backing_file":"base.qcow2",
3021 "full-backing-filename":"disks/base.qcow2",
3022 "backing-filename-format":"qcow2",
3023 "snapshots":[
3024 {
3025 "id": "1",
3026 "name": "snapshot1",
3027 "vm-state-size": 0,
3028 "date-sec": 10000200,
3029 "date-nsec": 12,
3030 "vm-clock-sec": 206,
3031 "vm-clock-nsec": 30
3032 }
3033 ],
3034 "backing-image":{
3035 "filename":"disks/base.qcow2",
3036 "format":"qcow2",
3037 "virtual-size":2048000
3038 }
3039 } } ] }
3040 drive-mirror (Command) Start mirroring a block device's writes to a
3042 new destination. target specifies the target of the new image. If the
3043 file exists, or if it is a device, it will be used as the new
3044 destination for writes. If it does not exist, a new file will be
3045 created. format specifies the format of the mirror image, default is to
3046 probe if mode='existing', else the format of the source.
3047 Arguments: the members of "DriveMirror"
3049 Returns: nothing on success If "device" is not a valid block device,
3051 GenericError
3052 Since: 1.3
3054 Example:
3056 -> { "execute": "drive-mirror",
3058 "arguments": { "device": "ide-hd0",
3059 "target": "/some/place/my-image",
3060 "sync": "full",
3061 "format": "qcow2" } }
3062 <- { "return": {} }
3063 DriveMirror (Object)
3065 A set of parameters describing drive mirror setup.
3067 Members:
3069 "job-id: string" (optional)
3071 identifier for the newly-created block job. If omitted, the device
3072 name will be used. (Since 2.7)
3073 "device: string"
3075 the device name or node-name of a root node whose writes should be
3076 mirrored.
3077 "target: string"
3079 the target of the new image. If the file exists, or if it is a
3080 device, the existing file/device will be used as the new
3081 destination. If it does not exist, a new file will be created.
3082 "format: string" (optional)
3084 the format of the new destination, default is to probe if "mode" is
3085 'existing', else the format of the source
3086 "node-name: string" (optional)
3088 the new block driver state node name in the graph (Since 2.1)
3089 "replaces: string" (optional)
3091 with sync=full graph node name to be replaced by the new image when
3092 a whole image copy is done. This can be used to repair broken
3093 Quorum files. (Since 2.1)
3094 "mode: NewImageMode" (optional)
3096 whether and how QEMU should create a new image, default is
3097 'absolute-paths'.
3098 "speed: int" (optional)
3100 the maximum speed, in bytes per second
3101 "sync: MirrorSyncMode"
3103 what parts of the disk image should be copied to the destination
3104 (all the disk, only the sectors allocated in the topmost image, or
3105 only new I/O).
3106 "granularity: int" (optional)
3108 granularity of the dirty bitmap, default is 64K if the image format
3109 doesn't have clusters, 4K if the clusters are smaller than that,
3110 else the cluster size. Must be a power of 2 between 512 and 64M
3111 (since 1.4).
3112 "buf-size: int" (optional)
3114 maximum amount of data in flight from source to target (since 1.4).
3115 "on-source-error: BlockdevOnError" (optional)
3117 the action to take on an error on the source, default 'report'.
3118 'stop' and 'enospc' can only be used if the block device supports
3119 io-status (see BlockInfo).
3120 "on-target-error: BlockdevOnError" (optional)
3122 the action to take on an error on the target, default 'report' (no
3123 limitations, since this applies to a different block device than
3124 "device").
3125 "unmap: boolean" (optional)
3127 Whether to try to unmap target sectors where source has only zero.
3128 If true, and target unallocated sectors will read as zero, target
3129 image sectors will be unmapped; otherwise, zeroes will be written.
3130 Both will result in identical contents. Default is true. (Since
3131 2.4)
3132 "copy-mode: MirrorCopyMode" (optional)
3134 when to copy data to the destination; defaults to 'background'
3135 (Since: 3.0)
3136 Since: 1.3
3138 BlockDirtyBitmap (Object)
3140 Members:
3142 "node: string"
3144 name of device/node which the bitmap is tracking
3145 "name: string"
3147 name of the dirty bitmap
3148 Since: 2.4
3150 BlockDirtyBitmapAdd (Object)
3152 Members:
3154 "node: string"
3156 name of device/node which the bitmap is tracking
3157 "name: string"
3159 name of the dirty bitmap
3160 "granularity: int" (optional)
3162 the bitmap granularity, default is 64k for block-dirty-bitmap-add
3163 "persistent: boolean" (optional)
3165 the bitmap is persistent, i.e. it will be saved to the
3166 corresponding block device image file on its close. For now only
3167 Qcow2 disks support persistent bitmaps. Default is false for block-
3168 dirty-bitmap-add. (Since: 2.10)
3169 "autoload: boolean" (optional)
3171 ignored and deprecated since 2.12. Currently, all dirty tracking
3172 bitmaps are loaded from Qcow2 on open.
3173 "x-disabled: boolean" (optional)
3175 the bitmap is created in the disabled state, which means that it
3176 will not track drive changes. The bitmap may be enabled with
3177 x-block-dirty-bitmap-enable. Default is false. (Since: 3.0)
3178 Since: 2.4
3180 BlockDirtyBitmapMerge (Object)
3182 Members:
3184 "node: string"
3186 name of device/node which the bitmap is tracking
3187 "dst_name: string"
3189 name of the destination dirty bitmap
3190 "src_name: string"
3192 name of the source dirty bitmap
3193 Since: 3.0
3195 block-dirty-bitmap-add (Command) Create a dirty bitmap with a name on
3197 the node, and start tracking the writes.
3198 Returns: nothing on success If "node" is not a valid block device or
3200 node, DeviceNotFound If "name" is already taken, GenericError with an
3201 explanation
3202 Since: 2.4
3204 Example:
3206 -> { "execute": "block-dirty-bitmap-add",
3208 "arguments": { "node": "drive0", "name": "bitmap0" } }
3209 <- { "return": {} }
3210 block-dirty-bitmap-remove (Command) Stop write tracking and remove the
3212 dirty bitmap that was created with block-dirty-bitmap-add. If the
3213 bitmap is persistent, remove it from its storage too.
3214 Returns: nothing on success If "node" is not a valid block device or
3216 node, DeviceNotFound If "name" is not found, GenericError with an
3217 explanation if "name" is frozen by an operation, GenericError
3218 Since: 2.4
3220 Example:
3222 -> { "execute": "block-dirty-bitmap-remove",
3224 "arguments": { "node": "drive0", "name": "bitmap0" } }
3225 <- { "return": {} }
3226 block-dirty-bitmap-clear (Command) Clear (reset) a dirty bitmap on the
3228 device, so that an incremental backup from this point in time forward
3229 will only backup clusters modified after this clear operation.
3230 Returns: nothing on success If "node" is not a valid block device,
3232 DeviceNotFound If "name" is not found, GenericError with an explanation
3233 Since: 2.4
3235 Example:
3237 -> { "execute": "block-dirty-bitmap-clear",
3239 "arguments": { "node": "drive0", "name": "bitmap0" } }
3240 <- { "return": {} }
3241 x-block-dirty-bitmap-enable (Command) Enables a dirty bitmap so that
3243 it will begin tracking disk changes.
3244 Returns: nothing on success If "node" is not a valid block device,
3246 DeviceNotFound If "name" is not found, GenericError with an explanation
3247 Since: 3.0
3249 Example:
3251 -> { "execute": "x-block-dirty-bitmap-enable",
3253 "arguments": { "node": "drive0", "name": "bitmap0" } }
3254 <- { "return": {} }
3255 x-block-dirty-bitmap-disable (Command) Disables a dirty bitmap so that
3257 it will stop tracking disk changes.
3258 Returns: nothing on success If "node" is not a valid block device,
3260 DeviceNotFound If "name" is not found, GenericError with an explanation
3261 Since: 3.0
3263 Example:
3265 -> { "execute": "x-block-dirty-bitmap-disable",
3267 "arguments": { "node": "drive0", "name": "bitmap0" } }
3268 <- { "return": {} }
3269 x-block-dirty-bitmap-merge (Command) Merge "src_name" dirty bitmap to
3271 "dst_name" dirty bitmap. "src_name" dirty bitmap is unchanged. On
3272 error, "dst_name" is unchanged.
3273 Returns: nothing on success If "node" is not a valid block device,
3275 DeviceNotFound If "dst_name" or "src_name" is not found, GenericError
3276 If bitmaps has different sizes or granularities, GenericError
3277 Since: 3.0
3279 Example:
3281 -> { "execute": "x-block-dirty-bitmap-merge",
3283 "arguments": { "node": "drive0", "dst_name": "bitmap0",
3284 "src_name": "bitmap1" } }
3285 <- { "return": {} }
3286 BlockDirtyBitmapSha256 (Object)
3288 SHA256 hash of dirty bitmap data
3290 Members:
3292 "sha256: string"
3294 ASCII representation of SHA256 bitmap hash
3295 Since: 2.10
3297 x-debug-block-dirty-bitmap-sha256 (Command) Get bitmap SHA256
3299 Returns: BlockDirtyBitmapSha256 on success If "node" is not a valid
3301 block device, DeviceNotFound If "name" is not found or if hashing has
3302 failed, GenericError with an explanation
3303 Since: 2.10
3305 blockdev-mirror (Command) Start mirroring a block device's writes to a
3307 new destination.
3308 Arguments:
3310 "job-id: string" (optional)
3312 identifier for the newly-created block job. If omitted, the device
3313 name will be used. (Since 2.7)
3314 "device: string"
3316 The device name or node-name of a root node whose writes should be
3317 mirrored.
3318 "target: string"
3320 the id or node-name of the block device to mirror to. This mustn't
3321 be attached to guest.
3322 "replaces: string" (optional)
3324 with sync=full graph node name to be replaced by the new image when
3325 a whole image copy is done. This can be used to repair broken
3326 Quorum files.
3327 "speed: int" (optional)
3329 the maximum speed, in bytes per second
3330 "sync: MirrorSyncMode"
3332 what parts of the disk image should be copied to the destination
3333 (all the disk, only the sectors allocated in the topmost image, or
3334 only new I/O).
3335 "granularity: int" (optional)
3337 granularity of the dirty bitmap, default is 64K if the image format
3338 doesn't have clusters, 4K if the clusters are smaller than that,
3339 else the cluster size. Must be a power of 2 between 512 and 64M
3340 "buf-size: int" (optional)
3342 maximum amount of data in flight from source to target
3343 "on-source-error: BlockdevOnError" (optional)
3345 the action to take on an error on the source, default 'report'.
3346 'stop' and 'enospc' can only be used if the block device supports
3347 io-status (see BlockInfo).
3348 "on-target-error: BlockdevOnError" (optional)
3350 the action to take on an error on the target, default 'report' (no
3351 limitations, since this applies to a different block device than
3352 "device").
3353 "filter-node-name: string" (optional)
3355 the node name that should be assigned to the filter driver that the
3356 mirror job inserts into the graph above "device". If this option is
3357 not given, a node name is autogenerated. (Since: 2.9)
3358 "copy-mode: MirrorCopyMode" (optional)
3360 when to copy data to the destination; defaults to 'background'
3361 (Since: 3.0)
3362 Returns: nothing on success.
3364 Since: 2.6
3366 Example:
3368 -> { "execute": "blockdev-mirror",
3370 "arguments": { "device": "ide-hd0",
3371 "target": "target0",
3372 "sync": "full" } }
3373 <- { "return": {} }
3374 block_set_io_throttle (Command) Change I/O throttle limits for a block
3376 drive.
3377 Since QEMU 2.4, each device with I/O limits is member of a throttle
3379 group.
3380 If two or more devices are members of the same group, the limits will
3382 apply to the combined I/O of the whole group in a round-robin fashion.
3383 Therefore, setting new I/O limits to a device will affect the whole
3384 group.
3385 The name of the group can be specified using the 'group' parameter. If
3387 the parameter is unset, it is assumed to be the current group of that
3388 device. If it's not in any group yet, the name of the device will be
3389 used as the name for its group.
3390 The 'group' parameter can also be used to move a device to a different
3392 group. In this case the limits specified in the parameters will be
3393 applied to the new group only.
3394 I/O limits can be disabled by setting all of them to 0. In this case
3396 the device will be removed from its group and the rest of its members
3397 will not be affected. The 'group' parameter is ignored.
3398 Arguments: the members of "BlockIOThrottle"
3400 Returns: Nothing on success If "device" is not a valid block device,
3402 DeviceNotFound
3403 Since: 1.1
3405 Example:
3407 -> { "execute": "block_set_io_throttle",
3409 "arguments": { "id": "virtio-blk-pci0/virtio-backend",
3410 "bps": 0,
3411 "bps_rd": 0,
3412 "bps_wr": 0,
3413 "iops": 512,
3414 "iops_rd": 0,
3415 "iops_wr": 0,
3416 "bps_max": 0,
3417 "bps_rd_max": 0,
3418 "bps_wr_max": 0,
3419 "iops_max": 0,
3420 "iops_rd_max": 0,
3421 "iops_wr_max": 0,
3422 "bps_max_length": 0,
3423 "iops_size": 0 } }
3424 <- { "return": {} }
3425 -> { "execute": "block_set_io_throttle",
3427 "arguments": { "id": "ide0-1-0",
3428 "bps": 1000000,
3429 "bps_rd": 0,
3430 "bps_wr": 0,
3431 "iops": 0,
3432 "iops_rd": 0,
3433 "iops_wr": 0,
3434 "bps_max": 8000000,
3435 "bps_rd_max": 0,
3436 "bps_wr_max": 0,
3437 "iops_max": 0,
3438 "iops_rd_max": 0,
3439 "iops_wr_max": 0,
3440 "bps_max_length": 60,
3441 "iops_size": 0 } }
3442 <- { "return": {} }
3443 BlockIOThrottle (Object)
3445 A set of parameters describing block throttling.
3447 Members:
3449 "device: string" (optional)
3451 Block device name (deprecated, use "id" instead)
3452 "id: string" (optional)
3454 The name or QOM path of the guest device (since: 2.8)
3455 "bps: int"
3457 total throughput limit in bytes per second
3458 "bps_rd: int"
3460 read throughput limit in bytes per second
3461 "bps_wr: int"
3463 write throughput limit in bytes per second
3464 "iops: int"
3466 total I/O operations per second
3467 "iops_rd: int"
3469 read I/O operations per second
3470 "iops_wr: int"
3472 write I/O operations per second
3473 "bps_max: int" (optional)
3475 total throughput limit during bursts, in bytes (Since 1.7)
3476 "bps_rd_max: int" (optional)
3478 read throughput limit during bursts, in bytes (Since 1.7)
3479 "bps_wr_max: int" (optional)
3481 write throughput limit during bursts, in bytes (Since 1.7)
3482 "iops_max: int" (optional)
3484 total I/O operations per second during bursts, in bytes (Since 1.7)
3485 "iops_rd_max: int" (optional)
3487 read I/O operations per second during bursts, in bytes (Since 1.7)
3488 "iops_wr_max: int" (optional)
3490 write I/O operations per second during bursts, in bytes (Since 1.7)
3491 "bps_max_length: int" (optional)
3493 maximum length of the "bps_max" burst period, in seconds. It must
3494 only be set if "bps_max" is set as well. Defaults to 1. (Since
3495 2.6)
3496 "bps_rd_max_length: int" (optional)
3498 maximum length of the "bps_rd_max" burst period, in seconds. It
3499 must only be set if "bps_rd_max" is set as well. Defaults to 1.
3500 (Since 2.6)
3501 "bps_wr_max_length: int" (optional)
3503 maximum length of the "bps_wr_max" burst period, in seconds. It
3504 must only be set if "bps_wr_max" is set as well. Defaults to 1.
3505 (Since 2.6)
3506 "iops_max_length: int" (optional)
3508 maximum length of the "iops" burst period, in seconds. It must only
3509 be set if "iops_max" is set as well. Defaults to 1. (Since 2.6)
3510 "iops_rd_max_length: int" (optional)
3512 maximum length of the "iops_rd_max" burst period, in seconds. It
3513 must only be set if "iops_rd_max" is set as well. Defaults to 1.
3514 (Since 2.6)
3515 "iops_wr_max_length: int" (optional)
3517 maximum length of the "iops_wr_max" burst period, in seconds. It
3518 must only be set if "iops_wr_max" is set as well. Defaults to 1.
3519 (Since 2.6)
3520 "iops_size: int" (optional)
3522 an I/O size in bytes (Since 1.7)
3523 "group: string" (optional)
3525 throttle group name (Since 2.4)
3526 Since: 1.1
3528 ThrottleLimits (Object)
3530 Limit parameters for throttling. Since some limit combinations are
3532 illegal, limits should always be set in one transaction. All fields are
3533 optional. When setting limits, if a field is missing the current value
3534 is not changed.
3535 Members:
3537 "iops-total: int" (optional)
3539 limit total I/O operations per second
3540 "iops-total-max: int" (optional)
3542 I/O operations burst
3543 "iops-total-max-length: int" (optional)
3545 length of the iops-total-max burst period, in seconds It must only
3546 be set if "iops-total-max" is set as well.
3547 "iops-read: int" (optional)
3549 limit read operations per second
3550 "iops-read-max: int" (optional)
3552 I/O operations read burst
3553 "iops-read-max-length: int" (optional)
3555 length of the iops-read-max burst period, in seconds It must only
3556 be set if "iops-read-max" is set as well.
3557 "iops-write: int" (optional)
3559 limit write operations per second
3560 "iops-write-max: int" (optional)
3562 I/O operations write burst
3563 "iops-write-max-length: int" (optional)
3565 length of the iops-write-max burst period, in seconds It must only
3566 be set if "iops-write-max" is set as well.
3567 "bps-total: int" (optional)
3569 limit total bytes per second
3570 "bps-total-max: int" (optional)
3572 total bytes burst
3573 "bps-total-max-length: int" (optional)
3575 length of the bps-total-max burst period, in seconds. It must only
3576 be set if "bps-total-max" is set as well.
3577 "bps-read: int" (optional)
3579 limit read bytes per second
3580 "bps-read-max: int" (optional)
3582 total bytes read burst
3583 "bps-read-max-length: int" (optional)
3585 length of the bps-read-max burst period, in seconds It must only be
3586 set if "bps-read-max" is set as well.
3587 "bps-write: int" (optional)
3589 limit write bytes per second
3590 "bps-write-max: int" (optional)
3592 total bytes write burst
3593 "bps-write-max-length: int" (optional)
3595 length of the bps-write-max burst period, in seconds It must only
3596 be set if "bps-write-max" is set as well.
3597 "iops-size: int" (optional)
3599 when limiting by iops max size of an I/O in bytes
3600 Since: 2.11
3602 block-stream (Command) Copy data from a backing file into a block
3604 device.
3605 The block streaming operation is performed in the background until the
3607 entire backing file has been copied. This command returns immediately
3608 once streaming has started. The status of ongoing block streaming
3609 operations can be checked with query-block-jobs. The operation can be
3610 stopped before it has completed using the block-job-cancel command.
3611 The node that receives the data is called the top image, can be located
3613 in any part of the chain (but always above the base image; see below)
3614 and can be specified using its device or node name. Earlier qemu
3615 versions only allowed 'device' to name the top level node; presence of
3616 the 'base-node' parameter during introspection can be used as a witness
3617 of the enhanced semantics of 'device'.
3618 If a base file is specified then sectors are not copied from that base
3620 file and its backing chain. When streaming completes the image file
3621 will have the base file as its backing file. This can be used to
3622 stream a subset of the backing file chain instead of flattening the
3623 entire image.
3624 On successful completion the image file is updated to drop the backing
3626 file and the BLOCK_JOB_COMPLETED event is emitted.
3627 Arguments:
3629 "job-id: string" (optional)
3631 identifier for the newly-created block job. If omitted, the device
3632 name will be used. (Since 2.7)
3633 "device: string"
3635 the device or node name of the top image
3636 "base: string" (optional)
3638 the common backing file name. It cannot be set if "base-node" is
3639 also set.
3640 "base-node: string" (optional)
3642 the node name of the backing file. It cannot be set if "base" is
3643 also set. (Since 2.8)
3644 "backing-file: string" (optional)
3646 The backing file string to write into the top image. This filename
3647 is not validated.
3648 If a pathname string is such that it cannot be resolved by QEMU,
3650 that means that subsequent QMP or HMP commands must use node-names
3651 for the image in question, as filename lookup methods will fail.
3652 If not specified, QEMU will automatically determine the backing
3654 file string to use, or error out if there is no obvious choice.
3655 Care should be taken when specifying the string, to specify a valid
3656 filename or protocol. (Since 2.1)
3657 "speed: int" (optional)
3659 the maximum speed, in bytes per second
3660 "on-error: BlockdevOnError" (optional)
3662 the action to take on an error (default report). 'stop' and
3663 'enospc' can only be used if the block device supports io-status
3664 (see BlockInfo). Since 1.3.
3665 Returns: Nothing on success. If "device" does not exist,
3667 DeviceNotFound.
3668 Since: 1.1
3670 Example:
3672 -> { "execute": "block-stream",
3674 "arguments": { "device": "virtio0",
3675 "base": "/tmp/master.qcow2" } }
3676 <- { "return": {} }
3677 block-job-set-speed (Command) Set maximum speed for a background block
3679 operation.
3680 This command can only be issued when there is an active block job.
3682 Throttling can be disabled by setting the speed to 0.
3684 Arguments:
3686 "device: string"
3688 The job identifier. This used to be a device name (hence the name
3689 of the parameter), but since QEMU 2.7 it can have other values.
3690 "speed: int"
3692 the maximum speed, in bytes per second, or 0 for unlimited.
3693 Defaults to 0.
3694 Returns: Nothing on success If no background operation is active on
3696 this device, DeviceNotActive
3697 Since: 1.1
3699 block-job-cancel (Command) Stop an active background block operation.
3701 This command returns immediately after marking the active background
3703 block operation for cancellation. It is an error to call this command
3704 if no operation is in progress.
3705 The operation will cancel as soon as possible and then emit the
3707 BLOCK_JOB_CANCELLED event. Before that happens the job is still
3708 visible when enumerated using query-block-jobs.
3709 Note that if you issue 'block-job-cancel' after 'drive-mirror' has
3711 indicated (via the event BLOCK_JOB_READY) that the source and
3712 destination are synchronized, then the event triggered by this command
3713 changes to BLOCK_JOB_COMPLETED, to indicate that the mirroring has
3714 ended and the destination now has a point-in-time copy tied to the time
3715 of the cancellation.
3716 For streaming, the image file retains its backing file unless the
3718 streaming operation happens to complete just as it is being cancelled.
3719 A new streaming operation can be started at a later time to finish
3720 copying all data from the backing file.
3721 Arguments:
3723 "device: string"
3725 The job identifier. This used to be a device name (hence the name
3726 of the parameter), but since QEMU 2.7 it can have other values.
3727 "force: boolean" (optional)
3729 If true, and the job has already emitted the event BLOCK_JOB_READY,
3730 abandon the job immediately (even if it is paused) instead of
3731 waiting for the destination to complete its final synchronization
3732 (since 1.3)
3733 Returns: Nothing on success If no background operation is active on
3735 this device, DeviceNotActive
3736 Since: 1.1
3738 block-job-pause (Command) Pause an active background block operation.
3740 This command returns immediately after marking the active background
3742 block operation for pausing. It is an error to call this command if no
3743 operation is in progress or if the job is already paused.
3744 The operation will pause as soon as possible. No event is emitted when
3746 the operation is actually paused. Cancelling a paused job
3747 automatically resumes it.
3748 Arguments:
3750 "device: string"
3752 The job identifier. This used to be a device name (hence the name
3753 of the parameter), but since QEMU 2.7 it can have other values.
3754 Returns: Nothing on success If no background operation is active on
3756 this device, DeviceNotActive
3757 Since: 1.3
3759 block-job-resume (Command) Resume an active background block
3761 operation.
3762 This command returns immediately after resuming a paused background
3764 block operation. It is an error to call this command if no operation
3765 is in progress or if the job is not paused.
3766 This command also clears the error status of the job.
3768 Arguments:
3770 "device: string"
3772 The job identifier. This used to be a device name (hence the name
3773 of the parameter), but since QEMU 2.7 it can have other values.
3774 Returns: Nothing on success If no background operation is active on
3776 this device, DeviceNotActive
3777 Since: 1.3
3779 block-job-complete (Command) Manually trigger completion of an active
3781 background block operation. This is supported for drive mirroring,
3782 where it also switches the device to write to the target path only.
3783 The ability to complete is signaled with a BLOCK_JOB_READY event.
3784 This command completes an active background block operation
3786 synchronously. The ordering of this command's return with the
3787 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
3788 occurs during the processing of this command: 1) the command itself
3789 will fail; 2) the error will be processed according to the
3790 rerror/werror arguments that were specified when starting the
3791 operation.
3792 A cancelled or paused job cannot be completed.
3794 Arguments:
3796 "device: string"
3798 The job identifier. This used to be a device name (hence the name
3799 of the parameter), but since QEMU 2.7 it can have other values.
3800 Returns: Nothing on success If no background operation is active on
3802 this device, DeviceNotActive
3803 Since: 1.3
3805 block-job-dismiss (Command) For jobs that have already concluded,
3807 remove them from the block-job-query list. This command only needs to
3808 be run for jobs which were started with QEMU 2.12+ job lifetime
3809 management semantics.
3810 This command will refuse to operate on any job that has not yet reached
3812 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
3813 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
3814 still need to be used as appropriate.
3815 Arguments:
3817 "id: string"
3819 The job identifier.
3820 Returns: Nothing on success
3822 Since: 2.12
3824 block-job-finalize (Command) Once a job that has manual=true reaches
3826 the pending state, it can be instructed to finalize any graph changes
3827 and do any necessary cleanup via this command. For jobs in a
3828 transaction, instructing one job to finalize will force ALL jobs in the
3829 transaction to finalize, so it is only necessary to instruct a single
3830 member job to finalize.
3831 Arguments:
3833 "id: string"
3835 The job identifier.
3836 Returns: Nothing on success
3838 Since: 2.12
3840 BlockdevDiscardOptions (Enum)
3842 Determines how to handle discard requests.
3844 Values:
3846 "ignore"
3848 Ignore the request
3849 "unmap"
3851 Forward as an unmap request
3852 Since: 2.9
3854 BlockdevDetectZeroesOptions (Enum)
3856 Describes the operation mode for the automatic conversion of plain zero
3858 writes by the OS to driver specific optimized zero write commands.
3859 Values:
3861 "off"
3863 Disabled (default)
3864 "on"
3866 Enabled
3867 "unmap"
3869 Enabled and even try to unmap blocks if possible. This requires
3870 also that "BlockdevDiscardOptions" is set to unmap for this device.
3871 Since: 2.1
3873 BlockdevAioOptions (Enum)
3875 Selects the AIO backend to handle I/O requests
3877 Values:
3879 "threads"
3881 Use qemu's thread pool
3882 "native"
3884 Use native AIO backend (only Linux and Windows)
3885 Since: 2.9
3887 BlockdevCacheOptions (Object)
3889 Includes cache-related options for block devices
3891 Members:
3893 "direct: boolean" (optional)
3895 enables use of O_DIRECT (bypass the host page cache; default:
3896 false)
3897 "no-flush: boolean" (optional)
3899 ignore any flush requests for the device (default: false)
3900 Since: 2.9
3902 BlockdevDriver (Enum)
3904 Drivers that are supported in block device operations.
3906 Values:
3908 "vxhs"
3910 Since 2.10
3911 "throttle"
3913 Since 2.11
3914 "nvme"
3916 Since 2.12
3917 "copy-on-read"
3919 Since 3.0
3920 "blklogwrites"
3922 Since 3.0
3923 "blkdebug"
3925 Not documented
3926 "blkverify"
3928 Not documented
3929 "bochs"
3931 Not documented
3932 "cloop"
3934 Not documented
3935 "dmg"
3937 Not documented
3938 "file"
3940 Not documented
3941 "ftp"
3943 Not documented
3944 "ftps"
3946 Not documented
3947 "gluster"
3949 Not documented
3950 "host_cdrom"
3952 Not documented
3953 "host_device"
3955 Not documented
3956 "http"
3958 Not documented
3959 "https"
3961 Not documented
3962 "iscsi"
3964 Not documented
3965 "luks"
3967 Not documented
3968 "nbd"
3970 Not documented
3971 "nfs"
3973 Not documented
3974 "null-aio"
3976 Not documented
3977 "null-co"
3979 Not documented
3980 "parallels"
3982 Not documented
3983 "qcow"
3985 Not documented
3986 "qcow2"
3988 Not documented
3989 "qed"
3991 Not documented
3992 "quorum"
3994 Not documented
3995 "raw"
3997 Not documented
3998 "rbd"
4000 Not documented
4001 "replication"
4003 Not documented
4004 "sheepdog"
4006 Not documented
4007 "ssh"
4009 Not documented
4010 "vdi"
4012 Not documented
4013 "vhdx"
4015 Not documented
4016 "vmdk"
4018 Not documented
4019 "vpc"
4021 Not documented
4022 "vvfat"
4024 Not documented
4025 Since: 2.9
4027 BlockdevOptionsFile (Object)
4029 Driver specific block device options for the file backend.
4031 Members:
4033 "filename: string"
4035 path to the image file
4036 "pr-manager: string" (optional)
4038 the id for the object that will handle persistent reservations for
4039 this device (default: none, forward the commands via SG_IO; since
4040 2.11)
4041 "aio: BlockdevAioOptions" (optional)
4043 AIO backend (default: threads) (since: 2.8)
4044 "locking: OnOffAuto" (optional)
4046 whether to enable file locking. If set to 'auto', only enable when
4047 Open File Descriptor (OFD) locking API is available (default: auto,
4048 since 2.10)
4049 "x-check-cache-dropped: boolean" (optional)
4051 whether to check that page cache was dropped on live migration.
4052 May cause noticeable delays if the image file is large, do not use
4053 in production. (default: off) (since: 3.0)
4054 Since: 2.9
4056 BlockdevOptionsNull (Object)
4058 Driver specific block device options for the null backend.
4060 Members:
4062 "size: int" (optional)
4064 size of the device in bytes.
4065 "latency-ns: int" (optional)
4067 emulated latency (in nanoseconds) in processing requests. Default
4068 to zero which completes requests immediately. (Since 2.4)
4069 Since: 2.9
4071 BlockdevOptionsNVMe (Object)
4073 Driver specific block device options for the NVMe backend.
4075 Members:
4077 "device: string"
4079 controller address of the NVMe device.
4080 "namespace: int"
4082 namespace number of the device, starting from 1.
4083 Since: 2.12
4085 BlockdevOptionsVVFAT (Object)
4087 Driver specific block device options for the vvfat protocol.
4089 Members:
4091 "dir: string"
4093 directory to be exported as FAT image
4094 "fat-type: int" (optional)
4096 FAT type: 12, 16 or 32
4097 "floppy: boolean" (optional)
4099 whether to export a floppy image (true) or partitioned hard disk
4100 (false; default)
4101 "label: string" (optional)
4103 set the volume label, limited to 11 bytes. FAT16 and FAT32
4104 traditionally have some restrictions on labels, which are ignored
4105 by most operating systems. Defaults to "QEMU VVFAT". (since 2.4)
4106 "rw: boolean" (optional)
4108 whether to allow write operations (default: false)
4109 Since: 2.9
4111 BlockdevOptionsGenericFormat (Object)
4113 Driver specific block device options for image format that have no
4115 option besides their data source.
4116 Members:
4118 "file: BlockdevRef"
4120 reference to or definition of the data source block device
4121 Since: 2.9
4123 BlockdevOptionsLUKS (Object)
4125 Driver specific block device options for LUKS.
4127 Members:
4129 "key-secret: string" (optional)
4131 the ID of a QCryptoSecret object providing the decryption key
4132 (since 2.6). Mandatory except when doing a metadata-only probe of
4133 the image.
4134 The members of "BlockdevOptionsGenericFormat"
4136 Since: 2.9
4138 BlockdevOptionsGenericCOWFormat (Object)
4140 Driver specific block device options for image format that have no
4142 option besides their data source and an optional backing file.
4143 Members:
4145 "backing: BlockdevRefOrNull" (optional)
4147 reference to or definition of the backing file block device, null
4148 disables the backing file entirely. Defaults to the backing file
4149 stored the image file.
4150 The members of "BlockdevOptionsGenericFormat"
4152 Since: 2.9
4154 Qcow2OverlapCheckMode (Enum)
4156 General overlap check modes.
4158 Values:
4160 "none"
4162 Do not perform any checks
4163 "constant"
4165 Perform only checks which can be done in constant time and without
4166 reading anything from disk
4167 "cached"
4169 Perform only checks which can be done without reading anything from
4170 disk
4171 "all"
4173 Perform all available overlap checks
4174 Since: 2.9
4176 Qcow2OverlapCheckFlags (Object)
4178 Structure of flags for each metadata structure. Setting a field to
4180 'true' makes qemu guard that structure against unintended overwriting.
4181 The default value is chosen according to the template given.
4182 Members:
4184 "template: Qcow2OverlapCheckMode" (optional)
4186 Specifies a template mode which can be adjusted using the other
4187 flags, defaults to 'cached'
4188 "bitmap-directory: boolean" (optional)
4190 since 3.0
4191 "main-header: boolean" (optional)
4193 Not documented
4194 "active-l1: boolean" (optional)
4196 Not documented
4197 "active-l2: boolean" (optional)
4199 Not documented
4200 "refcount-table: boolean" (optional)
4202 Not documented
4203 "refcount-block: boolean" (optional)
4205 Not documented
4206 "snapshot-table: boolean" (optional)
4208 Not documented
4209 "inactive-l1: boolean" (optional)
4211 Not documented
4212 "inactive-l2: boolean" (optional)
4214 Not documented
4215 Since: 2.9
4217 Qcow2OverlapChecks (Alternate)
4219 Specifies which metadata structures should be guarded against
4221 unintended overwriting.
4222 Members:
4224 "flags: Qcow2OverlapCheckFlags"
4226 set of flags for separate specification of each metadata structure
4227 type
4228 "mode: Qcow2OverlapCheckMode"
4230 named mode which chooses a specific set of flags
4231 Since: 2.9
4233 BlockdevQcowEncryptionFormat (Enum)
4235 Values:
4237 "aes"
4239 AES-CBC with plain64 initialization vectors
4240 Since: 2.10
4242 BlockdevQcowEncryption (Object)
4244 Members:
4246 "format: BlockdevQcowEncryptionFormat"
4248 Not documented
4249 The members of "QCryptoBlockOptionsQCow" when "format" is "aes"
4251 Since: 2.10
4253 BlockdevOptionsQcow (Object)
4255 Driver specific block device options for qcow.
4257 Members:
4259 "encrypt: BlockdevQcowEncryption" (optional)
4261 Image decryption options. Mandatory for encrypted images, except
4262 when doing a metadata-only probe of the image.
4263 The members of "BlockdevOptionsGenericCOWFormat"
4265 Since: 2.10
4267 BlockdevQcow2EncryptionFormat (Enum)
4269 Values:
4271 "aes"
4273 AES-CBC with plain64 initialization venctors
4274 "luks"
4276 Not documented
4277 Since: 2.10
4279 BlockdevQcow2Encryption (Object)
4281 Members:
4283 "format: BlockdevQcow2EncryptionFormat"
4285 Not documented
4286 The members of "QCryptoBlockOptionsQCow" when "format" is "aes"
4288 The members of "QCryptoBlockOptionsLUKS" when "format" is "luks"
4289 Since: 2.10
4291 BlockdevOptionsQcow2 (Object)
4293 Driver specific block device options for qcow2.
4295 Members:
4297 "lazy-refcounts: boolean" (optional)
4299 whether to enable the lazy refcounts feature (default is taken from
4300 the image file)
4301 "pass-discard-request: boolean" (optional)
4303 whether discard requests to the qcow2 device should be forwarded to
4304 the data source
4305 "pass-discard-snapshot: boolean" (optional)
4307 whether discard requests for the data source should be issued when
4308 a snapshot operation (e.g. deleting a snapshot) frees clusters in
4309 the qcow2 file
4310 "pass-discard-other: boolean" (optional)
4312 whether discard requests for the data source should be issued on
4313 other occasions where a cluster gets freed
4314 "overlap-check: Qcow2OverlapChecks" (optional)
4316 which overlap checks to perform for writes to the image, defaults
4317 to 'cached' (since 2.2)
4318 "cache-size: int" (optional)
4320 the maximum total size of the L2 table and refcount block caches in
4321 bytes (since 2.2)
4322 "l2-cache-size: int" (optional)
4324 the maximum size of the L2 table cache in bytes (since 2.2)
4325 "l2-cache-entry-size: int" (optional)
4327 the size of each entry in the L2 cache in bytes. It must be a power
4328 of two between 512 and the cluster size. The default value is the
4329 cluster size (since 2.12)
4330 "refcount-cache-size: int" (optional)
4332 the maximum size of the refcount block cache in bytes (since 2.2)
4333 "cache-clean-interval: int" (optional)
4335 clean unused entries in the L2 and refcount caches. The interval is
4336 in seconds. The default value is 0 and it disables this feature
4337 (since 2.5)
4338 "encrypt: BlockdevQcow2Encryption" (optional)
4340 Image decryption options. Mandatory for encrypted images, except
4341 when doing a metadata-only probe of the image. (since 2.10)
4342 The members of "BlockdevOptionsGenericCOWFormat"
4344 Since: 2.9
4346 SshHostKeyCheckMode (Enum)
4348 "none" Don't check the host key at all "hash"
4350 Compare the host key with a given hash "known_hosts" Check the
4351 host key against the known_hosts file
4352 Values:
4354 "none"
4356 Not documented
4357 "hash"
4359 Not documented
4360 "known_hosts"
4362 Not documented
4363 Since: 2.12
4365 SshHostKeyCheckHashType (Enum)
4367 "md5" The given hash is an md5 hash "sha1" The
4369 given hash is an sha1 hash
4370 Values:
4372 "md5"
4374 Not documented
4375 "sha1"
4377 Not documented
4378 Since: 2.12
4380 SshHostKeyHash (Object)
4382 "type" The hash algorithm used for the hash "hash"
4384 The expected hash value
4385 Members:
4387 "type: SshHostKeyCheckHashType"
4389 Not documented
4390 "hash: string"
4392 Not documented
4393 Since: 2.12
4395 SshHostKeyCheck (Object)
4397 Members:
4399 "mode: SshHostKeyCheckMode"
4401 Not documented
4402 The members of "SshHostKeyHash" when "mode" is "hash"
4404 Since: 2.12
4406 BlockdevOptionsSsh (Object)
4408 Members:
4410 "server: InetSocketAddress"
4412 host address
4413 "path: string"
4415 path to the image on the host
4416 "user: string" (optional)
4418 user as which to connect, defaults to current local user name
4419 "host-key-check: SshHostKeyCheck" (optional)
4421 Defines how and what to check the host key against (default:
4422 known_hosts)
4423 Since: 2.9
4425 BlkdebugEvent (Enum)
4427 Trigger events supported by blkdebug.
4429 Values:
4431 "l1_shrink_write_table"
4433 write zeros to the l1 table to shrink image. (since 2.11)
4434 "l1_shrink_free_l2_clusters"
4436 discard the l2 tables. (since 2.11)
4437 "cor_write"
4439 a write due to copy-on-read (since 2.11)
4440 "l1_update"
4442 Not documented
4443 "l1_grow_alloc_table"
4445 Not documented
4446 "l1_grow_write_table"
4448 Not documented
4449 "l1_grow_activate_table"
4451 Not documented
4452 "l2_load"
4454 Not documented
4455 "l2_update"
4457 Not documented
4458 "l2_update_compressed"
4460 Not documented
4461 "l2_alloc_cow_read"
4463 Not documented
4464 "l2_alloc_write"
4466 Not documented
4467 "read_aio"
4469 Not documented
4470 "read_backing_aio"
4472 Not documented
4473 "read_compressed"
4475 Not documented
4476 "write_aio"
4478 Not documented
4479 "write_compressed"
4481 Not documented
4482 "vmstate_load"
4484 Not documented
4485 "vmstate_save"
4487 Not documented
4488 "cow_read"
4490 Not documented
4491 "cow_write"
4493 Not documented
4494 "reftable_load"
4496 Not documented
4497 "reftable_grow"
4499 Not documented
4500 "reftable_update"
4502 Not documented
4503 "refblock_load"
4505 Not documented
4506 "refblock_update"
4508 Not documented
4509 "refblock_update_part"
4511 Not documented
4512 "refblock_alloc"
4514 Not documented
4515 "refblock_alloc_hookup"
4517 Not documented
4518 "refblock_alloc_write"
4520 Not documented
4521 "refblock_alloc_write_blocks"
4523 Not documented
4524 "refblock_alloc_write_table"
4526 Not documented
4527 "refblock_alloc_switch_table"
4529 Not documented
4530 "cluster_alloc"
4532 Not documented
4533 "cluster_alloc_bytes"
4535 Not documented
4536 "cluster_free"
4538 Not documented
4539 "flush_to_os"
4541 Not documented
4542 "flush_to_disk"
4544 Not documented
4545 "pwritev_rmw_head"
4547 Not documented
4548 "pwritev_rmw_after_head"
4550 Not documented
4551 "pwritev_rmw_tail"
4553 Not documented
4554 "pwritev_rmw_after_tail"
4556 Not documented
4557 "pwritev"
4559 Not documented
4560 "pwritev_zero"
4562 Not documented
4563 "pwritev_done"
4565 Not documented
4566 "empty_image_prepare"
4568 Not documented
4569 Since: 2.9
4571 BlkdebugInjectErrorOptions (Object)
4573 Describes a single error injection for blkdebug.
4575 Members:
4577 "event: BlkdebugEvent"
4579 trigger event
4580 "state: int" (optional)
4582 the state identifier blkdebug needs to be in to actually trigger
4583 the event; defaults to "any"
4584 "errno: int" (optional)
4586 error identifier (errno) to be returned; defaults to EIO
4587 "sector: int" (optional)
4589 specifies the sector index which has to be affected in order to
4590 actually trigger the event; defaults to "any sector"
4591 "once: boolean" (optional)
4593 disables further events after this one has been triggered; defaults
4594 to false
4595 "immediately: boolean" (optional)
4597 fail immediately; defaults to false
4598 Since: 2.9
4600 BlkdebugSetStateOptions (Object)
4602 Describes a single state-change event for blkdebug.
4604 Members:
4606 "event: BlkdebugEvent"
4608 trigger event
4609 "state: int" (optional)
4611 the current state identifier blkdebug needs to be in; defaults to
4612 "any"
4613 "new_state: int"
4615 the state identifier blkdebug is supposed to assume if this event
4616 is triggered
4617 Since: 2.9
4619 BlockdevOptionsBlkdebug (Object)
4621 Driver specific block device options for blkdebug.
4623 Members:
4625 "image: BlockdevRef"
4627 underlying raw block device (or image file)
4628 "config: string" (optional)
4630 filename of the configuration file
4631 "align: int" (optional)
4633 required alignment for requests in bytes, must be positive power of
4634 2, or 0 for default
4635 "max-transfer: int" (optional)
4637 maximum size for I/O transfers in bytes, must be positive multiple
4638 of "align" and of the underlying file's request alignment (but need
4639 not be a power of 2), or 0 for default (since 2.10)
4640 "opt-write-zero: int" (optional)
4642 preferred alignment for write zero requests in bytes, must be
4643 positive multiple of "align" and of the underlying file's request
4644 alignment (but need not be a power of 2), or 0 for default (since
4645 2.10)
4646 "max-write-zero: int" (optional)
4648 maximum size for write zero requests in bytes, must be positive
4649 multiple of "align", of "opt-write-zero", and of the underlying
4650 file's request alignment (but need not be a power of 2), or 0 for
4651 default (since 2.10)
4652 "opt-discard: int" (optional)
4654 preferred alignment for discard requests in bytes, must be positive
4655 multiple of "align" and of the underlying file's request alignment
4656 (but need not be a power of 2), or 0 for default (since 2.10)
4657 "max-discard: int" (optional)
4659 maximum size for discard requests in bytes, must be positive
4660 multiple of "align", of "opt-discard", and of the underlying file's
4661 request alignment (but need not be a power of 2), or 0 for default
4662 (since 2.10)
4663 "inject-error: array of BlkdebugInjectErrorOptions" (optional)
4665 array of error injection descriptions
4666 "set-state: array of BlkdebugSetStateOptions" (optional)
4668 array of state-change descriptions
4669 Since: 2.9
4671 BlockdevOptionsBlklogwrites (Object)
4673 Driver specific block device options for blklogwrites.
4675 Members:
4677 "file: BlockdevRef"
4679 block device
4680 "log: BlockdevRef"
4682 block device used to log writes to "file"
4683 "log-sector-size: int" (optional)
4685 sector size used in logging writes to "file", determines
4686 granularity of offsets and sizes of writes (default: 512)
4687 "log-append: boolean" (optional)
4689 append to an existing log (default: false)
4690 "log-super-update-interval: int" (optional)
4692 interval of write requests after which the log super block is
4693 updated to disk (default: 4096)
4694 Since: 3.0
4696 BlockdevOptionsBlkverify (Object)
4698 Driver specific block device options for blkverify.
4700 Members:
4702 "test: BlockdevRef"
4704 block device to be tested
4705 "raw: BlockdevRef"
4707 raw image used for verification
4708 Since: 2.9
4710 QuorumReadPattern (Enum)
4712 An enumeration of quorum read patterns.
4714 Values:
4716 "quorum"
4718 read all the children and do a quorum vote on reads
4719 "fifo"
4721 read only from the first child that has not failed
4722 Since: 2.9
4724 BlockdevOptionsQuorum (Object)
4726 Driver specific block device options for Quorum
4728 Members:
4730 "blkverify: boolean" (optional)
4732 true if the driver must print content mismatch set to false by
4733 default
4734 "children: array of BlockdevRef"
4736 the children block devices to use
4737 "vote-threshold: int"
4739 the vote limit under which a read will fail
4740 "rewrite-corrupted: boolean" (optional)
4742 rewrite corrupted data when quorum is reached (Since 2.1)
4743 "read-pattern: QuorumReadPattern" (optional)
4745 choose read pattern and set to quorum by default (Since 2.2)
4746 Since: 2.9
4748 BlockdevOptionsGluster (Object)
4750 Driver specific block device options for Gluster
4752 Members:
4754 "volume: string"
4756 name of gluster volume where VM image resides
4757 "path: string"
4759 absolute path to image file in gluster volume
4760 "server: array of SocketAddress"
4762 gluster servers description
4763 "debug: int" (optional)
4765 libgfapi log level (default '4' which is Error) (Since 2.8)
4766 "logfile: string" (optional)
4768 libgfapi log file (default /dev/stderr) (Since 2.8)
4769 Since: 2.9
4771 IscsiTransport (Enum)
4773 An enumeration of libiscsi transport types
4775 Values:
4777 "tcp"
4779 Not documented
4780 "iser"
4782 Not documented
4783 Since: 2.9
4785 IscsiHeaderDigest (Enum)
4787 An enumeration of header digests supported by libiscsi
4789 Values:
4791 "crc32c"
4793 Not documented
4794 "none"
4796 Not documented
4797 "crc32c-none"
4799 Not documented
4800 "none-crc32c"
4802 Not documented
4803 Since: 2.9
4805 BlockdevOptionsIscsi (Object)
4807 Members:
4809 "transport: IscsiTransport"
4811 The iscsi transport type
4812 "portal: string"
4814 The address of the iscsi portal
4815 "target: string"
4817 The target iqn name
4818 "lun: int" (optional)
4820 LUN to connect to. Defaults to 0.
4821 "user: string" (optional)
4823 User name to log in with. If omitted, no CHAP authentication is
4824 performed.
4825 "password-secret: string" (optional)
4827 The ID of a QCryptoSecret object providing the password for the
4828 login. This option is required if "user" is specified.
4829 "initiator-name: string" (optional)
4831 The iqn name we want to identify to the target as. If this option
4832 is not specified, an initiator name is generated automatically.
4833 "header-digest: IscsiHeaderDigest" (optional)
4835 The desired header digest. Defaults to none-crc32c.
4836 "timeout: int" (optional)
4838 Timeout in seconds after which a request will timeout. 0 means no
4839 timeout and is the default.
4840 Driver specific block device options for iscsi
4842 Since: 2.9
4844 RbdAuthMode (Enum)
4846 Values:
4848 "cephx"
4850 Not documented
4851 "none"
4853 Not documented
4854 Since: 3.0
4856 BlockdevOptionsRbd (Object)
4858 Members:
4860 "pool: string"
4862 Ceph pool name.
4863 "image: string"
4865 Image name in the Ceph pool.
4866 "conf: string" (optional)
4868 path to Ceph configuration file. Values in the configuration file
4869 will be overridden by options specified via QAPI.
4870 "snapshot: string" (optional)
4872 Ceph snapshot name.
4873 "user: string" (optional)
4875 Ceph id name.
4876 "auth-client-required: array of RbdAuthMode" (optional)
4878 Acceptable authentication modes. This maps to Ceph configuration
4879 option "auth_client_required". (Since 3.0)
4880 "key-secret: string" (optional)
4882 ID of a QCryptoSecret object providing a key for cephx
4883 authentication. This maps to Ceph configuration option "key".
4884 (Since 3.0)
4885 "server: array of InetSocketAddressBase" (optional)
4887 Monitor host address and port. This maps to the "mon_host" Ceph
4888 option.
4889 Since: 2.9
4891 BlockdevOptionsSheepdog (Object)
4893 Driver specific block device options for sheepdog
4895 Members:
4897 "vdi: string"
4899 Virtual disk image name
4900 "server: SocketAddress"
4902 The Sheepdog server to connect to
4903 "snap-id: int" (optional)
4905 Snapshot ID
4906 "tag: string" (optional)
4908 Snapshot tag name
4909 Only one of "snap-id" and "tag" may be present.
4911 Since: 2.9
4913 ReplicationMode (Enum)
4915 An enumeration of replication modes.
4917 Values:
4919 "primary"
4921 Primary mode, the vm's state will be sent to secondary QEMU.
4922 "secondary"
4924 Secondary mode, receive the vm's state from primary QEMU.
4925 Since: 2.9
4927 BlockdevOptionsReplication (Object)
4929 Driver specific block device options for replication
4931 Members:
4933 "mode: ReplicationMode"
4935 the replication mode
4936 "top-id: string" (optional)
4938 In secondary mode, node name or device ID of the root node who owns
4939 the replication node chain. Must not be given in primary mode.
4940 The members of "BlockdevOptionsGenericFormat"
4942 Since: 2.9
4944 NFSTransport (Enum)
4946 An enumeration of NFS transport types
4948 Values:
4950 "inet"
4952 TCP transport
4953 Since: 2.9
4955 NFSServer (Object)
4957 Captures the address of the socket
4959 Members:
4961 "type: NFSTransport"
4963 transport type used for NFS (only TCP supported)
4964 "host: string"
4966 host address for NFS server
4967 Since: 2.9
4969 BlockdevOptionsNfs (Object)
4971 Driver specific block device option for NFS
4973 Members:
4975 "server: NFSServer"
4977 host address
4978 "path: string"
4980 path of the image on the host
4981 "user: int" (optional)
4983 UID value to use when talking to the server (defaults to 65534 on
4984 Windows and getuid() on unix)
4985 "group: int" (optional)
4987 GID value to use when talking to the server (defaults to 65534 on
4988 Windows and getgid() in unix)
4989 "tcp-syn-count: int" (optional)
4991 number of SYNs during the session establishment (defaults to libnfs
4992 default)
4993 "readahead-size: int" (optional)
4995 set the readahead size in bytes (defaults to libnfs default)
4996 "page-cache-size: int" (optional)
4998 set the pagecache size in bytes (defaults to libnfs default)
4999 "debug: int" (optional)
5001 set the NFS debug level (max 2) (defaults to libnfs default)
5002 Since: 2.9
5004 BlockdevOptionsCurlBase (Object)
5006 Driver specific block device options shared by all protocols supported
5008 by the curl backend.
5009 Members:
5011 "url: string"
5013 URL of the image file
5014 "readahead: int" (optional)
5016 Size of the read-ahead cache; must be a multiple of 512 (defaults
5017 to 256 kB)
5018 "timeout: int" (optional)
5020 Timeout for connections, in seconds (defaults to 5)
5021 "username: string" (optional)
5023 Username for authentication (defaults to none)
5024 "password-secret: string" (optional)
5026 ID of a QCryptoSecret object providing a password for
5027 authentication (defaults to no password)
5028 "proxy-username: string" (optional)
5030 Username for proxy authentication (defaults to none)
5031 "proxy-password-secret: string" (optional)
5033 ID of a QCryptoSecret object providing a password for proxy
5034 authentication (defaults to no password)
5035 Since: 2.9
5037 BlockdevOptionsCurlHttp (Object)
5039 Driver specific block device options for HTTP connections over the curl
5041 backend. URLs must start with "http://".
5042 Members:
5044 "cookie: string" (optional)
5046 List of cookies to set; format is "name1=content1; name2=content2;"
5047 as explained by CURLOPT_COOKIE(3). Defaults to no cookies.
5048 "cookie-secret: string" (optional)
5050 ID of a QCryptoSecret object providing the cookie data in a secure
5051 way. See "cookie" for the format. (since 2.10)
5052 The members of "BlockdevOptionsCurlBase"
5054 Since: 2.9
5056 BlockdevOptionsCurlHttps (Object)
5058 Driver specific block device options for HTTPS connections over the
5060 curl backend. URLs must start with "https://".
5061 Members:
5063 "cookie: string" (optional)
5065 List of cookies to set; format is "name1=content1; name2=content2;"
5066 as explained by CURLOPT_COOKIE(3). Defaults to no cookies.
5067 "sslverify: boolean" (optional)
5069 Whether to verify the SSL certificate's validity (defaults to true)
5070 "cookie-secret: string" (optional)
5072 ID of a QCryptoSecret object providing the cookie data in a secure
5073 way. See "cookie" for the format. (since 2.10)
5074 The members of "BlockdevOptionsCurlBase"
5076 Since: 2.9
5078 BlockdevOptionsCurlFtp (Object)
5080 Driver specific block device options for FTP connections over the curl
5082 backend. URLs must start with "ftp://".
5083 Members:
5085 The members of "BlockdevOptionsCurlBase"
5087 Since: 2.9
5089 BlockdevOptionsCurlFtps (Object)
5091 Driver specific block device options for FTPS connections over the curl
5093 backend. URLs must start with "ftps://".
5094 Members:
5096 "sslverify: boolean" (optional)
5098 Whether to verify the SSL certificate's validity (defaults to true)
5099 The members of "BlockdevOptionsCurlBase"
5101 Since: 2.9
5103 BlockdevOptionsNbd (Object)
5105 Driver specific block device options for NBD.
5107 Members:
5109 "server: SocketAddress"
5111 NBD server address
5112 "export: string" (optional)
5114 export name
5115 "tls-creds: string" (optional)
5117 TLS credentials ID
5118 "x-dirty-bitmap: string" (optional)
5120 A "qemu:dirty-bitmap:NAME" string to query in place of traditional
5121 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
5122 the NBD protocol) (since 3.0)
5123 Since: 2.9
5125 BlockdevOptionsRaw (Object)
5127 Driver specific block device options for the raw driver.
5129 Members:
5131 "offset: int" (optional)
5133 position where the block device starts
5134 "size: int" (optional)
5136 the assumed size of the device
5137 The members of "BlockdevOptionsGenericFormat"
5139 Since: 2.9
5141 BlockdevOptionsVxHS (Object)
5143 Driver specific block device options for VxHS
5145 Members:
5147 "vdisk-id: string"
5149 UUID of VxHS volume
5150 "server: InetSocketAddressBase"
5152 vxhs server IP, port
5153 "tls-creds: string" (optional)
5155 TLS credentials ID
5156 Since: 2.10
5158 BlockdevOptionsThrottle (Object)
5160 Driver specific block device options for the throttle driver
5162 Members:
5164 "throttle-group: string"
5166 the name of the throttle-group object to use. It must already
5167 exist.
5168 "file: BlockdevRef"
5170 reference to or definition of the data source block device
5171 Since: 2.11
5173 BlockdevOptions (Object)
5175 Options for creating a block device. Many options are available for
5177 all block devices, independent of the block driver:
5178 Members:
5180 "driver: BlockdevDriver"
5182 block driver name
5183 "node-name: string" (optional)
5185 the node name of the new node (Since 2.0). This option is required
5186 on the top level of blockdev-add.
5187 "discard: BlockdevDiscardOptions" (optional)
5189 discard-related options (default: ignore)
5190 "cache: BlockdevCacheOptions" (optional)
5192 cache-related options
5193 "read-only: boolean" (optional)
5195 whether the block device should be read-only (default: false).
5196 Note that some block drivers support only read-only access, either
5197 generally or in certain configurations. In this case, the default
5198 value does not work and the option must be specified explicitly.
5199 "detect-zeroes: BlockdevDetectZeroesOptions" (optional)
5201 detect and optimize zero writes (Since 2.1) (default: off)
5202 "force-share: boolean" (optional)
5204 force share all permission on added nodes. Requires
5205 read-only=true. (Since 2.10)
5206 The members of "BlockdevOptionsBlkdebug" when "driver" is "blkdebug"
5208 The members of "BlockdevOptionsBlklogwrites" when "driver" is
5209 "blklogwrites"
5210 The members of "BlockdevOptionsBlkverify" when "driver" is "blkverify"
5211 The members of "BlockdevOptionsGenericFormat" when "driver" is "bochs"
5212 The members of "BlockdevOptionsGenericFormat" when "driver" is "cloop"
5213 The members of "BlockdevOptionsGenericFormat" when "driver" is "copy-
5214 on-read"
5215 The members of "BlockdevOptionsGenericFormat" when "driver" is "dmg"
5216 The members of "BlockdevOptionsFile" when "driver" is "file"
5217 The members of "BlockdevOptionsCurlFtp" when "driver" is "ftp"
5218 The members of "BlockdevOptionsCurlFtps" when "driver" is "ftps"
5219 The members of "BlockdevOptionsGluster" when "driver" is "gluster"
5220 The members of "BlockdevOptionsFile" when "driver" is "host_cdrom"
5221 The members of "BlockdevOptionsFile" when "driver" is "host_device"
5222 The members of "BlockdevOptionsCurlHttp" when "driver" is "http"
5223 The members of "BlockdevOptionsCurlHttps" when "driver" is "https"
5224 The members of "BlockdevOptionsIscsi" when "driver" is "iscsi"
5225 The members of "BlockdevOptionsLUKS" when "driver" is "luks"
5226 The members of "BlockdevOptionsNbd" when "driver" is "nbd"
5227 The members of "BlockdevOptionsNfs" when "driver" is "nfs"
5228 The members of "BlockdevOptionsNull" when "driver" is "null-aio"
5229 The members of "BlockdevOptionsNull" when "driver" is "null-co"
5230 The members of "BlockdevOptionsNVMe" when "driver" is "nvme"
5231 The members of "BlockdevOptionsGenericFormat" when "driver" is
5232 "parallels"
5233 The members of "BlockdevOptionsQcow2" when "driver" is "qcow2"
5234 The members of "BlockdevOptionsQcow" when "driver" is "qcow"
5235 The members of "BlockdevOptionsGenericCOWFormat" when "driver" is "qed"
5236 The members of "BlockdevOptionsQuorum" when "driver" is "quorum"
5237 The members of "BlockdevOptionsRaw" when "driver" is "raw"
5238 The members of "BlockdevOptionsRbd" when "driver" is "rbd"
5239 The members of "BlockdevOptionsReplication" when "driver" is
5240 "replication"
5241 The members of "BlockdevOptionsSheepdog" when "driver" is "sheepdog"
5242 The members of "BlockdevOptionsSsh" when "driver" is "ssh"
5243 The members of "BlockdevOptionsThrottle" when "driver" is "throttle"
5244 The members of "BlockdevOptionsGenericFormat" when "driver" is "vdi"
5245 The members of "BlockdevOptionsGenericFormat" when "driver" is "vhdx"
5246 The members of "BlockdevOptionsGenericCOWFormat" when "driver" is
5247 "vmdk"
5248 The members of "BlockdevOptionsGenericFormat" when "driver" is "vpc"
5249 The members of "BlockdevOptionsVVFAT" when "driver" is "vvfat"
5250 The members of "BlockdevOptionsVxHS" when "driver" is "vxhs"
5251 Remaining options are determined by the block driver.
5253 Since: 2.9
5255 BlockdevRef (Alternate)
5257 Reference to a block device.
5259 Members:
5261 "definition: BlockdevOptions"
5263 defines a new block device inline
5264 "reference: string"
5266 references the ID of an existing block device
5267 Since: 2.9
5269 BlockdevRefOrNull (Alternate)
5271 Reference to a block device.
5273 Members:
5275 "definition: BlockdevOptions"
5277 defines a new block device inline
5278 "reference: string"
5280 references the ID of an existing block device. An empty string
5281 means that no block device should be referenced. Deprecated; use
5282 null instead.
5283 "null: null"
5285 No block device should be referenced (since 2.10)
5286 Since: 2.9
5288 blockdev-add (Command) Creates a new block device. If the "id" option
5290 is given at the top level, a BlockBackend will be created; otherwise,
5291 "node-name" is mandatory at the top level and no BlockBackend will be
5292 created.
5293 Arguments: the members of "BlockdevOptions"
5295 Since: 2.9
5297 Example:
5299 1.
5301 -> { "execute": "blockdev-add",
5302 "arguments": {
5303 "driver": "qcow2",
5304 "node-name": "test1",
5305 "file": {
5306 "driver": "file",
5307 "filename": "test.qcow2"
5308 }
5309 }
5310 }
5311 <- { "return": {} }
5312 2.
5314 -> { "execute": "blockdev-add",
5315 "arguments": {
5316 "driver": "qcow2",
5317 "node-name": "node0",
5318 "discard": "unmap",
5319 "cache": {
5320 "direct": true
5321 },
5322 "file": {
5323 "driver": "file",
5324 "filename": "/tmp/test.qcow2"
5325 },
5326 "backing": {
5327 "driver": "raw",
5328 "file": {
5329 "driver": "file",
5330 "filename": "/dev/fdset/4"
5331 }
5332 }
5333 }
5334 }
5335 <- { "return": {} }
5337 blockdev-del (Command) Deletes a block device that has been added
5339 using blockdev-add. The command will fail if the node is attached to a
5340 device or is otherwise being used.
5341 Arguments:
5343 "node-name: string"
5345 Name of the graph node to delete.
5346 Since: 2.9
5348 Example:
5350 -> { "execute": "blockdev-add",
5352 "arguments": {
5353 "driver": "qcow2",
5354 "node-name": "node0",
5355 "file": {
5356 "driver": "file",
5357 "filename": "test.qcow2"
5358 }
5359 }
5360 }
5361 <- { "return": {} }
5362 -> { "execute": "blockdev-del",
5364 "arguments": { "node-name": "node0" }
5365 }
5366 <- { "return": {} }
5367 BlockdevCreateOptionsFile (Object)
5369 Driver specific image creation options for file.
5371 "filename" Filename for the new image file "size"
5373 Size of the virtual disk in bytes "preallocation" Preallocation mode
5374 for the new image (default: off) "nocow" Turn off copy-on-
5375 write (valid only on btrfs; default: off)
5376 Members:
5378 "filename: string"
5380 Not documented
5381 "size: int"
5383 Not documented
5384 "preallocation: PreallocMode" (optional)
5386 Not documented
5387 "nocow: boolean" (optional)
5389 Not documented
5390 Since: 2.12
5392 BlockdevCreateOptionsGluster (Object)
5394 Driver specific image creation options for gluster.
5396 "location" Where to store the new image file "size"
5398 Size of the virtual disk in bytes "preallocation" Preallocation mode
5399 for the new image (default: off)
5400 Members:
5402 "location: BlockdevOptionsGluster"
5404 Not documented
5405 "size: int"
5407 Not documented
5408 "preallocation: PreallocMode" (optional)
5410 Not documented
5411 Since: 2.12
5413 BlockdevCreateOptionsLUKS (Object)
5415 Driver specific image creation options for LUKS.
5417 "file" Node to create the image format on "size"
5419 Size of the virtual disk in bytes
5420 Members:
5422 "file: BlockdevRef"
5424 Not documented
5425 "size: int"
5427 Not documented
5428 The members of "QCryptoBlockCreateOptionsLUKS"
5430 Since: 2.12
5432 BlockdevCreateOptionsNfs (Object)
5434 Driver specific image creation options for NFS.
5436 "location" Where to store the new image file "size"
5438 Size of the virtual disk in bytes
5439 Members:
5441 "location: BlockdevOptionsNfs"
5443 Not documented
5444 "size: int"
5446 Not documented
5447 Since: 2.12
5449 BlockdevCreateOptionsParallels (Object)
5451 Driver specific image creation options for parallels.
5453 "file" Node to create the image format on "size"
5455 Size of the virtual disk in bytes "cluster-size" Cluster size in
5456 bytes (default: 1 MB)
5457 Members:
5459 "file: BlockdevRef"
5461 Not documented
5462 "size: int"
5464 Not documented
5465 "cluster-size: int" (optional)
5467 Not documented
5468 Since: 2.12
5470 BlockdevCreateOptionsQcow (Object)
5472 Driver specific image creation options for qcow.
5474 "file" Node to create the image format on "size"
5476 Size of the virtual disk in bytes "backing-file" File name of the
5477 backing file if a backing file should be used "encrypt"
5478 Encryption options if the image should be encrypted
5479 Members:
5481 "file: BlockdevRef"
5483 Not documented
5484 "size: int"
5486 Not documented
5487 "backing-file: string" (optional)
5489 Not documented
5490 "encrypt: QCryptoBlockCreateOptions" (optional)
5492 Not documented
5493 Since: 2.12
5495 BlockdevQcow2Version (Enum)
5497 Values:
5499 "v2"
5501 The original QCOW2 format as introduced in qemu 0.10 (version 2)
5502 "v3"
5504 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
5505 Since: 2.12
5507 BlockdevCreateOptionsQcow2 (Object)
5509 Driver specific image creation options for qcow2.
5511 "file" Node to create the image format on "size"
5513 Size of the virtual disk in bytes "version" Compatibility
5514 level (default: v3) "backing-file" File name of the backing file if
5515 a backing file should be used "backing-fmt" Name of the block
5516 driver to use for the backing file "encrypt" Encryption
5517 options if the image should be encrypted "cluster-size" qcow2
5518 cluster size in bytes (default: 65536) "preallocation" Preallocation
5519 mode for the new image (default: off) "lazy-refcounts" True if
5520 refcounts may be updated lazily (default: off) "refcount-bits" Width
5521 of reference counts in bits (default: 16)
5522 Members:
5524 "file: BlockdevRef"
5526 Not documented
5527 "size: int"
5529 Not documented
5530 "version: BlockdevQcow2Version" (optional)
5532 Not documented
5533 "backing-file: string" (optional)
5535 Not documented
5536 "backing-fmt: BlockdevDriver" (optional)
5538 Not documented
5539 "encrypt: QCryptoBlockCreateOptions" (optional)
5541 Not documented
5542 "cluster-size: int" (optional)
5544 Not documented
5545 "preallocation: PreallocMode" (optional)
5547 Not documented
5548 "lazy-refcounts: boolean" (optional)
5550 Not documented
5551 "refcount-bits: int" (optional)
5553 Not documented
5554 Since: 2.12
5556 BlockdevCreateOptionsQed (Object)
5558 Driver specific image creation options for qed.
5560 "file" Node to create the image format on "size"
5562 Size of the virtual disk in bytes "backing-file" File name of the
5563 backing file if a backing file should be used "backing-fmt" Name
5564 of the block driver to use for the backing file "cluster-size"
5565 Cluster size in bytes (default: 65536) "table-size" L1/L2 table
5566 size (in clusters)
5567 Members:
5569 "file: BlockdevRef"
5571 Not documented
5572 "size: int"
5574 Not documented
5575 "backing-file: string" (optional)
5577 Not documented
5578 "backing-fmt: BlockdevDriver" (optional)
5580 Not documented
5581 "cluster-size: int" (optional)
5583 Not documented
5584 "table-size: int" (optional)
5586 Not documented
5587 Since: 2.12
5589 BlockdevCreateOptionsRbd (Object)
5591 Driver specific image creation options for rbd/Ceph.
5593 "location" Where to store the new image file. This location
5595 cannot point to a snapshot. "size" Size of the virtual
5596 disk in bytes "cluster-size" RBD object size
5597 Members:
5599 "location: BlockdevOptionsRbd"
5601 Not documented
5602 "size: int"
5604 Not documented
5605 "cluster-size: int" (optional)
5607 Not documented
5608 Since: 2.12
5610 SheepdogRedundancyType (Enum)
5612 "full" Create a fully replicated vdi with x copies
5614 "erasure-coded" Create an erasure coded vdi with x data strips and y
5615 parity strips
5616 Values:
5618 "full"
5620 Not documented
5621 "erasure-coded"
5623 Not documented
5624 Since: 2.12
5626 SheepdogRedundancyFull (Object)
5628 "copies" Number of copies to use (between 1 and 31)
5630 Members:
5632 "copies: int"
5634 Not documented
5635 Since: 2.12
5637 SheepdogRedundancyErasureCoded (Object)
5639 "data-strips" Number of data strips to use (one of {2,4,8,16})
5641 "parity-strips" Number of parity strips to use (between 1 and 15)
5642 Members:
5644 "data-strips: int"
5646 Not documented
5647 "parity-strips: int"
5649 Not documented
5650 Since: 2.12
5652 SheepdogRedundancy (Object)
5654 Members:
5656 "type: SheepdogRedundancyType"
5658 Not documented
5659 The members of "SheepdogRedundancyFull" when "type" is "full"
5661 The members of "SheepdogRedundancyErasureCoded" when "type" is
5662 "erasure-coded"
5663 Since: 2.12
5665 BlockdevCreateOptionsSheepdog (Object)
5667 Driver specific image creation options for Sheepdog.
5669 "location" Where to store the new image file "size"
5671 Size of the virtual disk in bytes "backing-file" File name of a
5672 base image "preallocation" Preallocation mode (allowed values: off,
5673 full) "redundancy" Redundancy of the image "object-size"
5674 Object size of the image
5675 Members:
5677 "location: BlockdevOptionsSheepdog"
5679 Not documented
5680 "size: int"
5682 Not documented
5683 "backing-file: string" (optional)
5685 Not documented
5686 "preallocation: PreallocMode" (optional)
5688 Not documented
5689 "redundancy: SheepdogRedundancy" (optional)
5691 Not documented
5692 "object-size: int" (optional)
5694 Not documented
5695 Since: 2.12
5697 BlockdevCreateOptionsSsh (Object)
5699 Driver specific image creation options for SSH.
5701 "location" Where to store the new image file "size"
5703 Size of the virtual disk in bytes
5704 Members:
5706 "location: BlockdevOptionsSsh"
5708 Not documented
5709 "size: int"
5711 Not documented
5712 Since: 2.12
5714 BlockdevCreateOptionsVdi (Object)
5716 Driver specific image creation options for VDI.
5718 "file" Node to create the image format on "size"
5720 Size of the virtual disk in bytes "preallocation" Preallocation mode
5721 for the new image (allowed values: off, metadata; default: off)
5722 Members:
5724 "file: BlockdevRef"
5726 Not documented
5727 "size: int"
5729 Not documented
5730 "preallocation: PreallocMode" (optional)
5732 Not documented
5733 Since: 2.12
5735 BlockdevVhdxSubformat (Enum)
5737 Values:
5739 "dynamic"
5741 Growing image file
5742 "fixed"
5744 Preallocated fixed-size image file
5745 Since: 2.12
5747 BlockdevCreateOptionsVhdx (Object)
5749 Driver specific image creation options for vhdx.
5751 "file" Node to create the image format on "size"
5753 Size of the virtual disk in bytes "log-size" Log size in bytes,
5754 must be a multiple of 1 MB (default: 1 MB) "block-size" Block
5755 size in bytes, must be a multiple of 1 MB and not larger than 256 MB
5756 (default: automatically choose a block size depending on the image
5757 size) "subformat" vhdx subformat (default: dynamic)
5758 "block-state-zero" Force use of payload blocks of type 'ZERO'. Non-
5759 standard, but default. Do not set to 'off' when using 'qemu-img
5760 convert' with subformat=dynamic.
5761 Members:
5763 "file: BlockdevRef"
5765 Not documented
5766 "size: int"
5768 Not documented
5769 "log-size: int" (optional)
5771 Not documented
5772 "block-size: int" (optional)
5774 Not documented
5775 "subformat: BlockdevVhdxSubformat" (optional)
5777 Not documented
5778 "block-state-zero: boolean" (optional)
5780 Not documented
5781 Since: 2.12
5783 BlockdevVpcSubformat (Enum)
5785 Values:
5787 "dynamic"
5789 Growing image file
5790 "fixed"
5792 Preallocated fixed-size image file
5793 Since: 2.12
5795 BlockdevCreateOptionsVpc (Object)
5797 Driver specific image creation options for vpc (VHD).
5799 "file" Node to create the image format on "size"
5801 Size of the virtual disk in bytes "subformat" vhdx subformat
5802 (default: dynamic) "force-size" Force use of the exact byte size
5803 instead of rounding to the next size that can be represented in CHS
5804 geometry (default: false)
5805 Members:
5807 "file: BlockdevRef"
5809 Not documented
5810 "size: int"
5812 Not documented
5813 "subformat: BlockdevVpcSubformat" (optional)
5815 Not documented
5816 "force-size: boolean" (optional)
5818 Not documented
5819 Since: 2.12
5821 BlockdevCreateOptions (Object)
5823 Options for creating an image format on a given node.
5825 "driver" block driver to create the image format
5827 Members:
5829 "driver: BlockdevDriver"
5831 Not documented
5832 The members of "BlockdevCreateOptionsFile" when "driver" is "file"
5834 The members of "BlockdevCreateOptionsGluster" when "driver" is
5835 "gluster"
5836 The members of "BlockdevCreateOptionsLUKS" when "driver" is "luks"
5837 The members of "BlockdevCreateOptionsNfs" when "driver" is "nfs"
5838 The members of "BlockdevCreateOptionsParallels" when "driver" is
5839 "parallels"
5840 The members of "BlockdevCreateOptionsQcow" when "driver" is "qcow"
5841 The members of "BlockdevCreateOptionsQcow2" when "driver" is "qcow2"
5842 The members of "BlockdevCreateOptionsQed" when "driver" is "qed"
5843 The members of "BlockdevCreateOptionsRbd" when "driver" is "rbd"
5844 The members of "BlockdevCreateOptionsSheepdog" when "driver" is
5845 "sheepdog"
5846 The members of "BlockdevCreateOptionsSsh" when "driver" is "ssh"
5847 The members of "BlockdevCreateOptionsVdi" when "driver" is "vdi"
5848 The members of "BlockdevCreateOptionsVhdx" when "driver" is "vhdx"
5849 The members of "BlockdevCreateOptionsVpc" when "driver" is "vpc"
5850 Since: 2.12
5852 blockdev-create (Command) Starts a job to create an image format on a
5854 given node. The job is automatically finalized, but a manual job-
5855 dismiss is required.
5856 Arguments:
5858 "job-id: string"
5860 Identifier for the newly created job.
5861 "options: BlockdevCreateOptions"
5863 Options for the image creation.
5864 Since: 3.0
5866 blockdev-open-tray (Command) Opens a block device's tray. If there is
5868 a block driver state tree inserted as a medium, it will become
5869 inaccessible to the guest (but it will remain associated to the block
5870 device, so closing the tray will make it accessible again).
5871 If the tray was already open before, this will be a no-op.
5873 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are
5875 cases in which no such event will be generated, these include:
5876 - if the guest has locked the tray, "force" is false and the guest
5878 does not respond to the eject request
5879 - if the BlockBackend denoted by "device" does not have a guest
5881 device attached to it
5882 - if the guest device does not have an actual tray
5884 Arguments:
5886 "device: string" (optional)
5888 Block device name (deprecated, use "id" instead)
5889 "id: string" (optional)
5891 The name or QOM path of the guest device (since: 2.8)
5892 "force: boolean" (optional)
5894 if false (the default), an eject request will be sent to the guest
5895 if it has locked the tray (and the tray will not be opened
5896 immediately); if true, the tray will be opened regardless of
5897 whether it is locked
5898 Since: 2.5
5900 Example:
5902 -> { "execute": "blockdev-open-tray",
5904 "arguments": { "id": "ide0-1-0" } }
5905 <- { "timestamp": { "seconds": 1418751016,
5907 "microseconds": 716996 },
5908 "event": "DEVICE_TRAY_MOVED",
5909 "data": { "device": "ide1-cd0",
5910 "id": "ide0-1-0",
5911 "tray-open": true } }
5912 <- { "return": {} }
5914 blockdev-close-tray (Command) Closes a block device's tray. If there
5916 is a block driver state tree associated with the block device (which is
5917 currently ejected), that tree will be loaded as the medium.
5918 If the tray was already closed before, this will be a no-op.
5920 Arguments:
5922 "device: string" (optional)
5924 Block device name (deprecated, use "id" instead)
5925 "id: string" (optional)
5927 The name or QOM path of the guest device (since: 2.8)
5928 Since: 2.5
5930 Example:
5932 -> { "execute": "blockdev-close-tray",
5934 "arguments": { "id": "ide0-1-0" } }
5935 <- { "timestamp": { "seconds": 1418751345,
5937 "microseconds": 272147 },
5938 "event": "DEVICE_TRAY_MOVED",
5939 "data": { "device": "ide1-cd0",
5940 "id": "ide0-1-0",
5941 "tray-open": false } }
5942 <- { "return": {} }
5944 blockdev-remove-medium (Command) Removes a medium (a block driver
5946 state tree) from a block device. That block device's tray must
5947 currently be open (unless there is no attached guest device).
5948 If the tray is open and there is no medium inserted, this will be a no-
5950 op.
5951 Arguments:
5953 "id: string"
5955 The name or QOM path of the guest device
5956 Since: 2.12
5958 Example:
5960 -> { "execute": "blockdev-remove-medium",
5962 "arguments": { "id": "ide0-1-0" } }
5963 <- { "error": { "class": "GenericError",
5965 "desc": "Tray of device 'ide0-1-0' is not open" } }
5966 -> { "execute": "blockdev-open-tray",
5968 "arguments": { "id": "ide0-1-0" } }
5969 <- { "timestamp": { "seconds": 1418751627,
5971 "microseconds": 549958 },
5972 "event": "DEVICE_TRAY_MOVED",
5973 "data": { "device": "ide1-cd0",
5974 "id": "ide0-1-0",
5975 "tray-open": true } }
5976 <- { "return": {} }
5978 -> { "execute": "blockdev-remove-medium",
5980 "arguments": { "id": "ide0-1-0" } }
5981 <- { "return": {} }
5983 blockdev-insert-medium (Command) Inserts a medium (a block driver
5985 state tree) into a block device. That block device's tray must
5986 currently be open (unless there is no attached guest device) and there
5987 must be no medium inserted already.
5988 Arguments:
5990 "id: string"
5992 The name or QOM path of the guest device
5993 "node-name: string"
5995 name of a node in the block driver state graph
5996 Since: 2.12
5998 Example:
6000 -> { "execute": "blockdev-add",
6002 "arguments": {
6003 "node-name": "node0",
6004 "driver": "raw",
6005 "file": { "driver": "file",
6006 "filename": "fedora.iso" } } }
6007 <- { "return": {} }
6008 -> { "execute": "blockdev-insert-medium",
6010 "arguments": { "id": "ide0-1-0",
6011 "node-name": "node0" } }
6012 <- { "return": {} }
6014 BlockdevChangeReadOnlyMode (Enum)
6016 Specifies the new read-only mode of a block device subject to the
6018 "blockdev-change-medium" command.
6019 Values:
6021 "retain"
6023 Retains the current read-only mode
6024 "read-only"
6026 Makes the device read-only
6027 "read-write"
6029 Makes the device writable
6030 Since: 2.3
6032 blockdev-change-medium (Command) Changes the medium inserted into a
6034 block device by ejecting the current medium and loading a new image
6035 file which is inserted as the new medium (this command combines
6036 blockdev-open-tray, blockdev-remove-medium, blockdev-insert-medium and
6037 blockdev-close-tray).
6038 Arguments:
6040 "device: string" (optional)
6042 Block device name (deprecated, use "id" instead)
6043 "id: string" (optional)
6045 The name or QOM path of the guest device (since: 2.8)
6046 "filename: string"
6048 filename of the new image to be loaded
6049 "format: string" (optional)
6051 format to open the new image with (defaults to the probed format)
6052 "read-only-mode: BlockdevChangeReadOnlyMode" (optional)
6054 change the read-only mode of the device; defaults to 'retain'
6055 Since: 2.5
6057 Examples:
6059 1. Change a removable medium
6061 -> { "execute": "blockdev-change-medium",
6063 "arguments": { "id": "ide0-1-0",
6064 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
6065 "format": "raw" } }
6066 <- { "return": {} }
6067 2. Load a read-only medium into a writable drive
6069 -> { "execute": "blockdev-change-medium",
6071 "arguments": { "id": "floppyA",
6072 "filename": "/srv/images/ro.img",
6073 "format": "raw",
6074 "read-only-mode": "retain" } }
6075 <- { "error":
6077 { "class": "GenericError",
6078 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
6079 -> { "execute": "blockdev-change-medium",
6081 "arguments": { "id": "floppyA",
6082 "filename": "/srv/images/ro.img",
6083 "format": "raw",
6084 "read-only-mode": "read-only" } }
6085 <- { "return": {} }
6087 BlockErrorAction (Enum)
6089 An enumeration of action that has been taken when a DISK I/O occurs
6091 Values:
6093 "ignore"
6095 error has been ignored
6096 "report"
6098 error has been reported to the device
6099 "stop"
6101 error caused VM to be stopped
6102 Since: 2.1
6104 BLOCK_IMAGE_CORRUPTED (Event) Emitted when a disk image is being
6106 marked corrupt. The image can be identified by its device or node name.
6107 The 'device' field is always present for compatibility reasons, but it
6108 can be empty ("") if the image does not have a device name associated.
6109 Arguments:
6111 "device: string"
6113 device name. This is always present for compatibility reasons, but
6114 it can be empty ("") if the image does not have a device name
6115 associated.
6116 "node-name: string" (optional)
6118 node name (Since: 2.4)
6119 "msg: string"
6121 informative message for human consumption, such as the kind of
6122 corruption being detected. It should not be parsed by machine as it
6123 is not guaranteed to be stable
6124 "offset: int" (optional)
6126 if the corruption resulted from an image access, this is the host's
6127 access offset into the image
6128 "size: int" (optional)
6130 if the corruption resulted from an image access, this is the access
6131 size
6132 "fatal: boolean"
6134 if set, the image is marked corrupt and therefore unusable after
6135 this event and must be repaired (Since 2.2; before, every
6136 BLOCK_IMAGE_CORRUPTED event was fatal)
6137 Note: If action is "stop", a STOP event will eventually follow the
6139 BLOCK_IO_ERROR event.
6140 Example:
6142 <- { "event": "BLOCK_IMAGE_CORRUPTED",
6144 "data": { "device": "ide0-hd0", "node-name": "node0",
6145 "msg": "Prevented active L1 table overwrite", "offset": 196608,
6146 "size": 65536 },
6147 "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
6148 Since: 1.7
6150 BLOCK_IO_ERROR (Event) Emitted when a disk I/O error occurs
6152 Arguments:
6154 "device: string"
6156 device name. This is always present for compatibility reasons, but
6157 it can be empty ("") if the image does not have a device name
6158 associated.
6159 "node-name: string" (optional)
6161 node name. Note that errors may be reported for the root node that
6162 is directly attached to a guest device rather than for the node
6163 where the error occurred. The node name is not present if the drive
6164 is empty. (Since: 2.8)
6165 "operation: IoOperationType"
6167 I/O operation
6168 "action: BlockErrorAction"
6170 action that has been taken
6171 "nospace: boolean" (optional)
6173 true if I/O error was caused due to a no-space condition. This key
6174 is only present if query-block's io-status is present, please see
6175 query-block documentation for more information (since: 2.2)
6176 "reason: string"
6178 human readable string describing the error cause. (This field is a
6179 debugging aid for humans, it should not be parsed by applications)
6180 (since: 2.2)
6181 Note: If action is "stop", a STOP event will eventually follow the
6183 BLOCK_IO_ERROR event
6184 Since: 0.13.0
6186 Example:
6188 <- { "event": "BLOCK_IO_ERROR",
6190 "data": { "device": "ide0-hd1",
6191 "node-name": "#block212",
6192 "operation": "write",
6193 "action": "stop" },
6194 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6195 BLOCK_JOB_COMPLETED (Event) Emitted when a block job has completed
6197 Arguments:
6199 "type: JobType"
6201 job type
6202 "device: string"
6204 The job identifier. Originally the device name but other values are
6205 allowed since QEMU 2.7
6206 "len: int"
6208 maximum progress value
6209 "offset: int"
6211 current progress value. On success this is equal to len. On
6212 failure this is less than len
6213 "speed: int"
6215 rate limit, bytes per second
6216 "error: string" (optional)
6218 error message. Only present on failure. This field contains a
6219 human-readable error message. There are no semantics other than
6220 that streaming has failed and clients should not try to interpret
6221 the error string
6222 Since: 1.1
6224 Example:
6226 <- { "event": "BLOCK_JOB_COMPLETED",
6228 "data": { "type": "stream", "device": "virtio-disk0",
6229 "len": 10737418240, "offset": 10737418240,
6230 "speed": 0 },
6231 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6232 BLOCK_JOB_CANCELLED (Event) Emitted when a block job has been
6234 cancelled
6235 Arguments:
6237 "type: JobType"
6239 job type
6240 "device: string"
6242 The job identifier. Originally the device name but other values are
6243 allowed since QEMU 2.7
6244 "len: int"
6246 maximum progress value
6247 "offset: int"
6249 current progress value. On success this is equal to len. On
6250 failure this is less than len
6251 "speed: int"
6253 rate limit, bytes per second
6254 Since: 1.1
6256 Example:
6258 <- { "event": "BLOCK_JOB_CANCELLED",
6260 "data": { "type": "stream", "device": "virtio-disk0",
6261 "len": 10737418240, "offset": 134217728,
6262 "speed": 0 },
6263 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6264 BLOCK_JOB_ERROR (Event) Emitted when a block job encounters an error
6266 Arguments:
6268 "device: string"
6270 The job identifier. Originally the device name but other values are
6271 allowed since QEMU 2.7
6272 "operation: IoOperationType"
6274 I/O operation
6275 "action: BlockErrorAction"
6277 action that has been taken
6278 Since: 1.3
6280 Example:
6282 <- { "event": "BLOCK_JOB_ERROR",
6284 "data": { "device": "ide0-hd1",
6285 "operation": "write",
6286 "action": "stop" },
6287 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6288 BLOCK_JOB_READY (Event) Emitted when a block job is ready to complete
6290 Arguments:
6292 "type: JobType"
6294 job type
6295 "device: string"
6297 The job identifier. Originally the device name but other values are
6298 allowed since QEMU 2.7
6299 "len: int"
6301 maximum progress value
6302 "offset: int"
6304 current progress value. On success this is equal to len. On
6305 failure this is less than len
6306 "speed: int"
6308 rate limit, bytes per second
6309 Note: The "ready to complete" status is always reset by a
6311 "BLOCK_JOB_ERROR" event
6312 Since: 1.3
6314 Example:
6316 <- { "event": "BLOCK_JOB_READY",
6318 "data": { "device": "drive0", "type": "mirror", "speed": 0,
6319 "len": 2097152, "offset": 2097152 }
6320 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6321 BLOCK_JOB_PENDING (Event) Emitted when a block job is awaiting
6323 explicit authorization to finalize graph changes via
6324 "block-job-finalize". If this job is part of a transaction, it will not
6325 emit this event until the transaction has converged first.
6326 Arguments:
6328 "type: JobType"
6330 job type
6331 "id: string"
6333 The job identifier.
6334 Since: 2.12
6336 Example:
6338 <- { "event": "BLOCK_JOB_WAITING",
6340 "data": { "device": "drive0", "type": "mirror" },
6341 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6342 PreallocMode (Enum)
6344 Preallocation mode of QEMU image file
6346 Values:
6348 "off"
6350 no preallocation
6351 "metadata"
6353 preallocate only for metadata
6354 "falloc"
6356 like "full" preallocation but allocate disk space by
6357 posix_fallocate() rather than writing zeros.
6358 "full"
6360 preallocate all data by writing zeros to device to ensure disk
6361 space is really available. "full" preallocation also sets up
6362 metadata correctly.
6363 Since: 2.2
6365 BLOCK_WRITE_THRESHOLD (Event) Emitted when writes on block device
6367 reaches or exceeds the configured write threshold. For thin-provisioned
6368 devices, this means the device should be extended to avoid pausing for
6369 disk exhaustion. The event is one shot. Once triggered, it needs to be
6370 re-registered with another block-set-write-threshold command.
6371 Arguments:
6373 "node-name: string"
6375 graph node name on which the threshold was exceeded.
6376 "amount-exceeded: int"
6378 amount of data which exceeded the threshold, in bytes.
6379 "write-threshold: int"
6381 last configured threshold, in bytes.
6382 Since: 2.3
6384 block-set-write-threshold (Command) Change the write threshold for a
6386 block drive. An event will be delivered if a write to this block drive
6387 crosses the configured threshold. The threshold is an offset, thus
6388 must be non-negative. Default is no write threshold. Setting the
6389 threshold to zero disables it.
6390 This is useful to transparently resize thin-provisioned drives without
6392 the guest OS noticing.
6393 Arguments:
6395 "node-name: string"
6397 graph node name on which the threshold must be set.
6398 "write-threshold: int"
6400 configured threshold for the block device, bytes. Use 0 to disable
6401 the threshold.
6402 Since: 2.3
6404 Example:
6406 -> { "execute": "block-set-write-threshold",
6408 "arguments": { "node-name": "mydev",
6409 "write-threshold": 17179869184 } }
6410 <- { "return": {} }
6411 x-blockdev-change (Command) Dynamically reconfigure the block driver
6413 state graph. It can be used to add, remove, insert or replace a graph
6414 node. Currently only the Quorum driver implements this feature to add
6415 or remove its child. This is useful to fix a broken quorum child.
6416 If "node" is specified, it will be inserted under "parent". "child" may
6418 not be specified in this case. If both "parent" and "child" are
6419 specified but "node" is not, "child" will be detached from "parent".
6420 Arguments:
6422 "parent: string"
6424 the id or name of the parent node.
6425 "child: string" (optional)
6427 the name of a child under the given parent node.
6428 "node: string" (optional)
6430 the name of the node that will be added.
6431 Note: this command is experimental, and its API is not stable. It does
6433 not support all kinds of operations, all kinds of children, nor all
6434 block drivers.
6435 FIXME Removing children from a quorum node means introducing gaps in
6437 the child indices. This cannot be represented in the 'children' list of
6438 BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename().
6439 Warning: The data in a new quorum child MUST be consistent with that of
6441 the rest of the array.
6442 Since: 2.7
6444 Example:
6446 1. Add a new node to a quorum
6448 -> { "execute": "blockdev-add",
6449 "arguments": {
6450 "driver": "raw",
6451 "node-name": "new_node",
6452 "file": { "driver": "file",
6453 "filename": "test.raw" } } }
6454 <- { "return": {} }
6455 -> { "execute": "x-blockdev-change",
6456 "arguments": { "parent": "disk1",
6457 "node": "new_node" } }
6458 <- { "return": {} }
6459 2. Delete a quorum's node
6461 -> { "execute": "x-blockdev-change",
6462 "arguments": { "parent": "disk1",
6463 "child": "children.1" } }
6464 <- { "return": {} }
6465 x-blockdev-set-iothread (Command) Move "node" and its children into
6467 the "iothread". If "iothread" is null then move "node" and its
6468 children into the main loop.
6469 The node must not be attached to a BlockBackend.
6471 Arguments:
6473 "node-name: string"
6475 the name of the block driver node
6476 "iothread: StrOrNull"
6478 the name of the IOThread object or null for the main loop
6479 "force: boolean" (optional)
6481 true if the node and its children should be moved when a
6482 BlockBackend is already attached
6483 Note: this command is experimental and intended for test cases that
6485 need control over IOThreads only.
6486 Since: 2.12
6488 Example:
6490 1. Move a node into an IOThread
6492 -> { "execute": "x-blockdev-set-iothread",
6493 "arguments": { "node-name": "disk1",
6494 "iothread": "iothread0" } }
6495 <- { "return": {} }
6496 2. Move a node into the main loop
6498 -> { "execute": "x-blockdev-set-iothread",
6499 "arguments": { "node-name": "disk1",
6500 "iothread": null } }
6501 <- { "return": {} }
6502 Additional block stuff (VM related)
6504 BiosAtaTranslation (Enum)
6506 Policy that BIOS should use to interpret cylinder/head/sector
6508 addresses. Note that Bochs BIOS and SeaBIOS will not actually
6509 translate logical CHS to physical; instead, they will use logical block
6510 addressing.
6511 Values:
6513 "auto"
6515 If cylinder/heads/sizes are passed, choose between none and LBA
6516 depending on the size of the disk. If they are not passed, choose
6517 none if QEMU can guess that the disk had 16 or fewer heads, large
6518 if QEMU can guess that the disk had 131072 or fewer tracks across
6519 all heads (i.e. cylinders*heads<131072), otherwise LBA.
6520 "none"
6522 The physical disk geometry is equal to the logical geometry.
6523 "lba"
6525 Assume 63 sectors per track and one of 16, 32, 64, 128 or 255 heads
6526 (if fewer than 255 are enough to cover the whole disk with 1024
6527 cylinders/head). The number of cylinders/head is then computed
6528 based on the number of sectors and heads.
6529 "large"
6531 The number of cylinders per head is scaled down to 1024 by
6532 correspondingly scaling up the number of heads.
6533 "rechs"
6535 Same as "large", but first convert a 16-head geometry to 15-head,
6536 by proportionally scaling up the number of cylinders/head.
6537 Since: 2.0
6539 FloppyDriveType (Enum)
6541 Type of Floppy drive to be emulated by the Floppy Disk Controller.
6543 Values:
6545 144 1.44MB 3.5" drive
6547 288 2.88MB 3.5" drive
6549 120 1.2MB 5.25" drive
6551 "none"
6553 No drive connected
6554 "auto"
6556 Automatically determined by inserted media at boot
6557 Since: 2.6
6559 BlockdevSnapshotInternal (Object)
6561 Members:
6563 "device: string"
6565 the device name or node-name of a root node to generate the
6566 snapshot from
6567 "name: string"
6569 the name of the internal snapshot to be created
6570 Notes: In transaction, if "name" is empty, or any snapshot matching
6572 "name" exists, the operation will fail. Only some image formats support
6573 it, for example, qcow2, rbd, and sheepdog.
6574 Since: 1.7
6576 PRManagerInfo (Object)
6578 Information about a persistent reservation manager
6580 Members:
6582 "id: string"
6584 the identifier of the persistent reservation manager
6585 "connected: boolean"
6587 true if the persistent reservation manager is connected to the
6588 underlying storage or helper
6589 Since: 3.0
6591 query-pr-managers (Command) Returns a list of information about each
6593 persistent reservation manager.
6594 Returns: a list of "PRManagerInfo" for each persistent reservation
6596 manager
6597 Since: 3.0
6599 blockdev-snapshot-internal-sync (Command) Synchronously take an
6601 internal snapshot of a block device, when the format of the image used
6602 supports it. If the name is an empty string, or a snapshot with name
6603 already exists, the operation will fail.
6604 For the arguments, see the documentation of BlockdevSnapshotInternal.
6606 Returns: nothing on success
6608 If "device" is not a valid block device, GenericError
6610 If any snapshot matching "name" exists, or "name" is empty,
6612 GenericError
6613 If the format of the image used does not support it,
6615 BlockFormatFeatureNotSupported
6616 Since: 1.7
6618 Example:
6620 -> { "execute": "blockdev-snapshot-internal-sync",
6622 "arguments": { "device": "ide-hd0",
6623 "name": "snapshot0" }
6624 }
6625 <- { "return": {} }
6626 blockdev-snapshot-delete-internal-sync (Command) Synchronously delete
6628 an internal snapshot of a block device, when the format of the image
6629 used support it. The snapshot is identified by name or id or both. One
6630 of the name or id is required. Return SnapshotInfo for the successfully
6631 deleted snapshot.
6632 Arguments:
6634 "device: string"
6636 the device name or node-name of a root node to delete the snapshot
6637 from
6638 "id: string" (optional)
6640 optional the snapshot's ID to be deleted
6641 "name: string" (optional)
6643 optional the snapshot's name to be deleted
6644 Returns: SnapshotInfo on success If "device" is not a valid block
6646 device, GenericError If snapshot not found, GenericError If the format
6647 of the image used does not support it, BlockFormatFeatureNotSupported
6648 If "id" and "name" are both not specified, GenericError
6649 Since: 1.7
6651 Example:
6653 -> { "execute": "blockdev-snapshot-delete-internal-sync",
6655 "arguments": { "device": "ide-hd0",
6656 "name": "snapshot0" }
6657 }
6658 <- { "return": {
6659 "id": "1",
6660 "name": "snapshot0",
6661 "vm-state-size": 0,
6662 "date-sec": 1000012,
6663 "date-nsec": 10,
6664 "vm-clock-sec": 100,
6665 "vm-clock-nsec": 20
6666 }
6667 }
6668 eject (Command) Ejects a device from a removable drive.
6670 Arguments:
6672 "device: string" (optional)
6674 Block device name (deprecated, use "id" instead)
6675 "id: string" (optional)
6677 The name or QOM path of the guest device (since: 2.8)
6678 "force: boolean" (optional)
6680 If true, eject regardless of whether the drive is locked. If not
6681 specified, the default value is false.
6682 Returns: Nothing on success
6684 If "device" is not a valid block device, DeviceNotFound
6686 Notes: Ejecting a device with no media results in success
6688 Since: 0.14.0
6690 Example:
6692 -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
6694 <- { "return": {} }
6695 nbd-server-start (Command) Start an NBD server listening on the given
6697 host and port. Block devices can then be exported using
6698 "nbd-server-add". The NBD server will present them as named exports;
6699 for example, another QEMU instance could refer to them as
6700 "nbd:HOST:PORT:exportname=NAME".
6701 Arguments:
6703 "addr: SocketAddressLegacy"
6705 Address on which to listen.
6706 "tls-creds: string" (optional)
6708 (optional) ID of the TLS credentials object. Since 2.6
6709 Returns: error if the server is already running.
6711 Since: 1.3.0
6713 nbd-server-add (Command) Export a block node to QEMU's embedded NBD
6715 server.
6716 Arguments:
6718 "device: string"
6720 The device name or node name of the node to be exported
6721 "name: string" (optional)
6723 Export name. If unspecified, the "device" parameter is used as the
6724 export name. (Since 2.12)
6725 "writable: boolean" (optional)
6727 Whether clients should be able to write to the device via the NBD
6728 connection (default false).
6729 Returns: error if the server is not running, or export with the same
6731 name already exists.
6732 Since: 1.3.0
6734 NbdServerRemoveMode (Enum)
6736 Mode for removing an NBD export.
6738 Values:
6740 "safe"
6742 Remove export if there are no existing connections, fail otherwise.
6743 "hard"
6745 Drop all connections immediately and remove export.
6746 Potential additional modes to be added in the future:
6748 hide: Just hide export from new clients, leave existing connections as
6750 is. Remove export after all clients are disconnected.
6751 soft: Hide export from new clients, answer with ESHUTDOWN for all
6753 further requests from existing clients.
6754 Since: 2.12
6756 nbd-server-remove (Command) Remove NBD export by name.
6758 Arguments:
6760 "name: string"
6762 Export name.
6763 "mode: NbdServerRemoveMode" (optional)
6765 Mode of command operation. See "NbdServerRemoveMode" description.
6766 Default is 'safe'.
6767 Returns: error if
6769 - the server is not running
6771 - export is not found
6773 - mode is 'safe' and there are existing connections
6775 Since: 2.12
6777 x-nbd-server-add-bitmap (Command) Expose a dirty bitmap associated
6779 with the selected export. The bitmap search starts at the device
6780 attached to the export, and includes all backing files. The exported
6781 bitmap is then locked until the NBD export is removed.
6782 Arguments:
6784 "name: string"
6786 Export name.
6787 "bitmap: string"
6789 Bitmap name to search for.
6790 "bitmap-export-name: string" (optional)
6792 How the bitmap will be seen by nbd clients (default "bitmap")
6793 Note: the client must use NBD_OPT_SET_META_CONTEXT with a query of
6795 "qemu:dirty-bitmap:NAME" (where NAME matches "bitmap-export-name") to
6796 access the exposed bitmap.
6797 Since: 3.0
6799 nbd-server-stop (Command) Stop QEMU's embedded NBD server, and
6801 unregister all devices previously added via "nbd-server-add".
6802 Since: 1.3.0
6804 DEVICE_TRAY_MOVED (Event) Emitted whenever the tray of a removable
6806 device is moved by the guest or by HMP/QMP commands
6807 Arguments:
6809 "device: string"
6811 Block device name. This is always present for compatibility
6812 reasons, but it can be empty ("") if the image does not have a
6813 device name associated.
6814 "id: string"
6816 The name or QOM path of the guest device (since 2.8)
6817 "tray-open: boolean"
6819 true if the tray has been opened or false if it has been closed
6820 Since: 1.1
6822 Example:
6824 <- { "event": "DEVICE_TRAY_MOVED",
6826 "data": { "device": "ide1-cd0",
6827 "id": "/machine/unattached/device[22]",
6828 "tray-open": true
6829 },
6830 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6831 PR_MANAGER_STATUS_CHANGED (Event) Emitted whenever the connected
6833 status of a persistent reservation manager changes.
6834 Arguments:
6836 "id: string"
6838 The id of the PR manager object
6839 "connected: boolean"
6841 true if the PR manager is connected to a backend
6842 Since: 3.0
6844 Example:
6846 <- { "event": "PR_MANAGER_STATUS_CHANGED",
6848 "data": { "id": "pr-helper0",
6849 "connected": true
6850 },
6851 "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
6852 QuorumOpType (Enum)
6854 An enumeration of the quorum operation types
6856 Values:
6858 "read"
6860 read operation
6861 "write"
6863 write operation
6864 "flush"
6866 flush operation
6867 Since: 2.6
6869 QUORUM_FAILURE (Event) Emitted by the Quorum block driver if it fails
6871 to establish a quorum
6872 Arguments:
6874 "reference: string"
6876 device name if defined else node name
6877 "sector-num: int"
6879 number of the first sector of the failed read operation
6880 "sectors-count: int"
6882 failed read operation sector count
6883 Note: This event is rate-limited.
6885 Since: 2.0
6887 Example:
6889 <- { "event": "QUORUM_FAILURE",
6891 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
6892 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
6893 QUORUM_REPORT_BAD (Event) Emitted to report a corruption of a Quorum
6895 file
6896 Arguments:
6898 "type: QuorumOpType"
6900 quorum operation type (Since 2.6)
6901 "error: string" (optional)
6903 error message. Only present on failure. This field contains a
6904 human-readable error message. There are no semantics other than
6905 that the block layer reported an error and clients should not try
6906 to interpret the error string.
6907 "node-name: string"
6909 the graph node name of the block driver state
6910 "sector-num: int"
6912 number of the first sector of the failed read operation
6913 "sectors-count: int"
6915 failed read operation sector count
6916 Note: This event is rate-limited.
6918 Since: 2.0
6920 Example:
6922 1. Read operation
6924 { "event": "QUORUM_REPORT_BAD",
6926 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
6927 "type": "read" },
6928 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
6929 2. Flush operation
6931 { "event": "QUORUM_REPORT_BAD",
6933 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
6934 "type": "flush", "error": "Broken pipe" },
6935 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
6936 Character devices
6938 ChardevInfo (Object)
6939 Information about a character device.
6941 Members:
6943 "label: string"
6945 the label of the character device
6946 "filename: string"
6948 the filename of the character device
6949 "frontend-open: boolean"
6951 shows whether the frontend device attached to this backend (eg.
6952 with the chardev=... option) is in open or closed state (since 2.1)
6953 Notes: "filename" is encoded using the QEMU command line character
6955 device encoding. See the QEMU man page for details.
6956 Since: 0.14.0
6958 query-chardev (Command) Returns information about current character
6960 devices.
6961 Returns: a list of "ChardevInfo"
6963 Since: 0.14.0
6965 Example:
6967 -> { "execute": "query-chardev" }
6969 <- {
6970 "return": [
6971 {
6972 "label": "charchannel0",
6973 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
6974 "frontend-open": false
6975 },
6976 {
6977 "label": "charmonitor",
6978 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
6979 "frontend-open": true
6980 },
6981 {
6982 "label": "charserial0",
6983 "filename": "pty:/dev/pts/2",
6984 "frontend-open": true
6985 }
6986 ]
6987 }
6988 ChardevBackendInfo (Object)
6990 Information about a character device backend
6992 Members:
6994 "name: string"
6996 The backend name
6997 Since: 2.0
6999 query-chardev-backends (Command) Returns information about character
7001 device backends.
7002 Returns: a list of "ChardevBackendInfo"
7004 Since: 2.0
7006 Example:
7008 -> { "execute": "query-chardev-backends" }
7010 <- {
7011 "return":[
7012 {
7013 "name":"udp"
7014 },
7015 {
7016 "name":"tcp"
7017 },
7018 {
7019 "name":"unix"
7020 },
7021 {
7022 "name":"spiceport"
7023 }
7024 ]
7025 }
7026 DataFormat (Enum)
7028 An enumeration of data format.
7030 Values:
7032 "utf8"
7034 Data is a UTF-8 string (RFC 3629)
7035 "base64"
7037 Data is Base64 encoded binary (RFC 3548)
7038 Since: 1.4
7040 ringbuf-write (Command) Write to a ring buffer character device.
7042 Arguments:
7044 "device: string"
7046 the ring buffer character device name
7047 "data: string"
7049 data to write
7050 "format: DataFormat" (optional)
7052 data encoding (default 'utf8').
7053 - base64: data must be base64 encoded text. Its binary decoding
7055 gets written.
7056 - utf8: data's UTF-8 encoding is written
7058 - data itself is always Unicode regardless of format, like any
7060 other string.
7061 Returns: Nothing on success
7063 Since: 1.4
7065 Example:
7067 -> { "execute": "ringbuf-write",
7069 "arguments": { "device": "foo",
7070 "data": "abcdefgh",
7071 "format": "utf8" } }
7072 <- { "return": {} }
7073 ringbuf-read (Command) Read from a ring buffer character device.
7075 Arguments:
7077 "device: string"
7079 the ring buffer character device name
7080 "size: int"
7082 how many bytes to read at most
7083 "format: DataFormat" (optional)
7085 data encoding (default 'utf8').
7086 - base64: the data read is returned in base64 encoding.
7088 - utf8: the data read is interpreted as UTF-8. Bug: can screw up
7090 when the buffer contains invalid UTF-8 sequences, NUL
7091 characters, after the ring buffer lost data, and when reading
7092 stops because the size limit is reached.
7093 - The return value is always Unicode regardless of format, like
7095 any other string.
7096 Returns: data read from the device
7098 Since: 1.4
7100 Example:
7102 -> { "execute": "ringbuf-read",
7104 "arguments": { "device": "foo",
7105 "size": 1000,
7106 "format": "utf8" } }
7107 <- { "return": "abcdefgh" }
7108 ChardevCommon (Object)
7110 Configuration shared across all chardev backends
7112 Members:
7114 "logfile: string" (optional)
7116 The name of a logfile to save output
7117 "logappend: boolean" (optional)
7119 true to append instead of truncate (default to false to truncate)
7120 Since: 2.6
7122 ChardevFile (Object)
7124 Configuration info for file chardevs.
7126 Members:
7128 "in: string" (optional)
7130 The name of the input file
7131 "out: string"
7133 The name of the output file
7134 "append: boolean" (optional)
7136 Open the file in append mode (default false to truncate) (Since
7137 2.6)
7138 The members of "ChardevCommon"
7140 Since: 1.4
7142 ChardevHostdev (Object)
7144 Configuration info for device and pipe chardevs.
7146 Members:
7148 "device: string"
7150 The name of the special file for the device, i.e. /dev/ttyS0 on
7151 Unix or COM1: on Windows
7152 The members of "ChardevCommon"
7154 Since: 1.4
7156 ChardevSocket (Object)
7158 Configuration info for (stream) socket chardevs.
7160 Members:
7162 "addr: SocketAddressLegacy"
7164 socket address to listen on (server=true) or connect to
7165 (server=false)
7166 "tls-creds: string" (optional)
7168 the ID of the TLS credentials object (since 2.6)
7169 "server: boolean" (optional)
7171 create server socket (default: true)
7172 "wait: boolean" (optional)
7174 wait for incoming connection on server sockets (default: false).
7175 "nodelay: boolean" (optional)
7177 set TCP_NODELAY socket option (default: false)
7178 "telnet: boolean" (optional)
7180 enable telnet protocol on server sockets (default: false)
7181 "tn3270: boolean" (optional)
7183 enable tn3270 protocol on server sockets (default: false) (Since:
7184 2.10)
7185 "reconnect: int" (optional)
7187 For a client socket, if a socket is disconnected, then attempt a
7188 reconnect after the given number of seconds. Setting this to zero
7189 disables this function. (default: 0) (Since: 2.2)
7190 The members of "ChardevCommon"
7192 Since: 1.4
7194 ChardevUdp (Object)
7196 Configuration info for datagram socket chardevs.
7198 Members:
7200 "remote: SocketAddressLegacy"
7202 remote address
7203 "local: SocketAddressLegacy" (optional)
7205 local address
7206 The members of "ChardevCommon"
7208 Since: 1.5
7210 ChardevMux (Object)
7212 Configuration info for mux chardevs.
7214 Members:
7216 "chardev: string"
7218 name of the base chardev.
7219 The members of "ChardevCommon"
7221 Since: 1.5
7223 ChardevStdio (Object)
7225 Configuration info for stdio chardevs.
7227 Members:
7229 "signal: boolean" (optional)
7231 Allow signals (such as SIGINT triggered by ^C) be delivered to
7232 qemu. Default: true in -nographic mode, false otherwise.
7233 The members of "ChardevCommon"
7235 Since: 1.5
7237 ChardevSpiceChannel (Object)
7239 Configuration info for spice vm channel chardevs.
7241 Members:
7243 "type: string"
7245 kind of channel (for example vdagent).
7246 The members of "ChardevCommon"
7248 Since: 1.5
7250 ChardevSpicePort (Object)
7252 Configuration info for spice port chardevs.
7254 Members:
7256 "fqdn: string"
7258 name of the channel (see docs/spice-port-fqdn.txt)
7259 The members of "ChardevCommon"
7261 Since: 1.5
7263 ChardevVC (Object)
7265 Configuration info for virtual console chardevs.
7267 Members:
7269 "width: int" (optional)
7271 console width, in pixels
7272 "height: int" (optional)
7274 console height, in pixels
7275 "cols: int" (optional)
7277 console width, in chars
7278 "rows: int" (optional)
7280 console height, in chars
7281 The members of "ChardevCommon"
7283 Since: 1.5
7285 ChardevRingbuf (Object)
7287 Configuration info for ring buffer chardevs.
7289 Members:
7291 "size: int" (optional)
7293 ring buffer size, must be power of two, default is 65536
7294 The members of "ChardevCommon"
7296 Since: 1.5
7298 ChardevBackend (Object)
7300 Configuration info for the new chardev backend.
7302 Members:
7304 "type"
7306 One of "file", "serial", "parallel", "pipe", "socket", "udp",
7307 "pty", "null", "mux", "msmouse", "wctablet", "braille", "testdev",
7308 "stdio", "console", "spicevmc", "spiceport", "vc", "ringbuf",
7309 "memory"
7310 "data: ChardevFile" when "type" is "file"
7312 "data: ChardevHostdev" when "type" is "serial"
7313 "data: ChardevHostdev" when "type" is "parallel"
7314 "data: ChardevHostdev" when "type" is "pipe"
7315 "data: ChardevSocket" when "type" is "socket"
7316 "data: ChardevUdp" when "type" is "udp"
7317 "data: ChardevCommon" when "type" is "pty"
7318 "data: ChardevCommon" when "type" is "null"
7319 "data: ChardevMux" when "type" is "mux"
7320 "data: ChardevCommon" when "type" is "msmouse"
7321 "data: ChardevCommon" when "type" is "wctablet"
7322 "data: ChardevCommon" when "type" is "braille"
7323 "data: ChardevCommon" when "type" is "testdev"
7324 "data: ChardevStdio" when "type" is "stdio"
7325 "data: ChardevCommon" when "type" is "console"
7326 "data: ChardevSpiceChannel" when "type" is "spicevmc"
7327 "data: ChardevSpicePort" when "type" is "spiceport"
7328 "data: ChardevVC" when "type" is "vc"
7329 "data: ChardevRingbuf" when "type" is "ringbuf"
7330 "data: ChardevRingbuf" when "type" is "memory"
7331 Since: 1.4 (testdev since 2.2, wctablet since 2.9)
7333 ChardevReturn (Object)
7335 Return info about the chardev backend just created.
7337 Members:
7339 "pty: string" (optional)
7341 name of the slave pseudoterminal device, present if and only if a
7342 chardev of type 'pty' was created
7343 Since: 1.4
7345 chardev-add (Command) Add a character device backend
7347 Arguments:
7349 "id: string"
7351 the chardev's ID, must be unique
7352 "backend: ChardevBackend"
7354 backend type and parameters
7355 Returns: ChardevReturn.
7357 Since: 1.4
7359 Example:
7361 -> { "execute" : "chardev-add",
7363 "arguments" : { "id" : "foo",
7364 "backend" : { "type" : "null", "data" : {} } } }
7365 <- { "return": {} }
7366 -> { "execute" : "chardev-add",
7368 "arguments" : { "id" : "bar",
7369 "backend" : { "type" : "file",
7370 "data" : { "out" : "/tmp/bar.log" } } } }
7371 <- { "return": {} }
7372 -> { "execute" : "chardev-add",
7374 "arguments" : { "id" : "baz",
7375 "backend" : { "type" : "pty", "data" : {} } } }
7376 <- { "return": { "pty" : "/dev/pty/42" } }
7377 chardev-change (Command) Change a character device backend
7379 Arguments:
7381 "id: string"
7383 the chardev's ID, must exist
7384 "backend: ChardevBackend"
7386 new backend type and parameters
7387 Returns: ChardevReturn.
7389 Since: 2.10
7391 Example:
7393 -> { "execute" : "chardev-change",
7395 "arguments" : { "id" : "baz",
7396 "backend" : { "type" : "pty", "data" : {} } } }
7397 <- { "return": { "pty" : "/dev/pty/42" } }
7398 -> {"execute" : "chardev-change",
7400 "arguments" : {
7401 "id" : "charchannel2",
7402 "backend" : {
7403 "type" : "socket",
7404 "data" : {
7405 "addr" : {
7406 "type" : "unix" ,
7407 "data" : {
7408 "path" : "/tmp/charchannel2.socket"
7409 }
7410 },
7411 "server" : true,
7412 "wait" : false }}}}
7413 <- {"return": {}}
7414 chardev-remove (Command) Remove a character device backend
7416 Arguments:
7418 "id: string"
7420 the chardev's ID, must exist and not be in use
7421 Returns: Nothing on success
7423 Since: 1.4
7425 Example:
7427 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
7429 <- { "return": {} }
7430 chardev-send-break (Command) Send a break to a character device
7432 Arguments:
7434 "id: string"
7436 the chardev's ID, must exist
7437 Returns: Nothing on success
7439 Since: 2.10
7441 Example:
7443 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
7445 <- { "return": {} }
7446 VSERPORT_CHANGE (Event) Emitted when the guest opens or closes a
7448 virtio-serial port.
7449 Arguments:
7451 "id: string"
7453 device identifier of the virtio-serial port
7454 "open: boolean"
7456 true if the guest has opened the virtio-serial port
7457 Since: 2.1
7459 Example:
7461 <- { "event": "VSERPORT_CHANGE",
7463 "data": { "id": "channel0", "open": true },
7464 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
7465 Net devices
7467 set_link (Command) Sets the link status of a virtual network adapter.
7468 Arguments:
7470 "name: string"
7472 the device name of the virtual network adapter
7473 "up: boolean"
7475 true to set the link status to be up
7476 Returns: Nothing on success If "name" is not a valid network device,
7478 DeviceNotFound
7479 Since: 0.14.0
7481 Notes: Not all network adapters support setting link status. This
7483 command will succeed even if the network adapter does not support link
7484 status notification.
7485 Example:
7487 -> { "execute": "set_link",
7489 "arguments": { "name": "e1000.0", "up": false } }
7490 <- { "return": {} }
7491 netdev_add (Command) Add a network backend.
7493 Arguments:
7495 "type: string"
7497 the type of network backend. Possible values are listed in
7498 NetClientDriver (excluding 'none' and 'nic')
7499 "id: string"
7501 the name of the new network backend
7502 Additional arguments depend on the type.
7504 TODO: This command effectively bypasses QAPI completely due to its
7506 "additional arguments" business. It shouldn't have been added to the
7507 schema in this form. It should be qapified properly, or replaced by a
7508 properly qapified command.
7509 Since: 0.14.0
7511 Returns: Nothing on success If "type" is not a valid network backend,
7513 DeviceNotFound
7514 Example:
7516 -> { "execute": "netdev_add",
7518 "arguments": { "type": "user", "id": "netdev1",
7519 "dnssearch": "example.org" } }
7520 <- { "return": {} }
7521 netdev_del (Command) Remove a network backend.
7523 Arguments:
7525 "id: string"
7527 the name of the network backend to remove
7528 Returns: Nothing on success If "id" is not a valid network backend,
7530 DeviceNotFound
7531 Since: 0.14.0
7533 Example:
7535 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
7537 <- { "return": {} }
7538 NetLegacyNicOptions (Object)
7540 Create a new Network Interface Card.
7542 Members:
7544 "netdev: string" (optional)
7546 id of -netdev to connect to
7547 "macaddr: string" (optional)
7549 MAC address
7550 "model: string" (optional)
7552 device model (e1000, rtl8139, virtio etc.)
7553 "addr: string" (optional)
7555 PCI device address
7556 "vectors: int" (optional)
7558 number of MSI-x vectors, 0 to disable MSI-X
7559 Since: 1.2
7561 NetdevUserOptions (Object)
7563 Use the user mode network stack which requires no administrator
7565 privilege to run.
7566 Members:
7568 "hostname: string" (optional)
7570 client hostname reported by the builtin DHCP server
7571 "restrict: boolean" (optional)
7573 isolate the guest from the host
7574 "ipv4: boolean" (optional)
7576 whether to support IPv4, default true for enabled (since 2.6)
7577 "ipv6: boolean" (optional)
7579 whether to support IPv6, default true for enabled (since 2.6)
7580 "ip: string" (optional)
7582 legacy parameter, use net= instead
7583 "net: string" (optional)
7585 IP network address that the guest will see, in the form
7586 addr[/netmask] The netmask is optional, and can be either in the
7587 form a.b.c.d or as a number of valid top-most bits. Default is
7588 10.0.2.0/24.
7589 "host: string" (optional)
7591 guest-visible address of the host
7592 "tftp: string" (optional)
7594 root directory of the built-in TFTP server
7595 "bootfile: string" (optional)
7597 BOOTP filename, for use with tftp=
7598 "dhcpstart: string" (optional)
7600 the first of the 16 IPs the built-in DHCP server can assign
7601 "dns: string" (optional)
7603 guest-visible address of the virtual nameserver
7604 "dnssearch: array of String" (optional)
7606 list of DNS suffixes to search, passed as DHCP option to the guest
7607 "domainname: string" (optional)
7609 guest-visible domain name of the virtual nameserver (since 3.0)
7610 "ipv6-prefix: string" (optional)
7612 IPv6 network prefix (default is fec0::) (since 2.6). The network
7613 prefix is given in the usual hexadecimal IPv6 address notation.
7614 "ipv6-prefixlen: int" (optional)
7616 IPv6 network prefix length (default is 64) (since 2.6)
7617 "ipv6-host: string" (optional)
7619 guest-visible IPv6 address of the host (since 2.6)
7620 "ipv6-dns: string" (optional)
7622 guest-visible IPv6 address of the virtual nameserver (since 2.6)
7623 "smb: string" (optional)
7625 root directory of the built-in SMB server
7626 "smbserver: string" (optional)
7628 IP address of the built-in SMB server
7629 "hostfwd: array of String" (optional)
7631 redirect incoming TCP or UDP host connections to guest endpoints
7632 "guestfwd: array of String" (optional)
7634 forward guest TCP connections
7635 Since: 1.2
7637 NetdevTapOptions (Object)
7639 Used to configure a host TAP network interface backend.
7641 Members:
7643 "ifname: string" (optional)
7645 interface name
7646 "fd: string" (optional)
7648 file descriptor of an already opened tap
7649 "fds: string" (optional)
7651 multiple file descriptors of already opened multiqueue capable tap
7652 "script: string" (optional)
7654 script to initialize the interface
7655 "downscript: string" (optional)
7657 script to shut down the interface
7658 "br: string" (optional)
7660 bridge name (since 2.8)
7661 "helper: string" (optional)
7663 command to execute to configure bridge
7664 "sndbuf: int" (optional)
7666 send buffer limit. Understands [TGMKkb] suffixes.
7667 "vnet_hdr: boolean" (optional)
7669 enable the IFF_VNET_HDR flag on the tap interface
7670 "vhost: boolean" (optional)
7672 enable vhost-net network accelerator
7673 "vhostfd: string" (optional)
7675 file descriptor of an already opened vhost net device
7676 "vhostfds: string" (optional)
7678 file descriptors of multiple already opened vhost net devices
7679 "vhostforce: boolean" (optional)
7681 vhost on for non-MSIX virtio guests
7682 "queues: int" (optional)
7684 number of queues to be created for multiqueue capable tap
7685 "poll-us: int" (optional)
7687 maximum number of microseconds that could be spent on busy polling
7688 for tap (since 2.7)
7689 Since: 1.2
7691 NetdevSocketOptions (Object)
7693 Socket netdevs are used to establish a network connection to another
7695 QEMU virtual machine via a TCP socket.
7696 Members:
7698 "fd: string" (optional)
7700 file descriptor of an already opened socket
7701 "listen: string" (optional)
7703 port number, and optional hostname, to listen on
7704 "connect: string" (optional)
7706 port number, and optional hostname, to connect to
7707 "mcast: string" (optional)
7709 UDP multicast address and port number
7710 "localaddr: string" (optional)
7712 source address and port for multicast and udp packets
7713 "udp: string" (optional)
7715 UDP unicast address and port number
7716 Since: 1.2
7718 NetdevL2TPv3Options (Object)
7720 Configure an Ethernet over L2TPv3 tunnel.
7722 Members:
7724 "src: string"
7726 source address
7727 "dst: string"
7729 destination address
7730 "srcport: string" (optional)
7732 source port - mandatory for udp, optional for ip
7733 "dstport: string" (optional)
7735 destination port - mandatory for udp, optional for ip
7736 "ipv6: boolean" (optional)
7738 force the use of ipv6
7739 "udp: boolean" (optional)
7741 use the udp version of l2tpv3 encapsulation
7742 "cookie64: boolean" (optional)
7744 use 64 bit coookies
7745 "counter: boolean" (optional)
7747 have sequence counter
7748 "pincounter: boolean" (optional)
7750 pin sequence counter to zero - workaround for buggy implementations
7751 or networks with packet reorder
7752 "txcookie: int" (optional)
7754 32 or 64 bit transmit cookie
7755 "rxcookie: int" (optional)
7757 32 or 64 bit receive cookie
7758 "txsession: int"
7760 32 bit transmit session
7761 "rxsession: int" (optional)
7763 32 bit receive session - if not specified set to the same value as
7764 transmit
7765 "offset: int" (optional)
7767 additional offset - allows the insertion of additional application-
7768 specific data before the packet payload
7769 Since: 2.1
7771 NetdevVdeOptions (Object)
7773 Connect to a vde switch running on the host.
7775 Members:
7777 "sock: string" (optional)
7779 socket path
7780 "port: int" (optional)
7782 port number
7783 "group: string" (optional)
7785 group owner of socket
7786 "mode: int" (optional)
7788 permissions for socket
7789 Since: 1.2
7791 NetdevBridgeOptions (Object)
7793 Connect a host TAP network interface to a host bridge device.
7795 Members:
7797 "br: string" (optional)
7799 bridge name
7800 "helper: string" (optional)
7802 command to execute to configure bridge
7803 Since: 1.2
7805 NetdevHubPortOptions (Object)
7807 Connect two or more net clients through a software hub.
7809 Members:
7811 "hubid: int"
7813 hub identifier number
7814 "netdev: string" (optional)
7816 used to connect hub to a netdev instead of a device (since 2.12)
7817 Since: 1.2
7819 NetdevNetmapOptions (Object)
7821 Connect a client to a netmap-enabled NIC or to a VALE switch port
7823 Members:
7825 "ifname: string"
7827 Either the name of an existing network interface supported by
7828 netmap, or the name of a VALE port (created on the fly). A VALE
7829 port name is in the form 'valeXXX:YYY', where XXX and YYY are non-
7830 negative integers. XXX identifies a switch and YYY identifies a
7831 port of the switch. VALE ports having the same XXX are therefore
7832 connected to the same switch.
7833 "devname: string" (optional)
7835 path of the netmap device (default: '/dev/netmap').
7836 Since: 2.0
7838 NetdevVhostUserOptions (Object)
7840 Vhost-user network backend
7842 Members:
7844 "chardev: string"
7846 name of a unix socket chardev
7847 "vhostforce: boolean" (optional)
7849 vhost on for non-MSIX virtio guests (default: false).
7850 "queues: int" (optional)
7852 number of queues to be created for multiqueue vhost-user (default:
7853 1) (Since 2.5)
7854 Since: 2.1
7856 NetClientDriver (Enum)
7858 Available netdev drivers.
7860 Values:
7862 "none"
7864 Not documented
7865 "nic"
7867 Not documented
7868 "user"
7870 Not documented
7871 "tap"
7873 Not documented
7874 "l2tpv3"
7876 Not documented
7877 "socket"
7879 Not documented
7880 "vde"
7882 Not documented
7883 "bridge"
7885 Not documented
7886 "hubport"
7888 Not documented
7889 "netmap"
7891 Not documented
7892 "vhost-user"
7894 Not documented
7895 Since: 2.7
7897 'dump': dropped in 2.12
7899 Netdev (Object)
7901 Captures the configuration of a network device.
7903 Members:
7905 "id: string"
7907 identifier for monitor commands.
7908 "type: NetClientDriver"
7910 Specify the driver used for interpreting remaining arguments.
7911 The members of "NetLegacyNicOptions" when "type" is "nic"
7913 The members of "NetdevUserOptions" when "type" is "user"
7914 The members of "NetdevTapOptions" when "type" is "tap"
7915 The members of "NetdevL2TPv3Options" when "type" is "l2tpv3"
7916 The members of "NetdevSocketOptions" when "type" is "socket"
7917 The members of "NetdevVdeOptions" when "type" is "vde"
7918 The members of "NetdevBridgeOptions" when "type" is "bridge"
7919 The members of "NetdevHubPortOptions" when "type" is "hubport"
7920 The members of "NetdevNetmapOptions" when "type" is "netmap"
7921 The members of "NetdevVhostUserOptions" when "type" is "vhost-user"
7922 Since: 1.2
7924 'l2tpv3' - since 2.1
7926 NetLegacy (Object)
7928 Captures the configuration of a network device; legacy.
7930 Members:
7932 "id: string" (optional)
7934 identifier for monitor commands
7935 "name: string" (optional)
7937 identifier for monitor commands, ignored if "id" is present
7938 "opts: NetLegacyOptions"
7940 device type specific properties (legacy)
7941 Since: 1.2
7943 'vlan': dropped in 3.0
7945 NetLegacyOptionsType (Enum)
7947 Values:
7949 "none"
7951 Not documented
7952 "nic"
7954 Not documented
7955 "user"
7957 Not documented
7958 "tap"
7960 Not documented
7961 "l2tpv3"
7963 Not documented
7964 "socket"
7966 Not documented
7967 "vde"
7969 Not documented
7970 "bridge"
7972 Not documented
7973 "netmap"
7975 Not documented
7976 "vhost-user"
7978 Not documented
7979 Since: 1.2
7981 NetLegacyOptions (Object)
7983 Like Netdev, but for use only by the legacy command line options
7985 Members:
7987 "type: NetLegacyOptionsType"
7989 Not documented
7990 The members of "NetLegacyNicOptions" when "type" is "nic"
7992 The members of "NetdevUserOptions" when "type" is "user"
7993 The members of "NetdevTapOptions" when "type" is "tap"
7994 The members of "NetdevL2TPv3Options" when "type" is "l2tpv3"
7995 The members of "NetdevSocketOptions" when "type" is "socket"
7996 The members of "NetdevVdeOptions" when "type" is "vde"
7997 The members of "NetdevBridgeOptions" when "type" is "bridge"
7998 The members of "NetdevNetmapOptions" when "type" is "netmap"
7999 The members of "NetdevVhostUserOptions" when "type" is "vhost-user"
8000 Since: 1.2
8002 NetFilterDirection (Enum)
8004 Indicates whether a netfilter is attached to a netdev's transmit queue
8006 or receive queue or both.
8007 Values:
8009 "all"
8011 the filter is attached both to the receive and the transmit queue
8012 of the netdev (default).
8013 "rx"
8015 the filter is attached to the receive queue of the netdev, where it
8016 will receive packets sent to the netdev.
8017 "tx"
8019 the filter is attached to the transmit queue of the netdev, where
8020 it will receive packets sent by the netdev.
8021 Since: 2.5
8023 RxState (Enum)
8025 Packets receiving state
8027 Values:
8029 "normal"
8031 filter assigned packets according to the mac-table
8032 "none"
8034 don't receive any assigned packet
8035 "all"
8037 receive all assigned packets
8038 Since: 1.6
8040 RxFilterInfo (Object)
8042 Rx-filter information for a NIC.
8044 Members:
8046 "name: string"
8048 net client name
8049 "promiscuous: boolean"
8051 whether promiscuous mode is enabled
8052 "multicast: RxState"
8054 multicast receive state
8055 "unicast: RxState"
8057 unicast receive state
8058 "vlan: RxState"
8060 vlan receive state (Since 2.0)
8061 "broadcast-allowed: boolean"
8063 whether to receive broadcast
8064 "multicast-overflow: boolean"
8066 multicast table is overflowed or not
8067 "unicast-overflow: boolean"
8069 unicast table is overflowed or not
8070 "main-mac: string"
8072 the main macaddr string
8073 "vlan-table: array of int"
8075 a list of active vlan id
8076 "unicast-table: array of string"
8078 a list of unicast macaddr string
8079 "multicast-table: array of string"
8081 a list of multicast macaddr string
8082 Since: 1.6
8084 query-rx-filter (Command) Return rx-filter information for all NICs
8086 (or for the given NIC).
8087 Arguments:
8089 "name: string" (optional)
8091 net client name
8092 Returns: list of "RxFilterInfo" for all NICs (or for the given NIC).
8094 Returns an error if the given "name" doesn't exist, or given NIC
8095 doesn't support rx-filter querying, or given net client isn't a NIC.
8096 Since: 1.6
8098 Example:
8100 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
8102 <- { "return": [
8103 {
8104 "promiscuous": true,
8105 "name": "vnet0",
8106 "main-mac": "52:54:00:12:34:56",
8107 "unicast": "normal",
8108 "vlan": "normal",
8109 "vlan-table": [
8110 4,
8111 0
8112 ],
8113 "unicast-table": [
8114 ],
8115 "multicast": "normal",
8116 "multicast-overflow": false,
8117 "unicast-overflow": false,
8118 "multicast-table": [
8119 "01:00:5e:00:00:01",
8120 "33:33:00:00:00:01",
8121 "33:33:ff:12:34:56"
8122 ],
8123 "broadcast-allowed": false
8124 }
8125 ]
8126 }
8127 NIC_RX_FILTER_CHANGED (Event) Emitted once until the 'query-rx-filter'
8129 command is executed, the first event will always be emitted
8130 Arguments:
8132 "name: string" (optional)
8134 net client name
8135 "path: string"
8137 device path
8138 Since: 1.6
8140 Example:
8142 <- { "event": "NIC_RX_FILTER_CHANGED",
8144 "data": { "name": "vnet0",
8145 "path": "/machine/peripheral/vnet0/virtio-backend" },
8146 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
8147 }
8148 Rocker switch device
8150 RockerSwitch (Object)
8151 Rocker switch information.
8153 Members:
8155 "name: string"
8157 switch name
8158 "id: int"
8160 switch ID
8161 "ports: int"
8163 number of front-panel ports
8164 Since: 2.4
8166 query-rocker (Command) Return rocker switch information.
8168 Arguments:
8170 "name: string"
8172 Not documented
8173 Returns: "Rocker" information
8175 Since: 2.4
8177 Example:
8179 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
8181 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
8182 RockerPortDuplex (Enum)
8184 An eumeration of port duplex states.
8186 Values:
8188 "half"
8190 half duplex
8191 "full"
8193 full duplex
8194 Since: 2.4
8196 RockerPortAutoneg (Enum)
8198 An eumeration of port autoneg states.
8200 Values:
8202 "off"
8204 autoneg is off
8205 "on"
8207 autoneg is on
8208 Since: 2.4
8210 RockerPort (Object)
8212 Rocker switch port information.
8214 Members:
8216 "name: string"
8218 port name
8219 "enabled: boolean"
8221 port is enabled for I/O
8222 "link-up: boolean"
8224 physical link is UP on port
8225 "speed: int"
8227 port link speed in Mbps
8228 "duplex: RockerPortDuplex"
8230 port link duplex
8231 "autoneg: RockerPortAutoneg"
8233 port link autoneg
8234 Since: 2.4
8236 query-rocker-ports (Command) Return rocker switch port information.
8238 Arguments:
8240 "name: string"
8242 Not documented
8243 Returns: a list of "RockerPort" information
8245 Since: 2.4
8247 Example:
8249 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
8251 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
8252 "autoneg": "off", "link-up": true, "speed": 10000},
8253 {"duplex": "full", "enabled": true, "name": "sw1.2",
8254 "autoneg": "off", "link-up": true, "speed": 10000}
8255 ]}
8256 RockerOfDpaFlowKey (Object)
8258 Rocker switch OF-DPA flow key
8260 Members:
8262 "priority: int"
8264 key priority, 0 being lowest priority
8265 "tbl-id: int"
8267 flow table ID
8268 "in-pport: int" (optional)
8270 physical input port
8271 "tunnel-id: int" (optional)
8273 tunnel ID
8274 "vlan-id: int" (optional)
8276 VLAN ID
8277 "eth-type: int" (optional)
8279 Ethernet header type
8280 "eth-src: string" (optional)
8282 Ethernet header source MAC address
8283 "eth-dst: string" (optional)
8285 Ethernet header destination MAC address
8286 "ip-proto: int" (optional)
8288 IP Header protocol field
8289 "ip-tos: int" (optional)
8291 IP header TOS field
8292 "ip-dst: string" (optional)
8294 IP header destination address
8295 Note: optional members may or may not appear in the flow key depending
8297 if they're relevant to the flow key.
8298 Since: 2.4
8300 RockerOfDpaFlowMask (Object)
8302 Rocker switch OF-DPA flow mask
8304 Members:
8306 "in-pport: int" (optional)
8308 physical input port
8309 "tunnel-id: int" (optional)
8311 tunnel ID
8312 "vlan-id: int" (optional)
8314 VLAN ID
8315 "eth-src: string" (optional)
8317 Ethernet header source MAC address
8318 "eth-dst: string" (optional)
8320 Ethernet header destination MAC address
8321 "ip-proto: int" (optional)
8323 IP Header protocol field
8324 "ip-tos: int" (optional)
8326 IP header TOS field
8327 Note: optional members may or may not appear in the flow mask depending
8329 if they're relevant to the flow mask.
8330 Since: 2.4
8332 RockerOfDpaFlowAction (Object)
8334 Rocker switch OF-DPA flow action
8336 Members:
8338 "goto-tbl: int" (optional)
8340 next table ID
8341 "group-id: int" (optional)
8343 group ID
8344 "tunnel-lport: int" (optional)
8346 tunnel logical port ID
8347 "vlan-id: int" (optional)
8349 VLAN ID
8350 "new-vlan-id: int" (optional)
8352 new VLAN ID
8353 "out-pport: int" (optional)
8355 physical output port
8356 Note: optional members may or may not appear in the flow action
8358 depending if they're relevant to the flow action.
8359 Since: 2.4
8361 RockerOfDpaFlow (Object)
8363 Rocker switch OF-DPA flow
8365 Members:
8367 "cookie: int"
8369 flow unique cookie ID
8370 "hits: int"
8372 count of matches (hits) on flow
8373 "key: RockerOfDpaFlowKey"
8375 flow key
8376 "mask: RockerOfDpaFlowMask"
8378 flow mask
8379 "action: RockerOfDpaFlowAction"
8381 flow action
8382 Since: 2.4
8384 query-rocker-of-dpa-flows (Command) Return rocker OF-DPA flow
8386 information.
8387 Arguments:
8389 "name: string"
8391 switch name
8392 "tbl-id: int" (optional)
8394 flow table ID. If tbl-id is not specified, returns flow
8395 information for all tables.
8396 Returns: rocker OF-DPA flow information
8398 Since: 2.4
8400 Example:
8402 -> { "execute": "query-rocker-of-dpa-flows",
8404 "arguments": { "name": "sw1" } }
8405 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
8406 "hits": 138,
8407 "cookie": 0,
8408 "action": {"goto-tbl": 10},
8409 "mask": {"in-pport": 4294901760}
8410 },
8411 {...more...},
8412 ]}
8413 RockerOfDpaGroup (Object)
8415 Rocker switch OF-DPA group
8417 Members:
8419 "id: int"
8421 group unique ID
8422 "type: int"
8424 group type
8425 "vlan-id: int" (optional)
8427 VLAN ID
8428 "pport: int" (optional)
8430 physical port number
8431 "index: int" (optional)
8433 group index, unique with group type
8434 "out-pport: int" (optional)
8436 output physical port number
8437 "group-id: int" (optional)
8439 next group ID
8440 "set-vlan-id: int" (optional)
8442 VLAN ID to set
8443 "pop-vlan: int" (optional)
8445 pop VLAN headr from packet
8446 "group-ids: array of int" (optional)
8448 list of next group IDs
8449 "set-eth-src: string" (optional)
8451 set source MAC address in Ethernet header
8452 "set-eth-dst: string" (optional)
8454 set destination MAC address in Ethernet header
8455 "ttl-check: int" (optional)
8457 perform TTL check
8458 Note: optional members may or may not appear in the group depending if
8460 they're relevant to the group type.
8461 Since: 2.4
8463 query-rocker-of-dpa-groups (Command) Return rocker OF-DPA group
8465 information.
8466 Arguments:
8468 "name: string"
8470 switch name
8471 "type: int" (optional)
8473 group type. If type is not specified, returns group information
8474 for all group types.
8475 Returns: rocker OF-DPA group information
8477 Since: 2.4
8479 Example:
8481 -> { "execute": "query-rocker-of-dpa-groups",
8483 "arguments": { "name": "sw1" } }
8484 <- { "return": [ {"type": 0, "out-pport": 2,
8485 "pport": 2, "vlan-id": 3841,
8486 "pop-vlan": 1, "id": 251723778},
8487 {"type": 0, "out-pport": 0,
8488 "pport": 0, "vlan-id": 3841,
8489 "pop-vlan": 1, "id": 251723776},
8490 {"type": 0, "out-pport": 1,
8491 "pport": 1, "vlan-id": 3840,
8492 "pop-vlan": 1, "id": 251658241},
8493 {"type": 0, "out-pport": 0,
8494 "pport": 0, "vlan-id": 3840,
8495 "pop-vlan": 1, "id": 251658240}
8496 ]}
8497 TPM (trusted platform module) devices
8499 TpmModel (Enum)
8500 An enumeration of TPM models
8502 Values:
8504 "tpm-tis"
8506 TPM TIS model
8507 "tpm-crb"
8509 TPM CRB model (since 2.12)
8510 Since: 1.5
8512 query-tpm-models (Command) Return a list of supported TPM models
8514 Returns: a list of TpmModel
8516 Since: 1.5
8518 Example:
8520 -> { "execute": "query-tpm-models" }
8522 <- { "return": [ "tpm-tis", "tpm-crb" ] }
8523 TpmType (Enum)
8525 An enumeration of TPM types
8527 Values:
8529 "passthrough"
8531 TPM passthrough type
8532 "emulator"
8534 Software Emulator TPM type Since: 2.11
8535 Since: 1.5
8537 query-tpm-types (Command) Return a list of supported TPM types
8539 Returns: a list of TpmType
8541 Since: 1.5
8543 Example:
8545 -> { "execute": "query-tpm-types" }
8547 <- { "return": [ "passthrough", "emulator" ] }
8548 TPMPassthroughOptions (Object)
8550 Information about the TPM passthrough type
8552 Members:
8554 "path: string" (optional)
8556 string describing the path used for accessing the TPM device
8557 "cancel-path: string" (optional)
8559 string showing the TPM's sysfs cancel file for cancellation of TPM
8560 commands while they are executing
8561 Since: 1.5
8563 TPMEmulatorOptions (Object)
8565 Information about the TPM emulator type
8567 Members:
8569 "chardev: string"
8571 Name of a unix socket chardev
8572 Since: 2.11
8574 TpmTypeOptions (Object)
8576 A union referencing different TPM backend types' configuration options
8578 Members:
8580 "type"
8582 'passthrough' The configuration options for the TPM passthrough
8583 type 'emulator' The configuration options for TPM emulator backend
8584 type
8585 "data: TPMPassthroughOptions" when "type" is "passthrough"
8587 "data: TPMEmulatorOptions" when "type" is "emulator"
8588 Since: 1.5
8590 TPMInfo (Object)
8592 Information about the TPM
8594 Members:
8596 "id: string"
8598 The Id of the TPM
8599 "model: TpmModel"
8601 The TPM frontend model
8602 "options: TpmTypeOptions"
8604 The TPM (backend) type configuration options
8605 Since: 1.5
8607 query-tpm (Command) Return information about the TPM device
8609 Returns: "TPMInfo" on success
8611 Since: 1.5
8613 Example:
8615 -> { "execute": "query-tpm" }
8617 <- { "return":
8618 [
8619 { "model": "tpm-tis",
8620 "options":
8621 { "type": "passthrough",
8622 "data":
8623 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
8624 "path": "/dev/tpm0"
8625 }
8626 },
8627 "id": "tpm0"
8628 }
8629 ]
8630 }
8631 Remote desktop
8633 set_password (Command) Sets the password of a remote display session.
8634 Arguments:
8636 "protocol: string"
8638 `vnc' to modify the VNC server password `spice' to modify the Spice
8639 server password
8640 "password: string"
8642 the new password
8643 "connected: string" (optional)
8645 how to handle existing clients when changing the password. If
8646 nothing is specified, defaults to `keep' `fail' to fail the command
8647 if clients are connected `disconnect' to disconnect existing
8648 clients `keep' to maintain existing clients
8649 Returns: Nothing on success If Spice is not enabled, DeviceNotFound
8651 Since: 0.14.0
8653 Example:
8655 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
8657 "password": "secret" } }
8658 <- { "return": {} }
8659 expire_password (Command) Expire the password of a remote display
8661 server.
8662 Arguments:
8664 "protocol: string"
8666 the name of the remote display protocol `vnc' or `spice'
8667 "time: string"
8669 when to expire the password. `now' to expire the password
8670 immediately `never' to cancel password expiration `+INT' where INT
8671 is the number of seconds from now (integer) `INT' where INT is the
8672 absolute time in seconds
8673 Returns: Nothing on success If "protocol" is `spice' and Spice is not
8675 active, DeviceNotFound
8676 Since: 0.14.0
8678 Notes: Time is relative to the server and currently there is no way to
8680 coordinate server time with client time. It is not recommended to use
8681 the absolute time version of the "time" parameter unless you're sure
8682 you are on the same machine as the QEMU instance.
8683 Example:
8685 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
8687 "time": "+60" } }
8688 <- { "return": {} }
8689 screendump (Command) Write a PPM of the VGA screen to a file.
8691 Arguments:
8693 "filename: string"
8695 the path of a new PPM file to store the image
8696 "device: string" (optional)
8698 ID of the display device that should be dumped. If this parameter
8699 is missing, the primary display will be used. (Since 2.12)
8700 "head: int" (optional)
8702 head to use in case the device supports multiple heads. If this
8703 parameter is missing, head #0 will be used. Also note that the head
8704 can only be specified in conjunction with the device ID. (Since
8705 2.12)
8706 Returns: Nothing on success
8708 Since: 0.14.0
8710 Example:
8712 -> { "execute": "screendump",
8714 "arguments": { "filename": "/tmp/image" } }
8715 <- { "return": {} }
8716 Spice
8718 SpiceBasicInfo (Object)
8720 The basic information for SPICE network connection
8722 Members:
8724 "host: string"
8726 IP address
8727 "port: string"
8729 port number
8730 "family: NetworkAddressFamily"
8732 address family
8733 Since: 2.1
8735 If: "defined(CONFIG_SPICE)"
8737 SpiceServerInfo (Object)
8739 Information about a SPICE server
8741 Members:
8743 "auth: string" (optional)
8745 authentication method
8746 The members of "SpiceBasicInfo"
8748 Since: 2.1
8750 If: "defined(CONFIG_SPICE)"
8752 SpiceChannel (Object)
8754 Information about a SPICE client channel.
8756 Members:
8758 "connection-id: int"
8760 SPICE connection id number. All channels with the same id belong
8761 to the same SPICE session.
8762 "channel-type: int"
8764 SPICE channel type number. "1" is the main control channel, filter
8765 for this one if you want to track spice sessions only
8766 "channel-id: int"
8768 SPICE channel ID number. Usually "0", might be different when
8769 multiple channels of the same type exist, such as multiple display
8770 channels in a multihead setup
8771 "tls: boolean"
8773 true if the channel is encrypted, false otherwise.
8774 The members of "SpiceBasicInfo"
8776 Since: 0.14.0
8778 If: "defined(CONFIG_SPICE)"
8780 SpiceQueryMouseMode (Enum)
8782 An enumeration of Spice mouse states.
8784 Values:
8786 "client"
8788 Mouse cursor position is determined by the client.
8789 "server"
8791 Mouse cursor position is determined by the server.
8792 "unknown"
8794 No information is available about mouse mode used by the spice
8795 server.
8796 Note: spice/enums.h has a SpiceMouseMode already, hence the name.
8798 Since: 1.1
8800 If: "defined(CONFIG_SPICE)"
8802 SpiceInfo (Object)
8804 Information about the SPICE session.
8806 Members:
8808 "enabled: boolean"
8810 true if the SPICE server is enabled, false otherwise
8811 "migrated: boolean"
8813 true if the last guest migration completed and spice migration had
8814 completed as well. false otherwise. (since 1.4)
8815 "host: string" (optional)
8817 The hostname the SPICE server is bound to. This depends on the
8818 name resolution on the host and may be an IP address.
8819 "port: int" (optional)
8821 The SPICE server's port number.
8822 "compiled-version: string" (optional)
8824 SPICE server version.
8825 "tls-port: int" (optional)
8827 The SPICE server's TLS port number.
8828 "auth: string" (optional)
8830 the current authentication type used by the server 'none' if no
8831 authentication is being used 'spice' uses SASL or direct TLS
8832 authentication, depending on command line options
8833 "mouse-mode: SpiceQueryMouseMode"
8835 The mode in which the mouse cursor is displayed currently. Can be
8836 determined by the client or the server, or unknown if spice server
8837 doesn't provide this information. (since: 1.1)
8838 "channels: array of SpiceChannel" (optional)
8840 a list of "SpiceChannel" for each active spice channel
8841 Since: 0.14.0
8843 If: "defined(CONFIG_SPICE)"
8845 query-spice (Command) Returns information about the current SPICE
8847 server
8848 Returns: "SpiceInfo"
8850 Since: 0.14.0
8852 Example:
8854 -> { "execute": "query-spice" }
8856 <- { "return": {
8857 "enabled": true,
8858 "auth": "spice",
8859 "port": 5920,
8860 "tls-port": 5921,
8861 "host": "0.0.0.0",
8862 "channels": [
8863 {
8864 "port": "54924",
8865 "family": "ipv4",
8866 "channel-type": 1,
8867 "connection-id": 1804289383,
8868 "host": "127.0.0.1",
8869 "channel-id": 0,
8870 "tls": true
8871 },
8872 {
8873 "port": "36710",
8874 "family": "ipv4",
8875 "channel-type": 4,
8876 "connection-id": 1804289383,
8877 "host": "127.0.0.1",
8878 "channel-id": 0,
8879 "tls": false
8880 },
8881 [ ... more channels follow ... ]
8882 ]
8883 }
8884 }
8885 If: "defined(CONFIG_SPICE)"
8887 SPICE_CONNECTED (Event) Emitted when a SPICE client establishes a
8889 connection
8890 Arguments:
8892 "server: SpiceBasicInfo"
8894 server information
8895 "client: SpiceBasicInfo"
8897 client information
8898 Since: 0.14.0
8900 Example:
8902 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
8904 "event": "SPICE_CONNECTED",
8905 "data": {
8906 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
8907 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
8908 }}
8909 If: "defined(CONFIG_SPICE)"
8911 SPICE_INITIALIZED (Event) Emitted after initial handshake and
8913 authentication takes place (if any) and the SPICE channel is up and
8914 running
8915 Arguments:
8917 "server: SpiceServerInfo"
8919 server information
8920 "client: SpiceChannel"
8922 client information
8923 Since: 0.14.0
8925 Example:
8927 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
8929 "event": "SPICE_INITIALIZED",
8930 "data": {"server": {"auth": "spice", "port": "5921",
8931 "family": "ipv4", "host": "127.0.0.1"},
8932 "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
8933 "connection-id": 1804289383, "host": "127.0.0.1",
8934 "channel-id": 0, "tls": true}
8935 }}
8936 If: "defined(CONFIG_SPICE)"
8938 SPICE_DISCONNECTED (Event) Emitted when the SPICE connection is closed
8940 Arguments:
8942 "server: SpiceBasicInfo"
8944 server information
8945 "client: SpiceBasicInfo"
8947 client information
8948 Since: 0.14.0
8950 Example:
8952 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
8954 "event": "SPICE_DISCONNECTED",
8955 "data": {
8956 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
8957 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
8958 }}
8959 If: "defined(CONFIG_SPICE)"
8961 SPICE_MIGRATE_COMPLETED (Event) Emitted when SPICE migration has
8963 completed
8964 Since: 1.3
8966 Example:
8968 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
8970 "event": "SPICE_MIGRATE_COMPLETED" }
8971 If: "defined(CONFIG_SPICE)"
8973 VNC
8975 VncBasicInfo (Object)
8977 The basic information for vnc network connection
8979 Members:
8981 "host: string"
8983 IP address
8984 "service: string"
8986 The service name of the vnc port. This may depend on the host
8987 system's service database so symbolic names should not be relied
8988 on.
8989 "family: NetworkAddressFamily"
8991 address family
8992 "websocket: boolean"
8994 true in case the socket is a websocket (since 2.3).
8995 Since: 2.1
8997 If: "defined(CONFIG_VNC)"
8999 VncServerInfo (Object)
9001 The network connection information for server
9003 Members:
9005 "auth: string" (optional)
9007 authentication method used for the plain (non-websocket) VNC server
9008 The members of "VncBasicInfo"
9010 Since: 2.1
9012 If: "defined(CONFIG_VNC)"
9014 VncClientInfo (Object)
9016 Information about a connected VNC client.
9018 Members:
9020 "x509_dname: string" (optional)
9022 If x509 authentication is in use, the Distinguished Name of the
9023 client.
9024 "sasl_username: string" (optional)
9026 If SASL authentication is in use, the SASL username used for
9027 authentication.
9028 The members of "VncBasicInfo"
9030 Since: 0.14.0
9032 If: "defined(CONFIG_VNC)"
9034 VncInfo (Object)
9036 Information about the VNC session.
9038 Members:
9040 "enabled: boolean"
9042 true if the VNC server is enabled, false otherwise
9043 "host: string" (optional)
9045 The hostname the VNC server is bound to. This depends on the name
9046 resolution on the host and may be an IP address.
9047 "family: NetworkAddressFamily" (optional)
9049 'ipv6' if the host is listening for IPv6 connections 'ipv4' if the
9050 host is listening for IPv4 connections 'unix' if the host is
9051 listening on a unix domain socket 'unknown' otherwise
9052 "service: string" (optional)
9054 The service name of the server's port. This may depends on the
9055 host system's service database so symbolic names should not be
9056 relied on.
9057 "auth: string" (optional)
9059 the current authentication type used by the server 'none' if no
9060 authentication is being used 'vnc' if VNC authentication is being
9061 used 'vencrypt+plain' if VEncrypt is used with plain text
9062 authentication 'vencrypt+tls+none' if VEncrypt is used with TLS and
9063 no authentication 'vencrypt+tls+vnc' if VEncrypt is used with TLS
9064 and VNC authentication 'vencrypt+tls+plain' if VEncrypt is used
9065 with TLS and plain text auth 'vencrypt+x509+none' if VEncrypt is
9066 used with x509 and no auth 'vencrypt+x509+vnc' if VEncrypt is used
9067 with x509 and VNC auth 'vencrypt+x509+plain' if VEncrypt is used
9068 with x509 and plain text auth 'vencrypt+tls+sasl' if VEncrypt is
9069 used with TLS and SASL auth 'vencrypt+x509+sasl' if VEncrypt is
9070 used with x509 and SASL auth
9071 "clients: array of VncClientInfo" (optional)
9073 a list of "VncClientInfo" of all currently connected clients
9074 Since: 0.14.0
9076 If: "defined(CONFIG_VNC)"
9078 VncPrimaryAuth (Enum)
9080 vnc primary authentication method.
9082 Values:
9084 "none"
9086 Not documented
9087 "vnc"
9089 Not documented
9090 "ra2"
9092 Not documented
9093 "ra2ne"
9095 Not documented
9096 "tight"
9098 Not documented
9099 "ultra"
9101 Not documented
9102 "tls"
9104 Not documented
9105 "vencrypt"
9107 Not documented
9108 "sasl"
9110 Not documented
9111 Since: 2.3
9113 If: "defined(CONFIG_VNC)"
9115 VncVencryptSubAuth (Enum)
9117 vnc sub authentication method with vencrypt.
9119 Values:
9121 "plain"
9123 Not documented
9124 "tls-none"
9126 Not documented
9127 "x509-none"
9129 Not documented
9130 "tls-vnc"
9132 Not documented
9133 "x509-vnc"
9135 Not documented
9136 "tls-plain"
9138 Not documented
9139 "x509-plain"
9141 Not documented
9142 "tls-sasl"
9144 Not documented
9145 "x509-sasl"
9147 Not documented
9148 Since: 2.3
9150 If: "defined(CONFIG_VNC)"
9152 VncServerInfo2 (Object)
9154 The network connection information for server
9156 Members:
9158 "auth: VncPrimaryAuth"
9160 The current authentication type used by the servers
9161 "vencrypt: VncVencryptSubAuth" (optional)
9163 The vencrypt sub authentication type used by the servers, only
9164 specified in case auth == vencrypt.
9165 The members of "VncBasicInfo"
9167 Since: 2.9
9169 If: "defined(CONFIG_VNC)"
9171 VncInfo2 (Object)
9173 Information about a vnc server
9175 Members:
9177 "id: string"
9179 vnc server name.
9180 "server: array of VncServerInfo2"
9182 A list of "VncBasincInfo" describing all listening sockets. The
9183 list can be empty (in case the vnc server is disabled). It also
9184 may have multiple entries: normal + websocket, possibly also ipv4 +
9185 ipv6 in the future.
9186 "clients: array of VncClientInfo"
9188 A list of "VncClientInfo" of all currently connected clients. The
9189 list can be empty, for obvious reasons.
9190 "auth: VncPrimaryAuth"
9192 The current authentication type used by the non-websockets servers
9193 "vencrypt: VncVencryptSubAuth" (optional)
9195 The vencrypt authentication type used by the servers, only
9196 specified in case auth == vencrypt.
9197 "display: string" (optional)
9199 The display device the vnc server is linked to.
9200 Since: 2.3
9202 If: "defined(CONFIG_VNC)"
9204 query-vnc (Command) Returns information about the current VNC server
9206 Returns: "VncInfo"
9208 Since: 0.14.0
9210 Example:
9212 -> { "execute": "query-vnc" }
9214 <- { "return": {
9215 "enabled":true,
9216 "host":"0.0.0.0",
9217 "service":"50402",
9218 "auth":"vnc",
9219 "family":"ipv4",
9220 "clients":[
9221 {
9222 "host":"127.0.0.1",
9223 "service":"50401",
9224 "family":"ipv4"
9225 }
9226 ]
9227 }
9228 }
9229 If: "defined(CONFIG_VNC)"
9231 query-vnc-servers (Command) Returns a list of vnc servers. The list
9233 can be empty.
9234 Returns: a list of "VncInfo2"
9236 Since: 2.3
9238 If: "defined(CONFIG_VNC)"
9240 change-vnc-password (Command) Change the VNC server password.
9242 Arguments:
9244 "password: string"
9246 the new password to use with VNC authentication
9247 Since: 1.1
9249 Notes: An empty password in this command will set the password to the
9251 empty string. Existing clients are unaffected by executing this
9252 command.
9253 If: "defined(CONFIG_VNC)"
9255 VNC_CONNECTED (Event) Emitted when a VNC client establishes a
9257 connection
9258 Arguments:
9260 "server: VncServerInfo"
9262 server information
9263 "client: VncBasicInfo"
9265 client information
9266 Note: This event is emitted before any authentication takes place, thus
9268 the authentication ID is not provided
9269 Since: 0.13.0
9271 Example:
9273 <- { "event": "VNC_CONNECTED",
9275 "data": {
9276 "server": { "auth": "sasl", "family": "ipv4",
9277 "service": "5901", "host": "0.0.0.0" },
9278 "client": { "family": "ipv4", "service": "58425",
9279 "host": "127.0.0.1" } },
9280 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
9281 If: "defined(CONFIG_VNC)"
9283 VNC_INITIALIZED (Event) Emitted after authentication takes place (if
9285 any) and the VNC session is made active
9286 Arguments:
9288 "server: VncServerInfo"
9290 server information
9291 "client: VncClientInfo"
9293 client information
9294 Since: 0.13.0
9296 Example:
9298 <- { "event": "VNC_INITIALIZED",
9300 "data": {
9301 "server": { "auth": "sasl", "family": "ipv4",
9302 "service": "5901", "host": "0.0.0.0"},
9303 "client": { "family": "ipv4", "service": "46089",
9304 "host": "127.0.0.1", "sasl_username": "luiz" } },
9305 "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
9306 If: "defined(CONFIG_VNC)"
9308 VNC_DISCONNECTED (Event) Emitted when the connection is closed
9310 Arguments:
9312 "server: VncServerInfo"
9314 server information
9315 "client: VncClientInfo"
9317 client information
9318 Since: 0.13.0
9320 Example:
9322 <- { "event": "VNC_DISCONNECTED",
9324 "data": {
9325 "server": { "auth": "sasl", "family": "ipv4",
9326 "service": "5901", "host": "0.0.0.0" },
9327 "client": { "family": "ipv4", "service": "58425",
9328 "host": "127.0.0.1", "sasl_username": "luiz" } },
9329 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
9330 If: "defined(CONFIG_VNC)"
9332 Input
9334 MouseInfo (Object)
9335 Information about a mouse device.
9337 Members:
9339 "name: string"
9341 the name of the mouse device
9342 "index: int"
9344 the index of the mouse device
9345 "current: boolean"
9347 true if this device is currently receiving mouse events
9348 "absolute: boolean"
9350 true if this device supports absolute coordinates as input
9351 Since: 0.14.0
9353 query-mice (Command) Returns information about each active mouse
9355 device
9356 Returns: a list of "MouseInfo" for each device
9358 Since: 0.14.0
9360 Example:
9362 -> { "execute": "query-mice" }
9364 <- { "return": [
9365 {
9366 "name":"QEMU Microsoft Mouse",
9367 "index":0,
9368 "current":false,
9369 "absolute":false
9370 },
9371 {
9372 "name":"QEMU PS/2 Mouse",
9373 "index":1,
9374 "current":true,
9375 "absolute":true
9376 }
9377 ]
9378 }
9379 QKeyCode (Enum)
9381 An enumeration of key name.
9383 This is used by the "send-key" command.
9385 Values:
9387 "unmapped"
9389 since 2.0
9390 "pause"
9392 since 2.0
9393 "ro"
9395 since 2.4
9396 "kp_comma"
9398 since 2.4
9399 "kp_equals"
9401 since 2.6
9402 "power"
9404 since 2.6
9405 "hiragana"
9407 since 2.9
9408 "henkan"
9410 since 2.9
9411 "yen"
9413 since 2.9
9414 "sleep"
9416 since 2.10
9417 "wake"
9419 since 2.10
9420 "audionext"
9422 since 2.10
9423 "audioprev"
9425 since 2.10
9426 "audiostop"
9428 since 2.10
9429 "audioplay"
9431 since 2.10
9432 "audiomute"
9434 since 2.10
9435 "volumeup"
9437 since 2.10
9438 "volumedown"
9440 since 2.10
9441 "mediaselect"
9443 since 2.10
9444 "mail"
9446 since 2.10
9447 "calculator"
9449 since 2.10
9450 "computer"
9452 since 2.10
9453 "ac_home"
9455 since 2.10
9456 "ac_back"
9458 since 2.10
9459 "ac_forward"
9461 since 2.10
9462 "ac_refresh"
9464 since 2.10
9465 "ac_bookmarks"
9467 since 2.10 altgr, altgr_r: dropped in 2.10
9468 "muhenkan"
9470 since 2.12
9471 "katakanahiragana"
9473 since 2.12
9474 "shift"
9476 Not documented
9477 "shift_r"
9479 Not documented
9480 "alt"
9482 Not documented
9483 "alt_r"
9485 Not documented
9486 "ctrl"
9488 Not documented
9489 "ctrl_r"
9491 Not documented
9492 "menu"
9494 Not documented
9495 "esc"
9497 Not documented
9498 1 Not documented
9500 2 Not documented
9502 3 Not documented
9504 4 Not documented
9506 5 Not documented
9508 6 Not documented
9510 7 Not documented
9512 8 Not documented
9514 9 Not documented
9516 0 Not documented
9518 "minus"
9520 Not documented
9521 "equal"
9523 Not documented
9524 "backspace"
9526 Not documented
9527 "tab"
9529 Not documented
9530 "q" Not documented
9532 "w" Not documented
9534 "e" Not documented
9536 "r" Not documented
9538 "t" Not documented
9540 "y" Not documented
9542 "u" Not documented
9544 "i" Not documented
9546 "o" Not documented
9548 "p" Not documented
9550 "bracket_left"
9552 Not documented
9553 "bracket_right"
9555 Not documented
9556 "ret"
9558 Not documented
9559 "a" Not documented
9561 "s" Not documented
9563 "d" Not documented
9565 "f" Not documented
9567 "g" Not documented
9569 "h" Not documented
9571 "j" Not documented
9573 "k" Not documented
9575 "l" Not documented
9577 "semicolon"
9579 Not documented
9580 "apostrophe"
9582 Not documented
9583 "grave_accent"
9585 Not documented
9586 "backslash"
9588 Not documented
9589 "z" Not documented
9591 "x" Not documented
9593 "c" Not documented
9595 "v" Not documented
9597 "b" Not documented
9599 "n" Not documented
9601 "m" Not documented
9603 "comma"
9605 Not documented
9606 "dot"
9608 Not documented
9609 "slash"
9611 Not documented
9612 "asterisk"
9614 Not documented
9615 "spc"
9617 Not documented
9618 "caps_lock"
9620 Not documented
9621 "f1"
9623 Not documented
9624 "f2"
9626 Not documented
9627 "f3"
9629 Not documented
9630 "f4"
9632 Not documented
9633 "f5"
9635 Not documented
9636 "f6"
9638 Not documented
9639 "f7"
9641 Not documented
9642 "f8"
9644 Not documented
9645 "f9"
9647 Not documented
9648 "f10"
9650 Not documented
9651 "num_lock"
9653 Not documented
9654 "scroll_lock"
9656 Not documented
9657 "kp_divide"
9659 Not documented
9660 "kp_multiply"
9662 Not documented
9663 "kp_subtract"
9665 Not documented
9666 "kp_add"
9668 Not documented
9669 "kp_enter"
9671 Not documented
9672 "kp_decimal"
9674 Not documented
9675 "sysrq"
9677 Not documented
9678 "kp_0"
9680 Not documented
9681 "kp_1"
9683 Not documented
9684 "kp_2"
9686 Not documented
9687 "kp_3"
9689 Not documented
9690 "kp_4"
9692 Not documented
9693 "kp_5"
9695 Not documented
9696 "kp_6"
9698 Not documented
9699 "kp_7"
9701 Not documented
9702 "kp_8"
9704 Not documented
9705 "kp_9"
9707 Not documented
9708 "less"
9710 Not documented
9711 "f11"
9713 Not documented
9714 "f12"
9716 Not documented
9717 "print"
9719 Not documented
9720 "home"
9722 Not documented
9723 "pgup"
9725 Not documented
9726 "pgdn"
9728 Not documented
9729 "end"
9731 Not documented
9732 "left"
9734 Not documented
9735 "up"
9737 Not documented
9738 "down"
9740 Not documented
9741 "right"
9743 Not documented
9744 "insert"
9746 Not documented
9747 "delete"
9749 Not documented
9750 "stop"
9752 Not documented
9753 "again"
9755 Not documented
9756 "props"
9758 Not documented
9759 "undo"
9761 Not documented
9762 "front"
9764 Not documented
9765 "copy"
9767 Not documented
9768 "open"
9770 Not documented
9771 "paste"
9773 Not documented
9774 "find"
9776 Not documented
9777 "cut"
9779 Not documented
9780 "lf"
9782 Not documented
9783 "help"
9785 Not documented
9786 "meta_l"
9788 Not documented
9789 "meta_r"
9791 Not documented
9792 "compose"
9794 Not documented
9795 'sysrq' was mistakenly added to hack around the fact that the ps2
9797 driver was not generating correct scancodes sequences when 'alt+print'
9798 was pressed. This flaw is now fixed and the 'sysrq' key serves no
9799 further purpose. Any further use of 'sysrq' will be transparently
9800 changed to 'print', so they are effectively synonyms.
9801 Since: 1.3.0
9803 KeyValue (Object)
9805 Represents a keyboard key.
9807 Members:
9809 "type"
9811 One of "number", "qcode"
9812 "data: int" when "type" is "number"
9814 "data: QKeyCode" when "type" is "qcode"
9815 Since: 1.3.0
9817 send-key (Command) Send keys to guest.
9819 Arguments:
9821 "keys: array of KeyValue"
9823 An array of "KeyValue" elements. All "KeyValues" in this array are
9824 simultaneously sent to the guest. A "KeyValue".number value is sent
9825 directly to the guest, while "KeyValue".qcode must be a valid
9826 "QKeyCode" value
9827 "hold-time: int" (optional)
9829 time to delay key up events, milliseconds. Defaults to 100
9830 Returns: Nothing on success If key is unknown or redundant,
9832 InvalidParameter
9833 Since: 1.3.0
9835 Example:
9837 -> { "execute": "send-key",
9839 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
9840 { "type": "qcode", "data": "alt" },
9841 { "type": "qcode", "data": "delete" } ] } }
9842 <- { "return": {} }
9843 InputButton (Enum)
9845 Button of a pointer input device (mouse, tablet).
9847 Values:
9849 "side"
9851 front side button of a 5-button mouse (since 2.9)
9852 "extra"
9854 rear side button of a 5-button mouse (since 2.9)
9855 "left"
9857 Not documented
9858 "middle"
9860 Not documented
9861 "right"
9863 Not documented
9864 "wheel-up"
9866 Not documented
9867 "wheel-down"
9869 Not documented
9870 Since: 2.0
9872 InputAxis (Enum)
9874 Position axis of a pointer input device (mouse, tablet).
9876 Values:
9878 "x" Not documented
9880 "y" Not documented
9882 Since: 2.0
9884 InputKeyEvent (Object)
9886 Keyboard input event.
9888 Members:
9890 "key: KeyValue"
9892 Which key this event is for.
9893 "down: boolean"
9895 True for key-down and false for key-up events.
9896 Since: 2.0
9898 InputBtnEvent (Object)
9900 Pointer button input event.
9902 Members:
9904 "button: InputButton"
9906 Which button this event is for.
9907 "down: boolean"
9909 True for key-down and false for key-up events.
9910 Since: 2.0
9912 InputMoveEvent (Object)
9914 Pointer motion input event.
9916 Members:
9918 "axis: InputAxis"
9920 Which axis is referenced by "value".
9921 "value: int"
9923 Pointer position. For absolute coordinates the valid range is 0 ->
9924 0x7ffff
9925 Since: 2.0
9927 InputEvent (Object)
9929 Input event union.
9931 Members:
9933 "type"
9935 the input type, one of:
9936 - 'key': Input event of Keyboard
9938 - 'btn': Input event of pointer buttons
9940 - 'rel': Input event of relative pointer motion
9942 - 'abs': Input event of absolute pointer motion
9944 "data: InputKeyEvent" when "type" is "key"
9946 "data: InputBtnEvent" when "type" is "btn"
9947 "data: InputMoveEvent" when "type" is "rel"
9948 "data: InputMoveEvent" when "type" is "abs"
9949 Since: 2.0
9951 input-send-event (Command) Send input event(s) to guest.
9953 Arguments:
9955 "device: string" (optional)
9957 display device to send event(s) to.
9958 "head: int" (optional)
9960 head to send event(s) to, in case the display device supports
9961 multiple scanouts.
9962 "events: array of InputEvent"
9964 List of InputEvent union.
9965 Returns: Nothing on success.
9967 The "device" and "head" parameters can be used to send the input event
9969 to specific input devices in case (a) multiple input devices of the
9970 same kind are added to the virtual machine and (b) you have configured
9971 input routing (see docs/multiseat.txt) for those input devices. The
9972 parameters work exactly like the device and head properties of input
9973 devices. If "device" is missing, only devices that have no input
9974 routing config are admissible. If "device" is specified, both input
9975 devices with and without input routing config are admissible, but
9976 devices with input routing config take precedence.
9977 Since: 2.6
9979 Note: The consoles are visible in the qom tree, under
9981 /backend/console[$index]. They have a device link and head property, so
9982 it is possible to map which console belongs to which device and
9983 display.
9984 Example:
9986 1. Press left mouse button.
9988 -> { "execute": "input-send-event",
9990 "arguments": { "device": "video0",
9991 "events": [ { "type": "btn",
9992 "data" : { "down": true, "button": "left" } } ] } }
9993 <- { "return": {} }
9994 -> { "execute": "input-send-event",
9996 "arguments": { "device": "video0",
9997 "events": [ { "type": "btn",
9998 "data" : { "down": false, "button": "left" } } ] } }
9999 <- { "return": {} }
10000 2. Press ctrl-alt-del.
10002 -> { "execute": "input-send-event",
10004 "arguments": { "events": [
10005 { "type": "key", "data" : { "down": true,
10006 "key": {"type": "qcode", "data": "ctrl" } } },
10007 { "type": "key", "data" : { "down": true,
10008 "key": {"type": "qcode", "data": "alt" } } },
10009 { "type": "key", "data" : { "down": true,
10010 "key": {"type": "qcode", "data": "delete" } } } ] } }
10011 <- { "return": {} }
10012 3. Move mouse pointer to absolute coordinates (20000, 400).
10014 -> { "execute": "input-send-event" ,
10016 "arguments": { "events": [
10017 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
10018 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
10019 <- { "return": {} }
10020 DisplayGTK (Object)
10022 GTK display options.
10024 Members:
10026 "grab-on-hover: boolean" (optional)
10028 Grab keyboard input on mouse hover.
10029 Since: 2.12
10031 DisplayGLMode (Enum)
10033 Display OpenGL mode.
10035 Values:
10037 "off"
10039 Disable OpenGL (default).
10040 "on"
10042 Use OpenGL, pick context type automatically. Would better be named
10043 'auto' but is called 'on' for backward compatibility with bool
10044 type.
10045 "core"
10047 Use OpenGL with Core (desktop) Context.
10048 "es"
10050 Use OpenGL with ES (embedded systems) Context.
10051 Since: 3.0
10053 DisplayType (Enum)
10055 Display (user interface) type.
10057 Values:
10059 "default"
10061 Not documented
10062 "none"
10064 Not documented
10065 "gtk"
10067 Not documented
10068 "sdl"
10070 Not documented
10071 "egl-headless"
10073 Not documented
10074 "curses"
10076 Not documented
10077 "cocoa"
10079 Not documented
10080 Since: 2.12
10082 DisplayOptions (Object)
10084 Display (user interface) options.
10086 Members:
10088 "type: DisplayType"
10090 Which DisplayType qemu should use.
10091 "full-screen: boolean" (optional)
10093 Start user interface in fullscreen mode (default: off).
10094 "window-close: boolean" (optional)
10096 Allow to quit qemu with window close button (default: on).
10097 "gl: DisplayGLMode" (optional)
10099 Enable OpenGL support (default: off).
10100 The members of "DisplayGTK" when "type" is "gtk"
10102 Since: 2.12
10104 Migration
10106 MigrationStats (Object)
10107 Detailed migration status.
10109 Members:
10111 "transferred: int"
10113 amount of bytes already transferred to the target VM
10114 "remaining: int"
10116 amount of bytes remaining to be transferred to the target VM
10117 "total: int"
10119 total amount of bytes involved in the migration process
10120 "duplicate: int"
10122 number of duplicate (zero) pages (since 1.2)
10123 "skipped: int"
10125 number of skipped zero pages (since 1.5)
10126 "normal: int"
10128 number of normal pages (since 1.2)
10129 "normal-bytes: int"
10131 number of normal bytes sent (since 1.2)
10132 "dirty-pages-rate: int"
10134 number of pages dirtied by second by the guest (since 1.3)
10135 "mbps: number"
10137 throughput in megabits/sec. (since 1.6)
10138 "dirty-sync-count: int"
10140 number of times that dirty ram was synchronized (since 2.1)
10141 "postcopy-requests: int"
10143 The number of page requests received from the destination (since
10144 2.7)
10145 "page-size: int"
10147 The number of bytes per page for the various page-based statistics
10148 (since 2.10)
10149 "multifd-bytes: int"
10151 The number of bytes sent through multifd (since 3.0)
10152 Since: 0.14.0
10154 XBZRLECacheStats (Object)
10156 Detailed XBZRLE migration cache statistics
10158 Members:
10160 "cache-size: int"
10162 XBZRLE cache size
10163 "bytes: int"
10165 amount of bytes already transferred to the target VM
10166 "pages: int"
10168 amount of pages transferred to the target VM
10169 "cache-miss: int"
10171 number of cache miss
10172 "cache-miss-rate: number"
10174 rate of cache miss (since 2.1)
10175 "overflow: int"
10177 number of overflows
10178 Since: 1.2
10180 MigrationStatus (Enum)
10182 An enumeration of migration status.
10184 Values:
10186 "none"
10188 no migration has ever happened.
10189 "setup"
10191 migration process has been initiated.
10192 "cancelling"
10194 in the process of cancelling migration.
10195 "cancelled"
10197 cancelling migration is finished.
10198 "active"
10200 in the process of doing migration.
10201 "postcopy-active"
10203 like active, but now in postcopy mode. (since 2.5)
10204 "postcopy-paused"
10206 during postcopy but paused. (since 3.0)
10207 "postcopy-recover"
10209 trying to recover from a paused postcopy. (since 3.0)
10210 "completed"
10212 migration is finished.
10213 "failed"
10215 some error occurred during migration process.
10216 "colo"
10218 VM is in the process of fault tolerance, VM can not get into this
10219 state unless colo capability is enabled for migration. (since 2.8)
10220 "pre-switchover"
10222 Paused before device serialisation. (since 2.11)
10223 "device"
10225 During device serialisation when pause-before-switchover is enabled
10226 (since 2.11)
10227 Since: 2.3
10229 MigrationInfo (Object)
10231 Information about current migration process.
10233 Members:
10235 "status: MigrationStatus" (optional)
10237 "MigrationStatus" describing the current migration status. If this
10238 field is not returned, no migration process has been initiated
10239 "ram: MigrationStats" (optional)
10241 "MigrationStats" containing detailed migration status, only
10242 returned if status is 'active' or 'completed'(since 1.2)
10243 "disk: MigrationStats" (optional)
10245 "MigrationStats" containing detailed disk migration status, only
10246 returned if status is 'active' and it is a block migration
10247 "xbzrle-cache: XBZRLECacheStats" (optional)
10249 "XBZRLECacheStats" containing detailed XBZRLE migration statistics,
10250 only returned if XBZRLE feature is on and status is 'active' or
10251 'completed' (since 1.2)
10252 "total-time: int" (optional)
10254 total amount of milliseconds since migration started. If migration
10255 has ended, it returns the total migration time. (since 1.2)
10256 "downtime: int" (optional)
10258 only present when migration finishes correctly total downtime in
10259 milliseconds for the guest. (since 1.3)
10260 "expected-downtime: int" (optional)
10262 only present while migration is active expected downtime in
10263 milliseconds for the guest in last walk of the dirty bitmap. (since
10264 1.3)
10265 "setup-time: int" (optional)
10267 amount of setup time in milliseconds before the iterations begin
10268 but after the QMP command is issued. This is designed to provide an
10269 accounting of any activities (such as RDMA pinning) which may be
10270 expensive, but do not actually occur during the iterative migration
10271 rounds themselves. (since 1.6)
10272 "cpu-throttle-percentage: int" (optional)
10274 percentage of time guest cpus are being throttled during auto-
10275 converge. This is only present when auto-converge has started
10276 throttling guest cpus. (Since 2.7)
10277 "error-desc: string" (optional)
10279 the human readable error description string, when "status" is
10280 'failed'. Clients should not attempt to parse the error strings.
10281 (Since 2.7)
10282 "postcopy-blocktime: int" (optional)
10284 total time when all vCPU were blocked during postcopy live
10285 migration. This is only present when the postcopy-blocktime
10286 migration capability is enabled. (Since 3.0)
10287 "postcopy-vcpu-blocktime: array of int" (optional)
10289 list of the postcopy blocktime per vCPU. This is only present when
10290 the postcopy-blocktime migration capability is enabled. (Since 3.0)
10291 Since: 0.14.0
10293 query-migrate (Command) Returns information about current migration
10295 process. If migration is active there will be another json-object with
10296 RAM migration status and if block migration is active another one with
10297 block migration status.
10298 Returns: "MigrationInfo"
10300 Since: 0.14.0
10302 Example:
10304 1. Before the first migration
10306 -> { "execute": "query-migrate" }
10308 <- { "return": {} }
10309 2. Migration is done and has succeeded
10311 -> { "execute": "query-migrate" }
10313 <- { "return": {
10314 "status": "completed",
10315 "ram":{
10316 "transferred":123,
10317 "remaining":123,
10318 "total":246,
10319 "total-time":12345,
10320 "setup-time":12345,
10321 "downtime":12345,
10322 "duplicate":123,
10323 "normal":123,
10324 "normal-bytes":123456,
10325 "dirty-sync-count":15
10326 }
10327 }
10328 }
10329 3. Migration is done and has failed
10331 -> { "execute": "query-migrate" }
10333 <- { "return": { "status": "failed" } }
10334 4. Migration is being performed and is not a block migration:
10336 -> { "execute": "query-migrate" }
10338 <- {
10339 "return":{
10340 "status":"active",
10341 "ram":{
10342 "transferred":123,
10343 "remaining":123,
10344 "total":246,
10345 "total-time":12345,
10346 "setup-time":12345,
10347 "expected-downtime":12345,
10348 "duplicate":123,
10349 "normal":123,
10350 "normal-bytes":123456,
10351 "dirty-sync-count":15
10352 }
10353 }
10354 }
10355 5. Migration is being performed and is a block migration:
10357 -> { "execute": "query-migrate" }
10359 <- {
10360 "return":{
10361 "status":"active",
10362 "ram":{
10363 "total":1057024,
10364 "remaining":1053304,
10365 "transferred":3720,
10366 "total-time":12345,
10367 "setup-time":12345,
10368 "expected-downtime":12345,
10369 "duplicate":123,
10370 "normal":123,
10371 "normal-bytes":123456,
10372 "dirty-sync-count":15
10373 },
10374 "disk":{
10375 "total":20971520,
10376 "remaining":20880384,
10377 "transferred":91136
10378 }
10379 }
10380 }
10381 6. Migration is being performed and XBZRLE is active:
10383 -> { "execute": "query-migrate" }
10385 <- {
10386 "return":{
10387 "status":"active",
10388 "capabilities" : [ { "capability": "xbzrle", "state" : true } ],
10389 "ram":{
10390 "total":1057024,
10391 "remaining":1053304,
10392 "transferred":3720,
10393 "total-time":12345,
10394 "setup-time":12345,
10395 "expected-downtime":12345,
10396 "duplicate":10,
10397 "normal":3333,
10398 "normal-bytes":3412992,
10399 "dirty-sync-count":15
10400 },
10401 "xbzrle-cache":{
10402 "cache-size":67108864,
10403 "bytes":20971520,
10404 "pages":2444343,
10405 "cache-miss":2244,
10406 "cache-miss-rate":0.123,
10407 "overflow":34434
10408 }
10409 }
10410 }
10411 MigrationCapability (Enum)
10413 Migration capabilities enumeration
10415 Values:
10417 "xbzrle"
10419 Migration supports xbzrle (Xor Based Zero Run Length Encoding).
10420 This feature allows us to minimize migration traffic for certain
10421 work loads, by sending compressed difference of the pages
10422 "rdma-pin-all"
10424 Controls whether or not the entire VM memory footprint is mlock()'d
10425 on demand or all at once. Refer to docs/rdma.txt for usage.
10426 Disabled by default. (since 2.0)
10427 "zero-blocks"
10429 During storage migration encode blocks of zeroes efficiently. This
10430 essentially saves 1MB of zeroes per block on the wire. Enabling
10431 requires source and target VM to support this feature. To enable it
10432 is sufficient to enable the capability on the source VM. The
10433 feature is disabled by default. (since 1.6)
10434 "compress"
10436 Use multiple compression threads to accelerate live migration.
10437 This feature can help to reduce the migration traffic, by sending
10438 compressed pages. Please note that if compress and xbzrle are both
10439 on, compress only takes effect in the ram bulk stage, after that,
10440 it will be disabled and only xbzrle takes effect, this can help to
10441 minimize migration traffic. The feature is disabled by default.
10442 (since 2.4 )
10443 "events"
10445 generate events for each migration state change (since 2.4 )
10446 "auto-converge"
10448 If enabled, QEMU will automatically throttle down the guest to
10449 speed up convergence of RAM migration. (since 1.6)
10450 "postcopy-ram"
10452 Start executing on the migration target before all of RAM has been
10453 migrated, pulling the remaining pages along as needed. The capacity
10454 must have the same setting on both source and target or migration
10455 will not even start. NOTE: If the migration fails during postcopy
10456 the VM will fail. (since 2.6)
10457 "x-colo"
10459 If enabled, migration will never end, and the state of the VM on
10460 the primary side will be migrated continuously to the VM on
10461 secondary side, this process is called COarse-Grain LOck Stepping
10462 (COLO) for Non-stop Service. (since 2.8)
10463 "release-ram"
10465 if enabled, qemu will free the migrated ram pages on the source
10466 during postcopy-ram migration. (since 2.9)
10467 "block"
10469 If enabled, QEMU will also migrate the contents of all block
10470 devices. Default is disabled. A possible alternative uses mirror
10471 jobs to a builtin NBD server on the destination, which offers more
10472 flexibility. (Since 2.10)
10473 "return-path"
10475 If enabled, migration will use the return path even for precopy.
10476 (since 2.10)
10477 "pause-before-switchover"
10479 Pause outgoing migration before serialising device state and before
10480 disabling block IO (since 2.11)
10481 "x-multifd"
10483 Use more than one fd for migration (since 2.11)
10484 "dirty-bitmaps"
10486 If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
10487 "postcopy-blocktime"
10489 Calculate downtime for postcopy live migration (since 3.0)
10490 "late-block-activate"
10492 If enabled, the destination will not activate block devices (and
10493 thus take locks) immediately at the end of migration. (since 3.0)
10494 Since: 1.2
10496 MigrationCapabilityStatus (Object)
10498 Migration capability information
10500 Members:
10502 "capability: MigrationCapability"
10504 capability enum
10505 "state: boolean"
10507 capability state bool
10508 Since: 1.2
10510 migrate-set-capabilities (Command) Enable/Disable the following
10512 migration capabilities (like xbzrle)
10513 Arguments:
10515 "capabilities: array of MigrationCapabilityStatus"
10517 json array of capability modifications to make
10518 Since: 1.2
10520 Example:
10522 -> { "execute": "migrate-set-capabilities" , "arguments":
10524 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
10525 query-migrate-capabilities (Command) Returns information about the
10527 current migration capabilities status
10528 Returns: "MigrationCapabilitiesStatus"
10530 Since: 1.2
10532 Example:
10534 -> { "execute": "query-migrate-capabilities" }
10536 <- { "return": [
10537 {"state": false, "capability": "xbzrle"},
10538 {"state": false, "capability": "rdma-pin-all"},
10539 {"state": false, "capability": "auto-converge"},
10540 {"state": false, "capability": "zero-blocks"},
10541 {"state": false, "capability": "compress"},
10542 {"state": true, "capability": "events"},
10543 {"state": false, "capability": "postcopy-ram"},
10544 {"state": false, "capability": "x-colo"}
10545 ]}
10546 MigrationParameter (Enum)
10548 Migration parameters enumeration
10550 Values:
10552 "compress-level"
10554 Set the compression level to be used in live migration, the
10555 compression level is an integer between 0 and 9, where 0 means no
10556 compression, 1 means the best compression speed, and 9 means best
10557 compression ratio which will consume more CPU.
10558 "compress-threads"
10560 Set compression thread count to be used in live migration, the
10561 compression thread count is an integer between 1 and 255.
10562 "decompress-threads"
10564 Set decompression thread count to be used in live migration, the
10565 decompression thread count is an integer between 1 and 255.
10566 Usually, decompression is at least 4 times as fast as compression,
10567 so set the decompress-threads to the number about 1/4 of compress-
10568 threads is adequate.
10569 "cpu-throttle-initial"
10571 Initial percentage of time guest cpus are throttled when migration
10572 auto-converge is activated. The default value is 20. (Since 2.7)
10573 "cpu-throttle-increment"
10575 throttle percentage increase each time auto-converge detects that
10576 migration is not making progress. The default value is 10. (Since
10577 2.7)
10578 "tls-creds"
10580 ID of the 'tls-creds' object that provides credentials for
10581 establishing a TLS connection over the migration data channel. On
10582 the outgoing side of the migration, the credentials must be for a
10583 'client' endpoint, while for the incoming side the credentials must
10584 be for a 'server' endpoint. Setting this will enable TLS for all
10585 migrations. The default is unset, resulting in unsecured migration
10586 at the QEMU level. (Since 2.7)
10587 "tls-hostname"
10589 hostname of the target host for the migration. This is required
10590 when using x509 based TLS credentials and the migration URI does
10591 not already include a hostname. For example if using fd: or exec:
10592 based migration, the hostname must be provided so that the server's
10593 x509 certificate identity can be validated. (Since 2.7)
10594 "max-bandwidth"
10596 to set maximum speed for migration. maximum speed in bytes per
10597 second. (Since 2.8)
10598 "downtime-limit"
10600 set maximum tolerated downtime for migration. maximum downtime in
10601 milliseconds (Since 2.8)
10602 "x-checkpoint-delay"
10604 The delay time (in ms) between two COLO checkpoints in periodic
10605 mode. (Since 2.8)
10606 "block-incremental"
10608 Affects how much storage is migrated when the block migration
10609 capability is enabled. When false, the entire storage backing
10610 chain is migrated into a flattened image at the destination; when
10611 true, only the active qcow2 layer is migrated and the destination
10612 must already have access to the same backing chain as was used on
10613 the source. (since 2.10)
10614 "x-multifd-channels"
10616 Number of channels used to migrate data in parallel. This is the
10617 same number that the number of sockets used for migration. The
10618 default value is 2 (since 2.11)
10619 "x-multifd-page-count"
10621 Number of pages sent together to a thread. The default value is 16
10622 (since 2.11)
10623 "xbzrle-cache-size"
10625 cache size to be used by XBZRLE migration. It needs to be a
10626 multiple of the target page size and a power of 2 (Since 2.11)
10627 "max-postcopy-bandwidth"
10629 Background transfer bandwidth during postcopy. Defaults to 0
10630 (unlimited). In bytes per second. (Since 3.0)
10631 Since: 2.4
10633 MigrateSetParameters (Object)
10635 Members:
10637 "compress-level: int" (optional)
10639 compression level
10640 "compress-threads: int" (optional)
10642 compression thread count
10643 "decompress-threads: int" (optional)
10645 decompression thread count
10646 "cpu-throttle-initial: int" (optional)
10648 Initial percentage of time guest cpus are throttled when migration
10649 auto-converge is activated. The default value is 20. (Since 2.7)
10650 "cpu-throttle-increment: int" (optional)
10652 throttle percentage increase each time auto-converge detects that
10653 migration is not making progress. The default value is 10. (Since
10654 2.7)
10655 "tls-creds: StrOrNull" (optional)
10657 ID of the 'tls-creds' object that provides credentials for
10658 establishing a TLS connection over the migration data channel. On
10659 the outgoing side of the migration, the credentials must be for a
10660 'client' endpoint, while for the incoming side the credentials must
10661 be for a 'server' endpoint. Setting this to a non-empty string
10662 enables TLS for all migrations. An empty string means that QEMU
10663 will use plain text mode for migration, rather than TLS (Since 2.9)
10664 Previously (since 2.7), this was reported by omitting tls-creds
10665 instead.
10666 "tls-hostname: StrOrNull" (optional)
10668 hostname of the target host for the migration. This is required
10669 when using x509 based TLS credentials and the migration URI does
10670 not already include a hostname. For example if using fd: or exec:
10671 based migration, the hostname must be provided so that the server's
10672 x509 certificate identity can be validated. (Since 2.7) An empty
10673 string means that QEMU will use the hostname associated with the
10674 migration URI, if any. (Since 2.9) Previously (since 2.7), this was
10675 reported by omitting tls-hostname instead.
10676 "max-bandwidth: int" (optional)
10678 to set maximum speed for migration. maximum speed in bytes per
10679 second. (Since 2.8)
10680 "downtime-limit: int" (optional)
10682 set maximum tolerated downtime for migration. maximum downtime in
10683 milliseconds (Since 2.8)
10684 "x-checkpoint-delay: int" (optional)
10686 the delay time between two COLO checkpoints. (Since 2.8)
10687 "block-incremental: boolean" (optional)
10689 Affects how much storage is migrated when the block migration
10690 capability is enabled. When false, the entire storage backing
10691 chain is migrated into a flattened image at the destination; when
10692 true, only the active qcow2 layer is migrated and the destination
10693 must already have access to the same backing chain as was used on
10694 the source. (since 2.10)
10695 "x-multifd-channels: int" (optional)
10697 Number of channels used to migrate data in parallel. This is the
10698 same number that the number of sockets used for migration. The
10699 default value is 2 (since 2.11)
10700 "x-multifd-page-count: int" (optional)
10702 Number of pages sent together to a thread. The default value is 16
10703 (since 2.11)
10704 "xbzrle-cache-size: int" (optional)
10706 cache size to be used by XBZRLE migration. It needs to be a
10707 multiple of the target page size and a power of 2 (Since 2.11)
10708 "max-postcopy-bandwidth: int" (optional)
10710 Background transfer bandwidth during postcopy. Defaults to 0
10711 (unlimited). In bytes per second. (Since 3.0)
10712 Since: 2.4
10714 migrate-set-parameters (Command) Set various migration parameters.
10716 Arguments: the members of "MigrateSetParameters"
10718 Since: 2.4
10720 Example:
10722 -> { "execute": "migrate-set-parameters" ,
10724 "arguments": { "compress-level": 1 } }
10725 MigrationParameters (Object)
10727 The optional members aren't actually optional.
10729 Members:
10731 "compress-level: int" (optional)
10733 compression level
10734 "compress-threads: int" (optional)
10736 compression thread count
10737 "decompress-threads: int" (optional)
10739 decompression thread count
10740 "cpu-throttle-initial: int" (optional)
10742 Initial percentage of time guest cpus are throttled when migration
10743 auto-converge is activated. (Since 2.7)
10744 "cpu-throttle-increment: int" (optional)
10746 throttle percentage increase each time auto-converge detects that
10747 migration is not making progress. (Since 2.7)
10748 "tls-creds: string" (optional)
10750 ID of the 'tls-creds' object that provides credentials for
10751 establishing a TLS connection over the migration data channel. On
10752 the outgoing side of the migration, the credentials must be for a
10753 'client' endpoint, while for the incoming side the credentials must
10754 be for a 'server' endpoint. An empty string means that QEMU will
10755 use plain text mode for migration, rather than TLS (Since 2.7)
10756 Note: 2.8 reports this by omitting tls-creds instead.
10757 "tls-hostname: string" (optional)
10759 hostname of the target host for the migration. This is required
10760 when using x509 based TLS credentials and the migration URI does
10761 not already include a hostname. For example if using fd: or exec:
10762 based migration, the hostname must be provided so that the server's
10763 x509 certificate identity can be validated. (Since 2.7) An empty
10764 string means that QEMU will use the hostname associated with the
10765 migration URI, if any. (Since 2.9) Note: 2.8 reports this by
10766 omitting tls-hostname instead.
10767 "max-bandwidth: int" (optional)
10769 to set maximum speed for migration. maximum speed in bytes per
10770 second. (Since 2.8)
10771 "downtime-limit: int" (optional)
10773 set maximum tolerated downtime for migration. maximum downtime in
10774 milliseconds (Since 2.8)
10775 "x-checkpoint-delay: int" (optional)
10777 the delay time between two COLO checkpoints. (Since 2.8)
10778 "block-incremental: boolean" (optional)
10780 Affects how much storage is migrated when the block migration
10781 capability is enabled. When false, the entire storage backing
10782 chain is migrated into a flattened image at the destination; when
10783 true, only the active qcow2 layer is migrated and the destination
10784 must already have access to the same backing chain as was used on
10785 the source. (since 2.10)
10786 "x-multifd-channels: int" (optional)
10788 Number of channels used to migrate data in parallel. This is the
10789 same number that the number of sockets used for migration. The
10790 default value is 2 (since 2.11)
10791 "x-multifd-page-count: int" (optional)
10793 Number of pages sent together to a thread. The default value is 16
10794 (since 2.11)
10795 "xbzrle-cache-size: int" (optional)
10797 cache size to be used by XBZRLE migration. It needs to be a
10798 multiple of the target page size and a power of 2 (Since 2.11)
10799 "max-postcopy-bandwidth: int" (optional)
10801 Background transfer bandwidth during postcopy. Defaults to 0
10802 (unlimited). In bytes per second. (Since 3.0)
10803 Since: 2.4
10805 query-migrate-parameters (Command) Returns information about the
10807 current migration parameters
10808 Returns: "MigrationParameters"
10810 Since: 2.4
10812 Example:
10814 -> { "execute": "query-migrate-parameters" }
10816 <- { "return": {
10817 "decompress-threads": 2,
10818 "cpu-throttle-increment": 10,
10819 "compress-threads": 8,
10820 "compress-level": 1,
10821 "cpu-throttle-initial": 20,
10822 "max-bandwidth": 33554432,
10823 "downtime-limit": 300
10824 }
10825 }
10826 client_migrate_info (Command) Set migration information for remote
10828 display. This makes the server ask the client to automatically
10829 reconnect using the new parameters once migration finished
10830 successfully. Only implemented for SPICE.
10831 Arguments:
10833 "protocol: string"
10835 must be "spice"
10836 "hostname: string"
10838 migration target hostname
10839 "port: int" (optional)
10841 spice tcp port for plaintext channels
10842 "tls-port: int" (optional)
10844 spice tcp port for tls-secured channels
10845 "cert-subject: string" (optional)
10847 server certificate subject
10848 Since: 0.14.0
10850 Example:
10852 -> { "execute": "client_migrate_info",
10854 "arguments": { "protocol": "spice",
10855 "hostname": "virt42.lab.kraxel.org",
10856 "port": 1234 } }
10857 <- { "return": {} }
10858 migrate-start-postcopy (Command) Followup to a migration command to
10860 switch the migration to postcopy mode. The postcopy-ram capability
10861 must be set on both source and destination before the original
10862 migration command.
10863 Since: 2.5
10865 Example:
10867 -> { "execute": "migrate-start-postcopy" }
10869 <- { "return": {} }
10870 MIGRATION (Event) Emitted when a migration event happens
10872 Arguments:
10874 "status: MigrationStatus"
10876 "MigrationStatus" describing the current migration status.
10877 Since: 2.4
10879 Example:
10881 <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
10883 "event": "MIGRATION",
10884 "data": {"status": "completed"} }
10885 MIGRATION_PASS (Event) Emitted from the source side of a migration at
10887 the start of each pass (when it syncs the dirty bitmap)
10888 Arguments:
10890 "pass: int"
10892 An incrementing count (starting at 1 on the first pass)
10893 Since: 2.6
10895 Example:
10897 { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
10899 "event": "MIGRATION_PASS", "data": {"pass": 2} }
10900 COLOMessage (Enum)
10902 The message transmission between Primary side and Secondary side.
10904 Values:
10906 "checkpoint-ready"
10908 Secondary VM (SVM) is ready for checkpointing
10909 "checkpoint-request"
10911 Primary VM (PVM) tells SVM to prepare for checkpointing
10912 "checkpoint-reply"
10914 SVM gets PVM's checkpoint request
10915 "vmstate-send"
10917 VM's state will be sent by PVM.
10918 "vmstate-size"
10920 The total size of VMstate.
10921 "vmstate-received"
10923 VM's state has been received by SVM.
10924 "vmstate-loaded"
10926 VM's state has been loaded by SVM.
10927 Since: 2.8
10929 COLOMode (Enum)
10931 The colo mode
10933 Values:
10935 "unknown"
10937 unknown mode
10938 "primary"
10940 master side
10941 "secondary"
10943 slave side
10944 Since: 2.8
10946 FailoverStatus (Enum)
10948 An enumeration of COLO failover status
10950 Values:
10952 "none"
10954 no failover has ever happened
10955 "require"
10957 got failover requirement but not handled
10958 "active"
10960 in the process of doing failover
10961 "completed"
10963 finish the process of failover
10964 "relaunch"
10966 restart the failover process, from 'none' -> 'completed' (Since
10967 2.9)
10968 Since: 2.8
10970 x-colo-lost-heartbeat (Command) Tell qemu that heartbeat is lost,
10972 request it to do takeover procedures. If this command is sent to the
10973 PVM, the Primary side will exit COLO mode. If sent to the Secondary,
10974 the Secondary side will run failover work, then takes over server
10975 operation to become the service VM.
10976 Since: 2.8
10978 Example:
10980 -> { "execute": "x-colo-lost-heartbeat" }
10982 <- { "return": {} }
10983 migrate_cancel (Command) Cancel the current executing migration
10985 process.
10986 Returns: nothing on success
10988 Notes: This command succeeds even if there is no migration process
10990 running.
10991 Since: 0.14.0
10993 Example:
10995 -> { "execute": "migrate_cancel" }
10997 <- { "return": {} }
10998 migrate-continue (Command) Continue migration when it's in a paused
11000 state.
11001 Arguments:
11003 "state: MigrationStatus"
11005 The state the migration is currently expected to be in
11006 Returns: nothing on success
11008 Since: 2.11
11010 Example:
11012 -> { "execute": "migrate-continue" , "arguments":
11014 { "state": "pre-switchover" } }
11015 <- { "return": {} }
11016 migrate_set_downtime (Command) Set maximum tolerated downtime for
11018 migration.
11019 Arguments:
11021 "value: number"
11023 maximum downtime in seconds
11024 Returns: nothing on success
11026 Notes: This command is deprecated in favor of 'migrate-set-parameters'
11028 Since: 0.14.0
11030 Example:
11032 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
11034 <- { "return": {} }
11035 migrate_set_speed (Command) Set maximum speed for migration.
11037 Arguments:
11039 "value: int"
11041 maximum speed in bytes per second.
11042 Returns: nothing on success
11044 Notes: This command is deprecated in favor of 'migrate-set-parameters'
11046 Since: 0.14.0
11048 Example:
11050 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
11052 <- { "return": {} }
11053 migrate-set-cache-size (Command) Set cache size to be used by XBZRLE
11055 migration
11056 Arguments:
11058 "value: int"
11060 cache size in bytes
11061 The size will be rounded down to the nearest power of 2. The cache
11063 size can be modified before and during ongoing migration
11064 Returns: nothing on success
11066 Notes: This command is deprecated in favor of 'migrate-set-parameters'
11068 Since: 1.2
11070 Example:
11072 -> { "execute": "migrate-set-cache-size",
11074 "arguments": { "value": 536870912 } }
11075 <- { "return": {} }
11076 query-migrate-cache-size (Command) Query migration XBZRLE cache size
11078 Returns: XBZRLE cache size in bytes
11080 Notes: This command is deprecated in favor of
11082 'query-migrate-parameters'
11083 Since: 1.2
11085 Example:
11087 -> { "execute": "query-migrate-cache-size" }
11089 <- { "return": 67108864 }
11090 migrate (Command) Migrates the current running guest to another
11092 Virtual Machine.
11093 Arguments:
11095 "uri: string"
11097 the Uniform Resource Identifier of the destination VM
11098 "blk: boolean" (optional)
11100 do block migration (full disk copy)
11101 "inc: boolean" (optional)
11103 incremental disk copy migration
11104 "detach: boolean" (optional)
11106 this argument exists only for compatibility reasons and is ignored
11107 by QEMU
11108 "resume: boolean" (optional)
11110 resume one paused migration, default "off". (since 3.0)
11111 Returns: nothing on success
11113 Since: 0.14.0
11115 Notes:
11117 1. The 'query-migrate' command should be used to check migration's
11119 progress and final result (this information is provided by the
11120 'status' member)
11121 2. All boolean arguments default to false
11123 3. The user Monitor's "detach" argument is invalid in QMP and should
11125 not be used
11126 Example:
11128 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
11130 <- { "return": {} }
11131 migrate-incoming (Command) Start an incoming migration, the qemu must
11133 have been started with -incoming defer
11134 Arguments:
11136 "uri: string"
11138 The Uniform Resource Identifier identifying the source or address
11139 to listen on
11140 Returns: nothing on success
11142 Since: 2.3
11144 Notes:
11146 1. It's a bad idea to use a string for the uri, but it needs to stay
11148 compatible with -incoming and the format of the uri is already
11149 exposed above libvirt.
11150 2. QEMU must be started with -incoming defer to allow migrate-incoming
11152 to be used.
11153 3. The uri format is the same as for -incoming
11155 Example:
11157 -> { "execute": "migrate-incoming",
11159 "arguments": { "uri": "tcp::4446" } }
11160 <- { "return": {} }
11161 xen-save-devices-state (Command) Save the state of all devices to
11163 file. The RAM and the block devices of the VM are not saved by this
11164 command.
11165 Arguments:
11167 "filename: string"
11169 the file to save the state of the devices to as binary data. See
11170 xen-save-devices-state.txt for a description of the binary format.
11171 "live: boolean" (optional)
11173 Optional argument to ask QEMU to treat this command as part of a
11174 live migration. Default to true. (since 2.11)
11175 Returns: Nothing on success
11177 Since: 1.1
11179 Example:
11181 -> { "execute": "xen-save-devices-state",
11183 "arguments": { "filename": "/tmp/save" } }
11184 <- { "return": {} }
11185 xen-set-replication (Command) Enable or disable replication.
11187 Arguments:
11189 "enable: boolean"
11191 true to enable, false to disable.
11192 "primary: boolean"
11194 true for primary or false for secondary.
11195 "failover: boolean" (optional)
11197 true to do failover, false to stop. but cannot be specified if
11198 'enable' is true. default value is false.
11199 Returns: nothing.
11201 Example:
11203 -> { "execute": "xen-set-replication",
11205 "arguments": {"enable": true, "primary": false} }
11206 <- { "return": {} }
11207 Since: 2.9
11209 ReplicationStatus (Object)
11211 The result format for 'query-xen-replication-status'.
11213 Members:
11215 "error: boolean"
11217 true if an error happened, false if replication is normal.
11218 "desc: string" (optional)
11220 the human readable error description string, when "error" is
11221 'true'.
11222 Since: 2.9
11224 query-xen-replication-status (Command) Query replication status while
11226 the vm is running.
11227 Returns: A "ReplicationResult" object showing the status.
11229 Example:
11231 -> { "execute": "query-xen-replication-status" }
11233 <- { "return": { "error": false } }
11234 Since: 2.9
11236 xen-colo-do-checkpoint (Command) Xen uses this command to notify
11238 replication to trigger a checkpoint.
11239 Returns: nothing.
11241 Example:
11243 -> { "execute": "xen-colo-do-checkpoint" }
11245 <- { "return": {} }
11246 Since: 2.9
11248 migrate-recover (Command) Provide a recovery migration stream URI.
11250 Arguments:
11252 "uri: string"
11254 the URI to be used for the recovery of migration stream.
11255 Returns: nothing.
11257 Example:
11259 -> { "execute": "migrate-recover",
11261 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
11262 <- { "return": {} }
11263 Since: 3.0
11265 migrate-pause (Command) Pause a migration. Currently it only supports
11267 postcopy.
11268 Returns: nothing.
11270 Example:
11272 -> { "execute": "migrate-pause" }
11274 <- { "return": {} }
11275 Since: 3.0
11277 Transactions
11279 Abort (Object)
11280 This action can be used to test transaction failure.
11282 Since: 1.6
11284 ActionCompletionMode (Enum)
11286 An enumeration of Transactional completion modes.
11288 Values:
11290 "individual"
11292 Do not attempt to cancel any other Actions if any Actions fail
11293 after the Transaction request succeeds. All Actions that can
11294 complete successfully will do so without waiting on others. This
11295 is the default.
11296 "grouped"
11298 If any Action fails after the Transaction succeeds, cancel all
11299 Actions. Actions do not complete until all Actions are ready to
11300 complete. May be rejected by Actions that do not support this
11301 completion mode.
11302 Since: 2.5
11304 TransactionAction (Object)
11306 A discriminated record of operations that can be performed with
11308 "transaction". Action "type" can be:
11309 - "abort": since 1.6
11311 - "block-dirty-bitmap-add": since 2.5
11313 - "block-dirty-bitmap-clear": since 2.5
11315 - "x-block-dirty-bitmap-enable": since 3.0
11317 - "x-block-dirty-bitmap-disable": since 3.0
11319 - "blockdev-backup": since 2.3
11321 - "blockdev-snapshot": since 2.5
11323 - "blockdev-snapshot-internal-sync": since 1.7
11325 - "blockdev-snapshot-sync": since 1.1
11327 - "drive-backup": since 1.6
11329 Members:
11331 "type"
11333 One of "abort", "block-dirty-bitmap-add", "block-dirty-bitmap-
11334 clear", "x-block-dirty-bitmap-enable", "x-block-dirty-bitmap-
11335 disable", "blockdev-backup", "blockdev-snapshot", "blockdev-
11336 snapshot-internal-sync", "blockdev-snapshot-sync", "drive-backup"
11337 "data: Abort" when "type" is "abort"
11339 "data: BlockDirtyBitmapAdd" when "type" is "block-dirty-bitmap-add"
11340 "data: BlockDirtyBitmap" when "type" is "block-dirty-bitmap-clear"
11341 "data: BlockDirtyBitmap" when "type" is "x-block-dirty-bitmap-enable"
11342 "data: BlockDirtyBitmap" when "type" is "x-block-dirty-bitmap-disable"
11343 "data: BlockdevBackup" when "type" is "blockdev-backup"
11344 "data: BlockdevSnapshot" when "type" is "blockdev-snapshot"
11345 "data: BlockdevSnapshotInternal" when "type" is "blockdev-snapshot-
11346 internal-sync"
11347 "data: BlockdevSnapshotSync" when "type" is "blockdev-snapshot-sync"
11348 "data: DriveBackup" when "type" is "drive-backup"
11349 Since: 1.1
11351 TransactionProperties (Object)
11353 Optional arguments to modify the behavior of a Transaction.
11355 Members:
11357 "completion-mode: ActionCompletionMode" (optional)
11359 Controls how jobs launched asynchronously by Actions will complete
11360 or fail as a group. See "ActionCompletionMode" for details.
11361 Since: 2.5
11363 transaction (Command) Executes a number of transactionable QMP
11365 commands atomically. If any operation fails, then the entire set of
11366 actions will be abandoned and the appropriate error returned.
11367 For external snapshots, the dictionary contains the device, the file to
11369 use for the new snapshot, and the format. The default format, if not
11370 specified, is qcow2.
11371 Each new snapshot defaults to being created by QEMU (wiping any
11373 contents if the file already exists), but it is also possible to reuse
11374 an externally-created file. In the latter case, you should ensure that
11375 the new image file has the same contents as the current one; QEMU
11376 cannot perform any meaningful check. Typically this is achieved by
11377 using the current image file as the backing file for the new image.
11378 On failure, the original disks pre-snapshot attempt will be used.
11380 For internal snapshots, the dictionary contains the device and the
11382 snapshot's name. If an internal snapshot matching name already exists,
11383 the request will be rejected. Only some image formats support it, for
11384 example, qcow2, rbd, and sheepdog.
11385 On failure, qemu will try delete the newly created internal snapshot in
11387 the transaction. When an I/O error occurs during deletion, the user
11388 needs to fix it later with qemu-img or other command.
11389 Arguments:
11391 "actions: array of TransactionAction"
11393 List of "TransactionAction"; information needed for the respective
11394 operations.
11395 "properties: TransactionProperties" (optional)
11397 structure of additional options to control the execution of the
11398 transaction. See "TransactionProperties" for additional detail.
11399 Returns: nothing on success
11401 Errors depend on the operations of the transaction
11403 Note: The transaction aborts on the first failure. Therefore, there
11405 will be information on only one failed operation returned in an error
11406 condition, and subsequent actions will not have been attempted.
11407 Since: 1.1
11409 Example:
11411 -> { "execute": "transaction",
11413 "arguments": { "actions": [
11414 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
11415 "snapshot-file": "/some/place/my-image",
11416 "format": "qcow2" } },
11417 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
11418 "snapshot-file": "/some/place/my-image2",
11419 "snapshot-node-name": "node3432",
11420 "mode": "existing",
11421 "format": "qcow2" } },
11422 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
11423 "snapshot-file": "/some/place/my-image2",
11424 "mode": "existing",
11425 "format": "qcow2" } },
11426 { "type": "blockdev-snapshot-internal-sync", "data" : {
11427 "device": "ide-hd2",
11428 "name": "snapshot0" } } ] } }
11429 <- { "return": {} }
11430 Tracing
11432 TraceEventState (Enum)
11433 State of a tracing event.
11435 Values:
11437 "unavailable"
11439 The event is statically disabled.
11440 "disabled"
11442 The event is dynamically disabled.
11443 "enabled"
11445 The event is dynamically enabled.
11446 Since: 2.2
11448 TraceEventInfo (Object)
11450 Information of a tracing event.
11452 Members:
11454 "name: string"
11456 Event name.
11457 "state: TraceEventState"
11459 Tracing state.
11460 "vcpu: boolean"
11462 Whether this is a per-vCPU event (since 2.7).
11463 An event is per-vCPU if it has the "vcpu" property in the "trace-
11465 events" files.
11466 Since: 2.2
11468 trace-event-get-state (Command) Query the state of events.
11470 Arguments:
11472 "name: string"
11474 Event name pattern (case-sensitive glob).
11475 "vcpu: int" (optional)
11477 The vCPU to query (any by default; since 2.7).
11478 Returns: a list of "TraceEventInfo" for the matching events
11480 An event is returned if:
11482 - its name matches the "name" pattern, and
11484 - if "vcpu" is given, the event has the "vcpu" property.
11486 Therefore, if "vcpu" is given, the operation will only match per-vCPU
11488 events, returning their state on the specified vCPU. Special case: if
11489 "name" is an exact match, "vcpu" is given and the event does not have
11490 the "vcpu" property, an error is returned.
11491 Since: 2.2
11493 Example:
11495 -> { "execute": "trace-event-get-state",
11497 "arguments": { "name": "qemu_memalign" } }
11498 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
11499 trace-event-set-state (Command) Set the dynamic tracing state of
11501 events.
11502 Arguments:
11504 "name: string"
11506 Event name pattern (case-sensitive glob).
11507 "enable: boolean"
11509 Whether to enable tracing.
11510 "ignore-unavailable: boolean" (optional)
11512 Do not match unavailable events with "name".
11513 "vcpu: int" (optional)
11515 The vCPU to act upon (all by default; since 2.7).
11516 An event's state is modified if:
11518 - its name matches the "name" pattern, and
11520 - if "vcpu" is given, the event has the "vcpu" property.
11522 Therefore, if "vcpu" is given, the operation will only match per-vCPU
11524 events, setting their state on the specified vCPU. Special case: if
11525 "name" is an exact match, "vcpu" is given and the event does not have
11526 the "vcpu" property, an error is returned.
11527 Since: 2.2
11529 Example:
11531 -> { "execute": "trace-event-set-state",
11533 "arguments": { "name": "qemu_memalign", "enable": "true" } }
11534 <- { "return": {} }
11535 QMP introspection
11537 query-qmp-schema (Command) Command query-qmp-schema exposes the QMP
11538 wire ABI as an array of SchemaInfo. This lets QMP clients figure out
11539 what commands and events are available in this QEMU, and their
11540 parameters and results.
11541 However, the SchemaInfo can't reflect all the rules and restrictions
11543 that apply to QMP. It's interface introspection (figuring out what's
11544 there), not interface specification. The specification is in the QAPI
11545 schema.
11546 Furthermore, while we strive to keep the QMP wire format backwards-
11548 compatible across qemu versions, the introspection output is not
11549 guaranteed to have the same stability. For example, one version of
11550 qemu may list an object member as an optional non-variant, while
11551 another lists the same member only through the object's variants; or
11552 the type of a member may change from a generic string into a specific
11553 enum or from one specific type into an alternate that includes the
11554 original type alongside something else.
11555 Returns: array of "SchemaInfo", where each element describes an entity
11557 in the ABI: command, event, type, ...
11558 The order of the various SchemaInfo is unspecified; however, all names
11560 are guaranteed to be unique (no name will be duplicated with different
11561 meta-types).
11562 Note: the QAPI schema is also used to help define internal interfaces,
11564 by defining QAPI types. These are not part of the QMP wire ABI, and
11565 therefore not returned by this command.
11566 Since: 2.5
11568 SchemaMetaType (Enum)
11570 This is a "SchemaInfo"'s meta type, i.e. the kind of entity it
11572 describes.
11573 Values:
11575 "builtin"
11577 a predefined type such as 'int' or 'bool'.
11578 "enum"
11580 an enumeration type
11581 "array"
11583 an array type
11584 "object"
11586 an object type (struct or union)
11587 "alternate"
11589 an alternate type
11590 "command"
11592 a QMP command
11593 "event"
11595 a QMP event
11596 Since: 2.5
11598 SchemaInfo (Object)
11600 Members:
11602 "name: string"
11604 the entity's name, inherited from "base". The SchemaInfo is always
11605 referenced by this name. Commands and events have the name defined
11606 in the QAPI schema. Unlike command and event names, type names are
11607 not part of the wire ABI. Consequently, type names are meaningless
11608 strings here, although they are still guaranteed unique regardless
11609 of "meta-type".
11610 "meta-type: SchemaMetaType"
11612 the entity's meta type, inherited from "base".
11613 The members of "SchemaInfoBuiltin" when "meta-type" is "builtin"
11615 The members of "SchemaInfoEnum" when "meta-type" is "enum"
11616 The members of "SchemaInfoArray" when "meta-type" is "array"
11617 The members of "SchemaInfoObject" when "meta-type" is "object"
11618 The members of "SchemaInfoAlternate" when "meta-type" is "alternate"
11619 The members of "SchemaInfoCommand" when "meta-type" is "command"
11620 The members of "SchemaInfoEvent" when "meta-type" is "event"
11621 Additional members depend on the value of "meta-type".
11623 Since: 2.5
11625 SchemaInfoBuiltin (Object)
11627 Additional SchemaInfo members for meta-type 'builtin'.
11629 Members:
11631 "json-type: JSONType"
11633 the JSON type used for this type on the wire.
11634 Since: 2.5
11636 JSONType (Enum)
11638 The four primitive and two structured types according to RFC 7159
11640 section 1, plus 'int' (split off 'number'), plus the obvious top type
11641 'value'.
11642 Values:
11644 "string"
11646 Not documented
11647 "number"
11649 Not documented
11650 "int"
11652 Not documented
11653 "boolean"
11655 Not documented
11656 "null"
11658 Not documented
11659 "object"
11661 Not documented
11662 "array"
11664 Not documented
11665 "value"
11667 Not documented
11668 Since: 2.5
11670 SchemaInfoEnum (Object)
11672 Additional SchemaInfo members for meta-type 'enum'.
11674 Members:
11676 "values: array of string"
11678 the enumeration type's values, in no particular order.
11679 Values of this type are JSON string on the wire.
11681 Since: 2.5
11683 SchemaInfoArray (Object)
11685 Additional SchemaInfo members for meta-type 'array'.
11687 Members:
11689 "element-type: string"
11691 the array type's element type.
11692 Values of this type are JSON array on the wire.
11694 Since: 2.5
11696 SchemaInfoObject (Object)
11698 Additional SchemaInfo members for meta-type 'object'.
11700 Members:
11702 "members: array of SchemaInfoObjectMember"
11704 the object type's (non-variant) members, in no particular order.
11705 "tag: string" (optional)
11707 the name of the member serving as type tag. An element of
11708 "members" with this name must exist.
11709 "variants: array of SchemaInfoObjectVariant" (optional)
11711 variant members, i.e. additional members that depend on the type
11712 tag's value. Present exactly when "tag" is present. The variants
11713 are in no particular order, and may even differ from the order of
11714 the values of the enum type of the "tag".
11715 Values of this type are JSON object on the wire.
11717 Since: 2.5
11719 SchemaInfoObjectMember (Object)
11721 An object member.
11723 Members:
11725 "name: string"
11727 the member's name, as defined in the QAPI schema.
11728 "type: string"
11730 the name of the member's type.
11731 "default: value" (optional)
11733 default when used as command parameter. If absent, the parameter
11734 is mandatory. If present, the value must be null. The parameter
11735 is optional, and behavior when it's missing is not specified here.
11736 Future extension: if present and non-null, the parameter is
11737 optional, and defaults to this value.
11738 Since: 2.5
11740 SchemaInfoObjectVariant (Object)
11742 The variant members for a value of the type tag.
11744 Members:
11746 "case: string"
11748 a value of the type tag.
11749 "type: string"
11751 the name of the object type that provides the variant members when
11752 the type tag has value "case".
11753 Since: 2.5
11755 SchemaInfoAlternate (Object)
11757 Additional SchemaInfo members for meta-type 'alternate'.
11759 Members:
11761 "members: array of SchemaInfoAlternateMember"
11763 the alternate type's members, in no particular order. The members'
11764 wire encoding is distinct, see docs/devel/qapi-code-gen.txt section
11765 Alternate types.
11766 On the wire, this can be any of the members.
11768 Since: 2.5
11770 SchemaInfoAlternateMember (Object)
11772 An alternate member.
11774 Members:
11776 "type: string"
11778 the name of the member's type.
11779 Since: 2.5
11781 SchemaInfoCommand (Object)
11783 Additional SchemaInfo members for meta-type 'command'.
11785 Members:
11787 "arg-type: string"
11789 the name of the object type that provides the command's parameters.
11790 "ret-type: string"
11792 the name of the command's result type.
11793 "allow-oob: boolean" (optional)
11795 whether the command allows out-of-band execution, defaults to false
11796 (Since: 2.12)
11797 TODO: "success-response" (currently irrelevant, because it's QGA, not
11799 QMP)
11800 Since: 2.5
11802 SchemaInfoEvent (Object)
11804 Additional SchemaInfo members for meta-type 'event'.
11806 Members:
11808 "arg-type: string"
11810 the name of the object type that provides the event's parameters.
11811 Since: 2.5
11813 Miscellanea
11815 qmp_capabilities (Command) Enable QMP capabilities.
11816 Arguments:
11818 Arguments:
11820 "enable: array of QMPCapability" (optional)
11822 An optional list of QMPCapability values to enable. The client
11823 must not enable any capability that is not mentioned in the QMP
11824 greeting message. If the field is not provided, it means no QMP
11825 capabilities will be enabled. (since 2.12)
11826 Example:
11828 -> { "execute": "qmp_capabilities",
11830 "arguments": { "enable": [ "oob" ] } }
11831 <- { "return": {} }
11832 Notes: This command is valid exactly when first connecting: it must be
11834 issued before any other command will be accepted, and will fail once
11835 the monitor is accepting other commands. (see qemu
11836 docs/interop/qmp-spec.txt)
11837 The QMP client needs to explicitly enable QMP capabilities, otherwise
11839 all the QMP capabilities will be turned off by default.
11840 Since: 0.13
11842 QMPCapability (Enum)
11844 Enumeration of capabilities to be advertised during initial client
11846 connection, used for agreeing on particular QMP extension behaviors.
11847 Values:
11849 "oob"
11851 QMP ability to support out-of-band requests. (Please refer to
11852 qmp-spec.txt for more information on OOB)
11853 Since: 2.12
11855 VersionTriple (Object)
11857 A three-part version number.
11859 Members:
11861 "major: int"
11863 The major version number.
11864 "minor: int"
11866 The minor version number.
11867 "micro: int"
11869 The micro version number.
11870 Since: 2.4
11872 VersionInfo (Object)
11874 A description of QEMU's version.
11876 Members:
11878 "qemu: VersionTriple"
11880 The version of QEMU. By current convention, a micro version of 50
11881 signifies a development branch. A micro version greater than or
11882 equal to 90 signifies a release candidate for the next minor
11883 version. A micro version of less than 50 signifies a stable
11884 release.
11885 "package: string"
11887 QEMU will always set this field to an empty string. Downstream
11888 versions of QEMU should set this to a non-empty string. The exact
11889 format depends on the downstream however it highly recommended that
11890 a unique name is used.
11891 Since: 0.14.0
11893 query-version (Command) Returns the current version of QEMU.
11895 Returns: A "VersionInfo" object describing the current version of QEMU.
11897 Since: 0.14.0
11899 Example:
11901 -> { "execute": "query-version" }
11903 <- {
11904 "return":{
11905 "qemu":{
11906 "major":0,
11907 "minor":11,
11908 "micro":5
11909 },
11910 "package":""
11911 }
11912 }
11913 CommandInfo (Object)
11915 Information about a QMP command
11917 Members:
11919 "name: string"
11921 The command name
11922 Since: 0.14.0
11924 query-commands (Command) Return a list of supported QMP commands by
11926 this server
11927 Returns: A list of "CommandInfo" for all supported commands
11929 Since: 0.14.0
11931 Example:
11933 -> { "execute": "query-commands" }
11935 <- {
11936 "return":[
11937 {
11938 "name":"query-balloon"
11939 },
11940 {
11941 "name":"system_powerdown"
11942 }
11943 ]
11944 }
11945 Note: This example has been shortened as the real response is too long.
11947 LostTickPolicy (Enum)
11949 Policy for handling lost ticks in timer devices.
11951 Values:
11953 "discard"
11955 throw away the missed tick(s) and continue with future injection
11956 normally. Guest time may be delayed, unless the OS has explicit
11957 handling of lost ticks
11958 "delay"
11960 continue to deliver ticks at the normal rate. Guest time will be
11961 delayed due to the late tick
11962 "merge"
11964 merge the missed tick(s) into one tick and inject. Guest time may
11965 be delayed, depending on how the OS reacts to the merging of ticks
11966 "slew"
11968 deliver ticks at a higher rate to catch up with the missed tick.
11969 The guest time should not be delayed once catchup is complete.
11970 Since: 2.0
11972 add_client (Command) Allow client connections for VNC, Spice and
11974 socket based character devices to be passed in to QEMU via SCM_RIGHTS.
11975 Arguments:
11977 "protocol: string"
11979 protocol name. Valid names are "vnc", "spice" or the name of a
11980 character device (eg. from -chardev id=XXXX)
11981 "fdname: string"
11983 file descriptor name previously passed via 'getfd' command
11984 "skipauth: boolean" (optional)
11986 whether to skip authentication. Only applies to "vnc" and "spice"
11987 protocols
11988 "tls: boolean" (optional)
11990 whether to perform TLS. Only applies to the "spice" protocol
11991 Returns: nothing on success.
11993 Since: 0.14.0
11995 Example:
11997 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
11999 "fdname": "myclient" } }
12000 <- { "return": {} }
12001 NameInfo (Object)
12003 Guest name information.
12005 Members:
12007 "name: string" (optional)
12009 The name of the guest
12010 Since: 0.14.0
12012 query-name (Command) Return the name information of a guest.
12014 Returns: "NameInfo" of the guest
12016 Since: 0.14.0
12018 Example:
12020 -> { "execute": "query-name" }
12022 <- { "return": { "name": "qemu-name" } }
12023 KvmInfo (Object)
12025 Information about support for KVM acceleration
12027 Members:
12029 "enabled: boolean"
12031 true if KVM acceleration is active
12032 "present: boolean"
12034 true if KVM acceleration is built into this executable
12035 Since: 0.14.0
12037 query-kvm (Command) Returns information about KVM acceleration
12039 Returns: "KvmInfo"
12041 Since: 0.14.0
12043 Example:
12045 -> { "execute": "query-kvm" }
12047 <- { "return": { "enabled": true, "present": true } }
12048 UuidInfo (Object)
12050 Guest UUID information (Universally Unique Identifier).
12052 Members:
12054 "UUID: string"
12056 the UUID of the guest
12057 Since: 0.14.0
12059 Notes: If no UUID was specified for the guest, a null UUID is returned.
12061 query-uuid (Command) Query the guest UUID information.
12063 Returns: The "UuidInfo" for the guest
12065 Since: 0.14.0
12067 Example:
12069 -> { "execute": "query-uuid" }
12071 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
12072 EventInfo (Object)
12074 Information about a QMP event
12076 Members:
12078 "name: string"
12080 The event name
12081 Since: 1.2.0
12083 query-events (Command) Return a list of supported QMP events by this
12085 server
12086 Returns: A list of "EventInfo" for all supported events
12088 Since: 1.2.0
12090 Example:
12092 -> { "execute": "query-events" }
12094 <- {
12095 "return": [
12096 {
12097 "name":"SHUTDOWN"
12098 },
12099 {
12100 "name":"RESET"
12101 }
12102 ]
12103 }
12104 Note: This example has been shortened as the real response is too long.
12106 CpuInfoArch (Enum)
12108 An enumeration of cpu types that enable additional information during
12110 "query-cpus" and "query-cpus-fast".
12111 Values:
12113 "s390"
12115 since 2.12
12116 "riscv"
12118 since 2.12
12119 "x86"
12121 Not documented
12122 "sparc"
12124 Not documented
12125 "ppc"
12127 Not documented
12128 "mips"
12130 Not documented
12131 "tricore"
12133 Not documented
12134 "other"
12136 Not documented
12137 Since: 2.6
12139 CpuInfo (Object)
12141 Information about a virtual CPU
12143 Members:
12145 "CPU: int"
12147 the index of the virtual CPU
12148 "current: boolean"
12150 this only exists for backwards compatibility and should be ignored
12151 "halted: boolean"
12153 true if the virtual CPU is in the halt state. Halt usually refers
12154 to a processor specific low power mode.
12155 "qom_path: string"
12157 path to the CPU object in the QOM tree (since 2.4)
12158 "thread_id: int"
12160 ID of the underlying host thread
12161 "props: CpuInstanceProperties" (optional)
12163 properties describing to which node/socket/core/thread virtual CPU
12164 belongs to, provided if supported by board (since 2.10)
12165 "arch: CpuInfoArch"
12167 architecture of the cpu, which determines which additional fields
12168 will be listed (since 2.6)
12169 The members of "CpuInfoX86" when "arch" is "x86"
12171 The members of "CpuInfoSPARC" when "arch" is "sparc"
12172 The members of "CpuInfoPPC" when "arch" is "ppc"
12173 The members of "CpuInfoMIPS" when "arch" is "mips"
12174 The members of "CpuInfoTricore" when "arch" is "tricore"
12175 The members of "CpuInfoS390" when "arch" is "s390"
12176 The members of "CpuInfoRISCV" when "arch" is "riscv"
12177 Since: 0.14.0
12179 Notes: "halted" is a transient state that changes frequently. By the
12181 time the data is sent to the client, the guest may no longer be halted.
12182 CpuInfoX86 (Object)
12184 Additional information about a virtual i386 or x86_64 CPU
12186 Members:
12188 "pc: int"
12190 the 64-bit instruction pointer
12191 Since: 2.6
12193 CpuInfoSPARC (Object)
12195 Additional information about a virtual SPARC CPU
12197 Members:
12199 "pc: int"
12201 the PC component of the instruction pointer
12202 "npc: int"
12204 the NPC component of the instruction pointer
12205 Since: 2.6
12207 CpuInfoPPC (Object)
12209 Additional information about a virtual PPC CPU
12211 Members:
12213 "nip: int"
12215 the instruction pointer
12216 Since: 2.6
12218 CpuInfoMIPS (Object)
12220 Additional information about a virtual MIPS CPU
12222 Members:
12224 "PC: int"
12226 the instruction pointer
12227 Since: 2.6
12229 CpuInfoTricore (Object)
12231 Additional information about a virtual Tricore CPU
12233 Members:
12235 "PC: int"
12237 the instruction pointer
12238 Since: 2.6
12240 CpuInfoRISCV (Object)
12242 Additional information about a virtual RISCV CPU
12244 Members:
12246 "pc: int"
12248 the instruction pointer
12249 Since 2.12
12251 CpuS390State (Enum)
12253 An enumeration of cpu states that can be assumed by a virtual S390 CPU
12255 Values:
12257 "uninitialized"
12259 Not documented
12260 "stopped"
12262 Not documented
12263 "check-stop"
12265 Not documented
12266 "operating"
12268 Not documented
12269 "load"
12271 Not documented
12272 Since: 2.12
12274 CpuInfoS390 (Object)
12276 Additional information about a virtual S390 CPU
12278 Members:
12280 "cpu-state: CpuS390State"
12282 the virtual CPU's state
12283 Since: 2.12
12285 query-cpus (Command) Returns a list of information about each virtual
12287 CPU.
12288 This command causes vCPU threads to exit to userspace, which causes a
12290 small interruption to guest CPU execution. This will have a negative
12291 impact on realtime guests and other latency sensitive guest workloads.
12292 It is recommended to use "query-cpus-fast" instead of this command to
12293 avoid the vCPU interruption.
12294 Returns: a list of "CpuInfo" for each virtual CPU
12296 Since: 0.14.0
12298 Example:
12300 -> { "execute": "query-cpus" }
12302 <- { "return": [
12303 {
12304 "CPU":0,
12305 "current":true,
12306 "halted":false,
12307 "qom_path":"/machine/unattached/device[0]",
12308 "arch":"x86",
12309 "pc":3227107138,
12310 "thread_id":3134
12311 },
12312 {
12313 "CPU":1,
12314 "current":false,
12315 "halted":true,
12316 "qom_path":"/machine/unattached/device[2]",
12317 "arch":"x86",
12318 "pc":7108165,
12319 "thread_id":3135
12320 }
12321 ]
12322 }
12323 Notes: This interface is deprecated (since 2.12.0), and it is strongly
12325 recommended that you avoid using it. Use "query-cpus-fast" to obtain
12326 information about virtual CPUs.
12327 CpuInfoFast (Object)
12329 Information about a virtual CPU
12331 Members:
12333 "cpu-index: int"
12335 index of the virtual CPU
12336 "qom-path: string"
12338 path to the CPU object in the QOM tree
12339 "thread-id: int"
12341 ID of the underlying host thread
12342 "props: CpuInstanceProperties" (optional)
12344 properties describing to which node/socket/core/thread virtual CPU
12345 belongs to, provided if supported by board
12346 "arch: CpuInfoArch"
12348 base architecture of the cpu; deprecated since 3.0.0 in favor of
12349 "target"
12350 "target: SysEmuTarget"
12352 the QEMU system emulation target, which determines which additional
12353 fields will be listed (since 3.0)
12354 The members of "CpuInfoS390" when "target" is "s390x"
12356 Since: 2.12
12358 query-cpus-fast (Command) Returns information about all virtual CPUs.
12360 This command does not incur a performance penalty and should be used in
12361 production instead of query-cpus.
12362 Returns: list of "CpuInfoFast"
12364 Since: 2.12
12366 Example:
12368 -> { "execute": "query-cpus-fast" }
12370 <- { "return": [
12371 {
12372 "thread-id": 25627,
12373 "props": {
12374 "core-id": 0,
12375 "thread-id": 0,
12376 "socket-id": 0
12377 },
12378 "qom-path": "/machine/unattached/device[0]",
12379 "arch":"x86",
12380 "target":"x86_64",
12381 "cpu-index": 0
12382 },
12383 {
12384 "thread-id": 25628,
12385 "props": {
12386 "core-id": 0,
12387 "thread-id": 0,
12388 "socket-id": 1
12389 },
12390 "qom-path": "/machine/unattached/device[2]",
12391 "arch":"x86",
12392 "target":"x86_64",
12393 "cpu-index": 1
12394 }
12395 ]
12396 }
12397 IOThreadInfo (Object)
12399 Information about an iothread
12401 Members:
12403 "id: string"
12405 the identifier of the iothread
12406 "thread-id: int"
12408 ID of the underlying host thread
12409 "poll-max-ns: int"
12411 maximum polling time in ns, 0 means polling is disabled (since 2.9)
12412 "poll-grow: int"
12414 how many ns will be added to polling time, 0 means that it's not
12415 configured (since 2.9)
12416 "poll-shrink: int"
12418 how many ns will be removed from polling time, 0 means that it's
12419 not configured (since 2.9)
12420 Since: 2.0
12422 query-iothreads (Command) Returns a list of information about each
12424 iothread.
12425 Note: this list excludes the QEMU main loop thread, which is not
12427 declared using the -object iothread command-line option. It is always
12428 the main thread of the process.
12429 Returns: a list of "IOThreadInfo" for each iothread
12431 Since: 2.0
12433 Example:
12435 -> { "execute": "query-iothreads" }
12437 <- { "return": [
12438 {
12439 "id":"iothread0",
12440 "thread-id":3134
12441 },
12442 {
12443 "id":"iothread1",
12444 "thread-id":3135
12445 }
12446 ]
12447 }
12448 BalloonInfo (Object)
12450 Information about the guest balloon device.
12452 Members:
12454 "actual: int"
12456 the number of bytes the balloon currently contains
12457 Since: 0.14.0
12459 query-balloon (Command) Return information about the balloon device.
12461 Returns: "BalloonInfo" on success
12463 If the balloon driver is enabled but not functional because the KVM
12465 kernel module cannot support it, KvmMissingCap
12466 If no balloon device is present, DeviceNotActive
12468 Since: 0.14.0
12470 Example:
12472 -> { "execute": "query-balloon" }
12474 <- { "return": {
12475 "actual": 1073741824,
12476 }
12477 }
12478 BALLOON_CHANGE (Event) Emitted when the guest changes the actual
12480 BALLOON level. This value is equivalent to the "actual" field return by
12481 the 'query-balloon' command
12482 Arguments:
12484 "actual: int"
12486 actual level of the guest memory balloon in bytes
12487 Note: this event is rate-limited.
12489 Since: 1.2
12491 Example:
12493 <- { "event": "BALLOON_CHANGE",
12495 "data": { "actual": 944766976 },
12496 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
12497 PciMemoryRange (Object)
12499 A PCI device memory region
12501 Members:
12503 "base: int"
12505 the starting address (guest physical)
12506 "limit: int"
12508 the ending address (guest physical)
12509 Since: 0.14.0
12511 PciMemoryRegion (Object)
12513 Information about a PCI device I/O region.
12515 Members:
12517 "bar: int"
12519 the index of the Base Address Register for this region
12520 "type: string"
12522 'io' if the region is a PIO region 'memory' if the region is a MMIO
12523 region
12524 "size: int"
12526 memory size
12527 "prefetch: boolean" (optional)
12529 if "type" is 'memory', true if the memory is prefetchable
12530 "mem_type_64: boolean" (optional)
12532 if "type" is 'memory', true if the BAR is 64-bit
12533 "address: int"
12535 Not documented
12536 Since: 0.14.0
12538 PciBusInfo (Object)
12540 Information about a bus of a PCI Bridge device
12542 Members:
12544 "number: int"
12546 primary bus interface number. This should be the number of the bus
12547 the device resides on.
12548 "secondary: int"
12550 secondary bus interface number. This is the number of the main bus
12551 for the bridge
12552 "subordinate: int"
12554 This is the highest number bus that resides below the bridge.
12555 "io_range: PciMemoryRange"
12557 The PIO range for all devices on this bridge
12558 "memory_range: PciMemoryRange"
12560 The MMIO range for all devices on this bridge
12561 "prefetchable_range: PciMemoryRange"
12563 The range of prefetchable MMIO for all devices on this bridge
12564 Since: 2.4
12566 PciBridgeInfo (Object)
12568 Information about a PCI Bridge device
12570 Members:
12572 "bus: PciBusInfo"
12574 information about the bus the device resides on
12575 "devices: array of PciDeviceInfo" (optional)
12577 a list of "PciDeviceInfo" for each device on this bridge
12578 Since: 0.14.0
12580 PciDeviceClass (Object)
12582 Information about the Class of a PCI device
12584 Members:
12586 "desc: string" (optional)
12588 a string description of the device's class
12589 "class: int"
12591 the class code of the device
12592 Since: 2.4
12594 PciDeviceId (Object)
12596 Information about the Id of a PCI device
12598 Members:
12600 "device: int"
12602 the PCI device id
12603 "vendor: int"
12605 the PCI vendor id
12606 Since: 2.4
12608 PciDeviceInfo (Object)
12610 Information about a PCI device
12612 Members:
12614 "bus: int"
12616 the bus number of the device
12617 "slot: int"
12619 the slot the device is located in
12620 "function: int"
12622 the function of the slot used by the device
12623 "class_info: PciDeviceClass"
12625 the class of the device
12626 "id: PciDeviceId"
12628 the PCI device id
12629 "irq: int" (optional)
12631 if an IRQ is assigned to the device, the IRQ number
12632 "qdev_id: string"
12634 the device name of the PCI device
12635 "pci_bridge: PciBridgeInfo" (optional)
12637 if the device is a PCI bridge, the bridge information
12638 "regions: array of PciMemoryRegion"
12640 a list of the PCI I/O regions associated with the device
12641 Notes: the contents of "class_info".desc are not stable and should only
12643 be treated as informational.
12644 Since: 0.14.0
12646 PciInfo (Object)
12648 Information about a PCI bus
12650 Members:
12652 "bus: int"
12654 the bus index
12655 "devices: array of PciDeviceInfo"
12657 a list of devices on this bus
12658 Since: 0.14.0
12660 query-pci (Command) Return information about the PCI bus topology of
12662 the guest.
12663 Returns: a list of "PciInfo" for each PCI bus. Each bus is represented
12665 by a json-object, which has a key with a json-array of all PCI devices
12666 attached to it. Each device is represented by a json-object.
12667 Since: 0.14.0
12669 Example:
12671 -> { "execute": "query-pci" }
12673 <- { "return": [
12674 {
12675 "bus": 0,
12676 "devices": [
12677 {
12678 "bus": 0,
12679 "qdev_id": "",
12680 "slot": 0,
12681 "class_info": {
12682 "class": 1536,
12683 "desc": "Host bridge"
12684 },
12685 "id": {
12686 "device": 32902,
12687 "vendor": 4663
12688 },
12689 "function": 0,
12690 "regions": [
12691 ]
12692 },
12693 {
12694 "bus": 0,
12695 "qdev_id": "",
12696 "slot": 1,
12697 "class_info": {
12698 "class": 1537,
12699 "desc": "ISA bridge"
12700 },
12701 "id": {
12702 "device": 32902,
12703 "vendor": 28672
12704 },
12705 "function": 0,
12706 "regions": [
12707 ]
12708 },
12709 {
12710 "bus": 0,
12711 "qdev_id": "",
12712 "slot": 1,
12713 "class_info": {
12714 "class": 257,
12715 "desc": "IDE controller"
12716 },
12717 "id": {
12718 "device": 32902,
12719 "vendor": 28688
12720 },
12721 "function": 1,
12722 "regions": [
12723 {
12724 "bar": 4,
12725 "size": 16,
12726 "address": 49152,
12727 "type": "io"
12728 }
12729 ]
12730 },
12731 {
12732 "bus": 0,
12733 "qdev_id": "",
12734 "slot": 2,
12735 "class_info": {
12736 "class": 768,
12737 "desc": "VGA controller"
12738 },
12739 "id": {
12740 "device": 4115,
12741 "vendor": 184
12742 },
12743 "function": 0,
12744 "regions": [
12745 {
12746 "prefetch": true,
12747 "mem_type_64": false,
12748 "bar": 0,
12749 "size": 33554432,
12750 "address": 4026531840,
12751 "type": "memory"
12752 },
12753 {
12754 "prefetch": false,
12755 "mem_type_64": false,
12756 "bar": 1,
12757 "size": 4096,
12758 "address": 4060086272,
12759 "type": "memory"
12760 },
12761 {
12762 "prefetch": false,
12763 "mem_type_64": false,
12764 "bar": 6,
12765 "size": 65536,
12766 "address": -1,
12767 "type": "memory"
12768 }
12769 ]
12770 },
12771 {
12772 "bus": 0,
12773 "qdev_id": "",
12774 "irq": 11,
12775 "slot": 4,
12776 "class_info": {
12777 "class": 1280,
12778 "desc": "RAM controller"
12779 },
12780 "id": {
12781 "device": 6900,
12782 "vendor": 4098
12783 },
12784 "function": 0,
12785 "regions": [
12786 {
12787 "bar": 0,
12788 "size": 32,
12789 "address": 49280,
12790 "type": "io"
12791 }
12792 ]
12793 }
12794 ]
12795 }
12796 ]
12797 }
12798 Note: This example has been shortened as the real response is too long.
12800 quit (Command) This command will cause the QEMU process to exit
12802 gracefully. While every attempt is made to send the QMP response
12803 before terminating, this is not guaranteed. When using this interface,
12804 a premature EOF would not be unexpected.
12805 Since: 0.14.0
12807 Example:
12809 -> { "execute": "quit" }
12811 <- { "return": {} }
12812 stop (Command) Stop all guest VCPU execution.
12814 Since: 0.14.0
12816 Notes: This function will succeed even if the guest is already in the
12818 stopped state. In "inmigrate" state, it will ensure that the guest
12819 remains paused once migration finishes, as if the -S option was passed
12820 on the command line.
12821 Example:
12823 -> { "execute": "stop" }
12825 <- { "return": {} }
12826 system_reset (Command) Performs a hard reset of a guest.
12828 Since: 0.14.0
12830 Example:
12832 -> { "execute": "system_reset" }
12834 <- { "return": {} }
12835 system_powerdown (Command) Requests that a guest perform a powerdown
12837 operation.
12838 Since: 0.14.0
12840 Notes: A guest may or may not respond to this command. This command
12842 returning does not indicate that a guest has accepted the request or
12843 that it has shut down. Many guests will respond to this command by
12844 prompting the user in some way.
12845 Example:
12847 -> { "execute": "system_powerdown" }
12849 <- { "return": {} }
12850 cpu-add (Command) Adds CPU with specified ID
12852 Arguments:
12854 "id: int"
12856 ID of CPU to be created, valid values [0..max_cpus)
12857 Returns: Nothing on success
12859 Since: 1.5
12861 Example:
12863 -> { "execute": "cpu-add", "arguments": { "id": 2 } }
12865 <- { "return": {} }
12866 memsave (Command) Save a portion of guest memory to a file.
12868 Arguments:
12870 "val: int"
12872 the virtual address of the guest to start from
12873 "size: int"
12875 the size of memory region to save
12876 "filename: string"
12878 the file to save the memory to as binary data
12879 "cpu-index: int" (optional)
12881 the index of the virtual CPU to use for translating the virtual
12882 address (defaults to CPU 0)
12883 Returns: Nothing on success
12885 Since: 0.14.0
12887 Notes: Errors were not reliably returned until 1.1
12889 Example:
12891 -> { "execute": "memsave",
12893 "arguments": { "val": 10,
12894 "size": 100,
12895 "filename": "/tmp/virtual-mem-dump" } }
12896 <- { "return": {} }
12897 pmemsave (Command) Save a portion of guest physical memory to a file.
12899 Arguments:
12901 "val: int"
12903 the physical address of the guest to start from
12904 "size: int"
12906 the size of memory region to save
12907 "filename: string"
12909 the file to save the memory to as binary data
12910 Returns: Nothing on success
12912 Since: 0.14.0
12914 Notes: Errors were not reliably returned until 1.1
12916 Example:
12918 -> { "execute": "pmemsave",
12920 "arguments": { "val": 10,
12921 "size": 100,
12922 "filename": "/tmp/physical-mem-dump" } }
12923 <- { "return": {} }
12924 cont (Command) Resume guest VCPU execution.
12926 Since: 0.14.0
12928 Returns: If successful, nothing
12930 Notes: This command will succeed if the guest is currently running. It
12932 will also succeed if the guest is in the "inmigrate" state; in this
12933 case, the effect of the command is to make sure the guest starts once
12934 migration finishes, removing the effect of the -S command line option
12935 if it was passed.
12936 Example:
12938 -> { "execute": "cont" }
12940 <- { "return": {} }
12941 x-exit-preconfig (Command) Exit from "preconfig" state
12943 This command makes QEMU exit the preconfig state and proceed with VM
12945 initialization using configuration data provided on the command line
12946 and via the QMP monitor during the preconfig state. The command is only
12947 available during the preconfig state (i.e. when the --preconfig command
12948 line option was in use).
12949 Since 3.0
12951 Returns: nothing
12953 Example:
12955 -> { "execute": "x-exit-preconfig" }
12957 <- { "return": {} }
12958 system_wakeup (Command) Wakeup guest from suspend. Does nothing in
12960 case the guest isn't suspended.
12961 Since: 1.1
12963 Returns: nothing.
12965 Example:
12967 -> { "execute": "system_wakeup" }
12969 <- { "return": {} }
12970 inject-nmi (Command) Injects a Non-Maskable Interrupt into the default
12972 CPU (x86/s390) or all CPUs (ppc64). The command fails when the guest
12973 doesn't support injecting.
12974 Returns: If successful, nothing
12976 Since: 0.14.0
12978 Note: prior to 2.1, this command was only supported for x86 and s390
12980 VMs
12981 Example:
12983 -> { "execute": "inject-nmi" }
12985 <- { "return": {} }
12986 balloon (Command) Request the balloon driver to change its balloon
12988 size.
12989 Arguments:
12991 "value: int"
12993 the target size of the balloon in bytes
12994 Returns: Nothing on success If the balloon driver is enabled but not
12996 functional because the KVM kernel module cannot support it,
12997 KvmMissingCap If no balloon device is present, DeviceNotActive
12998 Notes: This command just issues a request to the guest. When it
13000 returns, the balloon size may not have changed. A guest can change the
13001 balloon size independent of this command.
13002 Since: 0.14.0
13004 Example:
13006 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
13008 <- { "return": {} }
13009 human-monitor-command (Command) Execute a command on the human monitor
13011 and return the output.
13012 Arguments:
13014 "command-line: string"
13016 the command to execute in the human monitor
13017 "cpu-index: int" (optional)
13019 The CPU to use for commands that require an implicit CPU
13020 Returns: the output of the command as a string
13022 Since: 0.14.0
13024 Notes: This command only exists as a stop-gap. Its use is highly
13026 discouraged. The semantics of this command are not guaranteed: this
13027 means that command names, arguments and responses can change or be
13028 removed at ANY time. Applications that rely on long term stability
13029 guarantees should NOT use this command.
13030 Known limitations:
13032 · This command is stateless, this means that commands that depend on
13034 state information (such as getfd) might not work
13035 · Commands that prompt the user for data don't currently work
13037 Example:
13039 -> { "execute": "human-monitor-command",
13041 "arguments": { "command-line": "info kvm" } }
13042 <- { "return": "kvm support: enabled\r\n" }
13043 ObjectPropertyInfo (Object)
13045 Members:
13047 "name: string"
13049 the name of the property
13050 "type: string"
13052 the type of the property. This will typically come in one of four
13053 forms:
13054 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or
13056 'double'. These types are mapped to the appropriate JSON type.
13057 2) A child type in the form 'child<subtype>' where subtype is a
13059 qdev device type name. Child properties create the composition
13060 tree.
13061 3) A link type in the form 'link<subtype>' where subtype is a qdev
13063 device type name. Link properties form the device model graph.
13064 "description: string" (optional)
13066 if specified, the description of the property.
13067 Since: 1.2
13069 qom-list (Command) This command will list any properties of a object
13071 given a path in the object model.
13072 Arguments:
13074 "path: string"
13076 the path within the object model. See "qom-get" for a description
13077 of this parameter.
13078 Returns: a list of "ObjectPropertyInfo" that describe the properties of
13080 the object.
13081 Since: 1.2
13083 qom-get (Command) This command will get a property from a object model
13085 path and return the value.
13086 Arguments:
13088 "path: string"
13090 The path within the object model. There are two forms of supported
13091 paths--absolute and partial paths.
13092 Absolute paths are derived from the root object and can follow
13094 child<> or link<> properties. Since they can follow link<>
13095 properties, they can be arbitrarily long. Absolute paths look like
13096 absolute filenames and are prefixed with a leading slash.
13097 Partial paths look like relative filenames. They do not begin with
13099 a prefix. The matching rules for partial paths are subtle but
13100 designed to make specifying objects easy. At each level of the
13101 composition tree, the partial path is matched as an absolute path.
13102 The first match is not returned. At least two matches are searched
13103 for. A successful result is only returned if only one match is
13104 found. If more than one match is found, a flag is return to
13105 indicate that the match was ambiguous.
13106 "property: string"
13108 The property name to read
13109 Returns: The property value. The type depends on the property type.
13111 child<> and link<> properties are returned as #str pathnames. All
13112 integer property types (u8, u16, etc) are returned as #int.
13113 Since: 1.2
13115 qom-set (Command) This command will set a property from a object model
13117 path.
13118 Arguments:
13120 "path: string"
13122 see "qom-get" for a description of this parameter
13123 "property: string"
13125 the property name to set
13126 "value: value"
13128 a value who's type is appropriate for the property type. See
13129 "qom-get" for a description of type mapping.
13130 Since: 1.2
13132 change (Command) This command is multiple commands multiplexed
13134 together.
13135 Arguments:
13137 "device: string"
13139 This is normally the name of a block device but it may also be
13140 'vnc'. when it's 'vnc', then sub command depends on "target"
13141 "target: string"
13143 If "device" is a block device, then this is the new filename. If
13144 "device" is 'vnc', then if the value 'password' selects the vnc
13145 change password command. Otherwise, this specifies a new server
13146 URI address to listen to for VNC connections.
13147 "arg: string" (optional)
13149 If "device" is a block device, then this is an optional format to
13150 open the device with. If "device" is 'vnc' and "target" is
13151 'password', this is the new VNC password to set. See change-vnc-
13152 password for additional notes.
13153 Returns: Nothing on success. If "device" is not a valid block device,
13155 DeviceNotFound
13156 Notes: This interface is deprecated, and it is strongly recommended
13158 that you avoid using it. For changing block devices, use blockdev-
13159 change-medium; for changing VNC parameters, use change-vnc-password.
13160 Since: 0.14.0
13162 Example:
13164 1. Change a removable medium
13166 -> { "execute": "change",
13168 "arguments": { "device": "ide1-cd0",
13169 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
13170 <- { "return": {} }
13171 2. Change VNC password
13173 -> { "execute": "change",
13175 "arguments": { "device": "vnc", "target": "password",
13176 "arg": "foobar1" } }
13177 <- { "return": {} }
13178 ObjectTypeInfo (Object)
13180 This structure describes a search result from "qom-list-types"
13182 Members:
13184 "name: string"
13186 the type name found in the search
13187 "abstract: boolean" (optional)
13189 the type is abstract and can't be directly instantiated. Omitted
13190 if false. (since 2.10)
13191 "parent: string" (optional)
13193 Name of parent type, if any (since 2.10)
13194 Since: 1.1
13196 qom-list-types (Command) This command will return a list of types
13198 given search parameters
13199 Arguments:
13201 "implements: string" (optional)
13203 if specified, only return types that implement this type name
13204 "abstract: boolean" (optional)
13206 if true, include abstract types in the results
13207 Returns: a list of "ObjectTypeInfo" or an empty list if no results are
13209 found
13210 Since: 1.1
13212 device-list-properties (Command) List properties associated with a
13214 device.
13215 Arguments:
13217 "typename: string"
13219 the type name of a device
13220 Returns: a list of ObjectPropertyInfo describing a devices properties
13222 Note: objects can create properties at runtime, for example to describe
13224 links between different devices and/or objects. These properties are
13225 not included in the output of this command.
13226 Since: 1.2
13228 qom-list-properties (Command) List properties associated with a QOM
13230 object.
13231 Arguments:
13233 "typename: string"
13235 the type name of an object
13236 Note: objects can create properties at runtime, for example to describe
13238 links between different devices and/or objects. These properties are
13239 not included in the output of this command.
13240 Returns: a list of ObjectPropertyInfo describing object properties
13242 Since: 2.12
13244 xen-set-global-dirty-log (Command) Enable or disable the global dirty
13246 log mode.
13247 Arguments:
13249 "enable: boolean"
13251 true to enable, false to disable.
13252 Returns: nothing
13254 Since: 1.3
13256 Example:
13258 -> { "execute": "xen-set-global-dirty-log",
13260 "arguments": { "enable": true } }
13261 <- { "return": {} }
13262 device_add (Command)
13264 Arguments:
13266 "driver: string"
13268 the name of the new device's driver
13269 "bus: string" (optional)
13271 the device's parent bus (device tree path)
13272 "id: string" (optional)
13274 the device's ID, must be unique
13275 Additional arguments depend on the type.
13277 Add a device.
13279 Notes:
13281 1. For detailed information about this command, please refer to the
13283 'docs/qdev-device-use.txt' file.
13284 2. It's possible to list device properties by running QEMU with the
13286 "-device DEVICE,help" command-line argument, where DEVICE is the
13287 device's name
13288 Example:
13290 -> { "execute": "device_add",
13292 "arguments": { "driver": "e1000", "id": "net1",
13293 "bus": "pci.0",
13294 "mac": "52:54:00:12:34:56" } }
13295 <- { "return": {} }
13296 TODO: This command effectively bypasses QAPI completely due to its
13298 "additional arguments" business. It shouldn't have been added to the
13299 schema in this form. It should be qapified properly, or replaced by a
13300 properly qapified command.
13301 Since: 0.13
13303 device_del (Command) Remove a device from a guest
13305 Arguments:
13307 "id: string"
13309 the device's ID or QOM path
13310 Returns: Nothing on success If "id" is not a valid device,
13312 DeviceNotFound
13313 Notes: When this command completes, the device may not be removed from
13315 the guest. Hot removal is an operation that requires guest
13316 cooperation. This command merely requests that the guest begin the hot
13317 removal process. Completion of the device removal process is signaled
13318 with a DEVICE_DELETED event. Guest reset will automatically complete
13319 removal for all devices.
13320 Since: 0.14.0
13322 Example:
13324 -> { "execute": "device_del",
13326 "arguments": { "id": "net1" } }
13327 <- { "return": {} }
13328 -> { "execute": "device_del",
13330 "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
13331 <- { "return": {} }
13332 DEVICE_DELETED (Event) Emitted whenever the device removal completion
13334 is acknowledged by the guest. At this point, it's safe to reuse the
13335 specified device ID. Device removal can be initiated by the guest or by
13336 HMP/QMP commands.
13337 Arguments:
13339 "device: string" (optional)
13341 device name
13342 "path: string"
13344 device path
13345 Since: 1.5
13347 Example:
13349 <- { "event": "DEVICE_DELETED",
13351 "data": { "device": "virtio-net-pci-0",
13352 "path": "/machine/peripheral/virtio-net-pci-0" },
13353 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
13354 DumpGuestMemoryFormat (Enum)
13356 An enumeration of guest-memory-dump's format.
13358 Values:
13360 "elf"
13362 elf format
13363 "kdump-zlib"
13365 kdump-compressed format with zlib-compressed
13366 "kdump-lzo"
13368 kdump-compressed format with lzo-compressed
13369 "kdump-snappy"
13371 kdump-compressed format with snappy-compressed
13372 "win-dmp"
13374 Windows full crashdump format, can be used instead of ELF
13375 converting (since 2.13)
13376 Since: 2.0
13378 dump-guest-memory (Command) Dump guest's memory to vmcore. It is a
13380 synchronous operation that can take very long depending on the amount
13381 of guest memory.
13382 Arguments:
13384 "paging: boolean"
13386 if true, do paging to get guest's memory mapping. This allows using
13387 gdb to process the core file.
13388 IMPORTANT: this option can make QEMU allocate several gigabytes of
13390 RAM. This can happen for a large guest, or a malicious guest
13391 pretending to be large.
13392 Also, paging=true has the following limitations:
13394 1. The guest may be in a catastrophic state or can have corrupted
13396 memory, which cannot be trusted
13397 2. The guest can be in real-mode even if paging is enabled. For
13399 example, the guest uses ACPI to sleep, and ACPI sleep state
13400 goes in real-mode
13401 3. Currently only supported on i386 and x86_64.
13403 "protocol: string"
13405 the filename or file descriptor of the vmcore. The supported
13406 protocols are:
13407 1. file: the protocol starts with "file:", and the following
13409 string is the file's path.
13410 2. fd: the protocol starts with "fd:", and the following string is
13412 the fd's name.
13413 "detach: boolean" (optional)
13415 if true, QMP will return immediately rather than waiting for the
13416 dump to finish. The user can track progress using "query-dump".
13417 (since 2.6).
13418 "begin: int" (optional)
13420 if specified, the starting physical address.
13421 "length: int" (optional)
13423 if specified, the memory size, in bytes. If you don't want to dump
13424 all guest's memory, please specify the start "begin" and "length"
13425 "format: DumpGuestMemoryFormat" (optional)
13427 if specified, the format of guest memory dump. But non-elf format
13428 is conflict with paging and filter, ie. "paging", "begin" and
13429 "length" is not allowed to be specified with non-elf "format" at
13430 the same time (since 2.0)
13431 Note: All boolean arguments default to false
13433 Returns: nothing on success
13435 Since: 1.2
13437 Example:
13439 -> { "execute": "dump-guest-memory",
13441 "arguments": { "protocol": "fd:dump" } }
13442 <- { "return": {} }
13443 DumpStatus (Enum)
13445 Describe the status of a long-running background guest memory dump.
13447 Values:
13449 "none"
13451 no dump-guest-memory has started yet.
13452 "active"
13454 there is one dump running in background.
13455 "completed"
13457 the last dump has finished successfully.
13458 "failed"
13460 the last dump has failed.
13461 Since: 2.6
13463 DumpQueryResult (Object)
13465 The result format for 'query-dump'.
13467 Members:
13469 "status: DumpStatus"
13471 enum of "DumpStatus", which shows current dump status
13472 "completed: int"
13474 bytes written in latest dump (uncompressed)
13475 "total: int"
13477 total bytes to be written in latest dump (uncompressed)
13478 Since: 2.6
13480 query-dump (Command) Query latest dump status.
13482 Returns: A "DumpStatus" object showing the dump status.
13484 Since: 2.6
13486 Example:
13488 -> { "execute": "query-dump" }
13490 <- { "return": { "status": "active", "completed": 1024000,
13491 "total": 2048000 } }
13492 DUMP_COMPLETED (Event) Emitted when background dump has completed
13494 Arguments:
13496 "result: DumpQueryResult"
13498 final dump status
13499 "error: string" (optional)
13501 human-readable error string that provides hint on why dump failed.
13502 Only presents on failure. The user should not try to interpret the
13503 error string.
13504 Since: 2.6
13506 Example:
13508 { "event": "DUMP_COMPLETED",
13510 "data": {"result": {"total": 1090650112, "status": "completed",
13511 "completed": 1090650112} } }
13512 DumpGuestMemoryCapability (Object)
13514 A list of the available formats for dump-guest-memory
13516 Members:
13518 "formats: array of DumpGuestMemoryFormat"
13520 Not documented
13521 Since: 2.0
13523 query-dump-guest-memory-capability (Command) Returns the available
13525 formats for dump-guest-memory
13526 Returns: A "DumpGuestMemoryCapability" object listing available formats
13528 for dump-guest-memory
13529 Since: 2.0
13531 Example:
13533 -> { "execute": "query-dump-guest-memory-capability" }
13535 <- { "return": { "formats":
13536 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
13537 dump-skeys (Command) Dump guest's storage keys
13539 Arguments:
13541 "filename: string"
13543 the path to the file to dump to
13544 This command is only supported on s390 architecture.
13546 Since: 2.5
13548 Example:
13550 -> { "execute": "dump-skeys",
13552 "arguments": { "filename": "/tmp/skeys" } }
13553 <- { "return": {} }
13554 object-add (Command) Create a QOM object.
13556 Arguments:
13558 "qom-type: string"
13560 the class name for the object to be created
13561 "id: string"
13563 the name of the new object
13564 "props: value" (optional)
13566 a dictionary of properties to be passed to the backend
13567 Returns: Nothing on success Error if "qom-type" is not a valid class
13569 name
13570 Since: 2.0
13572 Example:
13574 -> { "execute": "object-add",
13576 "arguments": { "qom-type": "rng-random", "id": "rng1",
13577 "props": { "filename": "/dev/hwrng" } } }
13578 <- { "return": {} }
13579 object-del (Command) Remove a QOM object.
13581 Arguments:
13583 "id: string"
13585 the name of the QOM object to remove
13586 Returns: Nothing on success Error if "id" is not a valid id for a QOM
13588 object
13589 Since: 2.0
13591 Example:
13593 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
13595 <- { "return": {} }
13596 getfd (Command) Receive a file descriptor via SCM rights and assign it
13598 a name
13599 Arguments:
13601 "fdname: string"
13603 file descriptor name
13604 Returns: Nothing on success
13606 Since: 0.14.0
13608 Notes: If "fdname" already exists, the file descriptor assigned to it
13610 will be closed and replaced by the received file descriptor.
13611 The 'closefd' command can be used to explicitly close the file
13613 descriptor when it is no longer needed.
13614 Example:
13616 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
13618 <- { "return": {} }
13619 closefd (Command) Close a file descriptor previously passed via SCM
13621 rights
13622 Arguments:
13624 "fdname: string"
13626 file descriptor name
13627 Returns: Nothing on success
13629 Since: 0.14.0
13631 Example:
13633 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
13635 <- { "return": {} }
13636 MachineInfo (Object)
13638 Information describing a machine.
13640 Members:
13642 "name: string"
13644 the name of the machine
13645 "alias: string" (optional)
13647 an alias for the machine name
13648 "is-default: boolean" (optional)
13650 whether the machine is default
13651 "cpu-max: int"
13653 maximum number of CPUs supported by the machine type (since 1.5.0)
13654 "hotpluggable-cpus: boolean"
13656 cpu hotplug via -device is supported (since 2.7.0)
13657 Since: 1.2.0
13659 query-machines (Command) Return a list of supported machines
13661 Returns: a list of MachineInfo
13663 Since: 1.2.0
13665 CpuDefinitionInfo (Object)
13667 Virtual CPU definition.
13669 Members:
13671 "name: string"
13673 the name of the CPU definition
13674 "migration-safe: boolean" (optional)
13676 whether a CPU definition can be safely used for migration in
13677 combination with a QEMU compatibility machine when migrating
13678 between different QMU versions and between hosts with different
13679 sets of (hardware or software) capabilities. If not provided,
13680 information is not available and callers should not assume the CPU
13681 definition to be migration-safe. (since 2.8)
13682 "static: boolean"
13684 whether a CPU definition is static and will not change depending on
13685 QEMU version, machine type, machine options and accelerator
13686 options. A static model is always migration-safe. (since 2.8)
13687 "unavailable-features: array of string" (optional)
13689 List of properties that prevent the CPU model from running in the
13690 current host. (since 2.8)
13691 "typename: string"
13693 Type name that can be used as argument to "device-list-properties",
13694 to introspect properties configurable using -cpu or -global.
13695 (since 2.9)
13696 "unavailable-features" is a list of QOM property names that represent
13698 CPU model attributes that prevent the CPU from running. If the QOM
13699 property is read-only, that means there's no known way to make the CPU
13700 model run in the current host. Implementations that choose not to
13701 provide specific information return the property name "type". If the
13702 property is read-write, it means that it MAY be possible to run the CPU
13703 model in the current host if that property is changed. Management
13704 software can use it as hints to suggest or choose an alternative for
13705 the user, or just to generate meaningful error messages explaining why
13706 the CPU model can't be used. If "unavailable-features" is an empty
13707 list, the CPU model is runnable using the current host and machine-
13708 type. If "unavailable-features" is not present, runnability
13709 information for the CPU is not available.
13710 Since: 1.2.0
13712 MemoryInfo (Object)
13714 Actual memory information in bytes.
13716 Members:
13718 "base-memory: int"
13720 size of "base" memory specified with command line option -m.
13721 "plugged-memory: int" (optional)
13723 size of memory that can be hot-unplugged. This field is omitted if
13724 target doesn't support memory hotplug (i.e. CONFIG_MEM_HOTPLUG not
13725 defined on build time).
13726 Since: 2.11.0
13728 query-memory-size-summary (Command) Return the amount of initially
13730 allocated and present hotpluggable (if enabled) memory in bytes.
13731 Example:
13733 -> { "execute": "query-memory-size-summary" }
13735 <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
13736 Since: 2.11.0
13738 query-cpu-definitions (Command) Return a list of supported virtual CPU
13740 definitions
13741 Returns: a list of CpuDefInfo
13743 Since: 1.2.0
13745 CpuModelInfo (Object)
13747 Virtual CPU model.
13749 A CPU model consists of the name of a CPU definition, to which delta
13751 changes are applied (e.g. features added/removed). Most magic values
13752 that an architecture might require should be hidden behind the name.
13753 However, if required, architectures can expose relevant properties.
13754 Members:
13756 "name: string"
13758 the name of the CPU definition the model is based on
13759 "props: value" (optional)
13761 a dictionary of QOM properties to be applied
13762 Since: 2.8.0
13764 CpuModelExpansionType (Enum)
13766 An enumeration of CPU model expansion types.
13768 Values:
13770 "static"
13772 Expand to a static CPU model, a combination of a static base model
13773 name and property delta changes. As the static base model will
13774 never change, the expanded CPU model will be the same, independent
13775 of independent of QEMU version, machine type, machine options, and
13776 accelerator options. Therefore, the resulting model can be used by
13777 tooling without having to specify a compatibility machine - e.g.
13778 when displaying the "host" model. static CPU models are migration-
13779 safe.
13780 "full"
13782 Expand all properties. The produced model is not guaranteed to be
13783 migration-safe, but allows tooling to get an insight and work with
13784 model details.
13785 Note: When a non-migration-safe CPU model is expanded in static mode,
13787 some features enabled by the CPU model may be omitted, because they
13788 can't be implemented by a static CPU model definition (e.g. cache info
13789 passthrough and PMU passthrough in x86). If you need an accurate
13790 representation of the features enabled by a non-migration-safe CPU
13791 model, use "full". If you need a static representation that will keep
13792 ABI compatibility even when changing QEMU version or machine-type, use
13793 "static" (but keep in mind that some features may be omitted).
13794 Since: 2.8.0
13796 CpuModelExpansionInfo (Object)
13798 The result of a cpu model expansion.
13800 Members:
13802 "model: CpuModelInfo"
13804 the expanded CpuModelInfo.
13805 Since: 2.8.0
13807 query-cpu-model-expansion (Command) Expands a given CPU model (or a
13809 combination of CPU model + additional options) to different
13810 granularities, allowing tooling to get an understanding what a specific
13811 CPU model looks like in QEMU under a certain configuration.
13812 This interface can be used to query the "host" CPU model.
13814 The data returned by this command may be affected by:
13816 · QEMU version: CPU models may look different depending on the QEMU
13818 version. (Except for CPU models reported as "static" in query-cpu-
13819 definitions.)
13820 · machine-type: CPU model may look different depending on the
13822 machine-type. (Except for CPU models reported as "static" in
13823 query-cpu-definitions.)
13824 · machine options (including accelerator): in some architectures, CPU
13826 models may look different depending on machine and accelerator
13827 options. (Except for CPU models reported as "static" in query-cpu-
13828 definitions.)
13829 · "-cpu" arguments and global properties: arguments to the -cpu
13831 option and global properties may affect expansion of CPU models.
13832 Using query-cpu-model-expansion while using these is not advised.
13833 Some architectures may not support all expansion types. s390x supports
13835 "full" and "static".
13836 Arguments:
13838 "type: CpuModelExpansionType"
13840 Not documented
13841 "model: CpuModelInfo"
13843 Not documented
13844 Returns: a CpuModelExpansionInfo. Returns an error if expanding CPU
13846 models is not supported, if the model cannot be expanded, if the model
13847 contains an unknown CPU definition name, unknown properties or
13848 properties with a wrong type. Also returns an error if an expansion
13849 type is not supported.
13850 Since: 2.8.0
13852 CpuModelCompareResult (Enum)
13854 An enumeration of CPU model comparison results. The result is usually
13856 calculated using e.g. CPU features or CPU generations.
13857 Values:
13859 "incompatible"
13861 If model A is incompatible to model B, model A is not guaranteed to
13862 run where model B runs and the other way around.
13863 "identical"
13865 If model A is identical to model B, model A is guaranteed to run
13866 where model B runs and the other way around.
13867 "superset"
13869 If model A is a superset of model B, model B is guaranteed to run
13870 where model A runs. There are no guarantees about the other way.
13871 "subset"
13873 If model A is a subset of model B, model A is guaranteed to run
13874 where model B runs. There are no guarantees about the other way.
13875 Since: 2.8.0
13877 CpuModelCompareInfo (Object)
13879 The result of a CPU model comparison.
13881 Members:
13883 "result: CpuModelCompareResult"
13885 The result of the compare operation.
13886 "responsible-properties: array of string"
13888 List of properties that led to the comparison result not being
13889 identical.
13890 "responsible-properties" is a list of QOM property names that led to
13892 both CPUs not being detected as identical. For identical models, this
13893 list is empty. If a QOM property is read-only, that means there's no
13894 known way to make the CPU models identical. If the special property
13895 name "type" is included, the models are by definition not identical and
13896 cannot be made identical.
13897 Since: 2.8.0
13899 query-cpu-model-comparison (Command) Compares two CPU models,
13901 returning how they compare in a specific configuration. The results
13902 indicates how both models compare regarding runnability. This result
13903 can be used by tooling to make decisions if a certain CPU model will
13904 run in a certain configuration or if a compatible CPU model has to be
13905 created by baselining.
13906 Usually, a CPU model is compared against the maximum possible CPU model
13908 of a certain configuration (e.g. the "host" model for KVM). If that CPU
13909 model is identical or a subset, it will run in that configuration.
13910 The result returned by this command may be affected by:
13912 · QEMU version: CPU models may look different depending on the QEMU
13914 version. (Except for CPU models reported as "static" in query-cpu-
13915 definitions.)
13916 · machine-type: CPU model may look different depending on the
13918 machine-type. (Except for CPU models reported as "static" in
13919 query-cpu-definitions.)
13920 · machine options (including accelerator): in some architectures, CPU
13922 models may look different depending on machine and accelerator
13923 options. (Except for CPU models reported as "static" in query-cpu-
13924 definitions.)
13925 · "-cpu" arguments and global properties: arguments to the -cpu
13927 option and global properties may affect expansion of CPU models.
13928 Using query-cpu-model-expansion while using these is not advised.
13929 Some architectures may not support comparing CPU models. s390x supports
13931 comparing CPU models.
13932 Arguments:
13934 "modela: CpuModelInfo"
13936 Not documented
13937 "modelb: CpuModelInfo"
13939 Not documented
13940 Returns: a CpuModelBaselineInfo. Returns an error if comparing CPU
13942 models is not supported, if a model cannot be used, if a model contains
13943 an unknown cpu definition name, unknown properties or properties with
13944 wrong types.
13945 Since: 2.8.0
13947 CpuModelBaselineInfo (Object)
13949 The result of a CPU model baseline.
13951 Members:
13953 "model: CpuModelInfo"
13955 the baselined CpuModelInfo.
13956 Since: 2.8.0
13958 query-cpu-model-baseline (Command) Baseline two CPU models, creating a
13960 compatible third model. The created model will always be a static,
13961 migration-safe CPU model (see "static" CPU model expansion for
13962 details).
13963 This interface can be used by tooling to create a compatible CPU model
13965 out two CPU models. The created CPU model will be identical to or a
13966 subset of both CPU models when comparing them. Therefore, the created
13967 CPU model is guaranteed to run where the given CPU models run.
13968 The result returned by this command may be affected by:
13970 · QEMU version: CPU models may look different depending on the QEMU
13972 version. (Except for CPU models reported as "static" in query-cpu-
13973 definitions.)
13974 · machine-type: CPU model may look different depending on the
13976 machine-type. (Except for CPU models reported as "static" in
13977 query-cpu-definitions.)
13978 · machine options (including accelerator): in some architectures, CPU
13980 models may look different depending on machine and accelerator
13981 options. (Except for CPU models reported as "static" in query-cpu-
13982 definitions.)
13983 · "-cpu" arguments and global properties: arguments to the -cpu
13985 option and global properties may affect expansion of CPU models.
13986 Using query-cpu-model-expansion while using these is not advised.
13987 Some architectures may not support baselining CPU models. s390x
13989 supports baselining CPU models.
13990 Arguments:
13992 "modela: CpuModelInfo"
13994 Not documented
13995 "modelb: CpuModelInfo"
13997 Not documented
13998 Returns: a CpuModelBaselineInfo. Returns an error if baselining CPU
14000 models is not supported, if a model cannot be used, if a model contains
14001 an unknown cpu definition name, unknown properties or properties with
14002 wrong types.
14003 Since: 2.8.0
14005 AddfdInfo (Object)
14007 Information about a file descriptor that was added to an fd set.
14009 Members:
14011 "fdset-id: int"
14013 The ID of the fd set that "fd" was added to.
14014 "fd: int"
14016 The file descriptor that was received via SCM rights and added to
14017 the fd set.
14018 Since: 1.2.0
14020 add-fd (Command) Add a file descriptor, that was passed via SCM
14022 rights, to an fd set.
14023 Arguments:
14025 "fdset-id: int" (optional)
14027 The ID of the fd set to add the file descriptor to.
14028 "opaque: string" (optional)
14030 A free-form string that can be used to describe the fd.
14031 Returns: "AddfdInfo" on success
14033 If file descriptor was not received, FdNotSupplied
14035 If "fdset-id" is a negative value, InvalidParameterValue
14037 Notes: The list of fd sets is shared by all monitor connections.
14039 If "fdset-id" is not specified, a new fd set will be created.
14041 Since: 1.2.0
14043 Example:
14045 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
14047 <- { "return": { "fdset-id": 1, "fd": 3 } }
14048 remove-fd (Command) Remove a file descriptor from an fd set.
14050 Arguments:
14052 "fdset-id: int"
14054 The ID of the fd set that the file descriptor belongs to.
14055 "fd: int" (optional)
14057 The file descriptor that is to be removed.
14058 Returns: Nothing on success If "fdset-id" or "fd" is not found,
14060 FdNotFound
14061 Since: 1.2.0
14063 Notes: The list of fd sets is shared by all monitor connections.
14065 If "fd" is not specified, all file descriptors in "fdset-id" will be
14067 removed.
14068 Example:
14070 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
14072 <- { "return": {} }
14073 FdsetFdInfo (Object)
14075 Information about a file descriptor that belongs to an fd set.
14077 Members:
14079 "fd: int"
14081 The file descriptor value.
14082 "opaque: string" (optional)
14084 A free-form string that can be used to describe the fd.
14085 Since: 1.2.0
14087 FdsetInfo (Object)
14089 Information about an fd set.
14091 Members:
14093 "fdset-id: int"
14095 The ID of the fd set.
14096 "fds: array of FdsetFdInfo"
14098 A list of file descriptors that belong to this fd set.
14099 Since: 1.2.0
14101 query-fdsets (Command) Return information describing all fd sets.
14103 Returns: A list of "FdsetInfo"
14105 Since: 1.2.0
14107 Note: The list of fd sets is shared by all monitor connections.
14109 Example:
14111 -> { "execute": "query-fdsets" }
14113 <- { "return": [
14114 {
14115 "fds": [
14116 {
14117 "fd": 30,
14118 "opaque": "rdonly:/path/to/file"
14119 },
14120 {
14121 "fd": 24,
14122 "opaque": "rdwr:/path/to/file"
14123 }
14124 ],
14125 "fdset-id": 1
14126 },
14127 {
14128 "fds": [
14129 {
14130 "fd": 28
14131 },
14132 {
14133 "fd": 29
14134 }
14135 ],
14136 "fdset-id": 0
14137 }
14138 ]
14139 }
14140 TargetInfo (Object)
14142 Information describing the QEMU target.
14144 Members:
14146 "arch: SysEmuTarget"
14148 the target architecture
14149 Since: 1.2.0
14151 query-target (Command) Return information about the target for this
14153 QEMU
14154 Returns: TargetInfo
14156 Since: 1.2.0
14158 AcpiTableOptions (Object)
14160 Specify an ACPI table on the command line to load.
14162 At most one of "file" and "data" can be specified. The list of files
14164 specified by any one of them is loaded and concatenated in order. If
14165 both are omitted, "data" is implied.
14166 Other fields / optargs can be used to override fields of the generic
14168 ACPI table header; refer to the ACPI specification 5.0, section 5.2.6
14169 System Description Table Header. If a header field is not overridden,
14170 then the corresponding value from the concatenated blob is used (in
14171 case of "file"), or it is filled in with a hard-coded value (in case of
14172 "data").
14173 String fields are copied into the matching ACPI member from lowest
14175 address upwards, and silently truncated / NUL-padded to length.
14176 Members:
14178 "sig: string" (optional)
14180 table signature / identifier (4 bytes)
14181 "rev: int" (optional)
14183 table revision number (dependent on signature, 1 byte)
14184 "oem_id: string" (optional)
14186 OEM identifier (6 bytes)
14187 "oem_table_id: string" (optional)
14189 OEM table identifier (8 bytes)
14190 "oem_rev: int" (optional)
14192 OEM-supplied revision number (4 bytes)
14193 "asl_compiler_id: string" (optional)
14195 identifier of the utility that created the table (4 bytes)
14196 "asl_compiler_rev: int" (optional)
14198 revision number of the utility that created the table (4 bytes)
14199 "file: string" (optional)
14201 colon (:) separated list of pathnames to load and concatenate as
14202 table data. The resultant binary blob is expected to have an ACPI
14203 table header. At least one file is required. This field excludes
14204 "data".
14205 "data: string" (optional)
14207 colon (:) separated list of pathnames to load and concatenate as
14208 table data. The resultant binary blob must not have an ACPI table
14209 header. At least one file is required. This field excludes "file".
14210 Since: 1.5
14212 CommandLineParameterType (Enum)
14214 Possible types for an option parameter.
14216 Values:
14218 "string"
14220 accepts a character string
14221 "boolean"
14223 accepts "on" or "off"
14224 "number"
14226 accepts a number
14227 "size"
14229 accepts a number followed by an optional suffix (K)ilo, (M)ega,
14230 (G)iga, (T)era
14231 Since: 1.5
14233 CommandLineParameterInfo (Object)
14235 Details about a single parameter of a command line option.
14237 Members:
14239 "name: string"
14241 parameter name
14242 "type: CommandLineParameterType"
14244 parameter "CommandLineParameterType"
14245 "help: string" (optional)
14247 human readable text string, not suitable for parsing.
14248 "default: string" (optional)
14250 default value string (since 2.1)
14251 Since: 1.5
14253 CommandLineOptionInfo (Object)
14255 Details about a command line option, including its list of parameter
14257 details
14258 Members:
14260 "option: string"
14262 option name
14263 "parameters: array of CommandLineParameterInfo"
14265 an array of "CommandLineParameterInfo"
14266 Since: 1.5
14268 query-command-line-options (Command) Query command line option schema.
14270 Arguments:
14272 "option: string" (optional)
14274 option name
14275 Returns: list of "CommandLineOptionInfo" for all options (or for the
14277 given "option"). Returns an error if the given "option" doesn't exist.
14278 Since: 1.5
14280 Example:
14282 -> { "execute": "query-command-line-options",
14284 "arguments": { "option": "option-rom" } }
14285 <- { "return": [
14286 {
14287 "parameters": [
14288 {
14289 "name": "romfile",
14290 "type": "string"
14291 },
14292 {
14293 "name": "bootindex",
14294 "type": "number"
14295 }
14296 ],
14297 "option": "option-rom"
14298 }
14299 ]
14300 }
14301 X86CPURegister32 (Enum)
14303 A X86 32-bit register
14305 Values:
14307 "EAX"
14309 Not documented
14310 "EBX"
14312 Not documented
14313 "ECX"
14315 Not documented
14316 "EDX"
14318 Not documented
14319 "ESP"
14321 Not documented
14322 "EBP"
14324 Not documented
14325 "ESI"
14327 Not documented
14328 "EDI"
14330 Not documented
14331 Since: 1.5
14333 X86CPUFeatureWordInfo (Object)
14335 Information about a X86 CPU feature word
14337 Members:
14339 "cpuid-input-eax: int"
14341 Input EAX value for CPUID instruction for that feature word
14342 "cpuid-input-ecx: int" (optional)
14344 Input ECX value for CPUID instruction for that feature word
14345 "cpuid-register: X86CPURegister32"
14347 Output register containing the feature bits
14348 "features: int"
14350 value of output register, containing the feature bits
14351 Since: 1.5
14353 DummyForceArrays (Object)
14355 Not used by QMP; hack to let us use X86CPUFeatureWordInfoList
14357 internally
14358 Members:
14360 "unused: array of X86CPUFeatureWordInfo"
14362 Not documented
14363 Since: 2.5
14365 NumaOptionsType (Enum)
14367 Values:
14369 "node"
14371 NUMA nodes configuration
14372 "dist"
14374 NUMA distance configuration (since 2.10)
14375 "cpu"
14377 property based CPU(s) to node mapping (Since: 2.10)
14378 Since: 2.1
14380 NumaOptions (Object)
14382 A discriminated record of NUMA options. (for OptsVisitor)
14384 Members:
14386 "type: NumaOptionsType"
14388 Not documented
14389 The members of "NumaNodeOptions" when "type" is "node"
14391 The members of "NumaDistOptions" when "type" is "dist"
14392 The members of "NumaCpuOptions" when "type" is "cpu"
14393 Since: 2.1
14395 NumaNodeOptions (Object)
14397 Create a guest NUMA node. (for OptsVisitor)
14399 Members:
14401 "nodeid: int" (optional)
14403 NUMA node ID (increase by 1 from 0 if omitted)
14404 "cpus: array of int" (optional)
14406 VCPUs belonging to this node (assign VCPUS round-robin if omitted)
14407 "mem: int" (optional)
14409 memory size of this node; mutually exclusive with "memdev".
14410 Equally divide total memory among nodes if both "mem" and "memdev"
14411 are omitted.
14412 "memdev: string" (optional)
14414 memory backend object. If specified for one node, it must be
14415 specified for all nodes.
14416 Since: 2.1
14418 NumaDistOptions (Object)
14420 Set the distance between 2 NUMA nodes.
14422 Members:
14424 "src: int"
14426 source NUMA node.
14427 "dst: int"
14429 destination NUMA node.
14430 "val: int"
14432 NUMA distance from source node to destination node. When a node is
14433 unreachable from another node, set the distance between them to
14434 255.
14435 Since: 2.10
14437 NumaCpuOptions (Object)
14439 Option "-numa cpu" overrides default cpu to node mapping. It accepts
14441 the same set of cpu properties as returned by
14442 query-hotpluggable-cpus[].props, where node-id could be used to
14443 override default node mapping.
14444 Members:
14446 The members of "CpuInstanceProperties"
14448 Since: 2.10
14450 HostMemPolicy (Enum)
14452 Host memory policy types
14454 Values:
14456 "default"
14458 restore default policy, remove any nondefault policy
14459 "preferred"
14461 set the preferred host nodes for allocation
14462 "bind"
14464 a strict policy that restricts memory allocation to the host nodes
14465 specified
14466 "interleave"
14468 memory allocations are interleaved across the set of host nodes
14469 specified
14470 Since: 2.1
14472 Memdev (Object)
14474 Information about memory backend
14476 Members:
14478 "id: string" (optional)
14480 backend's ID if backend has 'id' property (since 2.9)
14481 "size: int"
14483 memory backend size
14484 "merge: boolean"
14486 enables or disables memory merge support
14487 "dump: boolean"
14489 includes memory backend's memory in a core dump or not
14490 "prealloc: boolean"
14492 enables or disables memory preallocation
14493 "host-nodes: array of int"
14495 host nodes for its memory policy
14496 "policy: HostMemPolicy"
14498 memory policy of memory backend
14499 Since: 2.1
14501 query-memdev (Command) Returns information for all memory backends.
14503 Returns: a list of "Memdev".
14505 Since: 2.1
14507 Example:
14509 -> { "execute": "query-memdev" }
14511 <- { "return": [
14512 {
14513 "id": "mem1",
14514 "size": 536870912,
14515 "merge": false,
14516 "dump": true,
14517 "prealloc": false,
14518 "host-nodes": [0, 1],
14519 "policy": "bind"
14520 },
14521 {
14522 "size": 536870912,
14523 "merge": false,
14524 "dump": true,
14525 "prealloc": true,
14526 "host-nodes": [2, 3],
14527 "policy": "preferred"
14528 }
14529 ]
14530 }
14531 PCDIMMDeviceInfo (Object)
14533 PCDIMMDevice state information
14535 Members:
14537 "id: string" (optional)
14539 device's ID
14540 "addr: int"
14542 physical address, where device is mapped
14543 "size: int"
14545 size of memory that the device provides
14546 "slot: int"
14548 slot number at which device is plugged in
14549 "node: int"
14551 NUMA node number where device is plugged in
14552 "memdev: string"
14554 memory backend linked with device
14555 "hotplugged: boolean"
14557 true if device was hotplugged
14558 "hotpluggable: boolean"
14560 true if device if could be added/removed while machine is running
14561 Since: 2.1
14563 MemoryDeviceInfo (Object)
14565 Union containing information about a memory device
14567 Members:
14569 "type"
14571 One of "dimm", "nvdimm"
14572 "data: PCDIMMDeviceInfo" when "type" is "dimm"
14574 "data: PCDIMMDeviceInfo" when "type" is "nvdimm"
14575 Since: 2.1
14577 query-memory-devices (Command) Lists available memory devices and
14579 their state
14580 Since: 2.1
14582 Example:
14584 -> { "execute": "query-memory-devices" }
14586 <- { "return": [ { "data":
14587 { "addr": 5368709120,
14588 "hotpluggable": true,
14589 "hotplugged": true,
14590 "id": "d1",
14591 "memdev": "/objects/memX",
14592 "node": 0,
14593 "size": 1073741824,
14594 "slot": 0},
14595 "type": "dimm"
14596 } ] }
14597 MEM_UNPLUG_ERROR (Event) Emitted when memory hot unplug error occurs.
14599 Arguments:
14601 "device: string"
14603 device name
14604 "msg: string"
14606 Informative message
14607 Since: 2.4
14609 Example:
14611 <- { "event": "MEM_UNPLUG_ERROR"
14613 "data": { "device": "dimm1",
14614 "msg": "acpi: device unplug for unsupported device"
14615 },
14616 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
14617 ACPISlotType (Enum)
14619 Values:
14621 "DIMM"
14623 memory slot
14624 "CPU"
14626 logical CPU slot (since 2.7)
14627 ACPIOSTInfo (Object)
14629 OSPM Status Indication for a device For description of possible values
14631 of "source" and "status" fields see "_OST (OSPM Status Indication)"
14632 chapter of ACPI5.0 spec.
14633 Members:
14635 "device: string" (optional)
14637 device ID associated with slot
14638 "slot: string"
14640 slot ID, unique per slot of a given "slot-type"
14641 "slot-type: ACPISlotType"
14643 type of the slot
14644 "source: int"
14646 an integer containing the source event
14647 "status: int"
14649 an integer containing the status code
14650 Since: 2.1
14652 query-acpi-ospm-status (Command) Return a list of ACPIOSTInfo for
14654 devices that support status reporting via ACPI _OST method.
14655 Since: 2.1
14657 Example:
14659 -> { "execute": "query-acpi-ospm-status" }
14661 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
14662 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
14663 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
14664 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
14665 ]}
14666 ACPI_DEVICE_OST (Event) Emitted when guest executes ACPI _OST method.
14668 Arguments:
14670 "info: ACPIOSTInfo"
14672 OSPM Status Indication
14673 Since: 2.1
14675 Example:
14677 <- { "event": "ACPI_DEVICE_OST",
14679 "data": { "device": "d1", "slot": "0",
14680 "slot-type": "DIMM", "source": 1, "status": 0 } }
14681 rtc-reset-reinjection (Command) This command will reset the RTC
14683 interrupt reinjection backlog. Can be used if another mechanism to
14684 synchronize guest time is in effect, for example QEMU guest agent's
14685 guest-set-time command.
14686 Since: 2.1
14688 Example:
14690 -> { "execute": "rtc-reset-reinjection" }
14692 <- { "return": {} }
14693 RTC_CHANGE (Event) Emitted when the guest changes the RTC time.
14695 Arguments:
14697 "offset: int"
14699 offset between base RTC clock (as specified by -rtc base), and new
14700 RTC clock value
14701 Note: This event is rate-limited.
14703 Since: 0.13.0
14705 Example:
14707 <- { "event": "RTC_CHANGE",
14709 "data": { "offset": 78 },
14710 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
14711 ReplayMode (Enum)
14713 Mode of the replay subsystem.
14715 Values:
14717 "none"
14719 normal execution mode. Replay or record are not enabled.
14720 "record"
14722 record mode. All non-deterministic data is written into the replay
14723 log.
14724 "play"
14726 replay mode. Non-deterministic data required for system execution
14727 is read from the log.
14728 Since: 2.5
14730 xen-load-devices-state (Command) Load the state of all devices from
14732 file. The RAM and the block devices of the VM are not loaded by this
14733 command.
14734 Arguments:
14736 "filename: string"
14738 the file to load the state of the devices from as binary data. See
14739 xen-save-devices-state.txt for a description of the binary format.
14740 Since: 2.7
14742 Example:
14744 -> { "execute": "xen-load-devices-state",
14746 "arguments": { "filename": "/tmp/resume" } }
14747 <- { "return": {} }
14748 GICCapability (Object)
14750 The struct describes capability for a specific GIC (Generic Interrupt
14752 Controller) version. These bits are not only decided by QEMU/KVM
14753 software version, but also decided by the hardware that the program is
14754 running upon.
14755 Members:
14757 "version: int"
14759 version of GIC to be described. Currently, only 2 and 3 are
14760 supported.
14761 "emulated: boolean"
14763 whether current QEMU/hardware supports emulated GIC device in user
14764 space.
14765 "kernel: boolean"
14767 whether current QEMU/hardware supports hardware accelerated GIC
14768 device in kernel.
14769 Since: 2.6
14771 query-gic-capabilities (Command) This command is ARM-only. It will
14773 return a list of GICCapability objects that describe its capability
14774 bits.
14775 Returns: a list of GICCapability objects.
14777 Since: 2.6
14779 Example:
14781 -> { "execute": "query-gic-capabilities" }
14783 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
14784 { "version": 3, "emulated": false, "kernel": true } ] }
14785 CpuInstanceProperties (Object)
14787 List of properties to be used for hotplugging a CPU instance, it should
14789 be passed by management with device_add command when a CPU is being
14790 hotplugged.
14791 Members:
14793 "node-id: int" (optional)
14795 NUMA node ID the CPU belongs to
14796 "socket-id: int" (optional)
14798 socket number within node/board the CPU belongs to
14799 "core-id: int" (optional)
14801 core number within socket the CPU belongs to
14802 "thread-id: int" (optional)
14804 thread number within core the CPU belongs to
14805 Note: currently there are 4 properties that could be present but
14807 management should be prepared to pass through other properties with
14808 device_add command to allow for future interface extension. This also
14809 requires the filed names to be kept in sync with the properties passed
14810 to -device/device_add.
14811 Since: 2.7
14813 HotpluggableCPU (Object)
14815 Members:
14817 "type: string"
14819 CPU object type for usage with device_add command
14820 "props: CpuInstanceProperties"
14822 list of properties to be used for hotplugging CPU
14823 "vcpus-count: int"
14825 number of logical VCPU threads "HotpluggableCPU" provides
14826 "qom-path: string" (optional)
14828 link to existing CPU object if CPU is present or omitted if CPU is
14829 not present.
14830 Since: 2.7
14832 query-hotpluggable-cpus (Command)
14834 Returns: a list of HotpluggableCPU objects.
14836 Since: 2.7
14838 Example:
14840 For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
14842 -> { "execute": "query-hotpluggable-cpus" }
14844 <- {"return": [
14845 { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
14846 "vcpus-count": 1 },
14847 { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
14848 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
14849 ]}'
14850 For pc machine type started with -smp 1,maxcpus=2:
14852 -> { "execute": "query-hotpluggable-cpus" }
14854 <- {"return": [
14855 {
14856 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
14857 "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
14858 },
14859 {
14860 "qom-path": "/machine/unattached/device[0]",
14861 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
14862 "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
14863 }
14864 ]}
14865 For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
14867 (Since: 2.11):
14868 -> { "execute": "query-hotpluggable-cpus" }
14870 <- {"return": [
14871 {
14872 "type": "qemu-s390x-cpu", "vcpus-count": 1,
14873 "props": { "core-id": 1 }
14874 },
14875 {
14876 "qom-path": "/machine/unattached/device[0]",
14877 "type": "qemu-s390x-cpu", "vcpus-count": 1,
14878 "props": { "core-id": 0 }
14879 }
14880 ]}
14881 GuidInfo (Object)
14883 GUID information.
14885 Members:
14887 "guid: string"
14889 the globally unique identifier
14890 Since: 2.9
14892 query-vm-generation-id (Command) Show Virtual Machine Generation ID
14894 Since: 2.9
14896 SevState (Enum)
14898 An enumeration of SEV state information used during "query-sev".
14900 Values:
14902 "uninit"
14904 The guest is uninitialized.
14905 "launch-update"
14907 The guest is currently being launched; plaintext data and register
14908 state is being imported.
14909 "launch-secret"
14911 The guest is currently being launched; ciphertext data is being
14912 imported.
14913 "running"
14915 The guest is fully launched or migrated in.
14916 "send-update"
14918 The guest is currently being migrated out to another machine.
14919 "receive-update"
14921 The guest is currently being migrated from another machine.
14922 Since: 2.12
14924 SevInfo (Object)
14926 Information about Secure Encrypted Virtualization (SEV) support
14928 Members:
14930 "enabled: boolean"
14932 true if SEV is active
14933 "api-major: int"
14935 SEV API major version
14936 "api-minor: int"
14938 SEV API minor version
14939 "build-id: int"
14941 SEV FW build id
14942 "policy: int"
14944 SEV policy value
14945 "state: SevState"
14947 SEV guest state
14948 "handle: int"
14950 SEV firmware handle
14951 Since: 2.12
14953 query-sev (Command) Returns information about SEV
14955 Returns: "SevInfo"
14957 Since: 2.12
14959 Example:
14961 -> { "execute": "query-sev" }
14963 <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
14964 "build-id" : 0, "policy" : 0, "state" : "running",
14965 "handle" : 1 } }
14966 SevLaunchMeasureInfo (Object)
14968 SEV Guest Launch measurement information
14970 Members:
14972 "data: string"
14974 the measurement value encoded in base64
14975 Since: 2.12
14977 query-sev-launch-measure (Command) Query the SEV guest launch
14979 information.
14980 Returns: The "SevLaunchMeasureInfo" for the guest
14982 Since: 2.12
14984 Example:
14986 -> { "execute": "query-sev-launch-measure" }
14988 <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
14989 SevCapability (Object)
14991 The struct describes capability for a Secure Encrypted Virtualization
14993 feature.
14994 Members:
14996 "pdh: string"
14998 Platform Diffie-Hellman key (base64 encoded)
14999 "cert-chain: string"
15001 PDH certificate chain (base64 encoded)
15002 "cbitpos: int"
15004 C-bit location in page table entry
15005 "reduced-phys-bits: int"
15007 Number of physical Address bit reduction when SEV is enabled
15008 Since: 2.12
15010 query-sev-capabilities (Command) This command is used to get the SEV
15012 capabilities, and is supported on AMD X86 platforms only.
15013 Returns: SevCapability objects.
15015 Since: 2.12
15017 Example:
15019 -> { "execute": "query-sev-capabilities" }
15021 <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
15022 "cbitpos": 47, "reduced-phys-bits": 5}}
15023 CommandDropReason (Enum)
15025 Reasons that caused one command to be dropped.
15027 Values:
15029 "queue-full"
15031 the command queue is full. This can only occur when the client
15032 sends a new non-oob command before the response to the previous
15033 non-oob command has been received.
15034 Since: 2.12
15036 COMMAND_DROPPED (Event) Emitted when a command is dropped due to some
15038 reason. Commands can only be dropped when the oob capability is
15039 enabled.
15040 Arguments:
15042 "id: value"
15044 The dropped command's "id" field. FIXME Broken by design. Events
15045 are broadcast to all monitors. If another monitor's client has a
15046 command with the same ID in flight, the event will incorrectly
15047 claim that command was dropped.
15048 "reason: CommandDropReason"
15050 The reason why the command is dropped.
15051 Since: 2.12
15053 Example:
15055 { "event": "COMMAND_DROPPED",
15057 "data": {"result": {"id": "libvirt-102",
15058 "reason": "queue-full" } } }
15059 set-numa-node (Command) Runtime equivalent of '-numa' CLI option,
15061 available at preconfigure stage to configure numa mapping before
15062 initializing machine.
15063 Since 3.0
15065 Arguments: the members of "NumaOptions"
15067 2019-05-14 QEMU-QMP-REF.7(7)