1QEMU-QMP-REF(7) QEMU QEMU-QMP-REF(7)
2
6 qemu-qmp-ref - QEMU QMP Reference Manual
7
9 This document describes all commands currently supported by QMP.
10 Most of the time their usage is exactly the same as in the user Moni‐
12 tor, this means that any other document which also describe commands
13 (the manpage, QEMU's manual, etc) can and should be consulted.
14 QMP has two types of commands: regular and query commands. Regular com‐
16 mands usually change the Virtual Machine's state someway, while query
17 commands just return information. The sections below are divided ac‐
18 cordingly.
19 It's important to observe that all communication examples are formatted
21 in a reader-friendly way, so that they're easier to understand. How‐
22 ever, in real protocol usage, they're emitted as a single line.
23 Also, the following notation is used to denote data flow:
25 Example:
27 -> data issued by the Client
29 <- Server data response
30 Please, refer to the QMP specification (docs/interop/qmp-spec.txt) for
32 detailed information on the Server command and response formats.
33
35 The current QMP command set (described in this file) may be useful for
36 a number of use cases, however it's limited and several commands have
37 bad defined semantics, specially with regard to command completion.
38 These problems are going to be solved incrementally in the next QEMU
40 releases and we're going to establish a deprecation policy for badly
41 defined commands.
42 If you're planning to adopt QMP, please observe the following:
44 1. The deprecation policy will take effect and be documented soon,
46 please check the documentation of each used command as soon as a
47 new release of QEMU is available
48 2. DO NOT rely on anything which is not explicit documented
50 3. Errors, in special, are not documented. Applications should NOT
52 check for specific errors classes or data (it's strongly recom‐
53 mended to only check for the "error" key)
54
56 QapiErrorClass (Enum)
57 QEMU error classes
58 Values
60 GenericError
61 this is used for errors that don't require a specific error
62 class. This should be the default case for most errors
63 CommandNotFound
65 the requested command has not been found
66 DeviceNotActive
68 a device has failed to be become active
69 DeviceNotFound
71 the requested device has not been found
72 KVMMissingCap
74 the requested operation can't be fulfilled because a required
75 KVM capability is missing
76 Since
78 1.2
79
81 IoOperationType (Enum)
82 An enumeration of the I/O operation types
83 Values
85 read read operation
86 write write operation
88 Since
90 2.1
91 OnOffAuto (Enum)
93 An enumeration of three options: on, off, and auto
94 Values
96 auto QEMU selects the value between on and off
97 on Enabled
99 off Disabled
101 Since
103 2.2
104 OnOffSplit (Enum)
106 An enumeration of three values: on, off, and split
107 Values
109 on Enabled
110 off Disabled
112 split Mixed
114 Since
116 2.6
117 String (Object)
119 A fat type wrapping 'str', to be embedded in lists.
120 Members
122 str: string
123 Not documented
124 Since
126 1.2
127 StrOrNull (Alternate)
129 This is a string value or the explicit lack of a string (null pointer
130 in C). Intended for cases when 'optional absent' already has a differ‐
131 ent meaning.
132 Members
134 s: string
135 the string value
136 n: null
138 no string value
139 Since
141 2.10
142 OffAutoPCIBAR (Enum)
144 An enumeration of options for specifying a PCI BAR
145 Values
147 off The specified feature is disabled
148 auto The PCI BAR for the feature is automatically selected
150 bar0 PCI BAR0 is used for the feature
152 bar1 PCI BAR1 is used for the feature
154 bar2 PCI BAR2 is used for the feature
156 bar3 PCI BAR3 is used for the feature
158 bar4 PCI BAR4 is used for the feature
160 bar5 PCI BAR5 is used for the feature
162 Since
164 2.12
165 PCIELinkSpeed (Enum)
167 An enumeration of PCIe link speeds in units of GT/s
168 Values
170 2_5 2.5GT/s
171 5 5.0GT/s
173 8 8.0GT/s
175 16 16.0GT/s
177 Since
179 4.0
180 PCIELinkWidth (Enum)
182 An enumeration of PCIe link width
183 Values
185 1 x1
186 2 x2
188 4 x4
190 8 x8
192 12 x12
194 16 x16
196 32 x32
198 Since
200 4.0
201
203 NetworkAddressFamily (Enum)
204 The network address family
205 Values
207 ipv4 IPV4 family
208 ipv6 IPV6 family
210 unix unix socket
212 vsock vsock family (since 2.8)
214 unknown
216 otherwise
217 Since
219 2.1
220 InetSocketAddressBase (Object)
222 Members
223 host: string
224 host part of the address
225 port: string
227 port part of the address
228 InetSocketAddress (Object)
230 Captures a socket address or address range in the Internet namespace.
231 Members
233 numeric: boolean (optional)
234 true if the host/port are guaranteed to be numeric, false if
235 name resolution should be attempted. Defaults to false. (Since
236 2.9)
237 to: int (optional)
239 If present, this is range of possible addresses, with port be‐
240 tween port and to.
241 ipv4: boolean (optional)
243 whether to accept IPv4 addresses, default try both IPv4 and IPv6
244 ipv6: boolean (optional)
246 whether to accept IPv6 addresses, default try both IPv4 and IPv6
247 keep-alive: boolean (optional)
249 enable keep-alive when connecting to this socket. Not supported
250 for passive sockets. (Since 4.2)
251 The members of InetSocketAddressBase
253 Since
255 1.3
256 UnixSocketAddress (Object)
258 Captures a socket address in the local ("Unix socket") namespace.
259 Members
261 path: string
262 filesystem path to use
263 abstract: boolean (optional) (If: defined(CONFIG_LINUX))
265 if true, this is a Linux abstract socket address. path will be
266 prefixed by a null byte, and optionally padded with null bytes.
267 Defaults to false. (Since 5.1)
268 tight: boolean (optional) (If: defined(CONFIG_LINUX))
270 if false, pad an abstract socket address with enough null bytes
271 to make it fill struct sockaddr_un member sun_path. Defaults to
272 true. (Since 5.1)
273 Since
275 1.3
276 VsockSocketAddress (Object)
278 Captures a socket address in the vsock namespace.
279 Members
281 cid: string
282 unique host identifier
283 port: string
285 port
286 Note
288 string types are used to allow for possible future hostname or service
289 resolution support.
290 Since
292 2.8
293 SocketAddressLegacy (Object)
295 Captures the address of a socket, which could also be a named file de‐
296 scriptor
297 Members
299 type One of inet, unix, vsock, fd
300 data: InetSocketAddress when type is "inet"
302 data: UnixSocketAddress when type is "unix"
304 data: VsockSocketAddress when type is "vsock"
306 data: String when type is "fd"
308 Note
310 This type is deprecated in favor of SocketAddress. The difference be‐
311 tween SocketAddressLegacy and SocketAddress is that the latter is a
312 flat union rather than a simple union. Flat is nicer because it avoids
313 nesting on the wire, i.e. that form has fewer {}.
314 Since
316 1.3
317 SocketAddressType (Enum)
319 Available SocketAddress types
320 Values
322 inet Internet address
323 unix Unix domain socket
325 vsock VMCI address
327 fd decimal is for file descriptor number, otherwise a file descrip‐
329 tor name. Named file descriptors are permitted in monitor com‐
330 mands, in combination with the 'getfd' command. Decimal file de‐
331 scriptors are permitted at startup or other contexts where no
332 monitor context is active.
333 Since
335 2.9
336 SocketAddress (Object)
338 Captures the address of a socket, which could also be a named file de‐
339 scriptor
340 Members
342 type: SocketAddressType
343 Transport type
344 The members of InetSocketAddress when type is "inet"
346 The members of UnixSocketAddress when type is "unix"
348 The members of VsockSocketAddress when type is "vsock"
350 The members of String when type is "fd"
352 Since
354 2.9
355
357 RunState (Enum)
358 An enumeration of VM run states.
359 Values
361 debug QEMU is running on a debugger
362 finish-migrate
364 guest is paused to finish the migration process
365 inmigrate
367 guest is paused waiting for an incoming migration. Note that
368 this state does not tell whether the machine will start at the
369 end of the migration. This depends on the command-line -S op‐
370 tion and any invocation of 'stop' or 'cont' that has happened
371 since QEMU was started.
372 internal-error
374 An internal error that prevents further guest execution has oc‐
375 curred
376 io-error
378 the last IOP has failed and the device is configured to pause on
379 I/O errors
380 paused guest has been paused via the 'stop' command
382 postmigrate
384 guest is paused following a successful 'migrate'
385 prelaunch
387 QEMU was started with -S and guest has not started
388 restore-vm
390 guest is paused to restore VM state
391 running
393 guest is actively running
394 save-vm
396 guest is paused to save the VM state
397 shutdown
399 guest is shut down (and -no-shutdown is in use)
400 suspended
402 guest is suspended (ACPI S3)
403 watchdog
405 the watchdog action is configured to pause and has been trig‐
406 gered
407 guest-panicked
409 guest has been panicked as a result of guest OS panic
410 colo guest is paused to save/restore VM state under colo checkpoint,
412 VM can not get into this state unless colo capability is enabled
413 for migration. (since 2.8)
414 preconfig
416 QEMU is paused before board specific init callback is executed.
417 The state is reachable only if the --preconfig CLI option is
418 used. (Since 3.0)
419 ShutdownCause (Enum)
421 An enumeration of reasons for a Shutdown.
422 Values
424 none No shutdown request pending
425 host-error
427 An error prevents further use of guest
428 host-qmp-quit
430 Reaction to the QMP command 'quit'
431 host-qmp-system-reset
433 Reaction to the QMP command 'system_reset'
434 host-signal
436 Reaction to a signal, such as SIGINT
437 host-ui
439 Reaction to a UI event, like window close
440 guest-shutdown
442 Guest shutdown/suspend request, via ACPI or other hardware-spe‐
443 cific means
444 guest-reset
446 Guest reset request, and command line turns that into a shutdown
447 guest-panic
449 Guest panicked, and command line turns that into a shutdown
450 subsystem-reset
452 Partial guest reset that does not trigger QMP events and ignores
453 --no-reboot. This is useful for sanitizing hypercalls on s390
454 that are used during kexec/kdump/boot
455 StatusInfo (Object)
457 Information about VCPU run state
458 Members
460 running: boolean
461 true if all VCPUs are runnable, false if not runnable
462 singlestep: boolean
464 true if VCPUs are in single-step mode
465 status: RunState
467 the virtual machine RunState
468 Since
470 0.14.0
471 Notes
473 singlestep is enabled through the GDB stub
474 query-status (Command)
476 Query the run status of all VCPUs
477 Returns
479 StatusInfo reflecting all VCPUs
480 Since
482 0.14.0
483 Example
485 -> { "execute": "query-status" }
486 <- { "return": { "running": true,
487 "singlestep": false,
488 "status": "running" } }
489 SHUTDOWN (Event)
491 Emitted when the virtual machine has shut down, indicating that qemu is
492 about to exit.
493 Arguments
495 guest: boolean
496 If true, the shutdown was triggered by a guest request (such as
497 a guest-initiated ACPI shutdown request or other hardware-spe‐
498 cific action) rather than a host request (such as sending qemu a
499 SIGINT). (since 2.10)
500 reason: ShutdownCause
502 The ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
503 Note
505 If the command-line option "-no-shutdown" has been specified, qemu will
506 not exit, and a STOP event will eventually follow the SHUTDOWN event
507 Since
509 0.12.0
510 Example
512 <- { "event": "SHUTDOWN", "data": { "guest": true },
513 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
514 POWERDOWN (Event)
516 Emitted when the virtual machine is powered down through the power con‐
517 trol system, such as via ACPI.
518 Since
520 0.12.0
521 Example
523 <- { "event": "POWERDOWN",
524 "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
525 RESET (Event)
527 Emitted when the virtual machine is reset
528 Arguments
530 guest: boolean
531 If true, the reset was triggered by a guest request (such as a
532 guest-initiated ACPI reboot request or other hardware-specific
533 action) rather than a host request (such as the QMP command sys‐
534 tem_reset). (since 2.10)
535 reason: ShutdownCause
537 The ShutdownCause of the RESET. (since 4.0)
538 Since
540 0.12.0
541 Example
543 <- { "event": "RESET", "data": { "guest": false },
544 "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
545 STOP (Event)
547 Emitted when the virtual machine is stopped
548 Since
550 0.12.0
551 Example
553 <- { "event": "STOP",
554 "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
555 RESUME (Event)
557 Emitted when the virtual machine resumes execution
558 Since
560 0.12.0
561 Example
563 <- { "event": "RESUME",
564 "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
565 SUSPEND (Event)
567 Emitted when guest enters a hardware suspension state, for example, S3
568 state, which is sometimes called standby state
569 Since
571 1.1
572 Example
574 <- { "event": "SUSPEND",
575 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
576 SUSPEND_DISK (Event)
578 Emitted when guest enters a hardware suspension state with data saved
579 on disk, for example, S4 state, which is sometimes called hibernate
580 state
581 Note
583 QEMU shuts down (similar to event SHUTDOWN) when entering this state
584 Since
586 1.2
587 Example
589 <- { "event": "SUSPEND_DISK",
590 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
591 WAKEUP (Event)
593 Emitted when the guest has woken up from suspend state and is running
594 Since
596 1.1
597 Example
599 <- { "event": "WAKEUP",
600 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
601 WATCHDOG (Event)
603 Emitted when the watchdog device's timer is expired
604 Arguments
606 action: WatchdogAction
607 action that has been taken
608 Note
610 If action is "reset", "shutdown", or "pause" the WATCHDOG event is fol‐
611 lowed respectively by the RESET, SHUTDOWN, or STOP events
612 Note
614 This event is rate-limited.
615 Since
617 0.13.0
618 Example
620 <- { "event": "WATCHDOG",
621 "data": { "action": "reset" },
622 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
623 WatchdogAction (Enum)
625 An enumeration of the actions taken when the watchdog device's timer is
626 expired
627 Values
629 reset system resets
630 shutdown
632 system shutdown, note that it is similar to powerdown, which
633 tries to set to system status and notify guest
634 poweroff
636 system poweroff, the emulator program exits
637 pause system pauses, similar to stop
639 debug system enters debug state
641 none nothing is done
643 inject-nmi
645 a non-maskable interrupt is injected into the first VCPU (all
646 VCPUS on x86) (since 2.4)
647 Since
649 2.1
650 watchdog-set-action (Command)
652 Set watchdog action
653 Arguments
655 action: WatchdogAction
656 Not documented
657 Since
659 2.11
660 GUEST_PANICKED (Event)
662 Emitted when guest OS panic is detected
663 Arguments
665 action: GuestPanicAction
666 action that has been taken, currently always "pause"
667 info: GuestPanicInformation (optional)
669 information about a panic (since 2.9)
670 Since
672 1.5
673 Example
675 <- { "event": "GUEST_PANICKED",
676 "data": { "action": "pause" } }
677 GUEST_CRASHLOADED (Event)
679 Emitted when guest OS crash loaded is detected
680 Arguments
682 action: GuestPanicAction
683 action that has been taken, currently always "run"
684 info: GuestPanicInformation (optional)
686 information about a panic
687 Since
689 5.0
690 Example
692 <- { "event": "GUEST_CRASHLOADED",
693 "data": { "action": "run" } }
694 GuestPanicAction (Enum)
696 An enumeration of the actions taken when guest OS panic is detected
697 Values
699 pause system pauses
700 poweroff
702 Not documented
703 run Not documented
705 Since
707 2.1 (poweroff since 2.8, run since 5.0)
708 GuestPanicInformationType (Enum)
710 An enumeration of the guest panic information types
711 Values
713 hyper-v
714 hyper-v guest panic information type
715 s390 s390 guest panic information type (Since: 2.12)
717 Since
719 2.9
720 GuestPanicInformation (Object)
722 Information about a guest panic
723 Members
725 type: GuestPanicInformationType
726 Crash type that defines the hypervisor specific information
727 The members of GuestPanicInformationHyperV when type is "hyper-v"
729 The members of GuestPanicInformationS390 when type is "s390"
731 Since
733 2.9
734 GuestPanicInformationHyperV (Object)
736 Hyper-V specific guest panic information (HV crash MSRs)
737 Members
739 arg1: int
740 Not documented
741 arg2: int
743 Not documented
744 arg3: int
746 Not documented
747 arg4: int
749 Not documented
750 arg5: int
752 Not documented
753 Since
755 2.9
756 S390CrashReason (Enum)
758 Reason why the CPU is in a crashed state.
759 Values
761 unknown
762 no crash reason was set
763 disabled-wait
765 the CPU has entered a disabled wait state
766 extint-loop
768 clock comparator or cpu timer interrupt with new PSW enabled for
769 external interrupts
770 pgmint-loop
772 program interrupt with BAD new PSW
773 opint-loop
775 operation exception interrupt with invalid code at the program
776 interrupt new PSW
777 Since
779 2.12
780 GuestPanicInformationS390 (Object)
782 S390 specific guest panic information (PSW)
783 Members
785 core: int
786 core id of the CPU that crashed
787 psw-mask: int
789 control fields of guest PSW
790 psw-addr: int
792 guest instruction address
793 reason: S390CrashReason
795 guest crash reason
796 Since
798 2.12
799 MEMORY_FAILURE (Event)
801 Emitted when a memory failure occurs on host side.
802 Arguments
804 recipient: MemoryFailureRecipient
805 recipient is defined as MemoryFailureRecipient.
806 action: MemoryFailureAction
808 action that has been taken. action is defined as MemoryFailure‐
809 Action.
810 flags: MemoryFailureFlags
812 flags for MemoryFailureAction. action is defined as MemoryFail‐
813 ureFlags.
814 Since
816 5.2
817 Example
819 <- { "event": "MEMORY_FAILURE",
820 "data": { "recipient": "hypervisor",
821 "action": "fatal",
822 "flags": { 'action-required': false } }
823 MemoryFailureRecipient (Enum)
825 Hardware memory failure occurs, handled by recipient.
826 Values
828 hypervisor
829 memory failure at QEMU process address space. (none guest mem‐
830 ory, but used by QEMU itself).
831 guest memory failure at guest memory,
833 Since
835 5.2
836 MemoryFailureAction (Enum)
838 Actions taken by QEMU in response to a hardware memory failure.
839 Values
841 ignore the memory failure could be ignored. This will only be the case
842 for action-optional failures.
843 inject memory failure occurred in guest memory, the guest enabled MCE
845 handling mechanism, and QEMU could inject the MCE into the guest
846 successfully.
847 fatal the failure is unrecoverable. This occurs for action-required
849 failures if the recipient is the hypervisor; QEMU will exit.
850 reset the failure is unrecoverable but confined to the guest. This
852 occurs if the recipient is a guest guest which is not ready to
853 handle memory failures.
854 Since
856 5.2
857 MemoryFailureFlags (Object)
859 Additional information on memory failures.
860 Members
862 action-required: boolean
863 whether a memory failure event is action-required or action-op‐
864 tional (e.g. a failure during memory scrub).
865 recursive: boolean
867 whether the failure occurred while the previous failure was
868 still in progress.
869 Since
871 5.2
872
874 QCryptoTLSCredsEndpoint (Enum)
875 The type of network endpoint that will be using the credentials. Most
876 types of credential require different setup / structures depending on
877 whether they will be used in a server versus a client.
878 Values
880 client the network endpoint is acting as the client
881 server the network endpoint is acting as the server
883 Since
885 2.5
886 QCryptoSecretFormat (Enum)
888 The data format that the secret is provided in
889 Values
891 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
892 be used
893 base64 arbitrary base64 encoded binary data
895 Since
897 2.6
898 QCryptoHashAlgorithm (Enum)
900 The supported algorithms for computing content digests
901 Values
903 md5 MD5. Should not be used in any new code, legacy compat only
904 sha1 SHA-1. Should not be used in any new code, legacy compat only
906 sha224 SHA-224. (since 2.7)
908 sha256 SHA-256. Current recommended strong hash.
910 sha384 SHA-384. (since 2.7)
912 sha512 SHA-512. (since 2.7)
914 ripemd160
916 RIPEMD-160. (since 2.7)
917 Since
919 2.6
920 QCryptoCipherAlgorithm (Enum)
922 The supported algorithms for content encryption ciphers
923 Values
925 aes-128
926 AES with 128 bit / 16 byte keys
927 aes-192
929 AES with 192 bit / 24 byte keys
930 aes-256
932 AES with 256 bit / 32 byte keys
933 des-rfb
935 RFB specific variant of single DES. Do not use except in VNC.
936 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
938 cast5-128
940 Cast5 with 128 bit / 16 byte keys
941 serpent-128
943 Serpent with 128 bit / 16 byte keys
944 serpent-192
946 Serpent with 192 bit / 24 byte keys
947 serpent-256
949 Serpent with 256 bit / 32 byte keys
950 twofish-128
952 Twofish with 128 bit / 16 byte keys
953 twofish-192
955 Twofish with 192 bit / 24 byte keys
956 twofish-256
958 Twofish with 256 bit / 32 byte keys
959 Since
961 2.6
962 QCryptoCipherMode (Enum)
964 The supported modes for content encryption ciphers
965 Values
967 ecb Electronic Code Book
968 cbc Cipher Block Chaining
970 xts XEX with tweaked code book and ciphertext stealing
972 ctr Counter (Since 2.8)
974 Since
976 2.6
977 QCryptoIVGenAlgorithm (Enum)
979 The supported algorithms for generating initialization vectors for full
980 disk encryption. The 'plain' generator should not be used for disks
981 with sector numbers larger than 2^32, except where compatibility with
982 pre-existing Linux dm-crypt volumes is required.
983 Values
985 plain 64-bit sector number truncated to 32-bits
986 plain64
988 64-bit sector number
989 essiv 64-bit sector number encrypted with a hash of the encryption key
991 Since
993 2.6
994 QCryptoBlockFormat (Enum)
996 The supported full disk encryption formats
997 Values
999 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
1000 data from old images.
1001 luks LUKS encryption format. Recommended for new images
1003 Since
1005 2.6
1006 QCryptoBlockOptionsBase (Object)
1008 The common options that apply to all full disk encryption formats
1009 Members
1011 format: QCryptoBlockFormat
1012 the encryption format
1013 Since
1015 2.6
1016 QCryptoBlockOptionsQCow (Object)
1018 The options that apply to QCow/QCow2 AES-CBC encryption format
1019 Members
1021 key-secret: string (optional)
1022 the ID of a QCryptoSecret object providing the decryption key.
1023 Mandatory except when probing image for metadata only.
1024 Since
1026 2.6
1027 QCryptoBlockOptionsLUKS (Object)
1029 The options that apply to LUKS encryption format
1030 Members
1032 key-secret: string (optional)
1033 the ID of a QCryptoSecret object providing the decryption key.
1034 Mandatory except when probing image for metadata only.
1035 Since
1037 2.6
1038 QCryptoBlockCreateOptionsLUKS (Object)
1040 The options that apply to LUKS encryption format initialization
1041 Members
1043 cipher-alg: QCryptoCipherAlgorithm (optional)
1044 the cipher algorithm for data encryption Currently defaults to
1045 'aes-256'.
1046 cipher-mode: QCryptoCipherMode (optional)
1048 the cipher mode for data encryption Currently defaults to 'xts'
1049 ivgen-alg: QCryptoIVGenAlgorithm (optional)
1051 the initialization vector generator Currently defaults to
1052 'plain64'
1053 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1055 the initialization vector generator hash Currently defaults to
1056 'sha256'
1057 hash-alg: QCryptoHashAlgorithm (optional)
1059 the master key hash algorithm Currently defaults to 'sha256'
1060 iter-time: int (optional)
1062 number of milliseconds to spend in PBKDF passphrase processing.
1063 Currently defaults to 2000. (since 2.8)
1064 The members of QCryptoBlockOptionsLUKS
1066 Since
1068 2.6
1069 QCryptoBlockOpenOptions (Object)
1071 The options that are available for all encryption formats when opening
1072 an existing volume
1073 Members
1075 The members of QCryptoBlockOptionsBase
1076 The members of QCryptoBlockOptionsQCow when format is "qcow"
1078 The members of QCryptoBlockOptionsLUKS when format is "luks"
1080 Since
1082 2.6
1083 QCryptoBlockCreateOptions (Object)
1085 The options that are available for all encryption formats when initial‐
1086 izing a new volume
1087 Members
1089 The members of QCryptoBlockOptionsBase
1090 The members of QCryptoBlockOptionsQCow when format is "qcow"
1092 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
1094 Since
1096 2.6
1097 QCryptoBlockInfoBase (Object)
1099 The common information that applies to all full disk encryption formats
1100 Members
1102 format: QCryptoBlockFormat
1103 the encryption format
1104 Since
1106 2.7
1107 QCryptoBlockInfoLUKSSlot (Object)
1109 Information about the LUKS block encryption key slot options
1110 Members
1112 active: boolean
1113 whether the key slot is currently in use
1114 key-offset: int
1116 offset to the key material in bytes
1117 iters: int (optional)
1119 number of PBKDF2 iterations for key material
1120 stripes: int (optional)
1122 number of stripes for splitting key material
1123 Since
1125 2.7
1126 QCryptoBlockInfoLUKS (Object)
1128 Information about the LUKS block encryption options
1129 Members
1131 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
1159 2.7
1160 QCryptoBlockInfo (Object)
1162 Information about the block encryption options
1163 Members
1165 The members of QCryptoBlockInfoBase
1166 The members of QCryptoBlockInfoLUKS when format is "luks"
1168 Since
1170 2.7
1171 QCryptoBlockLUKSKeyslotState (Enum)
1173 Defines state of keyslots that are affected by the update
1174 Values
1176 active The slots contain the given password and marked as active
1177 inactive
1179 The slots are erased (contain garbage) and marked as inactive
1180 Since
1182 5.1
1183 QCryptoBlockAmendOptionsLUKS (Object)
1185 This struct defines the update parameters that activate/de-activate set
1186 of keyslots
1187 Members
1189 state: QCryptoBlockLUKSKeyslotState
1190 the desired state of the keyslots
1191 new-secret: string (optional)
1193 The ID of a QCryptoSecret object providing the password to be
1194 written into added active keyslots
1195 old-secret: string (optional)
1197 Optional (for deactivation only) If given will deactivate all
1198 keyslots that match password located in QCryptoSecret with this
1199 ID
1200 iter-time: int (optional)
1202 Optional (for activation only) Number of milliseconds to spend
1203 in PBKDF passphrase processing for the newly activated keyslot.
1204 Currently defaults to 2000.
1205 keyslot: int (optional)
1207 Optional. ID of the keyslot to activate/deactivate. For keyslot
1208 activation, keyslot should not be active already (this is unsafe
1209 to update an active keyslot), but possible if 'force' parameter
1210 is given. If keyslot is not given, first free keyslot will be
1211 written.
1212 For keyslot deactivation, this parameter specifies the exact
1214 keyslot to deactivate
1215 secret: string (optional)
1217 Optional. The ID of a QCryptoSecret object providing the pass‐
1218 word to use to retrieve current master key. Defaults to the
1219 same secret that was used to open the image
1220 Since 5.1
1221 QCryptoBlockAmendOptions (Object)
1223 The options that are available for all encryption formats when amending
1224 encryption settings
1225 Members
1227 The members of QCryptoBlockOptionsBase
1228 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
1230 Since
1232 5.1
1233
1235 Block core (VM unrelated)
1236 Background jobs
1237 JobType (Enum)
1238 Type of a background job.
1239 Values
1241 commit block commit job type, see "block-commit"
1242 stream block stream job type, see "block-stream"
1244 mirror drive mirror job type, see "drive-mirror"
1246 backup drive backup job type, see "drive-backup"
1248 create image creation job type, see "blockdev-create" (since 3.0)
1250 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
1252 Since
1254 1.7
1255 JobStatus (Enum)
1257 Indicates the present state of a given job in its lifetime.
1258 Values
1260 undefined
1261 Erroneous, default state. Should not ever be visible.
1262 created
1264 The job has been created, but not yet started.
1265 running
1267 The job is currently running.
1268 paused The job is running, but paused. The pause may be requested by
1270 either the QMP user or by internal processes.
1271 ready The job is running, but is ready for the user to signal comple‐
1273 tion. This is used for long-running jobs like mirror that are
1274 designed to run indefinitely.
1275 standby
1277 The job is ready, but paused. This is nearly identical to
1278 paused. The job may return to ready or otherwise be canceled.
1279 waiting
1281 The job is waiting for other jobs in the transaction to converge
1282 to the waiting state. This status will likely not be visible for
1283 the last job in a transaction.
1284 pending
1286 The job has finished its work, but has finalization steps that
1287 it needs to make prior to completing. These changes will require
1288 manual intervention via job-finalize if auto-finalize was set to
1289 false. These pending changes may still fail.
1290 aborting
1292 The job is in the process of being aborted, and will finish with
1293 an error. The job will afterwards report that it is concluded.
1294 This status may not be visible to the management process.
1295 concluded
1297 The job has finished all work. If auto-dismiss was set to false,
1298 the job will remain in the query list until it is dismissed via
1299 job-dismiss.
1300 null The job is in the process of being dismantled. This state should
1302 not ever be visible externally.
1303 Since
1305 2.12
1306 JobVerb (Enum)
1308 Represents command verbs that can be applied to a job.
1309 Values
1311 cancel see job-cancel
1312 pause see job-pause
1314 resume see job-resume
1316 set-speed
1318 see block-job-set-speed
1319 complete
1321 see job-complete
1322 dismiss
1324 see job-dismiss
1325 finalize
1327 see job-finalize
1328 Since
1330 2.12
1331 JOB_STATUS_CHANGE (Event)
1333 Emitted when a job transitions to a different status.
1334 Arguments
1336 id: string
1337 The job identifier
1338 status: JobStatus
1340 The new job status
1341 Since
1343 3.0
1344 job-pause (Command)
1346 Pause an active job.
1347 This command returns immediately after marking the active job for paus‐
1349 ing. Pausing an already paused job is an error.
1350 The job will pause as soon as possible, which means transitioning into
1352 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
1353 The corresponding JOB_STATUS_CHANGE event will be emitted.
1354 Cancelling a paused job automatically resumes it.
1356 Arguments
1358 id: string
1359 The job identifier.
1360 Since
1362 3.0
1363 job-resume (Command)
1365 Resume a paused job.
1366 This command returns immediately after resuming a paused job. Resuming
1368 an already running job is an error.
1369 id : The job identifier.
1371 Arguments
1373 id: string
1374 Not documented
1375 Since
1377 3.0
1378 job-cancel (Command)
1380 Instruct an active background job to cancel at the next opportunity.
1381 This command returns immediately after marking the active job for can‐
1382 cellation.
1383 The job will cancel as soon as possible and then emit a JOB_STA‐
1385 TUS_CHANGE event. Usually, the status will change to ABORTING, but it
1386 is possible that a job successfully completes (e.g. because it was al‐
1387 most done and there was no opportunity to cancel earlier than complet‐
1388 ing the job) and transitions to PENDING instead.
1389 Arguments
1391 id: string
1392 The job identifier.
1393 Since
1395 3.0
1396 job-complete (Command)
1398 Manually trigger completion of an active job in the READY state.
1399 Arguments
1401 id: string
1402 The job identifier.
1403 Since
1405 3.0
1406 job-dismiss (Command)
1408 Deletes a job that is in the CONCLUDED state. This command only needs
1409 to be run explicitly for jobs that don't have automatic dismiss en‐
1410 abled.
1411 This command will refuse to operate on any job that has not yet reached
1413 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
1414 JOB_READY event, job-cancel or job-complete will still need to be used
1415 as appropriate.
1416 Arguments
1418 id: string
1419 The job identifier.
1420 Since
1422 3.0
1423 job-finalize (Command)
1425 Instructs all jobs in a transaction (or a single job if it is not part
1426 of any transaction) to finalize any graph changes and do any necessary
1427 cleanup. This command requires that all involved jobs are in the PEND‐
1428 ING state.
1429 For jobs in a transaction, instructing one job to finalize will force
1431 ALL jobs in the transaction to finalize, so it is only necessary to in‐
1432 struct a single member job to finalize.
1433 Arguments
1435 id: string
1436 The identifier of any job in the transaction, or of a job that
1437 is not part of any transaction.
1438 Since
1440 3.0
1441 JobInfo (Object)
1443 Information about a job.
1444 Members
1446 id: string
1447 The job identifier
1448 type: JobType
1450 The kind of job that is being performed
1451 status: JobStatus
1453 Current job state/status
1454 current-progress: int
1456 Progress made until now. The unit is arbitrary and the value can
1457 only meaningfully be used for the ratio of current-progress to
1458 total-progress. The value is monotonically increasing.
1459 total-progress: int
1461 Estimated current-progress value at the completion of the job.
1462 This value can arbitrarily change while the job is running, in
1463 both directions.
1464 error: string (optional)
1466 If this field is present, the job failed; if it is still missing
1467 in the CONCLUDED state, this indicates successful completion.
1468 The value is a human-readable error message to describe the rea‐
1470 son for the job failure. It should not be parsed by applica‐
1471 tions.
1472 Since
1474 3.0
1475 query-jobs (Command)
1477 Return information about jobs.
1478 Returns
1480 a list with a JobInfo for each active job
1481 Since
1483 3.0
1484 SnapshotInfo (Object)
1486 Members
1487 id: string
1488 unique snapshot id
1489 name: string
1491 user chosen name
1492 vm-state-size: int
1494 size of the VM state
1495 date-sec: int
1497 UTC date of the snapshot in seconds
1498 date-nsec: int
1500 fractional part in nano seconds to be used with date-sec
1501 vm-clock-sec: int
1503 VM clock relative to boot in seconds
1504 vm-clock-nsec: int
1506 fractional part in nano seconds to be used with vm-clock-sec
1507 icount: int (optional)
1509 Current instruction count. Appears when execution record/replay
1510 is enabled. Used for "time-traveling" to match the moment in the
1511 recorded execution with the snapshots. This counter may be ob‐
1512 tained through query-replay command (since 5.2)
1513 Since
1515 1.3
1516 ImageInfoSpecificQCow2EncryptionBase (Object)
1518 Members
1519 format: BlockdevQcow2EncryptionFormat
1520 The encryption format
1521 Since
1523 2.10
1524 ImageInfoSpecificQCow2Encryption (Object)
1526 Members
1527 The members of ImageInfoSpecificQCow2EncryptionBase
1528 The members of QCryptoBlockInfoLUKS when format is "luks"
1530 Since
1532 2.10
1533 ImageInfoSpecificQCow2 (Object)
1535 Members
1536 compat: string
1537 compatibility level
1538 data-file: string (optional)
1540 the filename of the external data file that is stored in the im‐
1541 age and used as a default for opening the image (since: 4.0)
1542 data-file-raw: boolean (optional)
1544 True if the external data file must stay valid as a standalone
1545 (read-only) raw image without looking at qcow2 metadata (since:
1546 4.0)
1547 extended-l2: boolean (optional)
1549 true if the image has extended L2 entries; only valid for compat
1550 >= 1.1 (since 5.2)
1551 lazy-refcounts: boolean (optional)
1553 on or off; only valid for compat >= 1.1
1554 corrupt: boolean (optional)
1556 true if the image has been marked corrupt; only valid for compat
1557 >= 1.1 (since 2.2)
1558 refcount-bits: int
1560 width of a refcount entry in bits (since 2.3)
1561 encrypt: ImageInfoSpecificQCow2Encryption (optional)
1563 details about encryption parameters; only set if image is en‐
1564 crypted (since 2.10)
1565 bitmaps: array of Qcow2BitmapInfo (optional)
1567 A list of qcow2 bitmap details (since 4.0)
1568 compression-type: Qcow2CompressionType
1570 the image cluster compression method (since 5.1)
1571 Since
1573 1.7
1574 ImageInfoSpecificVmdk (Object)
1576 Members
1577 create-type: string
1578 The create type of VMDK image
1579 cid: int
1581 Content id of image
1582 parent-cid: int
1584 Parent VMDK image's cid
1585 extents: array of ImageInfo
1587 List of extent files
1588 Since
1590 1.7
1591 ImageInfoSpecific (Object)
1593 A discriminated record of image format specific information structures.
1594 Members
1596 type One of qcow2, vmdk, luks
1597 data: ImageInfoSpecificQCow2 when type is "qcow2"
1599 data: ImageInfoSpecificVmdk when type is "vmdk"
1601 data: QCryptoBlockInfoLUKS when type is "luks"
1603 Since
1605 1.7
1606 ImageInfo (Object)
1608 Information about a QEMU image file
1609 Members
1611 filename: string
1612 name of the image file
1613 format: string
1615 format of the image file
1616 virtual-size: int
1618 maximum capacity in bytes of the image
1619 actual-size: int (optional)
1621 actual size on disk in bytes of the image
1622 dirty-flag: boolean (optional)
1624 true if image is not cleanly closed
1625 cluster-size: int (optional)
1627 size of a cluster in bytes
1628 encrypted: boolean (optional)
1630 true if the image is encrypted
1631 compressed: boolean (optional)
1633 true if the image is compressed (Since 1.7)
1634 backing-filename: string (optional)
1636 name of the backing file
1637 full-backing-filename: string (optional)
1639 full path of the backing file
1640 backing-filename-format: string (optional)
1642 the format of the backing file
1643 snapshots: array of SnapshotInfo (optional)
1645 list of VM snapshots
1646 backing-image: ImageInfo (optional)
1648 info of the backing image (since 1.6)
1649 format-specific: ImageInfoSpecific (optional)
1651 structure supplying additional format-specific information
1652 (since 1.7)
1653 Since
1655 1.3
1656 ImageCheck (Object)
1658 Information about a QEMU image file check
1659 Members
1661 filename: string
1662 name of the image file checked
1663 format: string
1665 format of the image file checked
1666 check-errors: int
1668 number of unexpected errors occurred during check
1669 image-end-offset: int (optional)
1671 offset (in bytes) where the image ends, this field is present if
1672 the driver for the image format supports it
1673 corruptions: int (optional)
1675 number of corruptions found during the check if any
1676 leaks: int (optional)
1678 number of leaks found during the check if any
1679 corruptions-fixed: int (optional)
1681 number of corruptions fixed during the check if any
1682 leaks-fixed: int (optional)
1684 number of leaks fixed during the check if any
1685 total-clusters: int (optional)
1687 total number of clusters, this field is present if the driver
1688 for the image format supports it
1689 allocated-clusters: int (optional)
1691 total number of allocated clusters, this field is present if the
1692 driver for the image format supports it
1693 fragmented-clusters: int (optional)
1695 total number of fragmented clusters, this field is present if
1696 the driver for the image format supports it
1697 compressed-clusters: int (optional)
1699 total number of compressed clusters, this field is present if
1700 the driver for the image format supports it
1701 Since
1703 1.4
1704 MapEntry (Object)
1706 Mapping information from a virtual block range to a host file range
1707 Members
1709 start: int
1710 virtual (guest) offset of the first byte described by this entry
1711 length: int
1713 the number of bytes of the mapped virtual range
1714 data: boolean
1716 reading the image will actually read data from a file (in par‐
1717 ticular, if offset is present this means that the sectors are
1718 not simply preallocated, but contain actual data in raw format)
1719 zero: boolean
1721 whether the virtual blocks read as zeroes
1722 depth: int
1724 number of layers (0 = top image, 1 = top image's backing file,
1725 ..., n - 1 = bottom image (where n is the number of images in
1726 the chain)) before reaching one for which the range is allocated
1727 offset: int (optional)
1729 if present, the image file stores the data for this range in raw
1730 format at the given (host) offset
1731 filename: string (optional)
1733 filename that is referred to by offset
1734 Since
1736 2.6
1737 BlockdevCacheInfo (Object)
1739 Cache mode information for a block device
1740 Members
1742 writeback: boolean
1743 true if writeback mode is enabled
1744 direct: boolean
1746 true if the host page cache is bypassed (O_DIRECT)
1747 no-flush: boolean
1749 true if flush requests are ignored for the device
1750 Since
1752 2.3
1753 BlockDeviceInfo (Object)
1755 Information about the backing device for a block device.
1756 Members
1758 file: string
1759 the filename of the backing device
1760 node-name: string (optional)
1762 the name of the block driver node (Since 2.0)
1763 ro: boolean
1765 true if the backing device was open read-only
1766 drv: string
1768 the name of the block format used to open the backing device. As
1769 of 0.14.0 this can be: 'blkdebug', 'bochs', 'cloop', 'cow',
1770 'dmg', 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_de‐
1771 vice', 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow',
1772 'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago'
1773 added, 'cow' dropped 2.3: 'host_floppy' deprecated 2.5:
1774 'host_floppy' dropped 2.6: 'luks' added 2.8: 'replication'
1775 added, 'tftp' dropped 2.9: 'archipelago' dropped
1776 backing_file: string (optional)
1778 the name of the backing file (for copy-on-write)
1779 backing_file_depth: int
1781 number of files in the backing file chain (since: 1.2)
1782 encrypted: boolean
1784 true if the backing device is encrypted
1785 encryption_key_missing: boolean
1787 always false
1788 detect_zeroes: BlockdevDetectZeroesOptions
1790 detect and optimize zero writes (Since 2.1)
1791 bps: int
1793 total throughput limit in bytes per second is specified
1794 bps_rd: int
1796 read throughput limit in bytes per second is specified
1797 bps_wr: int
1799 write throughput limit in bytes per second is specified
1800 iops: int
1802 total I/O operations per second is specified
1803 iops_rd: int
1805 read I/O operations per second is specified
1806 iops_wr: int
1808 write I/O operations per second is specified
1809 image: ImageInfo
1811 the info of image used (since: 1.6)
1812 bps_max: int (optional)
1814 total throughput limit during bursts,
1816 in bytes (Since 1.7)
1817 bps_rd_max: int (optional)
1819 read throughput limit during bursts,
1821 in bytes (Since 1.7)
1822 bps_wr_max: int (optional)
1824 write throughput limit during bursts,
1826 in bytes (Since 1.7)
1827 iops_max: int (optional)
1829 total I/O operations per second during bursts,
1831 in bytes (Since 1.7)
1832 iops_rd_max: int (optional)
1834 read I/O operations per second during bursts,
1836 in bytes (Since 1.7)
1837 iops_wr_max: int (optional)
1839 write I/O operations per second during bursts,
1841 in bytes (Since 1.7)
1842 bps_max_length: int (optional)
1844 maximum length of the bps_max burst
1846 period, in seconds. (Since 2.6)
1847 bps_rd_max_length: int (optional)
1849 maximum length of the bps_rd_max
1851 burst period, in seconds. (Since 2.6)
1852 bps_wr_max_length: int (optional)
1854 maximum length of the bps_wr_max
1856 burst period, in seconds. (Since 2.6)
1857 iops_max_length: int (optional)
1859 maximum length of the iops burst
1861 period, in seconds. (Since 2.6)
1862 iops_rd_max_length: int (optional)
1864 maximum length of the iops_rd_max
1866 burst period, in seconds. (Since 2.6)
1867 iops_wr_max_length: int (optional)
1869 maximum length of the iops_wr_max
1871 burst period, in seconds. (Since 2.6)
1872 iops_size: int (optional)
1874 an I/O size in bytes (Since 1.7)
1875 group: string (optional)
1877 throttle group name (Since 2.4)
1878 cache: BlockdevCacheInfo
1880 the cache mode used for the block device (since: 2.3)
1881 write_threshold: int
1883 configured write threshold for the device. 0 if disabled.
1884 (Since 2.3)
1885 dirty-bitmaps: array of BlockDirtyInfo (optional)
1887 dirty bitmaps information (only present if node has one or more
1888 dirty bitmaps) (Since 4.2)
1889 Features
1891 deprecated
1892 Member encryption_key_missing is deprecated. It is always
1893 false.
1894 Since
1896 0.14.0
1897 BlockDeviceIoStatus (Enum)
1899 An enumeration of block device I/O status.
1900 Values
1902 ok The last I/O operation has succeeded
1903 failed The last I/O operation has failed
1905 nospace
1907 The last I/O operation has failed due to a no-space condition
1908 Since
1910 1.0
1911 DirtyBitmapStatus (Enum)
1913 An enumeration of possible states that a dirty bitmap can report to the
1914 user.
1915 Values
1917 frozen The bitmap is currently in-use by some operation and is im‐
1918 mutable. If the bitmap was active prior to the operation, new
1919 writes by the guest are being recorded in a temporary buffer,
1920 and will not be lost. Generally, bitmaps are cleared on suc‐
1921 cessful use in an operation and the temporary buffer is commit‐
1922 ted into the bitmap. On failure, the temporary buffer is merged
1923 back into the bitmap without first clearing it. Please refer to
1924 the documentation for each bitmap-using operation, See also
1925 blockdev-backup, drive-backup.
1926 disabled
1928 The bitmap is not currently recording new writes by the guest.
1929 This is requested explicitly via block-dirty-bitmap-disable. It
1930 can still be cleared, deleted, or used for backup operations.
1931 active The bitmap is actively monitoring for new writes, and can be
1933 cleared, deleted, or used for backup operations.
1934 locked The bitmap is currently in-use by some operation and is im‐
1936 mutable. If the bitmap was active prior to the operation, it is
1937 still recording new writes. If the bitmap was disabled, it is
1938 not recording new writes. (Since 2.12)
1939 inconsistent
1941 This is a persistent dirty bitmap that was marked in-use on
1942 disk, and is unusable by QEMU. It can only be deleted. Please
1943 rely on the inconsistent field in BlockDirtyInfo instead, as the
1944 status field is deprecated. (Since 4.0)
1945 Since
1947 2.4
1948 BlockDirtyInfo (Object)
1950 Block dirty bitmap information.
1951 Members
1953 name: string (optional)
1954 the name of the dirty bitmap (Since 2.4)
1955 count: int
1957 number of dirty bytes according to the dirty bitmap
1958 granularity: int
1960 granularity of the dirty bitmap in bytes (since 1.4)
1961 status: DirtyBitmapStatus
1963 current status of the dirty bitmap (since 2.4)
1964 recording: boolean
1966 true if the bitmap is recording new writes from the guest. Re‐
1967 places active and disabled statuses. (since 4.0)
1968 busy: boolean
1970 true if the bitmap is in-use by some operation (NBD or jobs) and
1971 cannot be modified via QMP or used by another operation. Re‐
1972 places locked and frozen statuses. (since 4.0)
1973 persistent: boolean
1975 true if the bitmap was stored on disk, is scheduled to be stored
1976 on disk, or both. (since 4.0)
1977 inconsistent: boolean (optional)
1979 true if this is a persistent bitmap that was improperly stored.
1980 Implies persistent to be true; recording and busy to be false.
1981 This bitmap cannot be used. To remove it, use block-dirty-bit‐
1982 map-remove. (Since 4.0)
1983 Features
1985 deprecated
1986 Member status is deprecated. Use recording and locked instead.
1987 Since
1989 1.3
1990 Qcow2BitmapInfoFlags (Enum)
1992 An enumeration of flags that a bitmap can report to the user.
1993 Values
1995 in-use This flag is set by any process actively modifying the qcow2
1996 file, and cleared when the updated bitmap is flushed to the
1997 qcow2 image. The presence of this flag in an offline image
1998 means that the bitmap was not saved correctly after its last us‐
1999 age, and may contain inconsistent data.
2000 auto The bitmap must reflect all changes of the virtual disk by any
2002 application that would write to this qcow2 file.
2003 Since
2005 4.0
2006 Qcow2BitmapInfo (Object)
2008 Qcow2 bitmap information.
2009 Members
2011 name: string
2012 the name of the bitmap
2013 granularity: int
2015 granularity of the bitmap in bytes
2016 flags: array of Qcow2BitmapInfoFlags
2018 flags of the bitmap
2019 Since
2021 4.0
2022 BlockLatencyHistogramInfo (Object)
2024 Block latency histogram.
2025 Members
2027 boundaries: array of int
2028 list of interval boundary values in nanoseconds, all greater
2029 than zero and in ascending order. For example, the list [10,
2030 50, 100] produces the following histogram intervals: [0, 10),
2031 [10, 50), [50, 100), [100, +inf).
2032 bins: array of int
2034 list of io request counts corresponding to histogram intervals.
2035 len(bins) = len(boundaries) + 1 For the example above, bins may
2036 be something like [3, 1, 5, 2], and corresponding histogram
2037 looks like:
2038 5| *
2040 4| *
2041 3| * *
2042 2| * * *
2043 1| * * * *
2044 +------------------
2045 10 50 100
2046 Since
2048 4.0
2049 BlockInfo (Object)
2051 Block device information. This structure describes a virtual device
2052 and the backing device associated with it.
2053 Members
2055 device: string
2056 The device name associated with the virtual device.
2057 qdev: string (optional)
2059 The qdev ID, or if no ID is assigned, the QOM path of the block
2060 device. (since 2.10)
2061 type: string
2063 This field is returned only for compatibility reasons, it should
2064 not be used (always returns 'unknown')
2065 removable: boolean
2067 True if the device supports removable media.
2068 locked: boolean
2070 True if the guest has locked this device from having its media
2071 removed
2072 tray_open: boolean (optional)
2074 True if the device's tray is open (only present if it has a
2075 tray)
2076 dirty-bitmaps: array of BlockDirtyInfo (optional)
2078 dirty bitmaps information (only present if the driver has one or
2079 more dirty bitmaps) (Since 2.0)
2080 io-status: BlockDeviceIoStatus (optional)
2082 BlockDeviceIoStatus. Only present if the device supports it and
2083 the VM is configured to stop on errors (supported device models:
2084 virtio-blk, IDE, SCSI except scsi-generic)
2085 inserted: BlockDeviceInfo (optional)
2087 BlockDeviceInfo describing the device if media is present
2088 Features
2090 deprecated
2091 Member dirty-bitmaps is deprecated. Use inserted member
2092 dirty-bitmaps instead.
2093 Since
2095 0.14.0
2096 BlockMeasureInfo (Object)
2098 Image file size calculation information. This structure describes the
2099 size requirements for creating a new image file.
2100 The size requirements depend on the new image file format. File size
2102 always equals virtual disk size for the 'raw' format, even for sparse
2103 POSIX files. Compact formats such as 'qcow2' represent unallocated and
2104 zero regions efficiently so file size may be smaller than virtual disk
2105 size.
2106 The values are upper bounds that are guaranteed to fit the new image
2108 file. Subsequent modification, such as internal snapshot or further
2109 bitmap creation, may require additional space and is not covered here.
2110 Members
2112 required: int
2113 Size required for a new image file, in bytes, when copying just
2114 allocated guest-visible contents.
2115 fully-allocated: int
2117 Image file size, in bytes, once data has been written to all
2118 sectors, when copying just guest-visible contents.
2119 bitmaps: int (optional)
2121 Additional size required if all the top-level bitmap metadata in
2122 the source image were to be copied to the destination, present
2123 only when source and destination both support persistent bit‐
2124 maps. (since 5.1)
2125 Since
2127 2.10
2128 query-block (Command)
2130 Get a list of BlockInfo for all virtual block devices.
2131 Returns
2133 a list of BlockInfo describing each virtual block device. Filter nodes
2134 that were created implicitly are skipped over.
2135 Since
2137 0.14.0
2138 Example
2140 -> { "execute": "query-block" }
2141 <- {
2142 "return":[
2143 {
2144 "io-status": "ok",
2145 "device":"ide0-hd0",
2146 "locked":false,
2147 "removable":false,
2148 "inserted":{
2149 "ro":false,
2150 "drv":"qcow2",
2151 "encrypted":false,
2152 "file":"disks/test.qcow2",
2153 "backing_file_depth":1,
2154 "bps":1000000,
2155 "bps_rd":0,
2156 "bps_wr":0,
2157 "iops":1000000,
2158 "iops_rd":0,
2159 "iops_wr":0,
2160 "bps_max": 8000000,
2161 "bps_rd_max": 0,
2162 "bps_wr_max": 0,
2163 "iops_max": 0,
2164 "iops_rd_max": 0,
2165 "iops_wr_max": 0,
2166 "iops_size": 0,
2167 "detect_zeroes": "on",
2168 "write_threshold": 0,
2169 "image":{
2170 "filename":"disks/test.qcow2",
2171 "format":"qcow2",
2172 "virtual-size":2048000,
2173 "backing_file":"base.qcow2",
2174 "full-backing-filename":"disks/base.qcow2",
2175 "backing-filename-format":"qcow2",
2176 "snapshots":[
2177 {
2178 "id": "1",
2179 "name": "snapshot1",
2180 "vm-state-size": 0,
2181 "date-sec": 10000200,
2182 "date-nsec": 12,
2183 "vm-clock-sec": 206,
2184 "vm-clock-nsec": 30
2185 }
2186 ],
2187 "backing-image":{
2188 "filename":"disks/base.qcow2",
2189 "format":"qcow2",
2190 "virtual-size":2048000
2191 }
2192 }
2193 },
2194 "qdev": "ide_disk",
2195 "type":"unknown"
2196 },
2197 {
2198 "io-status": "ok",
2199 "device":"ide1-cd0",
2200 "locked":false,
2201 "removable":true,
2202 "qdev": "/machine/unattached/device[23]",
2203 "tray_open": false,
2204 "type":"unknown"
2205 },
2206 {
2207 "device":"floppy0",
2208 "locked":false,
2209 "removable":true,
2210 "qdev": "/machine/unattached/device[20]",
2211 "type":"unknown"
2212 },
2213 {
2214 "device":"sd0",
2215 "locked":false,
2216 "removable":true,
2217 "type":"unknown"
2218 }
2219 ]
2220 }
2221 BlockDeviceTimedStats (Object)
2223 Statistics of a block device during a given interval of time.
2224 Members
2226 interval_length: int
2227 Interval used for calculating the statistics, in seconds.
2228 min_rd_latency_ns: int
2230 Minimum latency of read operations in the defined interval, in
2231 nanoseconds.
2232 min_wr_latency_ns: int
2234 Minimum latency of write operations in the defined interval, in
2235 nanoseconds.
2236 min_flush_latency_ns: int
2238 Minimum latency of flush operations in the defined interval, in
2239 nanoseconds.
2240 max_rd_latency_ns: int
2242 Maximum latency of read operations in the defined interval, in
2243 nanoseconds.
2244 max_wr_latency_ns: int
2246 Maximum latency of write operations in the defined interval, in
2247 nanoseconds.
2248 max_flush_latency_ns: int
2250 Maximum latency of flush operations in the defined interval, in
2251 nanoseconds.
2252 avg_rd_latency_ns: int
2254 Average latency of read operations in the defined interval, in
2255 nanoseconds.
2256 avg_wr_latency_ns: int
2258 Average latency of write operations in the defined interval, in
2259 nanoseconds.
2260 avg_flush_latency_ns: int
2262 Average latency of flush operations in the defined interval, in
2263 nanoseconds.
2264 avg_rd_queue_depth: number
2266 Average number of pending read operations in the defined inter‐
2267 val.
2268 avg_wr_queue_depth: number
2270 Average number of pending write operations in the defined inter‐
2271 val.
2272 Since
2274 2.5
2275 BlockDeviceStats (Object)
2277 Statistics of a virtual block device or a block backing device.
2278 Members
2280 rd_bytes: int
2281 The number of bytes read by the device.
2282 wr_bytes: int
2284 The number of bytes written by the device.
2285 unmap_bytes: int
2287 The number of bytes unmapped by the device (Since 4.2)
2288 rd_operations: int
2290 The number of read operations performed by the device.
2291 wr_operations: int
2293 The number of write operations performed by the device.
2294 flush_operations: int
2296 The number of cache flush operations performed by the device
2297 (since 0.15.0)
2298 unmap_operations: int
2300 The number of unmap operations performed by the device (Since
2301 4.2)
2302 rd_total_time_ns: int
2304 Total time spent on reads in nanoseconds (since 0.15.0).
2305 wr_total_time_ns: int
2307 Total time spent on writes in nanoseconds (since 0.15.0).
2308 flush_total_time_ns: int
2310 Total time spent on cache flushes in nanoseconds (since 0.15.0).
2311 unmap_total_time_ns: int
2313 Total time spent on unmap operations in nanoseconds (Since 4.2)
2314 wr_highest_offset: int
2316 The offset after the greatest byte written to the device. The
2317 intended use of this information is for growable sparse files
2318 (like qcow2) that are used on top of a physical device.
2319 rd_merged: int
2321 Number of read requests that have been merged into another re‐
2322 quest (Since 2.3).
2323 wr_merged: int
2325 Number of write requests that have been merged into another re‐
2326 quest (Since 2.3).
2327 unmap_merged: int
2329 Number of unmap requests that have been merged into another re‐
2330 quest (Since 4.2)
2331 idle_time_ns: int (optional)
2333 Time since the last I/O operation, in nanoseconds. If the field
2334 is absent it means that there haven't been any operations yet
2335 (Since 2.5).
2336 failed_rd_operations: int
2338 The number of failed read operations performed by the device
2339 (Since 2.5)
2340 failed_wr_operations: int
2342 The number of failed write operations performed by the device
2343 (Since 2.5)
2344 failed_flush_operations: int
2346 The number of failed flush operations performed by the device
2347 (Since 2.5)
2348 failed_unmap_operations: int
2350 The number of failed unmap operations performed by the device
2351 (Since 4.2)
2352 invalid_rd_operations: int
2354 The number of invalid read operations
2356 performed by the device (Since 2.5)
2357 invalid_wr_operations: int
2359 The number of invalid write operations performed by the device
2360 (Since 2.5)
2361 invalid_flush_operations: int
2363 The number of invalid flush operations performed by the device
2364 (Since 2.5)
2365 invalid_unmap_operations: int
2367 The number of invalid unmap operations performed by the device
2368 (Since 4.2)
2369 account_invalid: boolean
2371 Whether invalid operations are included in the last access sta‐
2372 tistics (Since 2.5)
2373 account_failed: boolean
2375 Whether failed operations are included in the latency and last
2376 access statistics (Since 2.5)
2377 timed_stats: array of BlockDeviceTimedStats
2379 Statistics specific to the set of previously defined intervals
2380 of time (Since 2.5)
2381 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
2383 BlockLatencyHistogramInfo. (Since 4.0)
2384 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
2386 BlockLatencyHistogramInfo. (Since 4.0)
2387 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
2389 BlockLatencyHistogramInfo. (Since 4.0)
2390 Since
2392 0.14.0
2393 BlockStatsSpecificFile (Object)
2395 File driver statistics
2396 Members
2398 discard-nb-ok: int
2399 The number of successful discard operations performed by the
2400 driver.
2401 discard-nb-failed: int
2403 The number of failed discard operations performed by the driver.
2404 discard-bytes-ok: int
2406 The number of bytes discarded by the driver.
2407 Since
2409 4.2
2410 BlockStatsSpecificNvme (Object)
2412 NVMe driver statistics
2413 Members
2415 completion-errors: int
2416 The number of completion errors.
2417 aligned-accesses: int
2419 The number of aligned accesses performed by the driver.
2420 unaligned-accesses: int
2422 The number of unaligned accesses performed by the driver.
2423 Since
2425 5.2
2426 BlockStatsSpecific (Object)
2428 Block driver specific statistics
2429 Members
2431 driver: BlockdevDriver
2432 Not documented
2433 The members of BlockStatsSpecificFile when driver is "file"
2435 The members of BlockStatsSpecificFile when driver is "host_device"
2437 The members of BlockStatsSpecificNvme when driver is "nvme"
2439 Since
2441 4.2
2442 BlockStats (Object)
2444 Statistics of a virtual block device or a block backing device.
2445 Members
2447 device: string (optional)
2448 If the stats are for a virtual block device, the name corre‐
2449 sponding to the virtual block device.
2450 node-name: string (optional)
2452 The node name of the device. (Since 2.3)
2453 qdev: string (optional)
2455 The qdev ID, or if no ID is assigned, the QOM path of the block
2456 device. (since 3.0)
2457 stats: BlockDeviceStats
2459 A BlockDeviceStats for the device.
2460 driver-specific: BlockStatsSpecific (optional)
2462 Optional driver-specific stats. (Since 4.2)
2463 parent: BlockStats (optional)
2465 This describes the file block device if it has one. Contains
2466 recursively the statistics of the underlying protocol (e.g. the
2467 host file for a qcow2 image). If there is no underlying proto‐
2468 col, this field is omitted
2469 backing: BlockStats (optional)
2471 This describes the backing block device if it has one. (Since
2472 2.0)
2473 Since
2475 0.14.0
2476 query-blockstats (Command)
2478 Query the BlockStats for all virtual block devices.
2479 Arguments
2481 query-nodes: boolean (optional)
2482 If true, the command will query all the block nodes that have a
2483 node name, in a list which will include "parent" information,
2484 but not "backing". If false or omitted, the behavior is as be‐
2485 fore - query all the device backends, recursively including
2486 their "parent" and "backing". Filter nodes that were created im‐
2487 plicitly are skipped over in this mode. (Since 2.3)
2488 Returns
2490 A list of BlockStats for each virtual block devices.
2491 Since
2493 0.14.0
2494 Example
2496 -> { "execute": "query-blockstats" }
2497 <- {
2498 "return":[
2499 {
2500 "device":"ide0-hd0",
2501 "parent":{
2502 "stats":{
2503 "wr_highest_offset":3686448128,
2504 "wr_bytes":9786368,
2505 "wr_operations":751,
2506 "rd_bytes":122567168,
2507 "rd_operations":36772
2508 "wr_total_times_ns":313253456
2509 "rd_total_times_ns":3465673657
2510 "flush_total_times_ns":49653
2511 "flush_operations":61,
2512 "rd_merged":0,
2513 "wr_merged":0,
2514 "idle_time_ns":2953431879,
2515 "account_invalid":true,
2516 "account_failed":false
2517 }
2518 },
2519 "stats":{
2520 "wr_highest_offset":2821110784,
2521 "wr_bytes":9786368,
2522 "wr_operations":692,
2523 "rd_bytes":122739200,
2524 "rd_operations":36604
2525 "flush_operations":51,
2526 "wr_total_times_ns":313253456
2527 "rd_total_times_ns":3465673657
2528 "flush_total_times_ns":49653,
2529 "rd_merged":0,
2530 "wr_merged":0,
2531 "idle_time_ns":2953431879,
2532 "account_invalid":true,
2533 "account_failed":false
2534 },
2535 "qdev": "/machine/unattached/device[23]"
2536 },
2537 {
2538 "device":"ide1-cd0",
2539 "stats":{
2540 "wr_highest_offset":0,
2541 "wr_bytes":0,
2542 "wr_operations":0,
2543 "rd_bytes":0,
2544 "rd_operations":0
2545 "flush_operations":0,
2546 "wr_total_times_ns":0
2547 "rd_total_times_ns":0
2548 "flush_total_times_ns":0,
2549 "rd_merged":0,
2550 "wr_merged":0,
2551 "account_invalid":false,
2552 "account_failed":false
2553 },
2554 "qdev": "/machine/unattached/device[24]"
2555 },
2556 {
2557 "device":"floppy0",
2558 "stats":{
2559 "wr_highest_offset":0,
2560 "wr_bytes":0,
2561 "wr_operations":0,
2562 "rd_bytes":0,
2563 "rd_operations":0
2564 "flush_operations":0,
2565 "wr_total_times_ns":0
2566 "rd_total_times_ns":0
2567 "flush_total_times_ns":0,
2568 "rd_merged":0,
2569 "wr_merged":0,
2570 "account_invalid":false,
2571 "account_failed":false
2572 },
2573 "qdev": "/machine/unattached/device[16]"
2574 },
2575 {
2576 "device":"sd0",
2577 "stats":{
2578 "wr_highest_offset":0,
2579 "wr_bytes":0,
2580 "wr_operations":0,
2581 "rd_bytes":0,
2582 "rd_operations":0
2583 "flush_operations":0,
2584 "wr_total_times_ns":0
2585 "rd_total_times_ns":0
2586 "flush_total_times_ns":0,
2587 "rd_merged":0,
2588 "wr_merged":0,
2589 "account_invalid":false,
2590 "account_failed":false
2591 }
2592 }
2593 ]
2594 }
2595 BlockdevOnError (Enum)
2597 An enumeration of possible behaviors for errors on I/O operations. The
2598 exact meaning depends on whether the I/O was initiated by a guest or by
2599 a block job
2600 Values
2602 report for guest operations, report the error to the guest; for jobs,
2603 cancel the job
2604 ignore ignore the error, only report a QMP event (BLOCK_IO_ERROR or
2606 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
2607 the failing request later and may still complete successfully.
2608 The stream block job continues to stream and will complete with
2609 an error.
2610 enospc same as stop on ENOSPC, same as report otherwise.
2612 stop for guest operations, stop the virtual machine; for jobs, pause
2614 the job
2615 auto inherit the error handling policy of the backend (since: 2.7)
2617 Since
2619 1.3
2620 MirrorSyncMode (Enum)
2622 An enumeration of possible behaviors for the initial synchronization
2623 phase of storage mirroring.
2624 Values
2626 top copies data in the topmost image to the destination
2627 full copies data from all images to the destination
2629 none only copy data written from now on
2631 incremental
2633 only copy data described by the dirty bitmap. (since: 2.4)
2634 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
2636 havior on completion is determined by the BitmapSyncMode.
2637 Since
2639 1.3
2640 BitmapSyncMode (Enum)
2642 An enumeration of possible behaviors for the synchronization of a bit‐
2643 map when used for data copy operations.
2644 Values
2646 on-success
2647 The bitmap is only synced when the operation is successful.
2648 This is the behavior always used for 'INCREMENTAL' backups.
2649 never The bitmap is never synchronized with the operation, and is
2651 treated solely as a read-only manifest of blocks to copy.
2652 always The bitmap is always synchronized with the operation, regardless
2654 of whether or not the operation was successful.
2655 Since
2657 4.2
2658 MirrorCopyMode (Enum)
2660 An enumeration whose values tell the mirror block job when to trigger
2661 writes to the target.
2662 Values
2664 background
2665 copy data in background only.
2666 write-blocking
2668 when data is written to the source, write it (synchronously) to
2669 the target as well. In addition, data is copied in background
2670 just like in background mode.
2671 Since
2673 3.0
2674 BlockJobInfo (Object)
2676 Information about a long-running block device operation.
2677 Members
2679 type: string
2680 the job type ('stream' for image streaming)
2681 device: string
2683 The job identifier. Originally the device name but other values
2684 are allowed since QEMU 2.7
2685 len: int
2687 Estimated offset value at the completion of the job. This value
2688 can arbitrarily change while the job is running, in both direc‐
2689 tions.
2690 offset: int
2692 Progress made until now. The unit is arbitrary and the value can
2693 only meaningfully be used for the ratio of offset to len. The
2694 value is monotonically increasing.
2695 busy: boolean
2697 false if the job is known to be in a quiescent state, with no
2698 pending I/O. Since 1.3.
2699 paused: boolean
2701 whether the job is paused or, if busy is true, will pause itself
2702 as soon as possible. Since 1.3.
2703 speed: int
2705 the rate limit, bytes per second
2706 io-status: BlockDeviceIoStatus
2708 the status of the job (since 1.3)
2709 ready: boolean
2711 true if the job may be completed (since 2.2)
2712 status: JobStatus
2714 Current job state/status (since 2.12)
2715 auto-finalize: boolean
2717 Job will finalize itself when PENDING, moving to the CONCLUDED
2718 state. (since 2.12)
2719 auto-dismiss: boolean
2721 Job will dismiss itself when CONCLUDED, moving to the NULL state
2722 and disappearing from the query list. (since 2.12)
2723 error: string (optional)
2725 Error information if the job did not complete successfully. Not
2726 set if the job completed successfully. (since 2.12.1)
2727 Since
2729 1.1
2730 query-block-jobs (Command)
2732 Return information about long-running block device operations.
2733 Returns
2735 a list of BlockJobInfo for each active block job
2736 Since
2738 1.1
2739 block_passwd (Command)
2741 This command sets the password of a block device that has not been open
2742 with a password and requires one.
2743 This command is now obsolete and will always return an error since 2.10
2745 Arguments
2747 device: string (optional)
2748 Not documented
2749 node-name: string (optional)
2751 Not documented
2752 password: string
2754 Not documented
2755 block_resize (Command)
2757 Resize a block image while a guest is running.
2758 Either device or node-name must be set but not both.
2760 Arguments
2762 device: string (optional)
2763 the name of the device to get the image resized
2764 node-name: string (optional)
2766 graph node name to get the image resized (Since 2.0)
2767 size: int
2769 new image size in bytes
2770 Returns
2772 • nothing on success
2773 • If device is not a valid block device, DeviceNotFound
2775 Since
2777 0.14.0
2778 Example
2780 -> { "execute": "block_resize",
2781 "arguments": { "device": "scratch", "size": 1073741824 } }
2782 <- { "return": {} }
2783 NewImageMode (Enum)
2785 An enumeration that tells QEMU how to set the backing file path in a
2786 new image file.
2787 Values
2789 existing
2790 QEMU should look for an existing image file.
2791 absolute-paths
2793 QEMU should create a new image with absolute paths for the back‐
2794 ing file. If there is no backing file available, the new image
2795 will not be backed either.
2796 Since
2798 1.1
2799 BlockdevSnapshotSync (Object)
2801 Either device or node-name must be set but not both.
2802 Members
2804 device: string (optional)
2805 the name of the device to take a snapshot of.
2806 node-name: string (optional)
2808 graph node name to generate the snapshot from (Since 2.0)
2809 snapshot-file: string
2811 the target of the new overlay image. If the file exists, or if
2812 it is a device, the overlay will be created in the existing
2813 file/device. Otherwise, a new file will be created.
2814 snapshot-node-name: string (optional)
2816 the graph node name of the new image (Since 2.0)
2817 format: string (optional)
2819 the format of the overlay image, default is 'qcow2'.
2820 mode: NewImageMode (optional)
2822 whether and how QEMU should create a new image, default is 'ab‐
2823 solute-paths'.
2824 BlockdevSnapshot (Object)
2826 Members
2827 node: string
2828 device or node name that will have a snapshot taken.
2829 overlay: string
2831 reference to the existing block device that will become the
2832 overlay of node, as part of taking the snapshot. It must not
2833 have a current backing file (this can be achieved by passing
2834 "backing": null to blockdev-add).
2835 Since
2837 2.5
2838 BackupCommon (Object)
2840 Members
2841 job-id: string (optional)
2842 identifier for the newly-created block job. If omitted, the de‐
2843 vice name will be used. (Since 2.7)
2844 device: string
2846 the device name or node-name of a root node which should be
2847 copied.
2848 sync: MirrorSyncMode
2850 what parts of the disk image should be copied to the destination
2851 (all the disk, only the sectors allocated in the topmost image,
2852 from a dirty bitmap, or only new I/O).
2853 speed: int (optional)
2855 the maximum speed, in bytes per second. The default is 0, for
2856 unlimited.
2857 bitmap: string (optional)
2859 The name of a dirty bitmap to use. Must be present if sync is
2860 "bitmap" or "incremental". Can be present if sync is "full" or
2861 "top". Must not be present otherwise. (Since 2.4
2862 (drive-backup), 3.1 (blockdev-backup))
2863 bitmap-mode: BitmapSyncMode (optional)
2865 Specifies the type of data the bitmap should contain after the
2866 operation concludes. Must be present if a bitmap was provided,
2867 Must NOT be present otherwise. (Since 4.2)
2868 compress: boolean (optional)
2870 true to compress data, if the target format supports it. (de‐
2871 fault: false) (since 2.8)
2872 on-source-error: BlockdevOnError (optional)
2874 the action to take on an error on the source, default 'report'.
2875 'stop' and 'enospc' can only be used if the block device sup‐
2876 ports io-status (see BlockInfo).
2877 on-target-error: BlockdevOnError (optional)
2879 the action to take on an error on the target, default 'report'
2880 (no limitations, since this applies to a different block device
2881 than device).
2882 auto-finalize: boolean (optional)
2884 When false, this job will wait in a PENDING state after it has
2885 finished its work, waiting for block-job-finalize before making
2886 any block graph changes. When true, this job will automatically
2887 perform its abort or commit actions. Defaults to true. (Since
2888 2.12)
2889 auto-dismiss: boolean (optional)
2891 When false, this job will wait in a CONCLUDED state after it has
2892 completely ceased all work, and awaits block-job-dismiss. When
2893 true, this job will automatically disappear from the query list
2894 without user intervention. Defaults to true. (Since 2.12)
2895 filter-node-name: string (optional)
2897 the node name that should be assigned to the filter driver that
2898 the backup job inserts into the graph above node specified by
2899 drive. If this option is not given, a node name is autogener‐
2900 ated. (Since: 4.2)
2901 Note
2903 on-source-error and on-target-error only affect background I/O. If an
2904 error occurs during a guest write request, the device's rerror/werror
2905 actions will be used.
2906 Since
2908 4.2
2909 DriveBackup (Object)
2911 Members
2912 target: string
2913 the target of the new image. If the file exists, or if it is a
2914 device, the existing file/device will be used as the new desti‐
2915 nation. If it does not exist, a new file will be created.
2916 format: string (optional)
2918 the format of the new destination, default is to probe if mode
2919 is 'existing', else the format of the source
2920 mode: NewImageMode (optional)
2922 whether and how QEMU should create a new image, default is 'ab‐
2923 solute-paths'.
2924 The members of BackupCommon
2926 Since
2928 1.6
2929 BlockdevBackup (Object)
2931 Members
2932 target: string
2933 the device name or node-name of the backup target node.
2934 The members of BackupCommon
2936 Since
2938 2.3
2939 blockdev-snapshot-sync (Command)
2941 Takes a synchronous snapshot of a block device.
2942 For the arguments, see the documentation of BlockdevSnapshotSync.
2944 Returns
2946 • nothing on success
2947 • If device is not a valid block device, DeviceNotFound
2949 Since
2951 0.14.0
2952 Example
2954 -> { "execute": "blockdev-snapshot-sync",
2955 "arguments": { "device": "ide-hd0",
2956 "snapshot-file":
2957 "/some/place/my-image",
2958 "format": "qcow2" } }
2959 <- { "return": {} }
2960 blockdev-snapshot (Command)
2962 Takes a snapshot of a block device.
2963 Take a snapshot, by installing 'node' as the backing image of 'over‐
2965 lay'. Additionally, if 'node' is associated with a block device, the
2966 block device changes to using 'overlay' as its new active image.
2967 For the arguments, see the documentation of BlockdevSnapshot.
2969 Features
2971 allow-write-only-overlay
2972 If present, the check whether this operation is safe was relaxed
2973 so that it can be used to change backing file of a destination
2974 of a blockdev-mirror. (since 5.0)
2975 Since
2977 2.5
2978 Example
2980 -> { "execute": "blockdev-add",
2981 "arguments": { "driver": "qcow2",
2982 "node-name": "node1534",
2983 "file": { "driver": "file",
2984 "filename": "hd1.qcow2" },
2985 "backing": null } }
2986 <- { "return": {} }
2988 -> { "execute": "blockdev-snapshot",
2990 "arguments": { "node": "ide-hd0",
2991 "overlay": "node1534" } }
2992 <- { "return": {} }
2993 change-backing-file (Command)
2995 Change the backing file in the image file metadata. This does not
2996 cause QEMU to reopen the image file to reparse the backing filename (it
2997 may, however, perform a reopen to change permissions from r/o -> r/w ->
2998 r/o, if needed). The new backing file string is written into the image
2999 file metadata, and the QEMU internal strings are updated.
3000 Arguments
3002 image-node-name: string
3003 The name of the block driver state node of the image to modify.
3004 The "device" argument is used to verify "image-node-name" is in
3005 the chain described by "device".
3006 device: string
3008 The device name or node-name of the root node that owns im‐
3009 age-node-name.
3010 backing-file: string
3012 The string to write as the backing file. This string is not
3013 validated, so care should be taken when specifying the string or
3014 the image chain may not be able to be reopened again.
3015 Returns
3017 • Nothing on success
3018 • If "device" does not exist or cannot be determined, DeviceNotFound
3020 Since
3022 2.1
3023 block-commit (Command)
3025 Live commit of data from overlay image nodes into backing nodes - i.e.,
3026 writes data between 'top' and 'base' into 'base'.
3027 If top == base, that is an error. If top has no overlays on top of it,
3029 or if it is in use by a writer, the job will not be completed by it‐
3030 self. The user needs to complete the job with the block-job-complete
3031 command after getting the ready event. (Since 2.0)
3032 If the base image is smaller than top, then the base image will be re‐
3034 sized to be the same size as top. If top is smaller than the base im‐
3035 age, the base will not be truncated. If you want the base image size
3036 to match the size of the smaller top, you can safely truncate it your‐
3037 self once the commit operation successfully completes.
3038 Arguments
3040 job-id: string (optional)
3041 identifier for the newly-created block job. If omitted, the de‐
3042 vice name will be used. (Since 2.7)
3043 device: string
3045 the device name or node-name of a root node
3046 base-node: string (optional)
3048 The node name of the backing image to write data into. If not
3049 specified, this is the deepest backing image. (since: 3.1)
3050 base: string (optional)
3052 Same as base-node, except that it is a file name rather than a
3053 node name. This must be the exact filename string that was used
3054 to open the node; other strings, even if addressing the same
3055 file, are not accepted
3056 top-node: string (optional)
3058 The node name of the backing image within the image chain which
3059 contains the topmost data to be committed down. If not speci‐
3060 fied, this is the active layer. (since: 3.1)
3061 top: string (optional)
3063 Same as top-node, except that it is a file name rather than a
3064 node name. This must be the exact filename string that was used
3065 to open the node; other strings, even if addressing the same
3066 file, are not accepted
3067 backing-file: string (optional)
3069 The backing file string to write into the overlay image of
3070 'top'. If 'top' does not have an overlay image, or if 'top' is
3071 in use by a writer, specifying a backing file string is an er‐
3072 ror.
3073 This filename is not validated. If a pathname string is such
3075 that it cannot be resolved by QEMU, that means that subsequent
3076 QMP or HMP commands must use node-names for the image in ques‐
3077 tion, as filename lookup methods will fail.
3078 If not specified, QEMU will automatically determine the backing
3080 file string to use, or error out if there is no obvious choice.
3081 Care should be taken when specifying the string, to specify a
3082 valid filename or protocol. (Since 2.1)
3083 speed: int (optional)
3085 the maximum speed, in bytes per second
3086 on-error: BlockdevOnError (optional)
3088 the action to take on an error. 'ignore' means that the request
3089 should be retried. (default: report; Since: 5.0)
3090 filter-node-name: string (optional)
3092 the node name that should be assigned to the filter driver that
3093 the commit job inserts into the graph above top. If this option
3094 is not given, a node name is autogenerated. (Since: 2.9)
3095 auto-finalize: boolean (optional)
3097 When false, this job will wait in a PENDING state after it has
3098 finished its work, waiting for block-job-finalize before making
3099 any block graph changes. When true, this job will automatically
3100 perform its abort or commit actions. Defaults to true. (Since
3101 3.1)
3102 auto-dismiss: boolean (optional)
3104 When false, this job will wait in a CONCLUDED state after it has
3105 completely ceased all work, and awaits block-job-dismiss. When
3106 true, this job will automatically disappear from the query list
3107 without user intervention. Defaults to true. (Since 3.1)
3108 Features
3110 deprecated
3111 Members base and top are deprecated. Use base-node and top-node
3112 instead.
3113 Returns
3115 • Nothing on success
3116 • If device does not exist, DeviceNotFound
3118 • Any other error returns a GenericError.
3120 Since
3122 1.3
3123 Example
3125 -> { "execute": "block-commit",
3126 "arguments": { "device": "virtio0",
3127 "top": "/tmp/snap1.qcow2" } }
3128 <- { "return": {} }
3129 drive-backup (Command)
3131 Start a point-in-time copy of a block device to a new destination. The
3132 status of ongoing drive-backup operations can be checked with
3133 query-block-jobs where the BlockJobInfo.type field has the value
3134 'backup'. The operation can be stopped before it has completed using
3135 the block-job-cancel command.
3136 Arguments
3138 The members of DriveBackup
3139 Returns
3141 • nothing on success
3142 • If device is not a valid block device, GenericError
3144 Since
3146 1.6
3147 Example
3149 -> { "execute": "drive-backup",
3150 "arguments": { "device": "drive0",
3151 "sync": "full",
3152 "target": "backup.img" } }
3153 <- { "return": {} }
3154 blockdev-backup (Command)
3156 Start a point-in-time copy of a block device to a new destination. The
3157 status of ongoing blockdev-backup operations can be checked with
3158 query-block-jobs where the BlockJobInfo.type field has the value
3159 'backup'. The operation can be stopped before it has completed using
3160 the block-job-cancel command.
3161 Arguments
3163 The members of BlockdevBackup
3164 Returns
3166 • nothing on success
3167 • If device is not a valid block device, DeviceNotFound
3169 Since
3171 2.3
3172 Example
3174 -> { "execute": "blockdev-backup",
3175 "arguments": { "device": "src-id",
3176 "sync": "full",
3177 "target": "tgt-id" } }
3178 <- { "return": {} }
3179 query-named-block-nodes (Command)
3181 Get the named block driver list
3182 Arguments
3184 flat: boolean (optional)
3185 Omit the nested data about backing image ("backing-image" key)
3186 if true. Default is false (Since 5.0)
3187 Returns
3189 the list of BlockDeviceInfo
3190 Since
3192 2.0
3193 Example
3195 -> { "execute": "query-named-block-nodes" }
3196 <- { "return": [ { "ro":false,
3197 "drv":"qcow2",
3198 "encrypted":false,
3199 "file":"disks/test.qcow2",
3200 "node-name": "my-node",
3201 "backing_file_depth":1,
3202 "bps":1000000,
3203 "bps_rd":0,
3204 "bps_wr":0,
3205 "iops":1000000,
3206 "iops_rd":0,
3207 "iops_wr":0,
3208 "bps_max": 8000000,
3209 "bps_rd_max": 0,
3210 "bps_wr_max": 0,
3211 "iops_max": 0,
3212 "iops_rd_max": 0,
3213 "iops_wr_max": 0,
3214 "iops_size": 0,
3215 "write_threshold": 0,
3216 "image":{
3217 "filename":"disks/test.qcow2",
3218 "format":"qcow2",
3219 "virtual-size":2048000,
3220 "backing_file":"base.qcow2",
3221 "full-backing-filename":"disks/base.qcow2",
3222 "backing-filename-format":"qcow2",
3223 "snapshots":[
3224 {
3225 "id": "1",
3226 "name": "snapshot1",
3227 "vm-state-size": 0,
3228 "date-sec": 10000200,
3229 "date-nsec": 12,
3230 "vm-clock-sec": 206,
3231 "vm-clock-nsec": 30
3232 }
3233 ],
3234 "backing-image":{
3235 "filename":"disks/base.qcow2",
3236 "format":"qcow2",
3237 "virtual-size":2048000
3238 }
3239 } } ] }
3240 XDbgBlockGraphNodeType (Enum)
3242 Values
3243 block-backend
3244 corresponds to BlockBackend
3245 block-job
3247 corresponds to BlockJob
3248 block-driver
3250 corresponds to BlockDriverState
3251 Since
3253 4.0
3254 XDbgBlockGraphNode (Object)
3256 Members
3257 id: int
3258 Block graph node identifier. This id is generated only for x-de‐
3259 bug-query-block-graph and does not relate to any other identi‐
3260 fiers in Qemu.
3261 type: XDbgBlockGraphNodeType
3263 Type of graph node. Can be one of block-backend, block-job or
3264 block-driver-state.
3265 name: string
3267 Human readable name of the node. Corresponds to node-name for
3268 block-driver-state nodes; is not guaranteed to be unique in the
3269 whole graph (with block-jobs and block-backends).
3270 Since
3272 4.0
3273 BlockPermission (Enum)
3275 Enum of base block permissions.
3276 Values
3278 consistent-read
3279 A user that has the "permission" of consistent reads is guaran‐
3280 teed that their view of the contents of the block device is com‐
3281 plete and self-consistent, representing the contents of a disk
3282 at a specific point. For most block devices (including their
3283 backing files) this is true, but the property cannot be main‐
3284 tained in a few situations like for intermediate nodes of a com‐
3285 mit block job.
3286 write This permission is required to change the visible disk contents.
3288 write-unchanged
3290 This permission (which is weaker than BLK_PERM_WRITE) is both
3291 enough and required for writes to the block node when the caller
3292 promises that the visible disk content doesn't change. As the
3293 BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
3294 cient to perform an unchanging write.
3295 resize This permission is required to change the size of a block node.
3297 graph-mod
3299 This permission is required to change the node that this
3300 BdrvChild points to.
3301 Since
3303 4.0
3304 XDbgBlockGraphEdge (Object)
3306 Block Graph edge description for x-debug-query-block-graph.
3307 Members
3309 parent: int
3310 parent id
3311 child: int
3313 child id
3314 name: string
3316 name of the relation (examples are 'file' and 'backing')
3317 perm: array of BlockPermission
3319 granted permissions for the parent operating on the child
3320 shared-perm: array of BlockPermission
3322 permissions that can still be granted to other users of the
3323 child while it is still attached to this parent
3324 Since
3326 4.0
3327 XDbgBlockGraph (Object)
3329 Block Graph - list of nodes and list of edges.
3330 Members
3332 nodes: array of XDbgBlockGraphNode
3333 Not documented
3334 edges: array of XDbgBlockGraphEdge
3336 Not documented
3337 Since
3339 4.0
3340 x-debug-query-block-graph (Command)
3342 Get the block graph.
3343 Since
3345 4.0
3346 drive-mirror (Command)
3348 Start mirroring a block device's writes to a new destination. target
3349 specifies the target of the new image. If the file exists, or if it is
3350 a device, it will be used as the new destination for writes. If it does
3351 not exist, a new file will be created. format specifies the format of
3352 the mirror image, default is to probe if mode='existing', else the for‐
3353 mat of the source.
3354 Arguments
3356 The members of DriveMirror
3357 Returns
3359 • nothing on success
3360 • If device is not a valid block device, GenericError
3362 Since
3364 1.3
3365 Example
3367 -> { "execute": "drive-mirror",
3368 "arguments": { "device": "ide-hd0",
3369 "target": "/some/place/my-image",
3370 "sync": "full",
3371 "format": "qcow2" } }
3372 <- { "return": {} }
3373 DriveMirror (Object)
3375 A set of parameters describing drive mirror setup.
3376 Members
3378 job-id: string (optional)
3379 identifier for the newly-created block job. If omitted, the de‐
3380 vice name will be used. (Since 2.7)
3381 device: string
3383 the device name or node-name of a root node whose writes should
3384 be mirrored.
3385 target: string
3387 the target of the new image. If the file exists, or if it is a
3388 device, the existing file/device will be used as the new desti‐
3389 nation. If it does not exist, a new file will be created.
3390 format: string (optional)
3392 the format of the new destination, default is to probe if mode
3393 is 'existing', else the format of the source
3394 node-name: string (optional)
3396 the new block driver state node name in the graph (Since 2.1)
3397 replaces: string (optional)
3399 with sync=full graph node name to be replaced by the new image
3400 when a whole image copy is done. This can be used to repair bro‐
3401 ken Quorum files. By default, device is replaced, although im‐
3402 plicitly created filters on it are kept. (Since 2.1)
3403 mode: NewImageMode (optional)
3405 whether and how QEMU should create a new image, default is 'ab‐
3406 solute-paths'.
3407 speed: int (optional)
3409 the maximum speed, in bytes per second
3410 sync: MirrorSyncMode
3412 what parts of the disk image should be copied to the destination
3413 (all the disk, only the sectors allocated in the topmost image,
3414 or only new I/O).
3415 granularity: int (optional)
3417 granularity of the dirty bitmap, default is 64K if the image
3418 format doesn't have clusters, 4K if the clusters are smaller
3419 than that, else the cluster size. Must be a power of 2 between
3420 512 and 64M (since 1.4).
3421 buf-size: int (optional)
3423 maximum amount of data in flight from source to target (since
3424 1.4).
3425 on-source-error: BlockdevOnError (optional)
3427 the action to take on an error on the source, default 'report'.
3428 'stop' and 'enospc' can only be used if the block device sup‐
3429 ports io-status (see BlockInfo).
3430 on-target-error: BlockdevOnError (optional)
3432 the action to take on an error on the target, default 'report'
3433 (no limitations, since this applies to a different block device
3434 than device).
3435 unmap: boolean (optional)
3437 Whether to try to unmap target sectors where source has only
3438 zero. If true, and target unallocated sectors will read as zero,
3439 target image sectors will be unmapped; otherwise, zeroes will be
3440 written. Both will result in identical contents. Default is
3441 true. (Since 2.4)
3442 copy-mode: MirrorCopyMode (optional)
3444 when to copy data to the destination; defaults to 'background'
3445 (Since: 3.0)
3446 auto-finalize: boolean (optional)
3448 When false, this job will wait in a PENDING state after it has
3449 finished its work, waiting for block-job-finalize before making
3450 any block graph changes. When true, this job will automatically
3451 perform its abort or commit actions. Defaults to true. (Since
3452 3.1)
3453 auto-dismiss: boolean (optional)
3455 When false, this job will wait in a CONCLUDED state after it has
3456 completely ceased all work, and awaits block-job-dismiss. When
3457 true, this job will automatically disappear from the query list
3458 without user intervention. Defaults to true. (Since 3.1)
3459 Since
3461 1.3
3462 BlockDirtyBitmap (Object)
3464 Members
3465 node: string
3466 name of device/node which the bitmap is tracking
3467 name: string
3469 name of the dirty bitmap
3470 Since
3472 2.4
3473 BlockDirtyBitmapAdd (Object)
3475 Members
3476 node: string
3477 name of device/node which the bitmap is tracking
3478 name: string
3480 name of the dirty bitmap (must be less than 1024 bytes)
3481 granularity: int (optional)
3483 the bitmap granularity, default is 64k for block-dirty-bit‐
3484 map-add
3485 persistent: boolean (optional)
3487 the bitmap is persistent, i.e. it will be saved to the corre‐
3488 sponding block device image file on its close. For now only
3489 Qcow2 disks support persistent bitmaps. Default is false for
3490 block-dirty-bitmap-add. (Since: 2.10)
3491 disabled: boolean (optional)
3493 the bitmap is created in the disabled state, which means that it
3494 will not track drive changes. The bitmap may be enabled with
3495 block-dirty-bitmap-enable. Default is false. (Since: 4.0)
3496 Since
3498 2.4
3499 BlockDirtyBitmapMergeSource (Alternate)
3501 Members
3502 local: string
3503 name of the bitmap, attached to the same node as target bitmap.
3504 external: BlockDirtyBitmap
3506 bitmap with specified node
3507 Since
3509 4.1
3510 BlockDirtyBitmapMerge (Object)
3512 Members
3513 node: string
3514 name of device/node which the target bitmap is tracking
3515 target: string
3517 name of the destination dirty bitmap
3518 bitmaps: array of BlockDirtyBitmapMergeSource
3520 name(s) of the source dirty bitmap(s) at node and/or fully spec‐
3521 ified BlockDirtyBitmap elements. The latter are supported since
3522 4.1.
3523 Since
3525 4.0
3526 block-dirty-bitmap-add (Command)
3528 Create a dirty bitmap with a name on the node, and start tracking the
3529 writes.
3530 Returns
3532 • nothing on success
3533 • If node is not a valid block device or node, DeviceNotFound
3535 • If name is already taken, GenericError with an explanation
3537 Since
3539 2.4
3540 Example
3542 -> { "execute": "block-dirty-bitmap-add",
3543 "arguments": { "node": "drive0", "name": "bitmap0" } }
3544 <- { "return": {} }
3545 block-dirty-bitmap-remove (Command)
3547 Stop write tracking and remove the dirty bitmap that was created with
3548 block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
3549 storage too.
3550 Returns
3552 • nothing on success
3553 • If node is not a valid block device or node, DeviceNotFound
3555 • If name is not found, GenericError with an explanation
3557 • if name is frozen by an operation, GenericError
3559 Since
3561 2.4
3562 Example
3564 -> { "execute": "block-dirty-bitmap-remove",
3565 "arguments": { "node": "drive0", "name": "bitmap0" } }
3566 <- { "return": {} }
3567 block-dirty-bitmap-clear (Command)
3569 Clear (reset) a dirty bitmap on the device, so that an incremental
3570 backup from this point in time forward will only backup clusters modi‐
3571 fied after this clear operation.
3572 Returns
3574 • nothing on success
3575 • If node is not a valid block device, DeviceNotFound
3577 • If name is not found, GenericError with an explanation
3579 Since
3581 2.4
3582 Example
3584 -> { "execute": "block-dirty-bitmap-clear",
3585 "arguments": { "node": "drive0", "name": "bitmap0" } }
3586 <- { "return": {} }
3587 block-dirty-bitmap-enable (Command)
3589 Enables a dirty bitmap so that it will begin tracking disk changes.
3590 Returns
3592 • nothing on success
3593 • If node is not a valid block device, DeviceNotFound
3595 • If name is not found, GenericError with an explanation
3597 Since
3599 4.0
3600 Example
3602 -> { "execute": "block-dirty-bitmap-enable",
3603 "arguments": { "node": "drive0", "name": "bitmap0" } }
3604 <- { "return": {} }
3605 block-dirty-bitmap-disable (Command)
3607 Disables a dirty bitmap so that it will stop tracking disk changes.
3608 Returns
3610 • nothing on success
3611 • If node is not a valid block device, DeviceNotFound
3613 • If name is not found, GenericError with an explanation
3615 Since
3617 4.0
3618 Example
3620 -> { "execute": "block-dirty-bitmap-disable",
3621 "arguments": { "node": "drive0", "name": "bitmap0" } }
3622 <- { "return": {} }
3623 block-dirty-bitmap-merge (Command)
3625 Merge dirty bitmaps listed in bitmaps to the target dirty bitmap.
3626 Dirty bitmaps in bitmaps will be unchanged, except if it also appears
3627 as the target bitmap. Any bits already set in target will still be set
3628 after the merge, i.e., this operation does not clear the target. On
3629 error, target is unchanged.
3630 The resulting bitmap will count as dirty any clusters that were dirty
3632 in any of the source bitmaps. This can be used to achieve backup check‐
3633 points, or in simpler usages, to copy bitmaps.
3634 Returns
3636 • nothing on success
3637 • If node is not a valid block device, DeviceNotFound
3639 • If any bitmap in bitmaps or target is not found, GenericError
3641 • If any of the bitmaps have different sizes or granularities, Gener‐
3643 icError
3644 Since
3646 4.0
3647 Example
3649 -> { "execute": "block-dirty-bitmap-merge",
3650 "arguments": { "node": "drive0", "target": "bitmap0",
3651 "bitmaps": ["bitmap1"] } }
3652 <- { "return": {} }
3653 BlockDirtyBitmapSha256 (Object)
3655 SHA256 hash of dirty bitmap data
3656 Members
3658 sha256: string
3659 ASCII representation of SHA256 bitmap hash
3660 Since
3662 2.10
3663 x-debug-block-dirty-bitmap-sha256 (Command)
3665 Get bitmap SHA256.
3666 Returns
3668 • BlockDirtyBitmapSha256 on success
3669 • If node is not a valid block device, DeviceNotFound
3671 • If name is not found or if hashing has failed, GenericError with an
3673 explanation
3674 Since
3676 2.10
3677 blockdev-mirror (Command)
3679 Start mirroring a block device's writes to a new destination.
3680 Arguments
3682 job-id: string (optional)
3683 identifier for the newly-created block job. If omitted, the de‐
3684 vice name will be used. (Since 2.7)
3685 device: string
3687 The device name or node-name of a root node whose writes should
3688 be mirrored.
3689 target: string
3691 the id or node-name of the block device to mirror to. This
3692 mustn't be attached to guest.
3693 replaces: string (optional)
3695 with sync=full graph node name to be replaced by the new image
3696 when a whole image copy is done. This can be used to repair bro‐
3697 ken Quorum files. By default, device is replaced, although im‐
3698 plicitly created filters on it are kept.
3699 speed: int (optional)
3701 the maximum speed, in bytes per second
3702 sync: MirrorSyncMode
3704 what parts of the disk image should be copied to the destination
3705 (all the disk, only the sectors allocated in the topmost image,
3706 or only new I/O).
3707 granularity: int (optional)
3709 granularity of the dirty bitmap, default is 64K if the image
3710 format doesn't have clusters, 4K if the clusters are smaller
3711 than that, else the cluster size. Must be a power of 2 between
3712 512 and 64M
3713 buf-size: int (optional)
3715 maximum amount of data in flight from source to target
3716 on-source-error: BlockdevOnError (optional)
3718 the action to take on an error on the source, default 'report'.
3719 'stop' and 'enospc' can only be used if the block device sup‐
3720 ports io-status (see BlockInfo).
3721 on-target-error: BlockdevOnError (optional)
3723 the action to take on an error on the target, default 'report'
3724 (no limitations, since this applies to a different block device
3725 than device).
3726 filter-node-name: string (optional)
3728 the node name that should be assigned to the filter driver that
3729 the mirror job inserts into the graph above device. If this op‐
3730 tion is not given, a node name is autogenerated. (Since: 2.9)
3731 copy-mode: MirrorCopyMode (optional)
3733 when to copy data to the destination; defaults to 'background'
3734 (Since: 3.0)
3735 auto-finalize: boolean (optional)
3737 When false, this job will wait in a PENDING state after it has
3738 finished its work, waiting for block-job-finalize before making
3739 any block graph changes. When true, this job will automatically
3740 perform its abort or commit actions. Defaults to true. (Since
3741 3.1)
3742 auto-dismiss: boolean (optional)
3744 When false, this job will wait in a CONCLUDED state after it has
3745 completely ceased all work, and awaits block-job-dismiss. When
3746 true, this job will automatically disappear from the query list
3747 without user intervention. Defaults to true. (Since 3.1)
3748 Returns
3750 nothing on success.
3751 Since
3753 2.6
3754 Example
3756 -> { "execute": "blockdev-mirror",
3757 "arguments": { "device": "ide-hd0",
3758 "target": "target0",
3759 "sync": "full" } }
3760 <- { "return": {} }
3761 BlockIOThrottle (Object)
3763 A set of parameters describing block throttling.
3764 Members
3766 device: string (optional)
3767 Block device name
3768 id: string (optional)
3770 The name or QOM path of the guest device (since: 2.8)
3771 bps: int
3773 total throughput limit in bytes per second
3774 bps_rd: int
3776 read throughput limit in bytes per second
3777 bps_wr: int
3779 write throughput limit in bytes per second
3780 iops: int
3782 total I/O operations per second
3783 iops_rd: int
3785 read I/O operations per second
3786 iops_wr: int
3788 write I/O operations per second
3789 bps_max: int (optional)
3791 total throughput limit during bursts, in bytes (Since 1.7)
3792 bps_rd_max: int (optional)
3794 read throughput limit during bursts, in bytes (Since 1.7)
3795 bps_wr_max: int (optional)
3797 write throughput limit during bursts, in bytes (Since 1.7)
3798 iops_max: int (optional)
3800 total I/O operations per second during bursts, in bytes (Since
3801 1.7)
3802 iops_rd_max: int (optional)
3804 read I/O operations per second during bursts, in bytes (Since
3805 1.7)
3806 iops_wr_max: int (optional)
3808 write I/O operations per second during bursts, in bytes (Since
3809 1.7)
3810 bps_max_length: int (optional)
3812 maximum length of the bps_max burst period, in seconds. It must
3813 only be set if bps_max is set as well. Defaults to 1. (Since
3814 2.6)
3815 bps_rd_max_length: int (optional)
3817 maximum length of the bps_rd_max burst period, in seconds. It
3818 must only be set if bps_rd_max is set as well. Defaults to 1.
3819 (Since 2.6)
3820 bps_wr_max_length: int (optional)
3822 maximum length of the bps_wr_max burst period, in seconds. It
3823 must only be set if bps_wr_max is set as well. Defaults to 1.
3824 (Since 2.6)
3825 iops_max_length: int (optional)
3827 maximum length of the iops burst period, in seconds. It must
3828 only be set if iops_max is set as well. Defaults to 1. (Since
3829 2.6)
3830 iops_rd_max_length: int (optional)
3832 maximum length of the iops_rd_max burst period, in seconds. It
3833 must only be set if iops_rd_max is set as well. Defaults to 1.
3834 (Since 2.6)
3835 iops_wr_max_length: int (optional)
3837 maximum length of the iops_wr_max burst period, in seconds. It
3838 must only be set if iops_wr_max is set as well. Defaults to 1.
3839 (Since 2.6)
3840 iops_size: int (optional)
3842 an I/O size in bytes (Since 1.7)
3843 group: string (optional)
3845 throttle group name (Since 2.4)
3846 Features
3848 deprecated
3849 Member device is deprecated. Use id instead.
3850 Since
3852 1.1
3853 ThrottleLimits (Object)
3855 Limit parameters for throttling. Since some limit combinations are il‐
3856 legal, limits should always be set in one transaction. All fields are
3857 optional. When setting limits, if a field is missing the current value
3858 is not changed.
3859 Members
3861 iops-total: int (optional)
3862 limit total I/O operations per second
3863 iops-total-max: int (optional)
3865 I/O operations burst
3866 iops-total-max-length: int (optional)
3868 length of the iops-total-max burst period, in seconds It must
3869 only be set if iops-total-max is set as well.
3870 iops-read: int (optional)
3872 limit read operations per second
3873 iops-read-max: int (optional)
3875 I/O operations read burst
3876 iops-read-max-length: int (optional)
3878 length of the iops-read-max burst period, in seconds It must
3879 only be set if iops-read-max is set as well.
3880 iops-write: int (optional)
3882 limit write operations per second
3883 iops-write-max: int (optional)
3885 I/O operations write burst
3886 iops-write-max-length: int (optional)
3888 length of the iops-write-max burst period, in seconds It must
3889 only be set if iops-write-max is set as well.
3890 bps-total: int (optional)
3892 limit total bytes per second
3893 bps-total-max: int (optional)
3895 total bytes burst
3896 bps-total-max-length: int (optional)
3898 length of the bps-total-max burst period, in seconds. It must
3899 only be set if bps-total-max is set as well.
3900 bps-read: int (optional)
3902 limit read bytes per second
3903 bps-read-max: int (optional)
3905 total bytes read burst
3906 bps-read-max-length: int (optional)
3908 length of the bps-read-max burst period, in seconds It must only
3909 be set if bps-read-max is set as well.
3910 bps-write: int (optional)
3912 limit write bytes per second
3913 bps-write-max: int (optional)
3915 total bytes write burst
3916 bps-write-max-length: int (optional)
3918 length of the bps-write-max burst period, in seconds It must
3919 only be set if bps-write-max is set as well.
3920 iops-size: int (optional)
3922 when limiting by iops max size of an I/O in bytes
3923 Since
3925 2.11
3926 block-stream (Command)
3928 Copy data from a backing file into a block device.
3929 The block streaming operation is performed in the background until the
3931 entire backing file has been copied. This command returns immediately
3932 once streaming has started. The status of ongoing block streaming op‐
3933 erations can be checked with query-block-jobs. The operation can be
3934 stopped before it has completed using the block-job-cancel command.
3935 The node that receives the data is called the top image, can be located
3937 in any part of the chain (but always above the base image; see below)
3938 and can be specified using its device or node name. Earlier qemu ver‐
3939 sions only allowed 'device' to name the top level node; presence of the
3940 'base-node' parameter during introspection can be used as a witness of
3941 the enhanced semantics of 'device'.
3942 If a base file is specified then sectors are not copied from that base
3944 file and its backing chain. This can be used to stream a subset of the
3945 backing file chain instead of flattening the entire image. When
3946 streaming completes the image file will have the base file as its back‐
3947 ing file, unless that node was changed while the job was running. In
3948 that case, base's parent's backing (or filtered, whichever exists)
3949 child (i.e., base at the beginning of the job) will be the new backing
3950 file.
3951 On successful completion the image file is updated to drop the backing
3953 file and the BLOCK_JOB_COMPLETED event is emitted.
3954 In case device is a filter node, block-stream modifies the first
3956 non-filter overlay node below it to point to the new backing node in‐
3957 stead of modifying device itself.
3958 Arguments
3960 job-id: string (optional)
3961 identifier for the newly-created block job. If omitted, the de‐
3962 vice name will be used. (Since 2.7)
3963 device: string
3965 the device or node name of the top image
3966 base: string (optional)
3968 the common backing file name. It cannot be set if base-node is
3969 also set.
3970 base-node: string (optional)
3972 the node name of the backing file. It cannot be set if base is
3973 also set. (Since 2.8)
3974 backing-file: string (optional)
3976 The backing file string to write into the top image. This file‐
3977 name is not validated.
3978 If a pathname string is such that it cannot be resolved by QEMU,
3980 that means that subsequent QMP or HMP commands must use
3981 node-names for the image in question, as filename lookup methods
3982 will fail.
3983 If not specified, QEMU will automatically determine the backing
3985 file string to use, or error out if there is no obvious choice.
3986 Care should be taken when specifying the string, to specify a
3987 valid filename or protocol. (Since 2.1)
3988 speed: int (optional)
3990 the maximum speed, in bytes per second
3991 on-error: BlockdevOnError (optional)
3993 the action to take on an error (default report). 'stop' and
3994 'enospc' can only be used if the block device supports io-status
3995 (see BlockInfo). Since 1.3.
3996 auto-finalize: boolean (optional)
3998 When false, this job will wait in a PENDING state after it has
3999 finished its work, waiting for block-job-finalize before making
4000 any block graph changes. When true, this job will automatically
4001 perform its abort or commit actions. Defaults to true. (Since
4002 3.1)
4003 auto-dismiss: boolean (optional)
4005 When false, this job will wait in a CONCLUDED state after it has
4006 completely ceased all work, and awaits block-job-dismiss. When
4007 true, this job will automatically disappear from the query list
4008 without user intervention. Defaults to true. (Since 3.1)
4009 Returns
4011 • Nothing on success.
4012 • If device does not exist, DeviceNotFound.
4014 Since
4016 1.1
4017 Example
4019 -> { "execute": "block-stream",
4020 "arguments": { "device": "virtio0",
4021 "base": "/tmp/master.qcow2" } }
4022 <- { "return": {} }
4023 block-job-set-speed (Command)
4025 Set maximum speed for a background block operation.
4026 This command can only be issued when there is an active block job.
4028 Throttling can be disabled by setting the speed to 0.
4030 Arguments
4032 device: string
4033 The job identifier. This used to be a device name (hence the
4034 name of the parameter), but since QEMU 2.7 it can have other
4035 values.
4036 speed: int
4038 the maximum speed, in bytes per second, or 0 for unlimited. De‐
4039 faults to 0.
4040 Returns
4042 • Nothing on success
4043 • If no background operation is active on this device, DeviceNotActive
4045 Since
4047 1.1
4048 block-job-cancel (Command)
4050 Stop an active background block operation.
4051 This command returns immediately after marking the active background
4053 block operation for cancellation. It is an error to call this command
4054 if no operation is in progress.
4055 The operation will cancel as soon as possible and then emit the
4057 BLOCK_JOB_CANCELLED event. Before that happens the job is still visi‐
4058 ble when enumerated using query-block-jobs.
4059 Note that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
4061 dicated (via the event BLOCK_JOB_READY) that the source and destination
4062 are synchronized, then the event triggered by this command changes to
4063 BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
4064 destination now has a point-in-time copy tied to the time of the can‐
4065 cellation.
4066 For streaming, the image file retains its backing file unless the
4068 streaming operation happens to complete just as it is being cancelled.
4069 A new streaming operation can be started at a later time to finish
4070 copying all data from the backing file.
4071 Arguments
4073 device: string
4074 The job identifier. This used to be a device name (hence the
4075 name of the parameter), but since QEMU 2.7 it can have other
4076 values.
4077 force: boolean (optional)
4079 If true, and the job has already emitted the event
4080 BLOCK_JOB_READY, abandon the job immediately (even if it is
4081 paused) instead of waiting for the destination to complete its
4082 final synchronization (since 1.3)
4083 Returns
4085 • Nothing on success
4086 • If no background operation is active on this device, DeviceNotActive
4088 Since
4090 1.1
4091 block-job-pause (Command)
4093 Pause an active background block operation.
4094 This command returns immediately after marking the active background
4096 block operation for pausing. It is an error to call this command if no
4097 operation is in progress or if the job is already paused.
4098 The operation will pause as soon as possible. No event is emitted when
4100 the operation is actually paused. Cancelling a paused job automati‐
4101 cally resumes it.
4102 Arguments
4104 device: string
4105 The job identifier. This used to be a device name (hence the
4106 name of the parameter), but since QEMU 2.7 it can have other
4107 values.
4108 Returns
4110 • Nothing on success
4111 • If no background operation is active on this device, DeviceNotActive
4113 Since
4115 1.3
4116 block-job-resume (Command)
4118 Resume an active background block operation.
4119 This command returns immediately after resuming a paused background
4121 block operation. It is an error to call this command if no operation
4122 is in progress or if the job is not paused.
4123 This command also clears the error status of the job.
4125 Arguments
4127 device: string
4128 The job identifier. This used to be a device name (hence the
4129 name of the parameter), but since QEMU 2.7 it can have other
4130 values.
4131 Returns
4133 • Nothing on success
4134 • If no background operation is active on this device, DeviceNotActive
4136 Since
4138 1.3
4139 block-job-complete (Command)
4141 Manually trigger completion of an active background block operation.
4142 This is supported for drive mirroring, where it also switches the de‐
4143 vice to write to the target path only. The ability to complete is sig‐
4144 naled with a BLOCK_JOB_READY event.
4145 This command completes an active background block operation syn‐
4147 chronously. The ordering of this command's return with the
4148 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
4149 occurs during the processing of this command: 1) the command itself
4150 will fail; 2) the error will be processed according to the rerror/wer‐
4151 ror arguments that were specified when starting the operation.
4152 A cancelled or paused job cannot be completed.
4154 Arguments
4156 device: string
4157 The job identifier. This used to be a device name (hence the
4158 name of the parameter), but since QEMU 2.7 it can have other
4159 values.
4160 Returns
4162 • Nothing on success
4163 • If no background operation is active on this device, DeviceNotActive
4165 Since
4167 1.3
4168 block-job-dismiss (Command)
4170 For jobs that have already concluded, remove them from the
4171 block-job-query list. This command only needs to be run for jobs which
4172 were started with QEMU 2.12+ job lifetime management semantics.
4173 This command will refuse to operate on any job that has not yet reached
4175 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
4176 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
4177 still need to be used as appropriate.
4178 Arguments
4180 id: string
4181 The job identifier.
4182 Returns
4184 Nothing on success
4185 Since
4187 2.12
4188 block-job-finalize (Command)
4190 Once a job that has manual=true reaches the pending state, it can be
4191 instructed to finalize any graph changes and do any necessary cleanup
4192 via this command. For jobs in a transaction, instructing one job to
4193 finalize will force ALL jobs in the transaction to finalize, so it is
4194 only necessary to instruct a single member job to finalize.
4195 Arguments
4197 id: string
4198 The job identifier.
4199 Returns
4201 Nothing on success
4202 Since
4204 2.12
4205 BlockdevDiscardOptions (Enum)
4207 Determines how to handle discard requests.
4208 Values
4210 ignore Ignore the request
4211 unmap Forward as an unmap request
4213 Since
4215 2.9
4216 BlockdevDetectZeroesOptions (Enum)
4218 Describes the operation mode for the automatic conversion of plain zero
4219 writes by the OS to driver specific optimized zero write commands.
4220 Values
4222 off Disabled (default)
4223 on Enabled
4225 unmap Enabled and even try to unmap blocks if possible. This requires
4227 also that BlockdevDiscardOptions is set to unmap for this de‐
4228 vice.
4229 Since
4231 2.1
4232 BlockdevAioOptions (Enum)
4234 Selects the AIO backend to handle I/O requests
4235 Values
4237 threads
4238 Use qemu's thread pool
4239 native Use native AIO backend (only Linux and Windows)
4241 io_uring (If: defined(CONFIG_LINUX_IO_URING))
4243 Use linux io_uring (since 5.0)
4244 Since
4246 2.9
4247 BlockdevCacheOptions (Object)
4249 Includes cache-related options for block devices
4250 Members
4252 direct: boolean (optional)
4253 enables use of O_DIRECT (bypass the host page cache; default:
4254 false)
4255 no-flush: boolean (optional)
4257 ignore any flush requests for the device (default: false)
4258 Since
4260 2.9
4261 BlockdevDriver (Enum)
4263 Drivers that are supported in block device operations.
4264 Values
4266 throttle
4267 Since 2.11
4268 nvme Since 2.12
4270 copy-on-read
4272 Since 3.0
4273 blklogwrites
4275 Since 3.0
4276 blkreplay
4278 Since 4.2
4279 compress
4281 Since 5.0
4282 blkdebug
4284 Not documented
4285 blkverify
4287 Not documented
4288 bochs Not documented
4290 cloop Not documented
4292 dmg Not documented
4294 file Not documented
4296 ftp Not documented
4298 ftps Not documented
4300 gluster
4302 Not documented
4303 host_cdrom
4305 Not documented
4306 host_device
4308 Not documented
4309 http Not documented
4311 https Not documented
4313 iscsi Not documented
4315 luks Not documented
4317 nbd Not documented
4319 nfs Not documented
4321 null-aio
4323 Not documented
4324 null-co
4326 Not documented
4327 parallels
4329 Not documented
4330 qcow Not documented
4332 qcow2 Not documented
4334 qed Not documented
4336 quorum Not documented
4338 raw Not documented
4340 rbd Not documented
4342 replication (If: defined(CONFIG_REPLICATION))
4344 Not documented
4345 sheepdog
4347 Not documented
4348 ssh Not documented
4350 vdi Not documented
4352 vhdx Not documented
4354 vmdk Not documented
4356 vpc Not documented
4358 vvfat Not documented
4360 Since
4362 2.9
4363 BlockdevOptionsFile (Object)
4365 Driver specific block device options for the file backend.
4366 Members
4368 filename: string
4369 path to the image file
4370 pr-manager: string (optional)
4372 the id for the object that will handle persistent reservations
4373 for this device (default: none, forward the commands via SG_IO;
4374 since 2.11)
4375 aio: BlockdevAioOptions (optional)
4377 AIO backend (default: threads) (since: 2.8)
4378 locking: OnOffAuto (optional)
4380 whether to enable file locking. If set to 'auto', only enable
4381 when Open File Descriptor (OFD) locking API is available (de‐
4382 fault: auto, since 2.10)
4383 drop-cache: boolean (optional) (If: defined(CONFIG_LINUX))
4385 invalidate page cache during live migration. This prevents
4386 stale data on the migration destination with cache.direct=off.
4387 Currently only supported on Linux hosts. (default: on, since:
4388 4.0)
4389 x-check-cache-dropped: boolean (optional)
4391 whether to check that page cache was dropped on live migration.
4392 May cause noticeable delays if the image file is large, do not
4393 use in production. (default: off) (since: 3.0)
4394 Features
4396 dynamic-auto-read-only
4397 If present, enabled auto-read-only means that the driver will
4398 open the image read-only at first, dynamically reopen the image
4399 file read-write when the first writer is attached to the node
4400 and reopen read-only when the last writer is detached. This al‐
4401 lows giving QEMU write permissions only on demand when an opera‐
4402 tion actually needs write access.
4403 Since
4405 2.9
4406 BlockdevOptionsNull (Object)
4408 Driver specific block device options for the null backend.
4409 Members
4411 size: int (optional)
4412 size of the device in bytes.
4413 latency-ns: int (optional)
4415 emulated latency (in nanoseconds) in processing requests. De‐
4416 fault to zero which completes requests immediately. (Since 2.4)
4417 read-zeroes: boolean (optional)
4419 if true, reads from the device produce zeroes; if false, the
4420 buffer is left unchanged. (default: false; since: 4.1)
4421 Since
4423 2.9
4424 BlockdevOptionsNVMe (Object)
4426 Driver specific block device options for the NVMe backend.
4427 Members
4429 device: string
4430 PCI controller address of the NVMe device in format hhhh:bb:ss.f
4431 (host:bus:slot.function)
4432 namespace: int
4434 namespace number of the device, starting from 1.
4435 Note that the PCI device must have been unbound from any host kernel
4436 driver before instructing QEMU to add the blockdev.
4437 Since
4439 2.12
4440 BlockdevOptionsVVFAT (Object)
4442 Driver specific block device options for the vvfat protocol.
4443 Members
4445 dir: string
4446 directory to be exported as FAT image
4447 fat-type: int (optional)
4449 FAT type: 12, 16 or 32
4450 floppy: boolean (optional)
4452 whether to export a floppy image (true) or partitioned hard disk
4453 (false; default)
4454 label: string (optional)
4456 set the volume label, limited to 11 bytes. FAT16 and FAT32 tra‐
4457 ditionally have some restrictions on labels, which are ignored
4458 by most operating systems. Defaults to "QEMU VVFAT". (since
4459 2.4)
4460 rw: boolean (optional)
4462 whether to allow write operations (default: false)
4463 Since
4465 2.9
4466 BlockdevOptionsGenericFormat (Object)
4468 Driver specific block device options for image format that have no op‐
4469 tion besides their data source.
4470 Members
4472 file: BlockdevRef
4473 reference to or definition of the data source block device
4474 Since
4476 2.9
4477 BlockdevOptionsLUKS (Object)
4479 Driver specific block device options for LUKS.
4480 Members
4482 key-secret: string (optional)
4483 the ID of a QCryptoSecret object providing the decryption key
4484 (since 2.6). Mandatory except when doing a metadata-only probe
4485 of the image.
4486 The members of BlockdevOptionsGenericFormat
4488 Since
4490 2.9
4491 BlockdevOptionsGenericCOWFormat (Object)
4493 Driver specific block device options for image format that have no op‐
4494 tion besides their data source and an optional backing file.
4495 Members
4497 backing: BlockdevRefOrNull (optional)
4498 reference to or definition of the backing file block device,
4499 null disables the backing file entirely. Defaults to the back‐
4500 ing file stored the image file.
4501 The members of BlockdevOptionsGenericFormat
4503 Since
4505 2.9
4506 Qcow2OverlapCheckMode (Enum)
4508 General overlap check modes.
4509 Values
4511 none Do not perform any checks
4512 constant
4514 Perform only checks which can be done in constant time and with‐
4515 out reading anything from disk
4516 cached Perform only checks which can be done without reading anything
4518 from disk
4519 all Perform all available overlap checks
4521 Since
4523 2.9
4524 Qcow2OverlapCheckFlags (Object)
4526 Structure of flags for each metadata structure. Setting a field to
4527 'true' makes qemu guard that structure against unintended overwriting.
4528 The default value is chosen according to the template given.
4529 Members
4531 template: Qcow2OverlapCheckMode (optional)
4532 Specifies a template mode which can be adjusted using the other
4533 flags, defaults to 'cached'
4534 bitmap-directory: boolean (optional)
4536 since 3.0
4537 main-header: boolean (optional)
4539 Not documented
4540 active-l1: boolean (optional)
4542 Not documented
4543 active-l2: boolean (optional)
4545 Not documented
4546 refcount-table: boolean (optional)
4548 Not documented
4549 refcount-block: boolean (optional)
4551 Not documented
4552 snapshot-table: boolean (optional)
4554 Not documented
4555 inactive-l1: boolean (optional)
4557 Not documented
4558 inactive-l2: boolean (optional)
4560 Not documented
4561 Since
4563 2.9
4564 Qcow2OverlapChecks (Alternate)
4566 Specifies which metadata structures should be guarded against unin‐
4567 tended overwriting.
4568 Members
4570 flags: Qcow2OverlapCheckFlags
4571 set of flags for separate specification of each metadata struc‐
4572 ture type
4573 mode: Qcow2OverlapCheckMode
4575 named mode which chooses a specific set of flags
4576 Since
4578 2.9
4579 BlockdevQcowEncryptionFormat (Enum)
4581 Values
4582 aes AES-CBC with plain64 initialization vectors
4583 Since
4585 2.10
4586 BlockdevQcowEncryption (Object)
4588 Members
4589 format: BlockdevQcowEncryptionFormat
4590 Not documented
4591 The members of QCryptoBlockOptionsQCow when format is "aes"
4593 Since
4595 2.10
4596 BlockdevOptionsQcow (Object)
4598 Driver specific block device options for qcow.
4599 Members
4601 encrypt: BlockdevQcowEncryption (optional)
4602 Image decryption options. Mandatory for encrypted images, except
4603 when doing a metadata-only probe of the image.
4604 The members of BlockdevOptionsGenericCOWFormat
4606 Since
4608 2.10
4609 BlockdevQcow2EncryptionFormat (Enum)
4611 Values
4612 aes AES-CBC with plain64 initialization vectors
4613 luks Not documented
4615 Since
4617 2.10
4618 BlockdevQcow2Encryption (Object)
4620 Members
4621 format: BlockdevQcow2EncryptionFormat
4622 Not documented
4623 The members of QCryptoBlockOptionsQCow when format is "aes"
4625 The members of QCryptoBlockOptionsLUKS when format is "luks"
4627 Since
4629 2.10
4630 BlockdevOptionsQcow2 (Object)
4632 Driver specific block device options for qcow2.
4633 Members
4635 lazy-refcounts: boolean (optional)
4636 whether to enable the lazy refcounts feature (default is taken
4637 from the image file)
4638 pass-discard-request: boolean (optional)
4640 whether discard requests to the qcow2 device should be forwarded
4641 to the data source
4642 pass-discard-snapshot: boolean (optional)
4644 whether discard requests for the data source should be issued
4645 when a snapshot operation (e.g. deleting a snapshot) frees
4646 clusters in the qcow2 file
4647 pass-discard-other: boolean (optional)
4649 whether discard requests for the data source should be issued on
4650 other occasions where a cluster gets freed
4651 overlap-check: Qcow2OverlapChecks (optional)
4653 which overlap checks to perform for writes to the image, de‐
4654 faults to 'cached' (since 2.2)
4655 cache-size: int (optional)
4657 the maximum total size of the L2 table and refcount block caches
4658 in bytes (since 2.2)
4659 l2-cache-size: int (optional)
4661 the maximum size of the L2 table cache in bytes (since 2.2)
4662 l2-cache-entry-size: int (optional)
4664 the size of each entry in the L2 cache in bytes. It must be a
4665 power of two between 512 and the cluster size. The default value
4666 is the cluster size (since 2.12)
4667 refcount-cache-size: int (optional)
4669 the maximum size of the refcount block cache in bytes (since
4670 2.2)
4671 cache-clean-interval: int (optional)
4673 clean unused entries in the L2 and refcount caches. The interval
4674 is in seconds. The default value is 600 on supporting platforms,
4675 and 0 on other platforms. 0 disables this feature. (since 2.5)
4676 encrypt: BlockdevQcow2Encryption (optional)
4678 Image decryption options. Mandatory for encrypted images, except
4679 when doing a metadata-only probe of the image. (since 2.10)
4680 data-file: BlockdevRef (optional)
4682 reference to or definition of the external data file. This may
4683 only be specified for images that require an external data file.
4684 If it is not specified for such an image, the data file name is
4685 loaded from the image file. (since 4.0)
4686 The members of BlockdevOptionsGenericCOWFormat
4688 Since
4690 2.9
4691 SshHostKeyCheckMode (Enum)
4693 Values
4694 none Don't check the host key at all
4695 hash Compare the host key with a given hash
4697 known_hosts
4699 Check the host key against the known_hosts file
4700 Since
4702 2.12
4703 SshHostKeyCheckHashType (Enum)
4705 Values
4706 md5 The given hash is an md5 hash
4707 sha1 The given hash is an sha1 hash
4709 Since
4711 2.12
4712 SshHostKeyHash (Object)
4714 Members
4715 type: SshHostKeyCheckHashType
4716 The hash algorithm used for the hash
4717 hash: string
4719 The expected hash value
4720 Since
4722 2.12
4723 SshHostKeyCheck (Object)
4725 Members
4726 mode: SshHostKeyCheckMode
4727 Not documented
4728 The members of SshHostKeyHash when mode is "hash"
4730 Since
4732 2.12
4733 BlockdevOptionsSsh (Object)
4735 Members
4736 server: InetSocketAddress
4737 host address
4738 path: string
4740 path to the image on the host
4741 user: string (optional)
4743 user as which to connect, defaults to current local user name
4744 host-key-check: SshHostKeyCheck (optional)
4746 Defines how and what to check the host key against (default:
4747 known_hosts)
4748 Since
4750 2.9
4751 BlkdebugEvent (Enum)
4753 Trigger events supported by blkdebug.
4754 Values
4756 l1_shrink_write_table
4757 write zeros to the l1 table to shrink image. (since 2.11)
4758 l1_shrink_free_l2_clusters
4760 discard the l2 tables. (since 2.11)
4761 cor_write
4763 a write due to copy-on-read (since 2.11)
4764 cluster_alloc_space
4766 an allocation of file space for a cluster (since 4.1)
4767 none triggers once at creation of the blkdebug node (since 4.1)
4769 l1_update
4771 Not documented
4772 l1_grow_alloc_table
4774 Not documented
4775 l1_grow_write_table
4777 Not documented
4778 l1_grow_activate_table
4780 Not documented
4781 l2_load
4783 Not documented
4784 l2_update
4786 Not documented
4787 l2_update_compressed
4789 Not documented
4790 l2_alloc_cow_read
4792 Not documented
4793 l2_alloc_write
4795 Not documented
4796 read_aio
4798 Not documented
4799 read_backing_aio
4801 Not documented
4802 read_compressed
4804 Not documented
4805 write_aio
4807 Not documented
4808 write_compressed
4810 Not documented
4811 vmstate_load
4813 Not documented
4814 vmstate_save
4816 Not documented
4817 cow_read
4819 Not documented
4820 cow_write
4822 Not documented
4823 reftable_load
4825 Not documented
4826 reftable_grow
4828 Not documented
4829 reftable_update
4831 Not documented
4832 refblock_load
4834 Not documented
4835 refblock_update
4837 Not documented
4838 refblock_update_part
4840 Not documented
4841 refblock_alloc
4843 Not documented
4844 refblock_alloc_hookup
4846 Not documented
4847 refblock_alloc_write
4849 Not documented
4850 refblock_alloc_write_blocks
4852 Not documented
4853 refblock_alloc_write_table
4855 Not documented
4856 refblock_alloc_switch_table
4858 Not documented
4859 cluster_alloc
4861 Not documented
4862 cluster_alloc_bytes
4864 Not documented
4865 cluster_free
4867 Not documented
4868 flush_to_os
4870 Not documented
4871 flush_to_disk
4873 Not documented
4874 pwritev_rmw_head
4876 Not documented
4877 pwritev_rmw_after_head
4879 Not documented
4880 pwritev_rmw_tail
4882 Not documented
4883 pwritev_rmw_after_tail
4885 Not documented
4886 pwritev
4888 Not documented
4889 pwritev_zero
4891 Not documented
4892 pwritev_done
4894 Not documented
4895 empty_image_prepare
4897 Not documented
4898 Since
4900 2.9
4901 BlkdebugIOType (Enum)
4903 Kinds of I/O that blkdebug can inject errors in.
4904 Values
4906 read .bdrv_co_preadv()
4907 write .bdrv_co_pwritev()
4909 write-zeroes
4911 .bdrv_co_pwrite_zeroes()
4912 discard
4914 .bdrv_co_pdiscard()
4915 flush .bdrv_co_flush_to_disk()
4917 block-status
4919 .bdrv_co_block_status()
4920 Since
4922 4.1
4923 BlkdebugInjectErrorOptions (Object)
4925 Describes a single error injection for blkdebug.
4926 Members
4928 event: BlkdebugEvent
4929 trigger event
4930 state: int (optional)
4932 the state identifier blkdebug needs to be in to actually trigger
4933 the event; defaults to "any"
4934 iotype: BlkdebugIOType (optional)
4936 the type of I/O operations on which this error should be in‐
4937 jected; defaults to "all read, write, write-zeroes, discard, and
4938 flush operations" (since: 4.1)
4939 errno: int (optional)
4941 error identifier (errno) to be returned; defaults to EIO
4942 sector: int (optional)
4944 specifies the sector index which has to be affected in order to
4945 actually trigger the event; defaults to "any sector"
4946 once: boolean (optional)
4948 disables further events after this one has been triggered; de‐
4949 faults to false
4950 immediately: boolean (optional)
4952 fail immediately; defaults to false
4953 Since
4955 2.9
4956 BlkdebugSetStateOptions (Object)
4958 Describes a single state-change event for blkdebug.
4959 Members
4961 event: BlkdebugEvent
4962 trigger event
4963 state: int (optional)
4965 the current state identifier blkdebug needs to be in; defaults
4966 to "any"
4967 new_state: int
4969 the state identifier blkdebug is supposed to assume if this
4970 event is triggered
4971 Since
4973 2.9
4974 BlockdevOptionsBlkdebug (Object)
4976 Driver specific block device options for blkdebug.
4977 Members
4979 image: BlockdevRef
4980 underlying raw block device (or image file)
4981 config: string (optional)
4983 filename of the configuration file
4984 align: int (optional)
4986 required alignment for requests in bytes, must be positive power
4987 of 2, or 0 for default
4988 max-transfer: int (optional)
4990 maximum size for I/O transfers in bytes, must be positive multi‐
4991 ple of align and of the underlying file's request alignment (but
4992 need not be a power of 2), or 0 for default (since 2.10)
4993 opt-write-zero: int (optional)
4995 preferred alignment for write zero requests in bytes, must be
4996 positive multiple of align and of the underlying file's request
4997 alignment (but need not be a power of 2), or 0 for default
4998 (since 2.10)
4999 max-write-zero: int (optional)
5001 maximum size for write zero requests in bytes, must be positive
5002 multiple of align, of opt-write-zero, and of the underlying
5003 file's request alignment (but need not be a power of 2), or 0
5004 for default (since 2.10)
5005 opt-discard: int (optional)
5007 preferred alignment for discard requests in bytes, must be posi‐
5008 tive multiple of align and of the underlying file's request
5009 alignment (but need not be a power of 2), or 0 for default
5010 (since 2.10)
5011 max-discard: int (optional)
5013 maximum size for discard requests in bytes, must be positive
5014 multiple of align, of opt-discard, and of the underlying file's
5015 request alignment (but need not be a power of 2), or 0 for de‐
5016 fault (since 2.10)
5017 inject-error: array of BlkdebugInjectErrorOptions (optional)
5019 array of error injection descriptions
5020 set-state: array of BlkdebugSetStateOptions (optional)
5022 array of state-change descriptions
5023 take-child-perms: array of BlockPermission (optional)
5025 Permissions to take on image in addition to what is necessary
5026 anyway (which depends on how the blkdebug node is used). De‐
5027 faults to none. (since 5.0)
5028 unshare-child-perms: array of BlockPermission (optional)
5030 Permissions not to share on image in addition to what cannot be
5031 shared anyway (which depends on how the blkdebug node is used).
5032 Defaults to none. (since 5.0)
5033 Since
5035 2.9
5036 BlockdevOptionsBlklogwrites (Object)
5038 Driver specific block device options for blklogwrites.
5039 Members
5041 file: BlockdevRef
5042 block device
5043 log: BlockdevRef
5045 block device used to log writes to file
5046 log-sector-size: int (optional)
5048 sector size used in logging writes to file, determines granular‐
5049 ity of offsets and sizes of writes (default: 512)
5050 log-append: boolean (optional)
5052 append to an existing log (default: false)
5053 log-super-update-interval: int (optional)
5055 interval of write requests after which the log super block is
5056 updated to disk (default: 4096)
5057 Since
5059 3.0
5060 BlockdevOptionsBlkverify (Object)
5062 Driver specific block device options for blkverify.
5063 Members
5065 test: BlockdevRef
5066 block device to be tested
5067 raw: BlockdevRef
5069 raw image used for verification
5070 Since
5072 2.9
5073 BlockdevOptionsBlkreplay (Object)
5075 Driver specific block device options for blkreplay.
5076 Members
5078 image: BlockdevRef
5079 disk image which should be controlled with blkreplay
5080 Since
5082 4.2
5083 QuorumReadPattern (Enum)
5085 An enumeration of quorum read patterns.
5086 Values
5088 quorum read all the children and do a quorum vote on reads
5089 fifo read only from the first child that has not failed
5091 Since
5093 2.9
5094 BlockdevOptionsQuorum (Object)
5096 Driver specific block device options for Quorum
5097 Members
5099 blkverify: boolean (optional)
5100 true if the driver must print content mismatch
5102 set to false by default
5103 children: array of BlockdevRef
5105 the children block devices to use
5106 vote-threshold: int
5108 the vote limit under which a read will fail
5109 rewrite-corrupted: boolean (optional)
5111 rewrite corrupted data when quorum is reached (Since 2.1)
5112 read-pattern: QuorumReadPattern (optional)
5114 choose read pattern and set to quorum by default (Since 2.2)
5115 Since
5117 2.9
5118 BlockdevOptionsGluster (Object)
5120 Driver specific block device options for Gluster
5121 Members
5123 volume: string
5124 name of gluster volume where VM image resides
5125 path: string
5127 absolute path to image file in gluster volume
5128 server: array of SocketAddress
5130 gluster servers description
5131 debug: int (optional)
5133 libgfapi log level (default '4' which is Error) (Since 2.8)
5134 logfile: string (optional)
5136 libgfapi log file (default /dev/stderr) (Since 2.8)
5137 Since
5139 2.9
5140 IscsiTransport (Enum)
5142 An enumeration of libiscsi transport types
5143 Values
5145 tcp Not documented
5146 iser Not documented
5148 Since
5150 2.9
5151 IscsiHeaderDigest (Enum)
5153 An enumeration of header digests supported by libiscsi
5154 Values
5156 crc32c Not documented
5157 none Not documented
5159 crc32c-none
5161 Not documented
5162 none-crc32c
5164 Not documented
5165 Since
5167 2.9
5168 BlockdevOptionsIscsi (Object)
5170 Members
5171 transport: IscsiTransport
5172 The iscsi transport type
5173 portal: string
5175 The address of the iscsi portal
5176 target: string
5178 The target iqn name
5179 lun: int (optional)
5181 LUN to connect to. Defaults to 0.
5182 user: string (optional)
5184 User name to log in with. If omitted, no CHAP authentication is
5185 performed.
5186 password-secret: string (optional)
5188 The ID of a QCryptoSecret object providing the password for the
5189 login. This option is required if user is specified.
5190 initiator-name: string (optional)
5192 The iqn name we want to identify to the target as. If this op‐
5193 tion is not specified, an initiator name is generated automati‐
5194 cally.
5195 header-digest: IscsiHeaderDigest (optional)
5197 The desired header digest. Defaults to none-crc32c.
5198 timeout: int (optional)
5200 Timeout in seconds after which a request will timeout. 0 means
5201 no timeout and is the default.
5202 Driver specific block device options for iscsi
5203 Since
5205 2.9
5206 RbdAuthMode (Enum)
5208 Values
5209 cephx Not documented
5210 none Not documented
5212 Since
5214 3.0
5215 BlockdevOptionsRbd (Object)
5217 Members
5218 pool: string
5219 Ceph pool name.
5220 namespace: string (optional)
5222 Rados namespace name in the Ceph pool. (Since 5.0)
5223 image: string
5225 Image name in the Ceph pool.
5226 conf: string (optional)
5228 path to Ceph configuration file. Values in the configuration
5229 file will be overridden by options specified via QAPI.
5230 snapshot: string (optional)
5232 Ceph snapshot name.
5233 user: string (optional)
5235 Ceph id name.
5236 auth-client-required: array of RbdAuthMode (optional)
5238 Acceptable authentication modes. This maps to Ceph configura‐
5239 tion option "auth_client_required". (Since 3.0)
5240 key-secret: string (optional)
5242 ID of a QCryptoSecret object providing a key for cephx authenti‐
5243 cation. This maps to Ceph configuration option "key". (Since
5244 3.0)
5245 server: array of InetSocketAddressBase (optional)
5247 Monitor host address and port. This maps to the "mon_host" Ceph
5248 option.
5249 Since
5251 2.9
5252 BlockdevOptionsSheepdog (Object)
5254 Driver specific block device options for sheepdog
5255 Members
5257 vdi: string
5258 Virtual disk image name
5259 server: SocketAddress
5261 The Sheepdog server to connect to
5262 snap-id: int (optional)
5264 Snapshot ID
5265 tag: string (optional)
5267 Snapshot tag name
5268 Only one of snap-id and tag may be present.
5269 Since
5271 2.9
5272 ReplicationMode (Enum)
5274 An enumeration of replication modes.
5275 Values
5277 primary
5278 Primary mode, the vm's state will be sent to secondary QEMU.
5279 secondary
5281 Secondary mode, receive the vm's state from primary QEMU.
5282 Since
5284 2.9
5285 If
5287 defined(CONFIG_REPLICATION).SS BlockdevOptionsReplication (Object)
5288 Driver specific block device options for replication
5290 Members
5292 mode: ReplicationMode
5293 the replication mode
5294 top-id: string (optional)
5296 In secondary mode, node name or device ID of the root node who
5297 owns the replication node chain. Must not be given in primary
5298 mode.
5299 The members of BlockdevOptionsGenericFormat
5301 Since
5303 2.9
5304 If
5306 defined(CONFIG_REPLICATION).SS NFSTransport (Enum)
5307 An enumeration of NFS transport types
5309 Values
5311 inet TCP transport
5312 Since
5314 2.9
5315 NFSServer (Object)
5317 Captures the address of the socket
5318 Members
5320 type: NFSTransport
5321 transport type used for NFS (only TCP supported)
5322 host: string
5324 host address for NFS server
5325 Since
5327 2.9
5328 BlockdevOptionsNfs (Object)
5330 Driver specific block device option for NFS
5331 Members
5333 server: NFSServer
5334 host address
5335 path: string
5337 path of the image on the host
5338 user: int (optional)
5340 UID value to use when talking to the server (defaults to 65534
5341 on Windows and getuid() on unix)
5342 group: int (optional)
5344 GID value to use when talking to the server (defaults to 65534
5345 on Windows and getgid() in unix)
5346 tcp-syn-count: int (optional)
5348 number of SYNs during the session establishment (defaults to
5349 libnfs default)
5350 readahead-size: int (optional)
5352 set the readahead size in bytes (defaults to libnfs default)
5353 page-cache-size: int (optional)
5355 set the pagecache size in bytes (defaults to libnfs default)
5356 debug: int (optional)
5358 set the NFS debug level (max 2) (defaults to libnfs default)
5359 Since
5361 2.9
5362 BlockdevOptionsCurlBase (Object)
5364 Driver specific block device options shared by all protocols supported
5365 by the curl backend.
5366 Members
5368 url: string
5369 URL of the image file
5370 readahead: int (optional)
5372 Size of the read-ahead cache; must be a multiple of 512 (de‐
5373 faults to 256 kB)
5374 timeout: int (optional)
5376 Timeout for connections, in seconds (defaults to 5)
5377 username: string (optional)
5379 Username for authentication (defaults to none)
5380 password-secret: string (optional)
5382 ID of a QCryptoSecret object providing a password for authenti‐
5383 cation (defaults to no password)
5384 proxy-username: string (optional)
5386 Username for proxy authentication (defaults to none)
5387 proxy-password-secret: string (optional)
5389 ID of a QCryptoSecret object providing a password for proxy au‐
5390 thentication (defaults to no password)
5391 Since
5393 2.9
5394 BlockdevOptionsCurlHttp (Object)
5396 Driver specific block device options for HTTP connections over the curl
5397 backend. URLs must start with "http://".
5398 Members
5400 cookie: string (optional)
5401 List of cookies to set; format is "name1=content1; name2=con‐
5402 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
5403 ies.
5404 cookie-secret: string (optional)
5406 ID of a QCryptoSecret object providing the cookie data in a se‐
5407 cure way. See cookie for the format. (since 2.10)
5408 The members of BlockdevOptionsCurlBase
5410 Since
5412 2.9
5413 BlockdevOptionsCurlHttps (Object)
5415 Driver specific block device options for HTTPS connections over the
5416 curl backend. URLs must start with "https://".
5417 Members
5419 cookie: string (optional)
5420 List of cookies to set; format is "name1=content1; name2=con‐
5421 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
5422 ies.
5423 sslverify: boolean (optional)
5425 Whether to verify the SSL certificate's validity (defaults to
5426 true)
5427 cookie-secret: string (optional)
5429 ID of a QCryptoSecret object providing the cookie data in a se‐
5430 cure way. See cookie for the format. (since 2.10)
5431 The members of BlockdevOptionsCurlBase
5433 Since
5435 2.9
5436 BlockdevOptionsCurlFtp (Object)
5438 Driver specific block device options for FTP connections over the curl
5439 backend. URLs must start with "ftp://".
5440 Members
5442 The members of BlockdevOptionsCurlBase
5443 Since
5445 2.9
5446 BlockdevOptionsCurlFtps (Object)
5448 Driver specific block device options for FTPS connections over the curl
5449 backend. URLs must start with "ftps://".
5450 Members
5452 sslverify: boolean (optional)
5453 Whether to verify the SSL certificate's validity (defaults to
5454 true)
5455 The members of BlockdevOptionsCurlBase
5457 Since
5459 2.9
5460 BlockdevOptionsNbd (Object)
5462 Driver specific block device options for NBD.
5463 Members
5465 server: SocketAddress
5466 NBD server address
5467 export: string (optional)
5469 export name
5470 tls-creds: string (optional)
5472 TLS credentials ID
5473 x-dirty-bitmap: string (optional)
5475 A metadata context name such as "qemu:dirty-bitmap:NAME" or
5476 "qemu:allocation-depth" to query in place of the traditional
5477 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
5478 the NBD protocol; and yes, naming this option x-context would
5479 have made more sense) (since 3.0)
5480 reconnect-delay: int (optional)
5482 On an unexpected disconnect, the nbd client tries to connect
5483 again until succeeding or encountering a serious error. During
5484 the first reconnect-delay seconds, all requests are paused and
5485 will be rerun on a successful reconnect. After that time, any
5486 delayed requests and all future requests before a successful re‐
5487 connect will immediately fail. Default 0 (Since 4.2)
5488 Since
5490 2.9
5491 BlockdevOptionsRaw (Object)
5493 Driver specific block device options for the raw driver.
5494 Members
5496 offset: int (optional)
5497 position where the block device starts
5498 size: int (optional)
5500 the assumed size of the device
5501 The members of BlockdevOptionsGenericFormat
5503 Since
5505 2.9
5506 BlockdevOptionsThrottle (Object)
5508 Driver specific block device options for the throttle driver
5509 Members
5511 throttle-group: string
5512 the name of the throttle-group object to use. It must already
5513 exist.
5514 file: BlockdevRef
5516 reference to or definition of the data source block device
5517 Since
5519 2.11
5520 BlockdevOptions (Object)
5522 Options for creating a block device. Many options are available for
5523 all block devices, independent of the block driver:
5524 Members
5526 driver: BlockdevDriver
5527 block driver name
5528 node-name: string (optional)
5530 the node name of the new node (Since 2.0). This option is re‐
5531 quired on the top level of blockdev-add. Valid node names start
5532 with an alphabetic character and may contain only alphanumeric
5533 characters, '-', '.' and '_'. Their maximum length is 31 charac‐
5534 ters.
5535 discard: BlockdevDiscardOptions (optional)
5537 discard-related options (default: ignore)
5538 cache: BlockdevCacheOptions (optional)
5540 cache-related options
5541 read-only: boolean (optional)
5543 whether the block device should be read-only (default: false).
5544 Note that some block drivers support only read-only access, ei‐
5545 ther generally or in certain configurations. In this case, the
5546 default value does not work and the option must be specified ex‐
5547 plicitly.
5548 auto-read-only: boolean (optional)
5550 if true and read-only is false, QEMU may automatically decide
5551 not to open the image read-write as requested, but fall back to
5552 read-only instead (and switch between the modes later), e.g. de‐
5553 pending on whether the image file is writable or whether a writ‐
5554 ing user is attached to the node (default: false, since 3.1)
5555 detect-zeroes: BlockdevDetectZeroesOptions (optional)
5557 detect and optimize zero writes (Since 2.1) (default: off)
5558 force-share: boolean (optional)
5560 force share all permission on added nodes. Requires
5561 read-only=true. (Since 2.10)
5562 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
5564 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
5566 writes"
5567 The members of BlockdevOptionsBlkverify when driver is "blkverify"
5569 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
5571 The members of BlockdevOptionsGenericFormat when driver is "bochs"
5573 The members of BlockdevOptionsGenericFormat when driver is "cloop"
5575 The members of BlockdevOptionsGenericFormat when driver is "compress"
5577 The members of BlockdevOptionsGenericFormat when driver is
5579 "copy-on-read"
5580 The members of BlockdevOptionsGenericFormat when driver is "dmg"
5582 The members of BlockdevOptionsFile when driver is "file"
5584 The members of BlockdevOptionsCurlFtp when driver is "ftp"
5586 The members of BlockdevOptionsCurlFtps when driver is "ftps"
5588 The members of BlockdevOptionsGluster when driver is "gluster"
5590 The members of BlockdevOptionsFile when driver is "host_cdrom"
5592 The members of BlockdevOptionsFile when driver is "host_device"
5594 The members of BlockdevOptionsCurlHttp when driver is "http"
5596 The members of BlockdevOptionsCurlHttps when driver is "https"
5598 The members of BlockdevOptionsIscsi when driver is "iscsi"
5600 The members of BlockdevOptionsLUKS when driver is "luks"
5602 The members of BlockdevOptionsNbd when driver is "nbd"
5604 The members of BlockdevOptionsNfs when driver is "nfs"
5606 The members of BlockdevOptionsNull when driver is "null-aio"
5608 The members of BlockdevOptionsNull when driver is "null-co"
5610 The members of BlockdevOptionsNVMe when driver is "nvme"
5612 The members of BlockdevOptionsGenericFormat when driver is "parallels"
5614 The members of BlockdevOptionsQcow2 when driver is "qcow2"
5616 The members of BlockdevOptionsQcow when driver is "qcow"
5618 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
5620 The members of BlockdevOptionsQuorum when driver is "quorum"
5622 The members of BlockdevOptionsRaw when driver is "raw"
5624 The members of BlockdevOptionsRbd when driver is "rbd"
5626 The members of BlockdevOptionsReplication when driver is "replication"
5628 (If: defined(CONFIG_REPLICATION))
5629 The members of BlockdevOptionsSheepdog when driver is "sheepdog"
5631 The members of BlockdevOptionsSsh when driver is "ssh"
5633 The members of BlockdevOptionsThrottle when driver is "throttle"
5635 The members of BlockdevOptionsGenericFormat when driver is "vdi"
5637 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
5639 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
5641 The members of BlockdevOptionsGenericFormat when driver is "vpc"
5643 The members of BlockdevOptionsVVFAT when driver is "vvfat"
5645 Remaining options are determined by the block driver.
5646 Since
5648 2.9
5649 BlockdevRef (Alternate)
5651 Reference to a block device.
5652 Members
5654 definition: BlockdevOptions
5655 defines a new block device inline
5656 reference: string
5658 references the ID of an existing block device
5659 Since
5661 2.9
5662 BlockdevRefOrNull (Alternate)
5664 Reference to a block device.
5665 Members
5667 definition: BlockdevOptions
5668 defines a new block device inline
5669 reference: string
5671 references the ID of an existing block device. An empty string
5672 means that no block device should be referenced. Deprecated;
5673 use null instead.
5674 null: null
5676 No block device should be referenced (since 2.10)
5677 Since
5679 2.9
5680 blockdev-add (Command)
5682 Creates a new block device.
5683 Arguments
5685 The members of BlockdevOptions
5686 Since
5688 2.9
5689 Example
5691 1.
5692 -> { "execute": "blockdev-add",
5693 "arguments": {
5694 "driver": "qcow2",
5695 "node-name": "test1",
5696 "file": {
5697 "driver": "file",
5698 "filename": "test.qcow2"
5699 }
5700 }
5701 }
5702 <- { "return": {} }
5703 2.
5705 -> { "execute": "blockdev-add",
5706 "arguments": {
5707 "driver": "qcow2",
5708 "node-name": "node0",
5709 "discard": "unmap",
5710 "cache": {
5711 "direct": true
5712 },
5713 "file": {
5714 "driver": "file",
5715 "filename": "/tmp/test.qcow2"
5716 },
5717 "backing": {
5718 "driver": "raw",
5719 "file": {
5720 "driver": "file",
5721 "filename": "/dev/fdset/4"
5722 }
5723 }
5724 }
5725 }
5726 <- { "return": {} }
5728 x-blockdev-reopen (Command)
5730 Reopens a block device using the given set of options. Any option not
5731 specified will be reset to its default value regardless of its previous
5732 status. If an option cannot be changed or a particular driver does not
5733 support reopening then the command will return an error.
5734 The top-level node-name option (from BlockdevOptions) must be specified
5736 and is used to select the block device to be reopened. Other node-name
5737 options must be either omitted or set to the current name of the appro‐
5738 priate node. This command won't change any node name and any attempt to
5739 do it will result in an error.
5740 In the case of options that refer to child nodes, the behavior of this
5742 command depends on the value:
5743 1. A set of options (BlockdevOptions): the child is reopened with
5745 the specified set of options.
5746 2. A reference to the current child: the child is reopened using its
5748 existing set of options.
5749 3. A reference to a different node: the current child is replaced
5751 with the specified one.
5752 4. NULL: the current child (if any) is detached.
5754 Options (1) and (2) are supported in all cases, but at the moment only
5756 backing allows replacing or detaching an existing child.
5757 Unlike with blockdev-add, the backing option must always be present un‐
5759 less the node being reopened does not have a backing file and its image
5760 does not have a default backing file name as part of its metadata.
5761 Arguments
5763 The members of BlockdevOptions
5764 Since
5766 4.0
5767 blockdev-del (Command)
5769 Deletes a block device that has been added using blockdev-add. The
5770 command will fail if the node is attached to a device or is otherwise
5771 being used.
5772 Arguments
5774 node-name: string
5775 Name of the graph node to delete.
5776 Since
5778 2.9
5779 Example
5781 -> { "execute": "blockdev-add",
5782 "arguments": {
5783 "driver": "qcow2",
5784 "node-name": "node0",
5785 "file": {
5786 "driver": "file",
5787 "filename": "test.qcow2"
5788 }
5789 }
5790 }
5791 <- { "return": {} }
5792 -> { "execute": "blockdev-del",
5794 "arguments": { "node-name": "node0" }
5795 }
5796 <- { "return": {} }
5797 BlockdevCreateOptionsFile (Object)
5799 Driver specific image creation options for file.
5800 Members
5802 filename: string
5803 Filename for the new image file
5804 size: int
5806 Size of the virtual disk in bytes
5807 preallocation: PreallocMode (optional)
5809 Preallocation mode for the new image (default: off; allowed val‐
5810 ues: off, falloc (if defined CONFIG_POSIX_FALLOCATE), full (if
5811 defined CONFIG_POSIX))
5812 nocow: boolean (optional)
5814 Turn off copy-on-write (valid only on btrfs; default: off)
5815 extent-size-hint: int (optional)
5817 Extent size hint to add to the image file; 0 for not adding an
5818 extent size hint (default: 1 MB, since 5.1)
5819 Since
5821 2.12
5822 BlockdevCreateOptionsGluster (Object)
5824 Driver specific image creation options for gluster.
5825 Members
5827 location: BlockdevOptionsGluster
5828 Where to store the new image file
5829 size: int
5831 Size of the virtual disk in bytes
5832 preallocation: PreallocMode (optional)
5834 Preallocation mode for the new image (default: off; allowed val‐
5835 ues: off, falloc (if defined CONFIG_GLUSTERFS_FALLOCATE), full
5836 (if defined CONFIG_GLUSTERFS_ZEROFILL))
5837 Since
5839 2.12
5840 BlockdevCreateOptionsLUKS (Object)
5842 Driver specific image creation options for LUKS.
5843 Members
5845 file: BlockdevRef
5846 Node to create the image format on
5847 size: int
5849 Size of the virtual disk in bytes
5850 preallocation: PreallocMode (optional)
5852 Preallocation mode for the new image (since: 4.2) (default: off;
5853 allowed values: off, metadata, falloc, full)
5854 The members of QCryptoBlockCreateOptionsLUKS
5856 Since
5858 2.12
5859 BlockdevCreateOptionsNfs (Object)
5861 Driver specific image creation options for NFS.
5862 Members
5864 location: BlockdevOptionsNfs
5865 Where to store the new image file
5866 size: int
5868 Size of the virtual disk in bytes
5869 Since
5871 2.12
5872 BlockdevCreateOptionsParallels (Object)
5874 Driver specific image creation options for parallels.
5875 Members
5877 file: BlockdevRef
5878 Node to create the image format on
5879 size: int
5881 Size of the virtual disk in bytes
5882 cluster-size: int (optional)
5884 Cluster size in bytes (default: 1 MB)
5885 Since
5887 2.12
5888 BlockdevCreateOptionsQcow (Object)
5890 Driver specific image creation options for qcow.
5891 Members
5893 file: BlockdevRef
5894 Node to create the image format on
5895 size: int
5897 Size of the virtual disk in bytes
5898 backing-file: string (optional)
5900 File name of the backing file if a backing file should be used
5901 encrypt: QCryptoBlockCreateOptions (optional)
5903 Encryption options if the image should be encrypted
5904 Since
5906 2.12
5907 BlockdevQcow2Version (Enum)
5909 Values
5910 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
5911 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
5913 Since
5915 2.12
5916 Qcow2CompressionType (Enum)
5918 Compression type used in qcow2 image file
5919 Values
5921 zlib zlib compression, see <http://zlib.net/>
5922 zstd (If: defined(CONFIG_ZSTD))
5924 zstd compression, see <http://github.com/facebook/zstd>
5925 Since
5927 5.1
5928 BlockdevCreateOptionsQcow2 (Object)
5930 Driver specific image creation options for qcow2.
5931 Members
5933 file: BlockdevRef
5934 Node to create the image format on
5935 data-file: BlockdevRef (optional)
5937 Node to use as an external data file in which all guest data is
5938 stored so that only metadata remains in the qcow2 file (since:
5939 4.0)
5940 data-file-raw: boolean (optional)
5942 True if the external data file must stay valid as a standalone
5943 (read-only) raw image without looking at qcow2 metadata (de‐
5944 fault: false; since: 4.0)
5945 extended-l2: boolean (optional)
5947 True to make the image have extended L2 entries (default: false;
5948 since 5.2)
5949 size: int
5951 Size of the virtual disk in bytes
5952 version: BlockdevQcow2Version (optional)
5954 Compatibility level (default: v3)
5955 backing-file: string (optional)
5957 File name of the backing file if a backing file should be used
5958 backing-fmt: BlockdevDriver (optional)
5960 Name of the block driver to use for the backing file
5961 encrypt: QCryptoBlockCreateOptions (optional)
5963 Encryption options if the image should be encrypted
5964 cluster-size: int (optional)
5966 qcow2 cluster size in bytes (default: 65536)
5967 preallocation: PreallocMode (optional)
5969 Preallocation mode for the new image (default: off; allowed val‐
5970 ues: off, falloc, full, metadata)
5971 lazy-refcounts: boolean (optional)
5973 True if refcounts may be updated lazily (default: off)
5974 refcount-bits: int (optional)
5976 Width of reference counts in bits (default: 16)
5977 compression-type: Qcow2CompressionType (optional)
5979 The image cluster compression method (default: zlib, since 5.1)
5980 Since
5982 2.12
5983 BlockdevCreateOptionsQed (Object)
5985 Driver specific image creation options for qed.
5986 Members
5988 file: BlockdevRef
5989 Node to create the image format on
5990 size: int
5992 Size of the virtual disk in bytes
5993 backing-file: string (optional)
5995 File name of the backing file if a backing file should be used
5996 backing-fmt: BlockdevDriver (optional)
5998 Name of the block driver to use for the backing file
5999 cluster-size: int (optional)
6001 Cluster size in bytes (default: 65536)
6002 table-size: int (optional)
6004 L1/L2 table size (in clusters)
6005 Since
6007 2.12
6008 BlockdevCreateOptionsRbd (Object)
6010 Driver specific image creation options for rbd/Ceph.
6011 Members
6013 location: BlockdevOptionsRbd
6014 Where to store the new image file. This location cannot point to
6015 a snapshot.
6016 size: int
6018 Size of the virtual disk in bytes
6019 cluster-size: int (optional)
6021 RBD object size
6022 Since
6024 2.12
6025 BlockdevVmdkSubformat (Enum)
6027 Subformat options for VMDK images
6028 Values
6030 monolithicSparse
6031 Single file image with sparse cluster allocation
6032 monolithicFlat
6034 Single flat data image and a descriptor file
6035 twoGbMaxExtentSparse
6037 Data is split into 2GB (per virtual LBA) sparse extent files, in
6038 addition to a descriptor file
6039 twoGbMaxExtentFlat
6041 Data is split into 2GB (per virtual LBA) flat extent files, in
6042 addition to a descriptor file
6043 streamOptimized
6045 Single file image sparse cluster allocation, optimized for
6046 streaming over network.
6047 Since
6049 4.0
6050 BlockdevVmdkAdapterType (Enum)
6052 Adapter type info for VMDK images
6053 Values
6055 ide Not documented
6056 buslogic
6058 Not documented
6059 lsilogic
6061 Not documented
6062 legacyESX
6064 Not documented
6065 Since
6067 4.0
6068 BlockdevCreateOptionsVmdk (Object)
6070 Driver specific image creation options for VMDK.
6071 Members
6073 file: BlockdevRef
6074 Where to store the new image file. This refers to the image file
6075 for monolithcSparse and streamOptimized format, or the descrip‐
6076 tor file for other formats.
6077 size: int
6079 Size of the virtual disk in bytes
6080 extents: array of BlockdevRef (optional)
6082 Where to store the data extents. Required for monolithcFlat,
6083 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For mono‐
6084 lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
6085 mats, the number of entries required is calculated as ex‐
6086 tent_number = virtual_size / 2GB. Providing more extents than
6087 will be used is an error.
6088 subformat: BlockdevVmdkSubformat (optional)
6090 The subformat of the VMDK image. Default: "monolithicSparse".
6091 backing-file: string (optional)
6093 The path of backing file. Default: no backing file is used.
6094 adapter-type: BlockdevVmdkAdapterType (optional)
6096 The adapter type used to fill in the descriptor. Default: ide.
6097 hwversion: string (optional)
6099 Hardware version. The meaningful options are "4" or "6". De‐
6100 fault: "4".
6101 zeroed-grain: boolean (optional)
6103 Whether to enable zeroed-grain feature for sparse subformats.
6104 Default: false.
6105 Since
6107 4.0
6108 SheepdogRedundancyType (Enum)
6110 Values
6111 full Create a fully replicated vdi with x copies
6112 erasure-coded
6114 Create an erasure coded vdi with x data strips and y parity
6115 strips
6116 Since
6118 2.12
6119 SheepdogRedundancyFull (Object)
6121 Members
6122 copies: int
6123 Number of copies to use (between 1 and 31)
6124 Since
6126 2.12
6127 SheepdogRedundancyErasureCoded (Object)
6129 Members
6130 data-strips: int
6131 Number of data strips to use (one of {2,4,8,16})
6132 parity-strips: int
6134 Number of parity strips to use (between 1 and 15)
6135 Since
6137 2.12
6138 SheepdogRedundancy (Object)
6140 Members
6141 type: SheepdogRedundancyType
6142 Not documented
6143 The members of SheepdogRedundancyFull when type is "full"
6145 The members of SheepdogRedundancyErasureCoded when type is "era‐
6147 sure-coded"
6148 Since
6150 2.12
6151 BlockdevCreateOptionsSheepdog (Object)
6153 Driver specific image creation options for Sheepdog.
6154 Members
6156 location: BlockdevOptionsSheepdog
6157 Where to store the new image file
6158 size: int
6160 Size of the virtual disk in bytes
6161 backing-file: string (optional)
6163 File name of a base image
6164 preallocation: PreallocMode (optional)
6166 Preallocation mode for the new image (default: off; allowed val‐
6167 ues: off, full)
6168 redundancy: SheepdogRedundancy (optional)
6170 Redundancy of the image
6171 object-size: int (optional)
6173 Object size of the image
6174 Since
6176 2.12
6177 BlockdevCreateOptionsSsh (Object)
6179 Driver specific image creation options for SSH.
6180 Members
6182 location: BlockdevOptionsSsh
6183 Where to store the new image file
6184 size: int
6186 Size of the virtual disk in bytes
6187 Since
6189 2.12
6190 BlockdevCreateOptionsVdi (Object)
6192 Driver specific image creation options for VDI.
6193 Members
6195 file: BlockdevRef
6196 Node to create the image format on
6197 size: int
6199 Size of the virtual disk in bytes
6200 preallocation: PreallocMode (optional)
6202 Preallocation mode for the new image (default: off; allowed val‐
6203 ues: off, metadata)
6204 Since
6206 2.12
6207 BlockdevVhdxSubformat (Enum)
6209 Values
6210 dynamic
6211 Growing image file
6212 fixed Preallocated fixed-size image file
6214 Since
6216 2.12
6217 BlockdevCreateOptionsVhdx (Object)
6219 Driver specific image creation options for vhdx.
6220 Members
6222 file: BlockdevRef
6223 Node to create the image format on
6224 size: int
6226 Size of the virtual disk in bytes
6227 log-size: int (optional)
6229 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
6230 block-size: int (optional)
6232 Block size in bytes, must be a multiple of 1 MB and not larger
6233 than 256 MB (default: automatically choose a block size depend‐
6234 ing on the image size)
6235 subformat: BlockdevVhdxSubformat (optional)
6237 vhdx subformat (default: dynamic)
6238 block-state-zero: boolean (optional)
6240 Force use of payload blocks of type 'ZERO'. Non-standard, but
6241 default. Do not set to 'off' when using 'qemu-img convert' with
6242 subformat=dynamic.
6243 Since
6245 2.12
6246 BlockdevVpcSubformat (Enum)
6248 Values
6249 dynamic
6250 Growing image file
6251 fixed Preallocated fixed-size image file
6253 Since
6255 2.12
6256 BlockdevCreateOptionsVpc (Object)
6258 Driver specific image creation options for vpc (VHD).
6259 Members
6261 file: BlockdevRef
6262 Node to create the image format on
6263 size: int
6265 Size of the virtual disk in bytes
6266 subformat: BlockdevVpcSubformat (optional)
6268 vhdx subformat (default: dynamic)
6269 force-size: boolean (optional)
6271 Force use of the exact byte size instead of rounding to the next
6272 size that can be represented in CHS geometry (default: false)
6273 Since
6275 2.12
6276 BlockdevCreateOptions (Object)
6278 Options for creating an image format on a given node.
6279 Members
6281 driver: BlockdevDriver
6282 block driver to create the image format
6283 The members of BlockdevCreateOptionsFile when driver is "file"
6285 The members of BlockdevCreateOptionsGluster when driver is "gluster"
6287 The members of BlockdevCreateOptionsLUKS when driver is "luks"
6289 The members of BlockdevCreateOptionsNfs when driver is "nfs"
6291 The members of BlockdevCreateOptionsParallels when driver is "paral‐
6293 lels"
6294 The members of BlockdevCreateOptionsQcow when driver is "qcow"
6296 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
6298 The members of BlockdevCreateOptionsQed when driver is "qed"
6300 The members of BlockdevCreateOptionsRbd when driver is "rbd"
6302 The members of BlockdevCreateOptionsSheepdog when driver is "sheepdog"
6304 The members of BlockdevCreateOptionsSsh when driver is "ssh"
6306 The members of BlockdevCreateOptionsVdi when driver is "vdi"
6308 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
6310 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
6312 The members of BlockdevCreateOptionsVpc when driver is "vpc"
6314 Since
6316 2.12
6317 blockdev-create (Command)
6319 Starts a job to create an image format on a given node. The job is au‐
6320 tomatically finalized, but a manual job-dismiss is required.
6321 Arguments
6323 job-id: string
6324 Identifier for the newly created job.
6325 options: BlockdevCreateOptions
6327 Options for the image creation.
6328 Since
6330 3.0
6331 BlockdevAmendOptionsLUKS (Object)
6333 Driver specific image amend options for LUKS.
6334 Members
6336 The members of QCryptoBlockAmendOptionsLUKS
6337 Since
6339 5.1
6340 BlockdevAmendOptionsQcow2 (Object)
6342 Driver specific image amend options for qcow2. For now, only encryp‐
6343 tion options can be amended
6344 encrypt Encryption options to be amended
6346 Members
6348 encrypt: QCryptoBlockAmendOptions (optional)
6349 Not documented
6350 Since
6352 5.1
6353 BlockdevAmendOptions (Object)
6355 Options for amending an image format
6356 Members
6358 driver: BlockdevDriver
6359 Block driver of the node to amend.
6360 The members of BlockdevAmendOptionsLUKS when driver is "luks"
6362 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
6364 Since
6366 5.1
6367 x-blockdev-amend (Command)
6369 Starts a job to amend format specific options of an existing open block
6370 device The job is automatically finalized, but a manual job-dismiss is
6371 required.
6372 Arguments
6374 job-id: string
6375 Identifier for the newly created job.
6376 node-name: string
6378 Name of the block node to work on
6379 options: BlockdevAmendOptions
6381 Options (driver specific)
6382 force: boolean (optional)
6384 Allow unsafe operations, format specific For luks that allows
6385 erase of the last active keyslot (permanent loss of data), and
6386 replacement of an active keyslot (possible loss of data if IO
6387 error happens)
6388 Since
6390 5.1
6391 BlockErrorAction (Enum)
6393 An enumeration of action that has been taken when a DISK I/O occurs
6394 Values
6396 ignore error has been ignored
6397 report error has been reported to the device
6399 stop error caused VM to be stopped
6401 Since
6403 2.1
6404 BLOCK_IMAGE_CORRUPTED (Event)
6406 Emitted when a disk image is being marked corrupt. The image can be
6407 identified by its device or node name. The 'device' field is always
6408 present for compatibility reasons, but it can be empty ("") if the im‐
6409 age does not have a device name associated.
6410 Arguments
6412 device: string
6413 device name. This is always present for compatibility reasons,
6414 but it can be empty ("") if the image does not have a device
6415 name associated.
6416 node-name: string (optional)
6418 node name (Since: 2.4)
6419 msg: string
6421 informative message for human consumption, such as the kind of
6422 corruption being detected. It should not be parsed by machine as
6423 it is not guaranteed to be stable
6424 offset: int (optional)
6426 if the corruption resulted from an image access, this is the
6427 host's access offset into the image
6428 size: int (optional)
6430 if the corruption resulted from an image access, this is the ac‐
6431 cess size
6432 fatal: boolean
6434 if set, the image is marked corrupt and therefore unusable after
6435 this event and must be repaired (Since 2.2; before, every
6436 BLOCK_IMAGE_CORRUPTED event was fatal)
6437 Note
6439 If action is "stop", a STOP event will eventually follow the
6440 BLOCK_IO_ERROR event.
6441 Example
6443 <- { "event": "BLOCK_IMAGE_CORRUPTED",
6444 "data": { "device": "ide0-hd0", "node-name": "node0",
6445 "msg": "Prevented active L1 table overwrite", "offset": 196608,
6446 "size": 65536 },
6447 "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
6448 Since
6450 1.7
6451 BLOCK_IO_ERROR (Event)
6453 Emitted when a disk I/O error occurs
6454 Arguments
6456 device: string
6457 device name. This is always present for compatibility reasons,
6458 but it can be empty ("") if the image does not have a device
6459 name associated.
6460 node-name: string (optional)
6462 node name. Note that errors may be reported for the root node
6463 that is directly attached to a guest device rather than for the
6464 node where the error occurred. The node name is not present if
6465 the drive is empty. (Since: 2.8)
6466 operation: IoOperationType
6468 I/O operation
6469 action: BlockErrorAction
6471 action that has been taken
6472 nospace: boolean (optional)
6474 true if I/O error was caused due to a no-space condition. This
6475 key is only present if query-block's io-status is present,
6476 please see query-block documentation for more information
6477 (since: 2.2)
6478 reason: string
6480 human readable string describing the error cause. (This field
6481 is a debugging aid for humans, it should not be parsed by appli‐
6482 cations) (since: 2.2)
6483 Note
6485 If action is "stop", a STOP event will eventually follow the
6486 BLOCK_IO_ERROR event
6487 Since
6489 0.13.0
6490 Example
6492 <- { "event": "BLOCK_IO_ERROR",
6493 "data": { "device": "ide0-hd1",
6494 "node-name": "#block212",
6495 "operation": "write",
6496 "action": "stop" },
6497 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6498 BLOCK_JOB_COMPLETED (Event)
6500 Emitted when a block job has completed
6501 Arguments
6503 type: JobType
6504 job type
6505 device: string
6507 The job identifier. Originally the device name but other values
6508 are allowed since QEMU 2.7
6509 len: int
6511 maximum progress value
6512 offset: int
6514 current progress value. On success this is equal to len. On
6515 failure this is less than len
6516 speed: int
6518 rate limit, bytes per second
6519 error: string (optional)
6521 error message. Only present on failure. This field contains a
6522 human-readable error message. There are no semantics other than
6523 that streaming has failed and clients should not try to inter‐
6524 pret the error string
6525 Since
6527 1.1
6528 Example
6530 <- { "event": "BLOCK_JOB_COMPLETED",
6531 "data": { "type": "stream", "device": "virtio-disk0",
6532 "len": 10737418240, "offset": 10737418240,
6533 "speed": 0 },
6534 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6535 BLOCK_JOB_CANCELLED (Event)
6537 Emitted when a block job has been cancelled
6538 Arguments
6540 type: JobType
6541 job type
6542 device: string
6544 The job identifier. Originally the device name but other values
6545 are allowed since QEMU 2.7
6546 len: int
6548 maximum progress value
6549 offset: int
6551 current progress value. On success this is equal to len. On
6552 failure this is less than len
6553 speed: int
6555 rate limit, bytes per second
6556 Since
6558 1.1
6559 Example
6561 <- { "event": "BLOCK_JOB_CANCELLED",
6562 "data": { "type": "stream", "device": "virtio-disk0",
6563 "len": 10737418240, "offset": 134217728,
6564 "speed": 0 },
6565 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6566 BLOCK_JOB_ERROR (Event)
6568 Emitted when a block job encounters an error
6569 Arguments
6571 device: string
6572 The job identifier. Originally the device name but other values
6573 are allowed since QEMU 2.7
6574 operation: IoOperationType
6576 I/O operation
6577 action: BlockErrorAction
6579 action that has been taken
6580 Since
6582 1.3
6583 Example
6585 <- { "event": "BLOCK_JOB_ERROR",
6586 "data": { "device": "ide0-hd1",
6587 "operation": "write",
6588 "action": "stop" },
6589 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6590 BLOCK_JOB_READY (Event)
6592 Emitted when a block job is ready to complete
6593 Arguments
6595 type: JobType
6596 job type
6597 device: string
6599 The job identifier. Originally the device name but other values
6600 are allowed since QEMU 2.7
6601 len: int
6603 maximum progress value
6604 offset: int
6606 current progress value. On success this is equal to len. On
6607 failure this is less than len
6608 speed: int
6610 rate limit, bytes per second
6611 Note
6613 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
6614 event
6615 Since
6617 1.3
6618 Example
6620 <- { "event": "BLOCK_JOB_READY",
6621 "data": { "device": "drive0", "type": "mirror", "speed": 0,
6622 "len": 2097152, "offset": 2097152 }
6623 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6624 BLOCK_JOB_PENDING (Event)
6626 Emitted when a block job is awaiting explicit authorization to finalize
6627 graph changes via block-job-finalize. If this job is part of a transac‐
6628 tion, it will not emit this event until the transaction has converged
6629 first.
6630 Arguments
6632 type: JobType
6633 job type
6634 id: string
6636 The job identifier.
6637 Since
6639 2.12
6640 Example
6642 <- { "event": "BLOCK_JOB_WAITING",
6643 "data": { "device": "drive0", "type": "mirror" },
6644 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6645 PreallocMode (Enum)
6647 Preallocation mode of QEMU image file
6648 Values
6650 off no preallocation
6651 metadata
6653 preallocate only for metadata
6654 falloc like full preallocation but allocate disk space by posix_fallo‐
6656 cate() rather than writing data.
6657 full preallocate all data by writing it to the device to ensure disk
6659 space is really available. This data may or may not be zero, de‐
6660 pending on the image format and storage. full preallocation
6661 also sets up metadata correctly.
6662 Since
6664 2.2
6665 BLOCK_WRITE_THRESHOLD (Event)
6667 Emitted when writes on block device reaches or exceeds the configured
6668 write threshold. For thin-provisioned devices, this means the device
6669 should be extended to avoid pausing for disk exhaustion. The event is
6670 one shot. Once triggered, it needs to be re-registered with another
6671 block-set-write-threshold command.
6672 Arguments
6674 node-name: string
6675 graph node name on which the threshold was exceeded.
6676 amount-exceeded: int
6678 amount of data which exceeded the threshold, in bytes.
6679 write-threshold: int
6681 last configured threshold, in bytes.
6682 Since
6684 2.3
6685 block-set-write-threshold (Command)
6687 Change the write threshold for a block drive. An event will be deliv‐
6688 ered if a write to this block drive crosses the configured threshold.
6689 The threshold is an offset, thus must be non-negative. Default is no
6690 write threshold. Setting the threshold to zero disables it.
6691 This is useful to transparently resize thin-provisioned drives without
6693 the guest OS noticing.
6694 Arguments
6696 node-name: string
6697 graph node name on which the threshold must be set.
6698 write-threshold: int
6700 configured threshold for the block device, bytes. Use 0 to dis‐
6701 able the threshold.
6702 Since
6704 2.3
6705 Example
6707 -> { "execute": "block-set-write-threshold",
6708 "arguments": { "node-name": "mydev",
6709 "write-threshold": 17179869184 } }
6710 <- { "return": {} }
6711 x-blockdev-change (Command)
6713 Dynamically reconfigure the block driver state graph. It can be used to
6714 add, remove, insert or replace a graph node. Currently only the Quorum
6715 driver implements this feature to add or remove its child. This is use‐
6716 ful to fix a broken quorum child.
6717 If node is specified, it will be inserted under parent. child may not
6719 be specified in this case. If both parent and child are specified but
6720 node is not, child will be detached from parent.
6721 Arguments
6723 parent: string
6724 the id or name of the parent node.
6725 child: string (optional)
6727 the name of a child under the given parent node.
6728 node: string (optional)
6730 the name of the node that will be added.
6731 Note
6733 this command is experimental, and its API is not stable. It does not
6734 support all kinds of operations, all kinds of children, nor all block
6735 drivers.
6736 FIXME Removing children from a quorum node means introducing gaps in
6738 the child indices. This cannot be represented in the 'children' list of
6739 BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename().
6740 Warning: The data in a new quorum child MUST be consistent with that of
6742 the rest of the array.
6743 Since
6745 2.7
6746 Example
6748 1. Add a new node to a quorum
6749 -> { "execute": "blockdev-add",
6750 "arguments": {
6751 "driver": "raw",
6752 "node-name": "new_node",
6753 "file": { "driver": "file",
6754 "filename": "test.raw" } } }
6755 <- { "return": {} }
6756 -> { "execute": "x-blockdev-change",
6757 "arguments": { "parent": "disk1",
6758 "node": "new_node" } }
6759 <- { "return": {} }
6760 2. Delete a quorum's node
6762 -> { "execute": "x-blockdev-change",
6763 "arguments": { "parent": "disk1",
6764 "child": "children.1" } }
6765 <- { "return": {} }
6766 x-blockdev-set-iothread (Command)
6768 Move node and its children into the iothread. If iothread is null then
6769 move node and its children into the main loop.
6770 The node must not be attached to a BlockBackend.
6772 Arguments
6774 node-name: string
6775 the name of the block driver node
6776 iothread: StrOrNull
6778 the name of the IOThread object or null for the main loop
6779 force: boolean (optional)
6781 true if the node and its children should be moved when a Block‐
6782 Backend is already attached
6783 Note
6785 this command is experimental and intended for test cases that need con‐
6786 trol over IOThreads only.
6787 Since
6789 2.12
6790 Example
6792 1. Move a node into an IOThread
6793 -> { "execute": "x-blockdev-set-iothread",
6794 "arguments": { "node-name": "disk1",
6795 "iothread": "iothread0" } }
6796 <- { "return": {} }
6797 2. Move a node into the main loop
6799 -> { "execute": "x-blockdev-set-iothread",
6800 "arguments": { "node-name": "disk1",
6801 "iothread": null } }
6802 <- { "return": {} }
6803 QuorumOpType (Enum)
6805 An enumeration of the quorum operation types
6806 Values
6808 read read operation
6809 write write operation
6811 flush flush operation
6813 Since
6815 2.6
6816 QUORUM_FAILURE (Event)
6818 Emitted by the Quorum block driver if it fails to establish a quorum
6819 Arguments
6821 reference: string
6822 device name if defined else node name
6823 sector-num: int
6825 number of the first sector of the failed read operation
6826 sectors-count: int
6828 failed read operation sector count
6829 Note
6831 This event is rate-limited.
6832 Since
6834 2.0
6835 Example
6837 <- { "event": "QUORUM_FAILURE",
6838 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
6839 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
6840 QUORUM_REPORT_BAD (Event)
6842 Emitted to report a corruption of a Quorum file
6843 Arguments
6845 type: QuorumOpType
6846 quorum operation type (Since 2.6)
6847 error: string (optional)
6849 error message. Only present on failure. This field contains a
6850 human-readable error message. There are no semantics other than
6851 that the block layer reported an error and clients should not
6852 try to interpret the error string.
6853 node-name: string
6855 the graph node name of the block driver state
6856 sector-num: int
6858 number of the first sector of the failed read operation
6859 sectors-count: int
6861 failed read operation sector count
6862 Note
6864 This event is rate-limited.
6865 Since
6867 2.0
6868 Example
6870 1. Read operation
6871 { "event": "QUORUM_REPORT_BAD",
6873 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
6874 "type": "read" },
6875 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
6876 2. Flush operation
6878 { "event": "QUORUM_REPORT_BAD",
6880 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
6881 "type": "flush", "error": "Broken pipe" },
6882 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
6883 BlockdevSnapshotInternal (Object)
6885 Members
6886 device: string
6887 the device name or node-name of a root node to generate the
6888 snapshot from
6889 name: string
6891 the name of the internal snapshot to be created
6892 Notes
6894 In transaction, if name is empty, or any snapshot matching name exists,
6895 the operation will fail. Only some image formats support it, for exam‐
6896 ple, qcow2, rbd, and sheepdog.
6897 Since
6899 1.7
6900 blockdev-snapshot-internal-sync (Command)
6902 Synchronously take an internal snapshot of a block device, when the
6903 format of the image used supports it. If the name is an empty string,
6904 or a snapshot with name already exists, the operation will fail.
6905 For the arguments, see the documentation of BlockdevSnapshotInternal.
6907 Returns
6909 • nothing on success
6910 • If device is not a valid block device, GenericError
6912 • If any snapshot matching name exists, or name is empty, GenericError
6914 • If the format of the image used does not support it, BlockFormatFea‐
6916 tureNotSupported
6917 Since
6919 1.7
6920 Example
6922 -> { "execute": "blockdev-snapshot-internal-sync",
6923 "arguments": { "device": "ide-hd0",
6924 "name": "snapshot0" }
6925 }
6926 <- { "return": {} }
6927 blockdev-snapshot-delete-internal-sync (Command)
6929 Synchronously delete an internal snapshot of a block device, when the
6930 format of the image used support it. The snapshot is identified by name
6931 or id or both. One of the name or id is required. Return SnapshotInfo
6932 for the successfully deleted snapshot.
6933 Arguments
6935 device: string
6936 the device name or node-name of a root node to delete the snap‐
6937 shot from
6938 id: string (optional)
6940 optional the snapshot's ID to be deleted
6941 name: string (optional)
6943 optional the snapshot's name to be deleted
6944 Returns
6946 • SnapshotInfo on success
6947 • If device is not a valid block device, GenericError
6949 • If snapshot not found, GenericError
6951 • If the format of the image used does not support it, BlockFormatFea‐
6953 tureNotSupported
6954 • If id and name are both not specified, GenericError
6956 Since
6958 1.7
6959 Example
6961 -> { "execute": "blockdev-snapshot-delete-internal-sync",
6962 "arguments": { "device": "ide-hd0",
6963 "name": "snapshot0" }
6964 }
6965 <- { "return": {
6966 "id": "1",
6967 "name": "snapshot0",
6968 "vm-state-size": 0,
6969 "date-sec": 1000012,
6970 "date-nsec": 10,
6971 "vm-clock-sec": 100,
6972 "vm-clock-nsec": 20,
6973 "icount": 220414
6974 }
6975 }
6976 Additional block stuff (VM related)
6978 BiosAtaTranslation (Enum)
6979 Policy that BIOS should use to interpret cylinder/head/sector ad‐
6980 dresses. Note that Bochs BIOS and SeaBIOS will not actually translate
6981 logical CHS to physical; instead, they will use logical block address‐
6982 ing.
6983 Values
6985 auto If cylinder/heads/sizes are passed, choose between none and LBA
6986 depending on the size of the disk. If they are not passed,
6987 choose none if QEMU can guess that the disk had 16 or fewer
6988 heads, large if QEMU can guess that the disk had 131072 or fewer
6989 tracks across all heads (i.e. cylinders*heads<131072), otherwise
6990 LBA.
6991 none The physical disk geometry is equal to the logical geometry.
6993 lba Assume 63 sectors per track and one of 16, 32, 64, 128 or 255
6995 heads (if fewer than 255 are enough to cover the whole disk with
6996 1024 cylinders/head). The number of cylinders/head is then com‐
6997 puted based on the number of sectors and heads.
6998 large The number of cylinders per head is scaled down to 1024 by cor‐
7000 respondingly scaling up the number of heads.
7001 rechs Same as large, but first convert a 16-head geometry to 15-head,
7003 by proportionally scaling up the number of cylinders/head.
7004 Since
7006 2.0
7007 FloppyDriveType (Enum)
7009 Type of Floppy drive to be emulated by the Floppy Disk Controller.
7010 Values
7012 144 1.44MB 3.5" drive
7013 288 2.88MB 3.5" drive
7015 120 1.2MB 5.25" drive
7017 none No drive connected
7019 auto Automatically determined by inserted media at boot
7021 Since
7023 2.6
7024 PRManagerInfo (Object)
7026 Information about a persistent reservation manager
7027 Members
7029 id: string
7030 the identifier of the persistent reservation manager
7031 connected: boolean
7033 true if the persistent reservation manager is connected to the
7034 underlying storage or helper
7035 Since
7037 3.0
7038 query-pr-managers (Command)
7040 Returns a list of information about each persistent reservation man‐
7041 ager.
7042 Returns
7044 a list of PRManagerInfo for each persistent reservation manager
7045 Since
7047 3.0
7048 eject (Command)
7050 Ejects the medium from a removable drive.
7051 Arguments
7053 device: string (optional)
7054 Block device name
7055 id: string (optional)
7057 The name or QOM path of the guest device (since: 2.8)
7058 force: boolean (optional)
7060 If true, eject regardless of whether the drive is locked. If
7061 not specified, the default value is false.
7062 Features
7064 deprecated
7065 Member device is deprecated. Use id instead.
7066 Returns
7068 • Nothing on success
7069 • If device is not a valid block device, DeviceNotFound
7071 Notes
7073 Ejecting a device with no media results in success
7074 Since
7076 0.14.0
7077 Example
7079 -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
7080 <- { "return": {} }
7081 blockdev-open-tray (Command)
7083 Opens a block device's tray. If there is a block driver state tree in‐
7084 serted as a medium, it will become inaccessible to the guest (but it
7085 will remain associated to the block device, so closing the tray will
7086 make it accessible again).
7087 If the tray was already open before, this will be a no-op.
7089 Once the tray opens, a DEVICE_TRAY_MOVED event is emitted. There are
7091 cases in which no such event will be generated, these include:
7092 • if the guest has locked the tray, force is false and the guest does
7094 not respond to the eject request
7095 • if the BlockBackend denoted by device does not have a guest device
7097 attached to it
7098 • if the guest device does not have an actual tray
7100 Arguments
7102 device: string (optional)
7103 Block device name
7104 id: string (optional)
7106 The name or QOM path of the guest device (since: 2.8)
7107 force: boolean (optional)
7109 if false (the default), an eject request will be sent to the
7110 guest if it has locked the tray (and the tray will not be opened
7111 immediately); if true, the tray will be opened regardless of
7112 whether it is locked
7113 Features
7115 deprecated
7116 Member device is deprecated. Use id instead.
7117 Since
7119 2.5
7120 Example
7122 -> { "execute": "blockdev-open-tray",
7123 "arguments": { "id": "ide0-1-0" } }
7124 <- { "timestamp": { "seconds": 1418751016,
7126 "microseconds": 716996 },
7127 "event": "DEVICE_TRAY_MOVED",
7128 "data": { "device": "ide1-cd0",
7129 "id": "ide0-1-0",
7130 "tray-open": true } }
7131 <- { "return": {} }
7133 blockdev-close-tray (Command)
7135 Closes a block device's tray. If there is a block driver state tree as‐
7136 sociated with the block device (which is currently ejected), that tree
7137 will be loaded as the medium.
7138 If the tray was already closed before, this will be a no-op.
7140 Arguments
7142 device: string (optional)
7143 Block device name
7144 id: string (optional)
7146 The name or QOM path of the guest device (since: 2.8)
7147 Features
7149 deprecated
7150 Member device is deprecated. Use id instead.
7151 Since
7153 2.5
7154 Example
7156 -> { "execute": "blockdev-close-tray",
7157 "arguments": { "id": "ide0-1-0" } }
7158 <- { "timestamp": { "seconds": 1418751345,
7160 "microseconds": 272147 },
7161 "event": "DEVICE_TRAY_MOVED",
7162 "data": { "device": "ide1-cd0",
7163 "id": "ide0-1-0",
7164 "tray-open": false } }
7165 <- { "return": {} }
7167 blockdev-remove-medium (Command)
7169 Removes a medium (a block driver state tree) from a block device. That
7170 block device's tray must currently be open (unless there is no attached
7171 guest device).
7172 If the tray is open and there is no medium inserted, this will be a
7174 no-op.
7175 Arguments
7177 id: string
7178 The name or QOM path of the guest device
7179 Since
7181 2.12
7182 Example
7184 -> { "execute": "blockdev-remove-medium",
7185 "arguments": { "id": "ide0-1-0" } }
7186 <- { "error": { "class": "GenericError",
7188 "desc": "Tray of device 'ide0-1-0' is not open" } }
7189 -> { "execute": "blockdev-open-tray",
7191 "arguments": { "id": "ide0-1-0" } }
7192 <- { "timestamp": { "seconds": 1418751627,
7194 "microseconds": 549958 },
7195 "event": "DEVICE_TRAY_MOVED",
7196 "data": { "device": "ide1-cd0",
7197 "id": "ide0-1-0",
7198 "tray-open": true } }
7199 <- { "return": {} }
7201 -> { "execute": "blockdev-remove-medium",
7203 "arguments": { "id": "ide0-1-0" } }
7204 <- { "return": {} }
7206 blockdev-insert-medium (Command)
7208 Inserts a medium (a block driver state tree) into a block device. That
7209 block device's tray must currently be open (unless there is no attached
7210 guest device) and there must be no medium inserted already.
7211 Arguments
7213 id: string
7214 The name or QOM path of the guest device
7215 node-name: string
7217 name of a node in the block driver state graph
7218 Since
7220 2.12
7221 Example
7223 -> { "execute": "blockdev-add",
7224 "arguments": {
7225 "node-name": "node0",
7226 "driver": "raw",
7227 "file": { "driver": "file",
7228 "filename": "fedora.iso" } } }
7229 <- { "return": {} }
7230 -> { "execute": "blockdev-insert-medium",
7232 "arguments": { "id": "ide0-1-0",
7233 "node-name": "node0" } }
7234 <- { "return": {} }
7236 BlockdevChangeReadOnlyMode (Enum)
7238 Specifies the new read-only mode of a block device subject to the
7239 blockdev-change-medium command.
7240 Values
7242 retain Retains the current read-only mode
7243 read-only
7245 Makes the device read-only
7246 read-write
7248 Makes the device writable
7249 Since
7251 2.3
7252 blockdev-change-medium (Command)
7254 Changes the medium inserted into a block device by ejecting the current
7255 medium and loading a new image file which is inserted as the new medium
7256 (this command combines blockdev-open-tray, blockdev-remove-medium,
7257 blockdev-insert-medium and blockdev-close-tray).
7258 Arguments
7260 device: string (optional)
7261 Block device name
7262 id: string (optional)
7264 The name or QOM path of the guest device (since: 2.8)
7265 filename: string
7267 filename of the new image to be loaded
7268 format: string (optional)
7270 format to open the new image with (defaults to the probed for‐
7271 mat)
7272 read-only-mode: BlockdevChangeReadOnlyMode (optional)
7274 change the read-only mode of the device; defaults to 'retain'
7275 Features
7277 deprecated
7278 Member device is deprecated. Use id instead.
7279 Since
7281 2.5
7282 Examples
7284 1. Change a removable medium
7285 -> { "execute": "blockdev-change-medium",
7287 "arguments": { "id": "ide0-1-0",
7288 "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
7289 "format": "raw" } }
7290 <- { "return": {} }
7291 2. Load a read-only medium into a writable drive
7293 -> { "execute": "blockdev-change-medium",
7295 "arguments": { "id": "floppyA",
7296 "filename": "/srv/images/ro.img",
7297 "format": "raw",
7298 "read-only-mode": "retain" } }
7299 <- { "error":
7301 { "class": "GenericError",
7302 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
7303 -> { "execute": "blockdev-change-medium",
7305 "arguments": { "id": "floppyA",
7306 "filename": "/srv/images/ro.img",
7307 "format": "raw",
7308 "read-only-mode": "read-only" } }
7309 <- { "return": {} }
7311 DEVICE_TRAY_MOVED (Event)
7313 Emitted whenever the tray of a removable device is moved by the guest
7314 or by HMP/QMP commands
7315 Arguments
7317 device: string
7318 Block device name. This is always present for compatibility rea‐
7319 sons, but it can be empty ("") if the image does not have a de‐
7320 vice name associated.
7321 id: string
7323 The name or QOM path of the guest device (since 2.8)
7324 tray-open: boolean
7326 true if the tray has been opened or false if it has been closed
7327 Since
7329 1.1
7330 Example
7332 <- { "event": "DEVICE_TRAY_MOVED",
7333 "data": { "device": "ide1-cd0",
7334 "id": "/machine/unattached/device[22]",
7335 "tray-open": true
7336 },
7337 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7338 PR_MANAGER_STATUS_CHANGED (Event)
7340 Emitted whenever the connected status of a persistent reservation man‐
7341 ager changes.
7342 Arguments
7344 id: string
7345 The id of the PR manager object
7346 connected: boolean
7348 true if the PR manager is connected to a backend
7349 Since
7351 3.0
7352 Example
7354 <- { "event": "PR_MANAGER_STATUS_CHANGED",
7355 "data": { "id": "pr-helper0",
7356 "connected": true
7357 },
7358 "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
7359 block_set_io_throttle (Command)
7361 Change I/O throttle limits for a block drive.
7362 Since QEMU 2.4, each device with I/O limits is member of a throttle
7364 group.
7365 If two or more devices are members of the same group, the limits will
7367 apply to the combined I/O of the whole group in a round-robin fashion.
7368 Therefore, setting new I/O limits to a device will affect the whole
7369 group.
7370 The name of the group can be specified using the 'group' parameter. If
7372 the parameter is unset, it is assumed to be the current group of that
7373 device. If it's not in any group yet, the name of the device will be
7374 used as the name for its group.
7375 The 'group' parameter can also be used to move a device to a different
7377 group. In this case the limits specified in the parameters will be ap‐
7378 plied to the new group only.
7379 I/O limits can be disabled by setting all of them to 0. In this case
7381 the device will be removed from its group and the rest of its members
7382 will not be affected. The 'group' parameter is ignored.
7383 Arguments
7385 The members of BlockIOThrottle
7386 Returns
7388 • Nothing on success
7389 • If device is not a valid block device, DeviceNotFound
7391 Since
7393 1.1
7394 Example
7396 -> { "execute": "block_set_io_throttle",
7397 "arguments": { "id": "virtio-blk-pci0/virtio-backend",
7398 "bps": 0,
7399 "bps_rd": 0,
7400 "bps_wr": 0,
7401 "iops": 512,
7402 "iops_rd": 0,
7403 "iops_wr": 0,
7404 "bps_max": 0,
7405 "bps_rd_max": 0,
7406 "bps_wr_max": 0,
7407 "iops_max": 0,
7408 "iops_rd_max": 0,
7409 "iops_wr_max": 0,
7410 "bps_max_length": 0,
7411 "iops_size": 0 } }
7412 <- { "return": {} }
7413 -> { "execute": "block_set_io_throttle",
7415 "arguments": { "id": "ide0-1-0",
7416 "bps": 1000000,
7417 "bps_rd": 0,
7418 "bps_wr": 0,
7419 "iops": 0,
7420 "iops_rd": 0,
7421 "iops_wr": 0,
7422 "bps_max": 8000000,
7423 "bps_rd_max": 0,
7424 "bps_wr_max": 0,
7425 "iops_max": 0,
7426 "iops_rd_max": 0,
7427 "iops_wr_max": 0,
7428 "bps_max_length": 60,
7429 "iops_size": 0 } }
7430 <- { "return": {} }
7431 block-latency-histogram-set (Command)
7433 Manage read, write and flush latency histograms for the device.
7434 If only id parameter is specified, remove all present latency his‐
7436 tograms for the device. Otherwise, add/reset some of (or all) latency
7437 histograms.
7438 Arguments
7440 id: string
7441 The name or QOM path of the guest device.
7442 boundaries: array of int (optional)
7444 list of interval boundary values (see description in BlockLaten‐
7445 cyHistogramInfo definition). If specified, all latency his‐
7446 tograms are removed, and empty ones created for all io types
7447 with intervals corresponding to boundaries (except for io types,
7448 for which specific boundaries are set through the following pa‐
7449 rameters).
7450 boundaries-read: array of int (optional)
7452 list of interval boundary values for read latency histogram. If
7453 specified, old read latency histogram is removed, and empty one
7454 created with intervals corresponding to boundaries-read. The pa‐
7455 rameter has higher priority then boundaries.
7456 boundaries-write: array of int (optional)
7458 list of interval boundary values for write latency histogram.
7459 boundaries-flush: array of int (optional)
7461 list of interval boundary values for flush latency histogram.
7462 Returns
7464 error if device is not found or any boundary arrays are invalid.
7465 Since
7467 4.0
7468 Example
7470 set new histograms for all io types with intervals
7471 [0, 10), [10, 50), [50, 100), [100, +inf):
7472 -> { "execute": "block-latency-histogram-set",
7474 "arguments": { "id": "drive0",
7475 "boundaries": [10, 50, 100] } }
7476 <- { "return": {} }
7477 Example
7479 set new histogram only for write, other histograms will remain
7480 not changed (or not created):
7481 -> { "execute": "block-latency-histogram-set",
7483 "arguments": { "id": "drive0",
7484 "boundaries-write": [10, 50, 100] } }
7485 <- { "return": {} }
7486 Example
7488 set new histograms with the following intervals:
7489 read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
7490 write: [0, 1000), [1000, 5000), [5000, +inf)
7491 -> { "execute": "block-latency-histogram-set",
7493 "arguments": { "id": "drive0",
7494 "boundaries": [10, 50, 100],
7495 "boundaries-write": [1000, 5000] } }
7496 <- { "return": {} }
7497 Example
7499 remove all latency histograms:
7500 -> { "execute": "block-latency-histogram-set",
7502 "arguments": { "id": "drive0" } }
7503 <- { "return": {} }
7504 Block device exports
7506 NbdServerOptions (Object)
7507 Keep this type consistent with the nbd-server-start arguments. The only
7508 intended difference is using SocketAddress instead of SocketAddressLe‐
7509 gacy.
7510 Members
7512 addr: SocketAddress
7513 Address on which to listen.
7514 tls-creds: string (optional)
7516 ID of the TLS credentials object (since 2.6).
7517 tls-authz: string (optional)
7519 ID of the QAuthZ authorization object used to validate the
7520 client's x509 distinguished name. This object is is only re‐
7521 solved at time of use, so can be deleted and recreated on the
7522 fly while the NBD server is active. If missing, it will default
7523 to denying access (since 4.0).
7524 max-connections: int (optional)
7526 The maximum number of connections to allow at the same time, 0
7527 for unlimited. (since 5.2; default: 0)
7528 Since
7530 4.2
7531 nbd-server-start (Command)
7533 Start an NBD server listening on the given host and port. Block de‐
7534 vices can then be exported using nbd-server-add. The NBD server will
7535 present them as named exports; for example, another QEMU instance could
7536 refer to them as "nbd:HOST:PORT:exportname=NAME".
7537 Keep this type consistent with the NbdServerOptions type. The only in‐
7539 tended difference is using SocketAddressLegacy instead of SocketAd‐
7540 dress.
7541 Arguments
7543 addr: SocketAddressLegacy
7544 Address on which to listen.
7545 tls-creds: string (optional)
7547 ID of the TLS credentials object (since 2.6).
7548 tls-authz: string (optional)
7550 ID of the QAuthZ authorization object used to validate the
7551 client's x509 distinguished name. This object is is only re‐
7552 solved at time of use, so can be deleted and recreated on the
7553 fly while the NBD server is active. If missing, it will default
7554 to denying access (since 4.0).
7555 max-connections: int (optional)
7557 The maximum number of connections to allow at the same time, 0
7558 for unlimited. (since 5.2; default: 0)
7559 Returns
7561 error if the server is already running.
7562 Since
7564 1.3.0
7565 BlockExportOptionsNbdBase (Object)
7567 An NBD block export (common options shared between nbd-server-add and
7568 the NBD branch of block-export-add).
7569 Members
7571 name: string (optional)
7572 Export name. If unspecified, the device parameter is used as the
7573 export name. (Since 2.12)
7574 description: string (optional)
7576 Free-form description of the export, up to 4096 bytes. (Since
7577 5.0)
7578 Since
7580 5.0
7581 BlockExportOptionsNbd (Object)
7583 An NBD block export (distinct options used in the NBD branch of
7584 block-export-add).
7585 Members
7587 bitmaps: array of string (optional)
7588 Also export each of the named dirty bitmaps reachable from de‐
7589 vice, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
7590 the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
7591 each bitmap.
7592 allocation-depth: boolean (optional)
7594 Also export the allocation depth map for device, so the NBD
7595 client can use NBD_OPT_SET_META_CONTEXT with the metadata con‐
7596 text name "qemu:allocation-depth" to inspect allocation details.
7597 (since 5.2)
7598 The members of BlockExportOptionsNbdBase
7600 Since
7602 5.2
7603 BlockExportOptionsVhostUserBlk (Object)
7605 A vhost-user-blk block export.
7606 Members
7608 addr: SocketAddress
7609 The vhost-user socket on which to listen. Both 'unix' and 'fd'
7610 SocketAddress types are supported. Passed fds must be UNIX do‐
7611 main sockets.
7612 logical-block-size: int (optional)
7614 Logical block size in bytes. Defaults to 512 bytes.
7615 num-queues: int (optional)
7617 Number of request virtqueues. Must be greater than 0. Defaults
7618 to 1.
7619 Since
7621 5.2
7622 NbdServerAddOptions (Object)
7624 An NBD block export, per legacy nbd-server-add command.
7625 Members
7627 device: string
7628 The device name or node name of the node to be exported
7629 writable: boolean (optional)
7631 Whether clients should be able to write to the device via the
7632 NBD connection (default false).
7633 bitmap: string (optional)
7635 Also export a single dirty bitmap reachable from device, so the
7636 NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
7637 context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
7638 (since 4.0).
7639 The members of BlockExportOptionsNbdBase
7641 Since
7643 5.0
7644 nbd-server-add (Command)
7646 Export a block node to QEMU's embedded NBD server.
7647 The export name will be used as the id for the resulting block export.
7649 Arguments
7651 The members of NbdServerAddOptions
7652 Features
7654 deprecated
7655 This command is deprecated. Use block-export-add instead.
7656 Returns
7658 error if the server is not running, or export with the same name al‐
7659 ready exists.
7660 Since
7662 1.3.0
7663 BlockExportRemoveMode (Enum)
7665 Mode for removing a block export.
7666 Values
7668 safe Remove export if there are no existing connections, fail other‐
7669 wise.
7670 hard Drop all connections immediately and remove export.
7672 Potential additional modes to be added in the future:
7673 hide: Just hide export from new clients, leave existing connections as
7675 is. Remove export after all clients are disconnected.
7676 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
7678 ther requests from existing clients.
7679 Since
7681 2.12
7682 nbd-server-remove (Command)
7684 Remove NBD export by name.
7685 Arguments
7687 name: string
7688 Block export id.
7689 mode: BlockExportRemoveMode (optional)
7691 Mode of command operation. See BlockExportRemoveMode descrip‐
7692 tion. Default is 'safe'.
7693 Features
7695 deprecated
7696 This command is deprecated. Use block-export-del instead.
7697 Returns
7699 error if
7700 • the server is not running
7702 • export is not found
7704 • mode is 'safe' and there are existing connections
7706 Since
7708 2.12
7709 nbd-server-stop (Command)
7711 Stop QEMU's embedded NBD server, and unregister all devices previously
7712 added via nbd-server-add.
7713 Since
7715 1.3.0
7716 BlockExportType (Enum)
7718 An enumeration of block export types
7719 Values
7721 nbd NBD export
7722 vhost-user-blk
7724 vhost-user-blk export (since 5.2)
7725 Since
7727 4.2
7728 BlockExportOptions (Object)
7730 Describes a block export, i.e. how single node should be exported on an
7731 external interface.
7732 Members
7734 id: string
7735 A unique identifier for the block export (across all export
7736 types)
7737 node-name: string
7739 The node name of the block node to be exported (since: 5.2)
7740 writable: boolean (optional)
7742 True if clients should be able to write to the export (default
7743 false)
7744 writethrough: boolean (optional)
7746 If true, caches are flushed after every write request to the ex‐
7747 port before completion is signalled. (since: 5.2; default:
7748 false)
7749 iothread: string (optional)
7751 The name of the iothread object where the export will run. The
7752 default is to use the thread currently associated with the block
7753 node. (since: 5.2)
7754 fixed-iothread: boolean (optional)
7756 True prevents the block node from being moved to another thread
7757 while the export is active. If true and iothread is given, ex‐
7758 port creation fails if the block node cannot be moved to the io‐
7759 thread. The default is false. (since: 5.2)
7760 type: BlockExportType
7762 Not documented
7763 The members of BlockExportOptionsNbd when type is "nbd"
7765 The members of BlockExportOptionsVhostUserBlk when type is
7767 "vhost-user-blk"
7768 Since
7770 4.2
7771 block-export-add (Command)
7773 Creates a new block export.
7774 Arguments
7776 The members of BlockExportOptions
7777 Since
7779 5.2
7780 block-export-del (Command)
7782 Request to remove a block export. This drops the user's reference to
7783 the export, but the export may still stay around after this command re‐
7784 turns until the shutdown of the export has completed.
7785 Arguments
7787 id: string
7788 Block export id.
7789 mode: BlockExportRemoveMode (optional)
7791 Mode of command operation. See BlockExportRemoveMode descrip‐
7792 tion. Default is 'safe'.
7793 Returns
7795 Error if the export is not found or mode is 'safe' and the export is
7796 still in use (e.g. by existing client connections)
7797 Since
7799 5.2
7800 BLOCK_EXPORT_DELETED (Event)
7802 Emitted when a block export is removed and its id can be reused.
7803 Arguments
7805 id: string
7806 Block export id.
7807 Since
7809 5.2
7810 BlockExportInfo (Object)
7812 Information about a single block export.
7813 Members
7815 id: string
7816 The unique identifier for the block export
7817 type: BlockExportType
7819 The block export type
7820 node-name: string
7822 The node name of the block node that is exported
7823 shutting-down: boolean
7825 True if the export is shutting down (e.g. after a block-ex‐
7826 port-del command, but before the shutdown has completed)
7827 Since
7829 5.2
7830 query-block-exports (Command)
7832 Returns
7833 A list of BlockExportInfo describing all block exports
7834 Since
7836 5.2
7837
7839 ChardevInfo (Object)
7840 Information about a character device.
7841 Members
7843 label: string
7844 the label of the character device
7845 filename: string
7847 the filename of the character device
7848 frontend-open: boolean
7850 shows whether the frontend device attached to this backend (eg.
7851 with the chardev=... option) is in open or closed state (since
7852 2.1)
7853 Notes
7855 filename is encoded using the QEMU command line character device encod‐
7856 ing. See the QEMU man page for details.
7857 Since
7859 0.14.0
7860 query-chardev (Command)
7862 Returns information about current character devices.
7863 Returns
7865 a list of ChardevInfo
7866 Since
7868 0.14.0
7869 Example
7871 -> { "execute": "query-chardev" }
7872 <- {
7873 "return": [
7874 {
7875 "label": "charchannel0",
7876 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
7877 "frontend-open": false
7878 },
7879 {
7880 "label": "charmonitor",
7881 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
7882 "frontend-open": true
7883 },
7884 {
7885 "label": "charserial0",
7886 "filename": "pty:/dev/pts/2",
7887 "frontend-open": true
7888 }
7889 ]
7890 }
7891 ChardevBackendInfo (Object)
7893 Information about a character device backend
7894 Members
7896 name: string
7897 The backend name
7898 Since
7900 2.0
7901 query-chardev-backends (Command)
7903 Returns information about character device backends.
7904 Returns
7906 a list of ChardevBackendInfo
7907 Since
7909 2.0
7910 Example
7912 -> { "execute": "query-chardev-backends" }
7913 <- {
7914 "return":[
7915 {
7916 "name":"udp"
7917 },
7918 {
7919 "name":"tcp"
7920 },
7921 {
7922 "name":"unix"
7923 },
7924 {
7925 "name":"spiceport"
7926 }
7927 ]
7928 }
7929 DataFormat (Enum)
7931 An enumeration of data format.
7932 Values
7934 utf8 Data is a UTF-8 string (RFC 3629)
7935 base64 Data is Base64 encoded binary (RFC 3548)
7937 Since
7939 1.4
7940 ringbuf-write (Command)
7942 Write to a ring buffer character device.
7943 Arguments
7945 device: string
7946 the ring buffer character device name
7947 data: string
7949 data to write
7950 format: DataFormat (optional)
7952 data encoding (default 'utf8').
7953 • base64: data must be base64 encoded text. Its binary decoding
7955 gets written.
7956 • utf8: data's UTF-8 encoding is written
7958 • data itself is always Unicode regardless of format, like any
7960 other string.
7961 Returns
7963 Nothing on success
7964 Since
7966 1.4
7967 Example
7969 -> { "execute": "ringbuf-write",
7970 "arguments": { "device": "foo",
7971 "data": "abcdefgh",
7972 "format": "utf8" } }
7973 <- { "return": {} }
7974 ringbuf-read (Command)
7976 Read from a ring buffer character device.
7977 Arguments
7979 device: string
7980 the ring buffer character device name
7981 size: int
7983 how many bytes to read at most
7984 format: DataFormat (optional)
7986 data encoding (default 'utf8').
7987 • base64: the data read is returned in base64 encoding.
7989 • utf8: the data read is interpreted as UTF-8. Bug: can screw
7991 up when the buffer contains invalid UTF-8 sequences, NUL char‐
7992 acters, after the ring buffer lost data, and when reading
7993 stops because the size limit is reached.
7994 • The return value is always Unicode regardless of format, like
7996 any other string.
7997 Returns
7999 data read from the device
8000 Since
8002 1.4
8003 Example
8005 -> { "execute": "ringbuf-read",
8006 "arguments": { "device": "foo",
8007 "size": 1000,
8008 "format": "utf8" } }
8009 <- { "return": "abcdefgh" }
8010 ChardevCommon (Object)
8012 Configuration shared across all chardev backends
8013 Members
8015 logfile: string (optional)
8016 The name of a logfile to save output
8017 logappend: boolean (optional)
8019 true to append instead of truncate (default to false to trun‐
8020 cate)
8021 Since
8023 2.6
8024 ChardevFile (Object)
8026 Configuration info for file chardevs.
8027 Members
8029 in: string (optional)
8030 The name of the input file
8031 out: string
8033 The name of the output file
8034 append: boolean (optional)
8036 Open the file in append mode (default false to truncate) (Since
8037 2.6)
8038 The members of ChardevCommon
8040 Since
8042 1.4
8043 ChardevHostdev (Object)
8045 Configuration info for device and pipe chardevs.
8046 Members
8048 device: string
8049 The name of the special file for the device, i.e. /dev/ttyS0 on
8050 Unix or COM1: on Windows
8051 The members of ChardevCommon
8053 Since
8055 1.4
8056 ChardevSocket (Object)
8058 Configuration info for (stream) socket chardevs.
8059 Members
8061 addr: SocketAddressLegacy
8062 socket address to listen on (server=true) or connect to
8063 (server=false)
8064 tls-creds: string (optional)
8066 the ID of the TLS credentials object (since 2.6)
8067 tls-authz: string (optional)
8069 the ID of the QAuthZ authorization object against which the
8070 client's x509 distinguished name will be validated. This object
8071 is only resolved at time of use, so can be deleted and recreated
8072 on the fly while the chardev server is active. If missing, it
8073 will default to denying access (since 4.0)
8074 server: boolean (optional)
8076 create server socket (default: true)
8077 wait: boolean (optional)
8079 wait for incoming connection on server sockets (default: false).
8080 Silently ignored with server: false. This use is deprecated.
8081 nodelay: boolean (optional)
8083 set TCP_NODELAY socket option (default: false)
8084 telnet: boolean (optional)
8086 enable telnet protocol on server sockets (default: false)
8087 tn3270: boolean (optional)
8089 enable tn3270 protocol on server sockets (default: false)
8090 (Since: 2.10)
8091 websocket: boolean (optional)
8093 enable websocket protocol on server sockets (default: false)
8094 (Since: 3.1)
8095 reconnect: int (optional)
8097 For a client socket, if a socket is disconnected, then attempt a
8098 reconnect after the given number of seconds. Setting this to
8099 zero disables this function. (default: 0) (Since: 2.2)
8100 The members of ChardevCommon
8102 Since
8104 1.4
8105 ChardevUdp (Object)
8107 Configuration info for datagram socket chardevs.
8108 Members
8110 remote: SocketAddressLegacy
8111 remote address
8112 local: SocketAddressLegacy (optional)
8114 local address
8115 The members of ChardevCommon
8117 Since
8119 1.5
8120 ChardevMux (Object)
8122 Configuration info for mux chardevs.
8123 Members
8125 chardev: string
8126 name of the base chardev.
8127 The members of ChardevCommon
8129 Since
8131 1.5
8132 ChardevStdio (Object)
8134 Configuration info for stdio chardevs.
8135 Members
8137 signal: boolean (optional)
8138 Allow signals (such as SIGINT triggered by ^C) be delivered to
8139 qemu. Default: true.
8140 The members of ChardevCommon
8142 Since
8144 1.5
8145 ChardevSpiceChannel (Object)
8147 Configuration info for spice vm channel chardevs.
8148 Members
8150 type: string
8151 kind of channel (for example vdagent).
8152 The members of ChardevCommon
8154 Since
8156 1.5
8157 If
8159 defined(CONFIG_SPICE).SS ChardevSpicePort (Object)
8160 Configuration info for spice port chardevs.
8162 Members
8164 fqdn: string
8165 name of the channel (see docs/spice-port-fqdn.txt)
8166 The members of ChardevCommon
8168 Since
8170 1.5
8171 If
8173 defined(CONFIG_SPICE).SS ChardevVC (Object)
8174 Configuration info for virtual console chardevs.
8176 Members
8178 width: int (optional)
8179 console width, in pixels
8180 height: int (optional)
8182 console height, in pixels
8183 cols: int (optional)
8185 console width, in chars
8186 rows: int (optional)
8188 console height, in chars
8189 The members of ChardevCommon
8191 Since
8193 1.5
8194 ChardevRingbuf (Object)
8196 Configuration info for ring buffer chardevs.
8197 Members
8199 size: int (optional)
8200 ring buffer size, must be power of two, default is 65536
8201 The members of ChardevCommon
8203 Since
8205 1.5
8206 ChardevBackend (Object)
8208 Configuration info for the new chardev backend.
8209 Members
8211 type One of file, serial, parallel, pipe, socket, udp, pty, null,
8212 mux, msmouse, wctablet, braille, testdev, stdio, console,
8213 spicevmc, spiceport, vc, ringbuf, memory
8214 data: ChardevFile when type is "file"
8216 data: ChardevHostdev when type is "serial"
8218 data: ChardevHostdev when type is "parallel"
8220 data: ChardevHostdev when type is "pipe"
8222 data: ChardevSocket when type is "socket"
8224 data: ChardevUdp when type is "udp"
8226 data: ChardevCommon when type is "pty"
8228 data: ChardevCommon when type is "null"
8230 data: ChardevMux when type is "mux"
8232 data: ChardevCommon when type is "msmouse"
8234 data: ChardevCommon when type is "wctablet"
8236 data: ChardevCommon when type is "braille"
8238 data: ChardevCommon when type is "testdev"
8240 data: ChardevStdio when type is "stdio"
8242 data: ChardevCommon when type is "console"
8244 data: ChardevSpiceChannel when type is "spicevmc" (If: defined(CON‐
8246 FIG_SPICE))
8247 data: ChardevSpicePort when type is "spiceport" (If: defined(CON‐
8249 FIG_SPICE))
8250 data: ChardevVC when type is "vc"
8252 data: ChardevRingbuf when type is "ringbuf"
8254 data: ChardevRingbuf when type is "memory"
8256 Since
8258 1.4 (testdev since 2.2, wctablet since 2.9)
8259 ChardevReturn (Object)
8261 Return info about the chardev backend just created.
8262 Members
8264 pty: string (optional)
8265 name of the slave pseudoterminal device, present if and only if
8266 a chardev of type 'pty' was created
8267 Since
8269 1.4
8270 chardev-add (Command)
8272 Add a character device backend
8273 Arguments
8275 id: string
8276 the chardev's ID, must be unique
8277 backend: ChardevBackend
8279 backend type and parameters
8280 Returns
8282 ChardevReturn.
8283 Since
8285 1.4
8286 Example
8288 -> { "execute" : "chardev-add",
8289 "arguments" : { "id" : "foo",
8290 "backend" : { "type" : "null", "data" : {} } } }
8291 <- { "return": {} }
8292 -> { "execute" : "chardev-add",
8294 "arguments" : { "id" : "bar",
8295 "backend" : { "type" : "file",
8296 "data" : { "out" : "/tmp/bar.log" } } } }
8297 <- { "return": {} }
8298 -> { "execute" : "chardev-add",
8300 "arguments" : { "id" : "baz",
8301 "backend" : { "type" : "pty", "data" : {} } } }
8302 <- { "return": { "pty" : "/dev/pty/42" } }
8303 chardev-change (Command)
8305 Change a character device backend
8306 Arguments
8308 id: string
8309 the chardev's ID, must exist
8310 backend: ChardevBackend
8312 new backend type and parameters
8313 Returns
8315 ChardevReturn.
8316 Since
8318 2.10
8319 Example
8321 -> { "execute" : "chardev-change",
8322 "arguments" : { "id" : "baz",
8323 "backend" : { "type" : "pty", "data" : {} } } }
8324 <- { "return": { "pty" : "/dev/pty/42" } }
8325 -> {"execute" : "chardev-change",
8327 "arguments" : {
8328 "id" : "charchannel2",
8329 "backend" : {
8330 "type" : "socket",
8331 "data" : {
8332 "addr" : {
8333 "type" : "unix" ,
8334 "data" : {
8335 "path" : "/tmp/charchannel2.socket"
8336 }
8337 },
8338 "server" : true,
8339 "wait" : false }}}}
8340 <- {"return": {}}
8341 chardev-remove (Command)
8343 Remove a character device backend
8344 Arguments
8346 id: string
8347 the chardev's ID, must exist and not be in use
8348 Returns
8350 Nothing on success
8351 Since
8353 1.4
8354 Example
8356 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
8357 <- { "return": {} }
8358 chardev-send-break (Command)
8360 Send a break to a character device
8361 Arguments
8363 id: string
8364 the chardev's ID, must exist
8365 Returns
8367 Nothing on success
8368 Since
8370 2.10
8371 Example
8373 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
8374 <- { "return": {} }
8375 VSERPORT_CHANGE (Event)
8377 Emitted when the guest opens or closes a virtio-serial port.
8378 Arguments
8380 id: string
8381 device identifier of the virtio-serial port
8382 open: boolean
8384 true if the guest has opened the virtio-serial port
8385 Note
8387 This event is rate-limited.
8388 Since
8390 2.1
8391 Example
8393 <- { "event": "VSERPORT_CHANGE",
8394 "data": { "id": "channel0", "open": true },
8395 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
8396
8398 DumpGuestMemoryFormat (Enum)
8399 An enumeration of guest-memory-dump's format.
8400 Values
8402 elf elf format
8403 kdump-zlib
8405 kdump-compressed format with zlib-compressed
8406 kdump-lzo
8408 kdump-compressed format with lzo-compressed
8409 kdump-snappy
8411 kdump-compressed format with snappy-compressed
8412 win-dmp
8414 Windows full crashdump format, can be used instead of ELF con‐
8415 verting (since 2.13)
8416 Since
8418 2.0
8419 dump-guest-memory (Command)
8421 Dump guest's memory to vmcore. It is a synchronous operation that can
8422 take very long depending on the amount of guest memory.
8423 Arguments
8425 paging: boolean
8426 if true, do paging to get guest's memory mapping. This allows
8427 using gdb to process the core file.
8428 IMPORTANT: this option can make QEMU allocate several gigabytes
8430 of RAM. This can happen for a large guest, or a malicious guest
8431 pretending to be large.
8432 Also, paging=true has the following limitations:
8434 1. The guest may be in a catastrophic state or can have cor‐
8436 rupted memory, which cannot be trusted
8437 2. The guest can be in real-mode even if paging is enabled.
8439 For example, the guest uses ACPI to sleep, and ACPI sleep
8440 state goes in real-mode
8441 3. Currently only supported on i386 and x86_64.
8443 protocol: string
8445 the filename or file descriptor of the vmcore. The supported
8446 protocols are:
8447 1. file: the protocol starts with "file:", and the following
8449 string is the file's path.
8450 2. fd: the protocol starts with "fd:", and the following string
8452 is the fd's name.
8453 detach: boolean (optional)
8455 if true, QMP will return immediately rather than waiting for the
8456 dump to finish. The user can track progress using "query-dump".
8457 (since 2.6).
8458 begin: int (optional)
8460 if specified, the starting physical address.
8461 length: int (optional)
8463 if specified, the memory size, in bytes. If you don't want to
8464 dump all guest's memory, please specify the start begin and
8465 length
8466 format: DumpGuestMemoryFormat (optional)
8468 if specified, the format of guest memory dump. But non-elf for‐
8469 mat is conflict with paging and filter, ie. paging, begin and
8470 length is not allowed to be specified with non-elf format at the
8471 same time (since 2.0)
8472 Note
8474 All boolean arguments default to false
8475 Returns
8477 nothing on success
8478 Since
8480 1.2
8481 Example
8483 -> { "execute": "dump-guest-memory",
8484 "arguments": { "protocol": "fd:dump" } }
8485 <- { "return": {} }
8486 DumpStatus (Enum)
8488 Describe the status of a long-running background guest memory dump.
8489 Values
8491 none no dump-guest-memory has started yet.
8492 active there is one dump running in background.
8494 completed
8496 the last dump has finished successfully.
8497 failed the last dump has failed.
8499 Since
8501 2.6
8502 DumpQueryResult (Object)
8504 The result format for 'query-dump'.
8505 Members
8507 status: DumpStatus
8508 enum of DumpStatus, which shows current dump status
8509 completed: int
8511 bytes written in latest dump (uncompressed)
8512 total: int
8514 total bytes to be written in latest dump (uncompressed)
8515 Since
8517 2.6
8518 query-dump (Command)
8520 Query latest dump status.
8521 Returns
8523 A DumpStatus object showing the dump status.
8524 Since
8526 2.6
8527 Example
8529 -> { "execute": "query-dump" }
8530 <- { "return": { "status": "active", "completed": 1024000,
8531 "total": 2048000 } }
8532 DUMP_COMPLETED (Event)
8534 Emitted when background dump has completed
8535 Arguments
8537 result: DumpQueryResult
8538 final dump status
8539 error: string (optional)
8541 human-readable error string that provides hint on why dump
8542 failed. Only presents on failure. The user should not try to in‐
8543 terpret the error string.
8544 Since
8546 2.6
8547 Example
8549 { "event": "DUMP_COMPLETED",
8550 "data": {"result": {"total": 1090650112, "status": "completed",
8551 "completed": 1090650112} } }
8552 DumpGuestMemoryCapability (Object)
8554 A list of the available formats for dump-guest-memory
8555 Members
8557 formats: array of DumpGuestMemoryFormat
8558 Not documented
8559 Since
8561 2.0
8562 query-dump-guest-memory-capability (Command)
8564 Returns the available formats for dump-guest-memory
8565 Returns
8567 A DumpGuestMemoryCapability object listing available formats for
8568 dump-guest-memory
8569 Since
8571 2.0
8572 Example
8574 -> { "execute": "query-dump-guest-memory-capability" }
8575 <- { "return": { "formats":
8576 ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
8577
8579 set_link (Command)
8580 Sets the link status of a virtual network adapter.
8581 Arguments
8583 name: string
8584 the device name of the virtual network adapter
8585 up: boolean
8587 true to set the link status to be up
8588 Returns
8590 Nothing on success If name is not a valid network device, DeviceNot‐
8591 Found
8592 Since
8594 0.14.0
8595 Notes
8597 Not all network adapters support setting link status. This command
8598 will succeed even if the network adapter does not support link status
8599 notification.
8600 Example
8602 -> { "execute": "set_link",
8603 "arguments": { "name": "e1000.0", "up": false } }
8604 <- { "return": {} }
8605 netdev_add (Command)
8607 Add a network backend.
8608 Additional arguments depend on the type.
8610 Arguments
8612 The members of Netdev
8613 Since
8615 0.14.0
8616 Returns
8618 Nothing on success If type is not a valid network backend, DeviceNot‐
8619 Found
8620 Example
8622 -> { "execute": "netdev_add",
8623 "arguments": { "type": "user", "id": "netdev1",
8624 "dnssearch": "example.org" } }
8625 <- { "return": {} }
8626 netdev_del (Command)
8628 Remove a network backend.
8629 Arguments
8631 id: string
8632 the name of the network backend to remove
8633 Returns
8635 Nothing on success If id is not a valid network backend, DeviceNotFound
8636 Since
8638 0.14.0
8639 Example
8641 -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
8642 <- { "return": {} }
8643 NetLegacyNicOptions (Object)
8645 Create a new Network Interface Card.
8646 Members
8648 netdev: string (optional)
8649 id of -netdev to connect to
8650 macaddr: string (optional)
8652 MAC address
8653 model: string (optional)
8655 device model (e1000, rtl8139, virtio etc.)
8656 addr: string (optional)
8658 PCI device address
8659 vectors: int (optional)
8661 number of MSI-x vectors, 0 to disable MSI-X
8662 Since
8664 1.2
8665 NetdevUserOptions (Object)
8667 Use the user mode network stack which requires no administrator privi‐
8668 lege to run.
8669 Members
8671 hostname: string (optional)
8672 client hostname reported by the builtin DHCP server
8673 restrict: boolean (optional)
8675 isolate the guest from the host
8676 ipv4: boolean (optional)
8678 whether to support IPv4, default true for enabled (since 2.6)
8679 ipv6: boolean (optional)
8681 whether to support IPv6, default true for enabled (since 2.6)
8682 ip: string (optional)
8684 legacy parameter, use net= instead
8685 net: string (optional)
8687 IP network address that the guest will see, in the form
8688 addr[/netmask] The netmask is optional, and can be either in the
8689 form a.b.c.d or as a number of valid top-most bits. Default is
8690 10.0.2.0/24.
8691 host: string (optional)
8693 guest-visible address of the host
8694 tftp: string (optional)
8696 root directory of the built-in TFTP server
8697 bootfile: string (optional)
8699 BOOTP filename, for use with tftp=
8700 dhcpstart: string (optional)
8702 the first of the 16 IPs the built-in DHCP server can assign
8703 dns: string (optional)
8705 guest-visible address of the virtual nameserver
8706 dnssearch: array of String (optional)
8708 list of DNS suffixes to search, passed as DHCP option to the
8709 guest
8710 domainname: string (optional)
8712 guest-visible domain name of the virtual nameserver (since 3.0)
8713 ipv6-prefix: string (optional)
8715 IPv6 network prefix (default is fec0::) (since 2.6). The network
8716 prefix is given in the usual hexadecimal IPv6 address notation.
8717 ipv6-prefixlen: int (optional)
8719 IPv6 network prefix length (default is 64) (since 2.6)
8720 ipv6-host: string (optional)
8722 guest-visible IPv6 address of the host (since 2.6)
8723 ipv6-dns: string (optional)
8725 guest-visible IPv6 address of the virtual nameserver (since 2.6)
8726 smb: string (optional)
8728 root directory of the built-in SMB server
8729 smbserver: string (optional)
8731 IP address of the built-in SMB server
8732 hostfwd: array of String (optional)
8734 redirect incoming TCP or UDP host connections to guest endpoints
8735 guestfwd: array of String (optional)
8737 forward guest TCP connections
8738 tftp-server-name: string (optional)
8740 RFC2132 "TFTP server name" string (Since 3.1)
8741 Since
8743 1.2
8744 NetdevTapOptions (Object)
8746 Used to configure a host TAP network interface backend.
8747 Members
8749 ifname: string (optional)
8750 interface name
8751 fd: string (optional)
8753 file descriptor of an already opened tap
8754 fds: string (optional)
8756 multiple file descriptors of already opened multiqueue capable
8757 tap
8758 script: string (optional)
8760 script to initialize the interface
8761 downscript: string (optional)
8763 script to shut down the interface
8764 br: string (optional)
8766 bridge name (since 2.8)
8767 helper: string (optional)
8769 command to execute to configure bridge
8770 sndbuf: int (optional)
8772 send buffer limit. Understands [TGMKkb] suffixes.
8773 vnet_hdr: boolean (optional)
8775 enable the IFF_VNET_HDR flag on the tap interface
8776 vhost: boolean (optional)
8778 enable vhost-net network accelerator
8779 vhostfd: string (optional)
8781 file descriptor of an already opened vhost net device
8782 vhostfds: string (optional)
8784 file descriptors of multiple already opened vhost net devices
8785 vhostforce: boolean (optional)
8787 vhost on for non-MSIX virtio guests
8788 queues: int (optional)
8790 number of queues to be created for multiqueue capable tap
8791 poll-us: int (optional)
8793 maximum number of microseconds that could be spent on busy
8794 polling for tap (since 2.7)
8795 Since
8797 1.2
8798 NetdevSocketOptions (Object)
8800 Socket netdevs are used to establish a network connection to another
8801 QEMU virtual machine via a TCP socket.
8802 Members
8804 fd: string (optional)
8805 file descriptor of an already opened socket
8806 listen: string (optional)
8808 port number, and optional hostname, to listen on
8809 connect: string (optional)
8811 port number, and optional hostname, to connect to
8812 mcast: string (optional)
8814 UDP multicast address and port number
8815 localaddr: string (optional)
8817 source address and port for multicast and udp packets
8818 udp: string (optional)
8820 UDP unicast address and port number
8821 Since
8823 1.2
8824 NetdevL2TPv3Options (Object)
8826 Configure an Ethernet over L2TPv3 tunnel.
8827 Members
8829 src: string
8830 source address
8831 dst: string
8833 destination address
8834 srcport: string (optional)
8836 source port - mandatory for udp, optional for ip
8837 dstport: string (optional)
8839 destination port - mandatory for udp, optional for ip
8840 ipv6: boolean (optional)
8842 force the use of ipv6
8843 udp: boolean (optional)
8845 use the udp version of l2tpv3 encapsulation
8846 cookie64: boolean (optional)
8848 use 64 bit coookies
8849 counter: boolean (optional)
8851 have sequence counter
8852 pincounter: boolean (optional)
8854 pin sequence counter to zero - workaround for buggy implementa‐
8855 tions or networks with packet reorder
8856 txcookie: int (optional)
8858 32 or 64 bit transmit cookie
8859 rxcookie: int (optional)
8861 32 or 64 bit receive cookie
8862 txsession: int
8864 32 bit transmit session
8865 rxsession: int (optional)
8867 32 bit receive session - if not specified set to the same value
8868 as transmit
8869 offset: int (optional)
8871 additional offset - allows the insertion of additional applica‐
8872 tion-specific data before the packet payload
8873 Since
8875 2.1
8876 NetdevVdeOptions (Object)
8878 Connect to a vde switch running on the host.
8879 Members
8881 sock: string (optional)
8882 socket path
8883 port: int (optional)
8885 port number
8886 group: string (optional)
8888 group owner of socket
8889 mode: int (optional)
8891 permissions for socket
8892 Since
8894 1.2
8895 NetdevBridgeOptions (Object)
8897 Connect a host TAP network interface to a host bridge device.
8898 Members
8900 br: string (optional)
8901 bridge name
8902 helper: string (optional)
8904 command to execute to configure bridge
8905 Since
8907 1.2
8908 NetdevHubPortOptions (Object)
8910 Connect two or more net clients through a software hub.
8911 Members
8913 hubid: int
8914 hub identifier number
8915 netdev: string (optional)
8917 used to connect hub to a netdev instead of a device (since 2.12)
8918 Since
8920 1.2
8921 NetdevNetmapOptions (Object)
8923 Connect a client to a netmap-enabled NIC or to a VALE switch port
8924 Members
8926 ifname: string
8927 Either the name of an existing network interface supported by
8928 netmap, or the name of a VALE port (created on the fly). A VALE
8929 port name is in the form 'valeXXX:YYY', where XXX and YYY are
8930 non-negative integers. XXX identifies a switch and YYY identi‐
8931 fies a port of the switch. VALE ports having the same XXX are
8932 therefore connected to the same switch.
8933 devname: string (optional)
8935 path of the netmap device (default: '/dev/netmap').
8936 Since
8938 2.0
8939 NetdevVhostUserOptions (Object)
8941 Vhost-user network backend
8942 Members
8944 chardev: string
8945 name of a unix socket chardev
8946 vhostforce: boolean (optional)
8948 vhost on for non-MSIX virtio guests (default: false).
8949 queues: int (optional)
8951 number of queues to be created for multiqueue vhost-user (de‐
8952 fault: 1) (Since 2.5)
8953 Since
8955 2.1
8956 NetdevVhostVDPAOptions (Object)
8958 Vhost-vdpa network backend
8959 vDPA device is a device that uses a datapath which complies with the
8961 virtio specifications with a vendor specific control path.
8962 Members
8964 vhostdev: string (optional)
8965 path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
8966 queues: int (optional)
8968 number of queues to be created for multiqueue vhost-vdpa (de‐
8969 fault: 1)
8970 Since
8972 5.1
8973 NetClientDriver (Enum)
8975 Available netdev drivers.
8976 Values
8978 none Not documented
8979 nic Not documented
8981 user Not documented
8983 tap Not documented
8985 l2tpv3 Not documented
8987 socket Not documented
8989 vde Not documented
8991 bridge Not documented
8993 hubport
8995 Not documented
8996 netmap Not documented
8998 vhost-user
9000 Not documented
9001 vhost-vdpa
9003 Not documented
9004 Since
9006 2.7
9007 vhost-vdpa since 5.1
9009 Netdev (Object)
9011 Captures the configuration of a network device.
9012 Members
9014 id: string
9015 identifier for monitor commands.
9016 type: NetClientDriver
9018 Specify the driver used for interpreting remaining arguments.
9019 The members of NetLegacyNicOptions when type is "nic"
9021 The members of NetdevUserOptions when type is "user"
9023 The members of NetdevTapOptions when type is "tap"
9025 The members of NetdevL2TPv3Options when type is "l2tpv3"
9027 The members of NetdevSocketOptions when type is "socket"
9029 The members of NetdevVdeOptions when type is "vde"
9031 The members of NetdevBridgeOptions when type is "bridge"
9033 The members of NetdevHubPortOptions when type is "hubport"
9035 The members of NetdevNetmapOptions when type is "netmap"
9037 The members of NetdevVhostUserOptions when type is "vhost-user"
9039 The members of NetdevVhostVDPAOptions when type is "vhost-vdpa"
9041 Since
9043 1.2
9044 'l2tpv3' - since 2.1
9046 NetFilterDirection (Enum)
9048 Indicates whether a netfilter is attached to a netdev's transmit queue
9049 or receive queue or both.
9050 Values
9052 all the filter is attached both to the receive and the transmit
9053 queue of the netdev (default).
9054 rx the filter is attached to the receive queue of the netdev, where
9056 it will receive packets sent to the netdev.
9057 tx the filter is attached to the transmit queue of the netdev,
9059 where it will receive packets sent by the netdev.
9060 Since
9062 2.5
9063 RxState (Enum)
9065 Packets receiving state
9066 Values
9068 normal filter assigned packets according to the mac-table
9069 none don't receive any assigned packet
9071 all receive all assigned packets
9073 Since
9075 1.6
9076 RxFilterInfo (Object)
9078 Rx-filter information for a NIC.
9079 Members
9081 name: string
9082 net client name
9083 promiscuous: boolean
9085 whether promiscuous mode is enabled
9086 multicast: RxState
9088 multicast receive state
9089 unicast: RxState
9091 unicast receive state
9092 vlan: RxState
9094 vlan receive state (Since 2.0)
9095 broadcast-allowed: boolean
9097 whether to receive broadcast
9098 multicast-overflow: boolean
9100 multicast table is overflowed or not
9101 unicast-overflow: boolean
9103 unicast table is overflowed or not
9104 main-mac: string
9106 the main macaddr string
9107 vlan-table: array of int
9109 a list of active vlan id
9110 unicast-table: array of string
9112 a list of unicast macaddr string
9113 multicast-table: array of string
9115 a list of multicast macaddr string
9116 Since
9118 1.6
9119 query-rx-filter (Command)
9121 Return rx-filter information for all NICs (or for the given NIC).
9122 Arguments
9124 name: string (optional)
9125 net client name
9126 Returns
9128 list of RxFilterInfo for all NICs (or for the given NIC). Returns an
9129 error if the given name doesn't exist, or given NIC doesn't support
9130 rx-filter querying, or given net client isn't a NIC.
9131 Since
9133 1.6
9134 Example
9136 -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
9137 <- { "return": [
9138 {
9139 "promiscuous": true,
9140 "name": "vnet0",
9141 "main-mac": "52:54:00:12:34:56",
9142 "unicast": "normal",
9143 "vlan": "normal",
9144 "vlan-table": [
9145 4,
9146 0
9147 ],
9148 "unicast-table": [
9149 ],
9150 "multicast": "normal",
9151 "multicast-overflow": false,
9152 "unicast-overflow": false,
9153 "multicast-table": [
9154 "01:00:5e:00:00:01",
9155 "33:33:00:00:00:01",
9156 "33:33:ff:12:34:56"
9157 ],
9158 "broadcast-allowed": false
9159 }
9160 ]
9161 }
9162 NIC_RX_FILTER_CHANGED (Event)
9164 Emitted once until the 'query-rx-filter' command is executed, the first
9165 event will always be emitted
9166 Arguments
9168 name: string (optional)
9169 net client name
9170 path: string
9172 device path
9173 Since
9175 1.6
9176 Example
9178 <- { "event": "NIC_RX_FILTER_CHANGED",
9179 "data": { "name": "vnet0",
9180 "path": "/machine/peripheral/vnet0/virtio-backend" },
9181 "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
9182 }
9183 AnnounceParameters (Object)
9185 Parameters for self-announce timers
9186 Members
9188 initial: int
9189 Initial delay (in ms) before sending the first GARP/RARP an‐
9190 nouncement
9191 max: int
9193 Maximum delay (in ms) between GARP/RARP announcement packets
9194 rounds: int
9196 Number of self-announcement attempts
9197 step: int
9199 Delay increase (in ms) after each self-announcement attempt
9200 interfaces: array of string (optional)
9202 An optional list of interface names, which restricts the an‐
9203 nouncement to the listed interfaces. (Since 4.1)
9204 id: string (optional)
9206 A name to be used to identify an instance of announce-timers and
9207 to allow it to modified later. Not for use as part of the mi‐
9208 gration parameters. (Since 4.1)
9209 Since
9211 4.0
9212 announce-self (Command)
9214 Trigger generation of broadcast RARP frames to update network switches.
9215 This can be useful when network bonds fail-over the active slave.
9216 Arguments
9218 The members of AnnounceParameters
9219 Example
9221 -> { "execute": "announce-self",
9222 "arguments": {
9223 "initial": 50, "max": 550, "rounds": 10, "step": 50,
9224 "interfaces": ["vn2", "vn3"], "id": "bob" } }
9225 <- { "return": {} }
9226 Since
9228 4.0
9229 FAILOVER_NEGOTIATED (Event)
9231 Emitted when VIRTIO_NET_F_STANDBY was enabled during feature negotia‐
9232 tion. Failover primary devices which were hidden (not hotplugged when
9233 requested) before will now be hotplugged by the virtio-net standby de‐
9234 vice.
9235 device-id: QEMU device id of the unplugged device
9237 Arguments
9239 device-id: string
9240 Not documented
9241 Since
9243 4.2
9244 Example
9246 <- { "event": "FAILOVER_NEGOTIATED",
9247 "data": "net1" }
9248
9250 RDMA_GID_STATUS_CHANGED (Event)
9251 Emitted when guest driver adds/deletes GID to/from device
9252 Arguments
9254 netdev: string
9255 RoCE Network Device name
9256 gid-status: boolean
9258 Add or delete indication
9259 subnet-prefix: int
9261 Subnet Prefix
9262 interface-id: int
9264 Not documented
9265 interface-id : Interface ID
9266 Since
9268 4.0
9269 Example
9271 <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760},
9272 "event": "RDMA_GID_STATUS_CHANGED",
9273 "data":
9274 {"netdev": "bridge0",
9275 "interface-id": 15880512517475447892,
9276 "gid-status": true,
9277 "subnet-prefix": 33022}}
9278
9280 RockerSwitch (Object)
9281 Rocker switch information.
9282 Members
9284 name: string
9285 switch name
9286 id: int
9288 switch ID
9289 ports: int
9291 number of front-panel ports
9292 Since
9294 2.4
9295 query-rocker (Command)
9297 Return rocker switch information.
9298 Arguments
9300 name: string
9301 Not documented
9302 Returns
9304 Rocker information
9305 Since
9307 2.4
9308 Example
9310 -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
9311 <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
9312 RockerPortDuplex (Enum)
9314 An eumeration of port duplex states.
9315 Values
9317 half half duplex
9318 full full duplex
9320 Since
9322 2.4
9323 RockerPortAutoneg (Enum)
9325 An eumeration of port autoneg states.
9326 Values
9328 off autoneg is off
9329 on autoneg is on
9331 Since
9333 2.4
9334 RockerPort (Object)
9336 Rocker switch port information.
9337 Members
9339 name: string
9340 port name
9341 enabled: boolean
9343 port is enabled for I/O
9344 link-up: boolean
9346 physical link is UP on port
9347 speed: int
9349 port link speed in Mbps
9350 duplex: RockerPortDuplex
9352 port link duplex
9353 autoneg: RockerPortAutoneg
9355 port link autoneg
9356 Since
9358 2.4
9359 query-rocker-ports (Command)
9361 Return rocker switch port information.
9362 Arguments
9364 name: string
9365 Not documented
9366 Returns
9368 a list of RockerPort information
9369 Since
9371 2.4
9372 Example
9374 -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
9375 <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
9376 "autoneg": "off", "link-up": true, "speed": 10000},
9377 {"duplex": "full", "enabled": true, "name": "sw1.2",
9378 "autoneg": "off", "link-up": true, "speed": 10000}
9379 ]}
9380 RockerOfDpaFlowKey (Object)
9382 Rocker switch OF-DPA flow key
9383 Members
9385 priority: int
9386 key priority, 0 being lowest priority
9387 tbl-id: int
9389 flow table ID
9390 in-pport: int (optional)
9392 physical input port
9393 tunnel-id: int (optional)
9395 tunnel ID
9396 vlan-id: int (optional)
9398 VLAN ID
9399 eth-type: int (optional)
9401 Ethernet header type
9402 eth-src: string (optional)
9404 Ethernet header source MAC address
9405 eth-dst: string (optional)
9407 Ethernet header destination MAC address
9408 ip-proto: int (optional)
9410 IP Header protocol field
9411 ip-tos: int (optional)
9413 IP header TOS field
9414 ip-dst: string (optional)
9416 IP header destination address
9417 Note
9419 optional members may or may not appear in the flow key depending if
9420 they're relevant to the flow key.
9421 Since
9423 2.4
9424 RockerOfDpaFlowMask (Object)
9426 Rocker switch OF-DPA flow mask
9427 Members
9429 in-pport: int (optional)
9430 physical input port
9431 tunnel-id: int (optional)
9433 tunnel ID
9434 vlan-id: int (optional)
9436 VLAN ID
9437 eth-src: string (optional)
9439 Ethernet header source MAC address
9440 eth-dst: string (optional)
9442 Ethernet header destination MAC address
9443 ip-proto: int (optional)
9445 IP Header protocol field
9446 ip-tos: int (optional)
9448 IP header TOS field
9449 Note
9451 optional members may or may not appear in the flow mask depending if
9452 they're relevant to the flow mask.
9453 Since
9455 2.4
9456 RockerOfDpaFlowAction (Object)
9458 Rocker switch OF-DPA flow action
9459 Members
9461 goto-tbl: int (optional)
9462 next table ID
9463 group-id: int (optional)
9465 group ID
9466 tunnel-lport: int (optional)
9468 tunnel logical port ID
9469 vlan-id: int (optional)
9471 VLAN ID
9472 new-vlan-id: int (optional)
9474 new VLAN ID
9475 out-pport: int (optional)
9477 physical output port
9478 Note
9480 optional members may or may not appear in the flow action depending if
9481 they're relevant to the flow action.
9482 Since
9484 2.4
9485 RockerOfDpaFlow (Object)
9487 Rocker switch OF-DPA flow
9488 Members
9490 cookie: int
9491 flow unique cookie ID
9492 hits: int
9494 count of matches (hits) on flow
9495 key: RockerOfDpaFlowKey
9497 flow key
9498 mask: RockerOfDpaFlowMask
9500 flow mask
9501 action: RockerOfDpaFlowAction
9503 flow action
9504 Since
9506 2.4
9507 query-rocker-of-dpa-flows (Command)
9509 Return rocker OF-DPA flow information.
9510 Arguments
9512 name: string
9513 switch name
9514 tbl-id: int (optional)
9516 flow table ID. If tbl-id is not specified, returns flow infor‐
9517 mation for all tables.
9518 Returns
9520 rocker OF-DPA flow information
9521 Since
9523 2.4
9524 Example
9526 -> { "execute": "query-rocker-of-dpa-flows",
9527 "arguments": { "name": "sw1" } }
9528 <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
9529 "hits": 138,
9530 "cookie": 0,
9531 "action": {"goto-tbl": 10},
9532 "mask": {"in-pport": 4294901760}
9533 },
9534 {...more...},
9535 ]}
9536 RockerOfDpaGroup (Object)
9538 Rocker switch OF-DPA group
9539 Members
9541 id: int
9542 group unique ID
9543 type: int
9545 group type
9546 vlan-id: int (optional)
9548 VLAN ID
9549 pport: int (optional)
9551 physical port number
9552 index: int (optional)
9554 group index, unique with group type
9555 out-pport: int (optional)
9557 output physical port number
9558 group-id: int (optional)
9560 next group ID
9561 set-vlan-id: int (optional)
9563 VLAN ID to set
9564 pop-vlan: int (optional)
9566 pop VLAN headr from packet
9567 group-ids: array of int (optional)
9569 list of next group IDs
9570 set-eth-src: string (optional)
9572 set source MAC address in Ethernet header
9573 set-eth-dst: string (optional)
9575 set destination MAC address in Ethernet header
9576 ttl-check: int (optional)
9578 perform TTL check
9579 Note
9581 optional members may or may not appear in the group depending if
9582 they're relevant to the group type.
9583 Since
9585 2.4
9586 query-rocker-of-dpa-groups (Command)
9588 Return rocker OF-DPA group information.
9589 Arguments
9591 name: string
9592 switch name
9593 type: int (optional)
9595 group type. If type is not specified, returns group information
9596 for all group types.
9597 Returns
9599 rocker OF-DPA group information
9600 Since
9602 2.4
9603 Example
9605 -> { "execute": "query-rocker-of-dpa-groups",
9606 "arguments": { "name": "sw1" } }
9607 <- { "return": [ {"type": 0, "out-pport": 2,
9608 "pport": 2, "vlan-id": 3841,
9609 "pop-vlan": 1, "id": 251723778},
9610 {"type": 0, "out-pport": 0,
9611 "pport": 0, "vlan-id": 3841,
9612 "pop-vlan": 1, "id": 251723776},
9613 {"type": 0, "out-pport": 1,
9614 "pport": 1, "vlan-id": 3840,
9615 "pop-vlan": 1, "id": 251658241},
9616 {"type": 0, "out-pport": 0,
9617 "pport": 0, "vlan-id": 3840,
9618 "pop-vlan": 1, "id": 251658240}
9619 ]}
9620
9622 TpmModel (Enum)
9623 An enumeration of TPM models
9624 Values
9626 tpm-tis
9627 TPM TIS model
9628 tpm-crb
9630 TPM CRB model (since 2.12)
9631 tpm-spapr
9633 TPM SPAPR model (since 5.0)
9634 Since
9636 1.5
9637 query-tpm-models (Command)
9639 Return a list of supported TPM models
9640 Returns
9642 a list of TpmModel
9643 Since
9645 1.5
9646 Example
9648 -> { "execute": "query-tpm-models" }
9649 <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
9650 TpmType (Enum)
9652 An enumeration of TPM types
9653 Values
9655 passthrough
9656 TPM passthrough type
9657 emulator
9659 Software Emulator TPM type Since: 2.11
9660 Since
9662 1.5
9663 query-tpm-types (Command)
9665 Return a list of supported TPM types
9666 Returns
9668 a list of TpmType
9669 Since
9671 1.5
9672 Example
9674 -> { "execute": "query-tpm-types" }
9675 <- { "return": [ "passthrough", "emulator" ] }
9676 TPMPassthroughOptions (Object)
9678 Information about the TPM passthrough type
9679 Members
9681 path: string (optional)
9682 string describing the path used for accessing the TPM device
9683 cancel-path: string (optional)
9685 string showing the TPM's sysfs cancel file for cancellation of
9686 TPM commands while they are executing
9687 Since
9689 1.5
9690 TPMEmulatorOptions (Object)
9692 Information about the TPM emulator type
9693 Members
9695 chardev: string
9696 Name of a unix socket chardev
9697 Since
9699 2.11
9700 TpmTypeOptions (Object)
9702 A union referencing different TPM backend types' configuration options
9703 Members
9705 type
9706 • 'passthrough' The configuration options for the TPM
9708 passthrough type
9709 • 'emulator' The configuration options for TPM emulator backend
9711 type
9712 data: TPMPassthroughOptions when type is "passthrough"
9714 data: TPMEmulatorOptions when type is "emulator"
9716 Since
9718 1.5
9719 TPMInfo (Object)
9721 Information about the TPM
9722 Members
9724 id: string
9725 The Id of the TPM
9726 model: TpmModel
9728 The TPM frontend model
9729 options: TpmTypeOptions
9731 The TPM (backend) type configuration options
9732 Since
9734 1.5
9735 query-tpm (Command)
9737 Return information about the TPM device
9738 Returns
9740 TPMInfo on success
9741 Since
9743 1.5
9744 Example
9746 -> { "execute": "query-tpm" }
9747 <- { "return":
9748 [
9749 { "model": "tpm-tis",
9750 "options":
9751 { "type": "passthrough",
9752 "data":
9753 { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
9754 "path": "/dev/tpm0"
9755 }
9756 },
9757 "id": "tpm0"
9758 }
9759 ]
9760 }
9761
9763 set_password (Command)
9764 Sets the password of a remote display session.
9765 Arguments
9767 protocol: string
9768 • 'vnc' to modify the VNC server password
9770 • 'spice' to modify the Spice server password
9772 password: string
9774 the new password
9775 connected: string (optional)
9777 how to handle existing clients when changing the password. If
9778 nothing is specified, defaults to 'keep' 'fail' to fail the com‐
9779 mand if clients are connected 'disconnect' to disconnect exist‐
9780 ing clients 'keep' to maintain existing clients
9781 Returns
9783 • Nothing on success
9784 • If Spice is not enabled, DeviceNotFound
9786 Since
9788 0.14.0
9789 Example
9791 -> { "execute": "set_password", "arguments": { "protocol": "vnc",
9792 "password": "secret" } }
9793 <- { "return": {} }
9794 expire_password (Command)
9796 Expire the password of a remote display server.
9797 Arguments
9799 protocol: string
9800 the name of the remote display protocol 'vnc' or 'spice'
9801 time: string
9803 when to expire the password.
9804 • 'now' to expire the password immediately
9806 • 'never' to cancel password expiration
9808 • '+INT' where INT is the number of seconds from now (integer)
9810 • 'INT' where INT is the absolute time in seconds
9812 Returns
9814 • Nothing on success
9815 • If protocol is 'spice' and Spice is not active, DeviceNotFound
9817 Since
9819 0.14.0
9820 Notes
9822 Time is relative to the server and currently there is no way to coordi‐
9823 nate server time with client time. It is not recommended to use the
9824 absolute time version of the time parameter unless you're sure you are
9825 on the same machine as the QEMU instance.
9826 Example
9828 -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
9829 "time": "+60" } }
9830 <- { "return": {} }
9831 screendump (Command)
9833 Write a PPM of the VGA screen to a file.
9834 Arguments
9836 filename: string
9837 the path of a new PPM file to store the image
9838 device: string (optional)
9840 ID of the display device that should be dumped. If this parame‐
9841 ter is missing, the primary display will be used. (Since 2.12)
9842 head: int (optional)
9844 head to use in case the device supports multiple heads. If this
9845 parameter is missing, head #0 will be used. Also note that the
9846 head can only be specified in conjunction with the device ID.
9847 (Since 2.12)
9848 Returns
9850 Nothing on success
9851 Since
9853 0.14.0
9854 Example
9856 -> { "execute": "screendump",
9857 "arguments": { "filename": "/tmp/image" } }
9858 <- { "return": {} }
9859 Spice
9861 SpiceBasicInfo (Object)
9862 The basic information for SPICE network connection
9863 Members
9865 host: string
9866 IP address
9867 port: string
9869 port number
9870 family: NetworkAddressFamily
9872 address family
9873 Since
9875 2.1
9876 If
9878 defined(CONFIG_SPICE).SS SpiceServerInfo (Object)
9879 Information about a SPICE server
9881 Members
9883 auth: string (optional)
9884 authentication method
9885 The members of SpiceBasicInfo
9887 Since
9889 2.1
9890 If
9892 defined(CONFIG_SPICE).SS SpiceChannel (Object)
9893 Information about a SPICE client channel.
9895 Members
9897 connection-id: int
9898 SPICE connection id number. All channels with the same id be‐
9899 long to the same SPICE session.
9900 channel-type: int
9902 SPICE channel type number. "1" is the main control channel,
9903 filter for this one if you want to track spice sessions only
9904 channel-id: int
9906 SPICE channel ID number. Usually "0", might be different when
9907 multiple channels of the same type exist, such as multiple dis‐
9908 play channels in a multihead setup
9909 tls: boolean
9911 true if the channel is encrypted, false otherwise.
9912 The members of SpiceBasicInfo
9914 Since
9916 0.14.0
9917 If
9919 defined(CONFIG_SPICE).SS SpiceQueryMouseMode (Enum)
9920 An enumeration of Spice mouse states.
9922 Values
9924 client Mouse cursor position is determined by the client.
9925 server Mouse cursor position is determined by the server.
9927 unknown
9929 No information is available about mouse mode used by the spice
9930 server.
9931 Note
9933 spice/enums.h has a SpiceMouseMode already, hence the name.
9934 Since
9936 1.1
9937 If
9939 defined(CONFIG_SPICE).SS SpiceInfo (Object)
9940 Information about the SPICE session.
9942 Members
9944 enabled: boolean
9945 true if the SPICE server is enabled, false otherwise
9946 migrated: boolean
9948 true if the last guest migration completed and spice migration
9949 had completed as well. false otherwise. (since 1.4)
9950 host: string (optional)
9952 The hostname the SPICE server is bound to. This depends on the
9953 name resolution on the host and may be an IP address.
9954 port: int (optional)
9956 The SPICE server's port number.
9957 compiled-version: string (optional)
9959 SPICE server version.
9960 tls-port: int (optional)
9962 The SPICE server's TLS port number.
9963 auth: string (optional)
9965 the current authentication type used by the server
9966 • 'none' if no authentication is being used
9968 • 'spice' uses SASL or direct TLS authentication, depending on
9970 command line options
9971 mouse-mode: SpiceQueryMouseMode
9973 The mode in which the mouse cursor is displayed currently. Can
9974 be determined by the client or the server, or unknown if spice
9975 server doesn't provide this information. (since: 1.1)
9976 channels: array of SpiceChannel (optional)
9978 a list of SpiceChannel for each active spice channel
9979 Since
9981 0.14.0
9982 If
9984 defined(CONFIG_SPICE).SS query-spice (Command)
9985 Returns information about the current SPICE server
9987 Returns
9989 SpiceInfo
9990 Since
9992 0.14.0
9993 Example
9995 -> { "execute": "query-spice" }
9996 <- { "return": {
9997 "enabled": true,
9998 "auth": "spice",
9999 "port": 5920,
10000 "tls-port": 5921,
10001 "host": "0.0.0.0",
10002 "channels": [
10003 {
10004 "port": "54924",
10005 "family": "ipv4",
10006 "channel-type": 1,
10007 "connection-id": 1804289383,
10008 "host": "127.0.0.1",
10009 "channel-id": 0,
10010 "tls": true
10011 },
10012 {
10013 "port": "36710",
10014 "family": "ipv4",
10015 "channel-type": 4,
10016 "connection-id": 1804289383,
10017 "host": "127.0.0.1",
10018 "channel-id": 0,
10019 "tls": false
10020 },
10021 [ ... more channels follow ... ]
10022 ]
10023 }
10024 }
10025 If
10027 defined(CONFIG_SPICE).SS SPICE_CONNECTED (Event)
10028 Emitted when a SPICE client establishes a connection
10030 Arguments
10032 server: SpiceBasicInfo
10033 server information
10034 client: SpiceBasicInfo
10036 client information
10037 Since
10039 0.14.0
10040 Example
10042 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
10043 "event": "SPICE_CONNECTED",
10044 "data": {
10045 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
10046 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
10047 }}
10048 If
10050 defined(CONFIG_SPICE).SS SPICE_INITIALIZED (Event)
10051 Emitted after initial handshake and authentication takes place (if any)
10053 and the SPICE channel is up and running
10054 Arguments
10056 server: SpiceServerInfo
10057 server information
10058 client: SpiceChannel
10060 client information
10061 Since
10063 0.14.0
10064 Example
10066 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
10067 "event": "SPICE_INITIALIZED",
10068 "data": {"server": {"auth": "spice", "port": "5921",
10069 "family": "ipv4", "host": "127.0.0.1"},
10070 "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
10071 "connection-id": 1804289383, "host": "127.0.0.1",
10072 "channel-id": 0, "tls": true}
10073 }}
10074 If
10076 defined(CONFIG_SPICE).SS SPICE_DISCONNECTED (Event)
10077 Emitted when the SPICE connection is closed
10079 Arguments
10081 server: SpiceBasicInfo
10082 server information
10083 client: SpiceBasicInfo
10085 client information
10086 Since
10088 0.14.0
10089 Example
10091 <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
10092 "event": "SPICE_DISCONNECTED",
10093 "data": {
10094 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
10095 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
10096 }}
10097 If
10099 defined(CONFIG_SPICE).SS SPICE_MIGRATE_COMPLETED (Event)
10100 Emitted when SPICE migration has completed
10102 Since
10104 1.3
10105 Example
10107 <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
10108 "event": "SPICE_MIGRATE_COMPLETED" }
10109 If
10111 defined(CONFIG_SPICE).SS VNC
10112 VncBasicInfo (Object)
10114 The basic information for vnc network connection
10115 Members
10117 host: string
10118 IP address
10119 service: string
10121 The service name of the vnc port. This may depend on the host
10122 system's service database so symbolic names should not be relied
10123 on.
10124 family: NetworkAddressFamily
10126 address family
10127 websocket: boolean
10129 true in case the socket is a websocket (since 2.3).
10130 Since
10132 2.1
10133 If
10135 defined(CONFIG_VNC).SS VncServerInfo (Object)
10136 The network connection information for server
10138 Members
10140 auth: string (optional)
10141 authentication method used for the plain (non-websocket) VNC
10142 server
10143 The members of VncBasicInfo
10145 Since
10147 2.1
10148 If
10150 defined(CONFIG_VNC).SS VncClientInfo (Object)
10151 Information about a connected VNC client.
10153 Members
10155 x509_dname: string (optional)
10156 If x509 authentication is in use, the Distinguished Name of the
10157 client.
10158 sasl_username: string (optional)
10160 If SASL authentication is in use, the SASL username used for au‐
10161 thentication.
10162 The members of VncBasicInfo
10164 Since
10166 0.14.0
10167 If
10169 defined(CONFIG_VNC).SS VncInfo (Object)
10170 Information about the VNC session.
10172 Members
10174 enabled: boolean
10175 true if the VNC server is enabled, false otherwise
10176 host: string (optional)
10178 The hostname the VNC server is bound to. This depends on the
10179 name resolution on the host and may be an IP address.
10180 family: NetworkAddressFamily (optional)
10182 • 'ipv6' if the host is listening for IPv6 connections
10184 • 'ipv4' if the host is listening for IPv4 connections
10186 • 'unix' if the host is listening on a unix domain socket
10188 • 'unknown' otherwise
10190 service: string (optional)
10192 The service name of the server's port. This may depends on the
10193 host system's service database so symbolic names should not be
10194 relied on.
10195 auth: string (optional)
10197 the current authentication type used by the server
10198 • 'none' if no authentication is being used
10200 • 'vnc' if VNC authentication is being used
10202 • 'vencrypt+plain' if VEncrypt is used with plain text authenti‐
10204 cation
10205 • 'vencrypt+tls+none' if VEncrypt is used with TLS and no au‐
10207 thentication
10208 • 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC au‐
10210 thentication
10211 • 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain
10213 text auth
10214 • 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
10216 • 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
10218 • 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain
10220 text auth
10221 • 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
10223 • 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL
10225 auth
10226 clients: array of VncClientInfo (optional)
10228 a list of VncClientInfo of all currently connected clients
10229 Since
10231 0.14.0
10232 If
10234 defined(CONFIG_VNC).SS VncPrimaryAuth (Enum)
10235 vnc primary authentication method.
10237 Values
10239 none Not documented
10240 vnc Not documented
10242 ra2 Not documented
10244 ra2ne Not documented
10246 tight Not documented
10248 ultra Not documented
10250 tls Not documented
10252 vencrypt
10254 Not documented
10255 sasl Not documented
10257 Since
10259 2.3
10260 If
10262 defined(CONFIG_VNC).SS VncVencryptSubAuth (Enum)
10263 vnc sub authentication method with vencrypt.
10265 Values
10267 plain Not documented
10268 tls-none
10270 Not documented
10271 x509-none
10273 Not documented
10274 tls-vnc
10276 Not documented
10277 x509-vnc
10279 Not documented
10280 tls-plain
10282 Not documented
10283 x509-plain
10285 Not documented
10286 tls-sasl
10288 Not documented
10289 x509-sasl
10291 Not documented
10292 Since
10294 2.3
10295 If
10297 defined(CONFIG_VNC).SS VncServerInfo2 (Object)
10298 The network connection information for server
10300 Members
10302 auth: VncPrimaryAuth
10303 The current authentication type used by the servers
10304 vencrypt: VncVencryptSubAuth (optional)
10306 The vencrypt sub authentication type used by the servers, only
10307 specified in case auth == vencrypt.
10308 The members of VncBasicInfo
10310 Since
10312 2.9
10313 If
10315 defined(CONFIG_VNC).SS VncInfo2 (Object)
10316 Information about a vnc server
10318 Members
10320 id: string
10321 vnc server name.
10322 server: array of VncServerInfo2
10324 A list of VncBasincInfo describing all listening sockets. The
10325 list can be empty (in case the vnc server is disabled). It also
10326 may have multiple entries: normal + websocket, possibly also
10327 ipv4 + ipv6 in the future.
10328 clients: array of VncClientInfo
10330 A list of VncClientInfo of all currently connected clients. The
10331 list can be empty, for obvious reasons.
10332 auth: VncPrimaryAuth
10334 The current authentication type used by the non-websockets
10335 servers
10336 vencrypt: VncVencryptSubAuth (optional)
10338 The vencrypt authentication type used by the servers, only spec‐
10339 ified in case auth == vencrypt.
10340 display: string (optional)
10342 The display device the vnc server is linked to.
10343 Since
10345 2.3
10346 If
10348 defined(CONFIG_VNC).SS query-vnc (Command)
10349 Returns information about the current VNC server
10351 Returns
10353 VncInfo
10354 Since
10356 0.14.0
10357 Example
10359 -> { "execute": "query-vnc" }
10360 <- { "return": {
10361 "enabled":true,
10362 "host":"0.0.0.0",
10363 "service":"50402",
10364 "auth":"vnc",
10365 "family":"ipv4",
10366 "clients":[
10367 {
10368 "host":"127.0.0.1",
10369 "service":"50401",
10370 "family":"ipv4"
10371 }
10372 ]
10373 }
10374 }
10375 If
10377 defined(CONFIG_VNC).SS query-vnc-servers (Command)
10378 Returns a list of vnc servers. The list can be empty.
10380 Returns
10382 a list of VncInfo2
10383 Since
10385 2.3
10386 If
10388 defined(CONFIG_VNC).SS change-vnc-password (Command)
10389 Change the VNC server password.
10391 Arguments
10393 password: string
10394 the new password to use with VNC authentication
10395 Since
10397 1.1
10398 Notes
10400 An empty password in this command will set the password to the empty
10401 string. Existing clients are unaffected by executing this command.
10402 If
10404 defined(CONFIG_VNC).SS VNC_CONNECTED (Event)
10405 Emitted when a VNC client establishes a connection
10407 Arguments
10409 server: VncServerInfo
10410 server information
10411 client: VncBasicInfo
10413 client information
10414 Note
10416 This event is emitted before any authentication takes place, thus the
10417 authentication ID is not provided
10418 Since
10420 0.13.0
10421 Example
10423 <- { "event": "VNC_CONNECTED",
10424 "data": {
10425 "server": { "auth": "sasl", "family": "ipv4",
10426 "service": "5901", "host": "0.0.0.0" },
10427 "client": { "family": "ipv4", "service": "58425",
10428 "host": "127.0.0.1" } },
10429 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
10430 If
10432 defined(CONFIG_VNC).SS VNC_INITIALIZED (Event)
10433 Emitted after authentication takes place (if any) and the VNC session
10435 is made active
10436 Arguments
10438 server: VncServerInfo
10439 server information
10440 client: VncClientInfo
10442 client information
10443 Since
10445 0.13.0
10446 Example
10448 <- { "event": "VNC_INITIALIZED",
10449 "data": {
10450 "server": { "auth": "sasl", "family": "ipv4",
10451 "service": "5901", "host": "0.0.0.0"},
10452 "client": { "family": "ipv4", "service": "46089",
10453 "host": "127.0.0.1", "sasl_username": "luiz" } },
10454 "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
10455 If
10457 defined(CONFIG_VNC).SS VNC_DISCONNECTED (Event)
10458 Emitted when the connection is closed
10460 Arguments
10462 server: VncServerInfo
10463 server information
10464 client: VncClientInfo
10466 client information
10467 Since
10469 0.13.0
10470 Example
10472 <- { "event": "VNC_DISCONNECTED",
10473 "data": {
10474 "server": { "auth": "sasl", "family": "ipv4",
10475 "service": "5901", "host": "0.0.0.0" },
10476 "client": { "family": "ipv4", "service": "58425",
10477 "host": "127.0.0.1", "sasl_username": "luiz" } },
10478 "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
10479 If
10481 defined(CONFIG_VNC).SH INPUT
10482 MouseInfo (Object)
10484 Information about a mouse device.
10485 Members
10487 name: string
10488 the name of the mouse device
10489 index: int
10491 the index of the mouse device
10492 current: boolean
10494 true if this device is currently receiving mouse events
10495 absolute: boolean
10497 true if this device supports absolute coordinates as input
10498 Since
10500 0.14.0
10501 query-mice (Command)
10503 Returns information about each active mouse device
10504 Returns
10506 a list of MouseInfo for each device
10507 Since
10509 0.14.0
10510 Example
10512 -> { "execute": "query-mice" }
10513 <- { "return": [
10514 {
10515 "name":"QEMU Microsoft Mouse",
10516 "index":0,
10517 "current":false,
10518 "absolute":false
10519 },
10520 {
10521 "name":"QEMU PS/2 Mouse",
10522 "index":1,
10523 "current":true,
10524 "absolute":true
10525 }
10526 ]
10527 }
10528 QKeyCode (Enum)
10530 An enumeration of key name.
10531 This is used by the send-key command.
10533 Values
10535 unmapped
10536 since 2.0
10537 pause since 2.0
10539 ro since 2.4
10541 kp_comma
10543 since 2.4
10544 kp_equals
10546 since 2.6
10547 power since 2.6
10549 hiragana
10551 since 2.9
10552 henkan since 2.9
10554 yen since 2.9
10556 sleep since 2.10
10558 wake since 2.10
10560 audionext
10562 since 2.10
10563 audioprev
10565 since 2.10
10566 audiostop
10568 since 2.10
10569 audioplay
10571 since 2.10
10572 audiomute
10574 since 2.10
10575 volumeup
10577 since 2.10
10578 volumedown
10580 since 2.10
10581 mediaselect
10583 since 2.10
10584 mail since 2.10
10586 calculator
10588 since 2.10
10589 computer
10591 since 2.10
10592 ac_home
10594 since 2.10
10595 ac_back
10597 since 2.10
10598 ac_forward
10600 since 2.10
10601 ac_refresh
10603 since 2.10
10604 ac_bookmarks
10606 since 2.10
10607 muhenkan
10609 since 2.12
10610 katakanahiragana
10612 since 2.12
10613 shift Not documented
10615 shift_r
10617 Not documented
10618 alt Not documented
10620 alt_r Not documented
10622 ctrl Not documented
10624 ctrl_r Not documented
10626 menu Not documented
10628 esc Not documented
10630 1 Not documented
10632 2 Not documented
10634 3 Not documented
10636 4 Not documented
10638 5 Not documented
10640 6 Not documented
10642 7 Not documented
10644 8 Not documented
10646 9 Not documented
10648 0 Not documented
10650 minus Not documented
10652 equal Not documented
10654 backspace
10656 Not documented
10657 tab Not documented
10659 q Not documented
10661 w Not documented
10663 e Not documented
10665 r Not documented
10667 t Not documented
10669 y Not documented
10671 u Not documented
10673 i Not documented
10675 o Not documented
10677 p Not documented
10679 bracket_left
10681 Not documented
10682 bracket_right
10684 Not documented
10685 ret Not documented
10687 a Not documented
10689 s Not documented
10691 d Not documented
10693 f Not documented
10695 g Not documented
10697 h Not documented
10699 j Not documented
10701 k Not documented
10703 l Not documented
10705 semicolon
10707 Not documented
10708 apostrophe
10710 Not documented
10711 grave_accent
10713 Not documented
10714 backslash
10716 Not documented
10717 z Not documented
10719 x Not documented
10721 c Not documented
10723 v Not documented
10725 b Not documented
10727 n Not documented
10729 m Not documented
10731 comma Not documented
10733 dot Not documented
10735 slash Not documented
10737 asterisk
10739 Not documented
10740 spc Not documented
10742 caps_lock
10744 Not documented
10745 f1 Not documented
10747 f2 Not documented
10749 f3 Not documented
10751 f4 Not documented
10753 f5 Not documented
10755 f6 Not documented
10757 f7 Not documented
10759 f8 Not documented
10761 f9 Not documented
10763 f10 Not documented
10765 num_lock
10767 Not documented
10768 scroll_lock
10770 Not documented
10771 kp_divide
10773 Not documented
10774 kp_multiply
10776 Not documented
10777 kp_subtract
10779 Not documented
10780 kp_add Not documented
10782 kp_enter
10784 Not documented
10785 kp_decimal
10787 Not documented
10788 sysrq Not documented
10790 kp_0 Not documented
10792 kp_1 Not documented
10794 kp_2 Not documented
10796 kp_3 Not documented
10798 kp_4 Not documented
10800 kp_5 Not documented
10802 kp_6 Not documented
10804 kp_7 Not documented
10806 kp_8 Not documented
10808 kp_9 Not documented
10810 less Not documented
10812 f11 Not documented
10814 f12 Not documented
10816 print Not documented
10818 home Not documented
10820 pgup Not documented
10822 pgdn Not documented
10824 end Not documented
10826 left Not documented
10828 up Not documented
10830 down Not documented
10832 right Not documented
10834 insert Not documented
10836 delete Not documented
10838 stop Not documented
10840 again Not documented
10842 props Not documented
10844 undo Not documented
10846 front Not documented
10848 copy Not documented
10850 open Not documented
10852 paste Not documented
10854 find Not documented
10856 cut Not documented
10858 lf Not documented
10860 help Not documented
10862 meta_l Not documented
10864 meta_r Not documented
10866 compose
10868 Not documented
10869 'sysrq' was mistakenly added to hack around the fact that the ps2
10870 driver was not generating correct scancodes sequences when 'alt+print'
10871 was pressed. This flaw is now fixed and the 'sysrq' key serves no fur‐
10872 ther purpose. Any further use of 'sysrq' will be transparently changed
10873 to 'print', so they are effectively synonyms.
10874 Since
10876 1.3.0
10877 KeyValue (Object)
10879 Represents a keyboard key.
10880 Members
10882 type One of number, qcode
10883 data: int when type is "number"
10885 data: QKeyCode when type is "qcode"
10887 Since
10889 1.3.0
10890 send-key (Command)
10892 Send keys to guest.
10893 Arguments
10895 keys: array of KeyValue
10896 An array of KeyValue elements. All KeyValues in this array are
10897 simultaneously sent to the guest. A KeyValue.number value is
10898 sent directly to the guest, while KeyValue.qcode must be a valid
10899 QKeyCode value
10900 hold-time: int (optional)
10902 time to delay key up events, milliseconds. Defaults to 100
10903 Returns
10905 • Nothing on success
10906 • If key is unknown or redundant, InvalidParameter
10908 Since
10910 1.3.0
10911 Example
10913 -> { "execute": "send-key",
10914 "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
10915 { "type": "qcode", "data": "alt" },
10916 { "type": "qcode", "data": "delete" } ] } }
10917 <- { "return": {} }
10918 InputButton (Enum)
10920 Button of a pointer input device (mouse, tablet).
10921 Values
10923 side front side button of a 5-button mouse (since 2.9)
10924 extra rear side button of a 5-button mouse (since 2.9)
10926 left Not documented
10928 middle Not documented
10930 right Not documented
10932 wheel-up
10934 Not documented
10935 wheel-down
10937 Not documented
10938 Since
10940 2.0
10941 InputAxis (Enum)
10943 Position axis of a pointer input device (mouse, tablet).
10944 Values
10946 x Not documented
10947 y Not documented
10949 Since
10951 2.0
10952 InputKeyEvent (Object)
10954 Keyboard input event.
10955 Members
10957 key: KeyValue
10958 Which key this event is for.
10959 down: boolean
10961 True for key-down and false for key-up events.
10962 Since
10964 2.0
10965 InputBtnEvent (Object)
10967 Pointer button input event.
10968 Members
10970 button: InputButton
10971 Which button this event is for.
10972 down: boolean
10974 True for key-down and false for key-up events.
10975 Since
10977 2.0
10978 InputMoveEvent (Object)
10980 Pointer motion input event.
10981 Members
10983 axis: InputAxis
10984 Which axis is referenced by value.
10985 value: int
10987 Pointer position. For absolute coordinates the valid range is 0
10988 -> 0x7ffff
10989 Since
10991 2.0
10992 InputEvent (Object)
10994 Input event union.
10995 Members
10997 type the input type, one of:
10998 • 'key': Input event of Keyboard
11000 • 'btn': Input event of pointer buttons
11002 • 'rel': Input event of relative pointer motion
11004 • 'abs': Input event of absolute pointer motion
11006 data: InputKeyEvent when type is "key"
11008 data: InputBtnEvent when type is "btn"
11010 data: InputMoveEvent when type is "rel"
11012 data: InputMoveEvent when type is "abs"
11014 Since
11016 2.0
11017 input-send-event (Command)
11019 Send input event(s) to guest.
11020 The device and head parameters can be used to send the input event to
11022 specific input devices in case (a) multiple input devices of the same
11023 kind are added to the virtual machine and (b) you have configured input
11024 routing (see docs/multiseat.txt) for those input devices. The parame‐
11025 ters work exactly like the device and head properties of input devices.
11026 If device is missing, only devices that have no input routing config
11027 are admissible. If device is specified, both input devices with and
11028 without input routing config are admissible, but devices with input
11029 routing config take precedence.
11030 Arguments
11032 device: string (optional)
11033 display device to send event(s) to.
11034 head: int (optional)
11036 head to send event(s) to, in case the display device supports
11037 multiple scanouts.
11038 events: array of InputEvent
11040 List of InputEvent union.
11041 Returns
11043 Nothing on success.
11044 Since
11046 2.6
11047 Note
11049 The consoles are visible in the qom tree, under /backend/console[$in‐
11050 dex]. They have a device link and head property, so it is possible to
11051 map which console belongs to which device and display.
11052 Example
11054 1. Press left mouse button.
11055 -> { "execute": "input-send-event",
11057 "arguments": { "device": "video0",
11058 "events": [ { "type": "btn",
11059 "data" : { "down": true, "button": "left" } } ] } }
11060 <- { "return": {} }
11061 -> { "execute": "input-send-event",
11063 "arguments": { "device": "video0",
11064 "events": [ { "type": "btn",
11065 "data" : { "down": false, "button": "left" } } ] } }
11066 <- { "return": {} }
11067 2. Press ctrl-alt-del.
11069 -> { "execute": "input-send-event",
11071 "arguments": { "events": [
11072 { "type": "key", "data" : { "down": true,
11073 "key": {"type": "qcode", "data": "ctrl" } } },
11074 { "type": "key", "data" : { "down": true,
11075 "key": {"type": "qcode", "data": "alt" } } },
11076 { "type": "key", "data" : { "down": true,
11077 "key": {"type": "qcode", "data": "delete" } } } ] } }
11078 <- { "return": {} }
11079 3. Move mouse pointer to absolute coordinates (20000, 400).
11081 -> { "execute": "input-send-event" ,
11083 "arguments": { "events": [
11084 { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
11085 { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
11086 <- { "return": {} }
11087 GrabToggleKeys (Enum)
11089 Keys to toggle input-linux between host and guest.
11090 Values
11092 ctrl-ctrl
11093 Not documented
11094 alt-alt
11096 Not documented
11097 shift-shift
11099 Not documented
11100 meta-meta
11102 Not documented
11103 scrolllock
11105 Not documented
11106 ctrl-scrolllock
11108 Not documented
11109 Since
11111 4.0
11112 DisplayGTK (Object)
11114 GTK display options.
11115 Members
11117 grab-on-hover: boolean (optional)
11118 Grab keyboard input on mouse hover.
11119 zoom-to-fit: boolean (optional)
11121 Zoom guest display to fit into the host window. When turned off
11122 the host window will be resized instead. In case the display
11123 device can notify the guest on window resizes (virtio-gpu) this
11124 will default to "on", assuming the guest will resize the display
11125 to match the window size then. Otherwise it defaults to "off".
11126 Since 3.1
11127 Since
11129 2.12
11130 DisplayEGLHeadless (Object)
11132 EGL headless display options.
11133 Members
11135 rendernode: string (optional)
11136 Which DRM render node should be used. Default is the first
11137 available node on the host.
11138 Since
11140 3.1
11141 DisplayGLMode (Enum)
11143 Display OpenGL mode.
11144 Values
11146 off Disable OpenGL (default).
11147 on Use OpenGL, pick context type automatically. Would better be
11149 named 'auto' but is called 'on' for backward compatibility with
11150 bool type.
11151 core Use OpenGL with Core (desktop) Context.
11153 es Use OpenGL with ES (embedded systems) Context.
11155 Since
11157 3.0
11158 DisplayCurses (Object)
11160 Curses display options.
11161 Members
11163 charset: string (optional)
11164 Font charset used by guest (default: CP437).
11165 Since
11167 4.0
11168 DisplayType (Enum)
11170 Display (user interface) type.
11171 Values
11173 default
11174 The default user interface, selecting from the first available
11175 of gtk, sdl, cocoa, and vnc.
11176 none No user interface or video output display. The guest will still
11178 see an emulated graphics card, but its output will not be dis‐
11179 played to the QEMU user.
11180 gtk The GTK user interface.
11182 sdl The SDL user interface.
11184 egl-headless
11186 No user interface, offload GL operations to a local DRI device.
11187 Graphical display need to be paired with VNC or Spice. (Since
11188 3.1)
11189 curses Display video output via curses. For graphics device models
11191 which support a text mode, QEMU can display this output using a
11192 curses/ncurses interface. Nothing is displayed when the graphics
11193 device is in graphical mode or if the graphics device does not
11194 support a text mode. Generally only the VGA device models sup‐
11195 port text mode.
11196 cocoa The Cocoa user interface.
11198 spice-app
11200 Set up a Spice server and run the default associated application
11201 to connect to it. The server will redirect the serial console
11202 and QEMU monitors. (Since 4.0)
11203 Since
11205 2.12
11206 DisplayOptions (Object)
11208 Display (user interface) options.
11209 Members
11211 type: DisplayType
11212 Which DisplayType qemu should use.
11213 full-screen: boolean (optional)
11215 Start user interface in fullscreen mode (default: off).
11216 window-close: boolean (optional)
11218 Allow to quit qemu with window close button (default: on).
11219 show-cursor: boolean (optional)
11221 Force showing the mouse cursor (default: off). (since: 5.0)
11222 gl: DisplayGLMode (optional)
11224 Enable OpenGL support (default: off).
11225 The members of DisplayGTK when type is "gtk"
11227 The members of DisplayCurses when type is "curses"
11229 The members of DisplayEGLHeadless when type is "egl-headless"
11231 Since
11233 2.12
11234 query-display-options (Command)
11236 Returns information about display configuration
11237 Returns
11239 DisplayOptions
11240 Since
11242 3.1
11243
11245 QAuthZListPolicy (Enum)
11246 The authorization policy result
11247 Values
11249 deny deny access
11250 allow allow access
11252 Since
11254 4.0
11255 QAuthZListFormat (Enum)
11257 The authorization policy match format
11258 Values
11260 exact an exact string match
11261 glob string with ? and * shell wildcard support
11263 Since
11265 4.0
11266 QAuthZListRule (Object)
11268 A single authorization rule.
11269 Members
11271 match: string
11272 a string or glob to match against a user identity
11273 policy: QAuthZListPolicy
11275 the result to return if match evaluates to true
11276 format: QAuthZListFormat (optional)
11278 the format of the match rule (default 'exact')
11279 Since
11281 4.0
11282 QAuthZListRuleListHack (Object)
11284 Not exposed via QMP; hack to generate QAuthZListRuleList for use inter‐
11285 nally by the code.
11286 Members
11288 unused: array of QAuthZListRule
11289 Not documented
11290 Since
11292 4.0
11293
11295 MigrationStats (Object)
11296 Detailed migration status.
11297 Members
11299 transferred: int
11300 amount of bytes already transferred to the target VM
11301 remaining: int
11303 amount of bytes remaining to be transferred to the target VM
11304 total: int
11306 total amount of bytes involved in the migration process
11307 duplicate: int
11309 number of duplicate (zero) pages (since 1.2)
11310 skipped: int
11312 number of skipped zero pages (since 1.5)
11313 normal: int
11315 number of normal pages (since 1.2)
11316 normal-bytes: int
11318 number of normal bytes sent (since 1.2)
11319 dirty-pages-rate: int
11321 number of pages dirtied by second by the guest (since 1.3)
11322 mbps: number
11324 throughput in megabits/sec. (since 1.6)
11325 dirty-sync-count: int
11327 number of times that dirty ram was synchronized (since 2.1)
11328 postcopy-requests: int
11330 The number of page requests received from the destination (since
11331 2.7)
11332 page-size: int
11334 The number of bytes per page for the various page-based statis‐
11335 tics (since 2.10)
11336 multifd-bytes: int
11338 The number of bytes sent through multifd (since 3.0)
11339 pages-per-second: int
11341 the number of memory pages transferred per second (Since 4.0)
11342 Since
11344 0.14.0
11345 XBZRLECacheStats (Object)
11347 Detailed XBZRLE migration cache statistics
11348 Members
11350 cache-size: int
11351 XBZRLE cache size
11352 bytes: int
11354 amount of bytes already transferred to the target VM
11355 pages: int
11357 amount of pages transferred to the target VM
11358 cache-miss: int
11360 number of cache miss
11361 cache-miss-rate: number
11363 rate of cache miss (since 2.1)
11364 encoding-rate: number
11366 rate of encoded bytes (since 5.1)
11367 overflow: int
11369 number of overflows
11370 Since
11372 1.2
11373 CompressionStats (Object)
11375 Detailed migration compression statistics
11376 Members
11378 pages: int
11379 amount of pages compressed and transferred to the target VM
11380 busy: int
11382 count of times that no free thread was available to compress
11383 data
11384 busy-rate: number
11386 rate of thread busy
11387 compressed-size: int
11389 amount of bytes after compression
11390 compression-rate: number
11392 rate of compressed size
11393 Since
11395 3.1
11396 MigrationStatus (Enum)
11398 An enumeration of migration status.
11399 Values
11401 none no migration has ever happened.
11402 setup migration process has been initiated.
11404 cancelling
11406 in the process of cancelling migration.
11407 cancelled
11409 cancelling migration is finished.
11410 active in the process of doing migration.
11412 postcopy-active
11414 like active, but now in postcopy mode. (since 2.5)
11415 postcopy-paused
11417 during postcopy but paused. (since 3.0)
11418 postcopy-recover
11420 trying to recover from a paused postcopy. (since 3.0)
11421 completed
11423 migration is finished.
11424 failed some error occurred during migration process.
11426 colo VM is in the process of fault tolerance, VM can not get into
11428 this state unless colo capability is enabled for migration.
11429 (since 2.8)
11430 pre-switchover
11432 Paused before device serialisation. (since 2.11)
11433 device During device serialisation when pause-before-switchover is en‐
11435 abled (since 2.11)
11436 wait-unplug
11438 wait for device unplug request by guest OS to be completed.
11439 (since 4.2)
11440 Since
11442 2.3
11443 VfioStats (Object)
11445 Detailed VFIO devices migration statistics
11446 Members
11448 transferred: int
11449 amount of bytes transferred to the target VM by VFIO devices
11450 Since
11452 5.2
11453 MigrationInfo (Object)
11455 Information about current migration process.
11456 Members
11458 status: MigrationStatus (optional)
11459 MigrationStatus describing the current migration status. If
11460 this field is not returned, no migration process has been initi‐
11461 ated
11462 ram: MigrationStats (optional)
11464 MigrationStats containing detailed migration status, only re‐
11465 turned if status is 'active' or 'completed'(since 1.2)
11466 disk: MigrationStats (optional)
11468 MigrationStats containing detailed disk migration status, only
11469 returned if status is 'active' and it is a block migration
11470 xbzrle-cache: XBZRLECacheStats (optional)
11472 XBZRLECacheStats containing detailed XBZRLE migration statis‐
11473 tics, only returned if XBZRLE feature is on and status is 'ac‐
11474 tive' or 'completed' (since 1.2)
11475 total-time: int (optional)
11477 total amount of milliseconds since migration started. If migra‐
11478 tion has ended, it returns the total migration time. (since 1.2)
11479 downtime: int (optional)
11481 only present when migration finishes correctly total downtime in
11482 milliseconds for the guest. (since 1.3)
11483 expected-downtime: int (optional)
11485 only present while migration is active expected downtime in mil‐
11486 liseconds for the guest in last walk of the dirty bitmap. (since
11487 1.3)
11488 setup-time: int (optional)
11490 amount of setup time in milliseconds before the iterations begin
11491 but after the QMP command is issued. This is designed to provide
11492 an accounting of any activities (such as RDMA pinning) which may
11493 be expensive, but do not actually occur during the iterative mi‐
11494 gration rounds themselves. (since 1.6)
11495 cpu-throttle-percentage: int (optional)
11497 percentage of time guest cpus are being throttled during
11498 auto-converge. This is only present when auto-converge has
11499 started throttling guest cpus. (Since 2.7)
11500 error-desc: string (optional)
11502 the human readable error description string, when status is
11503 'failed'. Clients should not attempt to parse the error strings.
11504 (Since 2.7)
11505 postcopy-blocktime: int (optional)
11507 total time when all vCPU were blocked during postcopy live mi‐
11508 gration. This is only present when the postcopy-blocktime migra‐
11509 tion capability is enabled. (Since 3.0)
11510 postcopy-vcpu-blocktime: array of int (optional)
11512 list of the postcopy blocktime per vCPU. This is only present
11513 when the postcopy-blocktime migration capability is enabled.
11514 (Since 3.0)
11515 compression: CompressionStats (optional)
11517 migration compression statistics, only returned if compression
11518 feature is on and status is 'active' or 'completed' (Since 3.1)
11519 socket-address: array of SocketAddress (optional)
11521 Only used for tcp, to know what the real port is (Since 4.0)
11522 vfio: VfioStats (optional)
11524 VfioStats containing detailed VFIO devices migration statistics,
11525 only returned if VFIO device is present, migration is supported
11526 by all VFIO devices and status is 'active' or 'completed' (since
11527 5.2)
11528 Since
11530 0.14.0
11531 query-migrate (Command)
11533 Returns information about current migration process. If migration is
11534 active there will be another json-object with RAM migration status and
11535 if block migration is active another one with block migration status.
11536 Returns
11538 MigrationInfo
11539 Since
11541 0.14.0
11542 Example
11544 1. Before the first migration
11545 -> { "execute": "query-migrate" }
11547 <- { "return": {} }
11548 2. Migration is done and has succeeded
11550 -> { "execute": "query-migrate" }
11552 <- { "return": {
11553 "status": "completed",
11554 "total-time":12345,
11555 "setup-time":12345,
11556 "downtime":12345,
11557 "ram":{
11558 "transferred":123,
11559 "remaining":123,
11560 "total":246,
11561 "duplicate":123,
11562 "normal":123,
11563 "normal-bytes":123456,
11564 "dirty-sync-count":15
11565 }
11566 }
11567 }
11568 3. Migration is done and has failed
11570 -> { "execute": "query-migrate" }
11572 <- { "return": { "status": "failed" } }
11573 4. Migration is being performed and is not a block migration:
11575 -> { "execute": "query-migrate" }
11577 <- {
11578 "return":{
11579 "status":"active",
11580 "total-time":12345,
11581 "setup-time":12345,
11582 "expected-downtime":12345,
11583 "ram":{
11584 "transferred":123,
11585 "remaining":123,
11586 "total":246,
11587 "duplicate":123,
11588 "normal":123,
11589 "normal-bytes":123456,
11590 "dirty-sync-count":15
11591 }
11592 }
11593 }
11594 5. Migration is being performed and is a block migration:
11596 -> { "execute": "query-migrate" }
11598 <- {
11599 "return":{
11600 "status":"active",
11601 "total-time":12345,
11602 "setup-time":12345,
11603 "expected-downtime":12345,
11604 "ram":{
11605 "total":1057024,
11606 "remaining":1053304,
11607 "transferred":3720,
11608 "duplicate":123,
11609 "normal":123,
11610 "normal-bytes":123456,
11611 "dirty-sync-count":15
11612 },
11613 "disk":{
11614 "total":20971520,
11615 "remaining":20880384,
11616 "transferred":91136
11617 }
11618 }
11619 }
11620 6. Migration is being performed and XBZRLE is active:
11622 -> { "execute": "query-migrate" }
11624 <- {
11625 "return":{
11626 "status":"active",
11627 "total-time":12345,
11628 "setup-time":12345,
11629 "expected-downtime":12345,
11630 "ram":{
11631 "total":1057024,
11632 "remaining":1053304,
11633 "transferred":3720,
11634 "duplicate":10,
11635 "normal":3333,
11636 "normal-bytes":3412992,
11637 "dirty-sync-count":15
11638 },
11639 "xbzrle-cache":{
11640 "cache-size":67108864,
11641 "bytes":20971520,
11642 "pages":2444343,
11643 "cache-miss":2244,
11644 "cache-miss-rate":0.123,
11645 "encoding-rate":80.1,
11646 "overflow":34434
11647 }
11648 }
11649 }
11650 MigrationCapability (Enum)
11652 Migration capabilities enumeration
11653 Values
11655 xbzrle Migration supports xbzrle (Xor Based Zero Run Length Encoding).
11656 This feature allows us to minimize migration traffic for certain
11657 work loads, by sending compressed difference of the pages
11658 rdma-pin-all
11660 Controls whether or not the entire VM memory footprint is
11661 mlock()'d on demand or all at once. Refer to docs/rdma.txt for
11662 usage. Disabled by default. (since 2.0)
11663 zero-blocks
11665 During storage migration encode blocks of zeroes efficiently.
11666 This essentially saves 1MB of zeroes per block on the wire. En‐
11667 abling requires source and target VM to support this feature. To
11668 enable it is sufficient to enable the capability on the source
11669 VM. The feature is disabled by default. (since 1.6)
11670 compress
11672 Use multiple compression threads to accelerate live migration.
11673 This feature can help to reduce the migration traffic, by send‐
11674 ing compressed pages. Please note that if compress and xbzrle
11675 are both on, compress only takes effect in the ram bulk stage,
11676 after that, it will be disabled and only xbzrle takes effect,
11677 this can help to minimize migration traffic. The feature is dis‐
11678 abled by default. (since 2.4 )
11679 events generate events for each migration state change (since 2.4 )
11681 auto-converge
11683 If enabled, QEMU will automatically throttle down the guest to
11684 speed up convergence of RAM migration. (since 1.6)
11685 postcopy-ram
11687 Start executing on the migration target before all of RAM has
11688 been migrated, pulling the remaining pages along as needed. The
11689 capacity must have the same setting on both source and target or
11690 migration will not even start. NOTE: If the migration fails dur‐
11691 ing postcopy the VM will fail. (since 2.6)
11692 x-colo If enabled, migration will never end, and the state of the VM on
11694 the primary side will be migrated continuously to the VM on sec‐
11695 ondary side, this process is called COarse-Grain LOck Stepping
11696 (COLO) for Non-stop Service. (since 2.8)
11697 release-ram
11699 if enabled, qemu will free the migrated ram pages on the source
11700 during postcopy-ram migration. (since 2.9)
11701 block If enabled, QEMU will also migrate the contents of all block de‐
11703 vices. Default is disabled. A possible alternative uses mirror
11704 jobs to a builtin NBD server on the destination, which offers
11705 more flexibility. (Since 2.10)
11706 return-path
11708 If enabled, migration will use the return path even for precopy.
11709 (since 2.10)
11710 pause-before-switchover
11712 Pause outgoing migration before serialising device state and be‐
11713 fore disabling block IO (since 2.11)
11714 multifd
11716 Use more than one fd for migration (since 4.0)
11717 dirty-bitmaps
11719 If enabled, QEMU will migrate named dirty bitmaps. (since 2.12)
11720 postcopy-blocktime
11722 Calculate downtime for postcopy live migration (since 3.0)
11723 late-block-activate
11725 If enabled, the destination will not activate block devices (and
11726 thus take locks) immediately at the end of migration. (since
11727 3.0)
11728 x-ignore-shared
11730 If enabled, QEMU will not migrate shared memory (since 4.0)
11731 validate-uuid
11733 Send the UUID of the source to allow the destination to ensure
11734 it is the same. (since 4.2)
11735 Since
11737 1.2
11738 MigrationCapabilityStatus (Object)
11740 Migration capability information
11741 Members
11743 capability: MigrationCapability
11744 capability enum
11745 state: boolean
11747 capability state bool
11748 Since
11750 1.2
11751 migrate-set-capabilities (Command)
11753 Enable/Disable the following migration capabilities (like xbzrle)
11754 Arguments
11756 capabilities: array of MigrationCapabilityStatus
11757 json array of capability modifications to make
11758 Since
11760 1.2
11761 Example
11763 -> { "execute": "migrate-set-capabilities" , "arguments":
11764 { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
11765 query-migrate-capabilities (Command)
11767 Returns information about the current migration capabilities status
11768 Returns
11770 MigrationCapabilitiesStatus
11771 Since
11773 1.2
11774 Example
11776 -> { "execute": "query-migrate-capabilities" }
11777 <- { "return": [
11778 {"state": false, "capability": "xbzrle"},
11779 {"state": false, "capability": "rdma-pin-all"},
11780 {"state": false, "capability": "auto-converge"},
11781 {"state": false, "capability": "zero-blocks"},
11782 {"state": false, "capability": "compress"},
11783 {"state": true, "capability": "events"},
11784 {"state": false, "capability": "postcopy-ram"},
11785 {"state": false, "capability": "x-colo"}
11786 ]}
11787 MultiFDCompression (Enum)
11789 An enumeration of multifd compression methods.
11790 Values
11792 none no compression.
11793 zlib use zlib compression method.
11795 zstd (If: defined(CONFIG_ZSTD))
11797 use zstd compression method.
11798 Since
11800 5.0
11801 BitmapMigrationBitmapAlias (Object)
11803 Members
11804 name: string
11805 The name of the bitmap.
11806 alias: string
11808 An alias name for migration (for example the bitmap name on the
11809 opposite site).
11810 Since
11812 5.2
11813 BitmapMigrationNodeAlias (Object)
11815 Maps a block node name and the bitmaps it has to aliases for dirty bit‐
11816 map migration.
11817 Members
11819 node-name: string
11820 A block node name.
11821 alias: string
11823 An alias block node name for migration (for example the node
11824 name on the opposite site).
11825 bitmaps: array of BitmapMigrationBitmapAlias
11827 Mappings for the bitmaps on this node.
11828 Since
11830 5.2
11831 MigrationParameter (Enum)
11833 Migration parameters enumeration
11834 Values
11836 announce-initial
11837 Initial delay (in milliseconds) before sending the first an‐
11838 nounce (Since 4.0)
11839 announce-max
11841 Maximum delay (in milliseconds) between packets in the announce‐
11842 ment (Since 4.0)
11843 announce-rounds
11845 Number of self-announce packets sent after migration (Since 4.0)
11846 announce-step
11848 Increase in delay (in milliseconds) between subsequent packets
11849 in the announcement (Since 4.0)
11850 compress-level
11852 Set the compression level to be used in live migration, the com‐
11853 pression level is an integer between 0 and 9, where 0 means no
11854 compression, 1 means the best compression speed, and 9 means
11855 best compression ratio which will consume more CPU.
11856 compress-threads
11858 Set compression thread count to be used in live migration, the
11859 compression thread count is an integer between 1 and 255.
11860 compress-wait-thread
11862 Controls behavior when all compression threads are currently
11863 busy. If true (default), wait for a free compression thread to
11864 become available; otherwise, send the page uncompressed. (Since
11865 3.1)
11866 decompress-threads
11868 Set decompression thread count to be used in live migration, the
11869 decompression thread count is an integer between 1 and 255. Usu‐
11870 ally, decompression is at least 4 times as fast as compression,
11871 so set the decompress-threads to the number about 1/4 of com‐
11872 press-threads is adequate.
11873 throttle-trigger-threshold
11875 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
11876 throttling. It is expressed as percentage. The default value is
11877 50. (Since 5.0)
11878 cpu-throttle-initial
11880 Initial percentage of time guest cpus are throttled when migra‐
11881 tion auto-converge is activated. The default value is 20. (Since
11882 2.7)
11883 cpu-throttle-increment
11885 throttle percentage increase each time auto-converge detects
11886 that migration is not making progress. The default value is 10.
11887 (Since 2.7)
11888 cpu-throttle-tailslow
11890 Make CPU throttling slower at tail stage At the tail stage of
11891 throttling, the Guest is very sensitive to CPU percentage while
11892 the cpu-throttle -increment is excessive usually at tail stage.
11893 If this parameter is true, we will compute the ideal CPU per‐
11894 centage used by the Guest, which may exactly make the dirty rate
11895 match the dirty rate threshold. Then we will choose a smaller
11896 throttle increment between the one specified by cpu-throttle-in‐
11897 crement and the one generated by ideal CPU percentage. There‐
11898 fore, it is compatible to traditional throttling, meanwhile the
11899 throttle increment won't be excessive at tail stage. The de‐
11900 fault value is false. (Since 5.1)
11901 tls-creds
11903 ID of the 'tls-creds' object that provides credentials for es‐
11904 tablishing a TLS connection over the migration data channel. On
11905 the outgoing side of the migration, the credentials must be for
11906 a 'client' endpoint, while for the incoming side the credentials
11907 must be for a 'server' endpoint. Setting this will enable TLS
11908 for all migrations. The default is unset, resulting in unsecured
11909 migration at the QEMU level. (Since 2.7)
11910 tls-hostname
11912 hostname of the target host for the migration. This is required
11913 when using x509 based TLS credentials and the migration URI does
11914 not already include a hostname. For example if using fd: or
11915 exec: based migration, the hostname must be provided so that the
11916 server's x509 certificate identity can be validated. (Since 2.7)
11917 tls-authz
11919 ID of the 'authz' object subclass that provides access control
11920 checking of the TLS x509 certificate distinguished name. This
11921 object is only resolved at time of use, so can be deleted and
11922 recreated on the fly while the migration server is active. If
11923 missing, it will default to denying access (Since 4.0)
11924 max-bandwidth
11926 to set maximum speed for migration. maximum speed in bytes per
11927 second. (Since 2.8)
11928 downtime-limit
11930 set maximum tolerated downtime for migration. maximum downtime
11931 in milliseconds (Since 2.8)
11932 x-checkpoint-delay
11934 The delay time (in ms) between two COLO checkpoints in periodic
11935 mode. (Since 2.8)
11936 block-incremental
11938 Affects how much storage is migrated when the block migration
11939 capability is enabled. When false, the entire storage backing
11940 chain is migrated into a flattened image at the destination;
11941 when true, only the active qcow2 layer is migrated and the des‐
11942 tination must already have access to the same backing chain as
11943 was used on the source. (since 2.10)
11944 multifd-channels
11946 Number of channels used to migrate data in parallel. This is the
11947 same number that the number of sockets used for migration. The
11948 default value is 2 (since 4.0)
11949 xbzrle-cache-size
11951 cache size to be used by XBZRLE migration. It needs to be a
11952 multiple of the target page size and a power of 2 (Since 2.11)
11953 max-postcopy-bandwidth
11955 Background transfer bandwidth during postcopy. Defaults to 0
11956 (unlimited). In bytes per second. (Since 3.0)
11957 max-cpu-throttle
11959 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
11960 multifd-compression
11962 Which compression method to use. Defaults to none. (Since 5.0)
11963 multifd-zlib-level
11965 Set the compression level to be used in live migration, the com‐
11966 pression level is an integer between 0 and 9, where 0 means no
11967 compression, 1 means the best compression speed, and 9 means
11968 best compression ratio which will consume more CPU. Defaults to
11969 1. (Since 5.0)
11970 multifd-zstd-level
11972 Set the compression level to be used in live migration, the com‐
11973 pression level is an integer between 0 and 20, where 0 means no
11974 compression, 1 means the best compression speed, and 20 means
11975 best compression ratio which will consume more CPU. Defaults to
11976 1. (Since 5.0)
11977 block-bitmap-mapping
11979 Maps block nodes and bitmaps on them to aliases for the purpose
11980 of dirty bitmap migration. Such aliases may for example be the
11981 corresponding names on the opposite site. The mapping must be
11982 one-to-one, but not necessarily complete: On the source, un‐
11983 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
11984 nored. On the destination, encountering an unmapped alias in
11985 the incoming migration stream will result in a report, and all
11986 further bitmap migration data will then be discarded. Note that
11987 the destination does not know about bitmaps it does not receive,
11988 so there is no limitation or requirement regarding the number of
11989 bitmaps received, or how they are named, or on which nodes they
11990 are placed. By default (when this parameter has never been
11991 set), bitmap names are mapped to themselves. Nodes are mapped
11992 to their block device name if there is one, and to their node
11993 name otherwise. (Since 5.2)
11994 Since
11996 2.4
11997 MigrateSetParameters (Object)
11999 Members
12000 announce-initial: int (optional)
12001 Initial delay (in milliseconds) before sending the first an‐
12002 nounce (Since 4.0)
12003 announce-max: int (optional)
12005 Maximum delay (in milliseconds) between packets in the announce‐
12006 ment (Since 4.0)
12007 announce-rounds: int (optional)
12009 Number of self-announce packets sent after migration (Since 4.0)
12010 announce-step: int (optional)
12012 Increase in delay (in milliseconds) between subsequent packets
12013 in the announcement (Since 4.0)
12014 compress-level: int (optional)
12016 compression level
12017 compress-threads: int (optional)
12019 compression thread count
12020 compress-wait-thread: boolean (optional)
12022 Controls behavior when all compression threads are currently
12023 busy. If true (default), wait for a free compression thread to
12024 become available; otherwise, send the page uncompressed. (Since
12025 3.1)
12026 decompress-threads: int (optional)
12028 decompression thread count
12029 throttle-trigger-threshold: int (optional)
12031 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
12032 throttling. It is expressed as percentage. The default value is
12033 50. (Since 5.0)
12034 cpu-throttle-initial: int (optional)
12036 Initial percentage of time guest cpus are throttled when migra‐
12037 tion auto-converge is activated. The default value is 20.
12038 (Since 2.7)
12039 cpu-throttle-increment: int (optional)
12041 throttle percentage increase each time auto-converge detects
12042 that migration is not making progress. The default value is 10.
12043 (Since 2.7)
12044 cpu-throttle-tailslow: boolean (optional)
12046 Make CPU throttling slower at tail stage At the tail stage of
12047 throttling, the Guest is very sensitive to CPU percentage while
12048 the cpu-throttle -increment is excessive usually at tail stage.
12049 If this parameter is true, we will compute the ideal CPU per‐
12050 centage used by the Guest, which may exactly make the dirty rate
12051 match the dirty rate threshold. Then we will choose a smaller
12052 throttle increment between the one specified by cpu-throttle-in‐
12053 crement and the one generated by ideal CPU percentage. There‐
12054 fore, it is compatible to traditional throttling, meanwhile the
12055 throttle increment won't be excessive at tail stage. The de‐
12056 fault value is false. (Since 5.1)
12057 tls-creds: StrOrNull (optional)
12059 ID of the 'tls-creds' object that provides credentials for es‐
12060 tablishing a TLS connection over the migration data channel. On
12061 the outgoing side of the migration, the credentials must be for
12062 a 'client' endpoint, while for the incoming side the credentials
12063 must be for a 'server' endpoint. Setting this to a non-empty
12064 string enables TLS for all migrations. An empty string means
12065 that QEMU will use plain text mode for migration, rather than
12066 TLS (Since 2.9) Previously (since 2.7), this was reported by
12067 omitting tls-creds instead.
12068 tls-hostname: StrOrNull (optional)
12070 hostname of the target host for the migration. This is required
12071 when using x509 based TLS credentials and the migration URI does
12072 not already include a hostname. For example if using fd: or
12073 exec: based migration, the hostname must be provided so that the
12074 server's x509 certificate identity can be validated. (Since 2.7)
12075 An empty string means that QEMU will use the hostname associated
12076 with the migration URI, if any. (Since 2.9) Previously (since
12077 2.7), this was reported by omitting tls-hostname instead.
12078 max-bandwidth: int (optional)
12080 to set maximum speed for migration. maximum speed in bytes per
12081 second. (Since 2.8)
12082 downtime-limit: int (optional)
12084 set maximum tolerated downtime for migration. maximum downtime
12085 in milliseconds (Since 2.8)
12086 x-checkpoint-delay: int (optional)
12088 the delay time between two COLO checkpoints. (Since 2.8)
12089 block-incremental: boolean (optional)
12091 Affects how much storage is migrated when the block migration
12092 capability is enabled. When false, the entire storage backing
12093 chain is migrated into a flattened image at the destination;
12094 when true, only the active qcow2 layer is migrated and the des‐
12095 tination must already have access to the same backing chain as
12096 was used on the source. (since 2.10)
12097 multifd-channels: int (optional)
12099 Number of channels used to migrate data in parallel. This is the
12100 same number that the number of sockets used for migration. The
12101 default value is 2 (since 4.0)
12102 xbzrle-cache-size: int (optional)
12104 cache size to be used by XBZRLE migration. It needs to be a
12105 multiple of the target page size and a power of 2 (Since 2.11)
12106 max-postcopy-bandwidth: int (optional)
12108 Background transfer bandwidth during postcopy. Defaults to 0
12109 (unlimited). In bytes per second. (Since 3.0)
12110 max-cpu-throttle: int (optional)
12112 maximum cpu throttle percentage. The default value is 99.
12113 (Since 3.1)
12114 multifd-compression: MultiFDCompression (optional)
12116 Which compression method to use. Defaults to none. (Since 5.0)
12117 multifd-zlib-level: int (optional)
12119 Set the compression level to be used in live migration, the com‐
12120 pression level is an integer between 0 and 9, where 0 means no
12121 compression, 1 means the best compression speed, and 9 means
12122 best compression ratio which will consume more CPU. Defaults to
12123 1. (Since 5.0)
12124 multifd-zstd-level: int (optional)
12126 Set the compression level to be used in live migration, the com‐
12127 pression level is an integer between 0 and 20, where 0 means no
12128 compression, 1 means the best compression speed, and 20 means
12129 best compression ratio which will consume more CPU. Defaults to
12130 1. (Since 5.0)
12131 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
12133 Maps block nodes and bitmaps on them to aliases for the purpose
12134 of dirty bitmap migration. Such aliases may for example be the
12135 corresponding names on the opposite site. The mapping must be
12136 one-to-one, but not necessarily complete: On the source, un‐
12137 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
12138 nored. On the destination, encountering an unmapped alias in
12139 the incoming migration stream will result in a report, and all
12140 further bitmap migration data will then be discarded. Note that
12141 the destination does not know about bitmaps it does not receive,
12142 so there is no limitation or requirement regarding the number of
12143 bitmaps received, or how they are named, or on which nodes they
12144 are placed. By default (when this parameter has never been
12145 set), bitmap names are mapped to themselves. Nodes are mapped
12146 to their block device name if there is one, and to their node
12147 name otherwise. (Since 5.2)
12148 tls-authz: StrOrNull (optional)
12150 Not documented
12151 Since
12153 2.4
12154 migrate-set-parameters (Command)
12156 Set various migration parameters.
12157 Arguments
12159 The members of MigrateSetParameters
12160 Since
12162 2.4
12163 Example
12165 -> { "execute": "migrate-set-parameters" ,
12166 "arguments": { "compress-level": 1 } }
12167 MigrationParameters (Object)
12169 The optional members aren't actually optional.
12170 Members
12172 announce-initial: int (optional)
12173 Initial delay (in milliseconds) before sending the first an‐
12174 nounce (Since 4.0)
12175 announce-max: int (optional)
12177 Maximum delay (in milliseconds) between packets in the announce‐
12178 ment (Since 4.0)
12179 announce-rounds: int (optional)
12181 Number of self-announce packets sent after migration (Since 4.0)
12182 announce-step: int (optional)
12184 Increase in delay (in milliseconds) between subsequent packets
12185 in the announcement (Since 4.0)
12186 compress-level: int (optional)
12188 compression level
12189 compress-threads: int (optional)
12191 compression thread count
12192 compress-wait-thread: boolean (optional)
12194 Controls behavior when all compression threads are currently
12195 busy. If true (default), wait for a free compression thread to
12196 become available; otherwise, send the page uncompressed. (Since
12197 3.1)
12198 decompress-threads: int (optional)
12200 decompression thread count
12201 throttle-trigger-threshold: int (optional)
12203 The ratio of bytes_dirty_period and bytes_xfer_period to trigger
12204 throttling. It is expressed as percentage. The default value is
12205 50. (Since 5.0)
12206 cpu-throttle-initial: int (optional)
12208 Initial percentage of time guest cpus are throttled when migra‐
12209 tion auto-converge is activated. (Since 2.7)
12210 cpu-throttle-increment: int (optional)
12212 throttle percentage increase each time auto-converge detects
12213 that migration is not making progress. (Since 2.7)
12214 cpu-throttle-tailslow: boolean (optional)
12216 Make CPU throttling slower at tail stage At the tail stage of
12217 throttling, the Guest is very sensitive to CPU percentage while
12218 the cpu-throttle -increment is excessive usually at tail stage.
12219 If this parameter is true, we will compute the ideal CPU per‐
12220 centage used by the Guest, which may exactly make the dirty rate
12221 match the dirty rate threshold. Then we will choose a smaller
12222 throttle increment between the one specified by cpu-throttle-in‐
12223 crement and the one generated by ideal CPU percentage. There‐
12224 fore, it is compatible to traditional throttling, meanwhile the
12225 throttle increment won't be excessive at tail stage. The de‐
12226 fault value is false. (Since 5.1)
12227 tls-creds: string (optional)
12229 ID of the 'tls-creds' object that provides credentials for es‐
12230 tablishing a TLS connection over the migration data channel. On
12231 the outgoing side of the migration, the credentials must be for
12232 a 'client' endpoint, while for the incoming side the credentials
12233 must be for a 'server' endpoint. An empty string means that
12234 QEMU will use plain text mode for migration, rather than TLS
12235 (Since 2.7) Note: 2.8 reports this by omitting tls-creds in‐
12236 stead.
12237 tls-hostname: string (optional)
12239 hostname of the target host for the migration. This is required
12240 when using x509 based TLS credentials and the migration URI does
12241 not already include a hostname. For example if using fd: or
12242 exec: based migration, the hostname must be provided so that the
12243 server's x509 certificate identity can be validated. (Since 2.7)
12244 An empty string means that QEMU will use the hostname associated
12245 with the migration URI, if any. (Since 2.9) Note: 2.8 reports
12246 this by omitting tls-hostname instead.
12247 tls-authz: string (optional)
12249 ID of the 'authz' object subclass that provides access control
12250 checking of the TLS x509 certificate distinguished name. (Since
12251 4.0)
12252 max-bandwidth: int (optional)
12254 to set maximum speed for migration. maximum speed in bytes per
12255 second. (Since 2.8)
12256 downtime-limit: int (optional)
12258 set maximum tolerated downtime for migration. maximum downtime
12259 in milliseconds (Since 2.8)
12260 x-checkpoint-delay: int (optional)
12262 the delay time between two COLO checkpoints. (Since 2.8)
12263 block-incremental: boolean (optional)
12265 Affects how much storage is migrated when the block migration
12266 capability is enabled. When false, the entire storage backing
12267 chain is migrated into a flattened image at the destination;
12268 when true, only the active qcow2 layer is migrated and the des‐
12269 tination must already have access to the same backing chain as
12270 was used on the source. (since 2.10)
12271 multifd-channels: int (optional)
12273 Number of channels used to migrate data in parallel. This is the
12274 same number that the number of sockets used for migration. The
12275 default value is 2 (since 4.0)
12276 xbzrle-cache-size: int (optional)
12278 cache size to be used by XBZRLE migration. It needs to be a
12279 multiple of the target page size and a power of 2 (Since 2.11)
12280 max-postcopy-bandwidth: int (optional)
12282 Background transfer bandwidth during postcopy. Defaults to 0
12283 (unlimited). In bytes per second. (Since 3.0)
12284 max-cpu-throttle: int (optional)
12286 maximum cpu throttle percentage. Defaults to 99. (Since 3.1)
12287 multifd-compression: MultiFDCompression (optional)
12289 Which compression method to use. Defaults to none. (Since 5.0)
12290 multifd-zlib-level: int (optional)
12292 Set the compression level to be used in live migration, the com‐
12293 pression level is an integer between 0 and 9, where 0 means no
12294 compression, 1 means the best compression speed, and 9 means
12295 best compression ratio which will consume more CPU. Defaults to
12296 1. (Since 5.0)
12297 multifd-zstd-level: int (optional)
12299 Set the compression level to be used in live migration, the com‐
12300 pression level is an integer between 0 and 20, where 0 means no
12301 compression, 1 means the best compression speed, and 20 means
12302 best compression ratio which will consume more CPU. Defaults to
12303 1. (Since 5.0)
12304 block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
12306 Maps block nodes and bitmaps on them to aliases for the purpose
12307 of dirty bitmap migration. Such aliases may for example be the
12308 corresponding names on the opposite site. The mapping must be
12309 one-to-one, but not necessarily complete: On the source, un‐
12310 mapped bitmaps and all bitmaps on unmapped nodes will be ig‐
12311 nored. On the destination, encountering an unmapped alias in
12312 the incoming migration stream will result in a report, and all
12313 further bitmap migration data will then be discarded. Note that
12314 the destination does not know about bitmaps it does not receive,
12315 so there is no limitation or requirement regarding the number of
12316 bitmaps received, or how they are named, or on which nodes they
12317 are placed. By default (when this parameter has never been
12318 set), bitmap names are mapped to themselves. Nodes are mapped
12319 to their block device name if there is one, and to their node
12320 name otherwise. (Since 5.2)
12321 Since
12323 2.4
12324 query-migrate-parameters (Command)
12326 Returns information about the current migration parameters
12327 Returns
12329 MigrationParameters
12330 Since
12332 2.4
12333 Example
12335 -> { "execute": "query-migrate-parameters" }
12336 <- { "return": {
12337 "decompress-threads": 2,
12338 "cpu-throttle-increment": 10,
12339 "compress-threads": 8,
12340 "compress-level": 1,
12341 "cpu-throttle-initial": 20,
12342 "max-bandwidth": 33554432,
12343 "downtime-limit": 300
12344 }
12345 }
12346 client_migrate_info (Command)
12348 Set migration information for remote display. This makes the server
12349 ask the client to automatically reconnect using the new parameters once
12350 migration finished successfully. Only implemented for SPICE.
12351 Arguments
12353 protocol: string
12354 must be "spice"
12355 hostname: string
12357 migration target hostname
12358 port: int (optional)
12360 spice tcp port for plaintext channels
12361 tls-port: int (optional)
12363 spice tcp port for tls-secured channels
12364 cert-subject: string (optional)
12366 server certificate subject
12367 Since
12369 0.14.0
12370 Example
12372 -> { "execute": "client_migrate_info",
12373 "arguments": { "protocol": "spice",
12374 "hostname": "virt42.lab.kraxel.org",
12375 "port": 1234 } }
12376 <- { "return": {} }
12377 migrate-start-postcopy (Command)
12379 Followup to a migration command to switch the migration to postcopy
12380 mode. The postcopy-ram capability must be set on both source and des‐
12381 tination before the original migration command.
12382 Since
12384 2.5
12385 Example
12387 -> { "execute": "migrate-start-postcopy" }
12388 <- { "return": {} }
12389 MIGRATION (Event)
12391 Emitted when a migration event happens
12392 Arguments
12394 status: MigrationStatus
12395 MigrationStatus describing the current migration status.
12396 Since
12398 2.4
12399 Example
12401 <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
12402 "event": "MIGRATION",
12403 "data": {"status": "completed"} }
12404 MIGRATION_PASS (Event)
12406 Emitted from the source side of a migration at the start of each pass
12407 (when it syncs the dirty bitmap)
12408 Arguments
12410 pass: int
12411 An incrementing count (starting at 1 on the first pass)
12412 Since
12414 2.6
12415 Example
12417 { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
12418 "event": "MIGRATION_PASS", "data": {"pass": 2} }
12419 COLOMessage (Enum)
12421 The message transmission between Primary side and Secondary side.
12422 Values
12424 checkpoint-ready
12425 Secondary VM (SVM) is ready for checkpointing
12426 checkpoint-request
12428 Primary VM (PVM) tells SVM to prepare for checkpointing
12429 checkpoint-reply
12431 SVM gets PVM's checkpoint request
12432 vmstate-send
12434 VM's state will be sent by PVM.
12435 vmstate-size
12437 The total size of VMstate.
12438 vmstate-received
12440 VM's state has been received by SVM.
12441 vmstate-loaded
12443 VM's state has been loaded by SVM.
12444 Since
12446 2.8
12447 COLOMode (Enum)
12449 The COLO current mode.
12450 Values
12452 none COLO is disabled.
12453 primary
12455 COLO node in primary side.
12456 secondary
12458 COLO node in slave side.
12459 Since
12461 2.8
12462 FailoverStatus (Enum)
12464 An enumeration of COLO failover status
12465 Values
12467 none no failover has ever happened
12468 require
12470 got failover requirement but not handled
12471 active in the process of doing failover
12473 completed
12475 finish the process of failover
12476 relaunch
12478 restart the failover process, from 'none' -> 'completed' (Since
12479 2.9)
12480 Since
12482 2.8
12483 COLO_EXIT (Event)
12485 Emitted when VM finishes COLO mode due to some errors happening or at
12486 the request of users.
12487 Arguments
12489 mode: COLOMode
12490 report COLO mode when COLO exited.
12491 reason: COLOExitReason
12493 describes the reason for the COLO exit.
12494 Since
12496 3.1
12497 Example
12499 <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
12500 "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
12501 COLOExitReason (Enum)
12503 The reason for a COLO exit.
12504 Values
12506 none failover has never happened. This state does not occur in the
12507 COLO_EXIT event, and is only visible in the result of
12508 query-colo-status.
12509 request
12511 COLO exit is due to an external request.
12512 error COLO exit is due to an internal error.
12514 processing
12516 COLO is currently handling a failover (since 4.0).
12517 Since
12519 3.1
12520 x-colo-lost-heartbeat (Command)
12522 Tell qemu that heartbeat is lost, request it to do takeover procedures.
12523 If this command is sent to the PVM, the Primary side will exit COLO
12524 mode. If sent to the Secondary, the Secondary side will run failover
12525 work, then takes over server operation to become the service VM.
12526 Since
12528 2.8
12529 Example
12531 -> { "execute": "x-colo-lost-heartbeat" }
12532 <- { "return": {} }
12533 migrate_cancel (Command)
12535 Cancel the current executing migration process.
12536 Returns
12538 nothing on success
12539 Notes
12541 This command succeeds even if there is no migration process running.
12542 Since
12544 0.14.0
12545 Example
12547 -> { "execute": "migrate_cancel" }
12548 <- { "return": {} }
12549 migrate-continue (Command)
12551 Continue migration when it's in a paused state.
12552 Arguments
12554 state: MigrationStatus
12555 The state the migration is currently expected to be in
12556 Returns
12558 nothing on success
12559 Since
12561 2.11
12562 Example
12564 -> { "execute": "migrate-continue" , "arguments":
12565 { "state": "pre-switchover" } }
12566 <- { "return": {} }
12567 migrate_set_downtime (Command)
12569 Set maximum tolerated downtime for migration.
12570 Arguments
12572 value: number
12573 maximum downtime in seconds
12574 Features
12576 deprecated
12577 This command is deprecated. Use 'migrate-set-parameters' in‐
12578 stead.
12579 Returns
12581 nothing on success
12582 Since
12584 0.14.0
12585 Example
12587 -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
12588 <- { "return": {} }
12589 migrate_set_speed (Command)
12591 Set maximum speed for migration.
12592 Arguments
12594 value: int
12595 maximum speed in bytes per second.
12596 Features
12598 deprecated
12599 This command is deprecated. Use 'migrate-set-parameters' in‐
12600 stead.
12601 Returns
12603 nothing on success
12604 Since
12606 0.14.0
12607 Example
12609 -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
12610 <- { "return": {} }
12611 migrate-set-cache-size (Command)
12613 Set cache size to be used by XBZRLE migration
12614 Arguments
12616 value: int
12617 cache size in bytes
12618 Features
12620 deprecated
12621 This command is deprecated. Use 'migrate-set-parameters' in‐
12622 stead.
12623 The size will be rounded down to the nearest power of 2. The cache
12624 size can be modified before and during ongoing migration
12625 Returns
12627 nothing on success
12628 Since
12630 1.2
12631 Example
12633 -> { "execute": "migrate-set-cache-size",
12634 "arguments": { "value": 536870912 } }
12635 <- { "return": {} }
12636 query-migrate-cache-size (Command)
12638 Query migration XBZRLE cache size
12639 Features
12641 deprecated
12642 This command is deprecated. Use 'query-migrate-parameters' in‐
12643 stead.
12644 Returns
12646 XBZRLE cache size in bytes
12647 Since
12649 1.2
12650 Example
12652 -> { "execute": "query-migrate-cache-size" }
12653 <- { "return": 67108864 }
12654 migrate (Command)
12656 Migrates the current running guest to another Virtual Machine.
12657 Arguments
12659 uri: string
12660 the Uniform Resource Identifier of the destination VM
12661 blk: boolean (optional)
12663 do block migration (full disk copy)
12664 inc: boolean (optional)
12666 incremental disk copy migration
12667 detach: boolean (optional)
12669 this argument exists only for compatibility reasons and is ig‐
12670 nored by QEMU
12671 resume: boolean (optional)
12673 resume one paused migration, default "off". (since 3.0)
12674 Returns
12676 nothing on success
12677 Since
12679 0.14.0
12680 Notes
12682 1. The 'query-migrate' command should be used to check migration's
12683 progress and final result (this information is provided by the 'sta‐
12684 tus' member)
12685 2. All boolean arguments default to false
12687 3. The user Monitor's "detach" argument is invalid in QMP and should
12689 not be used
12690 Example
12692 -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
12693 <- { "return": {} }
12694 migrate-incoming (Command)
12696 Start an incoming migration, the qemu must have been started with -in‐
12697 coming defer
12698 Arguments
12700 uri: string
12701 The Uniform Resource Identifier identifying the source or ad‐
12702 dress to listen on
12703 Returns
12705 nothing on success
12706 Since
12708 2.3
12709 Notes
12711 1. It's a bad idea to use a string for the uri, but it needs to stay
12712 compatible with -incoming and the format of the uri is already ex‐
12713 posed above libvirt.
12714 2. QEMU must be started with -incoming defer to allow migrate-incoming
12716 to be used.
12717 3. The uri format is the same as for -incoming
12719 Example
12721 -> { "execute": "migrate-incoming",
12722 "arguments": { "uri": "tcp::4446" } }
12723 <- { "return": {} }
12724 xen-save-devices-state (Command)
12726 Save the state of all devices to file. The RAM and the block devices of
12727 the VM are not saved by this command.
12728 Arguments
12730 filename: string
12731 the file to save the state of the devices to as binary data. See
12732 xen-save-devices-state.txt for a description of the binary for‐
12733 mat.
12734 live: boolean (optional)
12736 Optional argument to ask QEMU to treat this command as part of a
12737 live migration. Default to true. (since 2.11)
12738 Returns
12740 Nothing on success
12741 Since
12743 1.1
12744 Example
12746 -> { "execute": "xen-save-devices-state",
12747 "arguments": { "filename": "/tmp/save" } }
12748 <- { "return": {} }
12749 xen-set-global-dirty-log (Command)
12751 Enable or disable the global dirty log mode.
12752 Arguments
12754 enable: boolean
12755 true to enable, false to disable.
12756 Returns
12758 nothing
12759 Since
12761 1.3
12762 Example
12764 -> { "execute": "xen-set-global-dirty-log",
12765 "arguments": { "enable": true } }
12766 <- { "return": {} }
12767 xen-load-devices-state (Command)
12769 Load the state of all devices from file. The RAM and the block devices
12770 of the VM are not loaded by this command.
12771 Arguments
12773 filename: string
12774 the file to load the state of the devices from as binary data.
12775 See xen-save-devices-state.txt for a description of the binary
12776 format.
12777 Since
12779 2.7
12780 Example
12782 -> { "execute": "xen-load-devices-state",
12783 "arguments": { "filename": "/tmp/resume" } }
12784 <- { "return": {} }
12785 xen-set-replication (Command)
12787 Enable or disable replication.
12788 Arguments
12790 enable: boolean
12791 true to enable, false to disable.
12792 primary: boolean
12794 true for primary or false for secondary.
12795 failover: boolean (optional)
12797 true to do failover, false to stop. but cannot be specified if
12798 'enable' is true. default value is false.
12799 Returns
12801 nothing.
12802 Example
12804 -> { "execute": "xen-set-replication",
12805 "arguments": {"enable": true, "primary": false} }
12806 <- { "return": {} }
12807 Since
12809 2.9
12810 If
12812 defined(CONFIG_REPLICATION).SS ReplicationStatus (Object)
12813 The result format for 'query-xen-replication-status'.
12815 Members
12817 error: boolean
12818 true if an error happened, false if replication is normal.
12819 desc: string (optional)
12821 the human readable error description string, when error is
12822 'true'.
12823 Since
12825 2.9
12826 If
12828 defined(CONFIG_REPLICATION).SS query-xen-replication-status (Command)
12829 Query replication status while the vm is running.
12831 Returns
12833 A ReplicationResult object showing the status.
12834 Example
12836 -> { "execute": "query-xen-replication-status" }
12837 <- { "return": { "error": false } }
12838 Since
12840 2.9
12841 If
12843 defined(CONFIG_REPLICATION).SS xen-colo-do-checkpoint (Command)
12844 Xen uses this command to notify replication to trigger a checkpoint.
12846 Returns
12848 nothing.
12849 Example
12851 -> { "execute": "xen-colo-do-checkpoint" }
12852 <- { "return": {} }
12853 Since
12855 2.9
12856 If
12858 defined(CONFIG_REPLICATION).SS COLOStatus (Object)
12859 The result format for 'query-colo-status'.
12861 Members
12863 mode: COLOMode
12864 COLO running mode. If COLO is running, this field will return
12865 'primary' or 'secondary'.
12866 last-mode: COLOMode
12868 COLO last running mode. If COLO is running, this field will re‐
12869 turn same like mode field, after failover we can use this field
12870 to get last colo mode. (since 4.0)
12871 reason: COLOExitReason
12873 describes the reason for the COLO exit.
12874 Since
12876 3.1
12877 query-colo-status (Command)
12879 Query COLO status while the vm is running.
12880 Returns
12882 A COLOStatus object showing the status.
12883 Example
12885 -> { "execute": "query-colo-status" }
12886 <- { "return": { "mode": "primary", "reason": "request" } }
12887 Since
12889 3.1
12890 migrate-recover (Command)
12892 Provide a recovery migration stream URI.
12893 Arguments
12895 uri: string
12896 the URI to be used for the recovery of migration stream.
12897 Returns
12899 nothing.
12900 Example
12902 -> { "execute": "migrate-recover",
12903 "arguments": { "uri": "tcp:192.168.1.200:12345" } }
12904 <- { "return": {} }
12905 Since
12907 3.0
12908 migrate-pause (Command)
12910 Pause a migration. Currently it only supports postcopy.
12911 Returns
12913 nothing.
12914 Example
12916 -> { "execute": "migrate-pause" }
12917 <- { "return": {} }
12918 Since
12920 3.0
12921 UNPLUG_PRIMARY (Event)
12923 Emitted from source side of a migration when migration state is
12924 WAIT_UNPLUG. Device was unplugged by guest operating system. Device
12925 resources in QEMU are kept on standby to be able to re-plug it in case
12926 of migration failure.
12927 Arguments
12929 device-id: string
12930 QEMU device id of the unplugged device
12931 Since
12933 4.2
12934 Example
12936 {"event": "UNPLUG_PRIMARY", "data": {"device-id": "hostdev0"} }
12937 DirtyRateStatus (Enum)
12939 An enumeration of dirtyrate status.
12940 Values
12942 unstarted
12943 the dirtyrate thread has not been started.
12944 measuring
12946 the dirtyrate thread is measuring.
12947 measured
12949 the dirtyrate thread has measured and results are available.
12950 Since
12952 5.2
12953 DirtyRateInfo (Object)
12955 Information about current dirty page rate of vm.
12956 Members
12958 dirty-rate: int (optional)
12959 an estimate of the dirty page rate of the VM in units of MB/s,
12960 present only when estimating the rate has completed.
12961 status: DirtyRateStatus
12963 status containing dirtyrate query status includes 'unstarted' or
12964 'measuring' or 'measured'
12965 start-time: int
12967 start time in units of second for calculation
12968 calc-time: int
12970 time in units of second for sample dirty pages
12971 Since
12973 5.2
12974 calc-dirty-rate (Command)
12976 start calculating dirty page rate for vm
12977 Arguments
12979 calc-time: int
12980 time in units of second for sample dirty pages
12981 Since
12983 5.2
12984 Example
12986 {"command": "calc-dirty-rate", "data": {"calc-time": 1} }
12987 query-dirty-rate (Command)
12989 query dirty page rate in units of MB/s for vm
12990 Since
12992 5.2
12993
12995 Abort (Object)
12996 This action can be used to test transaction failure.
12997 Since
12999 1.6
13000 ActionCompletionMode (Enum)
13002 An enumeration of Transactional completion modes.
13003 Values
13005 individual
13006 Do not attempt to cancel any other Actions if any Actions fail
13007 after the Transaction request succeeds. All Actions that can
13008 complete successfully will do so without waiting on others.
13009 This is the default.
13010 grouped
13012 If any Action fails after the Transaction succeeds, cancel all
13013 Actions. Actions do not complete until all Actions are ready to
13014 complete. May be rejected by Actions that do not support this
13015 completion mode.
13016 Since
13018 2.5
13019 TransactionAction (Object)
13021 A discriminated record of operations that can be performed with trans‐
13022 action. Action type can be:
13023 • abort: since 1.6
13025 • block-dirty-bitmap-add: since 2.5
13027 • block-dirty-bitmap-remove: since 4.2
13029 • block-dirty-bitmap-clear: since 2.5
13031 • block-dirty-bitmap-enable: since 4.0
13033 • block-dirty-bitmap-disable: since 4.0
13035 • block-dirty-bitmap-merge: since 4.0
13037 • blockdev-backup: since 2.3
13039 • blockdev-snapshot: since 2.5
13041 • blockdev-snapshot-internal-sync: since 1.7
13043 • blockdev-snapshot-sync: since 1.1
13045 • drive-backup: since 1.6
13047 Members
13049 type One of abort, block-dirty-bitmap-add, block-dirty-bitmap-remove,
13050 block-dirty-bitmap-clear, block-dirty-bitmap-enable,
13051 block-dirty-bitmap-disable, block-dirty-bitmap-merge, block‐
13052 dev-backup, blockdev-snapshot, blockdev-snapshot-internal-sync,
13053 blockdev-snapshot-sync, drive-backup
13054 data: Abort when type is "abort"
13056 data: BlockDirtyBitmapAdd when type is "block-dirty-bitmap-add"
13058 data: BlockDirtyBitmap when type is "block-dirty-bitmap-remove"
13060 data: BlockDirtyBitmap when type is "block-dirty-bitmap-clear"
13062 data: BlockDirtyBitmap when type is "block-dirty-bitmap-enable"
13064 data: BlockDirtyBitmap when type is "block-dirty-bitmap-disable"
13066 data: BlockDirtyBitmapMerge when type is "block-dirty-bitmap-merge"
13068 data: BlockdevBackup when type is "blockdev-backup"
13070 data: BlockdevSnapshot when type is "blockdev-snapshot"
13072 data: BlockdevSnapshotInternal when type is "blockdev-snapshot-inter‐
13074 nal-sync"
13075 data: BlockdevSnapshotSync when type is "blockdev-snapshot-sync"
13077 data: DriveBackup when type is "drive-backup"
13079 Since
13081 1.1
13082 TransactionProperties (Object)
13084 Optional arguments to modify the behavior of a Transaction.
13085 Members
13087 completion-mode: ActionCompletionMode (optional)
13088 Controls how jobs launched asynchronously by Actions will com‐
13089 plete or fail as a group. See ActionCompletionMode for details.
13090 Since
13092 2.5
13093 transaction (Command)
13095 Executes a number of transactionable QMP commands atomically. If any
13096 operation fails, then the entire set of actions will be abandoned and
13097 the appropriate error returned.
13098 For external snapshots, the dictionary contains the device, the file to
13100 use for the new snapshot, and the format. The default format, if not
13101 specified, is qcow2.
13102 Each new snapshot defaults to being created by QEMU (wiping any con‐
13104 tents if the file already exists), but it is also possible to reuse an
13105 externally-created file. In the latter case, you should ensure that
13106 the new image file has the same contents as the current one; QEMU can‐
13107 not perform any meaningful check. Typically this is achieved by using
13108 the current image file as the backing file for the new image.
13109 On failure, the original disks pre-snapshot attempt will be used.
13111 For internal snapshots, the dictionary contains the device and the
13113 snapshot's name. If an internal snapshot matching name already exists,
13114 the request will be rejected. Only some image formats support it, for
13115 example, qcow2, rbd, and sheepdog.
13116 On failure, qemu will try delete the newly created internal snapshot in
13118 the transaction. When an I/O error occurs during deletion, the user
13119 needs to fix it later with qemu-img or other command.
13120 Arguments
13122 actions: array of TransactionAction
13123 List of TransactionAction; information needed for the respective
13124 operations.
13125 properties: TransactionProperties (optional)
13127 structure of additional options to control the execution of the
13128 transaction. See TransactionProperties for additional detail.
13129 Returns
13131 nothing on success
13132 Errors depend on the operations of the transaction
13134 Note
13136 The transaction aborts on the first failure. Therefore, there will be
13137 information on only one failed operation returned in an error condi‐
13138 tion, and subsequent actions will not have been attempted.
13139 Since
13141 1.1
13142 Example
13144 -> { "execute": "transaction",
13145 "arguments": { "actions": [
13146 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
13147 "snapshot-file": "/some/place/my-image",
13148 "format": "qcow2" } },
13149 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
13150 "snapshot-file": "/some/place/my-image2",
13151 "snapshot-node-name": "node3432",
13152 "mode": "existing",
13153 "format": "qcow2" } },
13154 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
13155 "snapshot-file": "/some/place/my-image2",
13156 "mode": "existing",
13157 "format": "qcow2" } },
13158 { "type": "blockdev-snapshot-internal-sync", "data" : {
13159 "device": "ide-hd2",
13160 "name": "snapshot0" } } ] } }
13161 <- { "return": {} }
13162
13164 TraceEventState (Enum)
13165 State of a tracing event.
13166 Values
13168 unavailable
13169 The event is statically disabled.
13170 disabled
13172 The event is dynamically disabled.
13173 enabled
13175 The event is dynamically enabled.
13176 Since
13178 2.2
13179 TraceEventInfo (Object)
13181 Information of a tracing event.
13182 Members
13184 name: string
13185 Event name.
13186 state: TraceEventState
13188 Tracing state.
13189 vcpu: boolean
13191 Whether this is a per-vCPU event (since 2.7).
13192 An event is per-vCPU if it has the "vcpu" property in the
13193 "trace-events" files.
13194 Since
13196 2.2
13197 trace-event-get-state (Command)
13199 Query the state of events.
13200 Arguments
13202 name: string
13203 Event name pattern (case-sensitive glob).
13204 vcpu: int (optional)
13206 The vCPU to query (any by default; since 2.7).
13207 Returns
13209 a list of TraceEventInfo for the matching events
13210 An event is returned if:
13212 • its name matches the name pattern, and
13214 • if vcpu is given, the event has the "vcpu" property.
13216 Therefore, if vcpu is given, the operation will only match per-vCPU
13218 events, returning their state on the specified vCPU. Special case: if
13219 name is an exact match, vcpu is given and the event does not have the
13220 "vcpu" property, an error is returned.
13221 Since
13223 2.2
13224 Example
13226 -> { "execute": "trace-event-get-state",
13227 "arguments": { "name": "qemu_memalign" } }
13228 <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
13229 trace-event-set-state (Command)
13231 Set the dynamic tracing state of events.
13232 Arguments
13234 name: string
13235 Event name pattern (case-sensitive glob).
13236 enable: boolean
13238 Whether to enable tracing.
13239 ignore-unavailable: boolean (optional)
13241 Do not match unavailable events with name.
13242 vcpu: int (optional)
13244 The vCPU to act upon (all by default; since 2.7).
13245 An event's state is modified if: - its name matches the name pattern,
13246 and - if vcpu is given, the event has the "vcpu" property.
13247 Therefore, if vcpu is given, the operation will only match per-vCPU
13249 events, setting their state on the specified vCPU. Special case: if
13250 name is an exact match, vcpu is given and the event does not have the
13251 "vcpu" property, an error is returned.
13252 Since
13254 2.2
13255 Example
13257 -> { "execute": "trace-event-set-state",
13258 "arguments": { "name": "qemu_memalign", "enable": "true" } }
13259 <- { "return": {} }
13260
13262 qmp_capabilities (Command)
13263 Enable QMP capabilities.
13264 Arguments:
13266 Arguments
13268 enable: array of QMPCapability (optional)
13269 An optional list of QMPCapability values to enable. The client
13270 must not enable any capability that is not mentioned in the QMP
13271 greeting message. If the field is not provided, it means no QMP
13272 capabilities will be enabled. (since 2.12)
13273 Example
13275 -> { "execute": "qmp_capabilities",
13276 "arguments": { "enable": [ "oob" ] } }
13277 <- { "return": {} }
13278 Notes
13280 This command is valid exactly when first connecting: it must be issued
13281 before any other command will be accepted, and will fail once the moni‐
13282 tor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
13283 The QMP client needs to explicitly enable QMP capabilities, otherwise
13285 all the QMP capabilities will be turned off by default.
13286 Since
13288 0.13
13289 QMPCapability (Enum)
13291 Enumeration of capabilities to be advertised during initial client con‐
13292 nection, used for agreeing on particular QMP extension behaviors.
13293 Values
13295 oob QMP ability to support out-of-band requests. (Please refer to
13296 qmp-spec.txt for more information on OOB)
13297 Since
13299 2.12
13300 VersionTriple (Object)
13302 A three-part version number.
13303 Members
13305 major: int
13306 The major version number.
13307 minor: int
13309 The minor version number.
13310 micro: int
13312 The micro version number.
13313 Since
13315 2.4
13316 VersionInfo (Object)
13318 A description of QEMU's version.
13319 Members
13321 qemu: VersionTriple
13322 The version of QEMU. By current convention, a micro version of
13323 50 signifies a development branch. A micro version greater than
13324 or equal to 90 signifies a release candidate for the next minor
13325 version. A micro version of less than 50 signifies a stable re‐
13326 lease.
13327 package: string
13329 QEMU will always set this field to an empty string. Downstream
13330 versions of QEMU should set this to a non-empty string. The ex‐
13331 act format depends on the downstream however it highly recom‐
13332 mended that a unique name is used.
13333 Since
13335 0.14.0
13336 query-version (Command)
13338 Returns the current version of QEMU.
13339 Returns
13341 A VersionInfo object describing the current version of QEMU.
13342 Since
13344 0.14.0
13345 Example
13347 -> { "execute": "query-version" }
13348 <- {
13349 "return":{
13350 "qemu":{
13351 "major":0,
13352 "minor":11,
13353 "micro":5
13354 },
13355 "package":""
13356 }
13357 }
13358 CommandInfo (Object)
13360 Information about a QMP command
13361 Members
13363 name: string
13364 The command name
13365 Since
13367 0.14.0
13368 query-commands (Command)
13370 Return a list of supported QMP commands by this server
13371 Returns
13373 A list of CommandInfo for all supported commands
13374 Since
13376 0.14.0
13377 Example
13379 -> { "execute": "query-commands" }
13380 <- {
13381 "return":[
13382 {
13383 "name":"query-balloon"
13384 },
13385 {
13386 "name":"system_powerdown"
13387 }
13388 ]
13389 }
13390 Note
13392 This example has been shortened as the real response is too long.
13393 EventInfo (Object)
13395 Information about a QMP event
13396 Members
13398 name: string
13399 The event name
13400 Since
13402 1.2.0
13403 query-events (Command)
13405 Return information on QMP events.
13406 Features
13408 deprecated
13409 This command is deprecated, because its output doesn't reflect
13410 compile-time configuration. Use 'query-qmp-schema' instead.
13411 Returns
13413 A list of EventInfo.
13414 Since
13416 1.2.0
13417 Example
13419 -> { "execute": "query-events" }
13420 <- {
13421 "return": [
13422 {
13423 "name":"SHUTDOWN"
13424 },
13425 {
13426 "name":"RESET"
13427 }
13428 ]
13429 }
13430 Note
13432 This example has been shortened as the real response is too long.
13433 quit (Command)
13435 This command will cause the QEMU process to exit gracefully. While ev‐
13436 ery attempt is made to send the QMP response before terminating, this
13437 is not guaranteed. When using this interface, a premature EOF would
13438 not be unexpected.
13439 Since
13441 0.14.0
13442 Example
13444 -> { "execute": "quit" }
13445 <- { "return": {} }
13446 MonitorMode (Enum)
13448 An enumeration of monitor modes.
13449 Values
13451 readline
13452 HMP monitor (human-oriented command line interface)
13453 control
13455 QMP monitor (JSON-based machine interface)
13456 Since
13458 5.0
13459 MonitorOptions (Object)
13461 Options to be used for adding a new monitor.
13462 Members
13464 id: string (optional)
13465 Name of the monitor
13466 mode: MonitorMode (optional)
13468 Selects the monitor mode (default: readline in the system emula‐
13469 tor, control in qemu-storage-daemon)
13470 pretty: boolean (optional)
13472 Enables pretty printing (QMP only)
13473 chardev: string
13475 Name of a character device to expose the monitor on
13476 Since
13478 5.0
13479
13481 query-qmp-schema (Command)
13482 Command query-qmp-schema exposes the QMP wire ABI as an array of
13483 SchemaInfo. This lets QMP clients figure out what commands and events
13484 are available in this QEMU, and their parameters and results.
13485 However, the SchemaInfo can't reflect all the rules and restrictions
13487 that apply to QMP. It's interface introspection (figuring out what's
13488 there), not interface specification. The specification is in the QAPI
13489 schema.
13490 Furthermore, while we strive to keep the QMP wire format backwards-com‐
13492 patible across qemu versions, the introspection output is not guaran‐
13493 teed to have the same stability. For example, one version of qemu may
13494 list an object member as an optional non-variant, while another lists
13495 the same member only through the object's variants; or the type of a
13496 member may change from a generic string into a specific enum or from
13497 one specific type into an alternate that includes the original type
13498 alongside something else.
13499 Returns
13501 array of SchemaInfo, where each element describes an entity in the ABI:
13502 command, event, type, ...
13503 The order of the various SchemaInfo is unspecified; however, all names
13505 are guaranteed to be unique (no name will be duplicated with different
13506 meta-types).
13507 Note
13509 the QAPI schema is also used to help define internal interfaces, by
13510 defining QAPI types. These are not part of the QMP wire ABI, and
13511 therefore not returned by this command.
13512 Since
13514 2.5
13515 SchemaMetaType (Enum)
13517 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
13518 Values
13520 builtin
13521 a predefined type such as 'int' or 'bool'.
13522 enum an enumeration type
13524 array an array type
13526 object an object type (struct or union)
13528 alternate
13530 an alternate type
13531 command
13533 a QMP command
13534 event a QMP event
13536 Since
13538 2.5
13539 SchemaInfo (Object)
13541 Members
13542 name: string
13543 the entity's name, inherited from base. The SchemaInfo is al‐
13544 ways referenced by this name. Commands and events have the name
13545 defined in the QAPI schema. Unlike command and event names,
13546 type names are not part of the wire ABI. Consequently, type
13547 names are meaningless strings here, although they are still
13548 guaranteed unique regardless of meta-type.
13549 meta-type: SchemaMetaType
13551 the entity's meta type, inherited from base.
13552 features: array of string (optional)
13554 names of features associated with the entity, in no particular
13555 order. (since 4.1 for object types, 4.2 for commands, 5.0 for
13556 the rest)
13557 The members of SchemaInfoBuiltin when meta-type is "builtin"
13559 The members of SchemaInfoEnum when meta-type is "enum"
13561 The members of SchemaInfoArray when meta-type is "array"
13563 The members of SchemaInfoObject when meta-type is "object"
13565 The members of SchemaInfoAlternate when meta-type is "alternate"
13567 The members of SchemaInfoCommand when meta-type is "command"
13569 The members of SchemaInfoEvent when meta-type is "event"
13571 Additional members depend on the value of meta-type.
13572 Since
13574 2.5
13575 SchemaInfoBuiltin (Object)
13577 Additional SchemaInfo members for meta-type 'builtin'.
13578 Members
13580 json-type: JSONType
13581 the JSON type used for this type on the wire.
13582 Since
13584 2.5
13585 JSONType (Enum)
13587 The four primitive and two structured types according to RFC 8259 sec‐
13588 tion 1, plus 'int' (split off 'number'), plus the obvious top type
13589 'value'.
13590 Values
13592 string Not documented
13593 number Not documented
13595 int Not documented
13597 boolean
13599 Not documented
13600 null Not documented
13602 object Not documented
13604 array Not documented
13606 value Not documented
13608 Since
13610 2.5
13611 SchemaInfoEnum (Object)
13613 Additional SchemaInfo members for meta-type 'enum'.
13614 Members
13616 values: array of string
13617 the enumeration type's values, in no particular order.
13618 Values of this type are JSON string on the wire.
13619 Since
13621 2.5
13622 SchemaInfoArray (Object)
13624 Additional SchemaInfo members for meta-type 'array'.
13625 Members
13627 element-type: string
13628 the array type's element type.
13629 Values of this type are JSON array on the wire.
13630 Since
13632 2.5
13633 SchemaInfoObject (Object)
13635 Additional SchemaInfo members for meta-type 'object'.
13636 Members
13638 members: array of SchemaInfoObjectMember
13639 the object type's (non-variant) members, in no particular order.
13640 tag: string (optional)
13642 the name of the member serving as type tag. An element of mem‐
13643 bers with this name must exist.
13644 variants: array of SchemaInfoObjectVariant (optional)
13646 variant members, i.e. additional members that depend on the type
13647 tag's value. Present exactly when tag is present. The variants
13648 are in no particular order, and may even differ from the order
13649 of the values of the enum type of the tag.
13650 Values of this type are JSON object on the wire.
13651 Since
13653 2.5
13654 SchemaInfoObjectMember (Object)
13656 An object member.
13657 Members
13659 name: string
13660 the member's name, as defined in the QAPI schema.
13661 type: string
13663 the name of the member's type.
13664 default: value (optional)
13666 default when used as command parameter. If absent, the parame‐
13667 ter is mandatory. If present, the value must be null. The pa‐
13668 rameter is optional, and behavior when it's missing is not spec‐
13669 ified here. Future extension: if present and non-null, the pa‐
13670 rameter is optional, and defaults to this value.
13671 features: array of string (optional)
13673 names of features associated with the member, in no particular
13674 order. (since 5.0)
13675 Since
13677 2.5
13678 SchemaInfoObjectVariant (Object)
13680 The variant members for a value of the type tag.
13681 Members
13683 case: string
13684 a value of the type tag.
13685 type: string
13687 the name of the object type that provides the variant members
13688 when the type tag has value case.
13689 Since
13691 2.5
13692 SchemaInfoAlternate (Object)
13694 Additional SchemaInfo members for meta-type 'alternate'.
13695 Members
13697 members: array of SchemaInfoAlternateMember
13698 the alternate type's members, in no particular order. The mem‐
13699 bers' wire encoding is distinct, see docs/de‐
13700 vel/qapi-code-gen.txt section Alternate types.
13701 On the wire, this can be any of the members.
13702 Since
13704 2.5
13705 SchemaInfoAlternateMember (Object)
13707 An alternate member.
13708 Members
13710 type: string
13711 the name of the member's type.
13712 Since
13714 2.5
13715 SchemaInfoCommand (Object)
13717 Additional SchemaInfo members for meta-type 'command'.
13718 Members
13720 arg-type: string
13721 the name of the object type that provides the command's parame‐
13722 ters.
13723 ret-type: string
13725 the name of the command's result type.
13726 allow-oob: boolean (optional)
13728 whether the command allows out-of-band execution, defaults to
13729 false (Since: 2.12)
13730 TODO
13732 success-response (currently irrelevant, because it's QGA, not QMP)
13733 Since
13735 2.5
13736 SchemaInfoEvent (Object)
13738 Additional SchemaInfo members for meta-type 'event'.
13739 Members
13741 arg-type: string
13742 the name of the object type that provides the event's parame‐
13743 ters.
13744 Since
13746 2.5
13747
13749 ObjectPropertyInfo (Object)
13750 Members
13751 name: string
13752 the name of the property
13753 type: string
13755 the type of the property. This will typically come in one of
13756 four forms:
13757 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
13759 ble'. These types are mapped to the appropriate JSON type.
13760 2. A child type in the form 'child<subtype>' where subtype is a
13762 qdev device type name. Child properties create the composi‐
13763 tion tree.
13764 3. A link type in the form 'link<subtype>' where subtype is a
13766 qdev device type name. Link properties form the device model
13767 graph.
13768 description: string (optional)
13770 if specified, the description of the property.
13771 default-value: value (optional)
13773 the default value, if any (since 5.0)
13774 Since
13776 1.2
13777 qom-list (Command)
13779 This command will list any properties of a object given a path in the
13780 object model.
13781 Arguments
13783 path: string
13784 the path within the object model. See qom-get for a description
13785 of this parameter.
13786 Returns
13788 a list of ObjectPropertyInfo that describe the properties of the ob‐
13789 ject.
13790 Since
13792 1.2
13793 Example
13795 -> { "execute": "qom-list",
13796 "arguments": { "path": "/chardevs" } }
13797 <- { "return": [ { "name": "type", "type": "string" },
13798 { "name": "parallel0", "type": "child<chardev-vc>" },
13799 { "name": "serial0", "type": "child<chardev-vc>" },
13800 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
13801 qom-get (Command)
13803 This command will get a property from a object model path and return
13804 the value.
13805 Arguments
13807 path: string
13808 The path within the object model. There are two forms of sup‐
13809 ported paths--absolute and partial paths.
13810 Absolute paths are derived from the root object and can follow
13812 child<> or link<> properties. Since they can follow link<>
13813 properties, they can be arbitrarily long. Absolute paths look
13814 like absolute filenames and are prefixed with a leading slash.
13815 Partial paths look like relative filenames. They do not begin
13817 with a prefix. The matching rules for partial paths are subtle
13818 but designed to make specifying objects easy. At each level of
13819 the composition tree, the partial path is matched as an absolute
13820 path. The first match is not returned. At least two matches
13821 are searched for. A successful result is only returned if only
13822 one match is found. If more than one match is found, a flag is
13823 return to indicate that the match was ambiguous.
13824 property: string
13826 The property name to read
13827 Returns
13829 The property value. The type depends on the property type. child<> and
13830 link<> properties are returned as #str pathnames. All integer property
13831 types (u8, u16, etc) are returned as #int.
13832 Since
13834 1.2
13835 Example
13837 1. Use absolute path
13838 -> { "execute": "qom-get",
13840 "arguments": { "path": "/machine/unattached/device[0]",
13841 "property": "hotplugged" } }
13842 <- { "return": false }
13843 2. Use partial path
13845 -> { "execute": "qom-get",
13847 "arguments": { "path": "unattached/sysbus",
13848 "property": "type" } }
13849 <- { "return": "System" }
13850 qom-set (Command)
13852 This command will set a property from a object model path.
13853 Arguments
13855 path: string
13856 see qom-get for a description of this parameter
13857 property: string
13859 the property name to set
13860 value: value
13862 a value who's type is appropriate for the property type. See
13863 qom-get for a description of type mapping.
13864 Since
13866 1.2
13867 Example
13869 -> { "execute": "qom-set",
13870 "arguments": { "path": "/machine",
13871 "property": "graphics",
13872 "value": false } }
13873 <- { "return": {} }
13874 ObjectTypeInfo (Object)
13876 This structure describes a search result from qom-list-types
13877 Members
13879 name: string
13880 the type name found in the search
13881 abstract: boolean (optional)
13883 the type is abstract and can't be directly instantiated. Omit‐
13884 ted if false. (since 2.10)
13885 parent: string (optional)
13887 Name of parent type, if any (since 2.10)
13888 Since
13890 1.1
13891 qom-list-types (Command)
13893 This command will return a list of types given search parameters
13894 Arguments
13896 implements: string (optional)
13897 if specified, only return types that implement this type name
13898 abstract: boolean (optional)
13900 if true, include abstract types in the results
13901 Returns
13903 a list of ObjectTypeInfo or an empty list if no results are found
13904 Since
13906 1.1
13907 qom-list-properties (Command)
13909 List properties associated with a QOM object.
13910 Arguments
13912 typename: string
13913 the type name of an object
13914 Note
13916 objects can create properties at runtime, for example to describe links
13917 between different devices and/or objects. These properties are not in‐
13918 cluded in the output of this command.
13919 Returns
13921 a list of ObjectPropertyInfo describing object properties
13922 Since
13924 2.12
13925 object-add (Command)
13927 Create a QOM object.
13928 Arguments
13930 qom-type: string
13931 the class name for the object to be created
13932 id: string
13934 the name of the new object
13935 props: value (optional)
13937 a dictionary of properties to be passed to the backend. Depre‐
13938 cated since 5.0, specify the properties on the top level in‐
13939 stead. It is an error to specify the same option both on the top
13940 level and in props.
13941 Additional arguments depend on qom-type and are passed to the backend
13942 unchanged.
13943 Returns
13945 Nothing on success Error if qom-type is not a valid class name
13946 Since
13948 2.0
13949 Example
13951 -> { "execute": "object-add",
13952 "arguments": { "qom-type": "rng-random", "id": "rng1",
13953 "filename": "/dev/hwrng" } }
13954 <- { "return": {} }
13955 object-del (Command)
13957 Remove a QOM object.
13958 Arguments
13960 id: string
13961 the name of the QOM object to remove
13962 Returns
13964 Nothing on success Error if id is not a valid id for a QOM object
13965 Since
13967 2.0
13968 Example
13970 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
13971 <- { "return": {} }
13972
13974 device-list-properties (Command)
13975 List properties associated with a device.
13976 Arguments
13978 typename: string
13979 the type name of a device
13980 Returns
13982 a list of ObjectPropertyInfo describing a devices properties
13983 Note
13985 objects can create properties at runtime, for example to describe links
13986 between different devices and/or objects. These properties are not in‐
13987 cluded in the output of this command.
13988 Since
13990 1.2
13991 device_add (Command)
13993 Arguments
13994 driver: string
13995 the name of the new device's driver
13996 bus: string (optional)
13998 the device's parent bus (device tree path)
13999 id: string (optional)
14001 the device's ID, must be unique
14002 Additional arguments depend on the type.
14003 Add a device.
14005 Notes
14007 1. For detailed information about this command, please refer to the
14008 'docs/qdev-device-use.txt' file.
14009 2. It's possible to list device properties by running QEMU with the
14011 "-device DEVICE,help" command-line argument, where DEVICE is the de‐
14012 vice's name
14013 Example
14015 -> { "execute": "device_add",
14016 "arguments": { "driver": "e1000", "id": "net1",
14017 "bus": "pci.0",
14018 "mac": "52:54:00:12:34:56" } }
14019 <- { "return": {} }
14020 TODO
14022 This command effectively bypasses QAPI completely due to its "addi‐
14023 tional arguments" business. It shouldn't have been added to the schema
14024 in this form. It should be qapified properly, or replaced by a prop‐
14025 erly qapified command.
14026 Since
14028 0.13
14029 device_del (Command)
14031 Remove a device from a guest
14032 Arguments
14034 id: string
14035 the device's ID or QOM path
14036 Returns
14038 Nothing on success If id is not a valid device, DeviceNotFound
14039 Notes
14041 When this command completes, the device may not be removed from the
14042 guest. Hot removal is an operation that requires guest cooperation.
14043 This command merely requests that the guest begin the hot removal
14044 process. Completion of the device removal process is signaled with a
14045 DEVICE_DELETED event. Guest reset will automatically complete removal
14046 for all devices.
14047 Since
14049 0.14.0
14050 Example
14052 -> { "execute": "device_del",
14053 "arguments": { "id": "net1" } }
14054 <- { "return": {} }
14055 -> { "execute": "device_del",
14057 "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
14058 <- { "return": {} }
14059 DEVICE_DELETED (Event)
14061 Emitted whenever the device removal completion is acknowledged by the
14062 guest. At this point, it's safe to reuse the specified device ID. De‐
14063 vice removal can be initiated by the guest or by HMP/QMP commands.
14064 Arguments
14066 device: string (optional)
14067 device name
14068 path: string
14070 device path
14071 Since
14073 1.5
14074 Example
14076 <- { "event": "DEVICE_DELETED",
14077 "data": { "device": "virtio-net-pci-0",
14078 "path": "/machine/peripheral/virtio-net-pci-0" },
14079 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
14080
14082 SysEmuTarget (Enum)
14083 The comprehensive enumeration of QEMU system emulation ("softmmu") tar‐
14084 gets. Run "./configure --help" in the project root directory, and look
14085 for the *-softmmu targets near the "--target-list" option. The individ‐
14086 ual target constants are not documented here, for the time being.
14087 Values
14089 rx since 5.0
14090 avr since 5.1
14092 aarch64
14094 Not documented
14095 alpha Not documented
14097 arm Not documented
14099 cris Not documented
14101 hppa Not documented
14103 i386 Not documented
14105 lm32 Not documented
14107 m68k Not documented
14109 microblaze
14111 Not documented
14112 microblazeel
14114 Not documented
14115 mips Not documented
14117 mips64 Not documented
14119 mips64el
14121 Not documented
14122 mipsel Not documented
14124 moxie Not documented
14126 nios2 Not documented
14128 or1k Not documented
14130 ppc Not documented
14132 ppc64 Not documented
14134 riscv32
14136 Not documented
14137 riscv64
14139 Not documented
14140 s390x Not documented
14142 sh4 Not documented
14144 sh4eb Not documented
14146 sparc Not documented
14148 sparc64
14150 Not documented
14151 tricore
14153 Not documented
14154 unicore32
14156 Not documented
14157 x86_64 Not documented
14159 xtensa Not documented
14161 xtensaeb
14163 Not documented
14164 Notes
14166 The resulting QMP strings can be appended to the "qemu-system-" prefix
14167 to produce the corresponding QEMU executable name. This is true even
14168 for "qemu-system-x86_64".
14169 Since
14171 3.0
14172 CpuInfoArch (Enum)
14174 An enumeration of cpu types that enable additional information during
14175 query-cpus and query-cpus-fast.
14176 Values
14178 s390 since 2.12
14179 riscv since 2.12
14181 x86 Not documented
14183 sparc Not documented
14185 ppc Not documented
14187 mips Not documented
14189 tricore
14191 Not documented
14192 other Not documented
14194 Since
14196 2.6
14197 CpuInfo (Object)
14199 Information about a virtual CPU
14200 Members
14202 CPU: int
14203 the index of the virtual CPU
14204 current: boolean
14206 this only exists for backwards compatibility and should be ig‐
14207 nored
14208 halted: boolean
14210 true if the virtual CPU is in the halt state. Halt usually
14211 refers to a processor specific low power mode.
14212 qom_path: string
14214 path to the CPU object in the QOM tree (since 2.4)
14215 thread_id: int
14217 ID of the underlying host thread
14218 props: CpuInstanceProperties (optional)
14220 properties describing to which node/socket/core/thread virtual
14221 CPU belongs to, provided if supported by board (since 2.10)
14222 arch: CpuInfoArch
14224 architecture of the cpu, which determines which additional
14225 fields will be listed (since 2.6)
14226 The members of CpuInfoX86 when arch is "x86"
14228 The members of CpuInfoSPARC when arch is "sparc"
14230 The members of CpuInfoPPC when arch is "ppc"
14232 The members of CpuInfoMIPS when arch is "mips"
14234 The members of CpuInfoTricore when arch is "tricore"
14236 The members of CpuInfoS390 when arch is "s390"
14238 The members of CpuInfoRISCV when arch is "riscv"
14240 Since
14242 0.14.0
14243 Notes
14245 halted is a transient state that changes frequently. By the time the
14246 data is sent to the client, the guest may no longer be halted.
14247 CpuInfoX86 (Object)
14249 Additional information about a virtual i386 or x86_64 CPU
14250 Members
14252 pc: int
14253 the 64-bit instruction pointer
14254 Since
14256 2.6
14257 CpuInfoSPARC (Object)
14259 Additional information about a virtual SPARC CPU
14260 Members
14262 pc: int
14263 the PC component of the instruction pointer
14264 npc: int
14266 the NPC component of the instruction pointer
14267 Since
14269 2.6
14270 CpuInfoPPC (Object)
14272 Additional information about a virtual PPC CPU
14273 Members
14275 nip: int
14276 the instruction pointer
14277 Since
14279 2.6
14280 CpuInfoMIPS (Object)
14282 Additional information about a virtual MIPS CPU
14283 Members
14285 PC: int
14286 the instruction pointer
14287 Since
14289 2.6
14290 CpuInfoTricore (Object)
14292 Additional information about a virtual Tricore CPU
14293 Members
14295 PC: int
14296 the instruction pointer
14297 Since
14299 2.6
14300 CpuInfoRISCV (Object)
14302 Additional information about a virtual RISCV CPU
14303 Members
14305 pc: int
14306 the instruction pointer
14307 Since 2.12
14308 CpuS390State (Enum)
14310 An enumeration of cpu states that can be assumed by a virtual S390 CPU
14311 Values
14313 uninitialized
14314 Not documented
14315 stopped
14317 Not documented
14318 check-stop
14320 Not documented
14321 operating
14323 Not documented
14324 load Not documented
14326 Since
14328 2.12
14329 CpuInfoS390 (Object)
14331 Additional information about a virtual S390 CPU
14332 Members
14334 cpu-state: CpuS390State
14335 the virtual CPU's state
14336 Since
14338 2.12
14339 query-cpus (Command)
14341 Returns a list of information about each virtual CPU.
14342 This command causes vCPU threads to exit to userspace, which causes a
14344 small interruption to guest CPU execution. This will have a negative
14345 impact on realtime guests and other latency sensitive guest workloads.
14346 Features
14348 deprecated
14349 This command is deprecated, because it interferes with the
14350 guest. Use 'query-cpus-fast' instead to avoid the vCPU inter‐
14351 ruption.
14352 Returns
14354 a list of CpuInfo for each virtual CPU
14355 Since
14357 0.14.0
14358 Example
14360 -> { "execute": "query-cpus" }
14361 <- { "return": [
14362 {
14363 "CPU":0,
14364 "current":true,
14365 "halted":false,
14366 "qom_path":"/machine/unattached/device[0]",
14367 "arch":"x86",
14368 "pc":3227107138,
14369 "thread_id":3134
14370 },
14371 {
14372 "CPU":1,
14373 "current":false,
14374 "halted":true,
14375 "qom_path":"/machine/unattached/device[2]",
14376 "arch":"x86",
14377 "pc":7108165,
14378 "thread_id":3135
14379 }
14380 ]
14381 }
14382 CpuInfoFast (Object)
14384 Information about a virtual CPU
14385 Members
14387 cpu-index: int
14388 index of the virtual CPU
14389 qom-path: string
14391 path to the CPU object in the QOM tree
14392 thread-id: int
14394 ID of the underlying host thread
14395 props: CpuInstanceProperties (optional)
14397 properties describing to which node/socket/core/thread virtual
14398 CPU belongs to, provided if supported by board
14399 arch: CpuInfoArch
14401 base architecture of the cpu
14402 target: SysEmuTarget
14404 the QEMU system emulation target, which determines which addi‐
14405 tional fields will be listed (since 3.0)
14406 The members of CpuInfoS390 when target is "s390x"
14408 Features
14410 deprecated
14411 Member arch is deprecated. Use target instead.
14412 Since
14414 2.12
14415 query-cpus-fast (Command)
14417 Returns information about all virtual CPUs. This command does not incur
14418 a performance penalty and should be used in production instead of
14419 query-cpus.
14420 Returns
14422 list of CpuInfoFast
14423 Since
14425 2.12
14426 Example
14428 -> { "execute": "query-cpus-fast" }
14429 <- { "return": [
14430 {
14431 "thread-id": 25627,
14432 "props": {
14433 "core-id": 0,
14434 "thread-id": 0,
14435 "socket-id": 0
14436 },
14437 "qom-path": "/machine/unattached/device[0]",
14438 "arch":"x86",
14439 "target":"x86_64",
14440 "cpu-index": 0
14441 },
14442 {
14443 "thread-id": 25628,
14444 "props": {
14445 "core-id": 0,
14446 "thread-id": 0,
14447 "socket-id": 1
14448 },
14449 "qom-path": "/machine/unattached/device[2]",
14450 "arch":"x86",
14451 "target":"x86_64",
14452 "cpu-index": 1
14453 }
14454 ]
14455 }
14456 MachineInfo (Object)
14458 Information describing a machine.
14459 Members
14461 name: string
14462 the name of the machine
14463 alias: string (optional)
14465 an alias for the machine name
14466 is-default: boolean (optional)
14468 whether the machine is default
14469 cpu-max: int
14471 maximum number of CPUs supported by the machine type (since
14472 1.5.0)
14473 hotpluggable-cpus: boolean
14475 cpu hotplug via -device is supported (since 2.7.0)
14476 numa-mem-supported: boolean
14478 true if '-numa node,mem' option is supported by the machine type
14479 and false otherwise (since 4.1)
14480 deprecated: boolean
14482 if true, the machine type is deprecated and may be removed in
14483 future versions of QEMU according to the QEMU deprecation policy
14484 (since 4.1.0)
14485 default-cpu-type: string (optional)
14487 default CPU model typename if none is requested via the -cpu ar‐
14488 gument. (since 4.2)
14489 default-ram-id: string (optional)
14491 the default ID of initial RAM memory backend (since 5.2)
14492 Since
14494 1.2.0
14495 query-machines (Command)
14497 Return a list of supported machines
14498 Returns
14500 a list of MachineInfo
14501 Since
14503 1.2.0
14504 CurrentMachineParams (Object)
14506 Information describing the running machine parameters.
14507 Members
14509 wakeup-suspend-support: boolean
14510 true if the machine supports wake up from suspend
14511 Since
14513 4.0
14514 query-current-machine (Command)
14516 Return information on the current virtual machine.
14517 Returns
14519 CurrentMachineParams
14520 Since
14522 4.0
14523 TargetInfo (Object)
14525 Information describing the QEMU target.
14526 Members
14528 arch: SysEmuTarget
14529 the target architecture
14530 Since
14532 1.2.0
14533 query-target (Command)
14535 Return information about the target for this QEMU
14536 Returns
14538 TargetInfo
14539 Since
14541 1.2.0
14542 UuidInfo (Object)
14544 Guest UUID information (Universally Unique Identifier).
14545 Members
14547 UUID: string
14548 the UUID of the guest
14549 Since
14551 0.14.0
14552 Notes
14554 If no UUID was specified for the guest, a null UUID is returned.
14555 query-uuid (Command)
14557 Query the guest UUID information.
14558 Returns
14560 The UuidInfo for the guest
14561 Since
14563 0.14.0
14564 Example
14566 -> { "execute": "query-uuid" }
14567 <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
14568 GuidInfo (Object)
14570 GUID information.
14571 Members
14573 guid: string
14574 the globally unique identifier
14575 Since
14577 2.9
14578 query-vm-generation-id (Command)
14580 Show Virtual Machine Generation ID
14581 Since
14583 2.9
14584 system_reset (Command)
14586 Performs a hard reset of a guest.
14587 Since
14589 0.14.0
14590 Example
14592 -> { "execute": "system_reset" }
14593 <- { "return": {} }
14594 system_powerdown (Command)
14596 Requests that a guest perform a powerdown operation.
14597 Since
14599 0.14.0
14600 Notes
14602 A guest may or may not respond to this command. This command returning
14603 does not indicate that a guest has accepted the request or that it has
14604 shut down. Many guests will respond to this command by prompting the
14605 user in some way.
14606 Example
14608 -> { "execute": "system_powerdown" }
14609 <- { "return": {} }
14610 system_wakeup (Command)
14612 Wake up guest from suspend. If the guest has wake-up from suspend sup‐
14613 port enabled (wakeup-suspend-support flag from query-current-machine),
14614 wake-up guest from suspend if the guest is in SUSPENDED state. Return
14615 an error otherwise.
14616 Since
14618 1.1
14619 Returns
14621 nothing.
14622 Note
14624 prior to 4.0, this command does nothing in case the guest isn't sus‐
14625 pended.
14626 Example
14628 -> { "execute": "system_wakeup" }
14629 <- { "return": {} }
14630 LostTickPolicy (Enum)
14632 Policy for handling lost ticks in timer devices. Ticks end up getting
14633 lost when, for example, the guest is paused.
14634 Values
14636 discard
14637 throw away the missed ticks and continue with future injection
14638 normally. The guest OS will see the timer jump ahead by a po‐
14639 tentially quite significant amount all at once, as if the inter‐
14640 vening chunk of time had simply not existed; needless to say,
14641 such a sudden jump can easily confuse a guest OS which is not
14642 specifically prepared to deal with it. Assuming the guest OS
14643 can deal correctly with the time jump, the time in the guest and
14644 in the host should now match.
14645 delay continue to deliver ticks at the normal rate. The guest OS will
14647 not notice anything is amiss, as from its point of view time
14648 will have continued to flow normally. The time in the guest
14649 should now be behind the time in the host by exactly the amount
14650 of time during which ticks have been missed.
14651 slew deliver ticks at a higher rate to catch up with the missed
14653 ticks. The guest OS will not notice anything is amiss, as from
14654 its point of view time will have continued to flow normally.
14655 Once the timer has managed to catch up with all the missing
14656 ticks, the time in the guest and in the host should match.
14657 Since
14659 2.0
14660 inject-nmi (Command)
14662 Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all
14663 CPUs (ppc64). The command fails when the guest doesn't support inject‐
14664 ing.
14665 Returns
14667 If successful, nothing
14668 Since
14670 0.14.0
14671 Note
14673 prior to 2.1, this command was only supported for x86 and s390 VMs
14674 Example
14676 -> { "execute": "inject-nmi" }
14677 <- { "return": {} }
14678 KvmInfo (Object)
14680 Information about support for KVM acceleration
14681 Members
14683 enabled: boolean
14684 true if KVM acceleration is active
14685 present: boolean
14687 true if KVM acceleration is built into this executable
14688 Since
14690 0.14.0
14691 query-kvm (Command)
14693 Returns information about KVM acceleration
14694 Returns
14696 KvmInfo
14697 Since
14699 0.14.0
14700 Example
14702 -> { "execute": "query-kvm" }
14703 <- { "return": { "enabled": true, "present": true } }
14704 NumaOptionsType (Enum)
14706 Values
14707 node NUMA nodes configuration
14708 dist NUMA distance configuration (since 2.10)
14710 cpu property based CPU(s) to node mapping (Since: 2.10)
14712 hmat-lb
14714 memory latency and bandwidth information (Since: 5.0)
14715 hmat-cache
14717 memory side cache information (Since: 5.0)
14718 Since
14720 2.1
14721 NumaOptions (Object)
14723 A discriminated record of NUMA options. (for OptsVisitor)
14724 Members
14726 type: NumaOptionsType
14727 Not documented
14728 The members of NumaNodeOptions when type is "node"
14730 The members of NumaDistOptions when type is "dist"
14732 The members of NumaCpuOptions when type is "cpu"
14734 The members of NumaHmatLBOptions when type is "hmat-lb"
14736 The members of NumaHmatCacheOptions when type is "hmat-cache"
14738 Since
14740 2.1
14741 NumaNodeOptions (Object)
14743 Create a guest NUMA node. (for OptsVisitor)
14744 Members
14746 nodeid: int (optional)
14747 NUMA node ID (increase by 1 from 0 if omitted)
14748 cpus: array of int (optional)
14750 VCPUs belonging to this node (assign VCPUS round-robin
14752 if omitted)
14753 mem: int (optional)
14755 memory size of this node; mutually exclusive with memdev.
14756 Equally divide total memory among nodes if both mem and memdev
14757 are omitted.
14758 memdev: string (optional)
14760 memory backend object. If specified for one node, it must be
14761 specified for all nodes.
14762 initiator: int (optional)
14764 defined in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points to the
14765 nodeid which has the memory controller responsible for this NUMA
14766 node. This field provides additional information as to the ini‐
14767 tiator node that is closest (as in directly attached) to this
14768 node, and therefore has the best performance (since 5.0)
14769 Since
14771 2.1
14772 NumaDistOptions (Object)
14774 Set the distance between 2 NUMA nodes.
14775 Members
14777 src: int
14778 source NUMA node.
14779 dst: int
14781 destination NUMA node.
14782 val: int
14784 NUMA distance from source node to destination node. When a node
14785 is unreachable from another node, set the distance between them
14786 to 255.
14787 Since
14789 2.10
14790 X86CPURegister32 (Enum)
14792 A X86 32-bit register
14793 Values
14795 EAX Not documented
14796 EBX Not documented
14798 ECX Not documented
14800 EDX Not documented
14802 ESP Not documented
14804 EBP Not documented
14806 ESI Not documented
14808 EDI Not documented
14810 Since
14812 1.5
14813 X86CPUFeatureWordInfo (Object)
14815 Information about a X86 CPU feature word
14816 Members
14818 cpuid-input-eax: int
14819 Input EAX value for CPUID instruction for that feature word
14820 cpuid-input-ecx: int (optional)
14822 Input ECX value for CPUID instruction for that feature word
14823 cpuid-register: X86CPURegister32
14825 Output register containing the feature bits
14826 features: int
14828 value of output register, containing the feature bits
14829 Since
14831 1.5
14832 DummyForceArrays (Object)
14834 Not used by QMP; hack to let us use X86CPUFeatureWordInfoList inter‐
14835 nally
14836 Members
14838 unused: array of X86CPUFeatureWordInfo
14839 Not documented
14840 Since
14842 2.5
14843 NumaCpuOptions (Object)
14845 Option "-numa cpu" overrides default cpu to node mapping. It accepts
14846 the same set of cpu properties as returned by query-hotplug‐
14847 gable-cpus[].props, where node-id could be used to override default
14848 node mapping.
14849 Members
14851 The members of CpuInstanceProperties
14852 Since
14854 2.10
14855 HmatLBMemoryHierarchy (Enum)
14857 The memory hierarchy in the System Locality Latency and Bandwidth In‐
14858 formation Structure of HMAT (Heterogeneous Memory Attribute Table)
14859 For more information about HmatLBMemoryHierarchy, see chapter 5.2.27.4:
14861 Table 5-146: Field "Flags" of ACPI 6.3 spec.
14862 Values
14864 memory the structure represents the memory performance
14865 first-level
14867 first level of memory side cache
14868 second-level
14870 second level of memory side cache
14871 third-level
14873 third level of memory side cache
14874 Since
14876 5.0
14877 HmatLBDataType (Enum)
14879 Data type in the System Locality Latency and Bandwidth Information
14880 Structure of HMAT (Heterogeneous Memory Attribute Table)
14881 For more information about HmatLBDataType, see chapter 5.2.27.4: Table
14883 5-146: Field "Data Type" of ACPI 6.3 spec.
14884 Values
14886 access-latency
14887 access latency (nanoseconds)
14888 read-latency
14890 read latency (nanoseconds)
14891 write-latency
14893 write latency (nanoseconds)
14894 access-bandwidth
14896 access bandwidth (Bytes per second)
14897 read-bandwidth
14899 read bandwidth (Bytes per second)
14900 write-bandwidth
14902 write bandwidth (Bytes per second)
14903 Since
14905 5.0
14906 NumaHmatLBOptions (Object)
14908 Set the system locality latency and bandwidth information between Ini‐
14909 tiator and Target proximity Domains.
14910 For more information about NumaHmatLBOptions, see chapter 5.2.27.4: Ta‐
14912 ble 5-146 of ACPI 6.3 spec.
14913 Members
14915 initiator: int
14916 the Initiator Proximity Domain.
14917 target: int
14919 the Target Proximity Domain.
14920 hierarchy: HmatLBMemoryHierarchy
14922 the Memory Hierarchy. Indicates the performance of memory or
14923 side cache.
14924 data-type: HmatLBDataType
14926 presents the type of data, access/read/write latency or hit la‐
14927 tency.
14928 latency: int (optional)
14930 the value of latency from initiator to target proximity domain,
14931 the latency unit is "ns(nanosecond)".
14932 bandwidth: int (optional)
14934 the value of bandwidth between initiator and target proximity
14935 domain, the bandwidth unit is "Bytes per second".
14936 Since
14938 5.0
14939 HmatCacheAssociativity (Enum)
14941 Cache associativity in the Memory Side Cache Information Structure of
14942 HMAT
14943 For more information of HmatCacheAssociativity, see chapter 5.2.27.5:
14945 Table 5-147 of ACPI 6.3 spec.
14946 Values
14948 none
14949 None (no memory side cache in this proximity domain,
14951 or cache associativity unknown)
14952 direct Direct Mapped
14954 complex
14956 Complex Cache Indexing (implementation specific)
14957 Since
14959 5.0
14960 HmatCacheWritePolicy (Enum)
14962 Cache write policy in the Memory Side Cache Information Structure of
14963 HMAT
14964 For more information of HmatCacheWritePolicy, see chapter 5.2.27.5: Ta‐
14966 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
14967 Values
14969 none None (no memory side cache in this proximity domain, or cache
14970 write policy unknown)
14971 write-back
14973 Write Back (WB)
14974 write-through
14976 Write Through (WT)
14977 Since
14979 5.0
14980 NumaHmatCacheOptions (Object)
14982 Set the memory side cache information for a given memory domain.
14983 For more information of NumaHmatCacheOptions, see chapter 5.2.27.5: Ta‐
14985 ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
14986 Members
14988 node-id: int
14989 the memory proximity domain to which the memory belongs.
14990 size: int
14992 the size of memory side cache in bytes.
14993 level: int
14995 the cache level described in this structure.
14996 associativity: HmatCacheAssociativity
14998 the cache associativity, none/direct-mapped/complex(complex
14999 cache indexing).
15000 policy: HmatCacheWritePolicy
15002 the write policy, none/write-back/write-through.
15003 line: int
15005 the cache Line size in bytes.
15006 Since
15008 5.0
15009 HostMemPolicy (Enum)
15011 Host memory policy types
15012 Values
15014 default
15015 restore default policy, remove any nondefault policy
15016 preferred
15018 set the preferred host nodes for allocation
15019 bind a strict policy that restricts memory allocation to the host
15021 nodes specified
15022 interleave
15024 memory allocations are interleaved across the set of host nodes
15025 specified
15026 Since
15028 2.1
15029 memsave (Command)
15031 Save a portion of guest memory to a file.
15032 Arguments
15034 val: int
15035 the virtual address of the guest to start from
15036 size: int
15038 the size of memory region to save
15039 filename: string
15041 the file to save the memory to as binary data
15042 cpu-index: int (optional)
15044 the index of the virtual CPU to use for translating the virtual
15045 address (defaults to CPU 0)
15046 Returns
15048 Nothing on success
15049 Since
15051 0.14.0
15052 Notes
15054 Errors were not reliably returned until 1.1
15055 Example
15057 -> { "execute": "memsave",
15058 "arguments": { "val": 10,
15059 "size": 100,
15060 "filename": "/tmp/virtual-mem-dump" } }
15061 <- { "return": {} }
15062 pmemsave (Command)
15064 Save a portion of guest physical memory to a file.
15065 Arguments
15067 val: int
15068 the physical address of the guest to start from
15069 size: int
15071 the size of memory region to save
15072 filename: string
15074 the file to save the memory to as binary data
15075 Returns
15077 Nothing on success
15078 Since
15080 0.14.0
15081 Notes
15083 Errors were not reliably returned until 1.1
15084 Example
15086 -> { "execute": "pmemsave",
15087 "arguments": { "val": 10,
15088 "size": 100,
15089 "filename": "/tmp/physical-mem-dump" } }
15090 <- { "return": {} }
15091 Memdev (Object)
15093 Information about memory backend
15094 Members
15096 id: string (optional)
15097 backend's ID if backend has 'id' property (since 2.9)
15098 size: int
15100 memory backend size
15101 merge: boolean
15103 enables or disables memory merge support
15104 dump: boolean
15106 includes memory backend's memory in a core dump or not
15107 prealloc: boolean
15109 enables or disables memory preallocation
15110 host-nodes: array of int
15112 host nodes for its memory policy
15113 policy: HostMemPolicy
15115 memory policy of memory backend
15116 Since
15118 2.1
15119 query-memdev (Command)
15121 Returns information for all memory backends.
15122 Returns
15124 a list of Memdev.
15125 Since
15127 2.1
15128 Example
15130 -> { "execute": "query-memdev" }
15131 <- { "return": [
15132 {
15133 "id": "mem1",
15134 "size": 536870912,
15135 "merge": false,
15136 "dump": true,
15137 "prealloc": false,
15138 "host-nodes": [0, 1],
15139 "policy": "bind"
15140 },
15141 {
15142 "size": 536870912,
15143 "merge": false,
15144 "dump": true,
15145 "prealloc": true,
15146 "host-nodes": [2, 3],
15147 "policy": "preferred"
15148 }
15149 ]
15150 }
15151 CpuInstanceProperties (Object)
15153 List of properties to be used for hotplugging a CPU instance, it should
15154 be passed by management with device_add command when a CPU is being
15155 hotplugged.
15156 Members
15158 node-id: int (optional)
15159 NUMA node ID the CPU belongs to
15160 socket-id: int (optional)
15162 socket number within node/board the CPU belongs to
15163 die-id: int (optional)
15165 die number within node/board the CPU belongs to (Since 4.1)
15166 core-id: int (optional)
15168 core number within die the CPU belongs to
15169 thread-id: int (optional)
15171 thread number within core the CPU belongs to
15172 Note
15174 currently there are 5 properties that could be present but management
15175 should be prepared to pass through other properties with device_add
15176 command to allow for future interface extension. This also requires the
15177 filed names to be kept in sync with the properties passed to -de‐
15178 vice/device_add.
15179 Since
15181 2.7
15182 HotpluggableCPU (Object)
15184 Members
15185 type: string
15186 CPU object type for usage with device_add command
15187 props: CpuInstanceProperties
15189 list of properties to be used for hotplugging CPU
15190 vcpus-count: int
15192 number of logical VCPU threads HotpluggableCPU provides
15193 qom-path: string (optional)
15195 link to existing CPU object if CPU is present or omitted if CPU
15196 is not present.
15197 Since
15199 2.7
15200 query-hotpluggable-cpus (Command)
15202 TODO
15203 Better documentation; currently there is none.
15204 Returns
15206 a list of HotpluggableCPU objects.
15207 Since
15209 2.7
15210 Example
15212 For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
15213 -> { "execute": "query-hotpluggable-cpus" }
15215 <- {"return": [
15216 { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
15217 "vcpus-count": 1 },
15218 { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
15219 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
15220 ]}'
15221 For pc machine type started with -smp 1,maxcpus=2:
15223 -> { "execute": "query-hotpluggable-cpus" }
15225 <- {"return": [
15226 {
15227 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
15228 "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
15229 },
15230 {
15231 "qom-path": "/machine/unattached/device[0]",
15232 "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
15233 "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
15234 }
15235 ]}
15236 For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
15238 (Since: 2.11):
15239 -> { "execute": "query-hotpluggable-cpus" }
15241 <- {"return": [
15242 {
15243 "type": "qemu-s390x-cpu", "vcpus-count": 1,
15244 "props": { "core-id": 1 }
15245 },
15246 {
15247 "qom-path": "/machine/unattached/device[0]",
15248 "type": "qemu-s390x-cpu", "vcpus-count": 1,
15249 "props": { "core-id": 0 }
15250 }
15251 ]}
15252 set-numa-node (Command)
15254 Runtime equivalent of '-numa' CLI option, available at preconfigure
15255 stage to configure numa mapping before initializing machine.
15256 Since 3.0
15258 Arguments
15260 The members of NumaOptions
15261 balloon (Command)
15263 Request the balloon driver to change its balloon size.
15264 Arguments
15266 value: int
15267 the target logical size of the VM in bytes. We can deduce the
15268 size of the balloon using this formula:
15269 logical_vm_size = vm_ram_size - balloon_size
15270 From it we have: balloon_size = vm_ram_size - value
15272 Returns
15274 • Nothing on success
15275 • If the balloon driver is enabled but not functional because the KVM
15277 kernel module cannot support it, KvmMissingCap
15278 • If no balloon device is present, DeviceNotActive
15280 Notes
15282 This command just issues a request to the guest. When it returns, the
15283 balloon size may not have changed. A guest can change the balloon size
15284 independent of this command.
15285 Since
15287 0.14.0
15288 Example
15290 -> { "execute": "balloon", "arguments": { "value": 536870912 } }
15291 <- { "return": {} }
15292 With a 2.5GiB guest this command inflated the ballon to 3GiB.
15294 BalloonInfo (Object)
15296 Information about the guest balloon device.
15297 Members
15299 actual: int
15300 the logical size of the VM in bytes Formula used: logi‐
15301 cal_vm_size = vm_ram_size - balloon_size
15302 Since
15304 0.14.0
15305 query-balloon (Command)
15307 Return information about the balloon device.
15308 Returns
15310 • BalloonInfo on success
15311 • If the balloon driver is enabled but not functional because the KVM
15313 kernel module cannot support it, KvmMissingCap
15314 • If no balloon device is present, DeviceNotActive
15316 Since
15318 0.14.0
15319 Example
15321 -> { "execute": "query-balloon" }
15322 <- { "return": {
15323 "actual": 1073741824,
15324 }
15325 }
15326 BALLOON_CHANGE (Event)
15328 Emitted when the guest changes the actual BALLOON level. This value is
15329 equivalent to the actual field return by the 'query-balloon' command
15330 Arguments
15332 actual: int
15333 the logical size of the VM in bytes Formula used: logi‐
15334 cal_vm_size = vm_ram_size - balloon_size
15335 Note
15337 this event is rate-limited.
15338 Since
15340 1.2
15341 Example
15343 <- { "event": "BALLOON_CHANGE",
15344 "data": { "actual": 944766976 },
15345 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
15346 MemoryInfo (Object)
15348 Actual memory information in bytes.
15349 Members
15351 base-memory: int
15352 size of "base" memory specified with command line option -m.
15353 plugged-memory: int (optional)
15355 size of memory that can be hot-unplugged. This field is omitted
15356 if target doesn't support memory hotplug (i.e. CONFIG_MEM_DEVICE
15357 not defined at build time).
15358 Since
15360 2.11.0
15361 query-memory-size-summary (Command)
15363 Return the amount of initially allocated and present hotpluggable (if
15364 enabled) memory in bytes.
15365 Example
15367 -> { "execute": "query-memory-size-summary" }
15368 <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
15369 Since
15371 2.11.0
15372 PCDIMMDeviceInfo (Object)
15374 PCDIMMDevice state information
15375 Members
15377 id: string (optional)
15378 device's ID
15379 addr: int
15381 physical address, where device is mapped
15382 size: int
15384 size of memory that the device provides
15385 slot: int
15387 slot number at which device is plugged in
15388 node: int
15390 NUMA node number where device is plugged in
15391 memdev: string
15393 memory backend linked with device
15394 hotplugged: boolean
15396 true if device was hotplugged
15397 hotpluggable: boolean
15399 true if device if could be added/removed while machine is run‐
15400 ning
15401 Since
15403 2.1
15404 VirtioPMEMDeviceInfo (Object)
15406 VirtioPMEM state information
15407 Members
15409 id: string (optional)
15410 device's ID
15411 memaddr: int
15413 physical address in memory, where device is mapped
15414 size: int
15416 size of memory that the device provides
15417 memdev: string
15419 memory backend linked with device
15420 Since
15422 4.1
15423 VirtioMEMDeviceInfo (Object)
15425 VirtioMEMDevice state information
15426 Members
15428 id: string (optional)
15429 device's ID
15430 memaddr: int
15432 physical address in memory, where device is mapped
15433 requested-size: int
15435 the user requested size of the device
15436 size: int
15438 the (current) size of memory that the device provides
15439 max-size: int
15441 the maximum size of memory that the device can provide
15442 block-size: int
15444 the block size of memory that the device provides
15445 node: int
15447 NUMA node number where device is assigned to
15448 memdev: string
15450 memory backend linked with the region
15451 Since
15453 5.1
15454 MemoryDeviceInfo (Object)
15456 Union containing information about a memory device
15457 nvdimm is included since 2.12. virtio-pmem is included since 4.1. vir‐
15459 tio-mem is included since 5.1.
15460 Members
15462 type One of dimm, nvdimm, virtio-pmem, virtio-mem
15463 data: PCDIMMDeviceInfo when type is "dimm"
15465 data: PCDIMMDeviceInfo when type is "nvdimm"
15467 data: VirtioPMEMDeviceInfo when type is "virtio-pmem"
15469 data: VirtioMEMDeviceInfo when type is "virtio-mem"
15471 Since
15473 2.1
15474 query-memory-devices (Command)
15476 Lists available memory devices and their state
15477 Since
15479 2.1
15480 Example
15482 -> { "execute": "query-memory-devices" }
15483 <- { "return": [ { "data":
15484 { "addr": 5368709120,
15485 "hotpluggable": true,
15486 "hotplugged": true,
15487 "id": "d1",
15488 "memdev": "/objects/memX",
15489 "node": 0,
15490 "size": 1073741824,
15491 "slot": 0},
15492 "type": "dimm"
15493 } ] }
15494 MEMORY_DEVICE_SIZE_CHANGE (Event)
15496 Emitted when the size of a memory device changes. Only emitted for mem‐
15497 ory devices that can actually change the size (e.g., virtio-mem due to
15498 guest action).
15499 Arguments
15501 id: string (optional)
15502 device's ID
15503 size: int
15505 the new size of memory that the device provides
15506 Note
15508 this event is rate-limited.
15509 Since
15511 5.1
15512 Example
15514 <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
15515 "data": { "id": "vm0", "size": 1073741824},
15516 "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
15517 MEM_UNPLUG_ERROR (Event)
15519 Emitted when memory hot unplug error occurs.
15520 Arguments
15522 device: string
15523 device name
15524 msg: string
15526 Informative message
15527 Since
15529 2.4
15530 Example
15532 <- { "event": "MEM_UNPLUG_ERROR"
15533 "data": { "device": "dimm1",
15534 "msg": "acpi: device unplug for unsupported device"
15535 },
15536 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
15537 CpuModelInfo (Object)
15539 Virtual CPU model.
15540 A CPU model consists of the name of a CPU definition, to which delta
15542 changes are applied (e.g. features added/removed). Most magic values
15543 that an architecture might require should be hidden behind the name.
15544 However, if required, architectures can expose relevant properties.
15545 Members
15547 name: string
15548 the name of the CPU definition the model is based on
15549 props: value (optional)
15551 a dictionary of QOM properties to be applied
15552 Since
15554 2.8.0
15555 CpuModelExpansionType (Enum)
15557 An enumeration of CPU model expansion types.
15558 Values
15560 static Expand to a static CPU model, a combination of a static base
15561 model name and property delta changes. As the static base model
15562 will never change, the expanded CPU model will be the same, in‐
15563 dependent of QEMU version, machine type, machine options, and
15564 accelerator options. Therefore, the resulting model can be used
15565 by tooling without having to specify a compatibility machine -
15566 e.g. when displaying the "host" model. The static CPU models are
15567 migration-safe.
15568 full Expand all properties. The produced model is not guaranteed to
15570 be migration-safe, but allows tooling to get an insight and work
15571 with model details.
15572 Note
15574 When a non-migration-safe CPU model is expanded in static mode, some
15575 features enabled by the CPU model may be omitted, because they can't be
15576 implemented by a static CPU model definition (e.g. cache info
15577 passthrough and PMU passthrough in x86). If you need an accurate repre‐
15578 sentation of the features enabled by a non-migration-safe CPU model,
15579 use full. If you need a static representation that will keep ABI com‐
15580 patibility even when changing QEMU version or machine-type, use static
15581 (but keep in mind that some features may be omitted).
15582 Since
15584 2.8.0
15585 CpuModelCompareResult (Enum)
15587 An enumeration of CPU model comparison results. The result is usually
15588 calculated using e.g. CPU features or CPU generations.
15589 Values
15591 incompatible
15592 If model A is incompatible to model B, model A is not guaranteed
15593 to run where model B runs and the other way around.
15594 identical
15596 If model A is identical to model B, model A is guaranteed to run
15597 where model B runs and the other way around.
15598 superset
15600 If model A is a superset of model B, model B is guaranteed to
15601 run where model A runs. There are no guarantees about the other
15602 way.
15603 subset If model A is a subset of model B, model A is guaranteed to run
15605 where model B runs. There are no guarantees about the other way.
15606 Since
15608 2.8.0
15609 CpuModelBaselineInfo (Object)
15611 The result of a CPU model baseline.
15612 Members
15614 model: CpuModelInfo
15615 the baselined CpuModelInfo.
15616 Since
15618 2.8.0
15619 If
15621 defined(TARGET_S390X).SS CpuModelCompareInfo (Object)
15622 The result of a CPU model comparison.
15624 Members
15626 result: CpuModelCompareResult
15627 The result of the compare operation.
15628 responsible-properties: array of string
15630 List of properties that led to the comparison result not being
15631 identical.
15632 responsible-properties is a list of QOM property names that led to both
15633 CPUs not being detected as identical. For identical models, this list
15634 is empty. If a QOM property is read-only, that means there's no known
15635 way to make the CPU models identical. If the special property name
15636 "type" is included, the models are by definition not identical and can‐
15637 not be made identical.
15638 Since
15640 2.8.0
15641 If
15643 defined(TARGET_S390X).SS query-cpu-model-comparison (Command)
15644 Compares two CPU models, returning how they compare in a specific con‐
15646 figuration. The results indicates how both models compare regarding
15647 runnability. This result can be used by tooling to make decisions if a
15648 certain CPU model will run in a certain configuration or if a compati‐
15649 ble CPU model has to be created by baselining.
15650 Usually, a CPU model is compared against the maximum possible CPU model
15652 of a certain configuration (e.g. the "host" model for KVM). If that CPU
15653 model is identical or a subset, it will run in that configuration.
15654 The result returned by this command may be affected by:
15656 • QEMU version: CPU models may look different depending on the QEMU
15658 version. (Except for CPU models reported as "static" in
15659 query-cpu-definitions.)
15660 • machine-type: CPU model may look different depending on the ma‐
15662 chine-type. (Except for CPU models reported as "static" in
15663 query-cpu-definitions.)
15664 • machine options (including accelerator): in some architectures, CPU
15666 models may look different depending on machine and accelerator op‐
15667 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
15668 nitions.)
15669 • "-cpu" arguments and global properties: arguments to the -cpu option
15671 and global properties may affect expansion of CPU models. Using
15672 query-cpu-model-expansion while using these is not advised.
15673 Some architectures may not support comparing CPU models. s390x supports
15675 comparing CPU models.
15676 Arguments
15678 modela: CpuModelInfo
15679 Not documented
15680 modelb: CpuModelInfo
15682 Not documented
15683 Returns
15685 a CpuModelBaselineInfo. Returns an error if comparing CPU models is not
15686 supported, if a model cannot be used, if a model contains an unknown
15687 cpu definition name, unknown properties or properties with wrong types.
15688 Note
15690 this command isn't specific to s390x, but is only implemented on this
15691 architecture currently.
15692 Since
15694 2.8.0
15695 If
15697 defined(TARGET_S390X).SS query-cpu-model-baseline (Command)
15698 Baseline two CPU models, creating a compatible third model. The created
15700 model will always be a static, migration-safe CPU model (see "static"
15701 CPU model expansion for details).
15702 This interface can be used by tooling to create a compatible CPU model
15704 out two CPU models. The created CPU model will be identical to or a
15705 subset of both CPU models when comparing them. Therefore, the created
15706 CPU model is guaranteed to run where the given CPU models run.
15707 The result returned by this command may be affected by:
15709 • QEMU version: CPU models may look different depending on the QEMU
15711 version. (Except for CPU models reported as "static" in
15712 query-cpu-definitions.)
15713 • machine-type: CPU model may look different depending on the ma‐
15715 chine-type. (Except for CPU models reported as "static" in
15716 query-cpu-definitions.)
15717 • machine options (including accelerator): in some architectures, CPU
15719 models may look different depending on machine and accelerator op‐
15720 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
15721 nitions.)
15722 • "-cpu" arguments and global properties: arguments to the -cpu option
15724 and global properties may affect expansion of CPU models. Using
15725 query-cpu-model-expansion while using these is not advised.
15726 Some architectures may not support baselining CPU models. s390x sup‐
15728 ports baselining CPU models.
15729 Arguments
15731 modela: CpuModelInfo
15732 Not documented
15733 modelb: CpuModelInfo
15735 Not documented
15736 Returns
15738 a CpuModelBaselineInfo. Returns an error if baselining CPU models is
15739 not supported, if a model cannot be used, if a model contains an un‐
15740 known cpu definition name, unknown properties or properties with wrong
15741 types.
15742 Note
15744 this command isn't specific to s390x, but is only implemented on this
15745 architecture currently.
15746 Since
15748 2.8.0
15749 If
15751 defined(TARGET_S390X).SS CpuModelExpansionInfo (Object)
15752 The result of a cpu model expansion.
15754 Members
15756 model: CpuModelInfo
15757 the expanded CpuModelInfo.
15758 Since
15760 2.8.0
15761 If
15763 defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM).SS
15764 query-cpu-model-expansion (Command)
15765 Expands a given CPU model (or a combination of CPU model + additional
15767 options) to different granularities, allowing tooling to get an under‐
15768 standing what a specific CPU model looks like in QEMU under a certain
15769 configuration.
15770 This interface can be used to query the "host" CPU model.
15772 The data returned by this command may be affected by:
15774 • QEMU version: CPU models may look different depending on the QEMU
15776 version. (Except for CPU models reported as "static" in
15777 query-cpu-definitions.)
15778 • machine-type: CPU model may look different depending on the ma‐
15780 chine-type. (Except for CPU models reported as "static" in
15781 query-cpu-definitions.)
15782 • machine options (including accelerator): in some architectures, CPU
15784 models may look different depending on machine and accelerator op‐
15785 tions. (Except for CPU models reported as "static" in query-cpu-defi‐
15786 nitions.)
15787 • "-cpu" arguments and global properties: arguments to the -cpu option
15789 and global properties may affect expansion of CPU models. Using
15790 query-cpu-model-expansion while using these is not advised.
15791 Some architectures may not support all expansion types. s390x supports
15793 "full" and "static". Arm only supports "full".
15794 Arguments
15796 type: CpuModelExpansionType
15797 Not documented
15798 model: CpuModelInfo
15800 Not documented
15801 Returns
15803 a CpuModelExpansionInfo. Returns an error if expanding CPU models is
15804 not supported, if the model cannot be expanded, if the model contains
15805 an unknown CPU definition name, unknown properties or properties with a
15806 wrong type. Also returns an error if an expansion type is not sup‐
15807 ported.
15808 Since
15810 2.8.0
15811 If
15813 defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM).SS
15814 CpuDefinitionInfo (Object)
15815 Virtual CPU definition.
15817 Members
15819 name: string
15820 the name of the CPU definition
15821 migration-safe: boolean (optional)
15823 whether a CPU definition can be safely used for migration in
15824 combination with a QEMU compatibility machine when migrating be‐
15825 tween different QEMU versions and between hosts with different
15826 sets of (hardware or software) capabilities. If not provided,
15827 information is not available and callers should not assume the
15828 CPU definition to be migration-safe. (since 2.8)
15829 static: boolean
15831 whether a CPU definition is static and will not change depending
15832 on QEMU version, machine type, machine options and accelerator
15833 options. A static model is always migration-safe. (since 2.8)
15834 unavailable-features: array of string (optional)
15836 List of properties that prevent the CPU model from running in
15837 the current host. (since 2.8)
15838 typename: string
15840 Type name that can be used as argument to device-list-proper‐
15841 ties, to introspect properties configurable using -cpu or
15842 -global. (since 2.9)
15843 alias-of: string (optional)
15845 Name of CPU model this model is an alias for. The target of the
15846 CPU model alias may change depending on the machine type. Man‐
15847 agement software is supposed to translate CPU model aliases in
15848 the VM configuration, because aliases may stop being migra‐
15849 tion-safe in the future (since 4.1)
15850 deprecated: boolean
15852 If true, this CPU model is deprecated and may be removed in in
15853 some future version of QEMU according to the QEMU deprecation
15854 policy. (since 5.2)
15855 unavailable-features is a list of QOM property names that represent CPU
15856 model attributes that prevent the CPU from running. If the QOM prop‐
15857 erty is read-only, that means there's no known way to make the CPU
15858 model run in the current host. Implementations that choose not to pro‐
15859 vide specific information return the property name "type". If the
15860 property is read-write, it means that it MAY be possible to run the CPU
15861 model in the current host if that property is changed. Management soft‐
15862 ware can use it as hints to suggest or choose an alternative for the
15863 user, or just to generate meaningful error messages explaining why the
15864 CPU model can't be used. If unavailable-features is an empty list, the
15865 CPU model is runnable using the current host and machine-type. If un‐
15866 available-features is not present, runnability information for the CPU
15867 is not available.
15868 Since
15870 1.2.0
15871 If
15873 defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) ||
15874 defined(TARGET_S390X) || defined(TARGET_MIPS).SS query-cpu-definitions
15875 (Command)
15876 Return a list of supported virtual CPU definitions
15878 Returns
15880 a list of CpuDefInfo
15881 Since
15883 1.2.0
15884 If
15886 defined(TARGET_PPC) || defined(TARGET_ARM) || defined(TARGET_I386) ||
15887 defined(TARGET_S390X) || defined(TARGET_MIPS).SH RECORD/REPLAY
15888 ReplayMode (Enum)
15890 Mode of the replay subsystem.
15891 Values
15893 none normal execution mode. Replay or record are not enabled.
15894 record record mode. All non-deterministic data is written into the re‐
15896 play log.
15897 play replay mode. Non-deterministic data required for system execu‐
15899 tion is read from the log.
15900 Since
15902 2.5
15903 ReplayInfo (Object)
15905 Record/replay information.
15906 Members
15908 mode: ReplayMode
15909 current mode.
15910 filename: string (optional)
15912 name of the record/replay log file. It is present only in
15913 record or replay modes, when the log is recorded or replayed.
15914 icount: int
15916 current number of executed instructions.
15917 Since
15919 5.2
15920 query-replay (Command)
15922 Retrieve the record/replay information. It includes current instruc‐
15923 tion count which may be used for replay-break and replay-seek commands.
15924 Returns
15926 record/replay information.
15927 Since
15929 5.2
15930 Example
15932 -> { "execute": "query-replay" }
15933 <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
15934 replay-break (Command)
15936 Set replay breakpoint at instruction count icount. Execution stops
15937 when the specified instruction is reached. There can be at most one
15938 breakpoint. When breakpoint is set, any prior one is removed. The
15939 breakpoint may be set only in replay mode and only "in the future",
15940 i.e. at instruction counts greater than the current one. The current
15941 instruction count can be observed with query-replay.
15942 Arguments
15944 icount: int
15945 instruction count to stop at
15946 Since
15948 5.2
15949 Example
15951 -> { "execute": "replay-break", "data": { "icount": 220414 } }
15952 replay-delete-break (Command)
15954 Remove replay breakpoint which was set with replay-break. The command
15955 is ignored when there are no replay breakpoints.
15956 Since
15958 5.2
15959 Example
15961 -> { "execute": "replay-delete-break" }
15962 replay-seek (Command)
15964 Automatically proceed to the instruction count icount, when replaying
15965 the execution. The command automatically loads nearest snapshot and re‐
15966 plays the execution to find the desired instruction. When there is no
15967 preceding snapshot or the execution is not replayed, then the command
15968 fails. icount for the reference may be obtained with query-replay com‐
15969 mand.
15970 Arguments
15972 icount: int
15973 target instruction count
15974 Since
15976 5.2
15977 Example
15979 -> { "execute": "replay-seek", "data": { "icount": 220414 } }
15980
15982 add_client (Command)
15983 Allow client connections for VNC, Spice and socket based character de‐
15984 vices to be passed in to QEMU via SCM_RIGHTS.
15985 Arguments
15987 protocol: string
15988 protocol name. Valid names are "vnc", "spice" or the name of a
15989 character device (eg. from -chardev id=XXXX)
15990 fdname: string
15992 file descriptor name previously passed via 'getfd' command
15993 skipauth: boolean (optional)
15995 whether to skip authentication. Only applies to "vnc" and
15996 "spice" protocols
15997 tls: boolean (optional)
15999 whether to perform TLS. Only applies to the "spice" protocol
16000 Returns
16002 nothing on success.
16003 Since
16005 0.14.0
16006 Example
16008 -> { "execute": "add_client", "arguments": { "protocol": "vnc",
16009 "fdname": "myclient" } }
16010 <- { "return": {} }
16011 NameInfo (Object)
16013 Guest name information.
16014 Members
16016 name: string (optional)
16017 The name of the guest
16018 Since
16020 0.14.0
16021 query-name (Command)
16023 Return the name information of a guest.
16024 Returns
16026 NameInfo of the guest
16027 Since
16029 0.14.0
16030 Example
16032 -> { "execute": "query-name" }
16033 <- { "return": { "name": "qemu-name" } }
16034 IOThreadInfo (Object)
16036 Information about an iothread
16037 Members
16039 id: string
16040 the identifier of the iothread
16041 thread-id: int
16043 ID of the underlying host thread
16044 poll-max-ns: int
16046 maximum polling time in ns, 0 means polling is disabled (since
16047 2.9)
16048 poll-grow: int
16050 how many ns will be added to polling time, 0 means that it's not
16051 configured (since 2.9)
16052 poll-shrink: int
16054 how many ns will be removed from polling time, 0 means that it's
16055 not configured (since 2.9)
16056 Since
16058 2.0
16059 query-iothreads (Command)
16061 Returns a list of information about each iothread.
16062 Note
16064 this list excludes the QEMU main loop thread, which is not declared us‐
16065 ing the -object iothread command-line option. It is always the main
16066 thread of the process.
16067 Returns
16069 a list of IOThreadInfo for each iothread
16070 Since
16072 2.0
16073 Example
16075 -> { "execute": "query-iothreads" }
16076 <- { "return": [
16077 {
16078 "id":"iothread0",
16079 "thread-id":3134
16080 },
16081 {
16082 "id":"iothread1",
16083 "thread-id":3135
16084 }
16085 ]
16086 }
16087 stop (Command)
16089 Stop all guest VCPU execution.
16090 Since
16092 0.14.0
16093 Notes
16095 This function will succeed even if the guest is already in the stopped
16096 state. In "inmigrate" state, it will ensure that the guest remains
16097 paused once migration finishes, as if the -S option was passed on the
16098 command line.
16099 Example
16101 -> { "execute": "stop" }
16102 <- { "return": {} }
16103 cont (Command)
16105 Resume guest VCPU execution.
16106 Since
16108 0.14.0
16109 Returns
16111 If successful, nothing
16112 Notes
16114 This command will succeed if the guest is currently running. It will
16115 also succeed if the guest is in the "inmigrate" state; in this case,
16116 the effect of the command is to make sure the guest starts once migra‐
16117 tion finishes, removing the effect of the -S command line option if it
16118 was passed.
16119 Example
16121 -> { "execute": "cont" }
16122 <- { "return": {} }
16123 x-exit-preconfig (Command)
16125 Exit from "preconfig" state
16126 This command makes QEMU exit the preconfig state and proceed with VM
16128 initialization using configuration data provided on the command line
16129 and via the QMP monitor during the preconfig state. The command is only
16130 available during the preconfig state (i.e. when the --preconfig command
16131 line option was in use).
16132 Since 3.0
16134 Returns
16136 nothing
16137 Example
16139 -> { "execute": "x-exit-preconfig" }
16140 <- { "return": {} }
16141 human-monitor-command (Command)
16143 Execute a command on the human monitor and return the output.
16144 Arguments
16146 command-line: string
16147 the command to execute in the human monitor
16148 cpu-index: int (optional)
16150 The CPU to use for commands that require an implicit CPU
16151 Features
16153 savevm-monitor-nodes
16154 If present, HMP command savevm only snapshots monitor-owned
16155 nodes if they have no parents. This allows the use of 'savevm'
16156 with -blockdev. (since 4.2)
16157 Returns
16159 the output of the command as a string
16160 Since
16162 0.14.0
16163 Notes
16165 This command only exists as a stop-gap. Its use is highly discouraged.
16166 The semantics of this command are not guaranteed: this means that com‐
16167 mand names, arguments and responses can change or be removed at ANY
16168 time. Applications that rely on long term stability guarantees should
16169 NOT use this command.
16170 Known limitations:
16172 • This command is stateless, this means that commands that depend on
16174 state information (such as getfd) might not work
16175 • Commands that prompt the user for data don't currently work
16177 Example
16179 -> { "execute": "human-monitor-command",
16180 "arguments": { "command-line": "info kvm" } }
16181 <- { "return": "kvm support: enabled\r\n" }
16182 change (Command)
16184 This command is multiple commands multiplexed together.
16185 Arguments
16187 device: string
16188 This is normally the name of a block device but it may also be
16189 'vnc'. when it's 'vnc', then sub command depends on target
16190 target: string
16192 If device is a block device, then this is the new filename. If
16193 device is 'vnc', then if the value 'password' selects the vnc
16194 change password command. Otherwise, this specifies a new
16195 server URI address to listen to for VNC connections.
16196 arg: string (optional)
16198 If device is a block device, then this is an optional format to
16199 open the device with. If device is 'vnc' and target is 'pass‐
16200 word', this is the new VNC password to set. See
16201 change-vnc-password for additional notes.
16202 Features
16204 deprecated
16205 This command is deprecated. For changing block devices, use
16206 'blockdev-change-medium' instead; for changing VNC parameters,
16207 use 'change-vnc-password' instead.
16208 Returns
16210 • Nothing on success.
16211 • If device is not a valid block device, DeviceNotFound
16213 Since
16215 0.14.0
16216 Example
16218 1. Change a removable medium
16219 -> { "execute": "change",
16221 "arguments": { "device": "ide1-cd0",
16222 "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
16223 <- { "return": {} }
16224 2. Change VNC password
16226 -> { "execute": "change",
16228 "arguments": { "device": "vnc", "target": "password",
16229 "arg": "foobar1" } }
16230 <- { "return": {} }
16231 getfd (Command)
16233 Receive a file descriptor via SCM rights and assign it a name
16234 Arguments
16236 fdname: string
16237 file descriptor name
16238 Returns
16240 Nothing on success
16241 Since
16243 0.14.0
16244 Notes
16246 If fdname already exists, the file descriptor assigned to it will be
16247 closed and replaced by the received file descriptor.
16248 The 'closefd' command can be used to explicitly close the file descrip‐
16250 tor when it is no longer needed.
16251 Example
16253 -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
16254 <- { "return": {} }
16255 closefd (Command)
16257 Close a file descriptor previously passed via SCM rights
16258 Arguments
16260 fdname: string
16261 file descriptor name
16262 Returns
16264 Nothing on success
16265 Since
16267 0.14.0
16268 Example
16270 -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
16271 <- { "return": {} }
16272 AddfdInfo (Object)
16274 Information about a file descriptor that was added to an fd set.
16275 Members
16277 fdset-id: int
16278 The ID of the fd set that fd was added to.
16279 fd: int
16281 The file descriptor that was received via SCM rights and added
16282 to the fd set.
16283 Since
16285 1.2.0
16286 add-fd (Command)
16288 Add a file descriptor, that was passed via SCM rights, to an fd set.
16289 Arguments
16291 fdset-id: int (optional)
16292 The ID of the fd set to add the file descriptor to.
16293 opaque: string (optional)
16295 A free-form string that can be used to describe the fd.
16296 Returns
16298 • AddfdInfo on success
16299 • If file descriptor was not received, FdNotSupplied
16301 • If fdset-id is a negative value, InvalidParameterValue
16303 Notes
16305 The list of fd sets is shared by all monitor connections.
16306 If fdset-id is not specified, a new fd set will be created.
16308 Since
16310 1.2.0
16311 Example
16313 -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
16314 <- { "return": { "fdset-id": 1, "fd": 3 } }
16315 remove-fd (Command)
16317 Remove a file descriptor from an fd set.
16318 Arguments
16320 fdset-id: int
16321 The ID of the fd set that the file descriptor belongs to.
16322 fd: int (optional)
16324 The file descriptor that is to be removed.
16325 Returns
16327 • Nothing on success
16328 • If fdset-id or fd is not found, FdNotFound
16330 Since
16332 1.2.0
16333 Notes
16335 The list of fd sets is shared by all monitor connections.
16336 If fd is not specified, all file descriptors in fdset-id will be re‐
16338 moved.
16339 Example
16341 -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
16342 <- { "return": {} }
16343 FdsetFdInfo (Object)
16345 Information about a file descriptor that belongs to an fd set.
16346 Members
16348 fd: int
16349 The file descriptor value.
16350 opaque: string (optional)
16352 A free-form string that can be used to describe the fd.
16353 Since
16355 1.2.0
16356 FdsetInfo (Object)
16358 Information about an fd set.
16359 Members
16361 fdset-id: int
16362 The ID of the fd set.
16363 fds: array of FdsetFdInfo
16365 A list of file descriptors that belong to this fd set.
16366 Since
16368 1.2.0
16369 query-fdsets (Command)
16371 Return information describing all fd sets.
16372 Returns
16374 A list of FdsetInfo
16375 Since
16377 1.2.0
16378 Note
16380 The list of fd sets is shared by all monitor connections.
16381 Example
16383 -> { "execute": "query-fdsets" }
16384 <- { "return": [
16385 {
16386 "fds": [
16387 {
16388 "fd": 30,
16389 "opaque": "rdonly:/path/to/file"
16390 },
16391 {
16392 "fd": 24,
16393 "opaque": "rdwr:/path/to/file"
16394 }
16395 ],
16396 "fdset-id": 1
16397 },
16398 {
16399 "fds": [
16400 {
16401 "fd": 28
16402 },
16403 {
16404 "fd": 29
16405 }
16406 ],
16407 "fdset-id": 0
16408 }
16409 ]
16410 }
16411 CommandLineParameterType (Enum)
16413 Possible types for an option parameter.
16414 Values
16416 string accepts a character string
16417 boolean
16419 accepts "on" or "off"
16420 number accepts a number
16422 size accepts a number followed by an optional suffix (K)ilo, (M)ega,
16424 (G)iga, (T)era
16425 Since
16427 1.5
16428 CommandLineParameterInfo (Object)
16430 Details about a single parameter of a command line option.
16431 Members
16433 name: string
16434 parameter name
16435 type: CommandLineParameterType
16437 parameter CommandLineParameterType
16438 help: string (optional)
16440 human readable text string, not suitable for parsing.
16441 default: string (optional)
16443 default value string (since 2.1)
16444 Since
16446 1.5
16447 CommandLineOptionInfo (Object)
16449 Details about a command line option, including its list of parameter
16450 details
16451 Members
16453 option: string
16454 option name
16455 parameters: array of CommandLineParameterInfo
16457 an array of CommandLineParameterInfo
16458 Since
16460 1.5
16461 query-command-line-options (Command)
16463 Query command line option schema.
16464 Arguments
16466 option: string (optional)
16467 option name
16468 Returns
16470 list of CommandLineOptionInfo for all options (or for the given op‐
16471 tion). Returns an error if the given option doesn't exist.
16472 Since
16474 1.5
16475 Example
16477 -> { "execute": "query-command-line-options",
16478 "arguments": { "option": "option-rom" } }
16479 <- { "return": [
16480 {
16481 "parameters": [
16482 {
16483 "name": "romfile",
16484 "type": "string"
16485 },
16486 {
16487 "name": "bootindex",
16488 "type": "number"
16489 }
16490 ],
16491 "option": "option-rom"
16492 }
16493 ]
16494 }
16495 RTC_CHANGE (Event)
16497 Emitted when the guest changes the RTC time.
16498 Arguments
16500 offset: int
16501 offset between base RTC clock (as specified by -rtc base), and
16502 new RTC clock value
16503 Note
16505 This event is rate-limited.
16506 Since
16508 0.13.0
16509 Example
16511 <- { "event": "RTC_CHANGE",
16512 "data": { "offset": 78 },
16513 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
16514 If
16516 defined(TARGET_ALPHA) || defined(TARGET_ARM) || defined(TARGET_HPPA) ||
16517 defined(TARGET_I386) || defined(TARGET_MIPS) || defined(TARGET_MIPS64)
16518 || defined(TARGET_MOXIE) || defined(TARGET_PPC) || defined(TAR‐
16519 GET_PPC64) || defined(TARGET_S390X) || defined(TARGET_SH4) || de‐
16520 fined(TARGET_SPARC).SS rtc-reset-reinjection (Command)
16521 This command will reset the RTC interrupt reinjection backlog. Can be
16523 used if another mechanism to synchronize guest time is in effect, for
16524 example QEMU guest agent's guest-set-time command.
16525 Since
16527 2.1
16528 Example
16530 -> { "execute": "rtc-reset-reinjection" }
16531 <- { "return": {} }
16532 If
16534 defined(TARGET_I386).SS SevState (Enum)
16535 An enumeration of SEV state information used during query-sev.
16537 Values
16539 uninit The guest is uninitialized.
16540 launch-update
16542 The guest is currently being launched; plaintext data and regis‐
16543 ter state is being imported.
16544 launch-secret
16546 The guest is currently being launched; ciphertext data is being
16547 imported.
16548 running
16550 The guest is fully launched or migrated in.
16551 send-update
16553 The guest is currently being migrated out to another machine.
16554 receive-update
16556 The guest is currently being migrated from another machine.
16557 Since
16559 2.12
16560 If
16562 defined(TARGET_I386).SS SevInfo (Object)
16563 Information about Secure Encrypted Virtualization (SEV) support
16565 Members
16567 enabled: boolean
16568 true if SEV is active
16569 api-major: int
16571 SEV API major version
16572 api-minor: int
16574 SEV API minor version
16575 build-id: int
16577 SEV FW build id
16578 policy: int
16580 SEV policy value
16581 state: SevState
16583 SEV guest state
16584 handle: int
16586 SEV firmware handle
16587 Since
16589 2.12
16590 If
16592 defined(TARGET_I386).SS query-sev (Command)
16593 Returns information about SEV
16595 Returns
16597 SevInfo
16598 Since
16600 2.12
16601 Example
16603 -> { "execute": "query-sev" }
16604 <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
16605 "build-id" : 0, "policy" : 0, "state" : "running",
16606 "handle" : 1 } }
16607 If
16609 defined(TARGET_I386).SS SevLaunchMeasureInfo (Object)
16610 SEV Guest Launch measurement information
16612 Members
16614 data: string
16615 the measurement value encoded in base64
16616 Since
16618 2.12
16619 If
16621 defined(TARGET_I386).SS query-sev-launch-measure (Command)
16622 Query the SEV guest launch information.
16624 Returns
16626 The SevLaunchMeasureInfo for the guest
16627 Since
16629 2.12
16630 Example
16632 -> { "execute": "query-sev-launch-measure" }
16633 <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
16634 If
16636 defined(TARGET_I386).SS SevCapability (Object)
16637 The struct describes capability for a Secure Encrypted Virtualization
16639 feature.
16640 Members
16642 pdh: string
16643 Platform Diffie-Hellman key (base64 encoded)
16644 cert-chain: string
16646 PDH certificate chain (base64 encoded)
16647 cbitpos: int
16649 C-bit location in page table entry
16650 reduced-phys-bits: int
16652 Number of physical Address bit reduction when SEV is enabled
16653 Since
16655 2.12
16656 If
16658 defined(TARGET_I386).SS query-sev-capabilities (Command)
16659 This command is used to get the SEV capabilities, and is supported on
16661 AMD X86 platforms only.
16662 Returns
16664 SevCapability objects.
16665 Since
16667 2.12
16668 Example
16670 -> { "execute": "query-sev-capabilities" }
16671 <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
16672 "cbitpos": 47, "reduced-phys-bits": 5}}
16673 If
16675 defined(TARGET_I386).SS dump-skeys (Command)
16676 Dump guest's storage keys
16678 Arguments
16680 filename: string
16681 the path to the file to dump to
16682 This command is only supported on s390 architecture.
16683 Since
16685 2.5
16686 Example
16688 -> { "execute": "dump-skeys",
16689 "arguments": { "filename": "/tmp/skeys" } }
16690 <- { "return": {} }
16691 If
16693 defined(TARGET_S390X).SS GICCapability (Object)
16694 The struct describes capability for a specific GIC (Generic Interrupt
16696 Controller) version. These bits are not only decided by QEMU/KVM soft‐
16697 ware version, but also decided by the hardware that the program is run‐
16698 ning upon.
16699 Members
16701 version: int
16702 version of GIC to be described. Currently, only 2 and 3 are sup‐
16703 ported.
16704 emulated: boolean
16706 whether current QEMU/hardware supports emulated GIC device in
16707 user space.
16708 kernel: boolean
16710 whether current QEMU/hardware supports hardware accelerated GIC
16711 device in kernel.
16712 Since
16714 2.6
16715 If
16717 defined(TARGET_ARM).SS query-gic-capabilities (Command)
16718 This command is ARM-only. It will return a list of GICCapability ob‐
16720 jects that describe its capability bits.
16721 Returns
16723 a list of GICCapability objects.
16724 Since
16726 2.6
16727 Example
16729 -> { "execute": "query-gic-capabilities" }
16730 <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
16731 { "version": 3, "emulated": false, "kernel": true } ] }
16732 If
16734 defined(TARGET_ARM).SH AUDIO
16735 AudiodevPerDirectionOptions (Object)
16737 General audio backend options that are used for both playback and
16738 recording.
16739 Members
16741 mixing-engine: boolean (optional)
16742 use QEMU's mixing engine to mix all streams inside QEMU and con‐
16743 vert audio formats when not supported by the backend. When set
16744 to off, fixed-settings must be also off (default on, since 4.2)
16745 fixed-settings: boolean (optional)
16747 use fixed settings for host input/output. When off, frequency,
16748 channels and format must not be specified (default true)
16749 frequency: int (optional)
16751 frequency to use when using fixed settings (default 44100)
16752 channels: int (optional)
16754 number of channels when using fixed settings (default 2)
16755 voices: int (optional)
16757 number of voices to use (default 1)
16758 format: AudioFormat (optional)
16760 sample format to use when using fixed settings (default s16)
16761 buffer-length: int (optional)
16763 the buffer length in microseconds
16764 Since
16766 4.0
16767 AudiodevGenericOptions (Object)
16769 Generic driver-specific options.
16770 Members
16772 in: AudiodevPerDirectionOptions (optional)
16773 options of the capture stream
16774 out: AudiodevPerDirectionOptions (optional)
16776 options of the playback stream
16777 Since
16779 4.0
16780 AudiodevAlsaPerDirectionOptions (Object)
16782 Options of the ALSA backend that are used for both playback and record‐
16783 ing.
16784 Members
16786 dev: string (optional)
16787 the name of the ALSA device to use (default 'default')
16788 period-length: int (optional)
16790 the period length in microseconds
16791 try-poll: boolean (optional)
16793 attempt to use poll mode, falling back to non-polling access on
16794 failure (default true)
16795 The members of AudiodevPerDirectionOptions
16797 Since
16799 4.0
16800 AudiodevAlsaOptions (Object)
16802 Options of the ALSA audio backend.
16803 Members
16805 in: AudiodevAlsaPerDirectionOptions (optional)
16806 options of the capture stream
16807 out: AudiodevAlsaPerDirectionOptions (optional)
16809 options of the playback stream
16810 threshold: int (optional)
16812 set the threshold (in microseconds) when playback starts
16813 Since
16815 4.0
16816 AudiodevCoreaudioPerDirectionOptions (Object)
16818 Options of the Core Audio backend that are used for both playback and
16819 recording.
16820 Members
16822 buffer-count: int (optional)
16823 number of buffers
16824 The members of AudiodevPerDirectionOptions
16826 Since
16828 4.0
16829 AudiodevCoreaudioOptions (Object)
16831 Options of the coreaudio audio backend.
16832 Members
16834 in: AudiodevCoreaudioPerDirectionOptions (optional)
16835 options of the capture stream
16836 out: AudiodevCoreaudioPerDirectionOptions (optional)
16838 options of the playback stream
16839 Since
16841 4.0
16842 AudiodevDsoundOptions (Object)
16844 Options of the DirectSound audio backend.
16845 Members
16847 in: AudiodevPerDirectionOptions (optional)
16848 options of the capture stream
16849 out: AudiodevPerDirectionOptions (optional)
16851 options of the playback stream
16852 latency: int (optional)
16854 add extra latency to playback in microseconds (default 10000)
16855 Since
16857 4.0
16858 AudiodevJackPerDirectionOptions (Object)
16860 Options of the JACK backend that are used for both playback and record‐
16861 ing.
16862 Members
16864 server-name: string (optional)
16865 select from among several possible concurrent server instances
16866 (default: environment variable $JACK_DEFAULT_SERVER if set, else
16867 "default")
16868 client-name: string (optional)
16870 the client name to use. The server will modify this name to cre‐
16871 ate a unique variant, if needed unless exact-name is true (de‐
16872 fault: the guest's name)
16873 connect-ports: string (optional)
16875 if set, a regular expression of JACK client port name(s) to mon‐
16876 itor for and automatically connect to
16877 start-server: boolean (optional)
16879 start a jack server process if one is not already present (de‐
16880 fault: false)
16881 exact-name: boolean (optional)
16883 use the exact name requested otherwise JACK automatically gener‐
16884 ates a unique one, if needed (default: false)
16885 The members of AudiodevPerDirectionOptions
16887 Since
16889 5.1
16890 AudiodevJackOptions (Object)
16892 Options of the JACK audio backend.
16893 Members
16895 in: AudiodevJackPerDirectionOptions (optional)
16896 options of the capture stream
16897 out: AudiodevJackPerDirectionOptions (optional)
16899 options of the playback stream
16900 Since
16902 5.1
16903 AudiodevOssPerDirectionOptions (Object)
16905 Options of the OSS backend that are used for both playback and record‐
16906 ing.
16907 Members
16909 dev: string (optional)
16910 file name of the OSS device (default '/dev/dsp')
16911 buffer-count: int (optional)
16913 number of buffers
16914 try-poll: boolean (optional)
16916 attempt to use poll mode, falling back to non-polling access on
16917 failure (default true)
16918 The members of AudiodevPerDirectionOptions
16920 Since
16922 4.0
16923 AudiodevOssOptions (Object)
16925 Options of the OSS audio backend.
16926 Members
16928 in: AudiodevOssPerDirectionOptions (optional)
16929 options of the capture stream
16930 out: AudiodevOssPerDirectionOptions (optional)
16932 options of the playback stream
16933 try-mmap: boolean (optional)
16935 try using memory-mapped access, falling back to non-mem‐
16936 ory-mapped access on failure (default true)
16937 exclusive: boolean (optional)
16939 open device in exclusive mode (vmix won't work) (default false)
16940 dsp-policy: int (optional)
16942 set the timing policy of the device (between 0 and 10, where
16943 smaller number means smaller latency but higher CPU usage) or -1
16944 to use fragment mode (option ignored on some platforms) (default
16945 5)
16946 Since
16948 4.0
16949 AudiodevPaPerDirectionOptions (Object)
16951 Options of the Pulseaudio backend that are used for both playback and
16952 recording.
16953 Members
16955 name: string (optional)
16956 name of the sink/source to use
16957 stream-name: string (optional)
16959 name of the PulseAudio stream created by qemu. Can be used to
16960 identify the stream in PulseAudio when you create multiple
16961 PulseAudio devices or run multiple qemu instances (default: au‐
16962 diodev's id, since 4.2)
16963 latency: int (optional)
16965 latency you want PulseAudio to achieve in microseconds (default
16966 15000)
16967 The members of AudiodevPerDirectionOptions
16969 Since
16971 4.0
16972 AudiodevPaOptions (Object)
16974 Options of the PulseAudio audio backend.
16975 Members
16977 in: AudiodevPaPerDirectionOptions (optional)
16978 options of the capture stream
16979 out: AudiodevPaPerDirectionOptions (optional)
16981 options of the playback stream
16982 server: string (optional)
16984 PulseAudio server address (default: let PulseAudio choose)
16985 Since
16987 4.0
16988 AudiodevWavOptions (Object)
16990 Options of the wav audio backend.
16991 Members
16993 in: AudiodevPerDirectionOptions (optional)
16994 options of the capture stream
16995 out: AudiodevPerDirectionOptions (optional)
16997 options of the playback stream
16998 path: string (optional)
17000 name of the wav file to record (default 'qemu.wav')
17001 Since
17003 4.0
17004 AudioFormat (Enum)
17006 An enumeration of possible audio formats.
17007 Values
17009 u8 unsigned 8 bit integer
17010 s8 signed 8 bit integer
17012 u16 unsigned 16 bit integer
17014 s16 signed 16 bit integer
17016 u32 unsigned 32 bit integer
17018 s32 signed 32 bit integer
17020 f32 single precision floating-point (since 5.0)
17022 Since
17024 4.0
17025 AudiodevDriver (Enum)
17027 An enumeration of possible audio backend drivers.
17028 Values
17030 jack JACK audio backend (since 5.1)
17031 none Not documented
17033 alsa Not documented
17035 coreaudio
17037 Not documented
17038 dsound Not documented
17040 oss Not documented
17042 pa Not documented
17044 sdl Not documented
17046 spice Not documented
17048 wav Not documented
17050 Since
17052 4.0
17053 Audiodev (Object)
17055 Options of an audio backend.
17056 Members
17058 id: string
17059 identifier of the backend
17060 driver: AudiodevDriver
17062 the backend driver to use
17063 timer-period: int (optional)
17065 timer period (in microseconds, 0: use lowest possible)
17066 The members of AudiodevGenericOptions when driver is "none"
17068 The members of AudiodevAlsaOptions when driver is "alsa"
17070 The members of AudiodevCoreaudioOptions when driver is "coreaudio"
17072 The members of AudiodevDsoundOptions when driver is "dsound"
17074 The members of AudiodevJackOptions when driver is "jack"
17076 The members of AudiodevOssOptions when driver is "oss"
17078 The members of AudiodevPaOptions when driver is "pa"
17080 The members of AudiodevGenericOptions when driver is "sdl"
17082 The members of AudiodevGenericOptions when driver is "spice"
17084 The members of AudiodevWavOptions when driver is "wav"
17086 Since
17088 4.0
17089
17091 AcpiTableOptions (Object)
17092 Specify an ACPI table on the command line to load.
17093 At most one of file and data can be specified. The list of files speci‐
17095 fied by any one of them is loaded and concatenated in order. If both
17096 are omitted, data is implied.
17097 Other fields / optargs can be used to override fields of the generic
17099 ACPI table header; refer to the ACPI specification 5.0, section 5.2.6
17100 System Description Table Header. If a header field is not overridden,
17101 then the corresponding value from the concatenated blob is used (in
17102 case of file), or it is filled in with a hard-coded value (in case of
17103 data).
17104 String fields are copied into the matching ACPI member from lowest ad‐
17106 dress upwards, and silently truncated / NUL-padded to length.
17107 Members
17109 sig: string (optional)
17110 table signature / identifier (4 bytes)
17111 rev: int (optional)
17113 table revision number (dependent on signature, 1 byte)
17114 oem_id: string (optional)
17116 OEM identifier (6 bytes)
17117 oem_table_id: string (optional)
17119 OEM table identifier (8 bytes)
17120 oem_rev: int (optional)
17122 OEM-supplied revision number (4 bytes)
17123 asl_compiler_id: string (optional)
17125 identifier of the utility that created the table (4 bytes)
17126 asl_compiler_rev: int (optional)
17128 revision number of the utility that created the table (4 bytes)
17129 file: string (optional)
17131 colon (:) separated list of pathnames to load and concatenate as
17132 table data. The resultant binary blob is expected to have an
17133 ACPI table header. At least one file is required. This field ex‐
17134 cludes data.
17135 data: string (optional)
17137 colon (:) separated list of pathnames to load and concatenate as
17138 table data. The resultant binary blob must not have an ACPI ta‐
17139 ble header. At least one file is required. This field excludes
17140 file.
17141 Since
17143 1.5
17144 ACPISlotType (Enum)
17146 Values
17147 DIMM memory slot
17148 CPU logical CPU slot (since 2.7)
17150 ACPIOSTInfo (Object)
17152 OSPM Status Indication for a device For description of possible values
17153 of source and status fields see "_OST (OSPM Status Indication)" chapter
17154 of ACPI5.0 spec.
17155 Members
17157 device: string (optional)
17158 device ID associated with slot
17159 slot: string
17161 slot ID, unique per slot of a given slot-type
17162 slot-type: ACPISlotType
17164 type of the slot
17165 source: int
17167 an integer containing the source event
17168 status: int
17170 an integer containing the status code
17171 Since
17173 2.1
17174 query-acpi-ospm-status (Command)
17176 Return a list of ACPIOSTInfo for devices that support status reporting
17177 via ACPI _OST method.
17178 Since
17180 2.1
17181 Example
17183 -> { "execute": "query-acpi-ospm-status" }
17184 <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
17185 { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
17186 { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
17187 { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
17188 ]}
17189 ACPI_DEVICE_OST (Event)
17191 Emitted when guest executes ACPI _OST method.
17192 Arguments
17194 info: ACPIOSTInfo
17195 OSPM Status Indication
17196 Since
17198 2.1
17199 Example
17201 <- { "event": "ACPI_DEVICE_OST",
17202 "data": { "device": "d1", "slot": "0",
17203 "slot-type": "DIMM", "source": 1, "status": 0 } }
17204
17206 PciMemoryRange (Object)
17207 A PCI device memory region
17208 Members
17210 base: int
17211 the starting address (guest physical)
17212 limit: int
17214 the ending address (guest physical)
17215 Since
17217 0.14.0
17218 PciMemoryRegion (Object)
17220 Information about a PCI device I/O region.
17221 Members
17223 bar: int
17224 the index of the Base Address Register for this region
17225 type: string
17227 • 'io' if the region is a PIO region
17229 • 'memory' if the region is a MMIO region
17231 size: int
17233 memory size
17234 prefetch: boolean (optional)
17236 if type is 'memory', true if the memory is prefetchable
17237 mem_type_64: boolean (optional)
17239 if type is 'memory', true if the BAR is 64-bit
17240 address: int
17242 Not documented
17243 Since
17245 0.14.0
17246 PciBusInfo (Object)
17248 Information about a bus of a PCI Bridge device
17249 Members
17251 number: int
17252 primary bus interface number. This should be the number of the
17253 bus the device resides on.
17254 secondary: int
17256 secondary bus interface number. This is the number of the main
17257 bus for the bridge
17258 subordinate: int
17260 This is the highest number bus that resides below the bridge.
17261 io_range: PciMemoryRange
17263 The PIO range for all devices on this bridge
17264 memory_range: PciMemoryRange
17266 The MMIO range for all devices on this bridge
17267 prefetchable_range: PciMemoryRange
17269 The range of prefetchable MMIO for all devices on this bridge
17270 Since
17272 2.4
17273 PciBridgeInfo (Object)
17275 Information about a PCI Bridge device
17276 Members
17278 bus: PciBusInfo
17279 information about the bus the device resides on
17280 devices: array of PciDeviceInfo (optional)
17282 a list of PciDeviceInfo for each device on this bridge
17283 Since
17285 0.14.0
17286 PciDeviceClass (Object)
17288 Information about the Class of a PCI device
17289 Members
17291 desc: string (optional)
17292 a string description of the device's class
17293 class: int
17295 the class code of the device
17296 Since
17298 2.4
17299 PciDeviceId (Object)
17301 Information about the Id of a PCI device
17302 Members
17304 device: int
17305 the PCI device id
17306 vendor: int
17308 the PCI vendor id
17309 subsystem: int (optional)
17311 the PCI subsystem id (since 3.1)
17312 subsystem-vendor: int (optional)
17314 the PCI subsystem vendor id (since 3.1)
17315 Since
17317 2.4
17318 PciDeviceInfo (Object)
17320 Information about a PCI device
17321 Members
17323 bus: int
17324 the bus number of the device
17325 slot: int
17327 the slot the device is located in
17328 function: int
17330 the function of the slot used by the device
17331 class_info: PciDeviceClass
17333 the class of the device
17334 id: PciDeviceId
17336 the PCI device id
17337 irq: int (optional)
17339 if an IRQ is assigned to the device, the IRQ number
17340 irq_pin: int
17342 the IRQ pin, zero means no IRQ (since 5.1)
17343 qdev_id: string
17345 the device name of the PCI device
17346 pci_bridge: PciBridgeInfo (optional)
17348 if the device is a PCI bridge, the bridge information
17349 regions: array of PciMemoryRegion
17351 a list of the PCI I/O regions associated with the device
17352 Notes
17354 the contents of class_info.desc are not stable and should only be
17355 treated as informational.
17356 Since
17358 0.14.0
17359 PciInfo (Object)
17361 Information about a PCI bus
17362 Members
17364 bus: int
17365 the bus index
17366 devices: array of PciDeviceInfo
17368 a list of devices on this bus
17369 Since
17371 0.14.0
17372 query-pci (Command)
17374 Return information about the PCI bus topology of the guest.
17375 Returns
17377 a list of PciInfo for each PCI bus. Each bus is represented by a
17378 json-object, which has a key with a json-array of all PCI devices at‐
17379 tached to it. Each device is represented by a json-object.
17380 Since
17382 0.14.0
17383 Example
17385 -> { "execute": "query-pci" }
17386 <- { "return": [
17387 {
17388 "bus": 0,
17389 "devices": [
17390 {
17391 "bus": 0,
17392 "qdev_id": "",
17393 "slot": 0,
17394 "class_info": {
17395 "class": 1536,
17396 "desc": "Host bridge"
17397 },
17398 "id": {
17399 "device": 32902,
17400 "vendor": 4663
17401 },
17402 "function": 0,
17403 "regions": [
17404 ]
17405 },
17406 {
17407 "bus": 0,
17408 "qdev_id": "",
17409 "slot": 1,
17410 "class_info": {
17411 "class": 1537,
17412 "desc": "ISA bridge"
17413 },
17414 "id": {
17415 "device": 32902,
17416 "vendor": 28672
17417 },
17418 "function": 0,
17419 "regions": [
17420 ]
17421 },
17422 {
17423 "bus": 0,
17424 "qdev_id": "",
17425 "slot": 1,
17426 "class_info": {
17427 "class": 257,
17428 "desc": "IDE controller"
17429 },
17430 "id": {
17431 "device": 32902,
17432 "vendor": 28688
17433 },
17434 "function": 1,
17435 "regions": [
17436 {
17437 "bar": 4,
17438 "size": 16,
17439 "address": 49152,
17440 "type": "io"
17441 }
17442 ]
17443 },
17444 {
17445 "bus": 0,
17446 "qdev_id": "",
17447 "slot": 2,
17448 "class_info": {
17449 "class": 768,
17450 "desc": "VGA controller"
17451 },
17452 "id": {
17453 "device": 4115,
17454 "vendor": 184
17455 },
17456 "function": 0,
17457 "regions": [
17458 {
17459 "prefetch": true,
17460 "mem_type_64": false,
17461 "bar": 0,
17462 "size": 33554432,
17463 "address": 4026531840,
17464 "type": "memory"
17465 },
17466 {
17467 "prefetch": false,
17468 "mem_type_64": false,
17469 "bar": 1,
17470 "size": 4096,
17471 "address": 4060086272,
17472 "type": "memory"
17473 },
17474 {
17475 "prefetch": false,
17476 "mem_type_64": false,
17477 "bar": 6,
17478 "size": 65536,
17479 "address": -1,
17480 "type": "memory"
17481 }
17482 ]
17483 },
17484 {
17485 "bus": 0,
17486 "qdev_id": "",
17487 "irq": 11,
17488 "slot": 4,
17489 "class_info": {
17490 "class": 1280,
17491 "desc": "RAM controller"
17492 },
17493 "id": {
17494 "device": 6900,
17495 "vendor": 4098
17496 },
17497 "function": 0,
17498 "regions": [
17499 {
17500 "bar": 0,
17501 "size": 32,
17502 "address": 49280,
17503 "type": "io"
17504 }
17505 ]
17506 }
17507 ]
17508 }
17509 ]
17510 }
17511 Note
17513 This example has been shortened as the real response is too long.
17514
17516 2021, The QEMU Project Developers
175175.2.0 May 19, 2021 QEMU-QMP-REF(7)