1QEMU-STORAGE-DAEMON-QMP-REF(7) QEMU QEMU-STORAGE-DAEMON-QMP-REF(7)
2
6 qemu-storage-daemon-qmp-ref - QEMU Storage Daemon QMP Reference Manual
7 Contents
9 • QEMU Storage Daemon QMP Reference Manual
10 • Common data types
12 • IoOperationType (Enum)
14 • OnOffAuto (Enum)
16 • OnOffSplit (Enum)
18 • String (Object)
20 • StrOrNull (Alternate)
22 • OffAutoPCIBAR (Enum)
24 • PCIELinkSpeed (Enum)
26 • PCIELinkWidth (Enum)
28 • HostMemPolicy (Enum)
30 • NetFilterDirection (Enum)
32 • GrabToggleKeys (Enum)
34 • HumanReadableText (Object)
36 • Socket data types
38 • NetworkAddressFamily (Enum)
40 • InetSocketAddressBase (Object)
42 • InetSocketAddress (Object)
44 • UnixSocketAddress (Object)
46 • VsockSocketAddress (Object)
48 • InetSocketAddressWrapper (Object)
50 • UnixSocketAddressWrapper (Object)
52 • VsockSocketAddressWrapper (Object)
54 • StringWrapper (Object)
56 • SocketAddressLegacy (Object)
58 • SocketAddressType (Enum)
60 • SocketAddress (Object)
62 • Cryptography
64 • QCryptoTLSCredsEndpoint (Enum)
66 • QCryptoSecretFormat (Enum)
68 • QCryptoHashAlgorithm (Enum)
70 • QCryptoCipherAlgorithm (Enum)
72 • QCryptoCipherMode (Enum)
74 • QCryptoIVGenAlgorithm (Enum)
76 • QCryptoBlockFormat (Enum)
78 • QCryptoBlockOptionsBase (Object)
80 • QCryptoBlockOptionsQCow (Object)
82 • QCryptoBlockOptionsLUKS (Object)
84 • QCryptoBlockCreateOptionsLUKS (Object)
86 • QCryptoBlockOpenOptions (Object)
88 • QCryptoBlockCreateOptions (Object)
90 • QCryptoBlockInfoBase (Object)
92 • QCryptoBlockInfoLUKSSlot (Object)
94 • QCryptoBlockInfoLUKS (Object)
96 • QCryptoBlockInfo (Object)
98 • QCryptoBlockLUKSKeyslotState (Enum)
100 • QCryptoBlockAmendOptionsLUKS (Object)
102 • QCryptoBlockAmendOptions (Object)
104 • SecretCommonProperties (Object)
106 • SecretProperties (Object)
108 • SecretKeyringProperties (Object)
110 • TlsCredsProperties (Object)
112 • TlsCredsAnonProperties (Object)
114 • TlsCredsPskProperties (Object)
116 • TlsCredsX509Properties (Object)
118 • QCryptoAkCipherAlgorithm (Enum)
120 • QCryptoAkCipherKeyType (Enum)
122 • QCryptoRSAPaddingAlgorithm (Enum)
124 • QCryptoAkCipherOptionsRSA (Object)
126 • QCryptoAkCipherOptions (Object)
128 • Background jobs
130 • JobType (Enum)
132 • JobStatus (Enum)
134 • JobVerb (Enum)
136 • JOB_STATUS_CHANGE (Event)
138 • job-pause (Command)
140 • job-resume (Command)
142 • job-cancel (Command)
144 • job-complete (Command)
146 • job-dismiss (Command)
148 • job-finalize (Command)
150 • JobInfo (Object)
152 • query-jobs (Command)
154 • Block devices
156 • Block core (VM unrelated)
158 • Block device exports
160 • Character devices
162 • ChardevInfo (Object)
164 • query-chardev (Command)
166 • ChardevBackendInfo (Object)
168 • query-chardev-backends (Command)
170 • DataFormat (Enum)
172 • ringbuf-write (Command)
174 • ringbuf-read (Command)
176 • ChardevCommon (Object)
178 • ChardevFile (Object)
180 • ChardevHostdev (Object)
182 • ChardevSocket (Object)
184 • ChardevUdp (Object)
186 • ChardevMux (Object)
188 • ChardevStdio (Object)
190 • ChardevSpiceChannel (Object)
192 • ChardevSpicePort (Object)
194 • ChardevDBus (Object)
196 • ChardevVC (Object)
198 • ChardevRingbuf (Object)
200 • ChardevQemuVDAgent (Object)
202 • ChardevBackendKind (Enum)
204 • ChardevFileWrapper (Object)
206 • ChardevHostdevWrapper (Object)
208 • ChardevSocketWrapper (Object)
210 • ChardevUdpWrapper (Object)
212 • ChardevCommonWrapper (Object)
214 • ChardevMuxWrapper (Object)
216 • ChardevStdioWrapper (Object)
218 • ChardevSpiceChannelWrapper (Object)
220 • ChardevSpicePortWrapper (Object)
222 • ChardevQemuVDAgentWrapper (Object)
224 • ChardevDBusWrapper (Object)
226 • ChardevVCWrapper (Object)
228 • ChardevRingbufWrapper (Object)
230 • ChardevBackend (Object)
232 • ChardevReturn (Object)
234 • chardev-add (Command)
236 • chardev-change (Command)
238 • chardev-remove (Command)
240 • chardev-send-break (Command)
242 • VSERPORT_CHANGE (Event)
244 • User authorization
246 • QAuthZListPolicy (Enum)
248 • QAuthZListFormat (Enum)
250 • QAuthZListRule (Object)
252 • AuthZListProperties (Object)
254 • AuthZListFileProperties (Object)
256 • AuthZPAMProperties (Object)
258 • AuthZSimpleProperties (Object)
260 • Transactions
262 • Abort (Object)
264 • ActionCompletionMode (Enum)
266 • TransactionActionKind (Enum)
268 • AbortWrapper (Object)
270 • BlockDirtyBitmapAddWrapper (Object)
272 • BlockDirtyBitmapWrapper (Object)
274 • BlockDirtyBitmapMergeWrapper (Object)
276 • BlockdevBackupWrapper (Object)
278 • BlockdevSnapshotWrapper (Object)
280 • BlockdevSnapshotInternalWrapper (Object)
282 • BlockdevSnapshotSyncWrapper (Object)
284 • DriveBackupWrapper (Object)
286 • TransactionAction (Object)
288 • TransactionProperties (Object)
290 • transaction (Command)
292 • QMP monitor control
294 • qmp_capabilities (Command)
296 • QMPCapability (Enum)
298 • VersionTriple (Object)
300 • VersionInfo (Object)
302 • query-version (Command)
304 • CommandInfo (Object)
306 • query-commands (Command)
308 • quit (Command)
310 • MonitorMode (Enum)
312 • MonitorOptions (Object)
314 • QMP introspection
316 • query-qmp-schema (Command)
318 • SchemaMetaType (Enum)
320 • SchemaInfo (Object)
322 • SchemaInfoBuiltin (Object)
324 • JSONType (Enum)
326 • SchemaInfoEnum (Object)
328 • SchemaInfoEnumMember (Object)
330 • SchemaInfoArray (Object)
332 • SchemaInfoObject (Object)
334 • SchemaInfoObjectMember (Object)
336 • SchemaInfoObjectVariant (Object)
338 • SchemaInfoAlternate (Object)
340 • SchemaInfoAlternateMember (Object)
342 • SchemaInfoCommand (Object)
344 • SchemaInfoEvent (Object)
346 • QEMU Object Model (QOM)
348 • ObjectPropertyInfo (Object)
350 • qom-list (Command)
352 • qom-get (Command)
354 • qom-set (Command)
356 • ObjectTypeInfo (Object)
358 • qom-list-types (Command)
360 • qom-list-properties (Command)
362 • CanHostSocketcanProperties (Object)
364 • ColoCompareProperties (Object)
366 • CryptodevBackendProperties (Object)
368 • CryptodevVhostUserProperties (Object)
370 • DBusVMStateProperties (Object)
372 • NetfilterInsert (Enum)
374 • NetfilterProperties (Object)
376 • FilterBufferProperties (Object)
378 • FilterDumpProperties (Object)
380 • FilterMirrorProperties (Object)
382 • FilterRedirectorProperties (Object)
384 • FilterRewriterProperties (Object)
386 • InputBarrierProperties (Object)
388 • InputLinuxProperties (Object)
390 • EventLoopBaseProperties (Object)
392 • IothreadProperties (Object)
394 • MainLoopProperties (Object)
396 • MemoryBackendProperties (Object)
398 • MemoryBackendFileProperties (Object)
400 • MemoryBackendMemfdProperties (Object)
402 • MemoryBackendEpcProperties (Object)
404 • PrManagerHelperProperties (Object)
406 • QtestProperties (Object)
408 • RemoteObjectProperties (Object)
410 • VfioUserServerProperties (Object)
412 • RngProperties (Object)
414 • RngEgdProperties (Object)
416 • RngRandomProperties (Object)
418 • SevGuestProperties (Object)
420 • ThreadContextProperties (Object)
422 • ObjectType (Enum)
424 • ObjectOptions (Object)
426 • object-add (Command)
428 • object-del (Command)
430
432 IoOperationType (Enum)
433 An enumeration of the I/O operation types
434 Values
436 read read operation
437 write write operation
439 Since
441 2.1
442 OnOffAuto (Enum)
444 An enumeration of three options: on, off, and auto
445 Values
447 auto QEMU selects the value between on and off
448 on Enabled
450 off Disabled
452 Since
454 2.2
455 OnOffSplit (Enum)
457 An enumeration of three values: on, off, and split
458 Values
460 on Enabled
461 off Disabled
463 split Mixed
465 Since
467 2.6
468 String (Object)
470 A fat type wrapping 'str', to be embedded in lists.
471 Members
473 str: string
474 Not documented
475 Since
477 1.2
478 StrOrNull (Alternate)
480 This is a string value or the explicit lack of a string (null pointer
481 in C). Intended for cases when 'optional absent' already has a differ‐
482 ent meaning.
483 Members
485 s: string
486 the string value
487 n: null
489 no string value
490 Since
492 2.10
493 OffAutoPCIBAR (Enum)
495 An enumeration of options for specifying a PCI BAR
496 Values
498 off The specified feature is disabled
499 auto The PCI BAR for the feature is automatically selected
501 bar0 PCI BAR0 is used for the feature
503 bar1 PCI BAR1 is used for the feature
505 bar2 PCI BAR2 is used for the feature
507 bar3 PCI BAR3 is used for the feature
509 bar4 PCI BAR4 is used for the feature
511 bar5 PCI BAR5 is used for the feature
513 Since
515 2.12
516 PCIELinkSpeed (Enum)
518 An enumeration of PCIe link speeds in units of GT/s
519 Values
521 2_5 2.5GT/s
522 5 5.0GT/s
524 8 8.0GT/s
526 16 16.0GT/s
528 Since
530 4.0
531 PCIELinkWidth (Enum)
533 An enumeration of PCIe link width
534 Values
536 1 x1
537 2 x2
539 4 x4
541 8 x8
543 12 x12
545 16 x16
547 32 x32
549 Since
551 4.0
552 HostMemPolicy (Enum)
554 Host memory policy types
555 Values
557 default
558 restore default policy, remove any nondefault policy
559 preferred
561 set the preferred host nodes for allocation
562 bind a strict policy that restricts memory allocation to the host
564 nodes specified
565 interleave
567 memory allocations are interleaved across the set of host nodes
568 specified
569 Since
571 2.1
572 NetFilterDirection (Enum)
574 Indicates whether a netfilter is attached to a netdev's transmit queue
575 or receive queue or both.
576 Values
578 all the filter is attached both to the receive and the transmit
579 queue of the netdev (default).
580 rx the filter is attached to the receive queue of the netdev, where
582 it will receive packets sent to the netdev.
583 tx the filter is attached to the transmit queue of the netdev,
585 where it will receive packets sent by the netdev.
586 Since
588 2.5
589 GrabToggleKeys (Enum)
591 Keys to toggle input-linux between host and guest.
592 Values
594 ctrl-ctrl
595 Not documented
596 alt-alt
598 Not documented
599 shift-shift
601 Not documented
602 meta-meta
604 Not documented
605 scrolllock
607 Not documented
608 ctrl-scrolllock
610 Not documented
611 Since
613 4.0
614 HumanReadableText (Object)
616 Members
617 human-readable-text: string
618 Formatted output intended for humans.
619 Since
621 6.2
622
624 NetworkAddressFamily (Enum)
625 The network address family
626 Values
628 ipv4 IPV4 family
629 ipv6 IPV6 family
631 unix unix socket
633 vsock vsock family (since 2.8)
635 unknown
637 otherwise
638 Since
640 2.1
641 InetSocketAddressBase (Object)
643 Members
644 host: string
645 host part of the address
646 port: string
648 port part of the address
649 InetSocketAddress (Object)
651 Captures a socket address or address range in the Internet namespace.
652 Members
654 numeric: boolean (optional)
655 true if the host/port are guaranteed to be numeric, false if
656 name resolution should be attempted. Defaults to false. (Since
657 2.9)
658 to: int (optional)
660 If present, this is range of possible addresses, with port be‐
661 tween port and to.
662 ipv4: boolean (optional)
664 whether to accept IPv4 addresses, default try both IPv4 and IPv6
665 ipv6: boolean (optional)
667 whether to accept IPv6 addresses, default try both IPv4 and IPv6
668 keep-alive: boolean (optional)
670 enable keep-alive when connecting to this socket. Not supported
671 for passive sockets. (Since 4.2)
672 mptcp: boolean (optional) (If: HAVE_IPPROTO_MPTCP)
674 enable multi-path TCP. (Since 6.1)
675 The members of InetSocketAddressBase
677 Since
679 1.3
680 UnixSocketAddress (Object)
682 Captures a socket address in the local ("Unix socket") namespace.
683 Members
685 path: string
686 filesystem path to use
687 abstract: boolean (optional) (If: CONFIG_LINUX)
689 if true, this is a Linux abstract socket address. path will be
690 prefixed by a null byte, and optionally padded with null bytes.
691 Defaults to false. (Since 5.1)
692 tight: boolean (optional) (If: CONFIG_LINUX)
694 if false, pad an abstract socket address with enough null bytes
695 to make it fill struct sockaddr_un member sun_path. Defaults to
696 true. (Since 5.1)
697 Since
699 1.3
700 VsockSocketAddress (Object)
702 Captures a socket address in the vsock namespace.
703 Members
705 cid: string
706 unique host identifier
707 port: string
709 port
710 Note
712 string types are used to allow for possible future hostname or service
713 resolution support.
714 Since
716 2.8
717 InetSocketAddressWrapper (Object)
719 Members
720 data: InetSocketAddress
721 Not documented
722 Since
724 1.3
725 UnixSocketAddressWrapper (Object)
727 Members
728 data: UnixSocketAddress
729 Not documented
730 Since
732 1.3
733 VsockSocketAddressWrapper (Object)
735 Members
736 data: VsockSocketAddress
737 Not documented
738 Since
740 2.8
741 StringWrapper (Object)
743 Members
744 data: String
745 Not documented
746 Since
748 1.3
749 SocketAddressLegacy (Object)
751 Captures the address of a socket, which could also be a named file de‐
752 scriptor
753 Members
755 type: SocketAddressType
756 Not documented
757 The members of InetSocketAddressWrapper when type is "inet"
759 The members of UnixSocketAddressWrapper when type is "unix"
761 The members of VsockSocketAddressWrapper when type is "vsock"
763 The members of StringWrapper when type is "fd"
765 Note
767 This type is deprecated in favor of SocketAddress. The difference be‐
768 tween SocketAddressLegacy and SocketAddress is that the latter has
769 fewer {} on the wire.
770 Since
772 1.3
773 SocketAddressType (Enum)
775 Available SocketAddress types
776 Values
778 inet Internet address
779 unix Unix domain socket
781 vsock VMCI address
783 fd decimal is for file descriptor number, otherwise a file descrip‐
785 tor name. Named file descriptors are permitted in monitor com‐
786 mands, in combination with the 'getfd' command. Decimal file
787 descriptors are permitted at startup or other contexts where no
788 monitor context is active.
789 Since
791 2.9
792 SocketAddress (Object)
794 Captures the address of a socket, which could also be a named file de‐
795 scriptor
796 Members
798 type: SocketAddressType
799 Transport type
800 The members of InetSocketAddress when type is "inet"
802 The members of UnixSocketAddress when type is "unix"
804 The members of VsockSocketAddress when type is "vsock"
806 The members of String when type is "fd"
808 Since
810 2.9
811
813 QCryptoTLSCredsEndpoint (Enum)
814 The type of network endpoint that will be using the credentials. Most
815 types of credential require different setup / structures depending on
816 whether they will be used in a server versus a client.
817 Values
819 client the network endpoint is acting as the client
820 server the network endpoint is acting as the server
822 Since
824 2.5
825 QCryptoSecretFormat (Enum)
827 The data format that the secret is provided in
828 Values
830 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
831 be used
832 base64 arbitrary base64 encoded binary data
834 Since
836 2.6
837 QCryptoHashAlgorithm (Enum)
839 The supported algorithms for computing content digests
840 Values
842 md5 MD5. Should not be used in any new code, legacy compat only
843 sha1 SHA-1. Should not be used in any new code, legacy compat only
845 sha224 SHA-224. (since 2.7)
847 sha256 SHA-256. Current recommended strong hash.
849 sha384 SHA-384. (since 2.7)
851 sha512 SHA-512. (since 2.7)
853 ripemd160
855 RIPEMD-160. (since 2.7)
856 Since
858 2.6
859 QCryptoCipherAlgorithm (Enum)
861 The supported algorithms for content encryption ciphers
862 Values
864 aes-128
865 AES with 128 bit / 16 byte keys
866 aes-192
868 AES with 192 bit / 24 byte keys
869 aes-256
871 AES with 256 bit / 32 byte keys
872 des DES with 56 bit / 8 byte keys. Do not use except in VNC.
874 (since 6.1)
875 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
877 cast5-128
879 Cast5 with 128 bit / 16 byte keys
880 serpent-128
882 Serpent with 128 bit / 16 byte keys
883 serpent-192
885 Serpent with 192 bit / 24 byte keys
886 serpent-256
888 Serpent with 256 bit / 32 byte keys
889 twofish-128
891 Twofish with 128 bit / 16 byte keys
892 twofish-192
894 Twofish with 192 bit / 24 byte keys
895 twofish-256
897 Twofish with 256 bit / 32 byte keys
898 Since
900 2.6
901 QCryptoCipherMode (Enum)
903 The supported modes for content encryption ciphers
904 Values
906 ecb Electronic Code Book
907 cbc Cipher Block Chaining
909 xts XEX with tweaked code book and ciphertext stealing
911 ctr Counter (Since 2.8)
913 Since
915 2.6
916 QCryptoIVGenAlgorithm (Enum)
918 The supported algorithms for generating initialization vectors for full
919 disk encryption. The 'plain' generator should not be used for disks
920 with sector numbers larger than 2^32, except where compatibility with
921 pre-existing Linux dm-crypt volumes is required.
922 Values
924 plain 64-bit sector number truncated to 32-bits
925 plain64
927 64-bit sector number
928 essiv 64-bit sector number encrypted with a hash of the encryption key
930 Since
932 2.6
933 QCryptoBlockFormat (Enum)
935 The supported full disk encryption formats
936 Values
938 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
939 data from old images.
940 luks LUKS encryption format. Recommended for new images
942 Since
944 2.6
945 QCryptoBlockOptionsBase (Object)
947 The common options that apply to all full disk encryption formats
948 Members
950 format: QCryptoBlockFormat
951 the encryption format
952 Since
954 2.6
955 QCryptoBlockOptionsQCow (Object)
957 The options that apply to QCow/QCow2 AES-CBC encryption format
958 Members
960 key-secret: string (optional)
961 the ID of a QCryptoSecret object providing the decryption key.
962 Mandatory except when probing image for metadata only.
963 Since
965 2.6
966 QCryptoBlockOptionsLUKS (Object)
968 The options that apply to LUKS encryption format
969 Members
971 key-secret: string (optional)
972 the ID of a QCryptoSecret object providing the decryption key.
973 Mandatory except when probing image for metadata only.
974 Since
976 2.6
977 QCryptoBlockCreateOptionsLUKS (Object)
979 The options that apply to LUKS encryption format initialization
980 Members
982 cipher-alg: QCryptoCipherAlgorithm (optional)
983 the cipher algorithm for data encryption Currently defaults to
984 'aes-256'.
985 cipher-mode: QCryptoCipherMode (optional)
987 the cipher mode for data encryption Currently defaults to 'xts'
988 ivgen-alg: QCryptoIVGenAlgorithm (optional)
990 the initialization vector generator Currently defaults to
991 'plain64'
992 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
994 the initialization vector generator hash Currently defaults to
995 'sha256'
996 hash-alg: QCryptoHashAlgorithm (optional)
998 the master key hash algorithm Currently defaults to 'sha256'
999 iter-time: int (optional)
1001 number of milliseconds to spend in PBKDF passphrase processing.
1002 Currently defaults to 2000. (since 2.8)
1003 The members of QCryptoBlockOptionsLUKS
1005 Since
1007 2.6
1008 QCryptoBlockOpenOptions (Object)
1010 The options that are available for all encryption formats when opening
1011 an existing volume
1012 Members
1014 The members of QCryptoBlockOptionsBase
1015 The members of QCryptoBlockOptionsQCow when format is "qcow"
1017 The members of QCryptoBlockOptionsLUKS when format is "luks"
1019 Since
1021 2.6
1022 QCryptoBlockCreateOptions (Object)
1024 The options that are available for all encryption formats when initial‐
1025 izing a new volume
1026 Members
1028 The members of QCryptoBlockOptionsBase
1029 The members of QCryptoBlockOptionsQCow when format is "qcow"
1031 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
1033 Since
1035 2.6
1036 QCryptoBlockInfoBase (Object)
1038 The common information that applies to all full disk encryption formats
1039 Members
1041 format: QCryptoBlockFormat
1042 the encryption format
1043 Since
1045 2.7
1046 QCryptoBlockInfoLUKSSlot (Object)
1048 Information about the LUKS block encryption key slot options
1049 Members
1051 active: boolean
1052 whether the key slot is currently in use
1053 key-offset: int
1055 offset to the key material in bytes
1056 iters: int (optional)
1058 number of PBKDF2 iterations for key material
1059 stripes: int (optional)
1061 number of stripes for splitting key material
1062 Since
1064 2.7
1065 QCryptoBlockInfoLUKS (Object)
1067 Information about the LUKS block encryption options
1068 Members
1070 cipher-alg: QCryptoCipherAlgorithm
1071 the cipher algorithm for data encryption
1072 cipher-mode: QCryptoCipherMode
1074 the cipher mode for data encryption
1075 ivgen-alg: QCryptoIVGenAlgorithm
1077 the initialization vector generator
1078 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1080 the initialization vector generator hash
1081 hash-alg: QCryptoHashAlgorithm
1083 the master key hash algorithm
1084 payload-offset: int
1086 offset to the payload data in bytes
1087 master-key-iters: int
1089 number of PBKDF2 iterations for key material
1090 uuid: string
1092 unique identifier for the volume
1093 slots: array of QCryptoBlockInfoLUKSSlot
1095 information about each key slot
1096 Since
1098 2.7
1099 QCryptoBlockInfo (Object)
1101 Information about the block encryption options
1102 Members
1104 The members of QCryptoBlockInfoBase
1105 The members of QCryptoBlockInfoLUKS when format is "luks"
1107 Since
1109 2.7
1110 QCryptoBlockLUKSKeyslotState (Enum)
1112 Defines state of keyslots that are affected by the update
1113 Values
1115 active The slots contain the given password and marked as active
1116 inactive
1118 The slots are erased (contain garbage) and marked as inactive
1119 Since
1121 5.1
1122 QCryptoBlockAmendOptionsLUKS (Object)
1124 This struct defines the update parameters that activate/de-activate set
1125 of keyslots
1126 Members
1128 state: QCryptoBlockLUKSKeyslotState
1129 the desired state of the keyslots
1130 new-secret: string (optional)
1132 The ID of a QCryptoSecret object providing the password to be
1133 written into added active keyslots
1134 old-secret: string (optional)
1136 Optional (for deactivation only) If given will deactivate all
1137 keyslots that match password located in QCryptoSecret with this
1138 ID
1139 iter-time: int (optional)
1141 Optional (for activation only) Number of milliseconds to spend
1142 in PBKDF passphrase processing for the newly activated keyslot.
1143 Currently defaults to 2000.
1144 keyslot: int (optional)
1146 Optional. ID of the keyslot to activate/deactivate. For
1147 keyslot activation, keyslot should not be active already (this
1148 is unsafe to update an active keyslot), but possible if 'force'
1149 parameter is given. If keyslot is not given, first free keyslot
1150 will be written.
1151 For keyslot deactivation, this parameter specifies the exact
1153 keyslot to deactivate
1154 secret: string (optional)
1156 Optional. The ID of a QCryptoSecret object providing the pass‐
1157 word to use to retrieve current master key. Defaults to the
1158 same secret that was used to open the image
1159 Since
1161 5.1
1162 QCryptoBlockAmendOptions (Object)
1164 The options that are available for all encryption formats when amending
1165 encryption settings
1166 Members
1168 The members of QCryptoBlockOptionsBase
1169 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
1171 Since
1173 5.1
1174 SecretCommonProperties (Object)
1176 Properties for objects of classes derived from secret-common.
1177 Members
1179 loaded: boolean (optional)
1180 if true, the secret is loaded immediately when applying this op‐
1181 tion and will probably fail when processing the next option.
1182 Don't use; only provided for compatibility. (default: false)
1183 format: QCryptoSecretFormat (optional)
1185 the data format that the secret is provided in (default: raw)
1186 keyid: string (optional)
1188 the name of another secret that should be used to decrypt the
1189 provided data. If not present, the data is assumed to be unen‐
1190 crypted.
1191 iv: string (optional)
1193 the random initialization vector used for encryption of this
1194 particular secret. Should be a base64 encrypted string of the
1195 16-byte IV. Mandatory if keyid is given. Ignored if keyid is
1196 absent.
1197 Features
1199 deprecated
1200 Member loaded is deprecated. Setting true doesn't make sense,
1201 and false is already the default.
1202 Since
1204 2.6
1205 SecretProperties (Object)
1207 Properties for secret objects.
1208 Either data or file must be provided, but not both.
1210 Members
1212 data: string (optional)
1213 the associated with the secret from
1214 file: string (optional)
1216 the filename to load the data associated with the secret from
1217 The members of SecretCommonProperties
1219 Since
1221 2.6
1222 SecretKeyringProperties (Object)
1224 Properties for secret_keyring objects.
1225 Members
1227 serial: int
1228 serial number that identifies a key to get from the kernel
1229 The members of SecretCommonProperties
1231 Since
1233 5.1
1234 TlsCredsProperties (Object)
1236 Properties for objects of classes derived from tls-creds.
1237 Members
1239 verify-peer: boolean (optional)
1240 if true the peer credentials will be verified once the handshake
1241 is completed. This is a no-op for anonymous credentials. (de‐
1242 fault: true)
1243 dir: string (optional)
1245 the path of the directory that contains the credential files
1246 endpoint: QCryptoTLSCredsEndpoint (optional)
1248 whether the QEMU network backend that uses the credentials will
1249 be acting as a client or as a server (default: client)
1250 priority: string (optional)
1252 a gnutls priority string as described at
1253 https://gnutls.org/manual/html_node/Priority-Strings.html
1254 Since
1256 2.5
1257 TlsCredsAnonProperties (Object)
1259 Properties for tls-creds-anon objects.
1260 Members
1262 loaded: boolean (optional)
1263 if true, the credentials are loaded immediately when applying
1264 this option and will ignore options that are processed later.
1265 Don't use; only provided for compatibility. (default: false)
1266 The members of TlsCredsProperties
1268 Features
1270 deprecated
1271 Member loaded is deprecated. Setting true doesn't make sense,
1272 and false is already the default.
1273 Since
1275 2.5
1276 TlsCredsPskProperties (Object)
1278 Properties for tls-creds-psk objects.
1279 Members
1281 loaded: boolean (optional)
1282 if true, the credentials are loaded immediately when applying
1283 this option and will ignore options that are processed later.
1284 Don't use; only provided for compatibility. (default: false)
1285 username: string (optional)
1287 the username which will be sent to the server. For clients
1288 only. If absent, "qemu" is sent and the property will read back
1289 as an empty string.
1290 The members of TlsCredsProperties
1292 Features
1294 deprecated
1295 Member loaded is deprecated. Setting true doesn't make sense,
1296 and false is already the default.
1297 Since
1299 3.0
1300 TlsCredsX509Properties (Object)
1302 Properties for tls-creds-x509 objects.
1303 Members
1305 loaded: boolean (optional)
1306 if true, the credentials are loaded immediately when applying
1307 this option and will ignore options that are processed later.
1308 Don't use; only provided for compatibility. (default: false)
1309 sanity-check: boolean (optional)
1311 if true, perform some sanity checks before using the credentials
1312 (default: true)
1313 passwordid: string (optional)
1315 For the server-key.pem and client-key.pem files which contain
1316 sensitive private keys, it is possible to use an encrypted ver‐
1317 sion by providing the passwordid parameter. This provides the
1318 ID of a previously created secret object containing the password
1319 for decryption.
1320 The members of TlsCredsProperties
1322 Features
1324 deprecated
1325 Member loaded is deprecated. Setting true doesn't make sense,
1326 and false is already the default.
1327 Since
1329 2.5
1330 QCryptoAkCipherAlgorithm (Enum)
1332 The supported algorithms for asymmetric encryption ciphers
1333 Values
1335 rsa RSA algorithm
1336 Since
1338 7.1
1339 QCryptoAkCipherKeyType (Enum)
1341 The type of asymmetric keys.
1342 Values
1344 public Not documented
1345 private
1347 Not documented
1348 Since
1350 7.1
1351 QCryptoRSAPaddingAlgorithm (Enum)
1353 The padding algorithm for RSA.
1354 Values
1356 raw no padding used
1357 pkcs1 pkcs1#v1.5
1359 Since
1361 7.1
1362 QCryptoAkCipherOptionsRSA (Object)
1364 Specific parameters for RSA algorithm.
1365 Members
1367 hash-alg: QCryptoHashAlgorithm
1368 QCryptoHashAlgorithm
1369 padding-alg: QCryptoRSAPaddingAlgorithm
1371 QCryptoRSAPaddingAlgorithm
1372 Since
1374 7.1
1375 QCryptoAkCipherOptions (Object)
1377 The options that are available for all asymmetric key algorithms when
1378 creating a new QCryptoAkCipher.
1379 Members
1381 alg: QCryptoAkCipherAlgorithm
1382 Not documented
1383 The members of QCryptoAkCipherOptionsRSA when alg is "rsa"
1385 Since
1387 7.1
1388
1390 JobType (Enum)
1391 Type of a background job.
1392 Values
1394 commit block commit job type, see "block-commit"
1395 stream block stream job type, see "block-stream"
1397 mirror drive mirror job type, see "drive-mirror"
1399 backup drive backup job type, see "drive-backup"
1401 create image creation job type, see "blockdev-create" (since 3.0)
1403 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
1405 snapshot-load
1407 snapshot load job type, see "snapshot-load" (since 6.0)
1408 snapshot-save
1410 snapshot save job type, see "snapshot-save" (since 6.0)
1411 snapshot-delete
1413 snapshot delete job type, see "snapshot-delete" (since 6.0)
1414 Since
1416 1.7
1417 JobStatus (Enum)
1419 Indicates the present state of a given job in its lifetime.
1420 Values
1422 undefined
1423 Erroneous, default state. Should not ever be visible.
1424 created
1426 The job has been created, but not yet started.
1427 running
1429 The job is currently running.
1430 paused The job is running, but paused. The pause may be requested by
1432 either the QMP user or by internal processes.
1433 ready The job is running, but is ready for the user to signal comple‐
1435 tion. This is used for long-running jobs like mirror that are
1436 designed to run indefinitely.
1437 standby
1439 The job is ready, but paused. This is nearly identical to
1440 paused. The job may return to ready or otherwise be canceled.
1441 waiting
1443 The job is waiting for other jobs in the transaction to converge
1444 to the waiting state. This status will likely not be visible
1445 for the last job in a transaction.
1446 pending
1448 The job has finished its work, but has finalization steps that
1449 it needs to make prior to completing. These changes will re‐
1450 quire manual intervention via job-finalize if auto-finalize was
1451 set to false. These pending changes may still fail.
1452 aborting
1454 The job is in the process of being aborted, and will finish with
1455 an error. The job will afterwards report that it is concluded.
1456 This status may not be visible to the management process.
1457 concluded
1459 The job has finished all work. If auto-dismiss was set to
1460 false, the job will remain in the query list until it is dis‐
1461 missed via job-dismiss.
1462 null The job is in the process of being dismantled. This state
1464 should not ever be visible externally.
1465 Since
1467 2.12
1468 JobVerb (Enum)
1470 Represents command verbs that can be applied to a job.
1471 Values
1473 cancel see job-cancel
1474 pause see job-pause
1476 resume see job-resume
1478 set-speed
1480 see block-job-set-speed
1481 complete
1483 see job-complete
1484 dismiss
1486 see job-dismiss
1487 finalize
1489 see job-finalize
1490 Since
1492 2.12
1493 JOB_STATUS_CHANGE (Event)
1495 Emitted when a job transitions to a different status.
1496 Arguments
1498 id: string
1499 The job identifier
1500 status: JobStatus
1502 The new job status
1503 Since
1505 3.0
1506 job-pause (Command)
1508 Pause an active job.
1509 This command returns immediately after marking the active job for paus‐
1511 ing. Pausing an already paused job is an error.
1512 The job will pause as soon as possible, which means transitioning into
1514 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
1515 The corresponding JOB_STATUS_CHANGE event will be emitted.
1516 Cancelling a paused job automatically resumes it.
1518 Arguments
1520 id: string
1521 The job identifier.
1522 Since
1524 3.0
1525 job-resume (Command)
1527 Resume a paused job.
1528 This command returns immediately after resuming a paused job. Resuming
1530 an already running job is an error.
1531 Arguments
1533 id: string
1534 The job identifier.
1535 Since
1537 3.0
1538 job-cancel (Command)
1540 Instruct an active background job to cancel at the next opportunity.
1541 This command returns immediately after marking the active job for can‐
1542 cellation.
1543 The job will cancel as soon as possible and then emit a JOB_STA‐
1545 TUS_CHANGE event. Usually, the status will change to ABORTING, but it
1546 is possible that a job successfully completes (e.g. because it was al‐
1547 most done and there was no opportunity to cancel earlier than complet‐
1548 ing the job) and transitions to PENDING instead.
1549 Arguments
1551 id: string
1552 The job identifier.
1553 Since
1555 3.0
1556 job-complete (Command)
1558 Manually trigger completion of an active job in the READY state.
1559 Arguments
1561 id: string
1562 The job identifier.
1563 Since
1565 3.0
1566 job-dismiss (Command)
1568 Deletes a job that is in the CONCLUDED state. This command only needs
1569 to be run explicitly for jobs that don't have automatic dismiss en‐
1570 abled.
1571 This command will refuse to operate on any job that has not yet reached
1573 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
1574 JOB_READY event, job-cancel or job-complete will still need to be used
1575 as appropriate.
1576 Arguments
1578 id: string
1579 The job identifier.
1580 Since
1582 3.0
1583 job-finalize (Command)
1585 Instructs all jobs in a transaction (or a single job if it is not part
1586 of any transaction) to finalize any graph changes and do any necessary
1587 cleanup. This command requires that all involved jobs are in the PEND‐
1588 ING state.
1589 For jobs in a transaction, instructing one job to finalize will force
1591 ALL jobs in the transaction to finalize, so it is only necessary to in‐
1592 struct a single member job to finalize.
1593 Arguments
1595 id: string
1596 The identifier of any job in the transaction, or of a job that
1597 is not part of any transaction.
1598 Since
1600 3.0
1601 JobInfo (Object)
1603 Information about a job.
1604 Members
1606 id: string
1607 The job identifier
1608 type: JobType
1610 The kind of job that is being performed
1611 status: JobStatus
1613 Current job state/status
1614 current-progress: int
1616 Progress made until now. The unit is arbitrary and the value
1617 can only meaningfully be used for the ratio of current-progress
1618 to total-progress. The value is monotonically increasing.
1619 total-progress: int
1621 Estimated current-progress value at the completion of the job.
1622 This value can arbitrarily change while the job is running, in
1623 both directions.
1624 error: string (optional)
1626 If this field is present, the job failed; if it is still missing
1627 in the CONCLUDED state, this indicates successful completion.
1628 The value is a human-readable error message to describe the rea‐
1630 son for the job failure. It should not be parsed by applica‐
1631 tions.
1632 Since
1634 3.0
1635 query-jobs (Command)
1637 Return information about jobs.
1638 Returns
1640 a list with a JobInfo for each active job
1641 Since
1643 3.0
1644
1646 Block core (VM unrelated)
1647 SnapshotInfo (Object)
1648 Members
1649 id: string
1650 unique snapshot id
1651 name: string
1653 user chosen name
1654 vm-state-size: int
1656 size of the VM state
1657 date-sec: int
1659 UTC date of the snapshot in seconds
1660 date-nsec: int
1662 fractional part in nano seconds to be used with date-sec
1663 vm-clock-sec: int
1665 VM clock relative to boot in seconds
1666 vm-clock-nsec: int
1668 fractional part in nano seconds to be used with vm-clock-sec
1669 icount: int (optional)
1671 Current instruction count. Appears when execution record/replay
1672 is enabled. Used for "time-traveling" to match the moment in
1673 the recorded execution with the snapshots. This counter may be
1674 obtained through query-replay command (since 5.2)
1675 Since
1677 1.3
1678 ImageInfoSpecificQCow2EncryptionBase (Object)
1680 Members
1681 format: BlockdevQcow2EncryptionFormat
1682 The encryption format
1683 Since
1685 2.10
1686 ImageInfoSpecificQCow2Encryption (Object)
1688 Members
1689 The members of ImageInfoSpecificQCow2EncryptionBase
1690 The members of QCryptoBlockInfoLUKS when format is "luks"
1692 Since
1694 2.10
1695 ImageInfoSpecificQCow2 (Object)
1697 Members
1698 compat: string
1699 compatibility level
1700 data-file: string (optional)
1702 the filename of the external data file that is stored in the im‐
1703 age and used as a default for opening the image (since: 4.0)
1704 data-file-raw: boolean (optional)
1706 True if the external data file must stay valid as a standalone
1707 (read-only) raw image without looking at qcow2 metadata (since:
1708 4.0)
1709 extended-l2: boolean (optional)
1711 true if the image has extended L2 entries; only valid for compat
1712 >= 1.1 (since 5.2)
1713 lazy-refcounts: boolean (optional)
1715 on or off; only valid for compat >= 1.1
1716 corrupt: boolean (optional)
1718 true if the image has been marked corrupt; only valid for compat
1719 >= 1.1 (since 2.2)
1720 refcount-bits: int
1722 width of a refcount entry in bits (since 2.3)
1723 encrypt: ImageInfoSpecificQCow2Encryption (optional)
1725 details about encryption parameters; only set if image is en‐
1726 crypted (since 2.10)
1727 bitmaps: array of Qcow2BitmapInfo (optional)
1729 A list of qcow2 bitmap details (since 4.0)
1730 compression-type: Qcow2CompressionType
1732 the image cluster compression method (since 5.1)
1733 Since
1735 1.7
1736 ImageInfoSpecificVmdk (Object)
1738 Members
1739 create-type: string
1740 The create type of VMDK image
1741 cid: int
1743 Content id of image
1744 parent-cid: int
1746 Parent VMDK image's cid
1747 extents: array of VmdkExtentInfo
1749 List of extent files
1750 Since
1752 1.7
1753 VmdkExtentInfo (Object)
1755 Information about a VMDK extent file
1756 Members
1758 filename: string
1759 Name of the extent file
1760 format: string
1762 Extent type (e.g. FLAT or SPARSE)
1763 virtual-size: int
1765 Number of bytes covered by this extent
1766 cluster-size: int (optional)
1768 Cluster size in bytes (for non-flat extents)
1769 compressed: boolean (optional)
1771 Whether this extent contains compressed data
1772 Since
1774 8.0
1775 ImageInfoSpecificRbd (Object)
1777 Members
1778 encryption-format: RbdImageEncryptionFormat (optional)
1779 Image encryption format
1780 Since
1782 6.1
1783 ImageInfoSpecificFile (Object)
1785 Members
1786 extent-size-hint: int (optional)
1787 Extent size hint (if available)
1788 Since
1790 8.0
1791 ImageInfoSpecificKind (Enum)
1793 Values
1794 luks Since 2.7
1795 rbd Since 6.1
1797 file Since 8.0
1799 qcow2 Not documented
1801 vmdk Not documented
1803 Since
1805 1.7
1806 ImageInfoSpecificQCow2Wrapper (Object)
1808 Members
1809 data: ImageInfoSpecificQCow2
1810 Not documented
1811 Since
1813 1.7
1814 ImageInfoSpecificVmdkWrapper (Object)
1816 Members
1817 data: ImageInfoSpecificVmdk
1818 Not documented
1819 Since
1821 6.1
1822 ImageInfoSpecificLUKSWrapper (Object)
1824 Members
1825 data: QCryptoBlockInfoLUKS
1826 Not documented
1827 Since
1829 2.7
1830 ImageInfoSpecificRbdWrapper (Object)
1832 Members
1833 data: ImageInfoSpecificRbd
1834 Not documented
1835 Since
1837 6.1
1838 ImageInfoSpecificFileWrapper (Object)
1840 Members
1841 data: ImageInfoSpecificFile
1842 Not documented
1843 Since
1845 8.0
1846 ImageInfoSpecific (Object)
1848 A discriminated record of image format specific information structures.
1849 Members
1851 type: ImageInfoSpecificKind
1852 Not documented
1853 The members of ImageInfoSpecificQCow2Wrapper when type is "qcow2"
1855 The members of ImageInfoSpecificVmdkWrapper when type is "vmdk"
1857 The members of ImageInfoSpecificLUKSWrapper when type is "luks"
1859 The members of ImageInfoSpecificRbdWrapper when type is "rbd"
1861 The members of ImageInfoSpecificFileWrapper when type is "file"
1863 Since
1865 1.7
1866 BlockNodeInfo (Object)
1868 Information about a QEMU image file
1869 Members
1871 filename: string
1872 name of the image file
1873 format: string
1875 format of the image file
1876 virtual-size: int
1878 maximum capacity in bytes of the image
1879 actual-size: int (optional)
1881 actual size on disk in bytes of the image
1882 dirty-flag: boolean (optional)
1884 true if image is not cleanly closed
1885 cluster-size: int (optional)
1887 size of a cluster in bytes
1888 encrypted: boolean (optional)
1890 true if the image is encrypted
1891 compressed: boolean (optional)
1893 true if the image is compressed (Since 1.7)
1894 backing-filename: string (optional)
1896 name of the backing file
1897 full-backing-filename: string (optional)
1899 full path of the backing file
1900 backing-filename-format: string (optional)
1902 the format of the backing file
1903 snapshots: array of SnapshotInfo (optional)
1905 list of VM snapshots
1906 format-specific: ImageInfoSpecific (optional)
1908 structure supplying additional format-specific information
1909 (since 1.7)
1910 Since
1912 8.0
1913 ImageInfo (Object)
1915 Information about a QEMU image file, and potentially its backing image
1916 Members
1918 backing-image: ImageInfo (optional)
1919 info of the backing image
1920 The members of BlockNodeInfo
1922 Since
1924 1.3
1925 BlockChildInfo (Object)
1927 Information about all nodes in the block graph starting at some node,
1928 annotated with information about that node in relation to its parent.
1929 Members
1931 name: string
1932 Child name of the root node in the BlockGraphInfo struct, in its
1933 role as the child of some undescribed parent node
1934 info: BlockGraphInfo
1936 Block graph information starting at this node
1937 Since
1939 8.0
1940 BlockGraphInfo (Object)
1942 Information about all nodes in a block (sub)graph in the form of Bloc‐
1943 kNodeInfo data. The base BlockNodeInfo struct contains the information
1944 for the (sub)graph's root node.
1945 Members
1947 children: array of BlockChildInfo
1948 Array of links to this node's child nodes' information
1949 The members of BlockNodeInfo
1951 Since
1953 8.0
1954 ImageCheck (Object)
1956 Information about a QEMU image file check
1957 Members
1959 filename: string
1960 name of the image file checked
1961 format: string
1963 format of the image file checked
1964 check-errors: int
1966 number of unexpected errors occurred during check
1967 image-end-offset: int (optional)
1969 offset (in bytes) where the image ends, this field is present if
1970 the driver for the image format supports it
1971 corruptions: int (optional)
1973 number of corruptions found during the check if any
1974 leaks: int (optional)
1976 number of leaks found during the check if any
1977 corruptions-fixed: int (optional)
1979 number of corruptions fixed during the check if any
1980 leaks-fixed: int (optional)
1982 number of leaks fixed during the check if any
1983 total-clusters: int (optional)
1985 total number of clusters, this field is present if the driver
1986 for the image format supports it
1987 allocated-clusters: int (optional)
1989 total number of allocated clusters, this field is present if the
1990 driver for the image format supports it
1991 fragmented-clusters: int (optional)
1993 total number of fragmented clusters, this field is present if
1994 the driver for the image format supports it
1995 compressed-clusters: int (optional)
1997 total number of compressed clusters, this field is present if
1998 the driver for the image format supports it
1999 Since
2001 1.4
2002 MapEntry (Object)
2004 Mapping information from a virtual block range to a host file range
2005 Members
2007 start: int
2008 virtual (guest) offset of the first byte described by this entry
2009 length: int
2011 the number of bytes of the mapped virtual range
2012 data: boolean
2014 reading the image will actually read data from a file (in par‐
2015 ticular, if offset is present this means that the sectors are
2016 not simply preallocated, but contain actual data in raw format)
2017 zero: boolean
2019 whether the virtual blocks read as zeroes
2020 depth: int
2022 number of layers (0 = top image, 1 = top image's backing file,
2023 ..., n - 1 = bottom image (where n is the number of images in
2024 the chain)) before reaching one for which the range is allocated
2025 present: boolean
2027 true if this layer provides the data, false if adding a backing
2028 layer could impact this region (since 6.1)
2029 offset: int (optional)
2031 if present, the image file stores the data for this range in raw
2032 format at the given (host) offset
2033 filename: string (optional)
2035 filename that is referred to by offset
2036 Since
2038 2.6
2039 BlockdevCacheInfo (Object)
2041 Cache mode information for a block device
2042 Members
2044 writeback: boolean
2045 true if writeback mode is enabled
2046 direct: boolean
2048 true if the host page cache is bypassed (O_DIRECT)
2049 no-flush: boolean
2051 true if flush requests are ignored for the device
2052 Since
2054 2.3
2055 BlockDeviceInfo (Object)
2057 Information about the backing device for a block device.
2058 Members
2060 file: string
2061 the filename of the backing device
2062 node-name: string (optional)
2064 the name of the block driver node (Since 2.0)
2065 ro: boolean
2067 true if the backing device was open read-only
2068 drv: string
2070 the name of the block format used to open the backing device.
2071 As of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow',
2072 'dmg', 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_de‐
2073 vice', 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow',
2074 'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago'
2075 added, 'cow' dropped 2.3: 'host_floppy' deprecated 2.5:
2076 'host_floppy' dropped 2.6: 'luks' added 2.8: 'replication'
2077 added, 'tftp' dropped 2.9: 'archipelago' dropped
2078 backing_file: string (optional)
2080 the name of the backing file (for copy-on-write)
2081 backing_file_depth: int
2083 number of files in the backing file chain (since: 1.2)
2084 encrypted: boolean
2086 true if the backing device is encrypted
2087 detect_zeroes: BlockdevDetectZeroesOptions
2089 detect and optimize zero writes (Since 2.1)
2090 bps: int
2092 total throughput limit in bytes per second is specified
2093 bps_rd: int
2095 read throughput limit in bytes per second is specified
2096 bps_wr: int
2098 write throughput limit in bytes per second is specified
2099 iops: int
2101 total I/O operations per second is specified
2102 iops_rd: int
2104 read I/O operations per second is specified
2105 iops_wr: int
2107 write I/O operations per second is specified
2108 image: ImageInfo
2110 the info of image used (since: 1.6)
2111 bps_max: int (optional)
2113 total throughput limit during bursts, in bytes (Since 1.7)
2114 bps_rd_max: int (optional)
2116 read throughput limit during bursts, in bytes (Since 1.7)
2117 bps_wr_max: int (optional)
2119 write throughput limit during bursts, in bytes (Since 1.7)
2120 iops_max: int (optional)
2122 total I/O operations per second during bursts, in bytes (Since
2123 1.7)
2124 iops_rd_max: int (optional)
2126 read I/O operations per second during bursts, in bytes (Since
2127 1.7)
2128 iops_wr_max: int (optional)
2130 write I/O operations per second during bursts, in bytes (Since
2131 1.7)
2132 bps_max_length: int (optional)
2134 maximum length of the bps_max burst period, in seconds. (Since
2135 2.6)
2136 bps_rd_max_length: int (optional)
2138 maximum length of the bps_rd_max burst period, in seconds.
2139 (Since 2.6)
2140 bps_wr_max_length: int (optional)
2142 maximum length of the bps_wr_max burst period, in seconds.
2143 (Since 2.6)
2144 iops_max_length: int (optional)
2146 maximum length of the iops burst period, in seconds. (Since
2147 2.6)
2148 iops_rd_max_length: int (optional)
2150 maximum length of the iops_rd_max burst period, in seconds.
2151 (Since 2.6)
2152 iops_wr_max_length: int (optional)
2154 maximum length of the iops_wr_max burst period, in seconds.
2155 (Since 2.6)
2156 iops_size: int (optional)
2158 an I/O size in bytes (Since 1.7)
2159 group: string (optional)
2161 throttle group name (Since 2.4)
2162 cache: BlockdevCacheInfo
2164 the cache mode used for the block device (since: 2.3)
2165 write_threshold: int
2167 configured write threshold for the device. 0 if disabled.
2168 (Since 2.3)
2169 dirty-bitmaps: array of BlockDirtyInfo (optional)
2171 dirty bitmaps information (only present if node has one or more
2172 dirty bitmaps) (Since 4.2)
2173 Since
2175 0.14
2176 BlockDeviceIoStatus (Enum)
2178 An enumeration of block device I/O status.
2179 Values
2181 ok The last I/O operation has succeeded
2182 failed The last I/O operation has failed
2184 nospace
2186 The last I/O operation has failed due to a no-space condition
2187 Since
2189 1.0
2190 BlockDirtyInfo (Object)
2192 Block dirty bitmap information.
2193 Members
2195 name: string (optional)
2196 the name of the dirty bitmap (Since 2.4)
2197 count: int
2199 number of dirty bytes according to the dirty bitmap
2200 granularity: int
2202 granularity of the dirty bitmap in bytes (since 1.4)
2203 recording: boolean
2205 true if the bitmap is recording new writes from the guest.
2206 (since 4.0)
2207 busy: boolean
2209 true if the bitmap is in-use by some operation (NBD or jobs) and
2210 cannot be modified via QMP or used by another operation. (since
2211 4.0)
2212 persistent: boolean
2214 true if the bitmap was stored on disk, is scheduled to be stored
2215 on disk, or both. (since 4.0)
2216 inconsistent: boolean (optional)
2218 true if this is a persistent bitmap that was improperly stored.
2219 Implies persistent to be true; recording and busy to be false.
2220 This bitmap cannot be used. To remove it, use block-dirty-bit‐
2221 map-remove. (Since 4.0)
2222 Since
2224 1.3
2225 Qcow2BitmapInfoFlags (Enum)
2227 An enumeration of flags that a bitmap can report to the user.
2228 Values
2230 in-use This flag is set by any process actively modifying the qcow2
2231 file, and cleared when the updated bitmap is flushed to the
2232 qcow2 image. The presence of this flag in an offline image
2233 means that the bitmap was not saved correctly after its last us‐
2234 age, and may contain inconsistent data.
2235 auto The bitmap must reflect all changes of the virtual disk by any
2237 application that would write to this qcow2 file.
2238 Since
2240 4.0
2241 Qcow2BitmapInfo (Object)
2243 Qcow2 bitmap information.
2244 Members
2246 name: string
2247 the name of the bitmap
2248 granularity: int
2250 granularity of the bitmap in bytes
2251 flags: array of Qcow2BitmapInfoFlags
2253 flags of the bitmap
2254 Since
2256 4.0
2257 BlockLatencyHistogramInfo (Object)
2259 Block latency histogram.
2260 Members
2262 boundaries: array of int
2263 list of interval boundary values in nanoseconds, all greater
2264 than zero and in ascending order. For example, the list [10,
2265 50, 100] produces the following histogram intervals: [0, 10),
2266 [10, 50), [50, 100), [100, +inf).
2267 bins: array of int
2269 list of io request counts corresponding to histogram intervals,
2270 one more element than boundaries has. For the example above,
2271 bins may be something like [3, 1, 5, 2], and corresponding his‐
2272 togram looks like:
2273 5| *
2275 4| *
2276 3| * *
2277 2| * * *
2278 1| * * * *
2279 +------------------
2280 10 50 100
2281 Since
2283 4.0
2284 BlockInfo (Object)
2286 Block device information. This structure describes a virtual device
2287 and the backing device associated with it.
2288 Members
2290 device: string
2291 The device name associated with the virtual device.
2292 qdev: string (optional)
2294 The qdev ID, or if no ID is assigned, the QOM path of the block
2295 device. (since 2.10)
2296 type: string
2298 This field is returned only for compatibility reasons, it should
2299 not be used (always returns 'unknown')
2300 removable: boolean
2302 True if the device supports removable media.
2303 locked: boolean
2305 True if the guest has locked this device from having its media
2306 removed
2307 tray_open: boolean (optional)
2309 True if the device's tray is open (only present if it has a
2310 tray)
2311 io-status: BlockDeviceIoStatus (optional)
2313 BlockDeviceIoStatus. Only present if the device supports it and
2314 the VM is configured to stop on errors (supported device models:
2315 virtio-blk, IDE, SCSI except scsi-generic)
2316 inserted: BlockDeviceInfo (optional)
2318 BlockDeviceInfo describing the device if media is present
2319 Since
2321 0.14
2322 BlockMeasureInfo (Object)
2324 Image file size calculation information. This structure describes the
2325 size requirements for creating a new image file.
2326 The size requirements depend on the new image file format. File size
2328 always equals virtual disk size for the 'raw' format, even for sparse
2329 POSIX files. Compact formats such as 'qcow2' represent unallocated and
2330 zero regions efficiently so file size may be smaller than virtual disk
2331 size.
2332 The values are upper bounds that are guaranteed to fit the new image
2334 file. Subsequent modification, such as internal snapshot or further
2335 bitmap creation, may require additional space and is not covered here.
2336 Members
2338 required: int
2339 Size required for a new image file, in bytes, when copying just
2340 allocated guest-visible contents.
2341 fully-allocated: int
2343 Image file size, in bytes, once data has been written to all
2344 sectors, when copying just guest-visible contents.
2345 bitmaps: int (optional)
2347 Additional size required if all the top-level bitmap metadata in
2348 the source image were to be copied to the destination, present
2349 only when source and destination both support persistent bit‐
2350 maps. (since 5.1)
2351 Since
2353 2.10
2354 query-block (Command)
2356 Get a list of BlockInfo for all virtual block devices.
2357 Returns
2359 a list of BlockInfo describing each virtual block device. Filter nodes
2360 that were created implicitly are skipped over.
2361 Since
2363 0.14
2364 Example
2366 -> { "execute": "query-block" }
2367 <- {
2368 "return":[
2369 {
2370 "io-status": "ok",
2371 "device":"ide0-hd0",
2372 "locked":false,
2373 "removable":false,
2374 "inserted":{
2375 "ro":false,
2376 "drv":"qcow2",
2377 "encrypted":false,
2378 "file":"disks/test.qcow2",
2379 "backing_file_depth":1,
2380 "bps":1000000,
2381 "bps_rd":0,
2382 "bps_wr":0,
2383 "iops":1000000,
2384 "iops_rd":0,
2385 "iops_wr":0,
2386 "bps_max": 8000000,
2387 "bps_rd_max": 0,
2388 "bps_wr_max": 0,
2389 "iops_max": 0,
2390 "iops_rd_max": 0,
2391 "iops_wr_max": 0,
2392 "iops_size": 0,
2393 "detect_zeroes": "on",
2394 "write_threshold": 0,
2395 "image":{
2396 "filename":"disks/test.qcow2",
2397 "format":"qcow2",
2398 "virtual-size":2048000,
2399 "backing_file":"base.qcow2",
2400 "full-backing-filename":"disks/base.qcow2",
2401 "backing-filename-format":"qcow2",
2402 "snapshots":[
2403 {
2404 "id": "1",
2405 "name": "snapshot1",
2406 "vm-state-size": 0,
2407 "date-sec": 10000200,
2408 "date-nsec": 12,
2409 "vm-clock-sec": 206,
2410 "vm-clock-nsec": 30
2411 }
2412 ],
2413 "backing-image":{
2414 "filename":"disks/base.qcow2",
2415 "format":"qcow2",
2416 "virtual-size":2048000
2417 }
2418 }
2419 },
2420 "qdev": "ide_disk",
2421 "type":"unknown"
2422 },
2423 {
2424 "io-status": "ok",
2425 "device":"ide1-cd0",
2426 "locked":false,
2427 "removable":true,
2428 "qdev": "/machine/unattached/device[23]",
2429 "tray_open": false,
2430 "type":"unknown"
2431 },
2432 {
2433 "device":"floppy0",
2434 "locked":false,
2435 "removable":true,
2436 "qdev": "/machine/unattached/device[20]",
2437 "type":"unknown"
2438 },
2439 {
2440 "device":"sd0",
2441 "locked":false,
2442 "removable":true,
2443 "type":"unknown"
2444 }
2445 ]
2446 }
2447 BlockDeviceTimedStats (Object)
2449 Statistics of a block device during a given interval of time.
2450 Members
2452 interval_length: int
2453 Interval used for calculating the statistics, in seconds.
2454 min_rd_latency_ns: int
2456 Minimum latency of read operations in the defined interval, in
2457 nanoseconds.
2458 min_wr_latency_ns: int
2460 Minimum latency of write operations in the defined interval, in
2461 nanoseconds.
2462 min_zone_append_latency_ns: int
2464 Minimum latency of zone append operations in the defined inter‐
2465 val, in nanoseconds (since 8.1)
2466 min_flush_latency_ns: int
2468 Minimum latency of flush operations in the defined interval, in
2469 nanoseconds.
2470 max_rd_latency_ns: int
2472 Maximum latency of read operations in the defined interval, in
2473 nanoseconds.
2474 max_wr_latency_ns: int
2476 Maximum latency of write operations in the defined interval, in
2477 nanoseconds.
2478 max_zone_append_latency_ns: int
2480 Maximum latency of zone append operations in the defined inter‐
2481 val, in nanoseconds (since 8.1)
2482 max_flush_latency_ns: int
2484 Maximum latency of flush operations in the defined interval, in
2485 nanoseconds.
2486 avg_rd_latency_ns: int
2488 Average latency of read operations in the defined interval, in
2489 nanoseconds.
2490 avg_wr_latency_ns: int
2492 Average latency of write operations in the defined interval, in
2493 nanoseconds.
2494 avg_zone_append_latency_ns: int
2496 Average latency of zone append operations in the defined inter‐
2497 val, in nanoseconds (since 8.1)
2498 avg_flush_latency_ns: int
2500 Average latency of flush operations in the defined interval, in
2501 nanoseconds.
2502 avg_rd_queue_depth: number
2504 Average number of pending read operations in the defined inter‐
2505 val.
2506 avg_wr_queue_depth: number
2508 Average number of pending write operations in the defined inter‐
2509 val.
2510 avg_zone_append_queue_depth: number
2512 Average number of pending zone append operations in the defined
2513 interval (since 8.1).
2514 Since
2516 2.5
2517 BlockDeviceStats (Object)
2519 Statistics of a virtual block device or a block backing device.
2520 Members
2522 rd_bytes: int
2523 The number of bytes read by the device.
2524 wr_bytes: int
2526 The number of bytes written by the device.
2527 zone_append_bytes: int
2529 The number of bytes appended by the zoned devices (since 8.1)
2530 unmap_bytes: int
2532 The number of bytes unmapped by the device (Since 4.2)
2533 rd_operations: int
2535 The number of read operations performed by the device.
2536 wr_operations: int
2538 The number of write operations performed by the device.
2539 zone_append_operations: int
2541 The number of zone append operations performed by the zoned de‐
2542 vices (since 8.1)
2543 flush_operations: int
2545 The number of cache flush operations performed by the device
2546 (since 0.15)
2547 unmap_operations: int
2549 The number of unmap operations performed by the device (Since
2550 4.2)
2551 rd_total_time_ns: int
2553 Total time spent on reads in nanoseconds (since 0.15).
2554 wr_total_time_ns: int
2556 Total time spent on writes in nanoseconds (since 0.15).
2557 zone_append_total_time_ns: int
2559 Total time spent on zone append writes in nanoseconds (since
2560 8.1)
2561 flush_total_time_ns: int
2563 Total time spent on cache flushes in nanoseconds (since 0.15).
2564 unmap_total_time_ns: int
2566 Total time spent on unmap operations in nanoseconds (Since 4.2)
2567 wr_highest_offset: int
2569 The offset after the greatest byte written to the device. The
2570 intended use of this information is for growable sparse files
2571 (like qcow2) that are used on top of a physical device.
2572 rd_merged: int
2574 Number of read requests that have been merged into another re‐
2575 quest (Since 2.3).
2576 wr_merged: int
2578 Number of write requests that have been merged into another re‐
2579 quest (Since 2.3).
2580 zone_append_merged: int
2582 Number of zone append requests that have been merged into an‐
2583 other request (since 8.1)
2584 unmap_merged: int
2586 Number of unmap requests that have been merged into another re‐
2587 quest (Since 4.2)
2588 idle_time_ns: int (optional)
2590 Time since the last I/O operation, in nanoseconds. If the field
2591 is absent it means that there haven't been any operations yet
2592 (Since 2.5).
2593 failed_rd_operations: int
2595 The number of failed read operations performed by the device
2596 (Since 2.5)
2597 failed_wr_operations: int
2599 The number of failed write operations performed by the device
2600 (Since 2.5)
2601 failed_zone_append_operations: int
2603 The number of failed zone append write operations performed by
2604 the zoned devices (since 8.1)
2605 failed_flush_operations: int
2607 The number of failed flush operations performed by the device
2608 (Since 2.5)
2609 failed_unmap_operations: int
2611 The number of failed unmap operations performed by the device
2612 (Since 4.2)
2613 invalid_rd_operations: int
2615 The number of invalid read operations performed by the device
2616 (Since 2.5)
2617 invalid_wr_operations: int
2619 The number of invalid write operations performed by the device
2620 (Since 2.5)
2621 invalid_zone_append_operations: int
2623 The number of invalid zone append operations performed by the
2624 zoned device (since 8.1)
2625 invalid_flush_operations: int
2627 The number of invalid flush operations performed by the device
2628 (Since 2.5)
2629 invalid_unmap_operations: int
2631 The number of invalid unmap operations performed by the device
2632 (Since 4.2)
2633 account_invalid: boolean
2635 Whether invalid operations are included in the last access sta‐
2636 tistics (Since 2.5)
2637 account_failed: boolean
2639 Whether failed operations are included in the latency and last
2640 access statistics (Since 2.5)
2641 timed_stats: array of BlockDeviceTimedStats
2643 Statistics specific to the set of previously defined intervals
2644 of time (Since 2.5)
2645 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
2647 BlockLatencyHistogramInfo. (Since 4.0)
2648 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
2650 BlockLatencyHistogramInfo. (Since 4.0)
2651 zone_append_latency_histogram: BlockLatencyHistogramInfo (optional)
2653 BlockLatencyHistogramInfo. (since 8.1)
2654 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
2656 BlockLatencyHistogramInfo. (Since 4.0)
2657 Since
2659 0.14
2660 BlockStatsSpecificFile (Object)
2662 File driver statistics
2663 Members
2665 discard-nb-ok: int
2666 The number of successful discard operations performed by the
2667 driver.
2668 discard-nb-failed: int
2670 The number of failed discard operations performed by the driver.
2671 discard-bytes-ok: int
2673 The number of bytes discarded by the driver.
2674 Since
2676 4.2
2677 BlockStatsSpecificNvme (Object)
2679 NVMe driver statistics
2680 Members
2682 completion-errors: int
2683 The number of completion errors.
2684 aligned-accesses: int
2686 The number of aligned accesses performed by the driver.
2687 unaligned-accesses: int
2689 The number of unaligned accesses performed by the driver.
2690 Since
2692 5.2
2693 BlockStatsSpecific (Object)
2695 Block driver specific statistics
2696 Members
2698 driver: BlockdevDriver
2699 Not documented
2700 The members of BlockStatsSpecificFile when driver is "file"
2702 The members of BlockStatsSpecificFile when driver is "host_device" (If:
2704 HAVE_HOST_BLOCK_DEVICE)
2705 The members of BlockStatsSpecificNvme when driver is "nvme"
2707 Since
2709 4.2
2710 BlockStats (Object)
2712 Statistics of a virtual block device or a block backing device.
2713 Members
2715 device: string (optional)
2716 If the stats are for a virtual block device, the name corre‐
2717 sponding to the virtual block device.
2718 node-name: string (optional)
2720 The node name of the device. (Since 2.3)
2721 qdev: string (optional)
2723 The qdev ID, or if no ID is assigned, the QOM path of the block
2724 device. (since 3.0)
2725 stats: BlockDeviceStats
2727 A BlockDeviceStats for the device.
2728 driver-specific: BlockStatsSpecific (optional)
2730 Optional driver-specific stats. (Since 4.2)
2731 parent: BlockStats (optional)
2733 This describes the file block device if it has one. Contains
2734 recursively the statistics of the underlying protocol (e.g. the
2735 host file for a qcow2 image). If there is no underlying proto‐
2736 col, this field is omitted
2737 backing: BlockStats (optional)
2739 This describes the backing block device if it has one. (Since
2740 2.0)
2741 Since
2743 0.14
2744 query-blockstats (Command)
2746 Query the BlockStats for all virtual block devices.
2747 Arguments
2749 query-nodes: boolean (optional)
2750 If true, the command will query all the block nodes that have a
2751 node name, in a list which will include "parent" information,
2752 but not "backing". If false or omitted, the behavior is as be‐
2753 fore - query all the device backends, recursively including
2754 their "parent" and "backing". Filter nodes that were created im‐
2755 plicitly are skipped over in this mode. (Since 2.3)
2756 Returns
2758 A list of BlockStats for each virtual block devices.
2759 Since
2761 0.14
2762 Example
2764 -> { "execute": "query-blockstats" }
2765 <- {
2766 "return":[
2767 {
2768 "device":"ide0-hd0",
2769 "parent":{
2770 "stats":{
2771 "wr_highest_offset":3686448128,
2772 "wr_bytes":9786368,
2773 "wr_operations":751,
2774 "rd_bytes":122567168,
2775 "rd_operations":36772
2776 "wr_total_times_ns":313253456
2777 "rd_total_times_ns":3465673657
2778 "flush_total_times_ns":49653
2779 "flush_operations":61,
2780 "rd_merged":0,
2781 "wr_merged":0,
2782 "idle_time_ns":2953431879,
2783 "account_invalid":true,
2784 "account_failed":false
2785 }
2786 },
2787 "stats":{
2788 "wr_highest_offset":2821110784,
2789 "wr_bytes":9786368,
2790 "wr_operations":692,
2791 "rd_bytes":122739200,
2792 "rd_operations":36604
2793 "flush_operations":51,
2794 "wr_total_times_ns":313253456
2795 "rd_total_times_ns":3465673657
2796 "flush_total_times_ns":49653,
2797 "rd_merged":0,
2798 "wr_merged":0,
2799 "idle_time_ns":2953431879,
2800 "account_invalid":true,
2801 "account_failed":false
2802 },
2803 "qdev": "/machine/unattached/device[23]"
2804 },
2805 {
2806 "device":"ide1-cd0",
2807 "stats":{
2808 "wr_highest_offset":0,
2809 "wr_bytes":0,
2810 "wr_operations":0,
2811 "rd_bytes":0,
2812 "rd_operations":0
2813 "flush_operations":0,
2814 "wr_total_times_ns":0
2815 "rd_total_times_ns":0
2816 "flush_total_times_ns":0,
2817 "rd_merged":0,
2818 "wr_merged":0,
2819 "account_invalid":false,
2820 "account_failed":false
2821 },
2822 "qdev": "/machine/unattached/device[24]"
2823 },
2824 {
2825 "device":"floppy0",
2826 "stats":{
2827 "wr_highest_offset":0,
2828 "wr_bytes":0,
2829 "wr_operations":0,
2830 "rd_bytes":0,
2831 "rd_operations":0
2832 "flush_operations":0,
2833 "wr_total_times_ns":0
2834 "rd_total_times_ns":0
2835 "flush_total_times_ns":0,
2836 "rd_merged":0,
2837 "wr_merged":0,
2838 "account_invalid":false,
2839 "account_failed":false
2840 },
2841 "qdev": "/machine/unattached/device[16]"
2842 },
2843 {
2844 "device":"sd0",
2845 "stats":{
2846 "wr_highest_offset":0,
2847 "wr_bytes":0,
2848 "wr_operations":0,
2849 "rd_bytes":0,
2850 "rd_operations":0
2851 "flush_operations":0,
2852 "wr_total_times_ns":0
2853 "rd_total_times_ns":0
2854 "flush_total_times_ns":0,
2855 "rd_merged":0,
2856 "wr_merged":0,
2857 "account_invalid":false,
2858 "account_failed":false
2859 }
2860 }
2861 ]
2862 }
2863 BlockdevOnError (Enum)
2865 An enumeration of possible behaviors for errors on I/O operations. The
2866 exact meaning depends on whether the I/O was initiated by a guest or by
2867 a block job
2868 Values
2870 report for guest operations, report the error to the guest; for jobs,
2871 cancel the job
2872 ignore ignore the error, only report a QMP event (BLOCK_IO_ERROR or
2874 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
2875 the failing request later and may still complete successfully.
2876 The stream block job continues to stream and will complete with
2877 an error.
2878 enospc same as stop on ENOSPC, same as report otherwise.
2880 stop for guest operations, stop the virtual machine; for jobs, pause
2882 the job
2883 auto inherit the error handling policy of the backend (since: 2.7)
2885 Since
2887 1.3
2888 MirrorSyncMode (Enum)
2890 An enumeration of possible behaviors for the initial synchronization
2891 phase of storage mirroring.
2892 Values
2894 top copies data in the topmost image to the destination
2895 full copies data from all images to the destination
2897 none only copy data written from now on
2899 incremental
2901 only copy data described by the dirty bitmap. (since: 2.4)
2902 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
2904 havior on completion is determined by the BitmapSyncMode.
2905 Since
2907 1.3
2908 BitmapSyncMode (Enum)
2910 An enumeration of possible behaviors for the synchronization of a bit‐
2911 map when used for data copy operations.
2912 Values
2914 on-success
2915 The bitmap is only synced when the operation is successful.
2916 This is the behavior always used for 'INCREMENTAL' backups.
2917 never The bitmap is never synchronized with the operation, and is
2919 treated solely as a read-only manifest of blocks to copy.
2920 always The bitmap is always synchronized with the operation, regardless
2922 of whether or not the operation was successful.
2923 Since
2925 4.2
2926 MirrorCopyMode (Enum)
2928 An enumeration whose values tell the mirror block job when to trigger
2929 writes to the target.
2930 Values
2932 background
2933 copy data in background only.
2934 write-blocking
2936 when data is written to the source, write it (synchronously) to
2937 the target as well. In addition, data is copied in background
2938 just like in background mode.
2939 Since
2941 3.0
2942 BlockJobInfo (Object)
2944 Information about a long-running block device operation.
2945 Members
2947 type: string
2948 the job type ('stream' for image streaming)
2949 device: string
2951 The job identifier. Originally the device name but other values
2952 are allowed since QEMU 2.7
2953 len: int
2955 Estimated offset value at the completion of the job. This value
2956 can arbitrarily change while the job is running, in both direc‐
2957 tions.
2958 offset: int
2960 Progress made until now. The unit is arbitrary and the value
2961 can only meaningfully be used for the ratio of offset to len.
2962 The value is monotonically increasing.
2963 busy: boolean
2965 false if the job is known to be in a quiescent state, with no
2966 pending I/O. (Since 1.3)
2967 paused: boolean
2969 whether the job is paused or, if busy is true, will pause itself
2970 as soon as possible. (Since 1.3)
2971 speed: int
2973 the rate limit, bytes per second
2974 io-status: BlockDeviceIoStatus
2976 the status of the job (since 1.3)
2977 ready: boolean
2979 true if the job may be completed (since 2.2)
2980 status: JobStatus
2982 Current job state/status (since 2.12)
2983 auto-finalize: boolean
2985 Job will finalize itself when PENDING, moving to the CONCLUDED
2986 state. (since 2.12)
2987 auto-dismiss: boolean
2989 Job will dismiss itself when CONCLUDED, moving to the NULL state
2990 and disappearing from the query list. (since 2.12)
2991 error: string (optional)
2993 Error information if the job did not complete successfully. Not
2994 set if the job completed successfully. (since 2.12.1)
2995 Since
2997 1.1
2998 query-block-jobs (Command)
3000 Return information about long-running block device operations.
3001 Returns
3003 a list of BlockJobInfo for each active block job
3004 Since
3006 1.1
3007 block_resize (Command)
3009 Resize a block image while a guest is running.
3010 Either device or node-name must be set but not both.
3012 Arguments
3014 device: string (optional)
3015 the name of the device to get the image resized
3016 node-name: string (optional)
3018 graph node name to get the image resized (Since 2.0)
3019 size: int
3021 new image size in bytes
3022 Returns
3024 • nothing on success
3025 • If device is not a valid block device, DeviceNotFound
3027 Since
3029 0.14
3030 Example
3032 -> { "execute": "block_resize",
3033 "arguments": { "device": "scratch", "size": 1073741824 } }
3034 <- { "return": {} }
3035 NewImageMode (Enum)
3037 An enumeration that tells QEMU how to set the backing file path in a
3038 new image file.
3039 Values
3041 existing
3042 QEMU should look for an existing image file.
3043 absolute-paths
3045 QEMU should create a new image with absolute paths for the back‐
3046 ing file. If there is no backing file available, the new image
3047 will not be backed either.
3048 Since
3050 1.1
3051 BlockdevSnapshotSync (Object)
3053 Either device or node-name must be set but not both.
3054 Members
3056 device: string (optional)
3057 the name of the device to take a snapshot of.
3058 node-name: string (optional)
3060 graph node name to generate the snapshot from (Since 2.0)
3061 snapshot-file: string
3063 the target of the new overlay image. If the file exists, or if
3064 it is a device, the overlay will be created in the existing
3065 file/device. Otherwise, a new file will be created.
3066 snapshot-node-name: string (optional)
3068 the graph node name of the new image (Since 2.0)
3069 format: string (optional)
3071 the format of the overlay image, default is 'qcow2'.
3072 mode: NewImageMode (optional)
3074 whether and how QEMU should create a new image, default is 'ab‐
3075 solute-paths'.
3076 BlockdevSnapshot (Object)
3078 Members
3079 node: string
3080 device or node name that will have a snapshot taken.
3081 overlay: string
3083 reference to the existing block device that will become the
3084 overlay of node, as part of taking the snapshot. It must not
3085 have a current backing file (this can be achieved by passing
3086 "backing": null to blockdev-add).
3087 Since
3089 2.5
3090 BackupPerf (Object)
3092 Optional parameters for backup. These parameters don't affect func‐
3093 tionality, but may significantly affect performance.
3094 Members
3096 use-copy-range: boolean (optional)
3097 Use copy offloading. Default false.
3098 max-workers: int (optional)
3100 Maximum number of parallel requests for the sustained background
3101 copying process. Doesn't influence copy-before-write opera‐
3102 tions. Default 64.
3103 max-chunk: int (optional)
3105 Maximum request length for the sustained background copying
3106 process. Doesn't influence copy-before-write operations. 0
3107 means unlimited. If max-chunk is non-zero then it should not be
3108 less than job cluster size which is calculated as maximum of
3109 target image cluster size and 64k. Default 0.
3110 Since
3112 6.0
3113 BackupCommon (Object)
3115 Members
3116 job-id: string (optional)
3117 identifier for the newly-created block job. If omitted, the de‐
3118 vice name will be used. (Since 2.7)
3119 device: string
3121 the device name or node-name of a root node which should be
3122 copied.
3123 sync: MirrorSyncMode
3125 what parts of the disk image should be copied to the destination
3126 (all the disk, only the sectors allocated in the topmost image,
3127 from a dirty bitmap, or only new I/O).
3128 speed: int (optional)
3130 the maximum speed, in bytes per second. The default is 0, for
3131 unlimited.
3132 bitmap: string (optional)
3134 The name of a dirty bitmap to use. Must be present if sync is
3135 "bitmap" or "incremental". Can be present if sync is "full" or
3136 "top". Must not be present otherwise. (Since 2.4
3137 (drive-backup), 3.1 (blockdev-backup))
3138 bitmap-mode: BitmapSyncMode (optional)
3140 Specifies the type of data the bitmap should contain after the
3141 operation concludes. Must be present if a bitmap was provided,
3142 Must NOT be present otherwise. (Since 4.2)
3143 compress: boolean (optional)
3145 true to compress data, if the target format supports it. (de‐
3146 fault: false) (since 2.8)
3147 on-source-error: BlockdevOnError (optional)
3149 the action to take on an error on the source, default 'report'.
3150 'stop' and 'enospc' can only be used if the block device sup‐
3151 ports io-status (see BlockInfo).
3152 on-target-error: BlockdevOnError (optional)
3154 the action to take on an error on the target, default 'report'
3155 (no limitations, since this applies to a different block device
3156 than device).
3157 auto-finalize: boolean (optional)
3159 When false, this job will wait in a PENDING state after it has
3160 finished its work, waiting for block-job-finalize before making
3161 any block graph changes. When true, this job will automatically
3162 perform its abort or commit actions. Defaults to true. (Since
3163 2.12)
3164 auto-dismiss: boolean (optional)
3166 When false, this job will wait in a CONCLUDED state after it has
3167 completely ceased all work, and awaits block-job-dismiss. When
3168 true, this job will automatically disappear from the query list
3169 without user intervention. Defaults to true. (Since 2.12)
3170 filter-node-name: string (optional)
3172 the node name that should be assigned to the filter driver that
3173 the backup job inserts into the graph above node specified by
3174 drive. If this option is not given, a node name is autogener‐
3175 ated. (Since: 4.2)
3176 x-perf: BackupPerf (optional)
3178 Performance options. (Since 6.0)
3179 Features
3181 unstable
3182 Member x-perf is experimental.
3183 Note
3185 on-source-error and on-target-error only affect background I/O. If an
3186 error occurs during a guest write request, the device's rerror/werror
3187 actions will be used.
3188 Since
3190 4.2
3191 DriveBackup (Object)
3193 Members
3194 target: string
3195 the target of the new image. If the file exists, or if it is a
3196 device, the existing file/device will be used as the new desti‐
3197 nation. If it does not exist, a new file will be created.
3198 format: string (optional)
3200 the format of the new destination, default is to probe if mode
3201 is 'existing', else the format of the source
3202 mode: NewImageMode (optional)
3204 whether and how QEMU should create a new image, default is 'ab‐
3205 solute-paths'.
3206 The members of BackupCommon
3208 Since
3210 1.6
3211 BlockdevBackup (Object)
3213 Members
3214 target: string
3215 the device name or node-name of the backup target node.
3216 The members of BackupCommon
3218 Since
3220 2.3
3221 blockdev-snapshot-sync (Command)
3223 Takes a synchronous snapshot of a block device.
3224 For the arguments, see the documentation of BlockdevSnapshotSync.
3226 Returns
3228 • nothing on success
3229 • If device is not a valid block device, DeviceNotFound
3231 Since
3233 0.14
3234 Example
3236 -> { "execute": "blockdev-snapshot-sync",
3237 "arguments": { "device": "ide-hd0",
3238 "snapshot-file":
3239 "/some/place/my-image",
3240 "format": "qcow2" } }
3241 <- { "return": {} }
3242 blockdev-snapshot (Command)
3244 Takes a snapshot of a block device.
3245 Take a snapshot, by installing 'node' as the backing image of 'over‐
3247 lay'. Additionally, if 'node' is associated with a block device, the
3248 block device changes to using 'overlay' as its new active image.
3249 For the arguments, see the documentation of BlockdevSnapshot.
3251 Features
3253 allow-write-only-overlay
3254 If present, the check whether this operation is safe was relaxed
3255 so that it can be used to change backing file of a destination
3256 of a blockdev-mirror. (since 5.0)
3257 Since
3259 2.5
3260 Example
3262 -> { "execute": "blockdev-add",
3263 "arguments": { "driver": "qcow2",
3264 "node-name": "node1534",
3265 "file": { "driver": "file",
3266 "filename": "hd1.qcow2" },
3267 "backing": null } }
3268 <- { "return": {} }
3270 -> { "execute": "blockdev-snapshot",
3272 "arguments": { "node": "ide-hd0",
3273 "overlay": "node1534" } }
3274 <- { "return": {} }
3275 change-backing-file (Command)
3277 Change the backing file in the image file metadata. This does not
3278 cause QEMU to reopen the image file to reparse the backing filename (it
3279 may, however, perform a reopen to change permissions from r/o -> r/w ->
3280 r/o, if needed). The new backing file string is written into the image
3281 file metadata, and the QEMU internal strings are updated.
3282 Arguments
3284 image-node-name: string
3285 The name of the block driver state node of the image to modify.
3286 The "device" argument is used to verify "image-node-name" is in
3287 the chain described by "device".
3288 device: string
3290 The device name or node-name of the root node that owns im‐
3291 age-node-name.
3292 backing-file: string
3294 The string to write as the backing file. This string is not
3295 validated, so care should be taken when specifying the string or
3296 the image chain may not be able to be reopened again.
3297 Returns
3299 • Nothing on success
3300 • If "device" does not exist or cannot be determined, DeviceNotFound
3302 Since
3304 2.1
3305 block-commit (Command)
3307 Live commit of data from overlay image nodes into backing nodes - i.e.,
3308 writes data between 'top' and 'base' into 'base'.
3309 If top == base, that is an error. If top has no overlays on top of it,
3311 or if it is in use by a writer, the job will not be completed by it‐
3312 self. The user needs to complete the job with the block-job-complete
3313 command after getting the ready event. (Since 2.0)
3314 If the base image is smaller than top, then the base image will be re‐
3316 sized to be the same size as top. If top is smaller than the base im‐
3317 age, the base will not be truncated. If you want the base image size
3318 to match the size of the smaller top, you can safely truncate it your‐
3319 self once the commit operation successfully completes.
3320 Arguments
3322 job-id: string (optional)
3323 identifier for the newly-created block job. If omitted, the de‐
3324 vice name will be used. (Since 2.7)
3325 device: string
3327 the device name or node-name of a root node
3328 base-node: string (optional)
3330 The node name of the backing image to write data into. If not
3331 specified, this is the deepest backing image. (since: 3.1)
3332 base: string (optional)
3334 Same as base-node, except that it is a file name rather than a
3335 node name. This must be the exact filename string that was used
3336 to open the node; other strings, even if addressing the same
3337 file, are not accepted
3338 top-node: string (optional)
3340 The node name of the backing image within the image chain which
3341 contains the topmost data to be committed down. If not speci‐
3342 fied, this is the active layer. (since: 3.1)
3343 top: string (optional)
3345 Same as top-node, except that it is a file name rather than a
3346 node name. This must be the exact filename string that was used
3347 to open the node; other strings, even if addressing the same
3348 file, are not accepted
3349 backing-file: string (optional)
3351 The backing file string to write into the overlay image of
3352 'top'. If 'top' does not have an overlay image, or if 'top' is
3353 in use by a writer, specifying a backing file string is an er‐
3354 ror.
3355 This filename is not validated. If a pathname string is such
3357 that it cannot be resolved by QEMU, that means that subsequent
3358 QMP or HMP commands must use node-names for the image in ques‐
3359 tion, as filename lookup methods will fail.
3360 If not specified, QEMU will automatically determine the backing
3362 file string to use, or error out if there is no obvious choice.
3363 Care should be taken when specifying the string, to specify a
3364 valid filename or protocol. (Since 2.1)
3365 speed: int (optional)
3367 the maximum speed, in bytes per second
3368 on-error: BlockdevOnError (optional)
3370 the action to take on an error. 'ignore' means that the request
3371 should be retried. (default: report; Since: 5.0)
3372 filter-node-name: string (optional)
3374 the node name that should be assigned to the filter driver that
3375 the commit job inserts into the graph above top. If this option
3376 is not given, a node name is autogenerated. (Since: 2.9)
3377 auto-finalize: boolean (optional)
3379 When false, this job will wait in a PENDING state after it has
3380 finished its work, waiting for block-job-finalize before making
3381 any block graph changes. When true, this job will automatically
3382 perform its abort or commit actions. Defaults to true. (Since
3383 3.1)
3384 auto-dismiss: boolean (optional)
3386 When false, this job will wait in a CONCLUDED state after it has
3387 completely ceased all work, and awaits block-job-dismiss. When
3388 true, this job will automatically disappear from the query list
3389 without user intervention. Defaults to true. (Since 3.1)
3390 Features
3392 deprecated
3393 Members base and top are deprecated. Use base-node and top-node
3394 instead.
3395 Returns
3397 • Nothing on success
3398 • If device does not exist, DeviceNotFound
3400 • Any other error returns a GenericError.
3402 Since
3404 1.3
3405 Example
3407 -> { "execute": "block-commit",
3408 "arguments": { "device": "virtio0",
3409 "top": "/tmp/snap1.qcow2" } }
3410 <- { "return": {} }
3411 drive-backup (Command)
3413 Start a point-in-time copy of a block device to a new destination. The
3414 status of ongoing drive-backup operations can be checked with
3415 query-block-jobs where the BlockJobInfo.type field has the value
3416 'backup'. The operation can be stopped before it has completed using
3417 the block-job-cancel command.
3418 Arguments
3420 The members of DriveBackup
3421 Features
3423 deprecated
3424 This command is deprecated. Use blockdev-backup instead.
3425 Returns
3427 • nothing on success
3428 • If device is not a valid block device, GenericError
3430 Since
3432 1.6
3433 Example
3435 -> { "execute": "drive-backup",
3436 "arguments": { "device": "drive0",
3437 "sync": "full",
3438 "target": "backup.img" } }
3439 <- { "return": {} }
3440 blockdev-backup (Command)
3442 Start a point-in-time copy of a block device to a new destination. The
3443 status of ongoing blockdev-backup operations can be checked with
3444 query-block-jobs where the BlockJobInfo.type field has the value
3445 'backup'. The operation can be stopped before it has completed using
3446 the block-job-cancel command.
3447 Arguments
3449 The members of BlockdevBackup
3450 Returns
3452 • nothing on success
3453 • If device is not a valid block device, DeviceNotFound
3455 Since
3457 2.3
3458 Example
3460 -> { "execute": "blockdev-backup",
3461 "arguments": { "device": "src-id",
3462 "sync": "full",
3463 "target": "tgt-id" } }
3464 <- { "return": {} }
3465 query-named-block-nodes (Command)
3467 Get the named block driver list
3468 Arguments
3470 flat: boolean (optional)
3471 Omit the nested data about backing image ("backing-image" key)
3472 if true. Default is false (Since 5.0)
3473 Returns
3475 the list of BlockDeviceInfo
3476 Since
3478 2.0
3479 Example
3481 -> { "execute": "query-named-block-nodes" }
3482 <- { "return": [ { "ro":false,
3483 "drv":"qcow2",
3484 "encrypted":false,
3485 "file":"disks/test.qcow2",
3486 "node-name": "my-node",
3487 "backing_file_depth":1,
3488 "detect_zeroes":"off",
3489 "bps":1000000,
3490 "bps_rd":0,
3491 "bps_wr":0,
3492 "iops":1000000,
3493 "iops_rd":0,
3494 "iops_wr":0,
3495 "bps_max": 8000000,
3496 "bps_rd_max": 0,
3497 "bps_wr_max": 0,
3498 "iops_max": 0,
3499 "iops_rd_max": 0,
3500 "iops_wr_max": 0,
3501 "iops_size": 0,
3502 "write_threshold": 0,
3503 "image":{
3504 "filename":"disks/test.qcow2",
3505 "format":"qcow2",
3506 "virtual-size":2048000,
3507 "backing_file":"base.qcow2",
3508 "full-backing-filename":"disks/base.qcow2",
3509 "backing-filename-format":"qcow2",
3510 "snapshots":[
3511 {
3512 "id": "1",
3513 "name": "snapshot1",
3514 "vm-state-size": 0,
3515 "date-sec": 10000200,
3516 "date-nsec": 12,
3517 "vm-clock-sec": 206,
3518 "vm-clock-nsec": 30
3519 }
3520 ],
3521 "backing-image":{
3522 "filename":"disks/base.qcow2",
3523 "format":"qcow2",
3524 "virtual-size":2048000
3525 }
3526 } } ] }
3527 XDbgBlockGraphNodeType (Enum)
3529 Values
3530 block-backend
3531 corresponds to BlockBackend
3532 block-job
3534 corresponds to BlockJob
3535 block-driver
3537 corresponds to BlockDriverState
3538 Since
3540 4.0
3541 XDbgBlockGraphNode (Object)
3543 Members
3544 id: int
3545 Block graph node identifier. This id is generated only for
3546 x-debug-query-block-graph and does not relate to any other iden‐
3547 tifiers in Qemu.
3548 type: XDbgBlockGraphNodeType
3550 Type of graph node. Can be one of block-backend, block-job or
3551 block-driver-state.
3552 name: string
3554 Human readable name of the node. Corresponds to node-name for
3555 block-driver-state nodes; is not guaranteed to be unique in the
3556 whole graph (with block-jobs and block-backends).
3557 Since
3559 4.0
3560 BlockPermission (Enum)
3562 Enum of base block permissions.
3563 Values
3565 consistent-read
3566 A user that has the "permission" of consistent reads is guaran‐
3567 teed that their view of the contents of the block device is com‐
3568 plete and self-consistent, representing the contents of a disk
3569 at a specific point. For most block devices (including their
3570 backing files) this is true, but the property cannot be main‐
3571 tained in a few situations like for intermediate nodes of a com‐
3572 mit block job.
3573 write This permission is required to change the visible disk contents.
3575 write-unchanged
3577 This permission (which is weaker than BLK_PERM_WRITE) is both
3578 enough and required for writes to the block node when the caller
3579 promises that the visible disk content doesn't change. As the
3580 BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
3581 cient to perform an unchanging write.
3582 resize This permission is required to change the size of a block node.
3584 Since
3586 4.0
3587 XDbgBlockGraphEdge (Object)
3589 Block Graph edge description for x-debug-query-block-graph.
3590 Members
3592 parent: int
3593 parent id
3594 child: int
3596 child id
3597 name: string
3599 name of the relation (examples are 'file' and 'backing')
3600 perm: array of BlockPermission
3602 granted permissions for the parent operating on the child
3603 shared-perm: array of BlockPermission
3605 permissions that can still be granted to other users of the
3606 child while it is still attached to this parent
3607 Since
3609 4.0
3610 XDbgBlockGraph (Object)
3612 Block Graph - list of nodes and list of edges.
3613 Members
3615 nodes: array of XDbgBlockGraphNode
3616 Not documented
3617 edges: array of XDbgBlockGraphEdge
3619 Not documented
3620 Since
3622 4.0
3623 x-debug-query-block-graph (Command)
3625 Get the block graph.
3626 Features
3628 unstable
3629 This command is meant for debugging.
3630 Since
3632 4.0
3633 drive-mirror (Command)
3635 Start mirroring a block device's writes to a new destination. target
3636 specifies the target of the new image. If the file exists, or if it is
3637 a device, it will be used as the new destination for writes. If it
3638 does not exist, a new file will be created. format specifies the for‐
3639 mat of the mirror image, default is to probe if mode='existing', else
3640 the format of the source.
3641 Arguments
3643 The members of DriveMirror
3644 Returns
3646 • nothing on success
3647 • If device is not a valid block device, GenericError
3649 Since
3651 1.3
3652 Example
3654 -> { "execute": "drive-mirror",
3655 "arguments": { "device": "ide-hd0",
3656 "target": "/some/place/my-image",
3657 "sync": "full",
3658 "format": "qcow2" } }
3659 <- { "return": {} }
3660 DriveMirror (Object)
3662 A set of parameters describing drive mirror setup.
3663 Members
3665 job-id: string (optional)
3666 identifier for the newly-created block job. If omitted, the de‐
3667 vice name will be used. (Since 2.7)
3668 device: string
3670 the device name or node-name of a root node whose writes should
3671 be mirrored.
3672 target: string
3674 the target of the new image. If the file exists, or if it is a
3675 device, the existing file/device will be used as the new desti‐
3676 nation. If it does not exist, a new file will be created.
3677 format: string (optional)
3679 the format of the new destination, default is to probe if mode
3680 is 'existing', else the format of the source
3681 node-name: string (optional)
3683 the new block driver state node name in the graph (Since 2.1)
3684 replaces: string (optional)
3686 with sync=full graph node name to be replaced by the new image
3687 when a whole image copy is done. This can be used to repair
3688 broken Quorum files. By default, device is replaced, although
3689 implicitly created filters on it are kept. (Since 2.1)
3690 mode: NewImageMode (optional)
3692 whether and how QEMU should create a new image, default is 'ab‐
3693 solute-paths'.
3694 speed: int (optional)
3696 the maximum speed, in bytes per second
3697 sync: MirrorSyncMode
3699 what parts of the disk image should be copied to the destination
3700 (all the disk, only the sectors allocated in the topmost image,
3701 or only new I/O).
3702 granularity: int (optional)
3704 granularity of the dirty bitmap, default is 64K if the image
3705 format doesn't have clusters, 4K if the clusters are smaller
3706 than that, else the cluster size. Must be a power of 2 between
3707 512 and 64M (since 1.4).
3708 buf-size: int (optional)
3710 maximum amount of data in flight from source to target (since
3711 1.4).
3712 on-source-error: BlockdevOnError (optional)
3714 the action to take on an error on the source, default 'report'.
3715 'stop' and 'enospc' can only be used if the block device sup‐
3716 ports io-status (see BlockInfo).
3717 on-target-error: BlockdevOnError (optional)
3719 the action to take on an error on the target, default 'report'
3720 (no limitations, since this applies to a different block device
3721 than device).
3722 unmap: boolean (optional)
3724 Whether to try to unmap target sectors where source has only
3725 zero. If true, and target unallocated sectors will read as
3726 zero, target image sectors will be unmapped; otherwise, zeroes
3727 will be written. Both will result in identical contents. De‐
3728 fault is true. (Since 2.4)
3729 copy-mode: MirrorCopyMode (optional)
3731 when to copy data to the destination; defaults to 'background'
3732 (Since: 3.0)
3733 auto-finalize: boolean (optional)
3735 When false, this job will wait in a PENDING state after it has
3736 finished its work, waiting for block-job-finalize before making
3737 any block graph changes. When true, this job will automatically
3738 perform its abort or commit actions. Defaults to true. (Since
3739 3.1)
3740 auto-dismiss: boolean (optional)
3742 When false, this job will wait in a CONCLUDED state after it has
3743 completely ceased all work, and awaits block-job-dismiss. When
3744 true, this job will automatically disappear from the query list
3745 without user intervention. Defaults to true. (Since 3.1)
3746 Since
3748 1.3
3749 BlockDirtyBitmap (Object)
3751 Members
3752 node: string
3753 name of device/node which the bitmap is tracking
3754 name: string
3756 name of the dirty bitmap
3757 Since
3759 2.4
3760 BlockDirtyBitmapAdd (Object)
3762 Members
3763 node: string
3764 name of device/node which the bitmap is tracking
3765 name: string
3767 name of the dirty bitmap (must be less than 1024 bytes)
3768 granularity: int (optional)
3770 the bitmap granularity, default is 64k for block-dirty-bit‐
3771 map-add
3772 persistent: boolean (optional)
3774 the bitmap is persistent, i.e. it will be saved to the corre‐
3775 sponding block device image file on its close. For now only
3776 Qcow2 disks support persistent bitmaps. Default is false for
3777 block-dirty-bitmap-add. (Since: 2.10)
3778 disabled: boolean (optional)
3780 the bitmap is created in the disabled state, which means that it
3781 will not track drive changes. The bitmap may be enabled with
3782 block-dirty-bitmap-enable. Default is false. (Since: 4.0)
3783 Since
3785 2.4
3786 BlockDirtyBitmapOrStr (Alternate)
3788 Members
3789 local: string
3790 name of the bitmap, attached to the same node as target bitmap.
3791 external: BlockDirtyBitmap
3793 bitmap with specified node
3794 Since
3796 4.1
3797 BlockDirtyBitmapMerge (Object)
3799 Members
3800 node: string
3801 name of device/node which the target bitmap is tracking
3802 target: string
3804 name of the destination dirty bitmap
3805 bitmaps: array of BlockDirtyBitmapOrStr
3807 name(s) of the source dirty bitmap(s) at node and/or fully spec‐
3808 ified BlockDirtyBitmap elements. The latter are supported since
3809 4.1.
3810 Since
3812 4.0
3813 block-dirty-bitmap-add (Command)
3815 Create a dirty bitmap with a name on the node, and start tracking the
3816 writes.
3817 Returns
3819 • nothing on success
3820 • If node is not a valid block device or node, DeviceNotFound
3822 • If name is already taken, GenericError with an explanation
3824 Since
3826 2.4
3827 Example
3829 -> { "execute": "block-dirty-bitmap-add",
3830 "arguments": { "node": "drive0", "name": "bitmap0" } }
3831 <- { "return": {} }
3832 block-dirty-bitmap-remove (Command)
3834 Stop write tracking and remove the dirty bitmap that was created with
3835 block-dirty-bitmap-add. If the bitmap is persistent, remove it from
3836 its storage too.
3837 Returns
3839 • nothing on success
3840 • If node is not a valid block device or node, DeviceNotFound
3842 • If name is not found, GenericError with an explanation
3844 • if name is frozen by an operation, GenericError
3846 Since
3848 2.4
3849 Example
3851 -> { "execute": "block-dirty-bitmap-remove",
3852 "arguments": { "node": "drive0", "name": "bitmap0" } }
3853 <- { "return": {} }
3854 block-dirty-bitmap-clear (Command)
3856 Clear (reset) a dirty bitmap on the device, so that an incremental
3857 backup from this point in time forward will only backup clusters modi‐
3858 fied after this clear operation.
3859 Returns
3861 • nothing on success
3862 • If node is not a valid block device, DeviceNotFound
3864 • If name is not found, GenericError with an explanation
3866 Since
3868 2.4
3869 Example
3871 -> { "execute": "block-dirty-bitmap-clear",
3872 "arguments": { "node": "drive0", "name": "bitmap0" } }
3873 <- { "return": {} }
3874 block-dirty-bitmap-enable (Command)
3876 Enables a dirty bitmap so that it will begin tracking disk changes.
3877 Returns
3879 • nothing on success
3880 • If node is not a valid block device, DeviceNotFound
3882 • If name is not found, GenericError with an explanation
3884 Since
3886 4.0
3887 Example
3889 -> { "execute": "block-dirty-bitmap-enable",
3890 "arguments": { "node": "drive0", "name": "bitmap0" } }
3891 <- { "return": {} }
3892 block-dirty-bitmap-disable (Command)
3894 Disables a dirty bitmap so that it will stop tracking disk changes.
3895 Returns
3897 • nothing on success
3898 • If node is not a valid block device, DeviceNotFound
3900 • If name is not found, GenericError with an explanation
3902 Since
3904 4.0
3905 Example
3907 -> { "execute": "block-dirty-bitmap-disable",
3908 "arguments": { "node": "drive0", "name": "bitmap0" } }
3909 <- { "return": {} }
3910 block-dirty-bitmap-merge (Command)
3912 Merge dirty bitmaps listed in bitmaps to the target dirty bitmap.
3913 Dirty bitmaps in bitmaps will be unchanged, except if it also appears
3914 as the target bitmap. Any bits already set in target will still be set
3915 after the merge, i.e., this operation does not clear the target. On
3916 error, target is unchanged.
3917 The resulting bitmap will count as dirty any clusters that were dirty
3919 in any of the source bitmaps. This can be used to achieve backup
3920 checkpoints, or in simpler usages, to copy bitmaps.
3921 Returns
3923 • nothing on success
3924 • If node is not a valid block device, DeviceNotFound
3926 • If any bitmap in bitmaps or target is not found, GenericError
3928 • If any of the bitmaps have different sizes or granularities, Gener‐
3930 icError
3931 Since
3933 4.0
3934 Example
3936 -> { "execute": "block-dirty-bitmap-merge",
3937 "arguments": { "node": "drive0", "target": "bitmap0",
3938 "bitmaps": ["bitmap1"] } }
3939 <- { "return": {} }
3940 BlockDirtyBitmapSha256 (Object)
3942 SHA256 hash of dirty bitmap data
3943 Members
3945 sha256: string
3946 ASCII representation of SHA256 bitmap hash
3947 Since
3949 2.10
3950 x-debug-block-dirty-bitmap-sha256 (Command)
3952 Get bitmap SHA256.
3953 Features
3955 unstable
3956 This command is meant for debugging.
3957 Returns
3959 • BlockDirtyBitmapSha256 on success
3960 • If node is not a valid block device, DeviceNotFound
3962 • If name is not found or if hashing has failed, GenericError with an
3964 explanation
3965 Since
3967 2.10
3968 blockdev-mirror (Command)
3970 Start mirroring a block device's writes to a new destination.
3971 Arguments
3973 job-id: string (optional)
3974 identifier for the newly-created block job. If omitted, the de‐
3975 vice name will be used. (Since 2.7)
3976 device: string
3978 The device name or node-name of a root node whose writes should
3979 be mirrored.
3980 target: string
3982 the id or node-name of the block device to mirror to. This
3983 mustn't be attached to guest.
3984 replaces: string (optional)
3986 with sync=full graph node name to be replaced by the new image
3987 when a whole image copy is done. This can be used to repair
3988 broken Quorum files. By default, device is replaced, although
3989 implicitly created filters on it are kept.
3990 speed: int (optional)
3992 the maximum speed, in bytes per second
3993 sync: MirrorSyncMode
3995 what parts of the disk image should be copied to the destination
3996 (all the disk, only the sectors allocated in the topmost image,
3997 or only new I/O).
3998 granularity: int (optional)
4000 granularity of the dirty bitmap, default is 64K if the image
4001 format doesn't have clusters, 4K if the clusters are smaller
4002 than that, else the cluster size. Must be a power of 2 between
4003 512 and 64M
4004 buf-size: int (optional)
4006 maximum amount of data in flight from source to target
4007 on-source-error: BlockdevOnError (optional)
4009 the action to take on an error on the source, default 'report'.
4010 'stop' and 'enospc' can only be used if the block device sup‐
4011 ports io-status (see BlockInfo).
4012 on-target-error: BlockdevOnError (optional)
4014 the action to take on an error on the target, default 'report'
4015 (no limitations, since this applies to a different block device
4016 than device).
4017 filter-node-name: string (optional)
4019 the node name that should be assigned to the filter driver that
4020 the mirror job inserts into the graph above device. If this op‐
4021 tion is not given, a node name is autogenerated. (Since: 2.9)
4022 copy-mode: MirrorCopyMode (optional)
4024 when to copy data to the destination; defaults to 'background'
4025 (Since: 3.0)
4026 auto-finalize: boolean (optional)
4028 When false, this job will wait in a PENDING state after it has
4029 finished its work, waiting for block-job-finalize before making
4030 any block graph changes. When true, this job will automatically
4031 perform its abort or commit actions. Defaults to true. (Since
4032 3.1)
4033 auto-dismiss: boolean (optional)
4035 When false, this job will wait in a CONCLUDED state after it has
4036 completely ceased all work, and awaits block-job-dismiss. When
4037 true, this job will automatically disappear from the query list
4038 without user intervention. Defaults to true. (Since 3.1)
4039 Returns
4041 nothing on success.
4042 Since
4044 2.6
4045 Example
4047 -> { "execute": "blockdev-mirror",
4048 "arguments": { "device": "ide-hd0",
4049 "target": "target0",
4050 "sync": "full" } }
4051 <- { "return": {} }
4052 BlockIOThrottle (Object)
4054 A set of parameters describing block throttling.
4055 Members
4057 device: string (optional)
4058 Block device name
4059 id: string (optional)
4061 The name or QOM path of the guest device (since: 2.8)
4062 bps: int
4064 total throughput limit in bytes per second
4065 bps_rd: int
4067 read throughput limit in bytes per second
4068 bps_wr: int
4070 write throughput limit in bytes per second
4071 iops: int
4073 total I/O operations per second
4074 iops_rd: int
4076 read I/O operations per second
4077 iops_wr: int
4079 write I/O operations per second
4080 bps_max: int (optional)
4082 total throughput limit during bursts, in bytes (Since 1.7)
4083 bps_rd_max: int (optional)
4085 read throughput limit during bursts, in bytes (Since 1.7)
4086 bps_wr_max: int (optional)
4088 write throughput limit during bursts, in bytes (Since 1.7)
4089 iops_max: int (optional)
4091 total I/O operations per second during bursts, in bytes (Since
4092 1.7)
4093 iops_rd_max: int (optional)
4095 read I/O operations per second during bursts, in bytes (Since
4096 1.7)
4097 iops_wr_max: int (optional)
4099 write I/O operations per second during bursts, in bytes (Since
4100 1.7)
4101 bps_max_length: int (optional)
4103 maximum length of the bps_max burst period, in seconds. It must
4104 only be set if bps_max is set as well. Defaults to 1. (Since
4105 2.6)
4106 bps_rd_max_length: int (optional)
4108 maximum length of the bps_rd_max burst period, in seconds. It
4109 must only be set if bps_rd_max is set as well. Defaults to 1.
4110 (Since 2.6)
4111 bps_wr_max_length: int (optional)
4113 maximum length of the bps_wr_max burst period, in seconds. It
4114 must only be set if bps_wr_max is set as well. Defaults to 1.
4115 (Since 2.6)
4116 iops_max_length: int (optional)
4118 maximum length of the iops burst period, in seconds. It must
4119 only be set if iops_max is set as well. Defaults to 1. (Since
4120 2.6)
4121 iops_rd_max_length: int (optional)
4123 maximum length of the iops_rd_max burst period, in seconds. It
4124 must only be set if iops_rd_max is set as well. Defaults to 1.
4125 (Since 2.6)
4126 iops_wr_max_length: int (optional)
4128 maximum length of the iops_wr_max burst period, in seconds. It
4129 must only be set if iops_wr_max is set as well. Defaults to 1.
4130 (Since 2.6)
4131 iops_size: int (optional)
4133 an I/O size in bytes (Since 1.7)
4134 group: string (optional)
4136 throttle group name (Since 2.4)
4137 Features
4139 deprecated
4140 Member device is deprecated. Use id instead.
4141 Since
4143 1.1
4144 ThrottleLimits (Object)
4146 Limit parameters for throttling. Since some limit combinations are il‐
4147 legal, limits should always be set in one transaction. All fields are
4148 optional. When setting limits, if a field is missing the current value
4149 is not changed.
4150 Members
4152 iops-total: int (optional)
4153 limit total I/O operations per second
4154 iops-total-max: int (optional)
4156 I/O operations burst
4157 iops-total-max-length: int (optional)
4159 length of the iops-total-max burst period, in seconds It must
4160 only be set if iops-total-max is set as well.
4161 iops-read: int (optional)
4163 limit read operations per second
4164 iops-read-max: int (optional)
4166 I/O operations read burst
4167 iops-read-max-length: int (optional)
4169 length of the iops-read-max burst period, in seconds It must
4170 only be set if iops-read-max is set as well.
4171 iops-write: int (optional)
4173 limit write operations per second
4174 iops-write-max: int (optional)
4176 I/O operations write burst
4177 iops-write-max-length: int (optional)
4179 length of the iops-write-max burst period, in seconds It must
4180 only be set if iops-write-max is set as well.
4181 bps-total: int (optional)
4183 limit total bytes per second
4184 bps-total-max: int (optional)
4186 total bytes burst
4187 bps-total-max-length: int (optional)
4189 length of the bps-total-max burst period, in seconds. It must
4190 only be set if bps-total-max is set as well.
4191 bps-read: int (optional)
4193 limit read bytes per second
4194 bps-read-max: int (optional)
4196 total bytes read burst
4197 bps-read-max-length: int (optional)
4199 length of the bps-read-max burst period, in seconds It must only
4200 be set if bps-read-max is set as well.
4201 bps-write: int (optional)
4203 limit write bytes per second
4204 bps-write-max: int (optional)
4206 total bytes write burst
4207 bps-write-max-length: int (optional)
4209 length of the bps-write-max burst period, in seconds It must
4210 only be set if bps-write-max is set as well.
4211 iops-size: int (optional)
4213 when limiting by iops max size of an I/O in bytes
4214 Since
4216 2.11
4217 ThrottleGroupProperties (Object)
4219 Properties for throttle-group objects.
4220 Members
4222 limits: ThrottleLimits (optional)
4223 limits to apply for this throttle group
4224 x-iops-total: int (optional)
4226 Not documented
4227 x-iops-total-max: int (optional)
4229 Not documented
4230 x-iops-total-max-length: int (optional)
4232 Not documented
4233 x-iops-read: int (optional)
4235 Not documented
4236 x-iops-read-max: int (optional)
4238 Not documented
4239 x-iops-read-max-length: int (optional)
4241 Not documented
4242 x-iops-write: int (optional)
4244 Not documented
4245 x-iops-write-max: int (optional)
4247 Not documented
4248 x-iops-write-max-length: int (optional)
4250 Not documented
4251 x-bps-total: int (optional)
4253 Not documented
4254 x-bps-total-max: int (optional)
4256 Not documented
4257 x-bps-total-max-length: int (optional)
4259 Not documented
4260 x-bps-read: int (optional)
4262 Not documented
4263 x-bps-read-max: int (optional)
4265 Not documented
4266 x-bps-read-max-length: int (optional)
4268 Not documented
4269 x-bps-write: int (optional)
4271 Not documented
4272 x-bps-write-max: int (optional)
4274 Not documented
4275 x-bps-write-max-length: int (optional)
4277 Not documented
4278 x-iops-size: int (optional)
4280 Not documented
4281 Features
4283 unstable
4284 All members starting with x- are aliases for the same key with‐
4285 out x- in the limits object. This is not a stable interface and
4286 may be removed or changed incompatibly in the future. Use lim‐
4287 its for a supported stable interface.
4288 Since
4290 2.11
4291 block-stream (Command)
4293 Copy data from a backing file into a block device.
4294 The block streaming operation is performed in the background until the
4296 entire backing file has been copied. This command returns immediately
4297 once streaming has started. The status of ongoing block streaming op‐
4298 erations can be checked with query-block-jobs. The operation can be
4299 stopped before it has completed using the block-job-cancel command.
4300 The node that receives the data is called the top image, can be located
4302 in any part of the chain (but always above the base image; see below)
4303 and can be specified using its device or node name. Earlier qemu ver‐
4304 sions only allowed 'device' to name the top level node; presence of the
4305 'base-node' parameter during introspection can be used as a witness of
4306 the enhanced semantics of 'device'.
4307 If a base file is specified then sectors are not copied from that base
4309 file and its backing chain. This can be used to stream a subset of the
4310 backing file chain instead of flattening the entire image. When
4311 streaming completes the image file will have the base file as its back‐
4312 ing file, unless that node was changed while the job was running. In
4313 that case, base's parent's backing (or filtered, whichever exists)
4314 child (i.e., base at the beginning of the job) will be the new backing
4315 file.
4316 On successful completion the image file is updated to drop the backing
4318 file and the BLOCK_JOB_COMPLETED event is emitted.
4319 In case device is a filter node, block-stream modifies the first
4321 non-filter overlay node below it to point to the new backing node in‐
4322 stead of modifying device itself.
4323 Arguments
4325 job-id: string (optional)
4326 identifier for the newly-created block job. If omitted, the de‐
4327 vice name will be used. (Since 2.7)
4328 device: string
4330 the device or node name of the top image
4331 base: string (optional)
4333 the common backing file name. It cannot be set if base-node or
4334 bottom is also set.
4335 base-node: string (optional)
4337 the node name of the backing file. It cannot be set if base or
4338 bottom is also set. (Since 2.8)
4339 bottom: string (optional)
4341 the last node in the chain that should be streamed into top. It
4342 cannot be set if base or base-node is also set. It cannot be
4343 filter node. (Since 6.0)
4344 backing-file: string (optional)
4346 The backing file string to write into the top image. This file‐
4347 name is not validated.
4348 If a pathname string is such that it cannot be resolved by QEMU,
4350 that means that subsequent QMP or HMP commands must use
4351 node-names for the image in question, as filename lookup methods
4352 will fail.
4353 If not specified, QEMU will automatically determine the backing
4355 file string to use, or error out if there is no obvious choice.
4356 Care should be taken when specifying the string, to specify a
4357 valid filename or protocol. (Since 2.1)
4358 speed: int (optional)
4360 the maximum speed, in bytes per second
4361 on-error: BlockdevOnError (optional)
4363 the action to take on an error (default report). 'stop' and
4364 'enospc' can only be used if the block device supports io-status
4365 (see BlockInfo). (Since 1.3)
4366 filter-node-name: string (optional)
4368 the node name that should be assigned to the filter driver that
4369 the stream job inserts into the graph above device. If this op‐
4370 tion is not given, a node name is autogenerated. (Since: 6.0)
4371 auto-finalize: boolean (optional)
4373 When false, this job will wait in a PENDING state after it has
4374 finished its work, waiting for block-job-finalize before making
4375 any block graph changes. When true, this job will automatically
4376 perform its abort or commit actions. Defaults to true. (Since
4377 3.1)
4378 auto-dismiss: boolean (optional)
4380 When false, this job will wait in a CONCLUDED state after it has
4381 completely ceased all work, and awaits block-job-dismiss. When
4382 true, this job will automatically disappear from the query list
4383 without user intervention. Defaults to true. (Since 3.1)
4384 Returns
4386 • Nothing on success.
4387 • If device does not exist, DeviceNotFound.
4389 Since
4391 1.1
4392 Example
4394 -> { "execute": "block-stream",
4395 "arguments": { "device": "virtio0",
4396 "base": "/tmp/master.qcow2" } }
4397 <- { "return": {} }
4398 block-job-set-speed (Command)
4400 Set maximum speed for a background block operation.
4401 This command can only be issued when there is an active block job.
4403 Throttling can be disabled by setting the speed to 0.
4405 Arguments
4407 device: string
4408 The job identifier. This used to be a device name (hence the
4409 name of the parameter), but since QEMU 2.7 it can have other
4410 values.
4411 speed: int
4413 the maximum speed, in bytes per second, or 0 for unlimited. De‐
4414 faults to 0.
4415 Returns
4417 • Nothing on success
4418 • If no background operation is active on this device, DeviceNotActive
4420 Since
4422 1.1
4423 block-job-cancel (Command)
4425 Stop an active background block operation.
4426 This command returns immediately after marking the active background
4428 block operation for cancellation. It is an error to call this command
4429 if no operation is in progress.
4430 The operation will cancel as soon as possible and then emit the
4432 BLOCK_JOB_CANCELLED event. Before that happens the job is still visi‐
4433 ble when enumerated using query-block-jobs.
4434 Note that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
4436 dicated (via the event BLOCK_JOB_READY) that the source and destination
4437 are synchronized, then the event triggered by this command changes to
4438 BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
4439 destination now has a point-in-time copy tied to the time of the can‐
4440 cellation.
4441 For streaming, the image file retains its backing file unless the
4443 streaming operation happens to complete just as it is being cancelled.
4444 A new streaming operation can be started at a later time to finish
4445 copying all data from the backing file.
4446 Arguments
4448 device: string
4449 The job identifier. This used to be a device name (hence the
4450 name of the parameter), but since QEMU 2.7 it can have other
4451 values.
4452 force: boolean (optional)
4454 If true, and the job has already emitted the event
4455 BLOCK_JOB_READY, abandon the job immediately (even if it is
4456 paused) instead of waiting for the destination to complete its
4457 final synchronization (since 1.3)
4458 Returns
4460 • Nothing on success
4461 • If no background operation is active on this device, DeviceNotActive
4463 Since
4465 1.1
4466 block-job-pause (Command)
4468 Pause an active background block operation.
4469 This command returns immediately after marking the active background
4471 block operation for pausing. It is an error to call this command if no
4472 operation is in progress or if the job is already paused.
4473 The operation will pause as soon as possible. No event is emitted when
4475 the operation is actually paused. Cancelling a paused job automati‐
4476 cally resumes it.
4477 Arguments
4479 device: string
4480 The job identifier. This used to be a device name (hence the
4481 name of the parameter), but since QEMU 2.7 it can have other
4482 values.
4483 Returns
4485 • Nothing on success
4486 • If no background operation is active on this device, DeviceNotActive
4488 Since
4490 1.3
4491 block-job-resume (Command)
4493 Resume an active background block operation.
4494 This command returns immediately after resuming a paused background
4496 block operation. It is an error to call this command if no operation
4497 is in progress or if the job is not paused.
4498 This command also clears the error status of the job.
4500 Arguments
4502 device: string
4503 The job identifier. This used to be a device name (hence the
4504 name of the parameter), but since QEMU 2.7 it can have other
4505 values.
4506 Returns
4508 • Nothing on success
4509 • If no background operation is active on this device, DeviceNotActive
4511 Since
4513 1.3
4514 block-job-complete (Command)
4516 Manually trigger completion of an active background block operation.
4517 This is supported for drive mirroring, where it also switches the de‐
4518 vice to write to the target path only. The ability to complete is sig‐
4519 naled with a BLOCK_JOB_READY event.
4520 This command completes an active background block operation syn‐
4522 chronously. The ordering of this command's return with the
4523 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
4524 occurs during the processing of this command: 1) the command itself
4525 will fail; 2) the error will be processed according to the rerror/wer‐
4526 ror arguments that were specified when starting the operation.
4527 A cancelled or paused job cannot be completed.
4529 Arguments
4531 device: string
4532 The job identifier. This used to be a device name (hence the
4533 name of the parameter), but since QEMU 2.7 it can have other
4534 values.
4535 Returns
4537 • Nothing on success
4538 • If no background operation is active on this device, DeviceNotActive
4540 Since
4542 1.3
4543 block-job-dismiss (Command)
4545 For jobs that have already concluded, remove them from the
4546 block-job-query list. This command only needs to be run for jobs which
4547 were started with QEMU 2.12+ job lifetime management semantics.
4548 This command will refuse to operate on any job that has not yet reached
4550 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
4551 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
4552 still need to be used as appropriate.
4553 Arguments
4555 id: string
4556 The job identifier.
4557 Returns
4559 Nothing on success
4560 Since
4562 2.12
4563 block-job-finalize (Command)
4565 Once a job that has manual=true reaches the pending state, it can be
4566 instructed to finalize any graph changes and do any necessary cleanup
4567 via this command. For jobs in a transaction, instructing one job to
4568 finalize will force ALL jobs in the transaction to finalize, so it is
4569 only necessary to instruct a single member job to finalize.
4570 Arguments
4572 id: string
4573 The job identifier.
4574 Returns
4576 Nothing on success
4577 Since
4579 2.12
4580 BlockdevDiscardOptions (Enum)
4582 Determines how to handle discard requests.
4583 Values
4585 ignore Ignore the request
4586 unmap Forward as an unmap request
4588 Since
4590 2.9
4591 BlockdevDetectZeroesOptions (Enum)
4593 Describes the operation mode for the automatic conversion of plain zero
4594 writes by the OS to driver specific optimized zero write commands.
4595 Values
4597 off Disabled (default)
4598 on Enabled
4600 unmap Enabled and even try to unmap blocks if possible. This requires
4602 also that BlockdevDiscardOptions is set to unmap for this de‐
4603 vice.
4604 Since
4606 2.1
4607 BlockdevAioOptions (Enum)
4609 Selects the AIO backend to handle I/O requests
4610 Values
4612 threads
4613 Use qemu's thread pool
4614 native Use native AIO backend (only Linux and Windows)
4616 io_uring (If: CONFIG_LINUX_IO_URING)
4618 Use linux io_uring (since 5.0)
4619 Since
4621 2.9
4622 BlockdevCacheOptions (Object)
4624 Includes cache-related options for block devices
4625 Members
4627 direct: boolean (optional)
4628 enables use of O_DIRECT (bypass the host page cache; default:
4629 false)
4630 no-flush: boolean (optional)
4632 ignore any flush requests for the device (default: false)
4633 Since
4635 2.9
4636 BlockdevDriver (Enum)
4638 Drivers that are supported in block device operations.
4639 Values
4641 throttle
4642 Since 2.11
4643 nvme Since 2.12
4645 copy-on-read
4647 Since 3.0
4648 blklogwrites
4650 Since 3.0
4651 blkreplay
4653 Since 4.2
4654 compress
4656 Since 5.0
4657 copy-before-write
4659 Since 6.2
4660 snapshot-access
4662 Since 7.0
4663 blkdebug
4665 Not documented
4666 blkverify
4668 Not documented
4669 bochs Not documented
4671 cloop Not documented
4673 dmg Not documented
4675 file Not documented
4677 ftp Not documented
4679 ftps Not documented
4681 gluster
4683 Not documented
4684 host_cdrom (If: HAVE_HOST_BLOCK_DEVICE)
4686 Not documented
4687 host_device (If: HAVE_HOST_BLOCK_DEVICE)
4689 Not documented
4690 http Not documented
4692 https Not documented
4694 io_uring (If: CONFIG_BLKIO)
4696 Not documented
4697 iscsi Not documented
4699 luks Not documented
4701 nbd Not documented
4703 nfs Not documented
4705 null-aio
4707 Not documented
4708 null-co
4710 Not documented
4711 nvme-io_uring (If: CONFIG_BLKIO)
4713 Not documented
4714 parallels
4716 Not documented
4717 preallocate
4719 Not documented
4720 qcow Not documented
4722 qcow2 Not documented
4724 qed Not documented
4726 quorum Not documented
4728 raw Not documented
4730 rbd Not documented
4732 replication (If: CONFIG_REPLICATION)
4734 Not documented
4735 ssh Not documented
4737 vdi Not documented
4739 vhdx Not documented
4741 virtio-blk-vfio-pci (If: CONFIG_BLKIO)
4743 Not documented
4744 virtio-blk-vhost-user (If: CONFIG_BLKIO)
4746 Not documented
4747 virtio-blk-vhost-vdpa (If: CONFIG_BLKIO)
4749 Not documented
4750 vmdk Not documented
4752 vpc Not documented
4754 vvfat Not documented
4756 Since
4758 2.9
4759 BlockdevOptionsFile (Object)
4761 Driver specific block device options for the file backend.
4762 Members
4764 filename: string
4765 path to the image file
4766 pr-manager: string (optional)
4768 the id for the object that will handle persistent reservations
4769 for this device (default: none, forward the commands via SG_IO;
4770 since 2.11)
4771 aio: BlockdevAioOptions (optional)
4773 AIO backend (default: threads) (since: 2.8)
4774 aio-max-batch: int (optional)
4776 maximum number of requests to batch together into a single sub‐
4777 mission in the AIO backend. The smallest value between this and
4778 the aio-max-batch value of the IOThread object is chosen. 0
4779 means that the AIO backend will handle it automatically. (de‐
4780 fault: 0, since 6.2)
4781 locking: OnOffAuto (optional)
4783 whether to enable file locking. If set to 'auto', only enable
4784 when Open File Descriptor (OFD) locking API is available (de‐
4785 fault: auto, since 2.10)
4786 drop-cache: boolean (optional) (If: CONFIG_LINUX)
4788 invalidate page cache during live migration. This prevents
4789 stale data on the migration destination with cache.direct=off.
4790 Currently only supported on Linux hosts. (default: on, since:
4791 4.0)
4792 x-check-cache-dropped: boolean (optional)
4794 whether to check that page cache was dropped on live migration.
4795 May cause noticeable delays if the image file is large, do not
4796 use in production. (default: off) (since: 3.0)
4797 Features
4799 dynamic-auto-read-only
4800 If present, enabled auto-read-only means that the driver will
4801 open the image read-only at first, dynamically reopen the image
4802 file read-write when the first writer is attached to the node
4803 and reopen read-only when the last writer is detached. This al‐
4804 lows giving QEMU write permissions only on demand when an opera‐
4805 tion actually needs write access.
4806 unstable
4808 Member x-check-cache-dropped is meant for debugging.
4809 Since
4811 2.9
4812 BlockdevOptionsNull (Object)
4814 Driver specific block device options for the null backend.
4815 Members
4817 size: int (optional)
4818 size of the device in bytes.
4819 latency-ns: int (optional)
4821 emulated latency (in nanoseconds) in processing requests. De‐
4822 fault to zero which completes requests immediately. (Since 2.4)
4823 read-zeroes: boolean (optional)
4825 if true, reads from the device produce zeroes; if false, the
4826 buffer is left unchanged. (default: false; since: 4.1)
4827 Since
4829 2.9
4830 BlockdevOptionsNVMe (Object)
4832 Driver specific block device options for the NVMe backend.
4833 Members
4835 device: string
4836 PCI controller address of the NVMe device in format hhhh:bb:ss.f
4837 (host:bus:slot.function)
4838 namespace: int
4840 namespace number of the device, starting from 1.
4841 Note that the PCI device must have been unbound from any host kernel
4842 driver before instructing QEMU to add the blockdev.
4843 Since
4845 2.12
4846 BlockdevOptionsVVFAT (Object)
4848 Driver specific block device options for the vvfat protocol.
4849 Members
4851 dir: string
4852 directory to be exported as FAT image
4853 fat-type: int (optional)
4855 FAT type: 12, 16 or 32
4856 floppy: boolean (optional)
4858 whether to export a floppy image (true) or partitioned hard disk
4859 (false; default)
4860 label: string (optional)
4862 set the volume label, limited to 11 bytes. FAT16 and FAT32 tra‐
4863 ditionally have some restrictions on labels, which are ignored
4864 by most operating systems. Defaults to "QEMU VVFAT". (since
4865 2.4)
4866 rw: boolean (optional)
4868 whether to allow write operations (default: false)
4869 Since
4871 2.9
4872 BlockdevOptionsGenericFormat (Object)
4874 Driver specific block device options for image format that have no op‐
4875 tion besides their data source.
4876 Members
4878 file: BlockdevRef
4879 reference to or definition of the data source block device
4880 Since
4882 2.9
4883 BlockdevOptionsLUKS (Object)
4885 Driver specific block device options for LUKS.
4886 Members
4888 key-secret: string (optional)
4889 the ID of a QCryptoSecret object providing the decryption key
4890 (since 2.6). Mandatory except when doing a metadata-only probe
4891 of the image.
4892 The members of BlockdevOptionsGenericFormat
4894 Since
4896 2.9
4897 BlockdevOptionsGenericCOWFormat (Object)
4899 Driver specific block device options for image format that have no op‐
4900 tion besides their data source and an optional backing file.
4901 Members
4903 backing: BlockdevRefOrNull (optional)
4904 reference to or definition of the backing file block device,
4905 null disables the backing file entirely. Defaults to the back‐
4906 ing file stored the image file.
4907 The members of BlockdevOptionsGenericFormat
4909 Since
4911 2.9
4912 Qcow2OverlapCheckMode (Enum)
4914 General overlap check modes.
4915 Values
4917 none Do not perform any checks
4918 constant
4920 Perform only checks which can be done in constant time and with‐
4921 out reading anything from disk
4922 cached Perform only checks which can be done without reading anything
4924 from disk
4925 all Perform all available overlap checks
4927 Since
4929 2.9
4930 Qcow2OverlapCheckFlags (Object)
4932 Structure of flags for each metadata structure. Setting a field to
4933 'true' makes qemu guard that structure against unintended overwriting.
4934 The default value is chosen according to the template given.
4935 Members
4937 template: Qcow2OverlapCheckMode (optional)
4938 Specifies a template mode which can be adjusted using the other
4939 flags, defaults to 'cached'
4940 bitmap-directory: boolean (optional)
4942 since 3.0
4943 main-header: boolean (optional)
4945 Not documented
4946 active-l1: boolean (optional)
4948 Not documented
4949 active-l2: boolean (optional)
4951 Not documented
4952 refcount-table: boolean (optional)
4954 Not documented
4955 refcount-block: boolean (optional)
4957 Not documented
4958 snapshot-table: boolean (optional)
4960 Not documented
4961 inactive-l1: boolean (optional)
4963 Not documented
4964 inactive-l2: boolean (optional)
4966 Not documented
4967 Since
4969 2.9
4970 Qcow2OverlapChecks (Alternate)
4972 Specifies which metadata structures should be guarded against unin‐
4973 tended overwriting.
4974 Members
4976 flags: Qcow2OverlapCheckFlags
4977 set of flags for separate specification of each metadata struc‐
4978 ture type
4979 mode: Qcow2OverlapCheckMode
4981 named mode which chooses a specific set of flags
4982 Since
4984 2.9
4985 BlockdevQcowEncryptionFormat (Enum)
4987 Values
4988 aes AES-CBC with plain64 initialization vectors
4989 Since
4991 2.10
4992 BlockdevQcowEncryption (Object)
4994 Members
4995 format: BlockdevQcowEncryptionFormat
4996 Not documented
4997 The members of QCryptoBlockOptionsQCow when format is "aes"
4999 Since
5001 2.10
5002 BlockdevOptionsQcow (Object)
5004 Driver specific block device options for qcow.
5005 Members
5007 encrypt: BlockdevQcowEncryption (optional)
5008 Image decryption options. Mandatory for encrypted images, ex‐
5009 cept when doing a metadata-only probe of the image.
5010 The members of BlockdevOptionsGenericCOWFormat
5012 Since
5014 2.10
5015 BlockdevQcow2EncryptionFormat (Enum)
5017 Values
5018 aes AES-CBC with plain64 initialization vectors
5019 luks Not documented
5021 Since
5023 2.10
5024 BlockdevQcow2Encryption (Object)
5026 Members
5027 format: BlockdevQcow2EncryptionFormat
5028 Not documented
5029 The members of QCryptoBlockOptionsQCow when format is "aes"
5031 The members of QCryptoBlockOptionsLUKS when format is "luks"
5033 Since
5035 2.10
5036 BlockdevOptionsPreallocate (Object)
5038 Filter driver intended to be inserted between format and protocol node
5039 and do preallocation in protocol node on write.
5040 Members
5042 prealloc-align: int (optional)
5043 on preallocation, align file length to this number, default
5044 1048576 (1M)
5045 prealloc-size: int (optional)
5047 how much to preallocate, default 134217728 (128M)
5048 The members of BlockdevOptionsGenericFormat
5050 Since
5052 6.0
5053 BlockdevOptionsQcow2 (Object)
5055 Driver specific block device options for qcow2.
5056 Members
5058 lazy-refcounts: boolean (optional)
5059 whether to enable the lazy refcounts feature (default is taken
5060 from the image file)
5061 pass-discard-request: boolean (optional)
5063 whether discard requests to the qcow2 device should be forwarded
5064 to the data source
5065 pass-discard-snapshot: boolean (optional)
5067 whether discard requests for the data source should be issued
5068 when a snapshot operation (e.g. deleting a snapshot) frees clus‐
5069 ters in the qcow2 file
5070 pass-discard-other: boolean (optional)
5072 whether discard requests for the data source should be issued on
5073 other occasions where a cluster gets freed
5074 discard-no-unref: boolean (optional)
5076 when enabled, data clusters will remain preallocated when they
5077 are no longer used, e.g. because they are discarded or converted
5078 to zero clusters. As usual, whether the old data is discarded
5079 or kept on the protocol level (i.e. in the image file) depends
5080 on the setting of the pass-discard-request option. Keeping the
5081 clusters preallocated prevents qcow2 fragmentation that would
5082 otherwise be caused by freeing and re-allocating them later.
5083 Besides potential performance degradation, such fragmentation
5084 can lead to increased allocation of clusters past the end of the
5085 image file, resulting in image files whose file length can grow
5086 much larger than their guest disk size would suggest. If image
5087 file length is of concern (e.g. when storing qcow2 images di‐
5088 rectly on block devices), you should consider enabling this op‐
5089 tion. (since 8.1)
5090 overlap-check: Qcow2OverlapChecks (optional)
5092 which overlap checks to perform for writes to the image, de‐
5093 faults to 'cached' (since 2.2)
5094 cache-size: int (optional)
5096 the maximum total size of the L2 table and refcount block caches
5097 in bytes (since 2.2)
5098 l2-cache-size: int (optional)
5100 the maximum size of the L2 table cache in bytes (since 2.2)
5101 l2-cache-entry-size: int (optional)
5103 the size of each entry in the L2 cache in bytes. It must be a
5104 power of two between 512 and the cluster size. The default
5105 value is the cluster size (since 2.12)
5106 refcount-cache-size: int (optional)
5108 the maximum size of the refcount block cache in bytes (since
5109 2.2)
5110 cache-clean-interval: int (optional)
5112 clean unused entries in the L2 and refcount caches. The inter‐
5113 val is in seconds. The default value is 600 on supporting plat‐
5114 forms, and 0 on other platforms. 0 disables this feature.
5115 (since 2.5)
5116 encrypt: BlockdevQcow2Encryption (optional)
5118 Image decryption options. Mandatory for encrypted images, ex‐
5119 cept when doing a metadata-only probe of the image. (since
5120 2.10)
5121 data-file: BlockdevRef (optional)
5123 reference to or definition of the external data file. This may
5124 only be specified for images that require an external data file.
5125 If it is not specified for such an image, the data file name is
5126 loaded from the image file. (since 4.0)
5127 The members of BlockdevOptionsGenericCOWFormat
5129 Since
5131 2.9
5132 SshHostKeyCheckMode (Enum)
5134 Values
5135 none Don't check the host key at all
5136 hash Compare the host key with a given hash
5138 known_hosts
5140 Check the host key against the known_hosts file
5141 Since
5143 2.12
5144 SshHostKeyCheckHashType (Enum)
5146 Values
5147 md5 The given hash is an md5 hash
5148 sha1 The given hash is an sha1 hash
5150 sha256 The given hash is an sha256 hash
5152 Since
5154 2.12
5155 SshHostKeyHash (Object)
5157 Members
5158 type: SshHostKeyCheckHashType
5159 The hash algorithm used for the hash
5160 hash: string
5162 The expected hash value
5163 Since
5165 2.12
5166 SshHostKeyCheck (Object)
5168 Members
5169 mode: SshHostKeyCheckMode
5170 Not documented
5171 The members of SshHostKeyHash when mode is "hash"
5173 Since
5175 2.12
5176 BlockdevOptionsSsh (Object)
5178 Members
5179 server: InetSocketAddress
5180 host address
5181 path: string
5183 path to the image on the host
5184 user: string (optional)
5186 user as which to connect, defaults to current local user name
5187 host-key-check: SshHostKeyCheck (optional)
5189 Defines how and what to check the host key against (default:
5190 known_hosts)
5191 Since
5193 2.9
5194 BlkdebugEvent (Enum)
5196 Trigger events supported by blkdebug.
5197 Values
5199 l1_shrink_write_table
5200 write zeros to the l1 table to shrink image. (since 2.11)
5201 l1_shrink_free_l2_clusters
5203 discard the l2 tables. (since 2.11)
5204 cor_write
5206 a write due to copy-on-read (since 2.11)
5207 cluster_alloc_space
5209 an allocation of file space for a cluster (since 4.1)
5210 none triggers once at creation of the blkdebug node (since 4.1)
5212 l1_update
5214 Not documented
5215 l1_grow_alloc_table
5217 Not documented
5218 l1_grow_write_table
5220 Not documented
5221 l1_grow_activate_table
5223 Not documented
5224 l2_load
5226 Not documented
5227 l2_update
5229 Not documented
5230 l2_update_compressed
5232 Not documented
5233 l2_alloc_cow_read
5235 Not documented
5236 l2_alloc_write
5238 Not documented
5239 read_aio
5241 Not documented
5242 read_backing_aio
5244 Not documented
5245 read_compressed
5247 Not documented
5248 write_aio
5250 Not documented
5251 write_compressed
5253 Not documented
5254 vmstate_load
5256 Not documented
5257 vmstate_save
5259 Not documented
5260 cow_read
5262 Not documented
5263 cow_write
5265 Not documented
5266 reftable_load
5268 Not documented
5269 reftable_grow
5271 Not documented
5272 reftable_update
5274 Not documented
5275 refblock_load
5277 Not documented
5278 refblock_update
5280 Not documented
5281 refblock_update_part
5283 Not documented
5284 refblock_alloc
5286 Not documented
5287 refblock_alloc_hookup
5289 Not documented
5290 refblock_alloc_write
5292 Not documented
5293 refblock_alloc_write_blocks
5295 Not documented
5296 refblock_alloc_write_table
5298 Not documented
5299 refblock_alloc_switch_table
5301 Not documented
5302 cluster_alloc
5304 Not documented
5305 cluster_alloc_bytes
5307 Not documented
5308 cluster_free
5310 Not documented
5311 flush_to_os
5313 Not documented
5314 flush_to_disk
5316 Not documented
5317 pwritev_rmw_head
5319 Not documented
5320 pwritev_rmw_after_head
5322 Not documented
5323 pwritev_rmw_tail
5325 Not documented
5326 pwritev_rmw_after_tail
5328 Not documented
5329 pwritev
5331 Not documented
5332 pwritev_zero
5334 Not documented
5335 pwritev_done
5337 Not documented
5338 empty_image_prepare
5340 Not documented
5341 Since
5343 2.9
5344 BlkdebugIOType (Enum)
5346 Kinds of I/O that blkdebug can inject errors in.
5347 Values
5349 read .bdrv_co_preadv()
5350 write .bdrv_co_pwritev()
5352 write-zeroes
5354 .bdrv_co_pwrite_zeroes()
5355 discard
5357 .bdrv_co_pdiscard()
5358 flush .bdrv_co_flush_to_disk()
5360 block-status
5362 .bdrv_co_block_status()
5363 Since
5365 4.1
5366 BlkdebugInjectErrorOptions (Object)
5368 Describes a single error injection for blkdebug.
5369 Members
5371 event: BlkdebugEvent
5372 trigger event
5373 state: int (optional)
5375 the state identifier blkdebug needs to be in to actually trigger
5376 the event; defaults to "any"
5377 iotype: BlkdebugIOType (optional)
5379 the type of I/O operations on which this error should be in‐
5380 jected; defaults to "all read, write, write-zeroes, discard, and
5381 flush operations" (since: 4.1)
5382 errno: int (optional)
5384 error identifier (errno) to be returned; defaults to EIO
5385 sector: int (optional)
5387 specifies the sector index which has to be affected in order to
5388 actually trigger the event; defaults to "any sector"
5389 once: boolean (optional)
5391 disables further events after this one has been triggered; de‐
5392 faults to false
5393 immediately: boolean (optional)
5395 fail immediately; defaults to false
5396 Since
5398 2.9
5399 BlkdebugSetStateOptions (Object)
5401 Describes a single state-change event for blkdebug.
5402 Members
5404 event: BlkdebugEvent
5405 trigger event
5406 state: int (optional)
5408 the current state identifier blkdebug needs to be in; defaults
5409 to "any"
5410 new_state: int
5412 the state identifier blkdebug is supposed to assume if this
5413 event is triggered
5414 Since
5416 2.9
5417 BlockdevOptionsBlkdebug (Object)
5419 Driver specific block device options for blkdebug.
5420 Members
5422 image: BlockdevRef
5423 underlying raw block device (or image file)
5424 config: string (optional)
5426 filename of the configuration file
5427 align: int (optional)
5429 required alignment for requests in bytes, must be positive power
5430 of 2, or 0 for default
5431 max-transfer: int (optional)
5433 maximum size for I/O transfers in bytes, must be positive multi‐
5434 ple of align and of the underlying file's request alignment (but
5435 need not be a power of 2), or 0 for default (since 2.10)
5436 opt-write-zero: int (optional)
5438 preferred alignment for write zero requests in bytes, must be
5439 positive multiple of align and of the underlying file's request
5440 alignment (but need not be a power of 2), or 0 for default
5441 (since 2.10)
5442 max-write-zero: int (optional)
5444 maximum size for write zero requests in bytes, must be positive
5445 multiple of align, of opt-write-zero, and of the underlying
5446 file's request alignment (but need not be a power of 2), or 0
5447 for default (since 2.10)
5448 opt-discard: int (optional)
5450 preferred alignment for discard requests in bytes, must be posi‐
5451 tive multiple of align and of the underlying file's request
5452 alignment (but need not be a power of 2), or 0 for default
5453 (since 2.10)
5454 max-discard: int (optional)
5456 maximum size for discard requests in bytes, must be positive
5457 multiple of align, of opt-discard, and of the underlying file's
5458 request alignment (but need not be a power of 2), or 0 for de‐
5459 fault (since 2.10)
5460 inject-error: array of BlkdebugInjectErrorOptions (optional)
5462 array of error injection descriptions
5463 set-state: array of BlkdebugSetStateOptions (optional)
5465 array of state-change descriptions
5466 take-child-perms: array of BlockPermission (optional)
5468 Permissions to take on image in addition to what is necessary
5469 anyway (which depends on how the blkdebug node is used). De‐
5470 faults to none. (since 5.0)
5471 unshare-child-perms: array of BlockPermission (optional)
5473 Permissions not to share on image in addition to what cannot be
5474 shared anyway (which depends on how the blkdebug node is used).
5475 Defaults to none. (since 5.0)
5476 Since
5478 2.9
5479 BlockdevOptionsBlklogwrites (Object)
5481 Driver specific block device options for blklogwrites.
5482 Members
5484 file: BlockdevRef
5485 block device
5486 log: BlockdevRef
5488 block device used to log writes to file
5489 log-sector-size: int (optional)
5491 sector size used in logging writes to file, determines granular‐
5492 ity of offsets and sizes of writes (default: 512)
5493 log-append: boolean (optional)
5495 append to an existing log (default: false)
5496 log-super-update-interval: int (optional)
5498 interval of write requests after which the log super block is
5499 updated to disk (default: 4096)
5500 Since
5502 3.0
5503 BlockdevOptionsBlkverify (Object)
5505 Driver specific block device options for blkverify.
5506 Members
5508 test: BlockdevRef
5509 block device to be tested
5510 raw: BlockdevRef
5512 raw image used for verification
5513 Since
5515 2.9
5516 BlockdevOptionsBlkreplay (Object)
5518 Driver specific block device options for blkreplay.
5519 Members
5521 image: BlockdevRef
5522 disk image which should be controlled with blkreplay
5523 Since
5525 4.2
5526 QuorumReadPattern (Enum)
5528 An enumeration of quorum read patterns.
5529 Values
5531 quorum read all the children and do a quorum vote on reads
5532 fifo read only from the first child that has not failed
5534 Since
5536 2.9
5537 BlockdevOptionsQuorum (Object)
5539 Driver specific block device options for Quorum
5540 Members
5542 blkverify: boolean (optional)
5543 true if the driver must print content mismatch set to false by
5544 default
5545 children: array of BlockdevRef
5547 the children block devices to use
5548 vote-threshold: int
5550 the vote limit under which a read will fail
5551 rewrite-corrupted: boolean (optional)
5553 rewrite corrupted data when quorum is reached (Since 2.1)
5554 read-pattern: QuorumReadPattern (optional)
5556 choose read pattern and set to quorum by default (Since 2.2)
5557 Since
5559 2.9
5560 BlockdevOptionsGluster (Object)
5562 Driver specific block device options for Gluster
5563 Members
5565 volume: string
5566 name of gluster volume where VM image resides
5567 path: string
5569 absolute path to image file in gluster volume
5570 server: array of SocketAddress
5572 gluster servers description
5573 debug: int (optional)
5575 libgfapi log level (default '4' which is Error) (Since 2.8)
5576 logfile: string (optional)
5578 libgfapi log file (default /dev/stderr) (Since 2.8)
5579 Since
5581 2.9
5582 BlockdevOptionsIoUring (Object)
5584 Driver specific block device options for the io_uring backend.
5585 Members
5587 filename: string
5588 path to the image file
5589 Since
5591 7.2
5592 If
5594 CONFIG_BLKIO
5595 BlockdevOptionsNvmeIoUring (Object)
5597 Driver specific block device options for the nvme-io_uring backend.
5598 Members
5600 path: string
5601 path to the NVMe namespace's character device (e.g.
5602 /dev/ng0n1).
5603 Since
5605 7.2
5606 If
5608 CONFIG_BLKIO
5609 BlockdevOptionsVirtioBlkVfioPci (Object)
5611 Driver specific block device options for the virtio-blk-vfio-pci back‐
5612 end.
5613 Members
5615 path: string
5616 path to the PCI device's sysfs directory (e.g. /sys/bus/pci/de‐
5617 vices/0000:00:01.0).
5618 Since
5620 7.2
5621 If
5623 CONFIG_BLKIO
5624 BlockdevOptionsVirtioBlkVhostUser (Object)
5626 Driver specific block device options for the virtio-blk-vhost-user
5627 backend.
5628 Members
5630 path: string
5631 path to the vhost-user UNIX domain socket.
5632 Since
5634 7.2
5635 If
5637 CONFIG_BLKIO
5638 BlockdevOptionsVirtioBlkVhostVdpa (Object)
5640 Driver specific block device options for the virtio-blk-vhost-vdpa
5641 backend.
5642 Members
5644 path: string
5645 path to the vhost-vdpa character device.
5646 Features
5648 fdset Member path supports the special "/dev/fdset/N" path (since 8.1)
5649 Since
5651 7.2
5652 If
5654 CONFIG_BLKIO
5655 IscsiTransport (Enum)
5657 An enumeration of libiscsi transport types
5658 Values
5660 tcp Not documented
5661 iser Not documented
5663 Since
5665 2.9
5666 IscsiHeaderDigest (Enum)
5668 An enumeration of header digests supported by libiscsi
5669 Values
5671 crc32c Not documented
5672 none Not documented
5674 crc32c-none
5676 Not documented
5677 none-crc32c
5679 Not documented
5680 Since
5682 2.9
5683 BlockdevOptionsIscsi (Object)
5685 Members
5686 transport: IscsiTransport
5687 The iscsi transport type
5688 portal: string
5690 The address of the iscsi portal
5691 target: string
5693 The target iqn name
5694 lun: int (optional)
5696 LUN to connect to. Defaults to 0.
5697 user: string (optional)
5699 User name to log in with. If omitted, no CHAP authentication is
5700 performed.
5701 password-secret: string (optional)
5703 The ID of a QCryptoSecret object providing the password for the
5704 login. This option is required if user is specified.
5705 initiator-name: string (optional)
5707 The iqn name we want to identify to the target as. If this op‐
5708 tion is not specified, an initiator name is generated automati‐
5709 cally.
5710 header-digest: IscsiHeaderDigest (optional)
5712 The desired header digest. Defaults to none-crc32c.
5713 timeout: int (optional)
5715 Timeout in seconds after which a request will timeout. 0 means
5716 no timeout and is the default.
5717 Driver specific block device options for iscsi
5718 Since
5720 2.9
5721 RbdAuthMode (Enum)
5723 Values
5724 cephx Not documented
5725 none Not documented
5727 Since
5729 3.0
5730 RbdImageEncryptionFormat (Enum)
5732 Values
5733 luks-any
5734 Used for opening either luks or luks2 (Since 8.0)
5735 luks Not documented
5737 luks2 Not documented
5739 Since
5741 6.1
5742 RbdEncryptionOptionsLUKSBase (Object)
5744 Members
5745 key-secret: string
5746 ID of a QCryptoSecret object providing a passphrase for unlock‐
5747 ing the encryption
5748 Since
5750 6.1
5751 RbdEncryptionCreateOptionsLUKSBase (Object)
5753 Members
5754 cipher-alg: QCryptoCipherAlgorithm (optional)
5755 The encryption algorithm
5756 The members of RbdEncryptionOptionsLUKSBase
5758 Since
5760 6.1
5761 RbdEncryptionOptionsLUKS (Object)
5763 Members
5764 The members of RbdEncryptionOptionsLUKSBase
5765 Since
5767 6.1
5768 RbdEncryptionOptionsLUKS2 (Object)
5770 Members
5771 The members of RbdEncryptionOptionsLUKSBase
5772 Since
5774 6.1
5775 RbdEncryptionOptionsLUKSAny (Object)
5777 Members
5778 The members of RbdEncryptionOptionsLUKSBase
5779 Since
5781 8.0
5782 RbdEncryptionCreateOptionsLUKS (Object)
5784 Members
5785 The members of RbdEncryptionCreateOptionsLUKSBase
5786 Since
5788 6.1
5789 RbdEncryptionCreateOptionsLUKS2 (Object)
5791 Members
5792 The members of RbdEncryptionCreateOptionsLUKSBase
5793 Since
5795 6.1
5796 RbdEncryptionOptions (Object)
5798 Members
5799 format: RbdImageEncryptionFormat
5800 Encryption format.
5801 parent: RbdEncryptionOptions (optional)
5803 Parent image encryption options (for cloned images). Can be
5804 left unspecified if this cloned image is encrypted using the
5805 same format and secret as its parent image (i.e. not explicitly
5806 formatted) or if its parent image is not encrypted. (Since 8.0)
5807 The members of RbdEncryptionOptionsLUKS when format is "luks"
5809 The members of RbdEncryptionOptionsLUKS2 when format is "luks2"
5811 The members of RbdEncryptionOptionsLUKSAny when format is "luks-any"
5813 Since
5815 6.1
5816 RbdEncryptionCreateOptions (Object)
5818 Members
5819 format: RbdImageEncryptionFormat
5820 Not documented
5821 The members of RbdEncryptionCreateOptionsLUKS when format is "luks"
5823 The members of RbdEncryptionCreateOptionsLUKS2 when format is "luks2"
5825 Since
5827 6.1
5828 BlockdevOptionsRbd (Object)
5830 Members
5831 pool: string
5832 Ceph pool name.
5833 namespace: string (optional)
5835 Rados namespace name in the Ceph pool. (Since 5.0)
5836 image: string
5838 Image name in the Ceph pool.
5839 conf: string (optional)
5841 path to Ceph configuration file. Values in the configuration
5842 file will be overridden by options specified via QAPI.
5843 snapshot: string (optional)
5845 Ceph snapshot name.
5846 encrypt: RbdEncryptionOptions (optional)
5848 Image encryption options. (Since 6.1)
5849 user: string (optional)
5851 Ceph id name.
5852 auth-client-required: array of RbdAuthMode (optional)
5854 Acceptable authentication modes. This maps to Ceph configura‐
5855 tion option "auth_client_required". (Since 3.0)
5856 key-secret: string (optional)
5858 ID of a QCryptoSecret object providing a key for cephx authenti‐
5859 cation. This maps to Ceph configuration option "key". (Since
5860 3.0)
5861 server: array of InetSocketAddressBase (optional)
5863 Monitor host address and port. This maps to the "mon_host" Ceph
5864 option.
5865 Since
5867 2.9
5868 ReplicationMode (Enum)
5870 An enumeration of replication modes.
5871 Values
5873 primary
5874 Primary mode, the vm's state will be sent to secondary QEMU.
5875 secondary
5877 Secondary mode, receive the vm's state from primary QEMU.
5878 Since
5880 2.9
5881 If
5883 CONFIG_REPLICATION
5884 BlockdevOptionsReplication (Object)
5886 Driver specific block device options for replication
5887 Members
5889 mode: ReplicationMode
5890 the replication mode
5891 top-id: string (optional)
5893 In secondary mode, node name or device ID of the root node who
5894 owns the replication node chain. Must not be given in primary
5895 mode.
5896 The members of BlockdevOptionsGenericFormat
5898 Since
5900 2.9
5901 If
5903 CONFIG_REPLICATION
5904 NFSTransport (Enum)
5906 An enumeration of NFS transport types
5907 Values
5909 inet TCP transport
5910 Since
5912 2.9
5913 NFSServer (Object)
5915 Captures the address of the socket
5916 Members
5918 type: NFSTransport
5919 transport type used for NFS (only TCP supported)
5920 host: string
5922 host address for NFS server
5923 Since
5925 2.9
5926 BlockdevOptionsNfs (Object)
5928 Driver specific block device option for NFS
5929 Members
5931 server: NFSServer
5932 host address
5933 path: string
5935 path of the image on the host
5936 user: int (optional)
5938 UID value to use when talking to the server (defaults to 65534
5939 on Windows and getuid() on unix)
5940 group: int (optional)
5942 GID value to use when talking to the server (defaults to 65534
5943 on Windows and getgid() in unix)
5944 tcp-syn-count: int (optional)
5946 number of SYNs during the session establishment (defaults to
5947 libnfs default)
5948 readahead-size: int (optional)
5950 set the readahead size in bytes (defaults to libnfs default)
5951 page-cache-size: int (optional)
5953 set the pagecache size in bytes (defaults to libnfs default)
5954 debug: int (optional)
5956 set the NFS debug level (max 2) (defaults to libnfs default)
5957 Since
5959 2.9
5960 BlockdevOptionsCurlBase (Object)
5962 Driver specific block device options shared by all protocols supported
5963 by the curl backend.
5964 Members
5966 url: string
5967 URL of the image file
5968 readahead: int (optional)
5970 Size of the read-ahead cache; must be a multiple of 512 (de‐
5971 faults to 256 kB)
5972 timeout: int (optional)
5974 Timeout for connections, in seconds (defaults to 5)
5975 username: string (optional)
5977 Username for authentication (defaults to none)
5978 password-secret: string (optional)
5980 ID of a QCryptoSecret object providing a password for authenti‐
5981 cation (defaults to no password)
5982 proxy-username: string (optional)
5984 Username for proxy authentication (defaults to none)
5985 proxy-password-secret: string (optional)
5987 ID of a QCryptoSecret object providing a password for proxy au‐
5988 thentication (defaults to no password)
5989 Since
5991 2.9
5992 BlockdevOptionsCurlHttp (Object)
5994 Driver specific block device options for HTTP connections over the curl
5995 backend. URLs must start with "http://".
5996 Members
5998 cookie: string (optional)
5999 List of cookies to set; format is "name1=content1; name2=con‐
6000 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
6001 ies.
6002 cookie-secret: string (optional)
6004 ID of a QCryptoSecret object providing the cookie data in a se‐
6005 cure way. See cookie for the format. (since 2.10)
6006 The members of BlockdevOptionsCurlBase
6008 Since
6010 2.9
6011 BlockdevOptionsCurlHttps (Object)
6013 Driver specific block device options for HTTPS connections over the
6014 curl backend. URLs must start with "https://".
6015 Members
6017 cookie: string (optional)
6018 List of cookies to set; format is "name1=content1; name2=con‐
6019 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
6020 ies.
6021 sslverify: boolean (optional)
6023 Whether to verify the SSL certificate's validity (defaults to
6024 true)
6025 cookie-secret: string (optional)
6027 ID of a QCryptoSecret object providing the cookie data in a se‐
6028 cure way. See cookie for the format. (since 2.10)
6029 The members of BlockdevOptionsCurlBase
6031 Since
6033 2.9
6034 BlockdevOptionsCurlFtp (Object)
6036 Driver specific block device options for FTP connections over the curl
6037 backend. URLs must start with "ftp://".
6038 Members
6040 The members of BlockdevOptionsCurlBase
6041 Since
6043 2.9
6044 BlockdevOptionsCurlFtps (Object)
6046 Driver specific block device options for FTPS connections over the curl
6047 backend. URLs must start with "ftps://".
6048 Members
6050 sslverify: boolean (optional)
6051 Whether to verify the SSL certificate's validity (defaults to
6052 true)
6053 The members of BlockdevOptionsCurlBase
6055 Since
6057 2.9
6058 BlockdevOptionsNbd (Object)
6060 Driver specific block device options for NBD.
6061 Members
6063 server: SocketAddress
6064 NBD server address
6065 export: string (optional)
6067 export name
6068 tls-creds: string (optional)
6070 TLS credentials ID
6071 tls-hostname: string (optional)
6073 TLS hostname override for certificate validation (Since 7.0)
6074 x-dirty-bitmap: string (optional)
6076 A metadata context name such as "qemu:dirty-bitmap:NAME" or
6077 "qemu:allocation-depth" to query in place of the traditional
6078 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
6079 the NBD protocol; and yes, naming this option x-context would
6080 have made more sense) (since 3.0)
6081 reconnect-delay: int (optional)
6083 On an unexpected disconnect, the nbd client tries to connect
6084 again until succeeding or encountering a serious error. During
6085 the first reconnect-delay seconds, all requests are paused and
6086 will be rerun on a successful reconnect. After that time, any
6087 delayed requests and all future requests before a successful re‐
6088 connect will immediately fail. Default 0 (Since 4.2)
6089 open-timeout: int (optional)
6091 In seconds. If zero, the nbd driver tries the connection only
6092 once, and fails to open if the connection fails. If non-zero,
6093 the nbd driver will repeat connection attempts until successful
6094 or until open-timeout seconds have elapsed. Default 0 (Since
6095 7.0)
6096 Features
6098 unstable
6099 Member x-dirty-bitmap is experimental.
6100 Since
6102 2.9
6103 BlockdevOptionsRaw (Object)
6105 Driver specific block device options for the raw driver.
6106 Members
6108 offset: int (optional)
6109 position where the block device starts
6110 size: int (optional)
6112 the assumed size of the device
6113 The members of BlockdevOptionsGenericFormat
6115 Since
6117 2.9
6118 BlockdevOptionsThrottle (Object)
6120 Driver specific block device options for the throttle driver
6121 Members
6123 throttle-group: string
6124 the name of the throttle-group object to use. It must already
6125 exist.
6126 file: BlockdevRef
6128 reference to or definition of the data source block device
6129 Since
6131 2.11
6132 BlockdevOptionsCor (Object)
6134 Driver specific block device options for the copy-on-read driver.
6135 Members
6137 bottom: string (optional)
6138 The name of a non-filter node (allocation-bearing layer) that
6139 limits the COR operations in the backing chain (inclusive), so
6140 that no data below this node will be copied by this filter. If
6141 option is absent, the limit is not applied, so that data from
6142 all backing layers may be copied.
6143 The members of BlockdevOptionsGenericFormat
6145 Since
6147 6.0
6148 OnCbwError (Enum)
6150 An enumeration of possible behaviors for copy-before-write operation
6151 failures.
6152 Values
6154 break-guest-write
6155 report the error to the guest. This way, the guest will not be
6156 able to overwrite areas that cannot be backed up, so the backup
6157 process remains valid.
6158 break-snapshot
6160 continue guest write. Doing so will make the provided snapshot
6161 state invalid and any backup or export process based on it will
6162 finally fail.
6163 Since
6165 7.1
6166 BlockdevOptionsCbw (Object)
6168 Driver specific block device options for the copy-before-write driver,
6169 which does so called copy-before-write operations: when data is written
6170 to the filter, the filter first reads corresponding blocks from its
6171 file child and copies them to target child. After successfully copy‐
6172 ing, the write request is propagated to file child. If copying fails,
6173 the original write request is failed too and no data is written to file
6174 child.
6175 Members
6177 target: BlockdevRef
6178 The target for copy-before-write operations.
6179 bitmap: BlockDirtyBitmap (optional)
6181 If specified, copy-before-write filter will do copy-before-write
6182 operations only for dirty regions of the bitmap. Bitmap size
6183 must be equal to length of file and target child of the filter.
6184 Note also, that bitmap is used only to initialize internal bit‐
6185 map of the process, so further modifications (or removing) of
6186 specified bitmap doesn't influence the filter. (Since 7.0)
6187 on-cbw-error: OnCbwError (optional)
6189 Behavior on failure of copy-before-write operation. Default is
6190 break-guest-write. (Since 7.1)
6191 cbw-timeout: int (optional)
6193 Zero means no limit. Non-zero sets the timeout in seconds for
6194 copy-before-write operation. When a timeout occurs, the respec‐
6195 tive copy-before-write operation will fail, and the on-cbw-error
6196 parameter will decide how this failure is handled. Default 0.
6197 (Since 7.1)
6198 The members of BlockdevOptionsGenericFormat
6200 Since
6202 6.2
6203 BlockdevOptions (Object)
6205 Options for creating a block device. Many options are available for
6206 all block devices, independent of the block driver:
6207 Members
6209 driver: BlockdevDriver
6210 block driver name
6211 node-name: string (optional)
6213 the node name of the new node (Since 2.0). This option is re‐
6214 quired on the top level of blockdev-add. Valid node names start
6215 with an alphabetic character and may contain only alphanumeric
6216 characters, '-', '.' and '_'. Their maximum length is 31 charac‐
6217 ters.
6218 discard: BlockdevDiscardOptions (optional)
6220 discard-related options (default: ignore)
6221 cache: BlockdevCacheOptions (optional)
6223 cache-related options
6224 read-only: boolean (optional)
6226 whether the block device should be read-only (default: false).
6227 Note that some block drivers support only read-only access, ei‐
6228 ther generally or in certain configurations. In this case, the
6229 default value does not work and the option must be specified ex‐
6230 plicitly.
6231 auto-read-only: boolean (optional)
6233 if true and read-only is false, QEMU may automatically decide
6234 not to open the image read-write as requested, but fall back to
6235 read-only instead (and switch between the modes later), e.g. de‐
6236 pending on whether the image file is writable or whether a writ‐
6237 ing user is attached to the node (default: false, since 3.1)
6238 detect-zeroes: BlockdevDetectZeroesOptions (optional)
6240 detect and optimize zero writes (Since 2.1) (default: off)
6241 force-share: boolean (optional)
6243 force share all permission on added nodes. Requires
6244 read-only=true. (Since 2.10)
6245 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
6247 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
6249 writes"
6250 The members of BlockdevOptionsBlkverify when driver is "blkverify"
6252 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
6254 The members of BlockdevOptionsGenericFormat when driver is "bochs"
6256 The members of BlockdevOptionsGenericFormat when driver is "cloop"
6258 The members of BlockdevOptionsGenericFormat when driver is "compress"
6260 The members of BlockdevOptionsCbw when driver is "copy-before-write"
6262 The members of BlockdevOptionsCor when driver is "copy-on-read"
6264 The members of BlockdevOptionsGenericFormat when driver is "dmg"
6266 The members of BlockdevOptionsFile when driver is "file"
6268 The members of BlockdevOptionsCurlFtp when driver is "ftp"
6270 The members of BlockdevOptionsCurlFtps when driver is "ftps"
6272 The members of BlockdevOptionsGluster when driver is "gluster"
6274 The members of BlockdevOptionsFile when driver is "host_cdrom" (If:
6276 HAVE_HOST_BLOCK_DEVICE)
6277 The members of BlockdevOptionsFile when driver is "host_device" (If:
6279 HAVE_HOST_BLOCK_DEVICE)
6280 The members of BlockdevOptionsCurlHttp when driver is "http"
6282 The members of BlockdevOptionsCurlHttps when driver is "https"
6284 The members of BlockdevOptionsIoUring when driver is "io_uring" (If:
6286 CONFIG_BLKIO)
6287 The members of BlockdevOptionsIscsi when driver is "iscsi"
6289 The members of BlockdevOptionsLUKS when driver is "luks"
6291 The members of BlockdevOptionsNbd when driver is "nbd"
6293 The members of BlockdevOptionsNfs when driver is "nfs"
6295 The members of BlockdevOptionsNull when driver is "null-aio"
6297 The members of BlockdevOptionsNull when driver is "null-co"
6299 The members of BlockdevOptionsNVMe when driver is "nvme"
6301 The members of BlockdevOptionsNvmeIoUring when driver is "nvme-io_ur‐
6303 ing" (If: CONFIG_BLKIO)
6304 The members of BlockdevOptionsGenericFormat when driver is "parallels"
6306 The members of BlockdevOptionsPreallocate when driver is "preallocate"
6308 The members of BlockdevOptionsQcow2 when driver is "qcow2"
6310 The members of BlockdevOptionsQcow when driver is "qcow"
6312 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
6314 The members of BlockdevOptionsQuorum when driver is "quorum"
6316 The members of BlockdevOptionsRaw when driver is "raw"
6318 The members of BlockdevOptionsRbd when driver is "rbd"
6320 The members of BlockdevOptionsReplication when driver is "replication"
6322 (If: CONFIG_REPLICATION)
6323 The members of BlockdevOptionsGenericFormat when driver is "snap‐
6325 shot-access"
6326 The members of BlockdevOptionsSsh when driver is "ssh"
6328 The members of BlockdevOptionsThrottle when driver is "throttle"
6330 The members of BlockdevOptionsGenericFormat when driver is "vdi"
6332 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
6334 The members of BlockdevOptionsVirtioBlkVfioPci when driver is "vir‐
6336 tio-blk-vfio-pci" (If: CONFIG_BLKIO)
6337 The members of BlockdevOptionsVirtioBlkVhostUser when driver is "vir‐
6339 tio-blk-vhost-user" (If: CONFIG_BLKIO)
6340 The members of BlockdevOptionsVirtioBlkVhostVdpa when driver is "vir‐
6342 tio-blk-vhost-vdpa" (If: CONFIG_BLKIO)
6343 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
6345 The members of BlockdevOptionsGenericFormat when driver is "vpc"
6347 The members of BlockdevOptionsVVFAT when driver is "vvfat"
6349 Remaining options are determined by the block driver.
6350 Since
6352 2.9
6353 BlockdevRef (Alternate)
6355 Reference to a block device.
6356 Members
6358 definition: BlockdevOptions
6359 defines a new block device inline
6360 reference: string
6362 references the ID of an existing block device
6363 Since
6365 2.9
6366 BlockdevRefOrNull (Alternate)
6368 Reference to a block device.
6369 Members
6371 definition: BlockdevOptions
6372 defines a new block device inline
6373 reference: string
6375 references the ID of an existing block device. An empty string
6376 means that no block device should be referenced. Deprecated;
6377 use null instead.
6378 null: null
6380 No block device should be referenced (since 2.10)
6381 Since
6383 2.9
6384 blockdev-add (Command)
6386 Creates a new block device.
6387 Arguments
6389 The members of BlockdevOptions
6390 Since
6392 2.9
6393 Examples
6395 -> { "execute": "blockdev-add",
6396 "arguments": {
6397 "driver": "qcow2",
6398 "node-name": "test1",
6399 "file": {
6400 "driver": "file",
6401 "filename": "test.qcow2"
6402 }
6403 }
6404 }
6405 <- { "return": {} }
6406 -> { "execute": "blockdev-add",
6408 "arguments": {
6409 "driver": "qcow2",
6410 "node-name": "node0",
6411 "discard": "unmap",
6412 "cache": {
6413 "direct": true
6414 },
6415 "file": {
6416 "driver": "file",
6417 "filename": "/tmp/test.qcow2"
6418 },
6419 "backing": {
6420 "driver": "raw",
6421 "file": {
6422 "driver": "file",
6423 "filename": "/dev/fdset/4"
6424 }
6425 }
6426 }
6427 }
6428 <- { "return": {} }
6430 blockdev-reopen (Command)
6432 Reopens one or more block devices using the given set of options. Any
6433 option not specified will be reset to its default value regardless of
6434 its previous status. If an option cannot be changed or a particular
6435 driver does not support reopening then the command will return an er‐
6436 ror. All devices in the list are reopened in one transaction, so if
6437 one of them fails then the whole transaction is cancelled.
6438 The command receives a list of block devices to reopen. For each one
6440 of them, the top-level node-name option (from BlockdevOptions) must be
6441 specified and is used to select the block device to be reopened. Other
6442 node-name options must be either omitted or set to the current name of
6443 the appropriate node. This command won't change any node name and any
6444 attempt to do it will result in an error.
6445 In the case of options that refer to child nodes, the behavior of this
6447 command depends on the value:
6448 1. A set of options (BlockdevOptions): the child is reopened with
6450 the specified set of options.
6451 2. A reference to the current child: the child is reopened using its
6453 existing set of options.
6454 3. A reference to a different node: the current child is replaced
6456 with the specified one.
6457 4. NULL: the current child (if any) is detached.
6459 Options (1) and (2) are supported in all cases. Option (3) is sup‐
6461 ported for file and backing, and option (4) for backing only.
6462 Unlike with blockdev-add, the backing option must always be present un‐
6464 less the node being reopened does not have a backing file and its image
6465 does not have a default backing file name as part of its metadata.
6466 Arguments
6468 options: array of BlockdevOptions
6469 Not documented
6470 Since
6472 6.1
6473 blockdev-del (Command)
6475 Deletes a block device that has been added using blockdev-add. The
6476 command will fail if the node is attached to a device or is otherwise
6477 being used.
6478 Arguments
6480 node-name: string
6481 Name of the graph node to delete.
6482 Since
6484 2.9
6485 Example
6487 -> { "execute": "blockdev-add",
6488 "arguments": {
6489 "driver": "qcow2",
6490 "node-name": "node0",
6491 "file": {
6492 "driver": "file",
6493 "filename": "test.qcow2"
6494 }
6495 }
6496 }
6497 <- { "return": {} }
6498 -> { "execute": "blockdev-del",
6500 "arguments": { "node-name": "node0" }
6501 }
6502 <- { "return": {} }
6503 BlockdevCreateOptionsFile (Object)
6505 Driver specific image creation options for file.
6506 Members
6508 filename: string
6509 Filename for the new image file
6510 size: int
6512 Size of the virtual disk in bytes
6513 preallocation: PreallocMode (optional)
6515 Preallocation mode for the new image (default: off; allowed val‐
6516 ues: off, falloc (if CONFIG_POSIX_FALLOCATE), full (if CON‐
6517 FIG_POSIX))
6518 nocow: boolean (optional)
6520 Turn off copy-on-write (valid only on btrfs; default: off)
6521 extent-size-hint: int (optional)
6523 Extent size hint to add to the image file; 0 for not adding an
6524 extent size hint (default: 1 MB, since 5.1)
6525 Since
6527 2.12
6528 BlockdevCreateOptionsGluster (Object)
6530 Driver specific image creation options for gluster.
6531 Members
6533 location: BlockdevOptionsGluster
6534 Where to store the new image file
6535 size: int
6537 Size of the virtual disk in bytes
6538 preallocation: PreallocMode (optional)
6540 Preallocation mode for the new image (default: off; allowed val‐
6541 ues: off, falloc (if CONFIG_GLUSTERFS_FALLOCATE), full (if CON‐
6542 FIG_GLUSTERFS_ZEROFILL))
6543 Since
6545 2.12
6546 BlockdevCreateOptionsLUKS (Object)
6548 Driver specific image creation options for LUKS.
6549 Members
6551 file: BlockdevRef
6552 Node to create the image format on
6553 size: int
6555 Size of the virtual disk in bytes
6556 preallocation: PreallocMode (optional)
6558 Preallocation mode for the new image (since: 4.2) (default: off;
6559 allowed values: off, metadata, falloc, full)
6560 The members of QCryptoBlockCreateOptionsLUKS
6562 Since
6564 2.12
6565 BlockdevCreateOptionsNfs (Object)
6567 Driver specific image creation options for NFS.
6568 Members
6570 location: BlockdevOptionsNfs
6571 Where to store the new image file
6572 size: int
6574 Size of the virtual disk in bytes
6575 Since
6577 2.12
6578 BlockdevCreateOptionsParallels (Object)
6580 Driver specific image creation options for parallels.
6581 Members
6583 file: BlockdevRef
6584 Node to create the image format on
6585 size: int
6587 Size of the virtual disk in bytes
6588 cluster-size: int (optional)
6590 Cluster size in bytes (default: 1 MB)
6591 Since
6593 2.12
6594 BlockdevCreateOptionsQcow (Object)
6596 Driver specific image creation options for qcow.
6597 Members
6599 file: BlockdevRef
6600 Node to create the image format on
6601 size: int
6603 Size of the virtual disk in bytes
6604 backing-file: string (optional)
6606 File name of the backing file if a backing file should be used
6607 encrypt: QCryptoBlockCreateOptions (optional)
6609 Encryption options if the image should be encrypted
6610 Since
6612 2.12
6613 BlockdevQcow2Version (Enum)
6615 Values
6616 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
6617 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
6619 Since
6621 2.12
6622 Qcow2CompressionType (Enum)
6624 Compression type used in qcow2 image file
6625 Values
6627 zlib zlib compression, see <http://zlib.net/>
6628 zstd (If: CONFIG_ZSTD)
6630 zstd compression, see <http://github.com/facebook/zstd>
6631 Since
6633 5.1
6634 BlockdevCreateOptionsQcow2 (Object)
6636 Driver specific image creation options for qcow2.
6637 Members
6639 file: BlockdevRef
6640 Node to create the image format on
6641 data-file: BlockdevRef (optional)
6643 Node to use as an external data file in which all guest data is
6644 stored so that only metadata remains in the qcow2 file (since:
6645 4.0)
6646 data-file-raw: boolean (optional)
6648 True if the external data file must stay valid as a standalone
6649 (read-only) raw image without looking at qcow2 metadata (de‐
6650 fault: false; since: 4.0)
6651 extended-l2: boolean (optional)
6653 True to make the image have extended L2 entries (default: false;
6654 since 5.2)
6655 size: int
6657 Size of the virtual disk in bytes
6658 version: BlockdevQcow2Version (optional)
6660 Compatibility level (default: v3)
6661 backing-file: string (optional)
6663 File name of the backing file if a backing file should be used
6664 backing-fmt: BlockdevDriver (optional)
6666 Name of the block driver to use for the backing file
6667 encrypt: QCryptoBlockCreateOptions (optional)
6669 Encryption options if the image should be encrypted
6670 cluster-size: int (optional)
6672 qcow2 cluster size in bytes (default: 65536)
6673 preallocation: PreallocMode (optional)
6675 Preallocation mode for the new image (default: off; allowed val‐
6676 ues: off, falloc, full, metadata)
6677 lazy-refcounts: boolean (optional)
6679 True if refcounts may be updated lazily (default: off)
6680 refcount-bits: int (optional)
6682 Width of reference counts in bits (default: 16)
6683 compression-type: Qcow2CompressionType (optional)
6685 The image cluster compression method (default: zlib, since 5.1)
6686 Since
6688 2.12
6689 BlockdevCreateOptionsQed (Object)
6691 Driver specific image creation options for qed.
6692 Members
6694 file: BlockdevRef
6695 Node to create the image format on
6696 size: int
6698 Size of the virtual disk in bytes
6699 backing-file: string (optional)
6701 File name of the backing file if a backing file should be used
6702 backing-fmt: BlockdevDriver (optional)
6704 Name of the block driver to use for the backing file
6705 cluster-size: int (optional)
6707 Cluster size in bytes (default: 65536)
6708 table-size: int (optional)
6710 L1/L2 table size (in clusters)
6711 Since
6713 2.12
6714 BlockdevCreateOptionsRbd (Object)
6716 Driver specific image creation options for rbd/Ceph.
6717 Members
6719 location: BlockdevOptionsRbd
6720 Where to store the new image file. This location cannot point
6721 to a snapshot.
6722 size: int
6724 Size of the virtual disk in bytes
6725 cluster-size: int (optional)
6727 RBD object size
6728 encrypt: RbdEncryptionCreateOptions (optional)
6730 Image encryption options. (Since 6.1)
6731 Since
6733 2.12
6734 BlockdevVmdkSubformat (Enum)
6736 Subformat options for VMDK images
6737 Values
6739 monolithicSparse
6740 Single file image with sparse cluster allocation
6741 monolithicFlat
6743 Single flat data image and a descriptor file
6744 twoGbMaxExtentSparse
6746 Data is split into 2GB (per virtual LBA) sparse extent files, in
6747 addition to a descriptor file
6748 twoGbMaxExtentFlat
6750 Data is split into 2GB (per virtual LBA) flat extent files, in
6751 addition to a descriptor file
6752 streamOptimized
6754 Single file image sparse cluster allocation, optimized for
6755 streaming over network.
6756 Since
6758 4.0
6759 BlockdevVmdkAdapterType (Enum)
6761 Adapter type info for VMDK images
6762 Values
6764 ide Not documented
6765 buslogic
6767 Not documented
6768 lsilogic
6770 Not documented
6771 legacyESX
6773 Not documented
6774 Since
6776 4.0
6777 BlockdevCreateOptionsVmdk (Object)
6779 Driver specific image creation options for VMDK.
6780 Members
6782 file: BlockdevRef
6783 Where to store the new image file. This refers to the image
6784 file for monolithcSparse and streamOptimized format, or the de‐
6785 scriptor file for other formats.
6786 size: int
6788 Size of the virtual disk in bytes
6789 extents: array of BlockdevRef (optional)
6791 Where to store the data extents. Required for monolithcFlat,
6792 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For mono‐
6793 lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
6794 mats, the number of entries required is calculated as ex‐
6795 tent_number = virtual_size / 2GB. Providing more extents than
6796 will be used is an error.
6797 subformat: BlockdevVmdkSubformat (optional)
6799 The subformat of the VMDK image. Default: "monolithicSparse".
6800 backing-file: string (optional)
6802 The path of backing file. Default: no backing file is used.
6803 adapter-type: BlockdevVmdkAdapterType (optional)
6805 The adapter type used to fill in the descriptor. Default: ide.
6806 hwversion: string (optional)
6808 Hardware version. The meaningful options are "4" or "6". De‐
6809 fault: "4".
6810 toolsversion: string (optional)
6812 VMware guest tools version. Default: "2147483647" (Since 6.2)
6813 zeroed-grain: boolean (optional)
6815 Whether to enable zeroed-grain feature for sparse subformats.
6816 Default: false.
6817 Since
6819 4.0
6820 BlockdevCreateOptionsSsh (Object)
6822 Driver specific image creation options for SSH.
6823 Members
6825 location: BlockdevOptionsSsh
6826 Where to store the new image file
6827 size: int
6829 Size of the virtual disk in bytes
6830 Since
6832 2.12
6833 BlockdevCreateOptionsVdi (Object)
6835 Driver specific image creation options for VDI.
6836 Members
6838 file: BlockdevRef
6839 Node to create the image format on
6840 size: int
6842 Size of the virtual disk in bytes
6843 preallocation: PreallocMode (optional)
6845 Preallocation mode for the new image (default: off; allowed val‐
6846 ues: off, metadata)
6847 Since
6849 2.12
6850 BlockdevVhdxSubformat (Enum)
6852 Values
6853 dynamic
6854 Growing image file
6855 fixed Preallocated fixed-size image file
6857 Since
6859 2.12
6860 BlockdevCreateOptionsVhdx (Object)
6862 Driver specific image creation options for vhdx.
6863 Members
6865 file: BlockdevRef
6866 Node to create the image format on
6867 size: int
6869 Size of the virtual disk in bytes
6870 log-size: int (optional)
6872 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
6873 block-size: int (optional)
6875 Block size in bytes, must be a multiple of 1 MB and not larger
6876 than 256 MB (default: automatically choose a block size depend‐
6877 ing on the image size)
6878 subformat: BlockdevVhdxSubformat (optional)
6880 vhdx subformat (default: dynamic)
6881 block-state-zero: boolean (optional)
6883 Force use of payload blocks of type 'ZERO'. Non-standard, but
6884 default. Do not set to 'off' when using 'qemu-img convert' with
6885 subformat=dynamic.
6886 Since
6888 2.12
6889 BlockdevVpcSubformat (Enum)
6891 Values
6892 dynamic
6893 Growing image file
6894 fixed Preallocated fixed-size image file
6896 Since
6898 2.12
6899 BlockdevCreateOptionsVpc (Object)
6901 Driver specific image creation options for vpc (VHD).
6902 Members
6904 file: BlockdevRef
6905 Node to create the image format on
6906 size: int
6908 Size of the virtual disk in bytes
6909 subformat: BlockdevVpcSubformat (optional)
6911 vhdx subformat (default: dynamic)
6912 force-size: boolean (optional)
6914 Force use of the exact byte size instead of rounding to the next
6915 size that can be represented in CHS geometry (default: false)
6916 Since
6918 2.12
6919 BlockdevCreateOptions (Object)
6921 Options for creating an image format on a given node.
6922 Members
6924 driver: BlockdevDriver
6925 block driver to create the image format
6926 The members of BlockdevCreateOptionsFile when driver is "file"
6928 The members of BlockdevCreateOptionsGluster when driver is "gluster"
6930 The members of BlockdevCreateOptionsLUKS when driver is "luks"
6932 The members of BlockdevCreateOptionsNfs when driver is "nfs"
6934 The members of BlockdevCreateOptionsParallels when driver is "paral‐
6936 lels"
6937 The members of BlockdevCreateOptionsQcow when driver is "qcow"
6939 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
6941 The members of BlockdevCreateOptionsQed when driver is "qed"
6943 The members of BlockdevCreateOptionsRbd when driver is "rbd"
6945 The members of BlockdevCreateOptionsSsh when driver is "ssh"
6947 The members of BlockdevCreateOptionsVdi when driver is "vdi"
6949 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
6951 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
6953 The members of BlockdevCreateOptionsVpc when driver is "vpc"
6955 Since
6957 2.12
6958 blockdev-create (Command)
6960 Starts a job to create an image format on a given node. The job is au‐
6961 tomatically finalized, but a manual job-dismiss is required.
6962 Arguments
6964 job-id: string
6965 Identifier for the newly created job.
6966 options: BlockdevCreateOptions
6968 Options for the image creation.
6969 Since
6971 3.0
6972 BlockdevAmendOptionsLUKS (Object)
6974 Driver specific image amend options for LUKS.
6975 Members
6977 The members of QCryptoBlockAmendOptionsLUKS
6978 Since
6980 5.1
6981 BlockdevAmendOptionsQcow2 (Object)
6983 Driver specific image amend options for qcow2. For now, only encryption
6984 options can be amended
6985 Members
6987 encrypt: QCryptoBlockAmendOptions (optional)
6988 Encryption options to be amended
6989 Since
6991 5.1
6992 BlockdevAmendOptions (Object)
6994 Options for amending an image format
6995 Members
6997 driver: BlockdevDriver
6998 Block driver of the node to amend.
6999 The members of BlockdevAmendOptionsLUKS when driver is "luks"
7001 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
7003 Since
7005 5.1
7006 x-blockdev-amend (Command)
7008 Starts a job to amend format specific options of an existing open block
7009 device The job is automatically finalized, but a manual job-dismiss is
7010 required.
7011 Arguments
7013 job-id: string
7014 Identifier for the newly created job.
7015 node-name: string
7017 Name of the block node to work on
7018 options: BlockdevAmendOptions
7020 Options (driver specific)
7021 force: boolean (optional)
7023 Allow unsafe operations, format specific For luks that allows
7024 erase of the last active keyslot (permanent loss of data), and
7025 replacement of an active keyslot (possible loss of data if IO
7026 error happens)
7027 Features
7029 unstable
7030 This command is experimental.
7031 Since
7033 5.1
7034 BlockErrorAction (Enum)
7036 An enumeration of action that has been taken when a DISK I/O occurs
7037 Values
7039 ignore error has been ignored
7040 report error has been reported to the device
7042 stop error caused VM to be stopped
7044 Since
7046 2.1
7047 BLOCK_IMAGE_CORRUPTED (Event)
7049 Emitted when a disk image is being marked corrupt. The image can be
7050 identified by its device or node name. The 'device' field is always
7051 present for compatibility reasons, but it can be empty ("") if the im‐
7052 age does not have a device name associated.
7053 Arguments
7055 device: string
7056 device name. This is always present for compatibility reasons,
7057 but it can be empty ("") if the image does not have a device
7058 name associated.
7059 node-name: string (optional)
7061 node name (Since: 2.4)
7062 msg: string
7064 informative message for human consumption, such as the kind of
7065 corruption being detected. It should not be parsed by machine
7066 as it is not guaranteed to be stable
7067 offset: int (optional)
7069 if the corruption resulted from an image access, this is the
7070 host's access offset into the image
7071 size: int (optional)
7073 if the corruption resulted from an image access, this is the ac‐
7074 cess size
7075 fatal: boolean
7077 if set, the image is marked corrupt and therefore unusable after
7078 this event and must be repaired (Since 2.2; before, every
7079 BLOCK_IMAGE_CORRUPTED event was fatal)
7080 Note
7082 If action is "stop", a STOP event will eventually follow the
7083 BLOCK_IO_ERROR event.
7084 Example
7086 <- { "event": "BLOCK_IMAGE_CORRUPTED",
7087 "data": { "device": "", "node-name": "drive", "fatal": false,
7088 "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" },
7089 "timestamp": { "seconds": 1648243240, "microseconds": 906060 } }
7090 Since
7092 1.7
7093 BLOCK_IO_ERROR (Event)
7095 Emitted when a disk I/O error occurs
7096 Arguments
7098 device: string
7099 device name. This is always present for compatibility reasons,
7100 but it can be empty ("") if the image does not have a device
7101 name associated.
7102 node-name: string (optional)
7104 node name. Note that errors may be reported for the root node
7105 that is directly attached to a guest device rather than for the
7106 node where the error occurred. The node name is not present if
7107 the drive is empty. (Since: 2.8)
7108 operation: IoOperationType
7110 I/O operation
7111 action: BlockErrorAction
7113 action that has been taken
7114 nospace: boolean (optional)
7116 true if I/O error was caused due to a no-space condition. This
7117 key is only present if query-block's io-status is present,
7118 please see query-block documentation for more information
7119 (since: 2.2)
7120 reason: string
7122 human readable string describing the error cause. (This field
7123 is a debugging aid for humans, it should not be parsed by appli‐
7124 cations) (since: 2.2)
7125 Note
7127 If action is "stop", a STOP event will eventually follow the
7128 BLOCK_IO_ERROR event
7129 Since
7131 0.13
7132 Example
7134 <- { "event": "BLOCK_IO_ERROR",
7135 "data": { "device": "ide0-hd1",
7136 "node-name": "#block212",
7137 "operation": "write",
7138 "action": "stop",
7139 "reason": "No space left on device" },
7140 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7141 BLOCK_JOB_COMPLETED (Event)
7143 Emitted when a block job has completed
7144 Arguments
7146 type: JobType
7147 job type
7148 device: string
7150 The job identifier. Originally the device name but other values
7151 are allowed since QEMU 2.7
7152 len: int
7154 maximum progress value
7155 offset: int
7157 current progress value. On success this is equal to len. On
7158 failure this is less than len
7159 speed: int
7161 rate limit, bytes per second
7162 error: string (optional)
7164 error message. Only present on failure. This field contains a
7165 human-readable error message. There are no semantics other than
7166 that streaming has failed and clients should not try to inter‐
7167 pret the error string
7168 Since
7170 1.1
7171 Example
7173 <- { "event": "BLOCK_JOB_COMPLETED",
7174 "data": { "type": "stream", "device": "virtio-disk0",
7175 "len": 10737418240, "offset": 10737418240,
7176 "speed": 0 },
7177 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
7178 BLOCK_JOB_CANCELLED (Event)
7180 Emitted when a block job has been cancelled
7181 Arguments
7183 type: JobType
7184 job type
7185 device: string
7187 The job identifier. Originally the device name but other values
7188 are allowed since QEMU 2.7
7189 len: int
7191 maximum progress value
7192 offset: int
7194 current progress value. On success this is equal to len. On
7195 failure this is less than len
7196 speed: int
7198 rate limit, bytes per second
7199 Since
7201 1.1
7202 Example
7204 <- { "event": "BLOCK_JOB_CANCELLED",
7205 "data": { "type": "stream", "device": "virtio-disk0",
7206 "len": 10737418240, "offset": 134217728,
7207 "speed": 0 },
7208 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
7209 BLOCK_JOB_ERROR (Event)
7211 Emitted when a block job encounters an error
7212 Arguments
7214 device: string
7215 The job identifier. Originally the device name but other values
7216 are allowed since QEMU 2.7
7217 operation: IoOperationType
7219 I/O operation
7220 action: BlockErrorAction
7222 action that has been taken
7223 Since
7225 1.3
7226 Example
7228 <- { "event": "BLOCK_JOB_ERROR",
7229 "data": { "device": "ide0-hd1",
7230 "operation": "write",
7231 "action": "stop" },
7232 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7233 BLOCK_JOB_READY (Event)
7235 Emitted when a block job is ready to complete
7236 Arguments
7238 type: JobType
7239 job type
7240 device: string
7242 The job identifier. Originally the device name but other values
7243 are allowed since QEMU 2.7
7244 len: int
7246 maximum progress value
7247 offset: int
7249 current progress value. On success this is equal to len. On
7250 failure this is less than len
7251 speed: int
7253 rate limit, bytes per second
7254 Note
7256 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
7257 event
7258 Since
7260 1.3
7261 Example
7263 <- { "event": "BLOCK_JOB_READY",
7264 "data": { "device": "drive0", "type": "mirror", "speed": 0,
7265 "len": 2097152, "offset": 2097152 },
7266 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7267 BLOCK_JOB_PENDING (Event)
7269 Emitted when a block job is awaiting explicit authorization to finalize
7270 graph changes via block-job-finalize. If this job is part of a trans‐
7271 action, it will not emit this event until the transaction has converged
7272 first.
7273 Arguments
7275 type: JobType
7276 job type
7277 id: string
7279 The job identifier.
7280 Since
7282 2.12
7283 Example
7285 <- { "event": "BLOCK_JOB_PENDING",
7286 "data": { "type": "mirror", "id": "backup_1" },
7287 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7288 PreallocMode (Enum)
7290 Preallocation mode of QEMU image file
7291 Values
7293 off no preallocation
7294 metadata
7296 preallocate only for metadata
7297 falloc like full preallocation but allocate disk space by posix_fallo‐
7299 cate() rather than writing data.
7300 full preallocate all data by writing it to the device to ensure disk
7302 space is really available. This data may or may not be zero,
7303 depending on the image format and storage. full preallocation
7304 also sets up metadata correctly.
7305 Since
7307 2.2
7308 BLOCK_WRITE_THRESHOLD (Event)
7310 Emitted when writes on block device reaches or exceeds the configured
7311 write threshold. For thin-provisioned devices, this means the device
7312 should be extended to avoid pausing for disk exhaustion. The event is
7313 one shot. Once triggered, it needs to be re-registered with another
7314 block-set-write-threshold command.
7315 Arguments
7317 node-name: string
7318 graph node name on which the threshold was exceeded.
7319 amount-exceeded: int
7321 amount of data which exceeded the threshold, in bytes.
7322 write-threshold: int
7324 last configured threshold, in bytes.
7325 Since
7327 2.3
7328 block-set-write-threshold (Command)
7330 Change the write threshold for a block drive. An event will be deliv‐
7331 ered if a write to this block drive crosses the configured threshold.
7332 The threshold is an offset, thus must be non-negative. Default is no
7333 write threshold. Setting the threshold to zero disables it.
7334 This is useful to transparently resize thin-provisioned drives without
7336 the guest OS noticing.
7337 Arguments
7339 node-name: string
7340 graph node name on which the threshold must be set.
7341 write-threshold: int
7343 configured threshold for the block device, bytes. Use 0 to dis‐
7344 able the threshold.
7345 Since
7347 2.3
7348 Example
7350 -> { "execute": "block-set-write-threshold",
7351 "arguments": { "node-name": "mydev",
7352 "write-threshold": 17179869184 } }
7353 <- { "return": {} }
7354 x-blockdev-change (Command)
7356 Dynamically reconfigure the block driver state graph. It can be used
7357 to add, remove, insert or replace a graph node. Currently only the
7358 Quorum driver implements this feature to add or remove its child. This
7359 is useful to fix a broken quorum child.
7360 If node is specified, it will be inserted under parent. child may not
7362 be specified in this case. If both parent and child are specified but
7363 node is not, child will be detached from parent.
7364 Arguments
7366 parent: string
7367 the id or name of the parent node.
7368 child: string (optional)
7370 the name of a child under the given parent node.
7371 node: string (optional)
7373 the name of the node that will be added.
7374 Features
7376 unstable
7377 This command is experimental, and its API is not stable. It
7378 does not support all kinds of operations, all kinds of children,
7379 nor all block drivers.
7380 FIXME Removing children from a quorum node means introducing
7382 gaps in the child indices. This cannot be represented in the
7383 'children' list of BlockdevOptionsQuorum, as returned by
7384 .bdrv_refresh_filename().
7385 Warning: The data in a new quorum child MUST be consistent with
7387 that of the rest of the array.
7388 Since
7390 2.7
7391 Examples
7393 1. Add a new node to a quorum
7394 -> { "execute": "blockdev-add",
7396 "arguments": {
7397 "driver": "raw",
7398 "node-name": "new_node",
7399 "file": { "driver": "file",
7400 "filename": "test.raw" } } }
7401 <- { "return": {} }
7402 -> { "execute": "x-blockdev-change",
7403 "arguments": { "parent": "disk1",
7404 "node": "new_node" } }
7405 <- { "return": {} }
7406 2. Delete a quorum's node
7408 -> { "execute": "x-blockdev-change",
7410 "arguments": { "parent": "disk1",
7411 "child": "children.1" } }
7412 <- { "return": {} }
7413 x-blockdev-set-iothread (Command)
7415 Move node and its children into the iothread. If iothread is null then
7416 move node and its children into the main loop.
7417 The node must not be attached to a BlockBackend.
7419 Arguments
7421 node-name: string
7422 the name of the block driver node
7423 iothread: StrOrNull
7425 the name of the IOThread object or null for the main loop
7426 force: boolean (optional)
7428 true if the node and its children should be moved when a Block‐
7429 Backend is already attached
7430 Features
7432 unstable
7433 This command is experimental and intended for test cases that
7434 need control over IOThreads only.
7435 Since
7437 2.12
7438 Examples
7440 1. Move a node into an IOThread
7441 -> { "execute": "x-blockdev-set-iothread",
7443 "arguments": { "node-name": "disk1",
7444 "iothread": "iothread0" } }
7445 <- { "return": {} }
7446 2. Move a node into the main loop
7448 -> { "execute": "x-blockdev-set-iothread",
7450 "arguments": { "node-name": "disk1",
7451 "iothread": null } }
7452 <- { "return": {} }
7453 QuorumOpType (Enum)
7455 An enumeration of the quorum operation types
7456 Values
7458 read read operation
7459 write write operation
7461 flush flush operation
7463 Since
7465 2.6
7466 QUORUM_FAILURE (Event)
7468 Emitted by the Quorum block driver if it fails to establish a quorum
7469 Arguments
7471 reference: string
7472 device name if defined else node name
7473 sector-num: int
7475 number of the first sector of the failed read operation
7476 sectors-count: int
7478 failed read operation sector count
7479 Note
7481 This event is rate-limited.
7482 Since
7484 2.0
7485 Example
7487 <- { "event": "QUORUM_FAILURE",
7488 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
7489 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7490 QUORUM_REPORT_BAD (Event)
7492 Emitted to report a corruption of a Quorum file
7493 Arguments
7495 type: QuorumOpType
7496 quorum operation type (Since 2.6)
7497 error: string (optional)
7499 error message. Only present on failure. This field contains a
7500 human-readable error message. There are no semantics other than
7501 that the block layer reported an error and clients should not
7502 try to interpret the error string.
7503 node-name: string
7505 the graph node name of the block driver state
7506 sector-num: int
7508 number of the first sector of the failed read operation
7509 sectors-count: int
7511 failed read operation sector count
7512 Note
7514 This event is rate-limited.
7515 Since
7517 2.0
7518 Examples
7520 1. Read operation
7521 <- { "event": "QUORUM_REPORT_BAD",
7523 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
7524 "type": "read" },
7525 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7526 2. Flush operation
7528 <- { "event": "QUORUM_REPORT_BAD",
7530 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
7531 "type": "flush", "error": "Broken pipe" },
7532 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
7533 BlockdevSnapshotInternal (Object)
7535 Members
7536 device: string
7537 the device name or node-name of a root node to generate the
7538 snapshot from
7539 name: string
7541 the name of the internal snapshot to be created
7542 Notes
7544 In transaction, if name is empty, or any snapshot matching name exists,
7545 the operation will fail. Only some image formats support it, for exam‐
7546 ple, qcow2, and rbd.
7547 Since
7549 1.7
7550 blockdev-snapshot-internal-sync (Command)
7552 Synchronously take an internal snapshot of a block device, when the
7553 format of the image used supports it. If the name is an empty string,
7554 or a snapshot with name already exists, the operation will fail.
7555 For the arguments, see the documentation of BlockdevSnapshotInternal.
7557 Returns
7559 • nothing on success
7560 • If device is not a valid block device, GenericError
7562 • If any snapshot matching name exists, or name is empty, GenericError
7564 • If the format of the image used does not support it, GenericError
7566 Since
7568 1.7
7569 Example
7571 -> { "execute": "blockdev-snapshot-internal-sync",
7572 "arguments": { "device": "ide-hd0",
7573 "name": "snapshot0" }
7574 }
7575 <- { "return": {} }
7576 blockdev-snapshot-delete-internal-sync (Command)
7578 Synchronously delete an internal snapshot of a block device, when the
7579 format of the image used support it. The snapshot is identified by
7580 name or id or both. One of the name or id is required. Return Snap‐
7581 shotInfo for the successfully deleted snapshot.
7582 Arguments
7584 device: string
7585 the device name or node-name of a root node to delete the snap‐
7586 shot from
7587 id: string (optional)
7589 optional the snapshot's ID to be deleted
7590 name: string (optional)
7592 optional the snapshot's name to be deleted
7593 Returns
7595 • SnapshotInfo on success
7596 • If device is not a valid block device, GenericError
7598 • If snapshot not found, GenericError
7600 • If the format of the image used does not support it, GenericError
7602 • If id and name are both not specified, GenericError
7604 Since
7606 1.7
7607 Example
7609 -> { "execute": "blockdev-snapshot-delete-internal-sync",
7610 "arguments": { "device": "ide-hd0",
7611 "name": "snapshot0" }
7612 }
7613 <- { "return": {
7614 "id": "1",
7615 "name": "snapshot0",
7616 "vm-state-size": 0,
7617 "date-sec": 1000012,
7618 "date-nsec": 10,
7619 "vm-clock-sec": 100,
7620 "vm-clock-nsec": 20,
7621 "icount": 220414
7622 }
7623 }
7624 DummyBlockCoreForceArrays (Object)
7626 Not used by QMP; hack to let us use BlockGraphInfoList internally
7627 Members
7629 unused-block-graph-info: array of BlockGraphInfo
7630 Not documented
7631 Since
7633 8.0
7634 Block device exports
7636 NbdServerOptions (Object)
7637 Keep this type consistent with the nbd-server-start arguments. The
7638 only intended difference is using SocketAddress instead of SocketAd‐
7639 dressLegacy.
7640 Members
7642 addr: SocketAddress
7643 Address on which to listen.
7644 tls-creds: string (optional)
7646 ID of the TLS credentials object (since 2.6).
7647 tls-authz: string (optional)
7649 ID of the QAuthZ authorization object used to validate the
7650 client's x509 distinguished name. This object is is only re‐
7651 solved at time of use, so can be deleted and recreated on the
7652 fly while the NBD server is active. If missing, it will default
7653 to denying access (since 4.0).
7654 max-connections: int (optional)
7656 The maximum number of connections to allow at the same time, 0
7657 for unlimited. Setting this to 1 also stops the server from ad‐
7658 vertising multiple client support (since 5.2; default: 0)
7659 Since
7661 4.2
7662 nbd-server-start (Command)
7664 Start an NBD server listening on the given host and port. Block de‐
7665 vices can then be exported using nbd-server-add. The NBD server will
7666 present them as named exports; for example, another QEMU instance could
7667 refer to them as "nbd:HOST:PORT:exportname=NAME".
7668 Keep this type consistent with the NbdServerOptions type. The only in‐
7670 tended difference is using SocketAddressLegacy instead of SocketAd‐
7671 dress.
7672 Arguments
7674 addr: SocketAddressLegacy
7675 Address on which to listen.
7676 tls-creds: string (optional)
7678 ID of the TLS credentials object (since 2.6).
7679 tls-authz: string (optional)
7681 ID of the QAuthZ authorization object used to validate the
7682 client's x509 distinguished name. This object is is only re‐
7683 solved at time of use, so can be deleted and recreated on the
7684 fly while the NBD server is active. If missing, it will default
7685 to denying access (since 4.0).
7686 max-connections: int (optional)
7688 The maximum number of connections to allow at the same time, 0
7689 for unlimited. Setting this to 1 also stops the server from ad‐
7690 vertising multiple client support (since 5.2; default: 0).
7691 Returns
7693 error if the server is already running.
7694 Since
7696 1.3
7697 BlockExportOptionsNbdBase (Object)
7699 An NBD block export (common options shared between nbd-server-add and
7700 the NBD branch of block-export-add).
7701 Members
7703 name: string (optional)
7704 Export name. If unspecified, the device parameter is used as
7705 the export name. (Since 2.12)
7706 description: string (optional)
7708 Free-form description of the export, up to 4096 bytes. (Since
7709 5.0)
7710 Since
7712 5.0
7713 BlockExportOptionsNbd (Object)
7715 An NBD block export (distinct options used in the NBD branch of
7716 block-export-add).
7717 Members
7719 bitmaps: array of BlockDirtyBitmapOrStr (optional)
7720 Also export each of the named dirty bitmaps reachable from de‐
7721 vice, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
7722 the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
7723 each bitmap. Since 7.1 bitmap may be specified by node/name
7724 pair.
7725 allocation-depth: boolean (optional)
7727 Also export the allocation depth map for device, so the NBD
7728 client can use NBD_OPT_SET_META_CONTEXT with the metadata con‐
7729 text name "qemu:allocation-depth" to inspect allocation details.
7730 (since 5.2)
7731 The members of BlockExportOptionsNbdBase
7733 Since
7735 5.2
7736 BlockExportOptionsVhostUserBlk (Object)
7738 A vhost-user-blk block export.
7739 Members
7741 addr: SocketAddress
7742 The vhost-user socket on which to listen. Both 'unix' and 'fd'
7743 SocketAddress types are supported. Passed fds must be UNIX do‐
7744 main sockets.
7745 logical-block-size: int (optional)
7747 Logical block size in bytes. Defaults to 512 bytes.
7748 num-queues: int (optional)
7750 Number of request virtqueues. Must be greater than 0. Defaults
7751 to 1.
7752 Since
7754 5.2
7755 FuseExportAllowOther (Enum)
7757 Possible allow_other modes for FUSE exports.
7758 Values
7760 off Do not pass allow_other as a mount option.
7761 on Pass allow_other as a mount option.
7763 auto Try mounting with allow_other first, and if that fails, retry
7765 without allow_other.
7766 Since
7768 6.1
7769 BlockExportOptionsFuse (Object)
7771 Options for exporting a block graph node on some (file) mountpoint as a
7772 raw image.
7773 Members
7775 mountpoint: string
7776 Path on which to export the block device via FUSE. This must
7777 point to an existing regular file.
7778 growable: boolean (optional)
7780 Whether writes beyond the EOF should grow the block node accord‐
7781 ingly. (default: false)
7782 allow-other: FuseExportAllowOther (optional)
7784 If this is off, only qemu's user is allowed access to this ex‐
7785 port. That cannot be changed even with chmod or chown. En‐
7786 abling this option will allow other users access to the export
7787 with the FUSE mount option "allow_other". Note that using al‐
7788 low_other as a non-root user requires user_allow_other to be en‐
7789 abled in the global fuse.conf configuration file. In auto mode
7790 (the default), the FUSE export driver will first attempt to
7791 mount the export with allow_other, and if that fails, try again
7792 without. (since 6.1; default: auto)
7793 Since
7795 6.0
7796 If
7798 CONFIG_FUSE
7799 BlockExportOptionsVduseBlk (Object)
7801 A vduse-blk block export.
7802 Members
7804 name: string
7805 the name of VDUSE device (must be unique across the host).
7806 num-queues: int (optional)
7808 the number of virtqueues. Defaults to 1.
7809 queue-size: int (optional)
7811 the size of virtqueue. Defaults to 256.
7812 logical-block-size: int (optional)
7814 Logical block size in bytes. Range [512, PAGE_SIZE] and must be
7815 power of 2. Defaults to 512 bytes.
7816 serial: string (optional)
7818 the serial number of virtio block device. Defaults to empty
7819 string.
7820 Since
7822 7.1
7823 NbdServerAddOptions (Object)
7825 An NBD block export, per legacy nbd-server-add command.
7826 Members
7828 device: string
7829 The device name or node name of the node to be exported
7830 writable: boolean (optional)
7832 Whether clients should be able to write to the device via the
7833 NBD connection (default false).
7834 bitmap: string (optional)
7836 Also export a single dirty bitmap reachable from device, so the
7837 NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
7838 context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
7839 (since 4.0).
7840 The members of BlockExportOptionsNbdBase
7842 Since
7844 5.0
7845 nbd-server-add (Command)
7847 Export a block node to QEMU's embedded NBD server.
7848 The export name will be used as the id for the resulting block export.
7850 Arguments
7852 The members of NbdServerAddOptions
7853 Features
7855 deprecated
7856 This command is deprecated. Use block-export-add instead.
7857 Returns
7859 error if the server is not running, or export with the same name al‐
7860 ready exists.
7861 Since
7863 1.3
7864 BlockExportRemoveMode (Enum)
7866 Mode for removing a block export.
7867 Values
7869 safe Remove export if there are no existing connections, fail other‐
7870 wise.
7871 hard Drop all connections immediately and remove export.
7873 Potential additional modes to be added in the future:
7874 hide: Just hide export from new clients, leave existing connections as
7876 is. Remove export after all clients are disconnected.
7877 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
7879 ther requests from existing clients.
7880 Since
7882 2.12
7883 nbd-server-remove (Command)
7885 Remove NBD export by name.
7886 Arguments
7888 name: string
7889 Block export id.
7890 mode: BlockExportRemoveMode (optional)
7892 Mode of command operation. See BlockExportRemoveMode descrip‐
7893 tion. Default is 'safe'.
7894 Features
7896 deprecated
7897 This command is deprecated. Use block-export-del instead.
7898 Returns
7900 error if
7901 • the server is not running
7903 • export is not found
7905 • mode is 'safe' and there are existing connections
7907 Since
7909 2.12
7910 nbd-server-stop (Command)
7912 Stop QEMU's embedded NBD server, and unregister all devices previously
7913 added via nbd-server-add.
7914 Since
7916 1.3
7917 BlockExportType (Enum)
7919 An enumeration of block export types
7920 Values
7922 nbd NBD export
7923 vhost-user-blk (If: CONFIG_VHOST_USER_BLK_SERVER)
7925 vhost-user-blk export (since 5.2)
7926 fuse (If: CONFIG_FUSE)
7928 FUSE export (since: 6.0)
7929 vduse-blk (If: CONFIG_VDUSE_BLK_EXPORT)
7931 vduse-blk export (since 7.1)
7932 Since
7934 4.2
7935 BlockExportOptions (Object)
7937 Describes a block export, i.e. how single node should be exported on an
7938 external interface.
7939 Members
7941 id: string
7942 A unique identifier for the block export (across all export
7943 types)
7944 node-name: string
7946 The node name of the block node to be exported (since: 5.2)
7947 writable: boolean (optional)
7949 True if clients should be able to write to the export (default
7950 false)
7951 writethrough: boolean (optional)
7953 If true, caches are flushed after every write request to the ex‐
7954 port before completion is signalled. (since: 5.2; default:
7955 false)
7956 iothread: string (optional)
7958 The name of the iothread object where the export will run. The
7959 default is to use the thread currently associated with the block
7960 node. (since: 5.2)
7961 fixed-iothread: boolean (optional)
7963 True prevents the block node from being moved to another thread
7964 while the export is active. If true and iothread is given, ex‐
7965 port creation fails if the block node cannot be moved to the io‐
7966 thread. The default is false. (since: 5.2)
7967 type: BlockExportType
7969 Not documented
7970 The members of BlockExportOptionsNbd when type is "nbd"
7972 The members of BlockExportOptionsVhostUserBlk when type is
7974 "vhost-user-blk" (If: CONFIG_VHOST_USER_BLK_SERVER)
7975 The members of BlockExportOptionsFuse when type is "fuse" (If: CON‐
7977 FIG_FUSE)
7978 The members of BlockExportOptionsVduseBlk when type is "vduse-blk" (If:
7980 CONFIG_VDUSE_BLK_EXPORT)
7981 Since
7983 4.2
7984 block-export-add (Command)
7986 Creates a new block export.
7987 Arguments
7989 The members of BlockExportOptions
7990 Since
7992 5.2
7993 block-export-del (Command)
7995 Request to remove a block export. This drops the user's reference to
7996 the export, but the export may still stay around after this command re‐
7997 turns until the shutdown of the export has completed.
7998 Arguments
8000 id: string
8001 Block export id.
8002 mode: BlockExportRemoveMode (optional)
8004 Mode of command operation. See BlockExportRemoveMode descrip‐
8005 tion. Default is 'safe'.
8006 Returns
8008 Error if the export is not found or mode is 'safe' and the export is
8009 still in use (e.g. by existing client connections)
8010 Since
8012 5.2
8013 BLOCK_EXPORT_DELETED (Event)
8015 Emitted when a block export is removed and its id can be reused.
8016 Arguments
8018 id: string
8019 Block export id.
8020 Since
8022 5.2
8023 BlockExportInfo (Object)
8025 Information about a single block export.
8026 Members
8028 id: string
8029 The unique identifier for the block export
8030 type: BlockExportType
8032 The block export type
8033 node-name: string
8035 The node name of the block node that is exported
8036 shutting-down: boolean
8038 True if the export is shutting down (e.g. after a block-ex‐
8039 port-del command, but before the shutdown has completed)
8040 Since
8042 5.2
8043 query-block-exports (Command)
8045 Returns
8046 A list of BlockExportInfo describing all block exports
8047 Since
8049 5.2
8050
8052 ChardevInfo (Object)
8053 Information about a character device.
8054 Members
8056 label: string
8057 the label of the character device
8058 filename: string
8060 the filename of the character device
8061 frontend-open: boolean
8063 shows whether the frontend device attached to this backend (e.g.
8064 with the chardev=... option) is in open or closed state (since
8065 2.1)
8066 Notes
8068 filename is encoded using the QEMU command line character device encod‐
8069 ing. See the QEMU man page for details.
8070 Since
8072 0.14
8073 query-chardev (Command)
8075 Returns information about current character devices.
8076 Returns
8078 a list of ChardevInfo
8079 Since
8081 0.14
8082 Example
8084 -> { "execute": "query-chardev" }
8085 <- {
8086 "return": [
8087 {
8088 "label": "charchannel0",
8089 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
8090 "frontend-open": false
8091 },
8092 {
8093 "label": "charmonitor",
8094 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
8095 "frontend-open": true
8096 },
8097 {
8098 "label": "charserial0",
8099 "filename": "pty:/dev/pts/2",
8100 "frontend-open": true
8101 }
8102 ]
8103 }
8104 ChardevBackendInfo (Object)
8106 Information about a character device backend
8107 Members
8109 name: string
8110 The backend name
8111 Since
8113 2.0
8114 query-chardev-backends (Command)
8116 Returns information about character device backends.
8117 Returns
8119 a list of ChardevBackendInfo
8120 Since
8122 2.0
8123 Example
8125 -> { "execute": "query-chardev-backends" }
8126 <- {
8127 "return":[
8128 {
8129 "name":"udp"
8130 },
8131 {
8132 "name":"tcp"
8133 },
8134 {
8135 "name":"unix"
8136 },
8137 {
8138 "name":"spiceport"
8139 }
8140 ]
8141 }
8142 DataFormat (Enum)
8144 An enumeration of data format.
8145 Values
8147 utf8 Data is a UTF-8 string (RFC 3629)
8148 base64 Data is Base64 encoded binary (RFC 3548)
8150 Since
8152 1.4
8153 ringbuf-write (Command)
8155 Write to a ring buffer character device.
8156 Arguments
8158 device: string
8159 the ring buffer character device name
8160 data: string
8162 data to write
8163 format: DataFormat (optional)
8165 data encoding (default 'utf8').
8166 • base64: data must be base64 encoded text. Its binary decoding
8168 gets written.
8169 • utf8: data's UTF-8 encoding is written
8171 • data itself is always Unicode regardless of format, like any
8173 other string.
8174 Returns
8176 Nothing on success
8177 Since
8179 1.4
8180 Example
8182 -> { "execute": "ringbuf-write",
8183 "arguments": { "device": "foo",
8184 "data": "abcdefgh",
8185 "format": "utf8" } }
8186 <- { "return": {} }
8187 ringbuf-read (Command)
8189 Read from a ring buffer character device.
8190 Arguments
8192 device: string
8193 the ring buffer character device name
8194 size: int
8196 how many bytes to read at most
8197 format: DataFormat (optional)
8199 data encoding (default 'utf8').
8200 • base64: the data read is returned in base64 encoding.
8202 • utf8: the data read is interpreted as UTF-8. Bug: can screw
8204 up when the buffer contains invalid UTF-8 sequences, NUL char‐
8205 acters, after the ring buffer lost data, and when reading
8206 stops because the size limit is reached.
8207 • The return value is always Unicode regardless of format, like
8209 any other string.
8210 Returns
8212 data read from the device
8213 Since
8215 1.4
8216 Example
8218 -> { "execute": "ringbuf-read",
8219 "arguments": { "device": "foo",
8220 "size": 1000,
8221 "format": "utf8" } }
8222 <- { "return": "abcdefgh" }
8223 ChardevCommon (Object)
8225 Configuration shared across all chardev backends
8226 Members
8228 logfile: string (optional)
8229 The name of a logfile to save output
8230 logappend: boolean (optional)
8232 true to append instead of truncate (default to false to trun‐
8233 cate)
8234 Since
8236 2.6
8237 ChardevFile (Object)
8239 Configuration info for file chardevs.
8240 Members
8242 in: string (optional)
8243 The name of the input file
8244 out: string
8246 The name of the output file
8247 append: boolean (optional)
8249 Open the file in append mode (default false to truncate) (Since
8250 2.6)
8251 The members of ChardevCommon
8253 Since
8255 1.4
8256 ChardevHostdev (Object)
8258 Configuration info for device and pipe chardevs.
8259 Members
8261 device: string
8262 The name of the special file for the device, i.e. /dev/ttyS0 on
8263 Unix or COM1: on Windows
8264 The members of ChardevCommon
8266 Since
8268 1.4
8269 ChardevSocket (Object)
8271 Configuration info for (stream) socket chardevs.
8272 Members
8274 addr: SocketAddressLegacy
8275 socket address to listen on (server=true) or connect to
8276 (server=false)
8277 tls-creds: string (optional)
8279 the ID of the TLS credentials object (since 2.6)
8280 tls-authz: string (optional)
8282 the ID of the QAuthZ authorization object against which the
8283 client's x509 distinguished name will be validated. This object
8284 is only resolved at time of use, so can be deleted and recreated
8285 on the fly while the chardev server is active. If missing, it
8286 will default to denying access (since 4.0)
8287 server: boolean (optional)
8289 create server socket (default: true)
8290 wait: boolean (optional)
8292 wait for incoming connection on server sockets (default: false).
8293 Silently ignored with server: false. This use is deprecated.
8294 nodelay: boolean (optional)
8296 set TCP_NODELAY socket option (default: false)
8297 telnet: boolean (optional)
8299 enable telnet protocol on server sockets (default: false)
8300 tn3270: boolean (optional)
8302 enable tn3270 protocol on server sockets (default: false)
8303 (Since: 2.10)
8304 websocket: boolean (optional)
8306 enable websocket protocol on server sockets (default: false)
8307 (Since: 3.1)
8308 reconnect: int (optional)
8310 For a client socket, if a socket is disconnected, then attempt a
8311 reconnect after the given number of seconds. Setting this to
8312 zero disables this function. (default: 0) (Since: 2.2)
8313 The members of ChardevCommon
8315 Since
8317 1.4
8318 ChardevUdp (Object)
8320 Configuration info for datagram socket chardevs.
8321 Members
8323 remote: SocketAddressLegacy
8324 remote address
8325 local: SocketAddressLegacy (optional)
8327 local address
8328 The members of ChardevCommon
8330 Since
8332 1.5
8333 ChardevMux (Object)
8335 Configuration info for mux chardevs.
8336 Members
8338 chardev: string
8339 name of the base chardev.
8340 The members of ChardevCommon
8342 Since
8344 1.5
8345 ChardevStdio (Object)
8347 Configuration info for stdio chardevs.
8348 Members
8350 signal: boolean (optional)
8351 Allow signals (such as SIGINT triggered by ^C) be delivered to
8352 qemu. Default: true.
8353 The members of ChardevCommon
8355 Since
8357 1.5
8358 ChardevSpiceChannel (Object)
8360 Configuration info for spice vm channel chardevs.
8361 Members
8363 type: string
8364 kind of channel (for example vdagent).
8365 The members of ChardevCommon
8367 Since
8369 1.5
8370 If
8372 CONFIG_SPICE
8373 ChardevSpicePort (Object)
8375 Configuration info for spice port chardevs.
8376 Members
8378 fqdn: string
8379 name of the channel (see docs/spice-port-fqdn.txt)
8380 The members of ChardevCommon
8382 Since
8384 1.5
8385 If
8387 CONFIG_SPICE
8388 ChardevDBus (Object)
8390 Configuration info for DBus chardevs.
8391 Members
8393 name: string
8394 name of the channel (following docs/spice-port-fqdn.txt)
8395 The members of ChardevCommon
8397 Since
8399 7.0
8400 If
8402 CONFIG_DBUS_DISPLAY
8403 ChardevVC (Object)
8405 Configuration info for virtual console chardevs.
8406 Members
8408 width: int (optional)
8409 console width, in pixels
8410 height: int (optional)
8412 console height, in pixels
8413 cols: int (optional)
8415 console width, in chars
8416 rows: int (optional)
8418 console height, in chars
8419 The members of ChardevCommon
8421 Since
8423 1.5
8424 ChardevRingbuf (Object)
8426 Configuration info for ring buffer chardevs.
8427 Members
8429 size: int (optional)
8430 ring buffer size, must be power of two, default is 65536
8431 The members of ChardevCommon
8433 Since
8435 1.5
8436 ChardevQemuVDAgent (Object)
8438 Configuration info for qemu vdagent implementation.
8439 Members
8441 mouse: boolean (optional)
8442 enable/disable mouse, default is enabled.
8443 clipboard: boolean (optional)
8445 enable/disable clipboard, default is disabled.
8446 The members of ChardevCommon
8448 Since
8450 6.1
8451 If
8453 CONFIG_SPICE_PROTOCOL
8454 ChardevBackendKind (Enum)
8456 Values
8457 pipe Since 1.5
8458 udp Since 1.5
8460 mux Since 1.5
8462 msmouse
8464 Since 1.5
8465 wctablet
8467 Since 2.9
8468 braille
8470 Since 1.5
8471 testdev
8473 Since 2.2
8474 stdio Since 1.5
8476 console
8478 Since 1.5
8479 spicevmc (If: CONFIG_SPICE)
8481 Since 1.5
8482 spiceport (If: CONFIG_SPICE)
8484 Since 1.5
8485 qemu-vdagent (If: CONFIG_SPICE_PROTOCOL)
8487 Since 6.1
8488 dbus (If: CONFIG_DBUS_DISPLAY)
8490 Since 7.0
8491 vc v1.5
8493 ringbuf
8495 Since 1.6
8496 memory Since 1.5
8498 file Not documented
8500 serial Not documented
8502 parallel
8504 Not documented
8505 socket Not documented
8507 pty Not documented
8509 null Not documented
8511 Since
8513 1.4
8514 ChardevFileWrapper (Object)
8516 Members
8517 data: ChardevFile
8518 Not documented
8519 Since
8521 1.4
8522 ChardevHostdevWrapper (Object)
8524 Members
8525 data: ChardevHostdev
8526 Not documented
8527 Since
8529 1.4
8530 ChardevSocketWrapper (Object)
8532 Members
8533 data: ChardevSocket
8534 Not documented
8535 Since
8537 1.4
8538 ChardevUdpWrapper (Object)
8540 Members
8541 data: ChardevUdp
8542 Not documented
8543 Since
8545 1.5
8546 ChardevCommonWrapper (Object)
8548 Members
8549 data: ChardevCommon
8550 Not documented
8551 Since
8553 2.6
8554 ChardevMuxWrapper (Object)
8556 Members
8557 data: ChardevMux
8558 Not documented
8559 Since
8561 1.5
8562 ChardevStdioWrapper (Object)
8564 Members
8565 data: ChardevStdio
8566 Not documented
8567 Since
8569 1.5
8570 ChardevSpiceChannelWrapper (Object)
8572 Members
8573 data: ChardevSpiceChannel
8574 Not documented
8575 Since
8577 1.5
8578 If
8580 CONFIG_SPICE
8581 ChardevSpicePortWrapper (Object)
8583 Members
8584 data: ChardevSpicePort
8585 Not documented
8586 Since
8588 1.5
8589 If
8591 CONFIG_SPICE
8592 ChardevQemuVDAgentWrapper (Object)
8594 Members
8595 data: ChardevQemuVDAgent
8596 Not documented
8597 Since
8599 6.1
8600 If
8602 CONFIG_SPICE_PROTOCOL
8603 ChardevDBusWrapper (Object)
8605 Members
8606 data: ChardevDBus
8607 Not documented
8608 Since
8610 7.0
8611 If
8613 CONFIG_DBUS_DISPLAY
8614 ChardevVCWrapper (Object)
8616 Members
8617 data: ChardevVC
8618 Not documented
8619 Since
8621 1.5
8622 ChardevRingbufWrapper (Object)
8624 Members
8625 data: ChardevRingbuf
8626 Not documented
8627 Since
8629 1.5
8630 ChardevBackend (Object)
8632 Configuration info for the new chardev backend.
8633 Members
8635 type: ChardevBackendKind
8636 Not documented
8637 The members of ChardevFileWrapper when type is "file"
8639 The members of ChardevHostdevWrapper when type is "serial"
8641 The members of ChardevHostdevWrapper when type is "parallel"
8643 The members of ChardevHostdevWrapper when type is "pipe"
8645 The members of ChardevSocketWrapper when type is "socket"
8647 The members of ChardevUdpWrapper when type is "udp"
8649 The members of ChardevCommonWrapper when type is "pty"
8651 The members of ChardevCommonWrapper when type is "null"
8653 The members of ChardevMuxWrapper when type is "mux"
8655 The members of ChardevCommonWrapper when type is "msmouse"
8657 The members of ChardevCommonWrapper when type is "wctablet"
8659 The members of ChardevCommonWrapper when type is "braille"
8661 The members of ChardevCommonWrapper when type is "testdev"
8663 The members of ChardevStdioWrapper when type is "stdio"
8665 The members of ChardevCommonWrapper when type is "console"
8667 The members of ChardevSpiceChannelWrapper when type is "spicevmc" (If:
8669 CONFIG_SPICE)
8670 The members of ChardevSpicePortWrapper when type is "spiceport" (If:
8672 CONFIG_SPICE)
8673 The members of ChardevQemuVDAgentWrapper when type is "qemu-vdagent"
8675 (If: CONFIG_SPICE_PROTOCOL)
8676 The members of ChardevDBusWrapper when type is "dbus" (If: CON‐
8678 FIG_DBUS_DISPLAY)
8679 The members of ChardevVCWrapper when type is "vc"
8681 The members of ChardevRingbufWrapper when type is "ringbuf"
8683 The members of ChardevRingbufWrapper when type is "memory"
8685 Since
8687 1.4
8688 ChardevReturn (Object)
8690 Return info about the chardev backend just created.
8691 Members
8693 pty: string (optional)
8694 name of the slave pseudoterminal device, present if and only if
8695 a chardev of type 'pty' was created
8696 Since
8698 1.4
8699 chardev-add (Command)
8701 Add a character device backend
8702 Arguments
8704 id: string
8705 the chardev's ID, must be unique
8706 backend: ChardevBackend
8708 backend type and parameters
8709 Returns
8711 ChardevReturn.
8712 Since
8714 1.4
8715 Examples
8717 -> { "execute" : "chardev-add",
8718 "arguments" : { "id" : "foo",
8719 "backend" : { "type" : "null", "data" : {} } } }
8720 <- { "return": {} }
8721 -> { "execute" : "chardev-add",
8723 "arguments" : { "id" : "bar",
8724 "backend" : { "type" : "file",
8725 "data" : { "out" : "/tmp/bar.log" } } } }
8726 <- { "return": {} }
8727 -> { "execute" : "chardev-add",
8729 "arguments" : { "id" : "baz",
8730 "backend" : { "type" : "pty", "data" : {} } } }
8731 <- { "return": { "pty" : "/dev/pty/42" } }
8732 chardev-change (Command)
8734 Change a character device backend
8735 Arguments
8737 id: string
8738 the chardev's ID, must exist
8739 backend: ChardevBackend
8741 new backend type and parameters
8742 Returns
8744 ChardevReturn.
8745 Since
8747 2.10
8748 Examples
8750 -> { "execute" : "chardev-change",
8751 "arguments" : { "id" : "baz",
8752 "backend" : { "type" : "pty", "data" : {} } } }
8753 <- { "return": { "pty" : "/dev/pty/42" } }
8754 -> {"execute" : "chardev-change",
8756 "arguments" : {
8757 "id" : "charchannel2",
8758 "backend" : {
8759 "type" : "socket",
8760 "data" : {
8761 "addr" : {
8762 "type" : "unix" ,
8763 "data" : {
8764 "path" : "/tmp/charchannel2.socket"
8765 }
8766 },
8767 "server" : true,
8768 "wait" : false }}}}
8769 <- {"return": {}}
8770 chardev-remove (Command)
8772 Remove a character device backend
8773 Arguments
8775 id: string
8776 the chardev's ID, must exist and not be in use
8777 Returns
8779 Nothing on success
8780 Since
8782 1.4
8783 Example
8785 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
8786 <- { "return": {} }
8787 chardev-send-break (Command)
8789 Send a break to a character device
8790 Arguments
8792 id: string
8793 the chardev's ID, must exist
8794 Returns
8796 Nothing on success
8797 Since
8799 2.10
8800 Example
8802 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
8803 <- { "return": {} }
8804 VSERPORT_CHANGE (Event)
8806 Emitted when the guest opens or closes a virtio-serial port.
8807 Arguments
8809 id: string
8810 device identifier of the virtio-serial port
8811 open: boolean
8813 true if the guest has opened the virtio-serial port
8814 Note
8816 This event is rate-limited.
8817 Since
8819 2.1
8820 Example
8822 <- { "event": "VSERPORT_CHANGE",
8823 "data": { "id": "channel0", "open": true },
8824 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
8825
8827 QAuthZListPolicy (Enum)
8828 The authorization policy result
8829 Values
8831 deny deny access
8832 allow allow access
8834 Since
8836 4.0
8837 QAuthZListFormat (Enum)
8839 The authorization policy match format
8840 Values
8842 exact an exact string match
8843 glob string with ? and * shell wildcard support
8845 Since
8847 4.0
8848 QAuthZListRule (Object)
8850 A single authorization rule.
8851 Members
8853 match: string
8854 a string or glob to match against a user identity
8855 policy: QAuthZListPolicy
8857 the result to return if match evaluates to true
8858 format: QAuthZListFormat (optional)
8860 the format of the match rule (default 'exact')
8861 Since
8863 4.0
8864 AuthZListProperties (Object)
8866 Properties for authz-list objects.
8867 Members
8869 policy: QAuthZListPolicy (optional)
8870 Default policy to apply when no rule matches (default: deny)
8871 rules: array of QAuthZListRule (optional)
8873 Authorization rules based on matching user
8874 Since
8876 4.0
8877 AuthZListFileProperties (Object)
8879 Properties for authz-listfile objects.
8880 Members
8882 filename: string
8883 File name to load the configuration from. The file must contain
8884 valid JSON for AuthZListProperties.
8885 refresh: boolean (optional)
8887 If true, inotify is used to monitor the file, automatically
8888 reloading changes. If an error occurs during reloading, all au‐
8889 thorizations will fail until the file is next successfully
8890 loaded. (default: true if the binary was built with CONFIG_INO‐
8891 TIFY1, false otherwise)
8892 Since
8894 4.0
8895 AuthZPAMProperties (Object)
8897 Properties for authz-pam objects.
8898 Members
8900 service: string
8901 PAM service name to use for authorization
8902 Since
8904 4.0
8905 AuthZSimpleProperties (Object)
8907 Properties for authz-simple objects.
8908 Members
8910 identity: string
8911 Identifies the allowed user. Its format depends on the network
8912 service that authorization object is associated with. For au‐
8913 thorizing based on TLS x509 certificates, the identity must be
8914 the x509 distinguished name.
8915 Since
8917 4.0
8918
8920 Abort (Object)
8921 This action can be used to test transaction failure.
8922 Since
8924 1.6
8925 ActionCompletionMode (Enum)
8927 An enumeration of Transactional completion modes.
8928 Values
8930 individual
8931 Do not attempt to cancel any other Actions if any Actions fail
8932 after the Transaction request succeeds. All Actions that can
8933 complete successfully will do so without waiting on others.
8934 This is the default.
8935 grouped
8937 If any Action fails after the Transaction succeeds, cancel all
8938 Actions. Actions do not complete until all Actions are ready to
8939 complete. May be rejected by Actions that do not support this
8940 completion mode.
8941 Since
8943 2.5
8944 TransactionActionKind (Enum)
8946 Values
8947 abort Since 1.6
8948 block-dirty-bitmap-add
8950 Since 2.5
8951 block-dirty-bitmap-remove
8953 Since 4.2
8954 block-dirty-bitmap-clear
8956 Since 2.5
8957 block-dirty-bitmap-enable
8959 Since 4.0
8960 block-dirty-bitmap-disable
8962 Since 4.0
8963 block-dirty-bitmap-merge
8965 Since 4.0
8966 blockdev-backup
8968 Since 2.3
8969 blockdev-snapshot
8971 Since 2.5
8972 blockdev-snapshot-internal-sync
8974 Since 1.7
8975 blockdev-snapshot-sync
8977 since 1.1
8978 drive-backup
8980 Since 1.6
8981 Features
8983 deprecated
8984 Member drive-backup is deprecated. Use member blockdev-backup
8985 instead.
8986 Since
8988 1.1
8989 AbortWrapper (Object)
8991 Members
8992 data: Abort
8993 Not documented
8994 Since
8996 1.6
8997 BlockDirtyBitmapAddWrapper (Object)
8999 Members
9000 data: BlockDirtyBitmapAdd
9001 Not documented
9002 Since
9004 2.5
9005 BlockDirtyBitmapWrapper (Object)
9007 Members
9008 data: BlockDirtyBitmap
9009 Not documented
9010 Since
9012 2.5
9013 BlockDirtyBitmapMergeWrapper (Object)
9015 Members
9016 data: BlockDirtyBitmapMerge
9017 Not documented
9018 Since
9020 4.0
9021 BlockdevBackupWrapper (Object)
9023 Members
9024 data: BlockdevBackup
9025 Not documented
9026 Since
9028 2.3
9029 BlockdevSnapshotWrapper (Object)
9031 Members
9032 data: BlockdevSnapshot
9033 Not documented
9034 Since
9036 2.5
9037 BlockdevSnapshotInternalWrapper (Object)
9039 Members
9040 data: BlockdevSnapshotInternal
9041 Not documented
9042 Since
9044 1.7
9045 BlockdevSnapshotSyncWrapper (Object)
9047 Members
9048 data: BlockdevSnapshotSync
9049 Not documented
9050 Since
9052 1.1
9053 DriveBackupWrapper (Object)
9055 Members
9056 data: DriveBackup
9057 Not documented
9058 Since
9060 1.6
9061 TransactionAction (Object)
9063 A discriminated record of operations that can be performed with trans‐
9064 action.
9065 Members
9067 type: TransactionActionKind
9068 Not documented
9069 The members of AbortWrapper when type is "abort"
9071 The members of BlockDirtyBitmapAddWrapper when type is
9073 "block-dirty-bitmap-add"
9074 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
9076 map-remove"
9077 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
9079 map-clear"
9080 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
9082 map-enable"
9083 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
9085 map-disable"
9086 The members of BlockDirtyBitmapMergeWrapper when type is
9088 "block-dirty-bitmap-merge"
9089 The members of BlockdevBackupWrapper when type is "blockdev-backup"
9091 The members of BlockdevSnapshotWrapper when type is "blockdev-snapshot"
9093 The members of BlockdevSnapshotInternalWrapper when type is "block‐
9095 dev-snapshot-internal-sync"
9096 The members of BlockdevSnapshotSyncWrapper when type is "blockdev-snap‐
9098 shot-sync"
9099 The members of DriveBackupWrapper when type is "drive-backup"
9101 Since
9103 1.1
9104 TransactionProperties (Object)
9106 Optional arguments to modify the behavior of a Transaction.
9107 Members
9109 completion-mode: ActionCompletionMode (optional)
9110 Controls how jobs launched asynchronously by Actions will com‐
9111 plete or fail as a group. See ActionCompletionMode for details.
9112 Since
9114 2.5
9115 transaction (Command)
9117 Executes a number of transactionable QMP commands atomically. If any
9118 operation fails, then the entire set of actions will be abandoned and
9119 the appropriate error returned.
9120 For external snapshots, the dictionary contains the device, the file to
9122 use for the new snapshot, and the format. The default format, if not
9123 specified, is qcow2.
9124 Each new snapshot defaults to being created by QEMU (wiping any con‐
9126 tents if the file already exists), but it is also possible to reuse an
9127 externally-created file. In the latter case, you should ensure that
9128 the new image file has the same contents as the current one; QEMU can‐
9129 not perform any meaningful check. Typically this is achieved by using
9130 the current image file as the backing file for the new image.
9131 On failure, the original disks pre-snapshot attempt will be used.
9133 For internal snapshots, the dictionary contains the device and the
9135 snapshot's name. If an internal snapshot matching name already exists,
9136 the request will be rejected. Only some image formats support it, for
9137 example, qcow2, and rbd,
9138 On failure, qemu will try delete the newly created internal snapshot in
9140 the transaction. When an I/O error occurs during deletion, the user
9141 needs to fix it later with qemu-img or other command.
9142 Arguments
9144 actions: array of TransactionAction
9145 List of TransactionAction; information needed for the respective
9146 operations.
9147 properties: TransactionProperties (optional)
9149 structure of additional options to control the execution of the
9150 transaction. See TransactionProperties for additional detail.
9151 Returns
9153 nothing on success
9154 Errors depend on the operations of the transaction
9156 Note
9158 The transaction aborts on the first failure. Therefore, there will be
9159 information on only one failed operation returned in an error condi‐
9160 tion, and subsequent actions will not have been attempted.
9161 Since
9163 1.1
9164 Example
9166 -> { "execute": "transaction",
9167 "arguments": { "actions": [
9168 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
9169 "snapshot-file": "/some/place/my-image",
9170 "format": "qcow2" } },
9171 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
9172 "snapshot-file": "/some/place/my-image2",
9173 "snapshot-node-name": "node3432",
9174 "mode": "existing",
9175 "format": "qcow2" } },
9176 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
9177 "snapshot-file": "/some/place/my-image2",
9178 "mode": "existing",
9179 "format": "qcow2" } },
9180 { "type": "blockdev-snapshot-internal-sync", "data" : {
9181 "device": "ide-hd2",
9182 "name": "snapshot0" } } ] } }
9183 <- { "return": {} }
9184
9186 qmp_capabilities (Command)
9187 Enable QMP capabilities.
9188 Arguments:
9190 Arguments
9192 enable: array of QMPCapability (optional)
9193 An optional list of QMPCapability values to enable. The client
9194 must not enable any capability that is not mentioned in the QMP
9195 greeting message. If the field is not provided, it means no QMP
9196 capabilities will be enabled. (since 2.12)
9197 Example
9199 -> { "execute": "qmp_capabilities",
9200 "arguments": { "enable": [ "oob" ] } }
9201 <- { "return": {} }
9202 Notes
9204 This command is valid exactly when first connecting: it must be issued
9205 before any other command will be accepted, and will fail once the moni‐
9206 tor is accepting other commands. (see qemu docs/interop/qmp-spec.rst)
9207 The QMP client needs to explicitly enable QMP capabilities, otherwise
9209 all the QMP capabilities will be turned off by default.
9210 Since
9212 0.13
9213 QMPCapability (Enum)
9215 Enumeration of capabilities to be advertised during initial client con‐
9216 nection, used for agreeing on particular QMP extension behaviors.
9217 Values
9219 oob QMP ability to support out-of-band requests. (Please refer to
9220 qmp-spec.rst for more information on OOB)
9221 Since
9223 2.12
9224 VersionTriple (Object)
9226 A three-part version number.
9227 Members
9229 major: int
9230 The major version number.
9231 minor: int
9233 The minor version number.
9234 micro: int
9236 The micro version number.
9237 Since
9239 2.4
9240 VersionInfo (Object)
9242 A description of QEMU's version.
9243 Members
9245 qemu: VersionTriple
9246 The version of QEMU. By current convention, a micro version of
9247 50 signifies a development branch. A micro version greater than
9248 or equal to 90 signifies a release candidate for the next minor
9249 version. A micro version of less than 50 signifies a stable re‐
9250 lease.
9251 package: string
9253 QEMU will always set this field to an empty string. Downstream
9254 versions of QEMU should set this to a non-empty string. The ex‐
9255 act format depends on the downstream however it highly recom‐
9256 mended that a unique name is used.
9257 Since
9259 0.14
9260 query-version (Command)
9262 Returns the current version of QEMU.
9263 Returns
9265 A VersionInfo object describing the current version of QEMU.
9266 Since
9268 0.14
9269 Example
9271 -> { "execute": "query-version" }
9272 <- {
9273 "return":{
9274 "qemu":{
9275 "major":0,
9276 "minor":11,
9277 "micro":5
9278 },
9279 "package":""
9280 }
9281 }
9282 CommandInfo (Object)
9284 Information about a QMP command
9285 Members
9287 name: string
9288 The command name
9289 Since
9291 0.14
9292 query-commands (Command)
9294 Return a list of supported QMP commands by this server
9295 Returns
9297 A list of CommandInfo for all supported commands
9298 Since
9300 0.14
9301 Example
9303 -> { "execute": "query-commands" }
9304 <- {
9305 "return":[
9306 {
9307 "name":"query-balloon"
9308 },
9309 {
9310 "name":"system_powerdown"
9311 }
9312 ]
9313 }
9314 Note
9316 This example has been shortened as the real response is too long.
9317 quit (Command)
9319 This command will cause the QEMU process to exit gracefully. While ev‐
9320 ery attempt is made to send the QMP response before terminating, this
9321 is not guaranteed. When using this interface, a premature EOF would
9322 not be unexpected.
9323 Since
9325 0.14
9326 Example
9328 -> { "execute": "quit" }
9329 <- { "return": {} }
9330 MonitorMode (Enum)
9332 An enumeration of monitor modes.
9333 Values
9335 readline
9336 HMP monitor (human-oriented command line interface)
9337 control
9339 QMP monitor (JSON-based machine interface)
9340 Since
9342 5.0
9343 MonitorOptions (Object)
9345 Options to be used for adding a new monitor.
9346 Members
9348 id: string (optional)
9349 Name of the monitor
9350 mode: MonitorMode (optional)
9352 Selects the monitor mode (default: readline in the system emula‐
9353 tor, control in qemu-storage-daemon)
9354 pretty: boolean (optional)
9356 Enables pretty printing (QMP only)
9357 chardev: string
9359 Name of a character device to expose the monitor on
9360 Since
9362 5.0
9363
9365 query-qmp-schema (Command)
9366 Command query-qmp-schema exposes the QMP wire ABI as an array of
9367 SchemaInfo. This lets QMP clients figure out what commands and events
9368 are available in this QEMU, and their parameters and results.
9369 However, the SchemaInfo can't reflect all the rules and restrictions
9371 that apply to QMP. It's interface introspection (figuring out what's
9372 there), not interface specification. The specification is in the QAPI
9373 schema.
9374 Furthermore, while we strive to keep the QMP wire format backwards-com‐
9376 patible across qemu versions, the introspection output is not guaran‐
9377 teed to have the same stability. For example, one version of qemu may
9378 list an object member as an optional non-variant, while another lists
9379 the same member only through the object's variants; or the type of a
9380 member may change from a generic string into a specific enum or from
9381 one specific type into an alternate that includes the original type
9382 alongside something else.
9383 Returns
9385 array of SchemaInfo, where each element describes an entity in the ABI:
9386 command, event, type, ...
9387 The order of the various SchemaInfo is unspecified; however, all names
9389 are guaranteed to be unique (no name will be duplicated with different
9390 meta-types).
9391 Note
9393 the QAPI schema is also used to help define internal interfaces, by
9394 defining QAPI types. These are not part of the QMP wire ABI, and
9395 therefore not returned by this command.
9396 Since
9398 2.5
9399 SchemaMetaType (Enum)
9401 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
9402 Values
9404 builtin
9405 a predefined type such as 'int' or 'bool'.
9406 enum an enumeration type
9408 array an array type
9410 object an object type (struct or union)
9412 alternate
9414 an alternate type
9415 command
9417 a QMP command
9418 event a QMP event
9420 Since
9422 2.5
9423 SchemaInfo (Object)
9425 Members
9426 name: string
9427 the entity's name, inherited from base. The SchemaInfo is al‐
9428 ways referenced by this name. Commands and events have the name
9429 defined in the QAPI schema. Unlike command and event names,
9430 type names are not part of the wire ABI. Consequently, type
9431 names are meaningless strings here, although they are still
9432 guaranteed unique regardless of meta-type.
9433 meta-type: SchemaMetaType
9435 the entity's meta type, inherited from base.
9436 features: array of string (optional)
9438 names of features associated with the entity, in no particular
9439 order. (since 4.1 for object types, 4.2 for commands, 5.0 for
9440 the rest)
9441 The members of SchemaInfoBuiltin when meta-type is "builtin"
9443 The members of SchemaInfoEnum when meta-type is "enum"
9445 The members of SchemaInfoArray when meta-type is "array"
9447 The members of SchemaInfoObject when meta-type is "object"
9449 The members of SchemaInfoAlternate when meta-type is "alternate"
9451 The members of SchemaInfoCommand when meta-type is "command"
9453 The members of SchemaInfoEvent when meta-type is "event"
9455 Additional members depend on the value of meta-type.
9456 Since
9458 2.5
9459 SchemaInfoBuiltin (Object)
9461 Additional SchemaInfo members for meta-type 'builtin'.
9462 Members
9464 json-type: JSONType
9465 the JSON type used for this type on the wire.
9466 Since
9468 2.5
9469 JSONType (Enum)
9471 The four primitive and two structured types according to RFC 8259 sec‐
9472 tion 1, plus 'int' (split off 'number'), plus the obvious top type
9473 'value'.
9474 Values
9476 string Not documented
9477 number Not documented
9479 int Not documented
9481 boolean
9483 Not documented
9484 null Not documented
9486 object Not documented
9488 array Not documented
9490 value Not documented
9492 Since
9494 2.5
9495 SchemaInfoEnum (Object)
9497 Additional SchemaInfo members for meta-type 'enum'.
9498 Members
9500 members: array of SchemaInfoEnumMember
9501 the enum type's members, in no particular order (since 6.2).
9502 values: array of string
9504 the enumeration type's member names, in no particular order.
9505 Redundant with members. Just for backward compatibility.
9506 Features
9508 deprecated
9509 Member values is deprecated. Use members instead.
9510 Values of this type are JSON string on the wire.
9511 Since
9513 2.5
9514 SchemaInfoEnumMember (Object)
9516 An object member.
9517 Members
9519 name: string
9520 the member's name, as defined in the QAPI schema.
9521 features: array of string (optional)
9523 names of features associated with the member, in no particular
9524 order.
9525 Since
9527 6.2
9528 SchemaInfoArray (Object)
9530 Additional SchemaInfo members for meta-type 'array'.
9531 Members
9533 element-type: string
9534 the array type's element type.
9535 Values of this type are JSON array on the wire.
9536 Since
9538 2.5
9539 SchemaInfoObject (Object)
9541 Additional SchemaInfo members for meta-type 'object'.
9542 Members
9544 members: array of SchemaInfoObjectMember
9545 the object type's (non-variant) members, in no particular order.
9546 tag: string (optional)
9548 the name of the member serving as type tag. An element of mem‐
9549 bers with this name must exist.
9550 variants: array of SchemaInfoObjectVariant (optional)
9552 variant members, i.e. additional members that depend on the type
9553 tag's value. Present exactly when tag is present. The variants
9554 are in no particular order, and may even differ from the order
9555 of the values of the enum type of the tag.
9556 Values of this type are JSON object on the wire.
9557 Since
9559 2.5
9560 SchemaInfoObjectMember (Object)
9562 An object member.
9563 Members
9565 name: string
9566 the member's name, as defined in the QAPI schema.
9567 type: string
9569 the name of the member's type.
9570 default: value (optional)
9572 default when used as command parameter. If absent, the parame‐
9573 ter is mandatory. If present, the value must be null. The pa‐
9574 rameter is optional, and behavior when it's missing is not spec‐
9575 ified here. Future extension: if present and non-null, the pa‐
9576 rameter is optional, and defaults to this value.
9577 features: array of string (optional)
9579 names of features associated with the member, in no particular
9580 order. (since 5.0)
9581 Since
9583 2.5
9584 SchemaInfoObjectVariant (Object)
9586 The variant members for a value of the type tag.
9587 Members
9589 case: string
9590 a value of the type tag.
9591 type: string
9593 the name of the object type that provides the variant members
9594 when the type tag has value case.
9595 Since
9597 2.5
9598 SchemaInfoAlternate (Object)
9600 Additional SchemaInfo members for meta-type 'alternate'.
9601 Members
9603 members: array of SchemaInfoAlternateMember
9604 the alternate type's members, in no particular order. The mem‐
9605 bers' wire encoding is distinct, see docs/de‐
9606 vel/qapi-code-gen.txt section Alternate types.
9607 On the wire, this can be any of the members.
9608 Since
9610 2.5
9611 SchemaInfoAlternateMember (Object)
9613 An alternate member.
9614 Members
9616 type: string
9617 the name of the member's type.
9618 Since
9620 2.5
9621 SchemaInfoCommand (Object)
9623 Additional SchemaInfo members for meta-type 'command'.
9624 Members
9626 arg-type: string
9627 the name of the object type that provides the command's parame‐
9628 ters.
9629 ret-type: string
9631 the name of the command's result type.
9632 allow-oob: boolean (optional)
9634 whether the command allows out-of-band execution, defaults to
9635 false (Since: 2.12)
9636 Since
9638 2.5
9639 SchemaInfoEvent (Object)
9641 Additional SchemaInfo members for meta-type 'event'.
9642 Members
9644 arg-type: string
9645 the name of the object type that provides the event's parame‐
9646 ters.
9647 Since
9649 2.5
9650
9652 ObjectPropertyInfo (Object)
9653 Members
9654 name: string
9655 the name of the property
9656 type: string
9658 the type of the property. This will typically come in one of
9659 four forms:
9660 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
9662 ble'. These types are mapped to the appropriate JSON type.
9663 2. A child type in the form 'child<subtype>' where subtype is a
9665 qdev device type name. Child properties create the composi‐
9666 tion tree.
9667 3. A link type in the form 'link<subtype>' where subtype is a
9669 qdev device type name. Link properties form the device model
9670 graph.
9671 description: string (optional)
9673 if specified, the description of the property.
9674 default-value: value (optional)
9676 the default value, if any (since 5.0)
9677 Since
9679 1.2
9680 qom-list (Command)
9682 This command will list any properties of a object given a path in the
9683 object model.
9684 Arguments
9686 path: string
9687 the path within the object model. See qom-get for a description
9688 of this parameter.
9689 Returns
9691 a list of ObjectPropertyInfo that describe the properties of the ob‐
9692 ject.
9693 Since
9695 1.2
9696 Example
9698 -> { "execute": "qom-list",
9699 "arguments": { "path": "/chardevs" } }
9700 <- { "return": [ { "name": "type", "type": "string" },
9701 { "name": "parallel0", "type": "child<chardev-vc>" },
9702 { "name": "serial0", "type": "child<chardev-vc>" },
9703 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
9704 qom-get (Command)
9706 This command will get a property from a object model path and return
9707 the value.
9708 Arguments
9710 path: string
9711 The path within the object model. There are two forms of sup‐
9712 ported paths--absolute and partial paths.
9713 Absolute paths are derived from the root object and can follow
9715 child<> or link<> properties. Since they can follow link<>
9716 properties, they can be arbitrarily long. Absolute paths look
9717 like absolute filenames and are prefixed with a leading slash.
9718 Partial paths look like relative filenames. They do not begin
9720 with a prefix. The matching rules for partial paths are subtle
9721 but designed to make specifying objects easy. At each level of
9722 the composition tree, the partial path is matched as an absolute
9723 path. The first match is not returned. At least two matches
9724 are searched for. A successful result is only returned if only
9725 one match is found. If more than one match is found, a flag is
9726 return to indicate that the match was ambiguous.
9727 property: string
9729 The property name to read
9730 Returns
9732 The property value. The type depends on the property type. child<>
9733 and link<> properties are returned as #str pathnames. All integer
9734 property types (u8, u16, etc) are returned as #int.
9735 Since
9737 1.2
9738 Examples
9740 1. Use absolute path
9741 -> { "execute": "qom-get",
9743 "arguments": { "path": "/machine/unattached/device[0]",
9744 "property": "hotplugged" } }
9745 <- { "return": false }
9746 2. Use partial path
9748 -> { "execute": "qom-get",
9750 "arguments": { "path": "unattached/sysbus",
9751 "property": "type" } }
9752 <- { "return": "System" }
9753 qom-set (Command)
9755 This command will set a property from a object model path.
9756 Arguments
9758 path: string
9759 see qom-get for a description of this parameter
9760 property: string
9762 the property name to set
9763 value: value
9765 a value who's type is appropriate for the property type. See
9766 qom-get for a description of type mapping.
9767 Since
9769 1.2
9770 Example
9772 -> { "execute": "qom-set",
9773 "arguments": { "path": "/machine",
9774 "property": "graphics",
9775 "value": false } }
9776 <- { "return": {} }
9777 ObjectTypeInfo (Object)
9779 This structure describes a search result from qom-list-types
9780 Members
9782 name: string
9783 the type name found in the search
9784 abstract: boolean (optional)
9786 the type is abstract and can't be directly instantiated. Omit‐
9787 ted if false. (since 2.10)
9788 parent: string (optional)
9790 Name of parent type, if any (since 2.10)
9791 Since
9793 1.1
9794 qom-list-types (Command)
9796 This command will return a list of types given search parameters
9797 Arguments
9799 implements: string (optional)
9800 if specified, only return types that implement this type name
9801 abstract: boolean (optional)
9803 if true, include abstract types in the results
9804 Returns
9806 a list of ObjectTypeInfo or an empty list if no results are found
9807 Since
9809 1.1
9810 qom-list-properties (Command)
9812 List properties associated with a QOM object.
9813 Arguments
9815 typename: string
9816 the type name of an object
9817 Note
9819 objects can create properties at runtime, for example to describe links
9820 between different devices and/or objects. These properties are not in‐
9821 cluded in the output of this command.
9822 Returns
9824 a list of ObjectPropertyInfo describing object properties
9825 Since
9827 2.12
9828 CanHostSocketcanProperties (Object)
9830 Properties for can-host-socketcan objects.
9831 Members
9833 if: string
9834 interface name of the host system CAN bus to connect to
9835 canbus: string
9837 object ID of the can-bus object to connect to the host interface
9838 Since
9840 2.12
9841 ColoCompareProperties (Object)
9843 Properties for colo-compare objects.
9844 Members
9846 primary_in: string
9847 name of the character device backend to use for the primary in‐
9848 put (incoming packets are redirected to outdev)
9849 secondary_in: string
9851 name of the character device backend to use for secondary input
9852 (incoming packets are only compared to the input on primary_in
9853 and then dropped)
9854 outdev: string
9856 name of the character device backend to use for output
9857 iothread: string
9859 name of the iothread to run in
9860 notify_dev: string (optional)
9862 name of the character device backend to be used to communicate
9863 with the remote colo-frame (only for Xen COLO)
9864 compare_timeout: int (optional)
9866 the maximum time to hold a packet from primary_in for comparison
9867 with an incoming packet on secondary_in in milliseconds (de‐
9868 fault: 3000)
9869 expired_scan_cycle: int (optional)
9871 the interval at which colo-compare checks whether packets from
9872 primary have timed out, in milliseconds (default: 3000)
9873 max_queue_size: int (optional)
9875 the maximum number of packets to keep in the queue for comparing
9876 with incoming packets from secondary_in. If the queue is full
9877 and additional packets are received, the additional packets are
9878 dropped. (default: 1024)
9879 vnet_hdr_support: boolean (optional)
9881 if true, vnet header support is enabled (default: false)
9882 Since
9884 2.8
9885 CryptodevBackendProperties (Object)
9887 Properties for cryptodev-backend and cryptodev-backend-builtin objects.
9888 Members
9890 queues: int (optional)
9891 the number of queues for the cryptodev backend. Ignored for
9892 cryptodev-backend and must be 1 for cryptodev-backend-builtin.
9893 (default: 1)
9894 throttle-bps: int (optional)
9896 limit total bytes per second (Since 8.0)
9897 throttle-ops: int (optional)
9899 limit total operations per second (Since 8.0)
9900 Since
9902 2.8
9903 CryptodevVhostUserProperties (Object)
9905 Properties for cryptodev-vhost-user objects.
9906 Members
9908 chardev: string
9909 the name of a Unix domain socket character device that connects
9910 to the vhost-user server
9911 The members of CryptodevBackendProperties
9913 Since
9915 2.12
9916 DBusVMStateProperties (Object)
9918 Properties for dbus-vmstate objects.
9919 Members
9921 addr: string
9922 the name of the DBus bus to connect to
9923 id-list: string (optional)
9925 a comma separated list of DBus IDs of helpers whose data should
9926 be included in the VM state on migration
9927 Since
9929 5.0
9930 NetfilterInsert (Enum)
9932 Indicates where to insert a netfilter relative to a given other filter.
9933 Values
9935 before insert before the specified filter
9936 behind insert behind the specified filter
9938 Since
9940 5.0
9941 NetfilterProperties (Object)
9943 Properties for objects of classes derived from netfilter.
9944 Members
9946 netdev: string
9947 id of the network device backend to filter
9948 queue: NetFilterDirection (optional)
9950 indicates which queue(s) to filter (default: all)
9951 status: string (optional)
9953 indicates whether the filter is enabled ("on") or disabled
9954 ("off") (default: "on")
9955 position: string (optional)
9957 specifies where the filter should be inserted in the filter
9958 list. "head" means the filter is inserted at the head of the
9959 filter list, before any existing filters. "tail" means the fil‐
9960 ter is inserted at the tail of the filter list, behind any ex‐
9961 isting filters (default). "id=<id>" means the filter is inserted
9962 before or behind the filter specified by <id>, depending on the
9963 insert property. (default: "tail")
9964 insert: NetfilterInsert (optional)
9966 where to insert the filter relative to the filter given in posi‐
9967 tion. Ignored if position is "head" or "tail". (default: be‐
9968 hind)
9969 Since
9971 2.5
9972 FilterBufferProperties (Object)
9974 Properties for filter-buffer objects.
9975 Members
9977 interval: int
9978 a non-zero interval in microseconds. All packets arriving in
9979 the given interval are delayed until the end of the interval.
9980 The members of NetfilterProperties
9982 Since
9984 2.5
9985 FilterDumpProperties (Object)
9987 Properties for filter-dump objects.
9988 Members
9990 file: string
9991 the filename where the dumped packets should be stored
9992 maxlen: int (optional)
9994 maximum number of bytes in a packet that are stored (default:
9995 65536)
9996 The members of NetfilterProperties
9998 Since
10000 2.5
10001 FilterMirrorProperties (Object)
10003 Properties for filter-mirror objects.
10004 Members
10006 outdev: string
10007 the name of a character device backend to which all incoming
10008 packets are mirrored
10009 vnet_hdr_support: boolean (optional)
10011 if true, vnet header support is enabled (default: false)
10012 The members of NetfilterProperties
10014 Since
10016 2.6
10017 FilterRedirectorProperties (Object)
10019 Properties for filter-redirector objects.
10020 At least one of indev or outdev must be present. If both are present,
10022 they must not refer to the same character device backend.
10023 Members
10025 indev: string (optional)
10026 the name of a character device backend from which packets are
10027 received and redirected to the filtered network device
10028 outdev: string (optional)
10030 the name of a character device backend to which all incoming
10031 packets are redirected
10032 vnet_hdr_support: boolean (optional)
10034 if true, vnet header support is enabled (default: false)
10035 The members of NetfilterProperties
10037 Since
10039 2.6
10040 FilterRewriterProperties (Object)
10042 Properties for filter-rewriter objects.
10043 Members
10045 vnet_hdr_support: boolean (optional)
10046 if true, vnet header support is enabled (default: false)
10047 The members of NetfilterProperties
10049 Since
10051 2.8
10052 InputBarrierProperties (Object)
10054 Properties for input-barrier objects.
10055 Members
10057 name: string
10058 the screen name as declared in the screens section of bar‐
10059 rier.conf
10060 server: string (optional)
10062 hostname of the Barrier server (default: "localhost")
10063 port: string (optional)
10065 TCP port of the Barrier server (default: "24800")
10066 x-origin: string (optional)
10068 x coordinate of the leftmost pixel on the guest screen (default:
10069 "0")
10070 y-origin: string (optional)
10072 y coordinate of the topmost pixel on the guest screen (default:
10073 "0")
10074 width: string (optional)
10076 the width of secondary screen in pixels (default: "1920")
10077 height: string (optional)
10079 the height of secondary screen in pixels (default: "1080")
10080 Since
10082 4.2
10083 InputLinuxProperties (Object)
10085 Properties for input-linux objects.
10086 Members
10088 evdev: string
10089 the path of the host evdev device to use
10090 grab_all: boolean (optional)
10092 if true, grab is toggled for all devices (e.g. both keyboard and
10093 mouse) instead of just one device (default: false)
10094 repeat: boolean (optional)
10096 enables auto-repeat events (default: false)
10097 grab-toggle: GrabToggleKeys (optional)
10099 the key or key combination that toggles device grab (default:
10100 ctrl-ctrl)
10101 Since
10103 2.6
10104 EventLoopBaseProperties (Object)
10106 Common properties for event loops
10107 Members
10109 aio-max-batch: int (optional)
10110 maximum number of requests in a batch for the AIO engine, 0
10111 means that the engine will use its default. (default: 0)
10112 thread-pool-min: int (optional)
10114 minimum number of threads reserved in the thread pool (de‐
10115 fault:0)
10116 thread-pool-max: int (optional)
10118 maximum number of threads the thread pool can contain (de‐
10119 fault:64)
10120 Since
10122 7.1
10123 IothreadProperties (Object)
10125 Properties for iothread objects.
10126 Members
10128 poll-max-ns: int (optional)
10129 the maximum number of nanoseconds to busy wait for events. 0
10130 means polling is disabled (default: 32768 on POSIX hosts, 0 oth‐
10131 erwise)
10132 poll-grow: int (optional)
10134 the multiplier used to increase the polling time when the algo‐
10135 rithm detects it is missing events due to not polling long
10136 enough. 0 selects a default behaviour (default: 0)
10137 poll-shrink: int (optional)
10139 the divisor used to decrease the polling time when the algorithm
10140 detects it is spending too long polling without encountering
10141 events. 0 selects a default behaviour (default: 0)
10142 The members of EventLoopBaseProperties
10144 The aio-max-batch option is available since 6.1.
10145 Since
10147 2.0
10148 MainLoopProperties (Object)
10150 Properties for the main-loop object.
10151 Members
10153 The members of EventLoopBaseProperties
10154 Since
10156 7.1
10157 MemoryBackendProperties (Object)
10159 Properties for objects of classes derived from memory-backend.
10160 Members
10162 merge: boolean (optional)
10163 if true, mark the memory as mergeable (default depends on the
10164 machine type)
10165 dump: boolean (optional)
10167 if true, include the memory in core dumps (default depends on
10168 the machine type)
10169 host-nodes: array of int (optional)
10171 the list of NUMA host nodes to bind the memory to
10172 policy: HostMemPolicy (optional)
10174 the NUMA policy (default: 'default')
10175 prealloc: boolean (optional)
10177 if true, preallocate memory (default: false)
10178 prealloc-threads: int (optional)
10180 number of CPU threads to use for prealloc (default: 1)
10181 prealloc-context: string (optional)
10183 thread context to use for creation of preallocation threads (de‐
10184 fault: none) (since 7.2)
10185 share: boolean (optional)
10187 if false, the memory is private to QEMU; if true, it is shared
10188 (default: false)
10189 reserve: boolean (optional)
10191 if true, reserve swap space (or huge pages) if applicable (de‐
10192 fault: true) (since 6.1)
10193 size: int
10195 size of the memory region in bytes
10196 x-use-canonical-path-for-ramblock-id: boolean (optional)
10198 if true, the canonical path is used for ramblock-id. Disable
10199 this for 4.0 machine types or older to allow migration with
10200 newer QEMU versions. (default: false generally, but true for
10201 machine types <= 4.0)
10202 Note
10204 prealloc=true and reserve=false cannot be set at the same time. With
10205 reserve=true, the behavior depends on the operating system: for exam‐
10206 ple, Linux will not reserve swap space for shared file mappings -- "not
10207 applicable". In contrast, reserve=false will bail out if it cannot be
10208 configured accordingly.
10209 Since
10211 2.1
10212 MemoryBackendFileProperties (Object)
10214 Properties for memory-backend-file objects.
10215 Members
10217 align: int (optional)
10218 the base address alignment when QEMU mmap(2)s mem-path. Some
10219 backend stores specified by mem-path require an alignment dif‐
10220 ferent than the default one used by QEMU, e.g. the device DAX
10221 /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
10222 users can specify the required alignment via this option. 0 se‐
10223 lects a default alignment (currently the page size). (default:
10224 0)
10225 offset: int (optional)
10227 the offset into the target file that the region starts at. You
10228 can use this option to back multiple regions with a single file.
10229 Must be a multiple of the page size. (default: 0) (since 8.1)
10230 discard-data: boolean (optional)
10232 if true, the file contents can be destroyed when QEMU exits, to
10233 avoid unnecessarily flushing data to the backing file. Note
10234 that discard-data is only an optimization, and QEMU might not
10235 discard file contents if it aborts unexpectedly or is terminated
10236 using SIGKILL. (default: false)
10237 mem-path: string
10239 the path to either a shared memory or huge page filesystem mount
10240 pmem: boolean (optional) (If: CONFIG_LIBPMEM)
10242 specifies whether the backing file specified by mem-path is in
10243 host persistent memory that can be accessed using the SNIA NVM
10244 programming model (e.g. Intel NVDIMM).
10245 readonly: boolean (optional)
10247 if true, the backing file is opened read-only; if false, it is
10248 opened read-write. (default: false)
10249 The members of MemoryBackendProperties
10251 Since
10253 2.1
10254 MemoryBackendMemfdProperties (Object)
10256 Properties for memory-backend-memfd objects.
10257 The share boolean option is true by default with memfd.
10259 Members
10261 hugetlb: boolean (optional)
10262 if true, the file to be created resides in the hugetlbfs
10263 filesystem (default: false)
10264 hugetlbsize: int (optional)
10266 the hugetlb page size on systems that support multiple hugetlb
10267 page sizes (it must be a power of 2 value supported by the sys‐
10268 tem). 0 selects a default page size. This option is ignored if
10269 hugetlb is false. (default: 0)
10270 seal: boolean (optional)
10272 if true, create a sealed-file, which will block further resizing
10273 of the memory (default: true)
10274 The members of MemoryBackendProperties
10276 Since
10278 2.12
10279 MemoryBackendEpcProperties (Object)
10281 Properties for memory-backend-epc objects.
10282 The share boolean option is true by default with epc
10284 The merge boolean option is false by default with epc
10286 The dump boolean option is false by default with epc
10288 Members
10290 The members of MemoryBackendProperties
10291 Since
10293 6.2
10294 PrManagerHelperProperties (Object)
10296 Properties for pr-manager-helper objects.
10297 Members
10299 path: string
10300 the path to a Unix domain socket for connecting to the external
10301 helper
10302 Since
10304 2.11
10305 QtestProperties (Object)
10307 Properties for qtest objects.
10308 Members
10310 chardev: string
10311 the chardev to be used to receive qtest commands on.
10312 log: string (optional)
10314 the path to a log file
10315 Since
10317 6.0
10318 RemoteObjectProperties (Object)
10320 Properties for x-remote-object objects.
10321 Members
10323 fd: string
10324 file descriptor name previously passed via 'getfd' command
10325 devid: string
10327 the id of the device to be associated with the file descriptor
10328 Since
10330 6.0
10331 VfioUserServerProperties (Object)
10333 Properties for x-vfio-user-server objects.
10334 Members
10336 socket: SocketAddress
10337 socket to be used by the libvfio-user library
10338 device: string
10340 the ID of the device to be emulated at the server
10341 Since
10343 7.1
10344 RngProperties (Object)
10346 Properties for objects of classes derived from rng.
10347 Members
10349 opened: boolean (optional)
10350 if true, the device is opened immediately when applying this op‐
10351 tion and will probably fail when processing the next option.
10352 Don't use; only provided for compatibility. (default: false)
10353 Features
10355 deprecated
10356 Member opened is deprecated. Setting true doesn't make sense,
10357 and false is already the default.
10358 Since
10360 1.3
10361 RngEgdProperties (Object)
10363 Properties for rng-egd objects.
10364 Members
10366 chardev: string
10367 the name of a character device backend that provides the connec‐
10368 tion to the RNG daemon
10369 The members of RngProperties
10371 Since
10373 1.3
10374 RngRandomProperties (Object)
10376 Properties for rng-random objects.
10377 Members
10379 filename: string (optional)
10380 the filename of the device on the host to obtain entropy from
10381 (default: "/dev/urandom")
10382 The members of RngProperties
10384 Since
10386 1.3
10387 SevGuestProperties (Object)
10389 Properties for sev-guest objects.
10390 Members
10392 sev-device: string (optional)
10393 SEV device to use (default: "/dev/sev")
10394 dh-cert-file: string (optional)
10396 guest owners DH certificate (encoded with base64)
10397 session-file: string (optional)
10399 guest owners session parameters (encoded with base64)
10400 policy: int (optional)
10402 SEV policy value (default: 0x1)
10403 handle: int (optional)
10405 SEV firmware handle (default: 0)
10406 cbitpos: int (optional)
10408 C-bit location in page table entry (default: 0)
10409 reduced-phys-bits: int
10411 number of bits in physical addresses that become unavailable
10412 when SEV is enabled
10413 kernel-hashes: boolean (optional)
10415 if true, add hashes of kernel/initrd/cmdline to a designated
10416 guest firmware page for measured boot with -kernel (default:
10417 false) (since 6.2)
10418 Since
10420 2.12
10421 ThreadContextProperties (Object)
10423 Properties for thread context objects.
10424 Members
10426 cpu-affinity: array of int (optional)
10427 the list of host CPU numbers used as CPU affinity for all
10428 threads created in the thread context (default: QEMU main thread
10429 CPU affinity)
10430 node-affinity: array of int (optional)
10432 the list of host node numbers that will be resolved to a list of
10433 host CPU numbers used as CPU affinity. This is a shortcut for
10434 specifying the list of host CPU numbers belonging to the host
10435 nodes manually by setting cpu-affinity. (default: QEMU main
10436 thread affinity)
10437 Since
10439 7.2
10440 ObjectType (Enum)
10442 Values
10443 authz-list
10444 Not documented
10445 authz-listfile
10447 Not documented
10448 authz-pam
10450 Not documented
10451 authz-simple
10453 Not documented
10454 can-bus
10456 Not documented
10457 can-host-socketcan (If: CONFIG_LINUX)
10459 Not documented
10460 colo-compare
10462 Not documented
10463 cryptodev-backend
10465 Not documented
10466 cryptodev-backend-builtin
10468 Not documented
10469 cryptodev-backend-lkcf
10471 Not documented
10472 cryptodev-vhost-user (If: CONFIG_VHOST_CRYPTO)
10474 Not documented
10475 dbus-vmstate
10477 Not documented
10478 filter-buffer
10480 Not documented
10481 filter-dump
10483 Not documented
10484 filter-mirror
10486 Not documented
10487 filter-redirector
10489 Not documented
10490 filter-replay
10492 Not documented
10493 filter-rewriter
10495 Not documented
10496 input-barrier
10498 Not documented
10499 input-linux (If: CONFIG_LINUX)
10501 Not documented
10502 iothread
10504 Not documented
10505 main-loop
10507 Not documented
10508 memory-backend-epc (If: CONFIG_LINUX)
10510 Not documented
10511 memory-backend-file
10513 Not documented
10514 memory-backend-memfd (If: CONFIG_LINUX)
10516 Not documented
10517 memory-backend-ram
10519 Not documented
10520 pef-guest
10522 Not documented
10523 pr-manager-helper (If: CONFIG_LINUX)
10525 Not documented
10526 qtest Not documented
10528 rng-builtin
10530 Not documented
10531 rng-egd
10533 Not documented
10534 rng-random (If: CONFIG_POSIX)
10536 Not documented
10537 secret Not documented
10539 secret_keyring (If: CONFIG_SECRET_KEYRING)
10541 Not documented
10542 sev-guest
10544 Not documented
10545 thread-context
10547 Not documented
10548 s390-pv-guest
10550 Not documented
10551 throttle-group
10553 Not documented
10554 tls-creds-anon
10556 Not documented
10557 tls-creds-psk
10559 Not documented
10560 tls-creds-x509
10562 Not documented
10563 tls-cipher-suites
10565 Not documented
10566 x-remote-object
10568 Not documented
10569 x-vfio-user-server
10571 Not documented
10572 Features
10574 unstable
10575 Member x-remote-object is experimental.
10576 Since
10578 6.0
10579 ObjectOptions (Object)
10581 Describes the options of a user creatable QOM object.
10582 Members
10584 qom-type: ObjectType
10585 the class name for the object to be created
10586 id: string
10588 the name of the new object
10589 The members of AuthZListProperties when qom-type is "authz-list"
10591 The members of AuthZListFileProperties when qom-type is "authz-list‐
10593 file"
10594 The members of AuthZPAMProperties when qom-type is "authz-pam"
10596 The members of AuthZSimpleProperties when qom-type is "authz-simple"
10598 The members of CanHostSocketcanProperties when qom-type is
10600 "can-host-socketcan" (If: CONFIG_LINUX)
10601 The members of ColoCompareProperties when qom-type is "colo-compare"
10603 The members of CryptodevBackendProperties when qom-type is "cryp‐
10605 todev-backend"
10606 The members of CryptodevBackendProperties when qom-type is "cryp‐
10608 todev-backend-builtin"
10609 The members of CryptodevBackendProperties when qom-type is "cryp‐
10611 todev-backend-lkcf"
10612 The members of CryptodevVhostUserProperties when qom-type is "cryp‐
10614 todev-vhost-user" (If: CONFIG_VHOST_CRYPTO)
10615 The members of DBusVMStateProperties when qom-type is "dbus-vmstate"
10617 The members of FilterBufferProperties when qom-type is "filter-buffer"
10619 The members of FilterDumpProperties when qom-type is "filter-dump"
10621 The members of FilterMirrorProperties when qom-type is "filter-mirror"
10623 The members of FilterRedirectorProperties when qom-type is "fil‐
10625 ter-redirector"
10626 The members of NetfilterProperties when qom-type is "filter-replay"
10628 The members of FilterRewriterProperties when qom-type is "fil‐
10630 ter-rewriter"
10631 The members of InputBarrierProperties when qom-type is "input-barrier"
10633 The members of InputLinuxProperties when qom-type is "input-linux" (If:
10635 CONFIG_LINUX)
10636 The members of IothreadProperties when qom-type is "iothread"
10638 The members of MainLoopProperties when qom-type is "main-loop"
10640 The members of MemoryBackendEpcProperties when qom-type is "mem‐
10642 ory-backend-epc" (If: CONFIG_LINUX)
10643 The members of MemoryBackendFileProperties when qom-type is "mem‐
10645 ory-backend-file"
10646 The members of MemoryBackendMemfdProperties when qom-type is "mem‐
10648 ory-backend-memfd" (If: CONFIG_LINUX)
10649 The members of MemoryBackendProperties when qom-type is "memory-back‐
10651 end-ram"
10652 The members of PrManagerHelperProperties when qom-type is "pr-man‐
10654 ager-helper" (If: CONFIG_LINUX)
10655 The members of QtestProperties when qom-type is "qtest"
10657 The members of RngProperties when qom-type is "rng-builtin"
10659 The members of RngEgdProperties when qom-type is "rng-egd"
10661 The members of RngRandomProperties when qom-type is "rng-random" (If:
10663 CONFIG_POSIX)
10664 The members of SecretProperties when qom-type is "secret"
10666 The members of SecretKeyringProperties when qom-type is "se‐
10668 cret_keyring" (If: CONFIG_SECRET_KEYRING)
10669 The members of SevGuestProperties when qom-type is "sev-guest"
10671 The members of ThreadContextProperties when qom-type is "thread-con‐
10673 text"
10674 The members of ThrottleGroupProperties when qom-type is "throt‐
10676 tle-group"
10677 The members of TlsCredsAnonProperties when qom-type is "tls-creds-anon"
10679 The members of TlsCredsPskProperties when qom-type is "tls-creds-psk"
10681 The members of TlsCredsX509Properties when qom-type is "tls-creds-x509"
10683 The members of TlsCredsProperties when qom-type is "tls-cipher-suites"
10685 The members of RemoteObjectProperties when qom-type is "x-remote-ob‐
10687 ject"
10688 The members of VfioUserServerProperties when qom-type is
10690 "x-vfio-user-server"
10691 Since
10693 6.0
10694 object-add (Command)
10696 Create a QOM object.
10697 Arguments
10699 The members of ObjectOptions
10700 Returns
10702 Nothing on success Error if qom-type is not a valid class name
10703 Since
10705 2.0
10706 Example
10708 -> { "execute": "object-add",
10709 "arguments": { "qom-type": "rng-random", "id": "rng1",
10710 "filename": "/dev/hwrng" } }
10711 <- { "return": {} }
10712 object-del (Command)
10714 Remove a QOM object.
10715 Arguments
10717 id: string
10718 the name of the QOM object to remove
10719 Returns
10721 Nothing on success Error if id is not a valid id for a QOM object
10722 Since
10724 2.0
10725 Example
10727 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
10728 <- { "return": {} }
10729
10731 2023, The QEMU Project Developers
107328.1.3 Nov 28, 2023 QEMU-STORAGE-DAEMON-QMP-REF(7)