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 • Block devices
12 • Block core (VM unrelated)
14 • Common data types
16 • IoOperationType (Enum)
18 • OnOffAuto (Enum)
20 • OnOffSplit (Enum)
22 • String (Object)
24 • StrOrNull (Alternate)
26 • OffAutoPCIBAR (Enum)
28 • PCIELinkSpeed (Enum)
30 • PCIELinkWidth (Enum)
32 • HostMemPolicy (Enum)
34 • NetFilterDirection (Enum)
36 • GrabToggleKeys (Enum)
38 • HumanReadableText (Object)
40 • Cryptography
42 • QCryptoTLSCredsEndpoint (Enum)
44 • QCryptoSecretFormat (Enum)
46 • QCryptoHashAlgorithm (Enum)
48 • QCryptoCipherAlgorithm (Enum)
50 • QCryptoCipherMode (Enum)
52 • QCryptoIVGenAlgorithm (Enum)
54 • QCryptoBlockFormat (Enum)
56 • QCryptoBlockOptionsBase (Object)
58 • QCryptoBlockOptionsQCow (Object)
60 • QCryptoBlockOptionsLUKS (Object)
62 • QCryptoBlockCreateOptionsLUKS (Object)
64 • QCryptoBlockOpenOptions (Object)
66 • QCryptoBlockCreateOptions (Object)
68 • QCryptoBlockInfoBase (Object)
70 • QCryptoBlockInfoLUKSSlot (Object)
72 • QCryptoBlockInfoLUKS (Object)
74 • QCryptoBlockInfo (Object)
76 • QCryptoBlockLUKSKeyslotState (Enum)
78 • QCryptoBlockAmendOptionsLUKS (Object)
80 • QCryptoBlockAmendOptions (Object)
82 • SecretCommonProperties (Object)
84 • SecretProperties (Object)
86 • SecretKeyringProperties (Object)
88 • TlsCredsProperties (Object)
90 • TlsCredsAnonProperties (Object)
92 • TlsCredsPskProperties (Object)
94 • TlsCredsX509Properties (Object)
96 • QCryptoAkCipherAlgorithm (Enum)
98 • QCryptoAkCipherKeyType (Enum)
100 • QCryptoRSAPaddingAlgorithm (Enum)
102 • QCryptoAkCipherOptionsRSA (Object)
104 • QCryptoAkCipherOptions (Object)
106 • Background jobs
108 • Socket data types
110 • NetworkAddressFamily (Enum)
112 • InetSocketAddressBase (Object)
114 • InetSocketAddress (Object)
116 • UnixSocketAddress (Object)
118 • VsockSocketAddress (Object)
120 • InetSocketAddressWrapper (Object)
122 • UnixSocketAddressWrapper (Object)
124 • VsockSocketAddressWrapper (Object)
126 • StringWrapper (Object)
128 • SocketAddressLegacy (Object)
130 • SocketAddressType (Enum)
132 • SocketAddress (Object)
134 • SnapshotInfo (Object)
136 • ImageInfoSpecificQCow2EncryptionBase (Object)
138 • ImageInfoSpecificQCow2Encryption (Object)
140 • ImageInfoSpecificQCow2 (Object)
142 • ImageInfoSpecificVmdk (Object)
144 • ImageInfoSpecificRbd (Object)
146 • ImageInfoSpecificKind (Enum)
148 • ImageInfoSpecificQCow2Wrapper (Object)
150 • ImageInfoSpecificVmdkWrapper (Object)
152 • ImageInfoSpecificLUKSWrapper (Object)
154 • ImageInfoSpecificRbdWrapper (Object)
156 • ImageInfoSpecific (Object)
158 • ImageInfo (Object)
160 • ImageCheck (Object)
162 • MapEntry (Object)
164 • BlockdevCacheInfo (Object)
166 • BlockDeviceInfo (Object)
168 • BlockDeviceIoStatus (Enum)
170 • BlockDirtyInfo (Object)
172 • Qcow2BitmapInfoFlags (Enum)
174 • Qcow2BitmapInfo (Object)
176 • BlockLatencyHistogramInfo (Object)
178 • BlockInfo (Object)
180 • BlockMeasureInfo (Object)
182 • query-block (Command)
184 • BlockDeviceTimedStats (Object)
186 • BlockDeviceStats (Object)
188 • BlockStatsSpecificFile (Object)
190 • BlockStatsSpecificNvme (Object)
192 • BlockStatsSpecific (Object)
194 • BlockStats (Object)
196 • query-blockstats (Command)
198 • BlockdevOnError (Enum)
200 • MirrorSyncMode (Enum)
202 • BitmapSyncMode (Enum)
204 • MirrorCopyMode (Enum)
206 • BlockJobInfo (Object)
208 • query-block-jobs (Command)
210 • block_resize (Command)
212 • NewImageMode (Enum)
214 • BlockdevSnapshotSync (Object)
216 • BlockdevSnapshot (Object)
218 • BackupPerf (Object)
220 • BackupCommon (Object)
222 • DriveBackup (Object)
224 • BlockdevBackup (Object)
226 • blockdev-snapshot-sync (Command)
228 • blockdev-snapshot (Command)
230 • change-backing-file (Command)
232 • block-commit (Command)
234 • drive-backup (Command)
236 • blockdev-backup (Command)
238 • query-named-block-nodes (Command)
240 • XDbgBlockGraphNodeType (Enum)
242 • XDbgBlockGraphNode (Object)
244 • BlockPermission (Enum)
246 • XDbgBlockGraphEdge (Object)
248 • XDbgBlockGraph (Object)
250 • x-debug-query-block-graph (Command)
252 • drive-mirror (Command)
254 • DriveMirror (Object)
256 • BlockDirtyBitmap (Object)
258 • BlockDirtyBitmapAdd (Object)
260 • BlockDirtyBitmapOrStr (Alternate)
262 • BlockDirtyBitmapMerge (Object)
264 • block-dirty-bitmap-add (Command)
266 • block-dirty-bitmap-remove (Command)
268 • block-dirty-bitmap-clear (Command)
270 • block-dirty-bitmap-enable (Command)
272 • block-dirty-bitmap-disable (Command)
274 • block-dirty-bitmap-merge (Command)
276 • BlockDirtyBitmapSha256 (Object)
278 • x-debug-block-dirty-bitmap-sha256 (Command)
280 • blockdev-mirror (Command)
282 • BlockIOThrottle (Object)
284 • ThrottleLimits (Object)
286 • ThrottleGroupProperties (Object)
288 • block-stream (Command)
290 • block-job-set-speed (Command)
292 • block-job-cancel (Command)
294 • block-job-pause (Command)
296 • block-job-resume (Command)
298 • block-job-complete (Command)
300 • block-job-dismiss (Command)
302 • block-job-finalize (Command)
304 • BlockdevDiscardOptions (Enum)
306 • BlockdevDetectZeroesOptions (Enum)
308 • BlockdevAioOptions (Enum)
310 • BlockdevCacheOptions (Object)
312 • BlockdevDriver (Enum)
314 • BlockdevOptionsFile (Object)
316 • BlockdevOptionsNull (Object)
318 • BlockdevOptionsNVMe (Object)
320 • BlockdevOptionsVVFAT (Object)
322 • BlockdevOptionsGenericFormat (Object)
324 • BlockdevOptionsLUKS (Object)
326 • BlockdevOptionsGenericCOWFormat (Object)
328 • Qcow2OverlapCheckMode (Enum)
330 • Qcow2OverlapCheckFlags (Object)
332 • Qcow2OverlapChecks (Alternate)
334 • BlockdevQcowEncryptionFormat (Enum)
336 • BlockdevQcowEncryption (Object)
338 • BlockdevOptionsQcow (Object)
340 • BlockdevQcow2EncryptionFormat (Enum)
342 • BlockdevQcow2Encryption (Object)
344 • BlockdevOptionsPreallocate (Object)
346 • BlockdevOptionsQcow2 (Object)
348 • SshHostKeyCheckMode (Enum)
350 • SshHostKeyCheckHashType (Enum)
352 • SshHostKeyHash (Object)
354 • SshHostKeyCheck (Object)
356 • BlockdevOptionsSsh (Object)
358 • BlkdebugEvent (Enum)
360 • BlkdebugIOType (Enum)
362 • BlkdebugInjectErrorOptions (Object)
364 • BlkdebugSetStateOptions (Object)
366 • BlockdevOptionsBlkdebug (Object)
368 • BlockdevOptionsBlklogwrites (Object)
370 • BlockdevOptionsBlkverify (Object)
372 • BlockdevOptionsBlkreplay (Object)
374 • QuorumReadPattern (Enum)
376 • BlockdevOptionsQuorum (Object)
378 • BlockdevOptionsGluster (Object)
380 • BlockdevOptionsIoUring (Object)
382 • BlockdevOptionsNvmeIoUring (Object)
384 • BlockdevOptionsVirtioBlkVfioPci (Object)
386 • BlockdevOptionsVirtioBlkVhostUser (Object)
388 • BlockdevOptionsVirtioBlkVhostVdpa (Object)
390 • IscsiTransport (Enum)
392 • IscsiHeaderDigest (Enum)
394 • BlockdevOptionsIscsi (Object)
396 • RbdAuthMode (Enum)
398 • RbdImageEncryptionFormat (Enum)
400 • RbdEncryptionOptionsLUKSBase (Object)
402 • RbdEncryptionCreateOptionsLUKSBase (Object)
404 • RbdEncryptionOptionsLUKS (Object)
406 • RbdEncryptionOptionsLUKS2 (Object)
408 • RbdEncryptionCreateOptionsLUKS (Object)
410 • RbdEncryptionCreateOptionsLUKS2 (Object)
412 • RbdEncryptionOptions (Object)
414 • RbdEncryptionCreateOptions (Object)
416 • BlockdevOptionsRbd (Object)
418 • ReplicationMode (Enum)
420 • BlockdevOptionsReplication (Object)
422 • NFSTransport (Enum)
424 • NFSServer (Object)
426 • BlockdevOptionsNfs (Object)
428 • BlockdevOptionsCurlBase (Object)
430 • BlockdevOptionsCurlHttp (Object)
432 • BlockdevOptionsCurlHttps (Object)
434 • BlockdevOptionsCurlFtp (Object)
436 • BlockdevOptionsCurlFtps (Object)
438 • BlockdevOptionsNbd (Object)
440 • BlockdevOptionsRaw (Object)
442 • BlockdevOptionsThrottle (Object)
444 • BlockdevOptionsCor (Object)
446 • OnCbwError (Enum)
448 • BlockdevOptionsCbw (Object)
450 • BlockdevOptions (Object)
452 • BlockdevRef (Alternate)
454 • BlockdevRefOrNull (Alternate)
456 • blockdev-add (Command)
458 • blockdev-reopen (Command)
460 • blockdev-del (Command)
462 • BlockdevCreateOptionsFile (Object)
464 • BlockdevCreateOptionsGluster (Object)
466 • BlockdevCreateOptionsLUKS (Object)
468 • BlockdevCreateOptionsNfs (Object)
470 • BlockdevCreateOptionsParallels (Object)
472 • BlockdevCreateOptionsQcow (Object)
474 • BlockdevQcow2Version (Enum)
476 • Qcow2CompressionType (Enum)
478 • BlockdevCreateOptionsQcow2 (Object)
480 • BlockdevCreateOptionsQed (Object)
482 • BlockdevCreateOptionsRbd (Object)
484 • BlockdevVmdkSubformat (Enum)
486 • BlockdevVmdkAdapterType (Enum)
488 • BlockdevCreateOptionsVmdk (Object)
490 • BlockdevCreateOptionsSsh (Object)
492 • BlockdevCreateOptionsVdi (Object)
494 • BlockdevVhdxSubformat (Enum)
496 • BlockdevCreateOptionsVhdx (Object)
498 • BlockdevVpcSubformat (Enum)
500 • BlockdevCreateOptionsVpc (Object)
502 • BlockdevCreateOptions (Object)
504 • blockdev-create (Command)
506 • BlockdevAmendOptionsLUKS (Object)
508 • BlockdevAmendOptionsQcow2 (Object)
510 • BlockdevAmendOptions (Object)
512 • x-blockdev-amend (Command)
514 • BlockErrorAction (Enum)
516 • BLOCK_IMAGE_CORRUPTED (Event)
518 • BLOCK_IO_ERROR (Event)
520 • BLOCK_JOB_COMPLETED (Event)
522 • BLOCK_JOB_CANCELLED (Event)
524 • BLOCK_JOB_ERROR (Event)
526 • BLOCK_JOB_READY (Event)
528 • BLOCK_JOB_PENDING (Event)
530 • PreallocMode (Enum)
532 • BLOCK_WRITE_THRESHOLD (Event)
534 • block-set-write-threshold (Command)
536 • x-blockdev-change (Command)
538 • x-blockdev-set-iothread (Command)
540 • QuorumOpType (Enum)
542 • QUORUM_FAILURE (Event)
544 • QUORUM_REPORT_BAD (Event)
546 • BlockdevSnapshotInternal (Object)
548 • blockdev-snapshot-internal-sync (Command)
550 • blockdev-snapshot-delete-internal-sync (Command)
552 • Block device exports
554 • Character devices
556 • ChardevInfo (Object)
558 • query-chardev (Command)
560 • ChardevBackendInfo (Object)
562 • query-chardev-backends (Command)
564 • DataFormat (Enum)
566 • ringbuf-write (Command)
568 • ringbuf-read (Command)
570 • ChardevCommon (Object)
572 • ChardevFile (Object)
574 • ChardevHostdev (Object)
576 • ChardevSocket (Object)
578 • ChardevUdp (Object)
580 • ChardevMux (Object)
582 • ChardevStdio (Object)
584 • ChardevSpiceChannel (Object)
586 • ChardevSpicePort (Object)
588 • ChardevDBus (Object)
590 • ChardevVC (Object)
592 • ChardevRingbuf (Object)
594 • ChardevQemuVDAgent (Object)
596 • ChardevBackendKind (Enum)
598 • ChardevFileWrapper (Object)
600 • ChardevHostdevWrapper (Object)
602 • ChardevSocketWrapper (Object)
604 • ChardevUdpWrapper (Object)
606 • ChardevCommonWrapper (Object)
608 • ChardevMuxWrapper (Object)
610 • ChardevStdioWrapper (Object)
612 • ChardevSpiceChannelWrapper (Object)
614 • ChardevSpicePortWrapper (Object)
616 • ChardevQemuVDAgentWrapper (Object)
618 • ChardevDBusWrapper (Object)
620 • ChardevVCWrapper (Object)
622 • ChardevRingbufWrapper (Object)
624 • ChardevBackend (Object)
626 • ChardevReturn (Object)
628 • chardev-add (Command)
630 • chardev-change (Command)
632 • chardev-remove (Command)
634 • chardev-send-break (Command)
636 • VSERPORT_CHANGE (Event)
638 • QMP monitor control
640 • qmp_capabilities (Command)
642 • QMPCapability (Enum)
644 • VersionTriple (Object)
646 • VersionInfo (Object)
648 • query-version (Command)
650 • CommandInfo (Object)
652 • query-commands (Command)
654 • quit (Command)
656 • MonitorMode (Enum)
658 • MonitorOptions (Object)
660 • QMP introspection
662 • query-qmp-schema (Command)
664 • SchemaMetaType (Enum)
666 • SchemaInfo (Object)
668 • SchemaInfoBuiltin (Object)
670 • JSONType (Enum)
672 • SchemaInfoEnum (Object)
674 • SchemaInfoEnumMember (Object)
676 • SchemaInfoArray (Object)
678 • SchemaInfoObject (Object)
680 • SchemaInfoObjectMember (Object)
682 • SchemaInfoObjectVariant (Object)
684 • SchemaInfoAlternate (Object)
686 • SchemaInfoAlternateMember (Object)
688 • SchemaInfoCommand (Object)
690 • SchemaInfoEvent (Object)
692 • User authorization
694 • QAuthZListPolicy (Enum)
696 • QAuthZListFormat (Enum)
698 • QAuthZListRule (Object)
700 • AuthZListProperties (Object)
702 • AuthZListFileProperties (Object)
704 • AuthZPAMProperties (Object)
706 • AuthZSimpleProperties (Object)
708 • QEMU Object Model (QOM)
710 • ObjectPropertyInfo (Object)
712 • qom-list (Command)
714 • qom-get (Command)
716 • qom-set (Command)
718 • ObjectTypeInfo (Object)
720 • qom-list-types (Command)
722 • qom-list-properties (Command)
724 • CanHostSocketcanProperties (Object)
726 • ColoCompareProperties (Object)
728 • CryptodevBackendProperties (Object)
730 • CryptodevVhostUserProperties (Object)
732 • DBusVMStateProperties (Object)
734 • NetfilterInsert (Enum)
736 • NetfilterProperties (Object)
738 • FilterBufferProperties (Object)
740 • FilterDumpProperties (Object)
742 • FilterMirrorProperties (Object)
744 • FilterRedirectorProperties (Object)
746 • FilterRewriterProperties (Object)
748 • InputBarrierProperties (Object)
750 • InputLinuxProperties (Object)
752 • EventLoopBaseProperties (Object)
754 • IothreadProperties (Object)
756 • MainLoopProperties (Object)
758 • MemoryBackendProperties (Object)
760 • MemoryBackendFileProperties (Object)
762 • MemoryBackendMemfdProperties (Object)
764 • MemoryBackendEpcProperties (Object)
766 • PrManagerHelperProperties (Object)
768 • QtestProperties (Object)
770 • RemoteObjectProperties (Object)
772 • VfioUserServerProperties (Object)
774 • RngProperties (Object)
776 • RngEgdProperties (Object)
778 • RngRandomProperties (Object)
780 • SevGuestProperties (Object)
782 • ThreadContextProperties (Object)
784 • ObjectType (Enum)
786 • ObjectOptions (Object)
788 • object-add (Command)
790 • object-del (Command)
792 • Transactions
794 • Abort (Object)
796 • ActionCompletionMode (Enum)
798 • TransactionActionKind (Enum)
800 • AbortWrapper (Object)
802 • BlockDirtyBitmapAddWrapper (Object)
804 • BlockDirtyBitmapWrapper (Object)
806 • BlockDirtyBitmapMergeWrapper (Object)
808 • BlockdevBackupWrapper (Object)
810 • BlockdevSnapshotWrapper (Object)
812 • BlockdevSnapshotInternalWrapper (Object)
814 • BlockdevSnapshotSyncWrapper (Object)
816 • DriveBackupWrapper (Object)
818 • TransactionAction (Object)
820 • TransactionProperties (Object)
822 • transaction (Command)
824
826 Block core (VM unrelated)
828 IoOperationType (Enum)
829 An enumeration of the I/O operation types
830 Values
832 read read operation
833 write write operation
835 Since
837 2.1
838 OnOffAuto (Enum)
840 An enumeration of three options: on, off, and auto
841 Values
843 auto QEMU selects the value between on and off
844 on Enabled
846 off Disabled
848 Since
850 2.2
851 OnOffSplit (Enum)
853 An enumeration of three values: on, off, and split
854 Values
856 on Enabled
857 off Disabled
859 split Mixed
861 Since
863 2.6
864 String (Object)
866 A fat type wrapping 'str', to be embedded in lists.
867 Members
869 str: string
870 Not documented
871 Since
873 1.2
874 StrOrNull (Alternate)
876 This is a string value or the explicit lack of a string (null pointer
877 in C). Intended for cases when 'optional absent' already has a differ‐
878 ent meaning.
879 Members
881 s: string
882 the string value
883 n: null
885 no string value
886 Since
888 2.10
889 OffAutoPCIBAR (Enum)
891 An enumeration of options for specifying a PCI BAR
892 Values
894 off The specified feature is disabled
895 auto The PCI BAR for the feature is automatically selected
897 bar0 PCI BAR0 is used for the feature
899 bar1 PCI BAR1 is used for the feature
901 bar2 PCI BAR2 is used for the feature
903 bar3 PCI BAR3 is used for the feature
905 bar4 PCI BAR4 is used for the feature
907 bar5 PCI BAR5 is used for the feature
909 Since
911 2.12
912 PCIELinkSpeed (Enum)
914 An enumeration of PCIe link speeds in units of GT/s
915 Values
917 2_5 2.5GT/s
918 5 5.0GT/s
920 8 8.0GT/s
922 16 16.0GT/s
924 Since
926 4.0
927 PCIELinkWidth (Enum)
929 An enumeration of PCIe link width
930 Values
932 1 x1
933 2 x2
935 4 x4
937 8 x8
939 12 x12
941 16 x16
943 32 x32
945 Since
947 4.0
948 HostMemPolicy (Enum)
950 Host memory policy types
951 Values
953 default
954 restore default policy, remove any nondefault policy
955 preferred
957 set the preferred host nodes for allocation
958 bind a strict policy that restricts memory allocation to the host
960 nodes specified
961 interleave
963 memory allocations are interleaved across the set of host nodes
964 specified
965 Since
967 2.1
968 NetFilterDirection (Enum)
970 Indicates whether a netfilter is attached to a netdev's transmit queue
971 or receive queue or both.
972 Values
974 all the filter is attached both to the receive and the transmit
975 queue of the netdev (default).
976 rx the filter is attached to the receive queue of the netdev, where
978 it will receive packets sent to the netdev.
979 tx the filter is attached to the transmit queue of the netdev,
981 where it will receive packets sent by the netdev.
982 Since
984 2.5
985 GrabToggleKeys (Enum)
987 Keys to toggle input-linux between host and guest.
988 Values
990 ctrl-ctrl
991 Not documented
992 alt-alt
994 Not documented
995 shift-shift
997 Not documented
998 meta-meta
1000 Not documented
1001 scrolllock
1003 Not documented
1004 ctrl-scrolllock
1006 Not documented
1007 Since
1009 4.0
1010 HumanReadableText (Object)
1012 Members
1013 human-readable-text: string
1014 Formatted output intended for humans.
1015 Since
1017 6.2
1018
1020 QCryptoTLSCredsEndpoint (Enum)
1021 The type of network endpoint that will be using the credentials. Most
1022 types of credential require different setup / structures depending on
1023 whether they will be used in a server versus a client.
1024 Values
1026 client the network endpoint is acting as the client
1027 server the network endpoint is acting as the server
1029 Since
1031 2.5
1032 QCryptoSecretFormat (Enum)
1034 The data format that the secret is provided in
1035 Values
1037 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
1038 be used
1039 base64 arbitrary base64 encoded binary data
1041 Since
1043 2.6
1044 QCryptoHashAlgorithm (Enum)
1046 The supported algorithms for computing content digests
1047 Values
1049 md5 MD5. Should not be used in any new code, legacy compat only
1050 sha1 SHA-1. Should not be used in any new code, legacy compat only
1052 sha224 SHA-224. (since 2.7)
1054 sha256 SHA-256. Current recommended strong hash.
1056 sha384 SHA-384. (since 2.7)
1058 sha512 SHA-512. (since 2.7)
1060 ripemd160
1062 RIPEMD-160. (since 2.7)
1063 Since
1065 2.6
1066 QCryptoCipherAlgorithm (Enum)
1068 The supported algorithms for content encryption ciphers
1069 Values
1071 aes-128
1072 AES with 128 bit / 16 byte keys
1073 aes-192
1075 AES with 192 bit / 24 byte keys
1076 aes-256
1078 AES with 256 bit / 32 byte keys
1079 des DES with 56 bit / 8 byte keys. Do not use except in VNC. (since
1081 6.1)
1082 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
1084 cast5-128
1086 Cast5 with 128 bit / 16 byte keys
1087 serpent-128
1089 Serpent with 128 bit / 16 byte keys
1090 serpent-192
1092 Serpent with 192 bit / 24 byte keys
1093 serpent-256
1095 Serpent with 256 bit / 32 byte keys
1096 twofish-128
1098 Twofish with 128 bit / 16 byte keys
1099 twofish-192
1101 Twofish with 192 bit / 24 byte keys
1102 twofish-256
1104 Twofish with 256 bit / 32 byte keys
1105 Since
1107 2.6
1108 QCryptoCipherMode (Enum)
1110 The supported modes for content encryption ciphers
1111 Values
1113 ecb Electronic Code Book
1114 cbc Cipher Block Chaining
1116 xts XEX with tweaked code book and ciphertext stealing
1118 ctr Counter (Since 2.8)
1120 Since
1122 2.6
1123 QCryptoIVGenAlgorithm (Enum)
1125 The supported algorithms for generating initialization vectors for full
1126 disk encryption. The 'plain' generator should not be used for disks
1127 with sector numbers larger than 2^32, except where compatibility with
1128 pre-existing Linux dm-crypt volumes is required.
1129 Values
1131 plain 64-bit sector number truncated to 32-bits
1132 plain64
1134 64-bit sector number
1135 essiv 64-bit sector number encrypted with a hash of the encryption key
1137 Since
1139 2.6
1140 QCryptoBlockFormat (Enum)
1142 The supported full disk encryption formats
1143 Values
1145 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
1146 data from old images.
1147 luks LUKS encryption format. Recommended for new images
1149 Since
1151 2.6
1152 QCryptoBlockOptionsBase (Object)
1154 The common options that apply to all full disk encryption formats
1155 Members
1157 format: QCryptoBlockFormat
1158 the encryption format
1159 Since
1161 2.6
1162 QCryptoBlockOptionsQCow (Object)
1164 The options that apply to QCow/QCow2 AES-CBC encryption format
1165 Members
1167 key-secret: string (optional)
1168 the ID of a QCryptoSecret object providing the decryption key.
1169 Mandatory except when probing image for metadata only.
1170 Since
1172 2.6
1173 QCryptoBlockOptionsLUKS (Object)
1175 The options that apply to LUKS encryption format
1176 Members
1178 key-secret: string (optional)
1179 the ID of a QCryptoSecret object providing the decryption key.
1180 Mandatory except when probing image for metadata only.
1181 Since
1183 2.6
1184 QCryptoBlockCreateOptionsLUKS (Object)
1186 The options that apply to LUKS encryption format initialization
1187 Members
1189 cipher-alg: QCryptoCipherAlgorithm (optional)
1190 the cipher algorithm for data encryption Currently defaults to
1191 'aes-256'.
1192 cipher-mode: QCryptoCipherMode (optional)
1194 the cipher mode for data encryption Currently defaults to 'xts'
1195 ivgen-alg: QCryptoIVGenAlgorithm (optional)
1197 the initialization vector generator Currently defaults to
1198 'plain64'
1199 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1201 the initialization vector generator hash Currently defaults to
1202 'sha256'
1203 hash-alg: QCryptoHashAlgorithm (optional)
1205 the master key hash algorithm Currently defaults to 'sha256'
1206 iter-time: int (optional)
1208 number of milliseconds to spend in PBKDF passphrase processing.
1209 Currently defaults to 2000. (since 2.8)
1210 The members of QCryptoBlockOptionsLUKS
1212 Since
1214 2.6
1215 QCryptoBlockOpenOptions (Object)
1217 The options that are available for all encryption formats when opening
1218 an existing volume
1219 Members
1221 The members of QCryptoBlockOptionsBase
1222 The members of QCryptoBlockOptionsQCow when format is "qcow"
1224 The members of QCryptoBlockOptionsLUKS when format is "luks"
1226 Since
1228 2.6
1229 QCryptoBlockCreateOptions (Object)
1231 The options that are available for all encryption formats when initial‐
1232 izing a new volume
1233 Members
1235 The members of QCryptoBlockOptionsBase
1236 The members of QCryptoBlockOptionsQCow when format is "qcow"
1238 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
1240 Since
1242 2.6
1243 QCryptoBlockInfoBase (Object)
1245 The common information that applies to all full disk encryption formats
1246 Members
1248 format: QCryptoBlockFormat
1249 the encryption format
1250 Since
1252 2.7
1253 QCryptoBlockInfoLUKSSlot (Object)
1255 Information about the LUKS block encryption key slot options
1256 Members
1258 active: boolean
1259 whether the key slot is currently in use
1260 key-offset: int
1262 offset to the key material in bytes
1263 iters: int (optional)
1265 number of PBKDF2 iterations for key material
1266 stripes: int (optional)
1268 number of stripes for splitting key material
1269 Since
1271 2.7
1272 QCryptoBlockInfoLUKS (Object)
1274 Information about the LUKS block encryption options
1275 Members
1277 cipher-alg: QCryptoCipherAlgorithm
1278 the cipher algorithm for data encryption
1279 cipher-mode: QCryptoCipherMode
1281 the cipher mode for data encryption
1282 ivgen-alg: QCryptoIVGenAlgorithm
1284 the initialization vector generator
1285 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1287 the initialization vector generator hash
1288 hash-alg: QCryptoHashAlgorithm
1290 the master key hash algorithm
1291 payload-offset: int
1293 offset to the payload data in bytes
1294 master-key-iters: int
1296 number of PBKDF2 iterations for key material
1297 uuid: string
1299 unique identifier for the volume
1300 slots: array of QCryptoBlockInfoLUKSSlot
1302 information about each key slot
1303 Since
1305 2.7
1306 QCryptoBlockInfo (Object)
1308 Information about the block encryption options
1309 Members
1311 The members of QCryptoBlockInfoBase
1312 The members of QCryptoBlockInfoLUKS when format is "luks"
1314 Since
1316 2.7
1317 QCryptoBlockLUKSKeyslotState (Enum)
1319 Defines state of keyslots that are affected by the update
1320 Values
1322 active The slots contain the given password and marked as active
1323 inactive
1325 The slots are erased (contain garbage) and marked as inactive
1326 Since
1328 5.1
1329 QCryptoBlockAmendOptionsLUKS (Object)
1331 This struct defines the update parameters that activate/de-activate set
1332 of keyslots
1333 Members
1335 state: QCryptoBlockLUKSKeyslotState
1336 the desired state of the keyslots
1337 new-secret: string (optional)
1339 The ID of a QCryptoSecret object providing the password to be
1340 written into added active keyslots
1341 old-secret: string (optional)
1343 Optional (for deactivation only) If given will deactivate all
1344 keyslots that match password located in QCryptoSecret with this
1345 ID
1346 iter-time: int (optional)
1348 Optional (for activation only) Number of milliseconds to spend
1349 in PBKDF passphrase processing for the newly activated keyslot.
1350 Currently defaults to 2000.
1351 keyslot: int (optional)
1353 Optional. ID of the keyslot to activate/deactivate. For keyslot
1354 activation, keyslot should not be active already (this is unsafe
1355 to update an active keyslot), but possible if 'force' parameter
1356 is given. If keyslot is not given, first free keyslot will be
1357 written.
1358 For keyslot deactivation, this parameter specifies the exact
1360 keyslot to deactivate
1361 secret: string (optional)
1363 Optional. The ID of a QCryptoSecret object providing the pass‐
1364 word to use to retrieve current master key. Defaults to the
1365 same secret that was used to open the image
1366 Since
1368 5.1
1369 QCryptoBlockAmendOptions (Object)
1371 The options that are available for all encryption formats when amending
1372 encryption settings
1373 Members
1375 The members of QCryptoBlockOptionsBase
1376 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
1378 Since
1380 5.1
1381 SecretCommonProperties (Object)
1383 Properties for objects of classes derived from secret-common.
1384 Members
1386 loaded: boolean (optional)
1387 if true, the secret is loaded immediately when applying this op‐
1388 tion and will probably fail when processing the next option.
1389 Don't use; only provided for compatibility. (default: false)
1390 format: QCryptoSecretFormat (optional)
1392 the data format that the secret is provided in (default: raw)
1393 keyid: string (optional)
1395 the name of another secret that should be used to decrypt the
1396 provided data. If not present, the data is assumed to be unen‐
1397 crypted.
1398 iv: string (optional)
1400 the random initialization vector used for encryption of this
1401 particular secret. Should be a base64 encrypted string of the
1402 16-byte IV. Mandatory if keyid is given. Ignored if keyid is ab‐
1403 sent.
1404 Features
1406 deprecated
1407 Member loaded is deprecated. Setting true doesn't make sense,
1408 and false is already the default.
1409 Since
1411 2.6
1412 SecretProperties (Object)
1414 Properties for secret objects.
1415 Either data or file must be provided, but not both.
1417 Members
1419 data: string (optional)
1420 the associated with the secret from
1421 file: string (optional)
1423 the filename to load the data associated with the secret from
1424 The members of SecretCommonProperties
1426 Since
1428 2.6
1429 SecretKeyringProperties (Object)
1431 Properties for secret_keyring objects.
1432 Members
1434 serial: int
1435 serial number that identifies a key to get from the kernel
1436 The members of SecretCommonProperties
1438 Since
1440 5.1
1441 TlsCredsProperties (Object)
1443 Properties for objects of classes derived from tls-creds.
1444 Members
1446 verify-peer: boolean (optional)
1447 if true the peer credentials will be verified once the handshake
1448 is completed. This is a no-op for anonymous credentials. (de‐
1449 fault: true)
1450 dir: string (optional)
1452 the path of the directory that contains the credential files
1453 endpoint: QCryptoTLSCredsEndpoint (optional)
1455 whether the QEMU network backend that uses the credentials will
1456 be acting as a client or as a server (default: client)
1457 priority: string (optional)
1459 a gnutls priority string as described at
1460 https://gnutls.org/manual/html_node/Priority-Strings.html
1461 Since
1463 2.5
1464 TlsCredsAnonProperties (Object)
1466 Properties for tls-creds-anon objects.
1467 Members
1469 loaded: boolean (optional)
1470 if true, the credentials are loaded immediately when applying
1471 this option and will ignore options that are processed later.
1472 Don't use; only provided for compatibility. (default: false)
1473 The members of TlsCredsProperties
1475 Features
1477 deprecated
1478 Member loaded is deprecated. Setting true doesn't make sense,
1479 and false is already the default.
1480 Since
1482 2.5
1483 TlsCredsPskProperties (Object)
1485 Properties for tls-creds-psk objects.
1486 Members
1488 loaded: boolean (optional)
1489 if true, the credentials are loaded immediately when applying
1490 this option and will ignore options that are processed later.
1491 Don't use; only provided for compatibility. (default: false)
1492 username: string (optional)
1494 the username which will be sent to the server. For clients
1495 only. If absent, "qemu" is sent and the property will read back
1496 as an empty string.
1497 The members of TlsCredsProperties
1499 Features
1501 deprecated
1502 Member loaded is deprecated. Setting true doesn't make sense,
1503 and false is already the default.
1504 Since
1506 3.0
1507 TlsCredsX509Properties (Object)
1509 Properties for tls-creds-x509 objects.
1510 Members
1512 loaded: boolean (optional)
1513 if true, the credentials are loaded immediately when applying
1514 this option and will ignore options that are processed later.
1515 Don't use; only provided for compatibility. (default: false)
1516 sanity-check: boolean (optional)
1518 if true, perform some sanity checks before using the credentials
1519 (default: true)
1520 passwordid: string (optional)
1522 For the server-key.pem and client-key.pem files which contain
1523 sensitive private keys, it is possible to use an encrypted ver‐
1524 sion by providing the passwordid parameter. This provides the
1525 ID of a previously created secret object containing the password
1526 for decryption.
1527 The members of TlsCredsProperties
1529 Features
1531 deprecated
1532 Member loaded is deprecated. Setting true doesn't make sense,
1533 and false is already the default.
1534 Since
1536 2.5
1537 QCryptoAkCipherAlgorithm (Enum)
1539 The supported algorithms for asymmetric encryption ciphers
1540 Values
1542 rsa RSA algorithm
1543 Since
1545 7.1
1546 QCryptoAkCipherKeyType (Enum)
1548 The type of asymmetric keys.
1549 Values
1551 public Not documented
1552 private
1554 Not documented
1555 Since
1557 7.1
1558 QCryptoRSAPaddingAlgorithm (Enum)
1560 The padding algorithm for RSA.
1561 Values
1563 raw no padding used
1564 pkcs1 pkcs1#v1.5
1566 Since
1568 7.1
1569 QCryptoAkCipherOptionsRSA (Object)
1571 Specific parameters for RSA algorithm.
1572 Members
1574 hash-alg: QCryptoHashAlgorithm
1575 QCryptoHashAlgorithm
1576 padding-alg: QCryptoRSAPaddingAlgorithm
1578 QCryptoRSAPaddingAlgorithm
1579 Since
1581 7.1
1582 QCryptoAkCipherOptions (Object)
1584 The options that are available for all asymmetric key algorithms when
1585 creating a new QCryptoAkCipher.
1586 Members
1588 alg: QCryptoAkCipherAlgorithm
1589 Not documented
1590 The members of QCryptoAkCipherOptionsRSA when alg is "rsa"
1592 Since
1594 7.1
1595 Background jobs
1597 JobType (Enum)
1598 Type of a background job.
1599 Values
1601 commit block commit job type, see "block-commit"
1602 stream block stream job type, see "block-stream"
1604 mirror drive mirror job type, see "drive-mirror"
1606 backup drive backup job type, see "drive-backup"
1608 create image creation job type, see "blockdev-create" (since 3.0)
1610 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
1612 snapshot-load
1614 snapshot load job type, see "snapshot-load" (since 6.0)
1615 snapshot-save
1617 snapshot save job type, see "snapshot-save" (since 6.0)
1618 snapshot-delete
1620 snapshot delete job type, see "snapshot-delete" (since 6.0)
1621 Since
1623 1.7
1624 JobStatus (Enum)
1626 Indicates the present state of a given job in its lifetime.
1627 Values
1629 undefined
1630 Erroneous, default state. Should not ever be visible.
1631 created
1633 The job has been created, but not yet started.
1634 running
1636 The job is currently running.
1637 paused The job is running, but paused. The pause may be requested by
1639 either the QMP user or by internal processes.
1640 ready The job is running, but is ready for the user to signal comple‐
1642 tion. This is used for long-running jobs like mirror that are
1643 designed to run indefinitely.
1644 standby
1646 The job is ready, but paused. This is nearly identical to
1647 paused. The job may return to ready or otherwise be canceled.
1648 waiting
1650 The job is waiting for other jobs in the transaction to converge
1651 to the waiting state. This status will likely not be visible for
1652 the last job in a transaction.
1653 pending
1655 The job has finished its work, but has finalization steps that
1656 it needs to make prior to completing. These changes will require
1657 manual intervention via job-finalize if auto-finalize was set to
1658 false. These pending changes may still fail.
1659 aborting
1661 The job is in the process of being aborted, and will finish with
1662 an error. The job will afterwards report that it is concluded.
1663 This status may not be visible to the management process.
1664 concluded
1666 The job has finished all work. If auto-dismiss was set to false,
1667 the job will remain in the query list until it is dismissed via
1668 job-dismiss.
1669 null The job is in the process of being dismantled. This state should
1671 not ever be visible externally.
1672 Since
1674 2.12
1675 JobVerb (Enum)
1677 Represents command verbs that can be applied to a job.
1678 Values
1680 cancel see job-cancel
1681 pause see job-pause
1683 resume see job-resume
1685 set-speed
1687 see block-job-set-speed
1688 complete
1690 see job-complete
1691 dismiss
1693 see job-dismiss
1694 finalize
1696 see job-finalize
1697 Since
1699 2.12
1700 JOB_STATUS_CHANGE (Event)
1702 Emitted when a job transitions to a different status.
1703 Arguments
1705 id: string
1706 The job identifier
1707 status: JobStatus
1709 The new job status
1710 Since
1712 3.0
1713 job-pause (Command)
1715 Pause an active job.
1716 This command returns immediately after marking the active job for paus‐
1718 ing. Pausing an already paused job is an error.
1719 The job will pause as soon as possible, which means transitioning into
1721 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
1722 The corresponding JOB_STATUS_CHANGE event will be emitted.
1723 Cancelling a paused job automatically resumes it.
1725 Arguments
1727 id: string
1728 The job identifier.
1729 Since
1731 3.0
1732 job-resume (Command)
1734 Resume a paused job.
1735 This command returns immediately after resuming a paused job. Resuming
1737 an already running job is an error.
1738 id : The job identifier.
1740 Arguments
1742 id: string
1743 Not documented
1744 Since
1746 3.0
1747 job-cancel (Command)
1749 Instruct an active background job to cancel at the next opportunity.
1750 This command returns immediately after marking the active job for can‐
1751 cellation.
1752 The job will cancel as soon as possible and then emit a JOB_STA‐
1754 TUS_CHANGE event. Usually, the status will change to ABORTING, but it
1755 is possible that a job successfully completes (e.g. because it was al‐
1756 most done and there was no opportunity to cancel earlier than complet‐
1757 ing the job) and transitions to PENDING instead.
1758 Arguments
1760 id: string
1761 The job identifier.
1762 Since
1764 3.0
1765 job-complete (Command)
1767 Manually trigger completion of an active job in the READY state.
1768 Arguments
1770 id: string
1771 The job identifier.
1772 Since
1774 3.0
1775 job-dismiss (Command)
1777 Deletes a job that is in the CONCLUDED state. This command only needs
1778 to be run explicitly for jobs that don't have automatic dismiss en‐
1779 abled.
1780 This command will refuse to operate on any job that has not yet reached
1782 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
1783 JOB_READY event, job-cancel or job-complete will still need to be used
1784 as appropriate.
1785 Arguments
1787 id: string
1788 The job identifier.
1789 Since
1791 3.0
1792 job-finalize (Command)
1794 Instructs all jobs in a transaction (or a single job if it is not part
1795 of any transaction) to finalize any graph changes and do any necessary
1796 cleanup. This command requires that all involved jobs are in the PEND‐
1797 ING state.
1798 For jobs in a transaction, instructing one job to finalize will force
1800 ALL jobs in the transaction to finalize, so it is only necessary to in‐
1801 struct a single member job to finalize.
1802 Arguments
1804 id: string
1805 The identifier of any job in the transaction, or of a job that
1806 is not part of any transaction.
1807 Since
1809 3.0
1810 JobInfo (Object)
1812 Information about a job.
1813 Members
1815 id: string
1816 The job identifier
1817 type: JobType
1819 The kind of job that is being performed
1820 status: JobStatus
1822 Current job state/status
1823 current-progress: int
1825 Progress made until now. The unit is arbitrary and the value can
1826 only meaningfully be used for the ratio of current-progress to
1827 total-progress. The value is monotonically increasing.
1828 total-progress: int
1830 Estimated current-progress value at the completion of the job.
1831 This value can arbitrarily change while the job is running, in
1832 both directions.
1833 error: string (optional)
1835 If this field is present, the job failed; if it is still missing
1836 in the CONCLUDED state, this indicates successful completion.
1837 The value is a human-readable error message to describe the rea‐
1839 son for the job failure. It should not be parsed by applica‐
1840 tions.
1841 Since
1843 3.0
1844 query-jobs (Command)
1846 Return information about jobs.
1847 Returns
1849 a list with a JobInfo for each active job
1850 Since
1852 3.0
1853
1855 NetworkAddressFamily (Enum)
1856 The network address family
1857 Values
1859 ipv4 IPV4 family
1860 ipv6 IPV6 family
1862 unix unix socket
1864 vsock vsock family (since 2.8)
1866 unknown
1868 otherwise
1869 Since
1871 2.1
1872 InetSocketAddressBase (Object)
1874 Members
1875 host: string
1876 host part of the address
1877 port: string
1879 port part of the address
1880 InetSocketAddress (Object)
1882 Captures a socket address or address range in the Internet namespace.
1883 Members
1885 numeric: boolean (optional)
1886 true if the host/port are guaranteed to be numeric, false if
1887 name resolution should be attempted. Defaults to false. (Since
1888 2.9)
1889 to: int (optional)
1891 If present, this is range of possible addresses, with port be‐
1892 tween port and to.
1893 ipv4: boolean (optional)
1895 whether to accept IPv4 addresses, default try both IPv4 and IPv6
1896 ipv6: boolean (optional)
1898 whether to accept IPv6 addresses, default try both IPv4 and IPv6
1899 keep-alive: boolean (optional)
1901 enable keep-alive when connecting to this socket. Not supported
1902 for passive sockets. (Since 4.2)
1903 mptcp: boolean (optional) (If: HAVE_IPPROTO_MPTCP)
1905 enable multi-path TCP. (Since 6.1)
1906 The members of InetSocketAddressBase
1908 Since
1910 1.3
1911 UnixSocketAddress (Object)
1913 Captures a socket address in the local ("Unix socket") namespace.
1914 Members
1916 path: string
1917 filesystem path to use
1918 abstract: boolean (optional) (If: CONFIG_LINUX)
1920 if true, this is a Linux abstract socket address. path will be
1921 prefixed by a null byte, and optionally padded with null bytes.
1922 Defaults to false. (Since 5.1)
1923 tight: boolean (optional) (If: CONFIG_LINUX)
1925 if false, pad an abstract socket address with enough null bytes
1926 to make it fill struct sockaddr_un member sun_path. Defaults to
1927 true. (Since 5.1)
1928 Since
1930 1.3
1931 VsockSocketAddress (Object)
1933 Captures a socket address in the vsock namespace.
1934 Members
1936 cid: string
1937 unique host identifier
1938 port: string
1940 port
1941 Note
1943 string types are used to allow for possible future hostname or service
1944 resolution support.
1945 Since
1947 2.8
1948 InetSocketAddressWrapper (Object)
1950 Members
1951 data: InetSocketAddress
1952 Not documented
1953 Since
1955 1.3
1956 UnixSocketAddressWrapper (Object)
1958 Members
1959 data: UnixSocketAddress
1960 Not documented
1961 Since
1963 1.3
1964 VsockSocketAddressWrapper (Object)
1966 Members
1967 data: VsockSocketAddress
1968 Not documented
1969 Since
1971 2.8
1972 StringWrapper (Object)
1974 Members
1975 data: String
1976 Not documented
1977 Since
1979 1.3
1980 SocketAddressLegacy (Object)
1982 Captures the address of a socket, which could also be a named file de‐
1983 scriptor
1984 Members
1986 type: SocketAddressType
1987 Not documented
1988 The members of InetSocketAddressWrapper when type is "inet"
1990 The members of UnixSocketAddressWrapper when type is "unix"
1992 The members of VsockSocketAddressWrapper when type is "vsock"
1994 The members of StringWrapper when type is "fd"
1996 Note
1998 This type is deprecated in favor of SocketAddress. The difference be‐
1999 tween SocketAddressLegacy and SocketAddress is that the latter has
2000 fewer {} on the wire.
2001 Since
2003 1.3
2004 SocketAddressType (Enum)
2006 Available SocketAddress types
2007 Values
2009 inet Internet address
2010 unix Unix domain socket
2012 vsock VMCI address
2014 fd decimal is for file descriptor number, otherwise a file descrip‐
2016 tor name. Named file descriptors are permitted in monitor com‐
2017 mands, in combination with the 'getfd' command. Decimal file de‐
2018 scriptors are permitted at startup or other contexts where no
2019 monitor context is active.
2020 Since
2022 2.9
2023 SocketAddress (Object)
2025 Captures the address of a socket, which could also be a named file de‐
2026 scriptor
2027 Members
2029 type: SocketAddressType
2030 Transport type
2031 The members of InetSocketAddress when type is "inet"
2033 The members of UnixSocketAddress when type is "unix"
2035 The members of VsockSocketAddress when type is "vsock"
2037 The members of String when type is "fd"
2039 Since
2041 2.9
2042 SnapshotInfo (Object)
2044 Members
2045 id: string
2046 unique snapshot id
2047 name: string
2049 user chosen name
2050 vm-state-size: int
2052 size of the VM state
2053 date-sec: int
2055 UTC date of the snapshot in seconds
2056 date-nsec: int
2058 fractional part in nano seconds to be used with date-sec
2059 vm-clock-sec: int
2061 VM clock relative to boot in seconds
2062 vm-clock-nsec: int
2064 fractional part in nano seconds to be used with vm-clock-sec
2065 icount: int (optional)
2067 Current instruction count. Appears when execution record/replay
2068 is enabled. Used for "time-traveling" to match the moment in the
2069 recorded execution with the snapshots. This counter may be ob‐
2070 tained through query-replay command (since 5.2)
2071 Since
2073 1.3
2074 ImageInfoSpecificQCow2EncryptionBase (Object)
2076 Members
2077 format: BlockdevQcow2EncryptionFormat
2078 The encryption format
2079 Since
2081 2.10
2082 ImageInfoSpecificQCow2Encryption (Object)
2084 Members
2085 The members of ImageInfoSpecificQCow2EncryptionBase
2086 The members of QCryptoBlockInfoLUKS when format is "luks"
2088 Since
2090 2.10
2091 ImageInfoSpecificQCow2 (Object)
2093 Members
2094 compat: string
2095 compatibility level
2096 data-file: string (optional)
2098 the filename of the external data file that is stored in the im‐
2099 age and used as a default for opening the image (since: 4.0)
2100 data-file-raw: boolean (optional)
2102 True if the external data file must stay valid as a standalone
2103 (read-only) raw image without looking at qcow2 metadata (since:
2104 4.0)
2105 extended-l2: boolean (optional)
2107 true if the image has extended L2 entries; only valid for compat
2108 >= 1.1 (since 5.2)
2109 lazy-refcounts: boolean (optional)
2111 on or off; only valid for compat >= 1.1
2112 corrupt: boolean (optional)
2114 true if the image has been marked corrupt; only valid for compat
2115 >= 1.1 (since 2.2)
2116 refcount-bits: int
2118 width of a refcount entry in bits (since 2.3)
2119 encrypt: ImageInfoSpecificQCow2Encryption (optional)
2121 details about encryption parameters; only set if image is en‐
2122 crypted (since 2.10)
2123 bitmaps: array of Qcow2BitmapInfo (optional)
2125 A list of qcow2 bitmap details (since 4.0)
2126 compression-type: Qcow2CompressionType
2128 the image cluster compression method (since 5.1)
2129 Since
2131 1.7
2132 ImageInfoSpecificVmdk (Object)
2134 Members
2135 create-type: string
2136 The create type of VMDK image
2137 cid: int
2139 Content id of image
2140 parent-cid: int
2142 Parent VMDK image's cid
2143 extents: array of ImageInfo
2145 List of extent files
2146 Since
2148 1.7
2149 ImageInfoSpecificRbd (Object)
2151 Members
2152 encryption-format: RbdImageEncryptionFormat (optional)
2153 Image encryption format
2154 Since
2156 6.1
2157 ImageInfoSpecificKind (Enum)
2159 Values
2160 luks Since 2.7
2161 rbd Since 6.1
2163 qcow2 Not documented
2165 vmdk Not documented
2167 Since
2169 1.7
2170 ImageInfoSpecificQCow2Wrapper (Object)
2172 Members
2173 data: ImageInfoSpecificQCow2
2174 Not documented
2175 Since
2177 1.7
2178 ImageInfoSpecificVmdkWrapper (Object)
2180 Members
2181 data: ImageInfoSpecificVmdk
2182 Not documented
2183 Since
2185 6.1
2186 ImageInfoSpecificLUKSWrapper (Object)
2188 Members
2189 data: QCryptoBlockInfoLUKS
2190 Not documented
2191 Since
2193 2.7
2194 ImageInfoSpecificRbdWrapper (Object)
2196 Members
2197 data: ImageInfoSpecificRbd
2198 Not documented
2199 Since
2201 6.1
2202 ImageInfoSpecific (Object)
2204 A discriminated record of image format specific information structures.
2205 Members
2207 type: ImageInfoSpecificKind
2208 Not documented
2209 The members of ImageInfoSpecificQCow2Wrapper when type is "qcow2"
2211 The members of ImageInfoSpecificVmdkWrapper when type is "vmdk"
2213 The members of ImageInfoSpecificLUKSWrapper when type is "luks"
2215 The members of ImageInfoSpecificRbdWrapper when type is "rbd"
2217 Since
2219 1.7
2220 ImageInfo (Object)
2222 Information about a QEMU image file
2223 Members
2225 filename: string
2226 name of the image file
2227 format: string
2229 format of the image file
2230 virtual-size: int
2232 maximum capacity in bytes of the image
2233 actual-size: int (optional)
2235 actual size on disk in bytes of the image
2236 dirty-flag: boolean (optional)
2238 true if image is not cleanly closed
2239 cluster-size: int (optional)
2241 size of a cluster in bytes
2242 encrypted: boolean (optional)
2244 true if the image is encrypted
2245 compressed: boolean (optional)
2247 true if the image is compressed (Since 1.7)
2248 backing-filename: string (optional)
2250 name of the backing file
2251 full-backing-filename: string (optional)
2253 full path of the backing file
2254 backing-filename-format: string (optional)
2256 the format of the backing file
2257 snapshots: array of SnapshotInfo (optional)
2259 list of VM snapshots
2260 backing-image: ImageInfo (optional)
2262 info of the backing image (since 1.6)
2263 format-specific: ImageInfoSpecific (optional)
2265 structure supplying additional format-specific information
2266 (since 1.7)
2267 Since
2269 1.3
2270 ImageCheck (Object)
2272 Information about a QEMU image file check
2273 Members
2275 filename: string
2276 name of the image file checked
2277 format: string
2279 format of the image file checked
2280 check-errors: int
2282 number of unexpected errors occurred during check
2283 image-end-offset: int (optional)
2285 offset (in bytes) where the image ends, this field is present if
2286 the driver for the image format supports it
2287 corruptions: int (optional)
2289 number of corruptions found during the check if any
2290 leaks: int (optional)
2292 number of leaks found during the check if any
2293 corruptions-fixed: int (optional)
2295 number of corruptions fixed during the check if any
2296 leaks-fixed: int (optional)
2298 number of leaks fixed during the check if any
2299 total-clusters: int (optional)
2301 total number of clusters, this field is present if the driver
2302 for the image format supports it
2303 allocated-clusters: int (optional)
2305 total number of allocated clusters, this field is present if the
2306 driver for the image format supports it
2307 fragmented-clusters: int (optional)
2309 total number of fragmented clusters, this field is present if
2310 the driver for the image format supports it
2311 compressed-clusters: int (optional)
2313 total number of compressed clusters, this field is present if
2314 the driver for the image format supports it
2315 Since
2317 1.4
2318 MapEntry (Object)
2320 Mapping information from a virtual block range to a host file range
2321 Members
2323 start: int
2324 virtual (guest) offset of the first byte described by this entry
2325 length: int
2327 the number of bytes of the mapped virtual range
2328 data: boolean
2330 reading the image will actually read data from a file (in par‐
2331 ticular, if offset is present this means that the sectors are
2332 not simply preallocated, but contain actual data in raw format)
2333 zero: boolean
2335 whether the virtual blocks read as zeroes
2336 depth: int
2338 number of layers (0 = top image, 1 = top image's backing file,
2339 ..., n - 1 = bottom image (where n is the number of images in
2340 the chain)) before reaching one for which the range is allocated
2341 present: boolean
2343 true if this layer provides the data, false if adding a backing
2344 layer could impact this region (since 6.1)
2345 offset: int (optional)
2347 if present, the image file stores the data for this range in raw
2348 format at the given (host) offset
2349 filename: string (optional)
2351 filename that is referred to by offset
2352 Since
2354 2.6
2355 BlockdevCacheInfo (Object)
2357 Cache mode information for a block device
2358 Members
2360 writeback: boolean
2361 true if writeback mode is enabled
2362 direct: boolean
2364 true if the host page cache is bypassed (O_DIRECT)
2365 no-flush: boolean
2367 true if flush requests are ignored for the device
2368 Since
2370 2.3
2371 BlockDeviceInfo (Object)
2373 Information about the backing device for a block device.
2374 Members
2376 file: string
2377 the filename of the backing device
2378 node-name: string (optional)
2380 the name of the block driver node (Since 2.0)
2381 ro: boolean
2383 true if the backing device was open read-only
2384 drv: string
2386 the name of the block format used to open the backing device. As
2387 of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
2388 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
2389 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2',
2390 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added,
2391 'cow' dropped 2.3: 'host_floppy' deprecated 2.5: 'host_floppy'
2392 dropped 2.6: 'luks' added 2.8: 'replication' added, 'tftp'
2393 dropped 2.9: 'archipelago' dropped
2394 backing_file: string (optional)
2396 the name of the backing file (for copy-on-write)
2397 backing_file_depth: int
2399 number of files in the backing file chain (since: 1.2)
2400 encrypted: boolean
2402 true if the backing device is encrypted
2403 detect_zeroes: BlockdevDetectZeroesOptions
2405 detect and optimize zero writes (Since 2.1)
2406 bps: int
2408 total throughput limit in bytes per second is specified
2409 bps_rd: int
2411 read throughput limit in bytes per second is specified
2412 bps_wr: int
2414 write throughput limit in bytes per second is specified
2415 iops: int
2417 total I/O operations per second is specified
2418 iops_rd: int
2420 read I/O operations per second is specified
2421 iops_wr: int
2423 write I/O operations per second is specified
2424 image: ImageInfo
2426 the info of image used (since: 1.6)
2427 bps_max: int (optional)
2429 total throughput limit during bursts,
2431 in bytes (Since 1.7)
2432 bps_rd_max: int (optional)
2434 read throughput limit during bursts,
2436 in bytes (Since 1.7)
2437 bps_wr_max: int (optional)
2439 write throughput limit during bursts,
2441 in bytes (Since 1.7)
2442 iops_max: int (optional)
2444 total I/O operations per second during bursts,
2446 in bytes (Since 1.7)
2447 iops_rd_max: int (optional)
2449 read I/O operations per second during bursts,
2451 in bytes (Since 1.7)
2452 iops_wr_max: int (optional)
2454 write I/O operations per second during bursts,
2456 in bytes (Since 1.7)
2457 bps_max_length: int (optional)
2459 maximum length of the bps_max burst
2461 period, in seconds. (Since 2.6)
2462 bps_rd_max_length: int (optional)
2464 maximum length of the bps_rd_max
2466 burst period, in seconds. (Since 2.6)
2467 bps_wr_max_length: int (optional)
2469 maximum length of the bps_wr_max
2471 burst period, in seconds. (Since 2.6)
2472 iops_max_length: int (optional)
2474 maximum length of the iops burst
2476 period, in seconds. (Since 2.6)
2477 iops_rd_max_length: int (optional)
2479 maximum length of the iops_rd_max
2481 burst period, in seconds. (Since 2.6)
2482 iops_wr_max_length: int (optional)
2484 maximum length of the iops_wr_max
2486 burst period, in seconds. (Since 2.6)
2487 iops_size: int (optional)
2489 an I/O size in bytes (Since 1.7)
2490 group: string (optional)
2492 throttle group name (Since 2.4)
2493 cache: BlockdevCacheInfo
2495 the cache mode used for the block device (since: 2.3)
2496 write_threshold: int
2498 configured write threshold for the device. 0 if disabled.
2499 (Since 2.3)
2500 dirty-bitmaps: array of BlockDirtyInfo (optional)
2502 dirty bitmaps information (only present if node has one or more
2503 dirty bitmaps) (Since 4.2)
2504 Since
2506 0.14
2507 BlockDeviceIoStatus (Enum)
2509 An enumeration of block device I/O status.
2510 Values
2512 ok The last I/O operation has succeeded
2513 failed The last I/O operation has failed
2515 nospace
2517 The last I/O operation has failed due to a no-space condition
2518 Since
2520 1.0
2521 BlockDirtyInfo (Object)
2523 Block dirty bitmap information.
2524 Members
2526 name: string (optional)
2527 the name of the dirty bitmap (Since 2.4)
2528 count: int
2530 number of dirty bytes according to the dirty bitmap
2531 granularity: int
2533 granularity of the dirty bitmap in bytes (since 1.4)
2534 recording: boolean
2536 true if the bitmap is recording new writes from the guest. Re‐
2537 places active and disabled statuses. (since 4.0)
2538 busy: boolean
2540 true if the bitmap is in-use by some operation (NBD or jobs) and
2541 cannot be modified via QMP or used by another operation. Re‐
2542 places locked and frozen statuses. (since 4.0)
2543 persistent: boolean
2545 true if the bitmap was stored on disk, is scheduled to be stored
2546 on disk, or both. (since 4.0)
2547 inconsistent: boolean (optional)
2549 true if this is a persistent bitmap that was improperly stored.
2550 Implies persistent to be true; recording and busy to be false.
2551 This bitmap cannot be used. To remove it, use block-dirty-bit‐
2552 map-remove. (Since 4.0)
2553 Since
2555 1.3
2556 Qcow2BitmapInfoFlags (Enum)
2558 An enumeration of flags that a bitmap can report to the user.
2559 Values
2561 in-use This flag is set by any process actively modifying the qcow2
2562 file, and cleared when the updated bitmap is flushed to the
2563 qcow2 image. The presence of this flag in an offline image
2564 means that the bitmap was not saved correctly after its last us‐
2565 age, and may contain inconsistent data.
2566 auto The bitmap must reflect all changes of the virtual disk by any
2568 application that would write to this qcow2 file.
2569 Since
2571 4.0
2572 Qcow2BitmapInfo (Object)
2574 Qcow2 bitmap information.
2575 Members
2577 name: string
2578 the name of the bitmap
2579 granularity: int
2581 granularity of the bitmap in bytes
2582 flags: array of Qcow2BitmapInfoFlags
2584 flags of the bitmap
2585 Since
2587 4.0
2588 BlockLatencyHistogramInfo (Object)
2590 Block latency histogram.
2591 Members
2593 boundaries: array of int
2594 list of interval boundary values in nanoseconds, all greater
2595 than zero and in ascending order. For example, the list [10,
2596 50, 100] produces the following histogram intervals: [0, 10),
2597 [10, 50), [50, 100), [100, +inf).
2598 bins: array of int
2600 list of io request counts corresponding to histogram intervals.
2601 len(bins) = len(boundaries) + 1 For the example above, bins may
2602 be something like [3, 1, 5, 2], and corresponding histogram
2603 looks like:
2604 5| *
2606 4| *
2607 3| * *
2608 2| * * *
2609 1| * * * *
2610 +------------------
2611 10 50 100
2612 Since
2614 4.0
2615 BlockInfo (Object)
2617 Block device information. This structure describes a virtual device
2618 and the backing device associated with it.
2619 Members
2621 device: string
2622 The device name associated with the virtual device.
2623 qdev: string (optional)
2625 The qdev ID, or if no ID is assigned, the QOM path of the block
2626 device. (since 2.10)
2627 type: string
2629 This field is returned only for compatibility reasons, it should
2630 not be used (always returns 'unknown')
2631 removable: boolean
2633 True if the device supports removable media.
2634 locked: boolean
2636 True if the guest has locked this device from having its media
2637 removed
2638 tray_open: boolean (optional)
2640 True if the device's tray is open (only present if it has a
2641 tray)
2642 io-status: BlockDeviceIoStatus (optional)
2644 BlockDeviceIoStatus. Only present if the device supports it and
2645 the VM is configured to stop on errors (supported device models:
2646 virtio-blk, IDE, SCSI except scsi-generic)
2647 inserted: BlockDeviceInfo (optional)
2649 BlockDeviceInfo describing the device if media is present
2650 Since
2652 0.14
2653 BlockMeasureInfo (Object)
2655 Image file size calculation information. This structure describes the
2656 size requirements for creating a new image file.
2657 The size requirements depend on the new image file format. File size
2659 always equals virtual disk size for the 'raw' format, even for sparse
2660 POSIX files. Compact formats such as 'qcow2' represent unallocated and
2661 zero regions efficiently so file size may be smaller than virtual disk
2662 size.
2663 The values are upper bounds that are guaranteed to fit the new image
2665 file. Subsequent modification, such as internal snapshot or further
2666 bitmap creation, may require additional space and is not covered here.
2667 Members
2669 required: int
2670 Size required for a new image file, in bytes, when copying just
2671 allocated guest-visible contents.
2672 fully-allocated: int
2674 Image file size, in bytes, once data has been written to all
2675 sectors, when copying just guest-visible contents.
2676 bitmaps: int (optional)
2678 Additional size required if all the top-level bitmap metadata in
2679 the source image were to be copied to the destination, present
2680 only when source and destination both support persistent bit‐
2681 maps. (since 5.1)
2682 Since
2684 2.10
2685 query-block (Command)
2687 Get a list of BlockInfo for all virtual block devices.
2688 Returns
2690 a list of BlockInfo describing each virtual block device. Filter nodes
2691 that were created implicitly are skipped over.
2692 Since
2694 0.14
2695 Example
2697 -> { "execute": "query-block" }
2698 <- {
2699 "return":[
2700 {
2701 "io-status": "ok",
2702 "device":"ide0-hd0",
2703 "locked":false,
2704 "removable":false,
2705 "inserted":{
2706 "ro":false,
2707 "drv":"qcow2",
2708 "encrypted":false,
2709 "file":"disks/test.qcow2",
2710 "backing_file_depth":1,
2711 "bps":1000000,
2712 "bps_rd":0,
2713 "bps_wr":0,
2714 "iops":1000000,
2715 "iops_rd":0,
2716 "iops_wr":0,
2717 "bps_max": 8000000,
2718 "bps_rd_max": 0,
2719 "bps_wr_max": 0,
2720 "iops_max": 0,
2721 "iops_rd_max": 0,
2722 "iops_wr_max": 0,
2723 "iops_size": 0,
2724 "detect_zeroes": "on",
2725 "write_threshold": 0,
2726 "image":{
2727 "filename":"disks/test.qcow2",
2728 "format":"qcow2",
2729 "virtual-size":2048000,
2730 "backing_file":"base.qcow2",
2731 "full-backing-filename":"disks/base.qcow2",
2732 "backing-filename-format":"qcow2",
2733 "snapshots":[
2734 {
2735 "id": "1",
2736 "name": "snapshot1",
2737 "vm-state-size": 0,
2738 "date-sec": 10000200,
2739 "date-nsec": 12,
2740 "vm-clock-sec": 206,
2741 "vm-clock-nsec": 30
2742 }
2743 ],
2744 "backing-image":{
2745 "filename":"disks/base.qcow2",
2746 "format":"qcow2",
2747 "virtual-size":2048000
2748 }
2749 }
2750 },
2751 "qdev": "ide_disk",
2752 "type":"unknown"
2753 },
2754 {
2755 "io-status": "ok",
2756 "device":"ide1-cd0",
2757 "locked":false,
2758 "removable":true,
2759 "qdev": "/machine/unattached/device[23]",
2760 "tray_open": false,
2761 "type":"unknown"
2762 },
2763 {
2764 "device":"floppy0",
2765 "locked":false,
2766 "removable":true,
2767 "qdev": "/machine/unattached/device[20]",
2768 "type":"unknown"
2769 },
2770 {
2771 "device":"sd0",
2772 "locked":false,
2773 "removable":true,
2774 "type":"unknown"
2775 }
2776 ]
2777 }
2778 BlockDeviceTimedStats (Object)
2780 Statistics of a block device during a given interval of time.
2781 Members
2783 interval_length: int
2784 Interval used for calculating the statistics, in seconds.
2785 min_rd_latency_ns: int
2787 Minimum latency of read operations in the defined interval, in
2788 nanoseconds.
2789 min_wr_latency_ns: int
2791 Minimum latency of write operations in the defined interval, in
2792 nanoseconds.
2793 min_flush_latency_ns: int
2795 Minimum latency of flush operations in the defined interval, in
2796 nanoseconds.
2797 max_rd_latency_ns: int
2799 Maximum latency of read operations in the defined interval, in
2800 nanoseconds.
2801 max_wr_latency_ns: int
2803 Maximum latency of write operations in the defined interval, in
2804 nanoseconds.
2805 max_flush_latency_ns: int
2807 Maximum latency of flush operations in the defined interval, in
2808 nanoseconds.
2809 avg_rd_latency_ns: int
2811 Average latency of read operations in the defined interval, in
2812 nanoseconds.
2813 avg_wr_latency_ns: int
2815 Average latency of write operations in the defined interval, in
2816 nanoseconds.
2817 avg_flush_latency_ns: int
2819 Average latency of flush operations in the defined interval, in
2820 nanoseconds.
2821 avg_rd_queue_depth: number
2823 Average number of pending read operations in the defined inter‐
2824 val.
2825 avg_wr_queue_depth: number
2827 Average number of pending write operations in the defined inter‐
2828 val.
2829 Since
2831 2.5
2832 BlockDeviceStats (Object)
2834 Statistics of a virtual block device or a block backing device.
2835 Members
2837 rd_bytes: int
2838 The number of bytes read by the device.
2839 wr_bytes: int
2841 The number of bytes written by the device.
2842 unmap_bytes: int
2844 The number of bytes unmapped by the device (Since 4.2)
2845 rd_operations: int
2847 The number of read operations performed by the device.
2848 wr_operations: int
2850 The number of write operations performed by the device.
2851 flush_operations: int
2853 The number of cache flush operations performed by the device
2854 (since 0.15)
2855 unmap_operations: int
2857 The number of unmap operations performed by the device (Since
2858 4.2)
2859 rd_total_time_ns: int
2861 Total time spent on reads in nanoseconds (since 0.15).
2862 wr_total_time_ns: int
2864 Total time spent on writes in nanoseconds (since 0.15).
2865 flush_total_time_ns: int
2867 Total time spent on cache flushes in nanoseconds (since 0.15).
2868 unmap_total_time_ns: int
2870 Total time spent on unmap operations in nanoseconds (Since 4.2)
2871 wr_highest_offset: int
2873 The offset after the greatest byte written to the device. The
2874 intended use of this information is for growable sparse files
2875 (like qcow2) that are used on top of a physical device.
2876 rd_merged: int
2878 Number of read requests that have been merged into another re‐
2879 quest (Since 2.3).
2880 wr_merged: int
2882 Number of write requests that have been merged into another re‐
2883 quest (Since 2.3).
2884 unmap_merged: int
2886 Number of unmap requests that have been merged into another re‐
2887 quest (Since 4.2)
2888 idle_time_ns: int (optional)
2890 Time since the last I/O operation, in nanoseconds. If the field
2891 is absent it means that there haven't been any operations yet
2892 (Since 2.5).
2893 failed_rd_operations: int
2895 The number of failed read operations performed by the device
2896 (Since 2.5)
2897 failed_wr_operations: int
2899 The number of failed write operations performed by the device
2900 (Since 2.5)
2901 failed_flush_operations: int
2903 The number of failed flush operations performed by the device
2904 (Since 2.5)
2905 failed_unmap_operations: int
2907 The number of failed unmap operations performed by the device
2908 (Since 4.2)
2909 invalid_rd_operations: int
2911 The number of invalid read operations
2913 performed by the device (Since 2.5)
2914 invalid_wr_operations: int
2916 The number of invalid write operations performed by the device
2917 (Since 2.5)
2918 invalid_flush_operations: int
2920 The number of invalid flush operations performed by the device
2921 (Since 2.5)
2922 invalid_unmap_operations: int
2924 The number of invalid unmap operations performed by the device
2925 (Since 4.2)
2926 account_invalid: boolean
2928 Whether invalid operations are included in the last access sta‐
2929 tistics (Since 2.5)
2930 account_failed: boolean
2932 Whether failed operations are included in the latency and last
2933 access statistics (Since 2.5)
2934 timed_stats: array of BlockDeviceTimedStats
2936 Statistics specific to the set of previously defined intervals
2937 of time (Since 2.5)
2938 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
2940 BlockLatencyHistogramInfo. (Since 4.0)
2941 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
2943 BlockLatencyHistogramInfo. (Since 4.0)
2944 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
2946 BlockLatencyHistogramInfo. (Since 4.0)
2947 Since
2949 0.14
2950 BlockStatsSpecificFile (Object)
2952 File driver statistics
2953 Members
2955 discard-nb-ok: int
2956 The number of successful discard operations performed by the
2957 driver.
2958 discard-nb-failed: int
2960 The number of failed discard operations performed by the driver.
2961 discard-bytes-ok: int
2963 The number of bytes discarded by the driver.
2964 Since
2966 4.2
2967 BlockStatsSpecificNvme (Object)
2969 NVMe driver statistics
2970 Members
2972 completion-errors: int
2973 The number of completion errors.
2974 aligned-accesses: int
2976 The number of aligned accesses performed by the driver.
2977 unaligned-accesses: int
2979 The number of unaligned accesses performed by the driver.
2980 Since
2982 5.2
2983 BlockStatsSpecific (Object)
2985 Block driver specific statistics
2986 Members
2988 driver: BlockdevDriver
2989 Not documented
2990 The members of BlockStatsSpecificFile when driver is "file"
2992 The members of BlockStatsSpecificFile when driver is "host_device" (If:
2994 HAVE_HOST_BLOCK_DEVICE)
2995 The members of BlockStatsSpecificNvme when driver is "nvme"
2997 Since
2999 4.2
3000 BlockStats (Object)
3002 Statistics of a virtual block device or a block backing device.
3003 Members
3005 device: string (optional)
3006 If the stats are for a virtual block device, the name corre‐
3007 sponding to the virtual block device.
3008 node-name: string (optional)
3010 The node name of the device. (Since 2.3)
3011 qdev: string (optional)
3013 The qdev ID, or if no ID is assigned, the QOM path of the block
3014 device. (since 3.0)
3015 stats: BlockDeviceStats
3017 A BlockDeviceStats for the device.
3018 driver-specific: BlockStatsSpecific (optional)
3020 Optional driver-specific stats. (Since 4.2)
3021 parent: BlockStats (optional)
3023 This describes the file block device if it has one. Contains
3024 recursively the statistics of the underlying protocol (e.g. the
3025 host file for a qcow2 image). If there is no underlying proto‐
3026 col, this field is omitted
3027 backing: BlockStats (optional)
3029 This describes the backing block device if it has one. (Since
3030 2.0)
3031 Since
3033 0.14
3034 query-blockstats (Command)
3036 Query the BlockStats for all virtual block devices.
3037 Arguments
3039 query-nodes: boolean (optional)
3040 If true, the command will query all the block nodes that have a
3041 node name, in a list which will include "parent" information,
3042 but not "backing". If false or omitted, the behavior is as be‐
3043 fore - query all the device backends, recursively including
3044 their "parent" and "backing". Filter nodes that were created im‐
3045 plicitly are skipped over in this mode. (Since 2.3)
3046 Returns
3048 A list of BlockStats for each virtual block devices.
3049 Since
3051 0.14
3052 Example
3054 -> { "execute": "query-blockstats" }
3055 <- {
3056 "return":[
3057 {
3058 "device":"ide0-hd0",
3059 "parent":{
3060 "stats":{
3061 "wr_highest_offset":3686448128,
3062 "wr_bytes":9786368,
3063 "wr_operations":751,
3064 "rd_bytes":122567168,
3065 "rd_operations":36772
3066 "wr_total_times_ns":313253456
3067 "rd_total_times_ns":3465673657
3068 "flush_total_times_ns":49653
3069 "flush_operations":61,
3070 "rd_merged":0,
3071 "wr_merged":0,
3072 "idle_time_ns":2953431879,
3073 "account_invalid":true,
3074 "account_failed":false
3075 }
3076 },
3077 "stats":{
3078 "wr_highest_offset":2821110784,
3079 "wr_bytes":9786368,
3080 "wr_operations":692,
3081 "rd_bytes":122739200,
3082 "rd_operations":36604
3083 "flush_operations":51,
3084 "wr_total_times_ns":313253456
3085 "rd_total_times_ns":3465673657
3086 "flush_total_times_ns":49653,
3087 "rd_merged":0,
3088 "wr_merged":0,
3089 "idle_time_ns":2953431879,
3090 "account_invalid":true,
3091 "account_failed":false
3092 },
3093 "qdev": "/machine/unattached/device[23]"
3094 },
3095 {
3096 "device":"ide1-cd0",
3097 "stats":{
3098 "wr_highest_offset":0,
3099 "wr_bytes":0,
3100 "wr_operations":0,
3101 "rd_bytes":0,
3102 "rd_operations":0
3103 "flush_operations":0,
3104 "wr_total_times_ns":0
3105 "rd_total_times_ns":0
3106 "flush_total_times_ns":0,
3107 "rd_merged":0,
3108 "wr_merged":0,
3109 "account_invalid":false,
3110 "account_failed":false
3111 },
3112 "qdev": "/machine/unattached/device[24]"
3113 },
3114 {
3115 "device":"floppy0",
3116 "stats":{
3117 "wr_highest_offset":0,
3118 "wr_bytes":0,
3119 "wr_operations":0,
3120 "rd_bytes":0,
3121 "rd_operations":0
3122 "flush_operations":0,
3123 "wr_total_times_ns":0
3124 "rd_total_times_ns":0
3125 "flush_total_times_ns":0,
3126 "rd_merged":0,
3127 "wr_merged":0,
3128 "account_invalid":false,
3129 "account_failed":false
3130 },
3131 "qdev": "/machine/unattached/device[16]"
3132 },
3133 {
3134 "device":"sd0",
3135 "stats":{
3136 "wr_highest_offset":0,
3137 "wr_bytes":0,
3138 "wr_operations":0,
3139 "rd_bytes":0,
3140 "rd_operations":0
3141 "flush_operations":0,
3142 "wr_total_times_ns":0
3143 "rd_total_times_ns":0
3144 "flush_total_times_ns":0,
3145 "rd_merged":0,
3146 "wr_merged":0,
3147 "account_invalid":false,
3148 "account_failed":false
3149 }
3150 }
3151 ]
3152 }
3153 BlockdevOnError (Enum)
3155 An enumeration of possible behaviors for errors on I/O operations. The
3156 exact meaning depends on whether the I/O was initiated by a guest or by
3157 a block job
3158 Values
3160 report for guest operations, report the error to the guest; for jobs,
3161 cancel the job
3162 ignore ignore the error, only report a QMP event (BLOCK_IO_ERROR or
3164 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
3165 the failing request later and may still complete successfully.
3166 The stream block job continues to stream and will complete with
3167 an error.
3168 enospc same as stop on ENOSPC, same as report otherwise.
3170 stop for guest operations, stop the virtual machine; for jobs, pause
3172 the job
3173 auto inherit the error handling policy of the backend (since: 2.7)
3175 Since
3177 1.3
3178 MirrorSyncMode (Enum)
3180 An enumeration of possible behaviors for the initial synchronization
3181 phase of storage mirroring.
3182 Values
3184 top copies data in the topmost image to the destination
3185 full copies data from all images to the destination
3187 none only copy data written from now on
3189 incremental
3191 only copy data described by the dirty bitmap. (since: 2.4)
3192 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
3194 havior on completion is determined by the BitmapSyncMode.
3195 Since
3197 1.3
3198 BitmapSyncMode (Enum)
3200 An enumeration of possible behaviors for the synchronization of a bit‐
3201 map when used for data copy operations.
3202 Values
3204 on-success
3205 The bitmap is only synced when the operation is successful.
3206 This is the behavior always used for 'INCREMENTAL' backups.
3207 never The bitmap is never synchronized with the operation, and is
3209 treated solely as a read-only manifest of blocks to copy.
3210 always The bitmap is always synchronized with the operation, regardless
3212 of whether or not the operation was successful.
3213 Since
3215 4.2
3216 MirrorCopyMode (Enum)
3218 An enumeration whose values tell the mirror block job when to trigger
3219 writes to the target.
3220 Values
3222 background
3223 copy data in background only.
3224 write-blocking
3226 when data is written to the source, write it (synchronously) to
3227 the target as well. In addition, data is copied in background
3228 just like in background mode.
3229 Since
3231 3.0
3232 BlockJobInfo (Object)
3234 Information about a long-running block device operation.
3235 Members
3237 type: string
3238 the job type ('stream' for image streaming)
3239 device: string
3241 The job identifier. Originally the device name but other values
3242 are allowed since QEMU 2.7
3243 len: int
3245 Estimated offset value at the completion of the job. This value
3246 can arbitrarily change while the job is running, in both direc‐
3247 tions.
3248 offset: int
3250 Progress made until now. The unit is arbitrary and the value can
3251 only meaningfully be used for the ratio of offset to len. The
3252 value is monotonically increasing.
3253 busy: boolean
3255 false if the job is known to be in a quiescent state, with no
3256 pending I/O. Since 1.3.
3257 paused: boolean
3259 whether the job is paused or, if busy is true, will pause itself
3260 as soon as possible. Since 1.3.
3261 speed: int
3263 the rate limit, bytes per second
3264 io-status: BlockDeviceIoStatus
3266 the status of the job (since 1.3)
3267 ready: boolean
3269 true if the job may be completed (since 2.2)
3270 status: JobStatus
3272 Current job state/status (since 2.12)
3273 auto-finalize: boolean
3275 Job will finalize itself when PENDING, moving to the CONCLUDED
3276 state. (since 2.12)
3277 auto-dismiss: boolean
3279 Job will dismiss itself when CONCLUDED, moving to the NULL state
3280 and disappearing from the query list. (since 2.12)
3281 error: string (optional)
3283 Error information if the job did not complete successfully. Not
3284 set if the job completed successfully. (since 2.12.1)
3285 Since
3287 1.1
3288 query-block-jobs (Command)
3290 Return information about long-running block device operations.
3291 Returns
3293 a list of BlockJobInfo for each active block job
3294 Since
3296 1.1
3297 block_resize (Command)
3299 Resize a block image while a guest is running.
3300 Either device or node-name must be set but not both.
3302 Arguments
3304 device: string (optional)
3305 the name of the device to get the image resized
3306 node-name: string (optional)
3308 graph node name to get the image resized (Since 2.0)
3309 size: int
3311 new image size in bytes
3312 Returns
3314 • nothing on success
3315 • If device is not a valid block device, DeviceNotFound
3317 Since
3319 0.14
3320 Example
3322 -> { "execute": "block_resize",
3323 "arguments": { "device": "scratch", "size": 1073741824 } }
3324 <- { "return": {} }
3325 NewImageMode (Enum)
3327 An enumeration that tells QEMU how to set the backing file path in a
3328 new image file.
3329 Values
3331 existing
3332 QEMU should look for an existing image file.
3333 absolute-paths
3335 QEMU should create a new image with absolute paths for the back‐
3336 ing file. If there is no backing file available, the new image
3337 will not be backed either.
3338 Since
3340 1.1
3341 BlockdevSnapshotSync (Object)
3343 Either device or node-name must be set but not both.
3344 Members
3346 device: string (optional)
3347 the name of the device to take a snapshot of.
3348 node-name: string (optional)
3350 graph node name to generate the snapshot from (Since 2.0)
3351 snapshot-file: string
3353 the target of the new overlay image. If the file exists, or if
3354 it is a device, the overlay will be created in the existing
3355 file/device. Otherwise, a new file will be created.
3356 snapshot-node-name: string (optional)
3358 the graph node name of the new image (Since 2.0)
3359 format: string (optional)
3361 the format of the overlay image, default is 'qcow2'.
3362 mode: NewImageMode (optional)
3364 whether and how QEMU should create a new image, default is 'ab‐
3365 solute-paths'.
3366 BlockdevSnapshot (Object)
3368 Members
3369 node: string
3370 device or node name that will have a snapshot taken.
3371 overlay: string
3373 reference to the existing block device that will become the
3374 overlay of node, as part of taking the snapshot. It must not
3375 have a current backing file (this can be achieved by passing
3376 "backing": null to blockdev-add).
3377 Since
3379 2.5
3380 BackupPerf (Object)
3382 Optional parameters for backup. These parameters don't affect function‐
3383 ality, but may significantly affect performance.
3384 Members
3386 use-copy-range: boolean (optional)
3387 Use copy offloading. Default false.
3388 max-workers: int (optional)
3390 Maximum number of parallel requests for the sustained background
3391 copying process. Doesn't influence copy-before-write operations.
3392 Default 64.
3393 max-chunk: int (optional)
3395 Maximum request length for the sustained background copying
3396 process. Doesn't influence copy-before-write operations. 0
3397 means unlimited. If max-chunk is non-zero then it should not be
3398 less than job cluster size which is calculated as maximum of
3399 target image cluster size and 64k. Default 0.
3400 Since
3402 6.0
3403 BackupCommon (Object)
3405 Members
3406 job-id: string (optional)
3407 identifier for the newly-created block job. If omitted, the de‐
3408 vice name will be used. (Since 2.7)
3409 device: string
3411 the device name or node-name of a root node which should be
3412 copied.
3413 sync: MirrorSyncMode
3415 what parts of the disk image should be copied to the destination
3416 (all the disk, only the sectors allocated in the topmost image,
3417 from a dirty bitmap, or only new I/O).
3418 speed: int (optional)
3420 the maximum speed, in bytes per second. The default is 0, for
3421 unlimited.
3422 bitmap: string (optional)
3424 The name of a dirty bitmap to use. Must be present if sync is
3425 "bitmap" or "incremental". Can be present if sync is "full" or
3426 "top". Must not be present otherwise. (Since 2.4
3427 (drive-backup), 3.1 (blockdev-backup))
3428 bitmap-mode: BitmapSyncMode (optional)
3430 Specifies the type of data the bitmap should contain after the
3431 operation concludes. Must be present if a bitmap was provided,
3432 Must NOT be present otherwise. (Since 4.2)
3433 compress: boolean (optional)
3435 true to compress data, if the target format supports it. (de‐
3436 fault: false) (since 2.8)
3437 on-source-error: BlockdevOnError (optional)
3439 the action to take on an error on the source, default 'report'.
3440 'stop' and 'enospc' can only be used if the block device sup‐
3441 ports io-status (see BlockInfo).
3442 on-target-error: BlockdevOnError (optional)
3444 the action to take on an error on the target, default 'report'
3445 (no limitations, since this applies to a different block device
3446 than device).
3447 auto-finalize: boolean (optional)
3449 When false, this job will wait in a PENDING state after it has
3450 finished its work, waiting for block-job-finalize before making
3451 any block graph changes. When true, this job will automatically
3452 perform its abort or commit actions. Defaults to true. (Since
3453 2.12)
3454 auto-dismiss: boolean (optional)
3456 When false, this job will wait in a CONCLUDED state after it has
3457 completely ceased all work, and awaits block-job-dismiss. When
3458 true, this job will automatically disappear from the query list
3459 without user intervention. Defaults to true. (Since 2.12)
3460 filter-node-name: string (optional)
3462 the node name that should be assigned to the filter driver that
3463 the backup job inserts into the graph above node specified by
3464 drive. If this option is not given, a node name is autogener‐
3465 ated. (Since: 4.2)
3466 x-perf: BackupPerf (optional)
3468 Performance options. (Since 6.0)
3469 Features
3471 unstable
3472 Member x-perf is experimental.
3473 Note
3475 on-source-error and on-target-error only affect background I/O. If an
3476 error occurs during a guest write request, the device's rerror/werror
3477 actions will be used.
3478 Since
3480 4.2
3481 DriveBackup (Object)
3483 Members
3484 target: string
3485 the target of the new image. If the file exists, or if it is a
3486 device, the existing file/device will be used as the new desti‐
3487 nation. If it does not exist, a new file will be created.
3488 format: string (optional)
3490 the format of the new destination, default is to probe if mode
3491 is 'existing', else the format of the source
3492 mode: NewImageMode (optional)
3494 whether and how QEMU should create a new image, default is 'ab‐
3495 solute-paths'.
3496 The members of BackupCommon
3498 Since
3500 1.6
3501 BlockdevBackup (Object)
3503 Members
3504 target: string
3505 the device name or node-name of the backup target node.
3506 The members of BackupCommon
3508 Since
3510 2.3
3511 blockdev-snapshot-sync (Command)
3513 Takes a synchronous snapshot of a block device.
3514 For the arguments, see the documentation of BlockdevSnapshotSync.
3516 Returns
3518 • nothing on success
3519 • If device is not a valid block device, DeviceNotFound
3521 Since
3523 0.14
3524 Example
3526 -> { "execute": "blockdev-snapshot-sync",
3527 "arguments": { "device": "ide-hd0",
3528 "snapshot-file":
3529 "/some/place/my-image",
3530 "format": "qcow2" } }
3531 <- { "return": {} }
3532 blockdev-snapshot (Command)
3534 Takes a snapshot of a block device.
3535 Take a snapshot, by installing 'node' as the backing image of 'over‐
3537 lay'. Additionally, if 'node' is associated with a block device, the
3538 block device changes to using 'overlay' as its new active image.
3539 For the arguments, see the documentation of BlockdevSnapshot.
3541 Features
3543 allow-write-only-overlay
3544 If present, the check whether this operation is safe was relaxed
3545 so that it can be used to change backing file of a destination
3546 of a blockdev-mirror. (since 5.0)
3547 Since
3549 2.5
3550 Example
3552 -> { "execute": "blockdev-add",
3553 "arguments": { "driver": "qcow2",
3554 "node-name": "node1534",
3555 "file": { "driver": "file",
3556 "filename": "hd1.qcow2" },
3557 "backing": null } }
3558 <- { "return": {} }
3560 -> { "execute": "blockdev-snapshot",
3562 "arguments": { "node": "ide-hd0",
3563 "overlay": "node1534" } }
3564 <- { "return": {} }
3565 change-backing-file (Command)
3567 Change the backing file in the image file metadata. This does not
3568 cause QEMU to reopen the image file to reparse the backing filename (it
3569 may, however, perform a reopen to change permissions from r/o -> r/w ->
3570 r/o, if needed). The new backing file string is written into the image
3571 file metadata, and the QEMU internal strings are updated.
3572 Arguments
3574 image-node-name: string
3575 The name of the block driver state node of the image to modify.
3576 The "device" argument is used to verify "image-node-name" is in
3577 the chain described by "device".
3578 device: string
3580 The device name or node-name of the root node that owns im‐
3581 age-node-name.
3582 backing-file: string
3584 The string to write as the backing file. This string is not
3585 validated, so care should be taken when specifying the string or
3586 the image chain may not be able to be reopened again.
3587 Returns
3589 • Nothing on success
3590 • If "device" does not exist or cannot be determined, DeviceNotFound
3592 Since
3594 2.1
3595 block-commit (Command)
3597 Live commit of data from overlay image nodes into backing nodes - i.e.,
3598 writes data between 'top' and 'base' into 'base'.
3599 If top == base, that is an error. If top has no overlays on top of it,
3601 or if it is in use by a writer, the job will not be completed by it‐
3602 self. The user needs to complete the job with the block-job-complete
3603 command after getting the ready event. (Since 2.0)
3604 If the base image is smaller than top, then the base image will be re‐
3606 sized to be the same size as top. If top is smaller than the base im‐
3607 age, the base will not be truncated. If you want the base image size
3608 to match the size of the smaller top, you can safely truncate it your‐
3609 self once the commit operation successfully completes.
3610 Arguments
3612 job-id: string (optional)
3613 identifier for the newly-created block job. If omitted, the de‐
3614 vice name will be used. (Since 2.7)
3615 device: string
3617 the device name or node-name of a root node
3618 base-node: string (optional)
3620 The node name of the backing image to write data into. If not
3621 specified, this is the deepest backing image. (since: 3.1)
3622 base: string (optional)
3624 Same as base-node, except that it is a file name rather than a
3625 node name. This must be the exact filename string that was used
3626 to open the node; other strings, even if addressing the same
3627 file, are not accepted
3628 top-node: string (optional)
3630 The node name of the backing image within the image chain which
3631 contains the topmost data to be committed down. If not speci‐
3632 fied, this is the active layer. (since: 3.1)
3633 top: string (optional)
3635 Same as top-node, except that it is a file name rather than a
3636 node name. This must be the exact filename string that was used
3637 to open the node; other strings, even if addressing the same
3638 file, are not accepted
3639 backing-file: string (optional)
3641 The backing file string to write into the overlay image of
3642 'top'. If 'top' does not have an overlay image, or if 'top' is
3643 in use by a writer, specifying a backing file string is an er‐
3644 ror.
3645 This filename is not validated. If a pathname string is such
3647 that it cannot be resolved by QEMU, that means that subsequent
3648 QMP or HMP commands must use node-names for the image in ques‐
3649 tion, as filename lookup methods will fail.
3650 If not specified, QEMU will automatically determine the backing
3652 file string to use, or error out if there is no obvious choice.
3653 Care should be taken when specifying the string, to specify a
3654 valid filename or protocol. (Since 2.1)
3655 speed: int (optional)
3657 the maximum speed, in bytes per second
3658 on-error: BlockdevOnError (optional)
3660 the action to take on an error. 'ignore' means that the request
3661 should be retried. (default: report; Since: 5.0)
3662 filter-node-name: string (optional)
3664 the node name that should be assigned to the filter driver that
3665 the commit job inserts into the graph above top. If this option
3666 is not given, a node name is autogenerated. (Since: 2.9)
3667 auto-finalize: boolean (optional)
3669 When false, this job will wait in a PENDING state after it has
3670 finished its work, waiting for block-job-finalize before making
3671 any block graph changes. When true, this job will automatically
3672 perform its abort or commit actions. Defaults to true. (Since
3673 3.1)
3674 auto-dismiss: boolean (optional)
3676 When false, this job will wait in a CONCLUDED state after it has
3677 completely ceased all work, and awaits block-job-dismiss. When
3678 true, this job will automatically disappear from the query list
3679 without user intervention. Defaults to true. (Since 3.1)
3680 Features
3682 deprecated
3683 Members base and top are deprecated. Use base-node and top-node
3684 instead.
3685 Returns
3687 • Nothing on success
3688 • If device does not exist, DeviceNotFound
3690 • Any other error returns a GenericError.
3692 Since
3694 1.3
3695 Example
3697 -> { "execute": "block-commit",
3698 "arguments": { "device": "virtio0",
3699 "top": "/tmp/snap1.qcow2" } }
3700 <- { "return": {} }
3701 drive-backup (Command)
3703 Start a point-in-time copy of a block device to a new destination. The
3704 status of ongoing drive-backup operations can be checked with
3705 query-block-jobs where the BlockJobInfo.type field has the value
3706 'backup'. The operation can be stopped before it has completed using
3707 the block-job-cancel command.
3708 Arguments
3710 The members of DriveBackup
3711 Features
3713 deprecated
3714 This command is deprecated. Use blockdev-backup instead.
3715 Returns
3717 • nothing on success
3718 • If device is not a valid block device, GenericError
3720 Since
3722 1.6
3723 Example
3725 -> { "execute": "drive-backup",
3726 "arguments": { "device": "drive0",
3727 "sync": "full",
3728 "target": "backup.img" } }
3729 <- { "return": {} }
3730 blockdev-backup (Command)
3732 Start a point-in-time copy of a block device to a new destination. The
3733 status of ongoing blockdev-backup operations can be checked with
3734 query-block-jobs where the BlockJobInfo.type field has the value
3735 'backup'. The operation can be stopped before it has completed using
3736 the block-job-cancel command.
3737 Arguments
3739 The members of BlockdevBackup
3740 Returns
3742 • nothing on success
3743 • If device is not a valid block device, DeviceNotFound
3745 Since
3747 2.3
3748 Example
3750 -> { "execute": "blockdev-backup",
3751 "arguments": { "device": "src-id",
3752 "sync": "full",
3753 "target": "tgt-id" } }
3754 <- { "return": {} }
3755 query-named-block-nodes (Command)
3757 Get the named block driver list
3758 Arguments
3760 flat: boolean (optional)
3761 Omit the nested data about backing image ("backing-image" key)
3762 if true. Default is false (Since 5.0)
3763 Returns
3765 the list of BlockDeviceInfo
3766 Since
3768 2.0
3769 Example
3771 -> { "execute": "query-named-block-nodes" }
3772 <- { "return": [ { "ro":false,
3773 "drv":"qcow2",
3774 "encrypted":false,
3775 "file":"disks/test.qcow2",
3776 "node-name": "my-node",
3777 "backing_file_depth":1,
3778 "detect_zeroes":"off",
3779 "bps":1000000,
3780 "bps_rd":0,
3781 "bps_wr":0,
3782 "iops":1000000,
3783 "iops_rd":0,
3784 "iops_wr":0,
3785 "bps_max": 8000000,
3786 "bps_rd_max": 0,
3787 "bps_wr_max": 0,
3788 "iops_max": 0,
3789 "iops_rd_max": 0,
3790 "iops_wr_max": 0,
3791 "iops_size": 0,
3792 "write_threshold": 0,
3793 "image":{
3794 "filename":"disks/test.qcow2",
3795 "format":"qcow2",
3796 "virtual-size":2048000,
3797 "backing_file":"base.qcow2",
3798 "full-backing-filename":"disks/base.qcow2",
3799 "backing-filename-format":"qcow2",
3800 "snapshots":[
3801 {
3802 "id": "1",
3803 "name": "snapshot1",
3804 "vm-state-size": 0,
3805 "date-sec": 10000200,
3806 "date-nsec": 12,
3807 "vm-clock-sec": 206,
3808 "vm-clock-nsec": 30
3809 }
3810 ],
3811 "backing-image":{
3812 "filename":"disks/base.qcow2",
3813 "format":"qcow2",
3814 "virtual-size":2048000
3815 }
3816 } } ] }
3817 XDbgBlockGraphNodeType (Enum)
3819 Values
3820 block-backend
3821 corresponds to BlockBackend
3822 block-job
3824 corresponds to BlockJob
3825 block-driver
3827 corresponds to BlockDriverState
3828 Since
3830 4.0
3831 XDbgBlockGraphNode (Object)
3833 Members
3834 id: int
3835 Block graph node identifier. This id is generated only for x-de‐
3836 bug-query-block-graph and does not relate to any other identi‐
3837 fiers in Qemu.
3838 type: XDbgBlockGraphNodeType
3840 Type of graph node. Can be one of block-backend, block-job or
3841 block-driver-state.
3842 name: string
3844 Human readable name of the node. Corresponds to node-name for
3845 block-driver-state nodes; is not guaranteed to be unique in the
3846 whole graph (with block-jobs and block-backends).
3847 Since
3849 4.0
3850 BlockPermission (Enum)
3852 Enum of base block permissions.
3853 Values
3855 consistent-read
3856 A user that has the "permission" of consistent reads is guaran‐
3857 teed that their view of the contents of the block device is com‐
3858 plete and self-consistent, representing the contents of a disk
3859 at a specific point. For most block devices (including their
3860 backing files) this is true, but the property cannot be main‐
3861 tained in a few situations like for intermediate nodes of a com‐
3862 mit block job.
3863 write This permission is required to change the visible disk contents.
3865 write-unchanged
3867 This permission (which is weaker than BLK_PERM_WRITE) is both
3868 enough and required for writes to the block node when the caller
3869 promises that the visible disk content doesn't change. As the
3870 BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
3871 cient to perform an unchanging write.
3872 resize This permission is required to change the size of a block node.
3874 Since
3876 4.0
3877 XDbgBlockGraphEdge (Object)
3879 Block Graph edge description for x-debug-query-block-graph.
3880 Members
3882 parent: int
3883 parent id
3884 child: int
3886 child id
3887 name: string
3889 name of the relation (examples are 'file' and 'backing')
3890 perm: array of BlockPermission
3892 granted permissions for the parent operating on the child
3893 shared-perm: array of BlockPermission
3895 permissions that can still be granted to other users of the
3896 child while it is still attached to this parent
3897 Since
3899 4.0
3900 XDbgBlockGraph (Object)
3902 Block Graph - list of nodes and list of edges.
3903 Members
3905 nodes: array of XDbgBlockGraphNode
3906 Not documented
3907 edges: array of XDbgBlockGraphEdge
3909 Not documented
3910 Since
3912 4.0
3913 x-debug-query-block-graph (Command)
3915 Get the block graph.
3916 Features
3918 unstable
3919 This command is meant for debugging.
3920 Since
3922 4.0
3923 drive-mirror (Command)
3925 Start mirroring a block device's writes to a new destination. target
3926 specifies the target of the new image. If the file exists, or if it is
3927 a device, it will be used as the new destination for writes. If it does
3928 not exist, a new file will be created. format specifies the format of
3929 the mirror image, default is to probe if mode='existing', else the for‐
3930 mat of the source.
3931 Arguments
3933 The members of DriveMirror
3934 Returns
3936 • nothing on success
3937 • If device is not a valid block device, GenericError
3939 Since
3941 1.3
3942 Example
3944 -> { "execute": "drive-mirror",
3945 "arguments": { "device": "ide-hd0",
3946 "target": "/some/place/my-image",
3947 "sync": "full",
3948 "format": "qcow2" } }
3949 <- { "return": {} }
3950 DriveMirror (Object)
3952 A set of parameters describing drive mirror setup.
3953 Members
3955 job-id: string (optional)
3956 identifier for the newly-created block job. If omitted, the de‐
3957 vice name will be used. (Since 2.7)
3958 device: string
3960 the device name or node-name of a root node whose writes should
3961 be mirrored.
3962 target: string
3964 the target of the new image. If the file exists, or if it is a
3965 device, the existing file/device will be used as the new desti‐
3966 nation. If it does not exist, a new file will be created.
3967 format: string (optional)
3969 the format of the new destination, default is to probe if mode
3970 is 'existing', else the format of the source
3971 node-name: string (optional)
3973 the new block driver state node name in the graph (Since 2.1)
3974 replaces: string (optional)
3976 with sync=full graph node name to be replaced by the new image
3977 when a whole image copy is done. This can be used to repair bro‐
3978 ken Quorum files. By default, device is replaced, although im‐
3979 plicitly created filters on it are kept. (Since 2.1)
3980 mode: NewImageMode (optional)
3982 whether and how QEMU should create a new image, default is 'ab‐
3983 solute-paths'.
3984 speed: int (optional)
3986 the maximum speed, in bytes per second
3987 sync: MirrorSyncMode
3989 what parts of the disk image should be copied to the destination
3990 (all the disk, only the sectors allocated in the topmost image,
3991 or only new I/O).
3992 granularity: int (optional)
3994 granularity of the dirty bitmap, default is 64K if the image
3995 format doesn't have clusters, 4K if the clusters are smaller
3996 than that, else the cluster size. Must be a power of 2 between
3997 512 and 64M (since 1.4).
3998 buf-size: int (optional)
4000 maximum amount of data in flight from source to target (since
4001 1.4).
4002 on-source-error: BlockdevOnError (optional)
4004 the action to take on an error on the source, default 'report'.
4005 'stop' and 'enospc' can only be used if the block device sup‐
4006 ports io-status (see BlockInfo).
4007 on-target-error: BlockdevOnError (optional)
4009 the action to take on an error on the target, default 'report'
4010 (no limitations, since this applies to a different block device
4011 than device).
4012 unmap: boolean (optional)
4014 Whether to try to unmap target sectors where source has only
4015 zero. If true, and target unallocated sectors will read as zero,
4016 target image sectors will be unmapped; otherwise, zeroes will be
4017 written. Both will result in identical contents. Default is
4018 true. (Since 2.4)
4019 copy-mode: MirrorCopyMode (optional)
4021 when to copy data to the destination; defaults to 'background'
4022 (Since: 3.0)
4023 auto-finalize: boolean (optional)
4025 When false, this job will wait in a PENDING state after it has
4026 finished its work, waiting for block-job-finalize before making
4027 any block graph changes. When true, this job will automatically
4028 perform its abort or commit actions. Defaults to true. (Since
4029 3.1)
4030 auto-dismiss: boolean (optional)
4032 When false, this job will wait in a CONCLUDED state after it has
4033 completely ceased all work, and awaits block-job-dismiss. When
4034 true, this job will automatically disappear from the query list
4035 without user intervention. Defaults to true. (Since 3.1)
4036 Since
4038 1.3
4039 BlockDirtyBitmap (Object)
4041 Members
4042 node: string
4043 name of device/node which the bitmap is tracking
4044 name: string
4046 name of the dirty bitmap
4047 Since
4049 2.4
4050 BlockDirtyBitmapAdd (Object)
4052 Members
4053 node: string
4054 name of device/node which the bitmap is tracking
4055 name: string
4057 name of the dirty bitmap (must be less than 1024 bytes)
4058 granularity: int (optional)
4060 the bitmap granularity, default is 64k for block-dirty-bit‐
4061 map-add
4062 persistent: boolean (optional)
4064 the bitmap is persistent, i.e. it will be saved to the corre‐
4065 sponding block device image file on its close. For now only
4066 Qcow2 disks support persistent bitmaps. Default is false for
4067 block-dirty-bitmap-add. (Since: 2.10)
4068 disabled: boolean (optional)
4070 the bitmap is created in the disabled state, which means that it
4071 will not track drive changes. The bitmap may be enabled with
4072 block-dirty-bitmap-enable. Default is false. (Since: 4.0)
4073 Since
4075 2.4
4076 BlockDirtyBitmapOrStr (Alternate)
4078 Members
4079 local: string
4080 name of the bitmap, attached to the same node as target bitmap.
4081 external: BlockDirtyBitmap
4083 bitmap with specified node
4084 Since
4086 4.1
4087 BlockDirtyBitmapMerge (Object)
4089 Members
4090 node: string
4091 name of device/node which the target bitmap is tracking
4092 target: string
4094 name of the destination dirty bitmap
4095 bitmaps: array of BlockDirtyBitmapOrStr
4097 name(s) of the source dirty bitmap(s) at node and/or fully spec‐
4098 ified BlockDirtyBitmap elements. The latter are supported since
4099 4.1.
4100 Since
4102 4.0
4103 block-dirty-bitmap-add (Command)
4105 Create a dirty bitmap with a name on the node, and start tracking the
4106 writes.
4107 Returns
4109 • nothing on success
4110 • If node is not a valid block device or node, DeviceNotFound
4112 • If name is already taken, GenericError with an explanation
4114 Since
4116 2.4
4117 Example
4119 -> { "execute": "block-dirty-bitmap-add",
4120 "arguments": { "node": "drive0", "name": "bitmap0" } }
4121 <- { "return": {} }
4122 block-dirty-bitmap-remove (Command)
4124 Stop write tracking and remove the dirty bitmap that was created with
4125 block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
4126 storage too.
4127 Returns
4129 • nothing on success
4130 • If node is not a valid block device or node, DeviceNotFound
4132 • If name is not found, GenericError with an explanation
4134 • if name is frozen by an operation, GenericError
4136 Since
4138 2.4
4139 Example
4141 -> { "execute": "block-dirty-bitmap-remove",
4142 "arguments": { "node": "drive0", "name": "bitmap0" } }
4143 <- { "return": {} }
4144 block-dirty-bitmap-clear (Command)
4146 Clear (reset) a dirty bitmap on the device, so that an incremental
4147 backup from this point in time forward will only backup clusters modi‐
4148 fied after this clear operation.
4149 Returns
4151 • nothing on success
4152 • If node is not a valid block device, DeviceNotFound
4154 • If name is not found, GenericError with an explanation
4156 Since
4158 2.4
4159 Example
4161 -> { "execute": "block-dirty-bitmap-clear",
4162 "arguments": { "node": "drive0", "name": "bitmap0" } }
4163 <- { "return": {} }
4164 block-dirty-bitmap-enable (Command)
4166 Enables a dirty bitmap so that it will begin tracking disk changes.
4167 Returns
4169 • nothing on success
4170 • If node is not a valid block device, DeviceNotFound
4172 • If name is not found, GenericError with an explanation
4174 Since
4176 4.0
4177 Example
4179 -> { "execute": "block-dirty-bitmap-enable",
4180 "arguments": { "node": "drive0", "name": "bitmap0" } }
4181 <- { "return": {} }
4182 block-dirty-bitmap-disable (Command)
4184 Disables a dirty bitmap so that it will stop tracking disk changes.
4185 Returns
4187 • nothing on success
4188 • If node is not a valid block device, DeviceNotFound
4190 • If name is not found, GenericError with an explanation
4192 Since
4194 4.0
4195 Example
4197 -> { "execute": "block-dirty-bitmap-disable",
4198 "arguments": { "node": "drive0", "name": "bitmap0" } }
4199 <- { "return": {} }
4200 block-dirty-bitmap-merge (Command)
4202 Merge dirty bitmaps listed in bitmaps to the target dirty bitmap.
4203 Dirty bitmaps in bitmaps will be unchanged, except if it also appears
4204 as the target bitmap. Any bits already set in target will still be set
4205 after the merge, i.e., this operation does not clear the target. On
4206 error, target is unchanged.
4207 The resulting bitmap will count as dirty any clusters that were dirty
4209 in any of the source bitmaps. This can be used to achieve backup check‐
4210 points, or in simpler usages, to copy bitmaps.
4211 Returns
4213 • nothing on success
4214 • If node is not a valid block device, DeviceNotFound
4216 • If any bitmap in bitmaps or target is not found, GenericError
4218 • If any of the bitmaps have different sizes or granularities, Gener‐
4220 icError
4221 Since
4223 4.0
4224 Example
4226 -> { "execute": "block-dirty-bitmap-merge",
4227 "arguments": { "node": "drive0", "target": "bitmap0",
4228 "bitmaps": ["bitmap1"] } }
4229 <- { "return": {} }
4230 BlockDirtyBitmapSha256 (Object)
4232 SHA256 hash of dirty bitmap data
4233 Members
4235 sha256: string
4236 ASCII representation of SHA256 bitmap hash
4237 Since
4239 2.10
4240 x-debug-block-dirty-bitmap-sha256 (Command)
4242 Get bitmap SHA256.
4243 Features
4245 unstable
4246 This command is meant for debugging.
4247 Returns
4249 • BlockDirtyBitmapSha256 on success
4250 • If node is not a valid block device, DeviceNotFound
4252 • If name is not found or if hashing has failed, GenericError with an
4254 explanation
4255 Since
4257 2.10
4258 blockdev-mirror (Command)
4260 Start mirroring a block device's writes to a new destination.
4261 Arguments
4263 job-id: string (optional)
4264 identifier for the newly-created block job. If omitted, the de‐
4265 vice name will be used. (Since 2.7)
4266 device: string
4268 The device name or node-name of a root node whose writes should
4269 be mirrored.
4270 target: string
4272 the id or node-name of the block device to mirror to. This
4273 mustn't be attached to guest.
4274 replaces: string (optional)
4276 with sync=full graph node name to be replaced by the new image
4277 when a whole image copy is done. This can be used to repair bro‐
4278 ken Quorum files. By default, device is replaced, although im‐
4279 plicitly created filters on it are kept.
4280 speed: int (optional)
4282 the maximum speed, in bytes per second
4283 sync: MirrorSyncMode
4285 what parts of the disk image should be copied to the destination
4286 (all the disk, only the sectors allocated in the topmost image,
4287 or only new I/O).
4288 granularity: int (optional)
4290 granularity of the dirty bitmap, default is 64K if the image
4291 format doesn't have clusters, 4K if the clusters are smaller
4292 than that, else the cluster size. Must be a power of 2 between
4293 512 and 64M
4294 buf-size: int (optional)
4296 maximum amount of data in flight from source to target
4297 on-source-error: BlockdevOnError (optional)
4299 the action to take on an error on the source, default 'report'.
4300 'stop' and 'enospc' can only be used if the block device sup‐
4301 ports io-status (see BlockInfo).
4302 on-target-error: BlockdevOnError (optional)
4304 the action to take on an error on the target, default 'report'
4305 (no limitations, since this applies to a different block device
4306 than device).
4307 filter-node-name: string (optional)
4309 the node name that should be assigned to the filter driver that
4310 the mirror job inserts into the graph above device. If this op‐
4311 tion is not given, a node name is autogenerated. (Since: 2.9)
4312 copy-mode: MirrorCopyMode (optional)
4314 when to copy data to the destination; defaults to 'background'
4315 (Since: 3.0)
4316 auto-finalize: boolean (optional)
4318 When false, this job will wait in a PENDING state after it has
4319 finished its work, waiting for block-job-finalize before making
4320 any block graph changes. When true, this job will automatically
4321 perform its abort or commit actions. Defaults to true. (Since
4322 3.1)
4323 auto-dismiss: boolean (optional)
4325 When false, this job will wait in a CONCLUDED state after it has
4326 completely ceased all work, and awaits block-job-dismiss. When
4327 true, this job will automatically disappear from the query list
4328 without user intervention. Defaults to true. (Since 3.1)
4329 Returns
4331 nothing on success.
4332 Since
4334 2.6
4335 Example
4337 -> { "execute": "blockdev-mirror",
4338 "arguments": { "device": "ide-hd0",
4339 "target": "target0",
4340 "sync": "full" } }
4341 <- { "return": {} }
4342 BlockIOThrottle (Object)
4344 A set of parameters describing block throttling.
4345 Members
4347 device: string (optional)
4348 Block device name
4349 id: string (optional)
4351 The name or QOM path of the guest device (since: 2.8)
4352 bps: int
4354 total throughput limit in bytes per second
4355 bps_rd: int
4357 read throughput limit in bytes per second
4358 bps_wr: int
4360 write throughput limit in bytes per second
4361 iops: int
4363 total I/O operations per second
4364 iops_rd: int
4366 read I/O operations per second
4367 iops_wr: int
4369 write I/O operations per second
4370 bps_max: int (optional)
4372 total throughput limit during bursts, in bytes (Since 1.7)
4373 bps_rd_max: int (optional)
4375 read throughput limit during bursts, in bytes (Since 1.7)
4376 bps_wr_max: int (optional)
4378 write throughput limit during bursts, in bytes (Since 1.7)
4379 iops_max: int (optional)
4381 total I/O operations per second during bursts, in bytes (Since
4382 1.7)
4383 iops_rd_max: int (optional)
4385 read I/O operations per second during bursts, in bytes (Since
4386 1.7)
4387 iops_wr_max: int (optional)
4389 write I/O operations per second during bursts, in bytes (Since
4390 1.7)
4391 bps_max_length: int (optional)
4393 maximum length of the bps_max burst period, in seconds. It must
4394 only be set if bps_max is set as well. Defaults to 1. (Since
4395 2.6)
4396 bps_rd_max_length: int (optional)
4398 maximum length of the bps_rd_max burst period, in seconds. It
4399 must only be set if bps_rd_max is set as well. Defaults to 1.
4400 (Since 2.6)
4401 bps_wr_max_length: int (optional)
4403 maximum length of the bps_wr_max burst period, in seconds. It
4404 must only be set if bps_wr_max is set as well. Defaults to 1.
4405 (Since 2.6)
4406 iops_max_length: int (optional)
4408 maximum length of the iops burst period, in seconds. It must
4409 only be set if iops_max is set as well. Defaults to 1. (Since
4410 2.6)
4411 iops_rd_max_length: int (optional)
4413 maximum length of the iops_rd_max burst period, in seconds. It
4414 must only be set if iops_rd_max is set as well. Defaults to 1.
4415 (Since 2.6)
4416 iops_wr_max_length: int (optional)
4418 maximum length of the iops_wr_max burst period, in seconds. It
4419 must only be set if iops_wr_max is set as well. Defaults to 1.
4420 (Since 2.6)
4421 iops_size: int (optional)
4423 an I/O size in bytes (Since 1.7)
4424 group: string (optional)
4426 throttle group name (Since 2.4)
4427 Features
4429 deprecated
4430 Member device is deprecated. Use id instead.
4431 Since
4433 1.1
4434 ThrottleLimits (Object)
4436 Limit parameters for throttling. Since some limit combinations are il‐
4437 legal, limits should always be set in one transaction. All fields are
4438 optional. When setting limits, if a field is missing the current value
4439 is not changed.
4440 Members
4442 iops-total: int (optional)
4443 limit total I/O operations per second
4444 iops-total-max: int (optional)
4446 I/O operations burst
4447 iops-total-max-length: int (optional)
4449 length of the iops-total-max burst period, in seconds It must
4450 only be set if iops-total-max is set as well.
4451 iops-read: int (optional)
4453 limit read operations per second
4454 iops-read-max: int (optional)
4456 I/O operations read burst
4457 iops-read-max-length: int (optional)
4459 length of the iops-read-max burst period, in seconds It must
4460 only be set if iops-read-max is set as well.
4461 iops-write: int (optional)
4463 limit write operations per second
4464 iops-write-max: int (optional)
4466 I/O operations write burst
4467 iops-write-max-length: int (optional)
4469 length of the iops-write-max burst period, in seconds It must
4470 only be set if iops-write-max is set as well.
4471 bps-total: int (optional)
4473 limit total bytes per second
4474 bps-total-max: int (optional)
4476 total bytes burst
4477 bps-total-max-length: int (optional)
4479 length of the bps-total-max burst period, in seconds. It must
4480 only be set if bps-total-max is set as well.
4481 bps-read: int (optional)
4483 limit read bytes per second
4484 bps-read-max: int (optional)
4486 total bytes read burst
4487 bps-read-max-length: int (optional)
4489 length of the bps-read-max burst period, in seconds It must only
4490 be set if bps-read-max is set as well.
4491 bps-write: int (optional)
4493 limit write bytes per second
4494 bps-write-max: int (optional)
4496 total bytes write burst
4497 bps-write-max-length: int (optional)
4499 length of the bps-write-max burst period, in seconds It must
4500 only be set if bps-write-max is set as well.
4501 iops-size: int (optional)
4503 when limiting by iops max size of an I/O in bytes
4504 Since
4506 2.11
4507 ThrottleGroupProperties (Object)
4509 Properties for throttle-group objects.
4510 Members
4512 limits: ThrottleLimits (optional)
4513 limits to apply for this throttle group
4514 x-iops-total: int (optional)
4516 Not documented
4517 x-iops-total-max: int (optional)
4519 Not documented
4520 x-iops-total-max-length: int (optional)
4522 Not documented
4523 x-iops-read: int (optional)
4525 Not documented
4526 x-iops-read-max: int (optional)
4528 Not documented
4529 x-iops-read-max-length: int (optional)
4531 Not documented
4532 x-iops-write: int (optional)
4534 Not documented
4535 x-iops-write-max: int (optional)
4537 Not documented
4538 x-iops-write-max-length: int (optional)
4540 Not documented
4541 x-bps-total: int (optional)
4543 Not documented
4544 x-bps-total-max: int (optional)
4546 Not documented
4547 x-bps-total-max-length: int (optional)
4549 Not documented
4550 x-bps-read: int (optional)
4552 Not documented
4553 x-bps-read-max: int (optional)
4555 Not documented
4556 x-bps-read-max-length: int (optional)
4558 Not documented
4559 x-bps-write: int (optional)
4561 Not documented
4562 x-bps-write-max: int (optional)
4564 Not documented
4565 x-bps-write-max-length: int (optional)
4567 Not documented
4568 x-iops-size: int (optional)
4570 Not documented
4571 Features
4573 unstable
4574 All members starting with x- are aliases for the same key with‐
4575 out x- in the limits object. This is not a stable interface and
4576 may be removed or changed incompatibly in the future. Use lim‐
4577 its for a supported stable interface.
4578 Since
4580 2.11
4581 block-stream (Command)
4583 Copy data from a backing file into a block device.
4584 The block streaming operation is performed in the background until the
4586 entire backing file has been copied. This command returns immediately
4587 once streaming has started. The status of ongoing block streaming op‐
4588 erations can be checked with query-block-jobs. The operation can be
4589 stopped before it has completed using the block-job-cancel command.
4590 The node that receives the data is called the top image, can be located
4592 in any part of the chain (but always above the base image; see below)
4593 and can be specified using its device or node name. Earlier qemu ver‐
4594 sions only allowed 'device' to name the top level node; presence of the
4595 'base-node' parameter during introspection can be used as a witness of
4596 the enhanced semantics of 'device'.
4597 If a base file is specified then sectors are not copied from that base
4599 file and its backing chain. This can be used to stream a subset of the
4600 backing file chain instead of flattening the entire image. When
4601 streaming completes the image file will have the base file as its back‐
4602 ing file, unless that node was changed while the job was running. In
4603 that case, base's parent's backing (or filtered, whichever exists)
4604 child (i.e., base at the beginning of the job) will be the new backing
4605 file.
4606 On successful completion the image file is updated to drop the backing
4608 file and the BLOCK_JOB_COMPLETED event is emitted.
4609 In case device is a filter node, block-stream modifies the first
4611 non-filter overlay node below it to point to the new backing node in‐
4612 stead of modifying device itself.
4613 Arguments
4615 job-id: string (optional)
4616 identifier for the newly-created block job. If omitted, the de‐
4617 vice name will be used. (Since 2.7)
4618 device: string
4620 the device or node name of the top image
4621 base: string (optional)
4623 the common backing file name. It cannot be set if base-node or
4624 bottom is also set.
4625 base-node: string (optional)
4627 the node name of the backing file. It cannot be set if base or
4628 bottom is also set. (Since 2.8)
4629 bottom: string (optional)
4631 the last node in the chain that should be streamed into top. It
4632 cannot be set if base or base-node is also set. It cannot be
4633 filter node. (Since 6.0)
4634 backing-file: string (optional)
4636 The backing file string to write into the top image. This file‐
4637 name is not validated.
4638 If a pathname string is such that it cannot be resolved by QEMU,
4640 that means that subsequent QMP or HMP commands must use
4641 node-names for the image in question, as filename lookup methods
4642 will fail.
4643 If not specified, QEMU will automatically determine the backing
4645 file string to use, or error out if there is no obvious choice.
4646 Care should be taken when specifying the string, to specify a
4647 valid filename or protocol. (Since 2.1)
4648 speed: int (optional)
4650 the maximum speed, in bytes per second
4651 on-error: BlockdevOnError (optional)
4653 the action to take on an error (default report). 'stop' and
4654 'enospc' can only be used if the block device supports io-status
4655 (see BlockInfo). Since 1.3.
4656 filter-node-name: string (optional)
4658 the node name that should be assigned to the filter driver that
4659 the stream job inserts into the graph above device. If this op‐
4660 tion is not given, a node name is autogenerated. (Since: 6.0)
4661 auto-finalize: boolean (optional)
4663 When false, this job will wait in a PENDING state after it has
4664 finished its work, waiting for block-job-finalize before making
4665 any block graph changes. When true, this job will automatically
4666 perform its abort or commit actions. Defaults to true. (Since
4667 3.1)
4668 auto-dismiss: boolean (optional)
4670 When false, this job will wait in a CONCLUDED state after it has
4671 completely ceased all work, and awaits block-job-dismiss. When
4672 true, this job will automatically disappear from the query list
4673 without user intervention. Defaults to true. (Since 3.1)
4674 Returns
4676 • Nothing on success.
4677 • If device does not exist, DeviceNotFound.
4679 Since
4681 1.1
4682 Example
4684 -> { "execute": "block-stream",
4685 "arguments": { "device": "virtio0",
4686 "base": "/tmp/master.qcow2" } }
4687 <- { "return": {} }
4688 block-job-set-speed (Command)
4690 Set maximum speed for a background block operation.
4691 This command can only be issued when there is an active block job.
4693 Throttling can be disabled by setting the speed to 0.
4695 Arguments
4697 device: string
4698 The job identifier. This used to be a device name (hence the
4699 name of the parameter), but since QEMU 2.7 it can have other
4700 values.
4701 speed: int
4703 the maximum speed, in bytes per second, or 0 for unlimited. De‐
4704 faults to 0.
4705 Returns
4707 • Nothing on success
4708 • If no background operation is active on this device, DeviceNotActive
4710 Since
4712 1.1
4713 block-job-cancel (Command)
4715 Stop an active background block operation.
4716 This command returns immediately after marking the active background
4718 block operation for cancellation. It is an error to call this command
4719 if no operation is in progress.
4720 The operation will cancel as soon as possible and then emit the
4722 BLOCK_JOB_CANCELLED event. Before that happens the job is still visi‐
4723 ble when enumerated using query-block-jobs.
4724 Note that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
4726 dicated (via the event BLOCK_JOB_READY) that the source and destination
4727 are synchronized, then the event triggered by this command changes to
4728 BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
4729 destination now has a point-in-time copy tied to the time of the can‐
4730 cellation.
4731 For streaming, the image file retains its backing file unless the
4733 streaming operation happens to complete just as it is being cancelled.
4734 A new streaming operation can be started at a later time to finish
4735 copying all data from the backing file.
4736 Arguments
4738 device: string
4739 The job identifier. This used to be a device name (hence the
4740 name of the parameter), but since QEMU 2.7 it can have other
4741 values.
4742 force: boolean (optional)
4744 If true, and the job has already emitted the event
4745 BLOCK_JOB_READY, abandon the job immediately (even if it is
4746 paused) instead of waiting for the destination to complete its
4747 final synchronization (since 1.3)
4748 Returns
4750 • Nothing on success
4751 • If no background operation is active on this device, DeviceNotActive
4753 Since
4755 1.1
4756 block-job-pause (Command)
4758 Pause an active background block operation.
4759 This command returns immediately after marking the active background
4761 block operation for pausing. It is an error to call this command if no
4762 operation is in progress or if the job is already paused.
4763 The operation will pause as soon as possible. No event is emitted when
4765 the operation is actually paused. Cancelling a paused job automati‐
4766 cally resumes it.
4767 Arguments
4769 device: string
4770 The job identifier. This used to be a device name (hence the
4771 name of the parameter), but since QEMU 2.7 it can have other
4772 values.
4773 Returns
4775 • Nothing on success
4776 • If no background operation is active on this device, DeviceNotActive
4778 Since
4780 1.3
4781 block-job-resume (Command)
4783 Resume an active background block operation.
4784 This command returns immediately after resuming a paused background
4786 block operation. It is an error to call this command if no operation
4787 is in progress or if the job is not paused.
4788 This command also clears the error status of the job.
4790 Arguments
4792 device: string
4793 The job identifier. This used to be a device name (hence the
4794 name of the parameter), but since QEMU 2.7 it can have other
4795 values.
4796 Returns
4798 • Nothing on success
4799 • If no background operation is active on this device, DeviceNotActive
4801 Since
4803 1.3
4804 block-job-complete (Command)
4806 Manually trigger completion of an active background block operation.
4807 This is supported for drive mirroring, where it also switches the de‐
4808 vice to write to the target path only. The ability to complete is sig‐
4809 naled with a BLOCK_JOB_READY event.
4810 This command completes an active background block operation syn‐
4812 chronously. The ordering of this command's return with the
4813 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
4814 occurs during the processing of this command: 1) the command itself
4815 will fail; 2) the error will be processed according to the rerror/wer‐
4816 ror arguments that were specified when starting the operation.
4817 A cancelled or paused job cannot be completed.
4819 Arguments
4821 device: string
4822 The job identifier. This used to be a device name (hence the
4823 name of the parameter), but since QEMU 2.7 it can have other
4824 values.
4825 Returns
4827 • Nothing on success
4828 • If no background operation is active on this device, DeviceNotActive
4830 Since
4832 1.3
4833 block-job-dismiss (Command)
4835 For jobs that have already concluded, remove them from the
4836 block-job-query list. This command only needs to be run for jobs which
4837 were started with QEMU 2.12+ job lifetime management semantics.
4838 This command will refuse to operate on any job that has not yet reached
4840 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
4841 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
4842 still need to be used as appropriate.
4843 Arguments
4845 id: string
4846 The job identifier.
4847 Returns
4849 Nothing on success
4850 Since
4852 2.12
4853 block-job-finalize (Command)
4855 Once a job that has manual=true reaches the pending state, it can be
4856 instructed to finalize any graph changes and do any necessary cleanup
4857 via this command. For jobs in a transaction, instructing one job to
4858 finalize will force ALL jobs in the transaction to finalize, so it is
4859 only necessary to instruct a single member job to finalize.
4860 Arguments
4862 id: string
4863 The job identifier.
4864 Returns
4866 Nothing on success
4867 Since
4869 2.12
4870 BlockdevDiscardOptions (Enum)
4872 Determines how to handle discard requests.
4873 Values
4875 ignore Ignore the request
4876 unmap Forward as an unmap request
4878 Since
4880 2.9
4881 BlockdevDetectZeroesOptions (Enum)
4883 Describes the operation mode for the automatic conversion of plain zero
4884 writes by the OS to driver specific optimized zero write commands.
4885 Values
4887 off Disabled (default)
4888 on Enabled
4890 unmap Enabled and even try to unmap blocks if possible. This requires
4892 also that BlockdevDiscardOptions is set to unmap for this de‐
4893 vice.
4894 Since
4896 2.1
4897 BlockdevAioOptions (Enum)
4899 Selects the AIO backend to handle I/O requests
4900 Values
4902 threads
4903 Use qemu's thread pool
4904 native Use native AIO backend (only Linux and Windows)
4906 io_uring (If: CONFIG_LINUX_IO_URING)
4908 Use linux io_uring (since 5.0)
4909 Since
4911 2.9
4912 BlockdevCacheOptions (Object)
4914 Includes cache-related options for block devices
4915 Members
4917 direct: boolean (optional)
4918 enables use of O_DIRECT (bypass the host page cache; default:
4919 false)
4920 no-flush: boolean (optional)
4922 ignore any flush requests for the device (default: false)
4923 Since
4925 2.9
4926 BlockdevDriver (Enum)
4928 Drivers that are supported in block device operations.
4929 Values
4931 throttle
4932 Since 2.11
4933 nvme Since 2.12
4935 copy-on-read
4937 Since 3.0
4938 blklogwrites
4940 Since 3.0
4941 blkreplay
4943 Since 4.2
4944 compress
4946 Since 5.0
4947 copy-before-write
4949 Since 6.2
4950 snapshot-access
4952 Since 7.0
4953 blkdebug
4955 Not documented
4956 blkverify
4958 Not documented
4959 bochs Not documented
4961 cloop Not documented
4963 dmg Not documented
4965 file Not documented
4967 ftp Not documented
4969 ftps Not documented
4971 gluster
4973 Not documented
4974 host_cdrom (If: HAVE_HOST_BLOCK_DEVICE)
4976 Not documented
4977 host_device (If: HAVE_HOST_BLOCK_DEVICE)
4979 Not documented
4980 http Not documented
4982 https Not documented
4984 io_uring (If: CONFIG_BLKIO)
4986 Not documented
4987 iscsi Not documented
4989 luks Not documented
4991 nbd Not documented
4993 nfs Not documented
4995 null-aio
4997 Not documented
4998 null-co
5000 Not documented
5001 nvme-io_uring (If: CONFIG_BLKIO)
5003 Not documented
5004 parallels
5006 Not documented
5007 preallocate
5009 Not documented
5010 qcow Not documented
5012 qcow2 Not documented
5014 qed Not documented
5016 quorum Not documented
5018 raw Not documented
5020 rbd Not documented
5022 replication (If: CONFIG_REPLICATION)
5024 Not documented
5025 ssh Not documented
5027 vdi Not documented
5029 vhdx Not documented
5031 virtio-blk-vfio-pci (If: CONFIG_BLKIO)
5033 Not documented
5034 virtio-blk-vhost-user (If: CONFIG_BLKIO)
5036 Not documented
5037 virtio-blk-vhost-vdpa (If: CONFIG_BLKIO)
5039 Not documented
5040 vmdk Not documented
5042 vpc Not documented
5044 vvfat Not documented
5046 Since
5048 2.9
5049 BlockdevOptionsFile (Object)
5051 Driver specific block device options for the file backend.
5052 Members
5054 filename: string
5055 path to the image file
5056 pr-manager: string (optional)
5058 the id for the object that will handle persistent reservations
5059 for this device (default: none, forward the commands via SG_IO;
5060 since 2.11)
5061 aio: BlockdevAioOptions (optional)
5063 AIO backend (default: threads) (since: 2.8)
5064 aio-max-batch: int (optional)
5066 maximum number of requests to batch together into a single sub‐
5067 mission in the AIO backend. The smallest value between this and
5068 the aio-max-batch value of the IOThread object is chosen. 0
5069 means that the AIO backend will handle it automatically. (de‐
5070 fault: 0, since 6.2)
5071 locking: OnOffAuto (optional)
5073 whether to enable file locking. If set to 'auto', only enable
5074 when Open File Descriptor (OFD) locking API is available (de‐
5075 fault: auto, since 2.10)
5076 drop-cache: boolean (optional) (If: CONFIG_LINUX)
5078 invalidate page cache during live migration. This prevents
5079 stale data on the migration destination with cache.direct=off.
5080 Currently only supported on Linux hosts. (default: on, since:
5081 4.0)
5082 x-check-cache-dropped: boolean (optional)
5084 whether to check that page cache was dropped on live migration.
5085 May cause noticeable delays if the image file is large, do not
5086 use in production. (default: off) (since: 3.0)
5087 Features
5089 dynamic-auto-read-only
5090 If present, enabled auto-read-only means that the driver will
5091 open the image read-only at first, dynamically reopen the image
5092 file read-write when the first writer is attached to the node
5093 and reopen read-only when the last writer is detached. This al‐
5094 lows giving QEMU write permissions only on demand when an opera‐
5095 tion actually needs write access.
5096 unstable
5098 Member x-check-cache-dropped is meant for debugging.
5099 Since
5101 2.9
5102 BlockdevOptionsNull (Object)
5104 Driver specific block device options for the null backend.
5105 Members
5107 size: int (optional)
5108 size of the device in bytes.
5109 latency-ns: int (optional)
5111 emulated latency (in nanoseconds) in processing requests. De‐
5112 fault to zero which completes requests immediately. (Since 2.4)
5113 read-zeroes: boolean (optional)
5115 if true, reads from the device produce zeroes; if false, the
5116 buffer is left unchanged. (default: false; since: 4.1)
5117 Since
5119 2.9
5120 BlockdevOptionsNVMe (Object)
5122 Driver specific block device options for the NVMe backend.
5123 Members
5125 device: string
5126 PCI controller address of the NVMe device in format hhhh:bb:ss.f
5127 (host:bus:slot.function)
5128 namespace: int
5130 namespace number of the device, starting from 1.
5131 Note that the PCI device must have been unbound from any host kernel
5132 driver before instructing QEMU to add the blockdev.
5133 Since
5135 2.12
5136 BlockdevOptionsVVFAT (Object)
5138 Driver specific block device options for the vvfat protocol.
5139 Members
5141 dir: string
5142 directory to be exported as FAT image
5143 fat-type: int (optional)
5145 FAT type: 12, 16 or 32
5146 floppy: boolean (optional)
5148 whether to export a floppy image (true) or partitioned hard disk
5149 (false; default)
5150 label: string (optional)
5152 set the volume label, limited to 11 bytes. FAT16 and FAT32 tra‐
5153 ditionally have some restrictions on labels, which are ignored
5154 by most operating systems. Defaults to "QEMU VVFAT". (since
5155 2.4)
5156 rw: boolean (optional)
5158 whether to allow write operations (default: false)
5159 Since
5161 2.9
5162 BlockdevOptionsGenericFormat (Object)
5164 Driver specific block device options for image format that have no op‐
5165 tion besides their data source.
5166 Members
5168 file: BlockdevRef
5169 reference to or definition of the data source block device
5170 Since
5172 2.9
5173 BlockdevOptionsLUKS (Object)
5175 Driver specific block device options for LUKS.
5176 Members
5178 key-secret: string (optional)
5179 the ID of a QCryptoSecret object providing the decryption key
5180 (since 2.6). Mandatory except when doing a metadata-only probe
5181 of the image.
5182 The members of BlockdevOptionsGenericFormat
5184 Since
5186 2.9
5187 BlockdevOptionsGenericCOWFormat (Object)
5189 Driver specific block device options for image format that have no op‐
5190 tion besides their data source and an optional backing file.
5191 Members
5193 backing: BlockdevRefOrNull (optional)
5194 reference to or definition of the backing file block device,
5195 null disables the backing file entirely. Defaults to the back‐
5196 ing file stored the image file.
5197 The members of BlockdevOptionsGenericFormat
5199 Since
5201 2.9
5202 Qcow2OverlapCheckMode (Enum)
5204 General overlap check modes.
5205 Values
5207 none Do not perform any checks
5208 constant
5210 Perform only checks which can be done in constant time and with‐
5211 out reading anything from disk
5212 cached Perform only checks which can be done without reading anything
5214 from disk
5215 all Perform all available overlap checks
5217 Since
5219 2.9
5220 Qcow2OverlapCheckFlags (Object)
5222 Structure of flags for each metadata structure. Setting a field to
5223 'true' makes qemu guard that structure against unintended overwriting.
5224 The default value is chosen according to the template given.
5225 Members
5227 template: Qcow2OverlapCheckMode (optional)
5228 Specifies a template mode which can be adjusted using the other
5229 flags, defaults to 'cached'
5230 bitmap-directory: boolean (optional)
5232 since 3.0
5233 main-header: boolean (optional)
5235 Not documented
5236 active-l1: boolean (optional)
5238 Not documented
5239 active-l2: boolean (optional)
5241 Not documented
5242 refcount-table: boolean (optional)
5244 Not documented
5245 refcount-block: boolean (optional)
5247 Not documented
5248 snapshot-table: boolean (optional)
5250 Not documented
5251 inactive-l1: boolean (optional)
5253 Not documented
5254 inactive-l2: boolean (optional)
5256 Not documented
5257 Since
5259 2.9
5260 Qcow2OverlapChecks (Alternate)
5262 Specifies which metadata structures should be guarded against unin‐
5263 tended overwriting.
5264 Members
5266 flags: Qcow2OverlapCheckFlags
5267 set of flags for separate specification of each metadata struc‐
5268 ture type
5269 mode: Qcow2OverlapCheckMode
5271 named mode which chooses a specific set of flags
5272 Since
5274 2.9
5275 BlockdevQcowEncryptionFormat (Enum)
5277 Values
5278 aes AES-CBC with plain64 initialization vectors
5279 Since
5281 2.10
5282 BlockdevQcowEncryption (Object)
5284 Members
5285 format: BlockdevQcowEncryptionFormat
5286 Not documented
5287 The members of QCryptoBlockOptionsQCow when format is "aes"
5289 Since
5291 2.10
5292 BlockdevOptionsQcow (Object)
5294 Driver specific block device options for qcow.
5295 Members
5297 encrypt: BlockdevQcowEncryption (optional)
5298 Image decryption options. Mandatory for encrypted images, except
5299 when doing a metadata-only probe of the image.
5300 The members of BlockdevOptionsGenericCOWFormat
5302 Since
5304 2.10
5305 BlockdevQcow2EncryptionFormat (Enum)
5307 Values
5308 aes AES-CBC with plain64 initialization vectors
5309 luks Not documented
5311 Since
5313 2.10
5314 BlockdevQcow2Encryption (Object)
5316 Members
5317 format: BlockdevQcow2EncryptionFormat
5318 Not documented
5319 The members of QCryptoBlockOptionsQCow when format is "aes"
5321 The members of QCryptoBlockOptionsLUKS when format is "luks"
5323 Since
5325 2.10
5326 BlockdevOptionsPreallocate (Object)
5328 Filter driver intended to be inserted between format and protocol node
5329 and do preallocation in protocol node on write.
5330 Members
5332 prealloc-align: int (optional)
5333 on preallocation, align file length to this number, default
5334 1048576 (1M)
5335 prealloc-size: int (optional)
5337 how much to preallocate, default 134217728 (128M)
5338 The members of BlockdevOptionsGenericFormat
5340 Since
5342 6.0
5343 BlockdevOptionsQcow2 (Object)
5345 Driver specific block device options for qcow2.
5346 Members
5348 lazy-refcounts: boolean (optional)
5349 whether to enable the lazy refcounts feature (default is taken
5350 from the image file)
5351 pass-discard-request: boolean (optional)
5353 whether discard requests to the qcow2 device should be forwarded
5354 to the data source
5355 pass-discard-snapshot: boolean (optional)
5357 whether discard requests for the data source should be issued
5358 when a snapshot operation (e.g. deleting a snapshot) frees
5359 clusters in the qcow2 file
5360 pass-discard-other: boolean (optional)
5362 whether discard requests for the data source should be issued on
5363 other occasions where a cluster gets freed
5364 overlap-check: Qcow2OverlapChecks (optional)
5366 which overlap checks to perform for writes to the image, de‐
5367 faults to 'cached' (since 2.2)
5368 cache-size: int (optional)
5370 the maximum total size of the L2 table and refcount block caches
5371 in bytes (since 2.2)
5372 l2-cache-size: int (optional)
5374 the maximum size of the L2 table cache in bytes (since 2.2)
5375 l2-cache-entry-size: int (optional)
5377 the size of each entry in the L2 cache in bytes. It must be a
5378 power of two between 512 and the cluster size. The default value
5379 is the cluster size (since 2.12)
5380 refcount-cache-size: int (optional)
5382 the maximum size of the refcount block cache in bytes (since
5383 2.2)
5384 cache-clean-interval: int (optional)
5386 clean unused entries in the L2 and refcount caches. The interval
5387 is in seconds. The default value is 600 on supporting platforms,
5388 and 0 on other platforms. 0 disables this feature. (since 2.5)
5389 encrypt: BlockdevQcow2Encryption (optional)
5391 Image decryption options. Mandatory for encrypted images, except
5392 when doing a metadata-only probe of the image. (since 2.10)
5393 data-file: BlockdevRef (optional)
5395 reference to or definition of the external data file. This may
5396 only be specified for images that require an external data file.
5397 If it is not specified for such an image, the data file name is
5398 loaded from the image file. (since 4.0)
5399 The members of BlockdevOptionsGenericCOWFormat
5401 Since
5403 2.9
5404 SshHostKeyCheckMode (Enum)
5406 Values
5407 none Don't check the host key at all
5408 hash Compare the host key with a given hash
5410 known_hosts
5412 Check the host key against the known_hosts file
5413 Since
5415 2.12
5416 SshHostKeyCheckHashType (Enum)
5418 Values
5419 md5 The given hash is an md5 hash
5420 sha1 The given hash is an sha1 hash
5422 sha256 The given hash is an sha256 hash
5424 Since
5426 2.12
5427 SshHostKeyHash (Object)
5429 Members
5430 type: SshHostKeyCheckHashType
5431 The hash algorithm used for the hash
5432 hash: string
5434 The expected hash value
5435 Since
5437 2.12
5438 SshHostKeyCheck (Object)
5440 Members
5441 mode: SshHostKeyCheckMode
5442 Not documented
5443 The members of SshHostKeyHash when mode is "hash"
5445 Since
5447 2.12
5448 BlockdevOptionsSsh (Object)
5450 Members
5451 server: InetSocketAddress
5452 host address
5453 path: string
5455 path to the image on the host
5456 user: string (optional)
5458 user as which to connect, defaults to current local user name
5459 host-key-check: SshHostKeyCheck (optional)
5461 Defines how and what to check the host key against (default:
5462 known_hosts)
5463 Since
5465 2.9
5466 BlkdebugEvent (Enum)
5468 Trigger events supported by blkdebug.
5469 Values
5471 l1_shrink_write_table
5472 write zeros to the l1 table to shrink image. (since 2.11)
5473 l1_shrink_free_l2_clusters
5475 discard the l2 tables. (since 2.11)
5476 cor_write
5478 a write due to copy-on-read (since 2.11)
5479 cluster_alloc_space
5481 an allocation of file space for a cluster (since 4.1)
5482 none triggers once at creation of the blkdebug node (since 4.1)
5484 l1_update
5486 Not documented
5487 l1_grow_alloc_table
5489 Not documented
5490 l1_grow_write_table
5492 Not documented
5493 l1_grow_activate_table
5495 Not documented
5496 l2_load
5498 Not documented
5499 l2_update
5501 Not documented
5502 l2_update_compressed
5504 Not documented
5505 l2_alloc_cow_read
5507 Not documented
5508 l2_alloc_write
5510 Not documented
5511 read_aio
5513 Not documented
5514 read_backing_aio
5516 Not documented
5517 read_compressed
5519 Not documented
5520 write_aio
5522 Not documented
5523 write_compressed
5525 Not documented
5526 vmstate_load
5528 Not documented
5529 vmstate_save
5531 Not documented
5532 cow_read
5534 Not documented
5535 cow_write
5537 Not documented
5538 reftable_load
5540 Not documented
5541 reftable_grow
5543 Not documented
5544 reftable_update
5546 Not documented
5547 refblock_load
5549 Not documented
5550 refblock_update
5552 Not documented
5553 refblock_update_part
5555 Not documented
5556 refblock_alloc
5558 Not documented
5559 refblock_alloc_hookup
5561 Not documented
5562 refblock_alloc_write
5564 Not documented
5565 refblock_alloc_write_blocks
5567 Not documented
5568 refblock_alloc_write_table
5570 Not documented
5571 refblock_alloc_switch_table
5573 Not documented
5574 cluster_alloc
5576 Not documented
5577 cluster_alloc_bytes
5579 Not documented
5580 cluster_free
5582 Not documented
5583 flush_to_os
5585 Not documented
5586 flush_to_disk
5588 Not documented
5589 pwritev_rmw_head
5591 Not documented
5592 pwritev_rmw_after_head
5594 Not documented
5595 pwritev_rmw_tail
5597 Not documented
5598 pwritev_rmw_after_tail
5600 Not documented
5601 pwritev
5603 Not documented
5604 pwritev_zero
5606 Not documented
5607 pwritev_done
5609 Not documented
5610 empty_image_prepare
5612 Not documented
5613 Since
5615 2.9
5616 BlkdebugIOType (Enum)
5618 Kinds of I/O that blkdebug can inject errors in.
5619 Values
5621 read .bdrv_co_preadv()
5622 write .bdrv_co_pwritev()
5624 write-zeroes
5626 .bdrv_co_pwrite_zeroes()
5627 discard
5629 .bdrv_co_pdiscard()
5630 flush .bdrv_co_flush_to_disk()
5632 block-status
5634 .bdrv_co_block_status()
5635 Since
5637 4.1
5638 BlkdebugInjectErrorOptions (Object)
5640 Describes a single error injection for blkdebug.
5641 Members
5643 event: BlkdebugEvent
5644 trigger event
5645 state: int (optional)
5647 the state identifier blkdebug needs to be in to actually trigger
5648 the event; defaults to "any"
5649 iotype: BlkdebugIOType (optional)
5651 the type of I/O operations on which this error should be in‐
5652 jected; defaults to "all read, write, write-zeroes, discard, and
5653 flush operations" (since: 4.1)
5654 errno: int (optional)
5656 error identifier (errno) to be returned; defaults to EIO
5657 sector: int (optional)
5659 specifies the sector index which has to be affected in order to
5660 actually trigger the event; defaults to "any sector"
5661 once: boolean (optional)
5663 disables further events after this one has been triggered; de‐
5664 faults to false
5665 immediately: boolean (optional)
5667 fail immediately; defaults to false
5668 Since
5670 2.9
5671 BlkdebugSetStateOptions (Object)
5673 Describes a single state-change event for blkdebug.
5674 Members
5676 event: BlkdebugEvent
5677 trigger event
5678 state: int (optional)
5680 the current state identifier blkdebug needs to be in; defaults
5681 to "any"
5682 new_state: int
5684 the state identifier blkdebug is supposed to assume if this
5685 event is triggered
5686 Since
5688 2.9
5689 BlockdevOptionsBlkdebug (Object)
5691 Driver specific block device options for blkdebug.
5692 Members
5694 image: BlockdevRef
5695 underlying raw block device (or image file)
5696 config: string (optional)
5698 filename of the configuration file
5699 align: int (optional)
5701 required alignment for requests in bytes, must be positive power
5702 of 2, or 0 for default
5703 max-transfer: int (optional)
5705 maximum size for I/O transfers in bytes, must be positive multi‐
5706 ple of align and of the underlying file's request alignment (but
5707 need not be a power of 2), or 0 for default (since 2.10)
5708 opt-write-zero: int (optional)
5710 preferred alignment for write zero requests in bytes, must be
5711 positive multiple of align and of the underlying file's request
5712 alignment (but need not be a power of 2), or 0 for default
5713 (since 2.10)
5714 max-write-zero: int (optional)
5716 maximum size for write zero requests in bytes, must be positive
5717 multiple of align, of opt-write-zero, and of the underlying
5718 file's request alignment (but need not be a power of 2), or 0
5719 for default (since 2.10)
5720 opt-discard: int (optional)
5722 preferred alignment for discard requests in bytes, must be posi‐
5723 tive multiple of align and of the underlying file's request
5724 alignment (but need not be a power of 2), or 0 for default
5725 (since 2.10)
5726 max-discard: int (optional)
5728 maximum size for discard requests in bytes, must be positive
5729 multiple of align, of opt-discard, and of the underlying file's
5730 request alignment (but need not be a power of 2), or 0 for de‐
5731 fault (since 2.10)
5732 inject-error: array of BlkdebugInjectErrorOptions (optional)
5734 array of error injection descriptions
5735 set-state: array of BlkdebugSetStateOptions (optional)
5737 array of state-change descriptions
5738 take-child-perms: array of BlockPermission (optional)
5740 Permissions to take on image in addition to what is necessary
5741 anyway (which depends on how the blkdebug node is used). De‐
5742 faults to none. (since 5.0)
5743 unshare-child-perms: array of BlockPermission (optional)
5745 Permissions not to share on image in addition to what cannot be
5746 shared anyway (which depends on how the blkdebug node is used).
5747 Defaults to none. (since 5.0)
5748 Since
5750 2.9
5751 BlockdevOptionsBlklogwrites (Object)
5753 Driver specific block device options for blklogwrites.
5754 Members
5756 file: BlockdevRef
5757 block device
5758 log: BlockdevRef
5760 block device used to log writes to file
5761 log-sector-size: int (optional)
5763 sector size used in logging writes to file, determines granular‐
5764 ity of offsets and sizes of writes (default: 512)
5765 log-append: boolean (optional)
5767 append to an existing log (default: false)
5768 log-super-update-interval: int (optional)
5770 interval of write requests after which the log super block is
5771 updated to disk (default: 4096)
5772 Since
5774 3.0
5775 BlockdevOptionsBlkverify (Object)
5777 Driver specific block device options for blkverify.
5778 Members
5780 test: BlockdevRef
5781 block device to be tested
5782 raw: BlockdevRef
5784 raw image used for verification
5785 Since
5787 2.9
5788 BlockdevOptionsBlkreplay (Object)
5790 Driver specific block device options for blkreplay.
5791 Members
5793 image: BlockdevRef
5794 disk image which should be controlled with blkreplay
5795 Since
5797 4.2
5798 QuorumReadPattern (Enum)
5800 An enumeration of quorum read patterns.
5801 Values
5803 quorum read all the children and do a quorum vote on reads
5804 fifo read only from the first child that has not failed
5806 Since
5808 2.9
5809 BlockdevOptionsQuorum (Object)
5811 Driver specific block device options for Quorum
5812 Members
5814 blkverify: boolean (optional)
5815 true if the driver must print content mismatch
5817 set to false by default
5818 children: array of BlockdevRef
5820 the children block devices to use
5821 vote-threshold: int
5823 the vote limit under which a read will fail
5824 rewrite-corrupted: boolean (optional)
5826 rewrite corrupted data when quorum is reached (Since 2.1)
5827 read-pattern: QuorumReadPattern (optional)
5829 choose read pattern and set to quorum by default (Since 2.2)
5830 Since
5832 2.9
5833 BlockdevOptionsGluster (Object)
5835 Driver specific block device options for Gluster
5836 Members
5838 volume: string
5839 name of gluster volume where VM image resides
5840 path: string
5842 absolute path to image file in gluster volume
5843 server: array of SocketAddress
5845 gluster servers description
5846 debug: int (optional)
5848 libgfapi log level (default '4' which is Error) (Since 2.8)
5849 logfile: string (optional)
5851 libgfapi log file (default /dev/stderr) (Since 2.8)
5852 Since
5854 2.9
5855 BlockdevOptionsIoUring (Object)
5857 Driver specific block device options for the io_uring backend.
5858 Members
5860 filename: string
5861 path to the image file
5862 Since
5864 7.2
5865 If
5867 CONFIG_BLKIO
5868 BlockdevOptionsNvmeIoUring (Object)
5870 Driver specific block device options for the nvme-io_uring backend.
5871 Members
5873 path: string
5874 path to the NVMe namespace's character device (e.g. /dev/ng0n1).
5875 Since
5877 7.2
5878 If
5880 CONFIG_BLKIO
5881 BlockdevOptionsVirtioBlkVfioPci (Object)
5883 Driver specific block device options for the virtio-blk-vfio-pci back‐
5884 end.
5885 Members
5887 path: string
5888 path to the PCI device's sysfs directory (e.g. /sys/bus/pci/de‐
5889 vices/0000:00:01.0).
5890 Since
5892 7.2
5893 If
5895 CONFIG_BLKIO
5896 BlockdevOptionsVirtioBlkVhostUser (Object)
5898 Driver specific block device options for the virtio-blk-vhost-user
5899 backend.
5900 Members
5902 path: string
5903 path to the vhost-user UNIX domain socket.
5904 Since
5906 7.2
5907 If
5909 CONFIG_BLKIO
5910 BlockdevOptionsVirtioBlkVhostVdpa (Object)
5912 Driver specific block device options for the virtio-blk-vhost-vdpa
5913 backend.
5914 Members
5916 path: string
5917 path to the vhost-vdpa character device.
5918 Since
5920 7.2
5921 If
5923 CONFIG_BLKIO
5924 IscsiTransport (Enum)
5926 An enumeration of libiscsi transport types
5927 Values
5929 tcp Not documented
5930 iser Not documented
5932 Since
5934 2.9
5935 IscsiHeaderDigest (Enum)
5937 An enumeration of header digests supported by libiscsi
5938 Values
5940 crc32c Not documented
5941 none Not documented
5943 crc32c-none
5945 Not documented
5946 none-crc32c
5948 Not documented
5949 Since
5951 2.9
5952 BlockdevOptionsIscsi (Object)
5954 Members
5955 transport: IscsiTransport
5956 The iscsi transport type
5957 portal: string
5959 The address of the iscsi portal
5960 target: string
5962 The target iqn name
5963 lun: int (optional)
5965 LUN to connect to. Defaults to 0.
5966 user: string (optional)
5968 User name to log in with. If omitted, no CHAP authentication is
5969 performed.
5970 password-secret: string (optional)
5972 The ID of a QCryptoSecret object providing the password for the
5973 login. This option is required if user is specified.
5974 initiator-name: string (optional)
5976 The iqn name we want to identify to the target as. If this op‐
5977 tion is not specified, an initiator name is generated automati‐
5978 cally.
5979 header-digest: IscsiHeaderDigest (optional)
5981 The desired header digest. Defaults to none-crc32c.
5982 timeout: int (optional)
5984 Timeout in seconds after which a request will timeout. 0 means
5985 no timeout and is the default.
5986 Driver specific block device options for iscsi
5987 Since
5989 2.9
5990 RbdAuthMode (Enum)
5992 Values
5993 cephx Not documented
5994 none Not documented
5996 Since
5998 3.0
5999 RbdImageEncryptionFormat (Enum)
6001 Values
6002 luks Not documented
6003 luks2 Not documented
6005 Since
6007 6.1
6008 RbdEncryptionOptionsLUKSBase (Object)
6010 Members
6011 key-secret: string
6012 ID of a QCryptoSecret object providing a passphrase for unlock‐
6013 ing the encryption
6014 Since
6016 6.1
6017 RbdEncryptionCreateOptionsLUKSBase (Object)
6019 Members
6020 cipher-alg: QCryptoCipherAlgorithm (optional)
6021 The encryption algorithm
6022 The members of RbdEncryptionOptionsLUKSBase
6024 Since
6026 6.1
6027 RbdEncryptionOptionsLUKS (Object)
6029 Members
6030 The members of RbdEncryptionOptionsLUKSBase
6031 Since
6033 6.1
6034 RbdEncryptionOptionsLUKS2 (Object)
6036 Members
6037 The members of RbdEncryptionOptionsLUKSBase
6038 Since
6040 6.1
6041 RbdEncryptionCreateOptionsLUKS (Object)
6043 Members
6044 The members of RbdEncryptionCreateOptionsLUKSBase
6045 Since
6047 6.1
6048 RbdEncryptionCreateOptionsLUKS2 (Object)
6050 Members
6051 The members of RbdEncryptionCreateOptionsLUKSBase
6052 Since
6054 6.1
6055 RbdEncryptionOptions (Object)
6057 Members
6058 format: RbdImageEncryptionFormat
6059 Not documented
6060 The members of RbdEncryptionOptionsLUKS when format is "luks"
6062 The members of RbdEncryptionOptionsLUKS2 when format is "luks2"
6064 Since
6066 6.1
6067 RbdEncryptionCreateOptions (Object)
6069 Members
6070 format: RbdImageEncryptionFormat
6071 Not documented
6072 The members of RbdEncryptionCreateOptionsLUKS when format is "luks"
6074 The members of RbdEncryptionCreateOptionsLUKS2 when format is "luks2"
6076 Since
6078 6.1
6079 BlockdevOptionsRbd (Object)
6081 Members
6082 pool: string
6083 Ceph pool name.
6084 namespace: string (optional)
6086 Rados namespace name in the Ceph pool. (Since 5.0)
6087 image: string
6089 Image name in the Ceph pool.
6090 conf: string (optional)
6092 path to Ceph configuration file. Values in the configuration
6093 file will be overridden by options specified via QAPI.
6094 snapshot: string (optional)
6096 Ceph snapshot name.
6097 encrypt: RbdEncryptionOptions (optional)
6099 Image encryption options. (Since 6.1)
6100 user: string (optional)
6102 Ceph id name.
6103 auth-client-required: array of RbdAuthMode (optional)
6105 Acceptable authentication modes. This maps to Ceph configura‐
6106 tion option "auth_client_required". (Since 3.0)
6107 key-secret: string (optional)
6109 ID of a QCryptoSecret object providing a key for cephx authenti‐
6110 cation. This maps to Ceph configuration option "key". (Since
6111 3.0)
6112 server: array of InetSocketAddressBase (optional)
6114 Monitor host address and port. This maps to the "mon_host" Ceph
6115 option.
6116 Since
6118 2.9
6119 ReplicationMode (Enum)
6121 An enumeration of replication modes.
6122 Values
6124 primary
6125 Primary mode, the vm's state will be sent to secondary QEMU.
6126 secondary
6128 Secondary mode, receive the vm's state from primary QEMU.
6129 Since
6131 2.9
6132 If
6134 CONFIG_REPLICATION
6135 BlockdevOptionsReplication (Object)
6137 Driver specific block device options for replication
6138 Members
6140 mode: ReplicationMode
6141 the replication mode
6142 top-id: string (optional)
6144 In secondary mode, node name or device ID of the root node who
6145 owns the replication node chain. Must not be given in primary
6146 mode.
6147 The members of BlockdevOptionsGenericFormat
6149 Since
6151 2.9
6152 If
6154 CONFIG_REPLICATION
6155 NFSTransport (Enum)
6157 An enumeration of NFS transport types
6158 Values
6160 inet TCP transport
6161 Since
6163 2.9
6164 NFSServer (Object)
6166 Captures the address of the socket
6167 Members
6169 type: NFSTransport
6170 transport type used for NFS (only TCP supported)
6171 host: string
6173 host address for NFS server
6174 Since
6176 2.9
6177 BlockdevOptionsNfs (Object)
6179 Driver specific block device option for NFS
6180 Members
6182 server: NFSServer
6183 host address
6184 path: string
6186 path of the image on the host
6187 user: int (optional)
6189 UID value to use when talking to the server (defaults to 65534
6190 on Windows and getuid() on unix)
6191 group: int (optional)
6193 GID value to use when talking to the server (defaults to 65534
6194 on Windows and getgid() in unix)
6195 tcp-syn-count: int (optional)
6197 number of SYNs during the session establishment (defaults to
6198 libnfs default)
6199 readahead-size: int (optional)
6201 set the readahead size in bytes (defaults to libnfs default)
6202 page-cache-size: int (optional)
6204 set the pagecache size in bytes (defaults to libnfs default)
6205 debug: int (optional)
6207 set the NFS debug level (max 2) (defaults to libnfs default)
6208 Since
6210 2.9
6211 BlockdevOptionsCurlBase (Object)
6213 Driver specific block device options shared by all protocols supported
6214 by the curl backend.
6215 Members
6217 url: string
6218 URL of the image file
6219 readahead: int (optional)
6221 Size of the read-ahead cache; must be a multiple of 512 (de‐
6222 faults to 256 kB)
6223 timeout: int (optional)
6225 Timeout for connections, in seconds (defaults to 5)
6226 username: string (optional)
6228 Username for authentication (defaults to none)
6229 password-secret: string (optional)
6231 ID of a QCryptoSecret object providing a password for authenti‐
6232 cation (defaults to no password)
6233 proxy-username: string (optional)
6235 Username for proxy authentication (defaults to none)
6236 proxy-password-secret: string (optional)
6238 ID of a QCryptoSecret object providing a password for proxy au‐
6239 thentication (defaults to no password)
6240 Since
6242 2.9
6243 BlockdevOptionsCurlHttp (Object)
6245 Driver specific block device options for HTTP connections over the curl
6246 backend. URLs must start with "http://".
6247 Members
6249 cookie: string (optional)
6250 List of cookies to set; format is "name1=content1; name2=con‐
6251 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
6252 ies.
6253 cookie-secret: string (optional)
6255 ID of a QCryptoSecret object providing the cookie data in a se‐
6256 cure way. See cookie for the format. (since 2.10)
6257 The members of BlockdevOptionsCurlBase
6259 Since
6261 2.9
6262 BlockdevOptionsCurlHttps (Object)
6264 Driver specific block device options for HTTPS connections over the
6265 curl backend. URLs must start with "https://".
6266 Members
6268 cookie: string (optional)
6269 List of cookies to set; format is "name1=content1; name2=con‐
6270 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
6271 ies.
6272 sslverify: boolean (optional)
6274 Whether to verify the SSL certificate's validity (defaults to
6275 true)
6276 cookie-secret: string (optional)
6278 ID of a QCryptoSecret object providing the cookie data in a se‐
6279 cure way. See cookie for the format. (since 2.10)
6280 The members of BlockdevOptionsCurlBase
6282 Since
6284 2.9
6285 BlockdevOptionsCurlFtp (Object)
6287 Driver specific block device options for FTP connections over the curl
6288 backend. URLs must start with "ftp://".
6289 Members
6291 The members of BlockdevOptionsCurlBase
6292 Since
6294 2.9
6295 BlockdevOptionsCurlFtps (Object)
6297 Driver specific block device options for FTPS connections over the curl
6298 backend. URLs must start with "ftps://".
6299 Members
6301 sslverify: boolean (optional)
6302 Whether to verify the SSL certificate's validity (defaults to
6303 true)
6304 The members of BlockdevOptionsCurlBase
6306 Since
6308 2.9
6309 BlockdevOptionsNbd (Object)
6311 Driver specific block device options for NBD.
6312 Members
6314 server: SocketAddress
6315 NBD server address
6316 export: string (optional)
6318 export name
6319 tls-creds: string (optional)
6321 TLS credentials ID
6322 tls-hostname: string (optional)
6324 TLS hostname override for certificate validation (Since 7.0)
6325 x-dirty-bitmap: string (optional)
6327 A metadata context name such as "qemu:dirty-bitmap:NAME" or
6328 "qemu:allocation-depth" to query in place of the traditional
6329 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
6330 the NBD protocol; and yes, naming this option x-context would
6331 have made more sense) (since 3.0)
6332 reconnect-delay: int (optional)
6334 On an unexpected disconnect, the nbd client tries to connect
6335 again until succeeding or encountering a serious error. During
6336 the first reconnect-delay seconds, all requests are paused and
6337 will be rerun on a successful reconnect. After that time, any
6338 delayed requests and all future requests before a successful re‐
6339 connect will immediately fail. Default 0 (Since 4.2)
6340 open-timeout: int (optional)
6342 In seconds. If zero, the nbd driver tries the connection only
6343 once, and fails to open if the connection fails. If non-zero,
6344 the nbd driver will repeat connection attempts until successful
6345 or until open-timeout seconds have elapsed. Default 0 (Since
6346 7.0)
6347 Features
6349 unstable
6350 Member x-dirty-bitmap is experimental.
6351 Since
6353 2.9
6354 BlockdevOptionsRaw (Object)
6356 Driver specific block device options for the raw driver.
6357 Members
6359 offset: int (optional)
6360 position where the block device starts
6361 size: int (optional)
6363 the assumed size of the device
6364 The members of BlockdevOptionsGenericFormat
6366 Since
6368 2.9
6369 BlockdevOptionsThrottle (Object)
6371 Driver specific block device options for the throttle driver
6372 Members
6374 throttle-group: string
6375 the name of the throttle-group object to use. It must already
6376 exist.
6377 file: BlockdevRef
6379 reference to or definition of the data source block device
6380 Since
6382 2.11
6383 BlockdevOptionsCor (Object)
6385 Driver specific block device options for the copy-on-read driver.
6386 Members
6388 bottom: string (optional)
6389 The name of a non-filter node (allocation-bearing layer) that
6390 limits the COR operations in the backing chain (inclusive), so
6391 that no data below this node will be copied by this filter. If
6392 option is absent, the limit is not applied, so that data from
6393 all backing layers may be copied.
6394 The members of BlockdevOptionsGenericFormat
6396 Since
6398 6.0
6399 OnCbwError (Enum)
6401 An enumeration of possible behaviors for copy-before-write operation
6402 failures.
6403 Values
6405 break-guest-write
6406 report the error to the guest. This way, the guest will not be
6407 able to overwrite areas that cannot be backed up, so the backup
6408 process remains valid.
6409 break-snapshot
6411 continue guest write. Doing so will make the provided snapshot
6412 state invalid and any backup or export process based on it will
6413 finally fail.
6414 Since
6416 7.1
6417 BlockdevOptionsCbw (Object)
6419 Driver specific block device options for the copy-before-write driver,
6420 which does so called copy-before-write operations: when data is written
6421 to the filter, the filter first reads corresponding blocks from its
6422 file child and copies them to target child. After successfully copying,
6423 the write request is propagated to file child. If copying fails, the
6424 original write request is failed too and no data is written to file
6425 child.
6426 Members
6428 target: BlockdevRef
6429 The target for copy-before-write operations.
6430 bitmap: BlockDirtyBitmap (optional)
6432 If specified, copy-before-write filter will do copy-before-write
6433 operations only for dirty regions of the bitmap. Bitmap size
6434 must be equal to length of file and target child of the filter.
6435 Note also, that bitmap is used only to initialize internal bit‐
6436 map of the process, so further modifications (or removing) of
6437 specified bitmap doesn't influence the filter. (Since 7.0)
6438 on-cbw-error: OnCbwError (optional)
6440 Behavior on failure of copy-before-write operation. Default is
6441 break-guest-write. (Since 7.1)
6442 cbw-timeout: int (optional)
6444 Zero means no limit. Non-zero sets the timeout in seconds for
6445 copy-before-write operation. When a timeout occurs, the respec‐
6446 tive copy-before-write operation will fail, and the on-cbw-error
6447 parameter will decide how this failure is handled. Default 0.
6448 (Since 7.1)
6449 The members of BlockdevOptionsGenericFormat
6451 Since
6453 6.2
6454 BlockdevOptions (Object)
6456 Options for creating a block device. Many options are available for
6457 all block devices, independent of the block driver:
6458 Members
6460 driver: BlockdevDriver
6461 block driver name
6462 node-name: string (optional)
6464 the node name of the new node (Since 2.0). This option is re‐
6465 quired on the top level of blockdev-add. Valid node names start
6466 with an alphabetic character and may contain only alphanumeric
6467 characters, '-', '.' and '_'. Their maximum length is 31 charac‐
6468 ters.
6469 discard: BlockdevDiscardOptions (optional)
6471 discard-related options (default: ignore)
6472 cache: BlockdevCacheOptions (optional)
6474 cache-related options
6475 read-only: boolean (optional)
6477 whether the block device should be read-only (default: false).
6478 Note that some block drivers support only read-only access, ei‐
6479 ther generally or in certain configurations. In this case, the
6480 default value does not work and the option must be specified ex‐
6481 plicitly.
6482 auto-read-only: boolean (optional)
6484 if true and read-only is false, QEMU may automatically decide
6485 not to open the image read-write as requested, but fall back to
6486 read-only instead (and switch between the modes later), e.g. de‐
6487 pending on whether the image file is writable or whether a writ‐
6488 ing user is attached to the node (default: false, since 3.1)
6489 detect-zeroes: BlockdevDetectZeroesOptions (optional)
6491 detect and optimize zero writes (Since 2.1) (default: off)
6492 force-share: boolean (optional)
6494 force share all permission on added nodes. Requires
6495 read-only=true. (Since 2.10)
6496 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
6498 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
6500 writes"
6501 The members of BlockdevOptionsBlkverify when driver is "blkverify"
6503 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
6505 The members of BlockdevOptionsGenericFormat when driver is "bochs"
6507 The members of BlockdevOptionsGenericFormat when driver is "cloop"
6509 The members of BlockdevOptionsGenericFormat when driver is "compress"
6511 The members of BlockdevOptionsCbw when driver is "copy-before-write"
6513 The members of BlockdevOptionsCor when driver is "copy-on-read"
6515 The members of BlockdevOptionsGenericFormat when driver is "dmg"
6517 The members of BlockdevOptionsFile when driver is "file"
6519 The members of BlockdevOptionsCurlFtp when driver is "ftp"
6521 The members of BlockdevOptionsCurlFtps when driver is "ftps"
6523 The members of BlockdevOptionsGluster when driver is "gluster"
6525 The members of BlockdevOptionsFile when driver is "host_cdrom" (If:
6527 HAVE_HOST_BLOCK_DEVICE)
6528 The members of BlockdevOptionsFile when driver is "host_device" (If:
6530 HAVE_HOST_BLOCK_DEVICE)
6531 The members of BlockdevOptionsCurlHttp when driver is "http"
6533 The members of BlockdevOptionsCurlHttps when driver is "https"
6535 The members of BlockdevOptionsIoUring when driver is "io_uring" (If:
6537 CONFIG_BLKIO)
6538 The members of BlockdevOptionsIscsi when driver is "iscsi"
6540 The members of BlockdevOptionsLUKS when driver is "luks"
6542 The members of BlockdevOptionsNbd when driver is "nbd"
6544 The members of BlockdevOptionsNfs when driver is "nfs"
6546 The members of BlockdevOptionsNull when driver is "null-aio"
6548 The members of BlockdevOptionsNull when driver is "null-co"
6550 The members of BlockdevOptionsNVMe when driver is "nvme"
6552 The members of BlockdevOptionsNvmeIoUring when driver is "nvme-io_ur‐
6554 ing" (If: CONFIG_BLKIO)
6555 The members of BlockdevOptionsGenericFormat when driver is "parallels"
6557 The members of BlockdevOptionsPreallocate when driver is "preallocate"
6559 The members of BlockdevOptionsQcow2 when driver is "qcow2"
6561 The members of BlockdevOptionsQcow when driver is "qcow"
6563 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
6565 The members of BlockdevOptionsQuorum when driver is "quorum"
6567 The members of BlockdevOptionsRaw when driver is "raw"
6569 The members of BlockdevOptionsRbd when driver is "rbd"
6571 The members of BlockdevOptionsReplication when driver is "replication"
6573 (If: CONFIG_REPLICATION)
6574 The members of BlockdevOptionsGenericFormat when driver is "snap‐
6576 shot-access"
6577 The members of BlockdevOptionsSsh when driver is "ssh"
6579 The members of BlockdevOptionsThrottle when driver is "throttle"
6581 The members of BlockdevOptionsGenericFormat when driver is "vdi"
6583 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
6585 The members of BlockdevOptionsVirtioBlkVfioPci when driver is "vir‐
6587 tio-blk-vfio-pci" (If: CONFIG_BLKIO)
6588 The members of BlockdevOptionsVirtioBlkVhostUser when driver is "vir‐
6590 tio-blk-vhost-user" (If: CONFIG_BLKIO)
6591 The members of BlockdevOptionsVirtioBlkVhostVdpa when driver is "vir‐
6593 tio-blk-vhost-vdpa" (If: CONFIG_BLKIO)
6594 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
6596 The members of BlockdevOptionsGenericFormat when driver is "vpc"
6598 The members of BlockdevOptionsVVFAT when driver is "vvfat"
6600 Remaining options are determined by the block driver.
6601 Since
6603 2.9
6604 BlockdevRef (Alternate)
6606 Reference to a block device.
6607 Members
6609 definition: BlockdevOptions
6610 defines a new block device inline
6611 reference: string
6613 references the ID of an existing block device
6614 Since
6616 2.9
6617 BlockdevRefOrNull (Alternate)
6619 Reference to a block device.
6620 Members
6622 definition: BlockdevOptions
6623 defines a new block device inline
6624 reference: string
6626 references the ID of an existing block device. An empty string
6627 means that no block device should be referenced. Deprecated;
6628 use null instead.
6629 null: null
6631 No block device should be referenced (since 2.10)
6632 Since
6634 2.9
6635 blockdev-add (Command)
6637 Creates a new block device.
6638 Arguments
6640 The members of BlockdevOptions
6641 Since
6643 2.9
6644 Example
6646 1.
6647 -> { "execute": "blockdev-add",
6648 "arguments": {
6649 "driver": "qcow2",
6650 "node-name": "test1",
6651 "file": {
6652 "driver": "file",
6653 "filename": "test.qcow2"
6654 }
6655 }
6656 }
6657 <- { "return": {} }
6658 2.
6660 -> { "execute": "blockdev-add",
6661 "arguments": {
6662 "driver": "qcow2",
6663 "node-name": "node0",
6664 "discard": "unmap",
6665 "cache": {
6666 "direct": true
6667 },
6668 "file": {
6669 "driver": "file",
6670 "filename": "/tmp/test.qcow2"
6671 },
6672 "backing": {
6673 "driver": "raw",
6674 "file": {
6675 "driver": "file",
6676 "filename": "/dev/fdset/4"
6677 }
6678 }
6679 }
6680 }
6681 <- { "return": {} }
6683 blockdev-reopen (Command)
6685 Reopens one or more block devices using the given set of options. Any
6686 option not specified will be reset to its default value regardless of
6687 its previous status. If an option cannot be changed or a particular
6688 driver does not support reopening then the command will return an er‐
6689 ror. All devices in the list are reopened in one transaction, so if one
6690 of them fails then the whole transaction is cancelled.
6691 The command receives a list of block devices to reopen. For each one of
6693 them, the top-level node-name option (from BlockdevOptions) must be
6694 specified and is used to select the block device to be reopened. Other
6695 node-name options must be either omitted or set to the current name of
6696 the appropriate node. This command won't change any node name and any
6697 attempt to do it will result in an error.
6698 In the case of options that refer to child nodes, the behavior of this
6700 command depends on the value:
6701 1. A set of options (BlockdevOptions): the child is reopened with
6703 the specified set of options.
6704 2. A reference to the current child: the child is reopened using its
6706 existing set of options.
6707 3. A reference to a different node: the current child is replaced
6709 with the specified one.
6710 4. NULL: the current child (if any) is detached.
6712 Options (1) and (2) are supported in all cases. Option (3) is supported
6714 for file and backing, and option (4) for backing only.
6715 Unlike with blockdev-add, the backing option must always be present un‐
6717 less the node being reopened does not have a backing file and its image
6718 does not have a default backing file name as part of its metadata.
6719 Arguments
6721 options: array of BlockdevOptions
6722 Not documented
6723 Since
6725 6.1
6726 blockdev-del (Command)
6728 Deletes a block device that has been added using blockdev-add. The
6729 command will fail if the node is attached to a device or is otherwise
6730 being used.
6731 Arguments
6733 node-name: string
6734 Name of the graph node to delete.
6735 Since
6737 2.9
6738 Example
6740 -> { "execute": "blockdev-add",
6741 "arguments": {
6742 "driver": "qcow2",
6743 "node-name": "node0",
6744 "file": {
6745 "driver": "file",
6746 "filename": "test.qcow2"
6747 }
6748 }
6749 }
6750 <- { "return": {} }
6751 -> { "execute": "blockdev-del",
6753 "arguments": { "node-name": "node0" }
6754 }
6755 <- { "return": {} }
6756 BlockdevCreateOptionsFile (Object)
6758 Driver specific image creation options for file.
6759 Members
6761 filename: string
6762 Filename for the new image file
6763 size: int
6765 Size of the virtual disk in bytes
6766 preallocation: PreallocMode (optional)
6768 Preallocation mode for the new image (default: off; allowed val‐
6769 ues: off, falloc (if CONFIG_POSIX_FALLOCATE), full (if CON‐
6770 FIG_POSIX))
6771 nocow: boolean (optional)
6773 Turn off copy-on-write (valid only on btrfs; default: off)
6774 extent-size-hint: int (optional)
6776 Extent size hint to add to the image file; 0 for not adding an
6777 extent size hint (default: 1 MB, since 5.1)
6778 Since
6780 2.12
6781 BlockdevCreateOptionsGluster (Object)
6783 Driver specific image creation options for gluster.
6784 Members
6786 location: BlockdevOptionsGluster
6787 Where to store the new image file
6788 size: int
6790 Size of the virtual disk in bytes
6791 preallocation: PreallocMode (optional)
6793 Preallocation mode for the new image (default: off; allowed val‐
6794 ues: off, falloc (if CONFIG_GLUSTERFS_FALLOCATE), full (if CON‐
6795 FIG_GLUSTERFS_ZEROFILL))
6796 Since
6798 2.12
6799 BlockdevCreateOptionsLUKS (Object)
6801 Driver specific image creation options for LUKS.
6802 Members
6804 file: BlockdevRef
6805 Node to create the image format on
6806 size: int
6808 Size of the virtual disk in bytes
6809 preallocation: PreallocMode (optional)
6811 Preallocation mode for the new image (since: 4.2) (default: off;
6812 allowed values: off, metadata, falloc, full)
6813 The members of QCryptoBlockCreateOptionsLUKS
6815 Since
6817 2.12
6818 BlockdevCreateOptionsNfs (Object)
6820 Driver specific image creation options for NFS.
6821 Members
6823 location: BlockdevOptionsNfs
6824 Where to store the new image file
6825 size: int
6827 Size of the virtual disk in bytes
6828 Since
6830 2.12
6831 BlockdevCreateOptionsParallels (Object)
6833 Driver specific image creation options for parallels.
6834 Members
6836 file: BlockdevRef
6837 Node to create the image format on
6838 size: int
6840 Size of the virtual disk in bytes
6841 cluster-size: int (optional)
6843 Cluster size in bytes (default: 1 MB)
6844 Since
6846 2.12
6847 BlockdevCreateOptionsQcow (Object)
6849 Driver specific image creation options for qcow.
6850 Members
6852 file: BlockdevRef
6853 Node to create the image format on
6854 size: int
6856 Size of the virtual disk in bytes
6857 backing-file: string (optional)
6859 File name of the backing file if a backing file should be used
6860 encrypt: QCryptoBlockCreateOptions (optional)
6862 Encryption options if the image should be encrypted
6863 Since
6865 2.12
6866 BlockdevQcow2Version (Enum)
6868 Values
6869 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
6870 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
6872 Since
6874 2.12
6875 Qcow2CompressionType (Enum)
6877 Compression type used in qcow2 image file
6878 Values
6880 zlib zlib compression, see <http://zlib.net/>
6881 zstd (If: CONFIG_ZSTD)
6883 zstd compression, see <http://github.com/facebook/zstd>
6884 Since
6886 5.1
6887 BlockdevCreateOptionsQcow2 (Object)
6889 Driver specific image creation options for qcow2.
6890 Members
6892 file: BlockdevRef
6893 Node to create the image format on
6894 data-file: BlockdevRef (optional)
6896 Node to use as an external data file in which all guest data is
6897 stored so that only metadata remains in the qcow2 file (since:
6898 4.0)
6899 data-file-raw: boolean (optional)
6901 True if the external data file must stay valid as a standalone
6902 (read-only) raw image without looking at qcow2 metadata (de‐
6903 fault: false; since: 4.0)
6904 extended-l2: boolean (optional)
6906 True to make the image have extended L2 entries (default: false;
6907 since 5.2)
6908 size: int
6910 Size of the virtual disk in bytes
6911 version: BlockdevQcow2Version (optional)
6913 Compatibility level (default: v3)
6914 backing-file: string (optional)
6916 File name of the backing file if a backing file should be used
6917 backing-fmt: BlockdevDriver (optional)
6919 Name of the block driver to use for the backing file
6920 encrypt: QCryptoBlockCreateOptions (optional)
6922 Encryption options if the image should be encrypted
6923 cluster-size: int (optional)
6925 qcow2 cluster size in bytes (default: 65536)
6926 preallocation: PreallocMode (optional)
6928 Preallocation mode for the new image (default: off; allowed val‐
6929 ues: off, falloc, full, metadata)
6930 lazy-refcounts: boolean (optional)
6932 True if refcounts may be updated lazily (default: off)
6933 refcount-bits: int (optional)
6935 Width of reference counts in bits (default: 16)
6936 compression-type: Qcow2CompressionType (optional)
6938 The image cluster compression method (default: zlib, since 5.1)
6939 Since
6941 2.12
6942 BlockdevCreateOptionsQed (Object)
6944 Driver specific image creation options for qed.
6945 Members
6947 file: BlockdevRef
6948 Node to create the image format on
6949 size: int
6951 Size of the virtual disk in bytes
6952 backing-file: string (optional)
6954 File name of the backing file if a backing file should be used
6955 backing-fmt: BlockdevDriver (optional)
6957 Name of the block driver to use for the backing file
6958 cluster-size: int (optional)
6960 Cluster size in bytes (default: 65536)
6961 table-size: int (optional)
6963 L1/L2 table size (in clusters)
6964 Since
6966 2.12
6967 BlockdevCreateOptionsRbd (Object)
6969 Driver specific image creation options for rbd/Ceph.
6970 Members
6972 location: BlockdevOptionsRbd
6973 Where to store the new image file. This location cannot point to
6974 a snapshot.
6975 size: int
6977 Size of the virtual disk in bytes
6978 cluster-size: int (optional)
6980 RBD object size
6981 encrypt: RbdEncryptionCreateOptions (optional)
6983 Image encryption options. (Since 6.1)
6984 Since
6986 2.12
6987 BlockdevVmdkSubformat (Enum)
6989 Subformat options for VMDK images
6990 Values
6992 monolithicSparse
6993 Single file image with sparse cluster allocation
6994 monolithicFlat
6996 Single flat data image and a descriptor file
6997 twoGbMaxExtentSparse
6999 Data is split into 2GB (per virtual LBA) sparse extent files, in
7000 addition to a descriptor file
7001 twoGbMaxExtentFlat
7003 Data is split into 2GB (per virtual LBA) flat extent files, in
7004 addition to a descriptor file
7005 streamOptimized
7007 Single file image sparse cluster allocation, optimized for
7008 streaming over network.
7009 Since
7011 4.0
7012 BlockdevVmdkAdapterType (Enum)
7014 Adapter type info for VMDK images
7015 Values
7017 ide Not documented
7018 buslogic
7020 Not documented
7021 lsilogic
7023 Not documented
7024 legacyESX
7026 Not documented
7027 Since
7029 4.0
7030 BlockdevCreateOptionsVmdk (Object)
7032 Driver specific image creation options for VMDK.
7033 Members
7035 file: BlockdevRef
7036 Where to store the new image file. This refers to the image file
7037 for monolithcSparse and streamOptimized format, or the descrip‐
7038 tor file for other formats.
7039 size: int
7041 Size of the virtual disk in bytes
7042 extents: array of BlockdevRef (optional)
7044 Where to store the data extents. Required for monolithcFlat,
7045 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For mono‐
7046 lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
7047 mats, the number of entries required is calculated as ex‐
7048 tent_number = virtual_size / 2GB. Providing more extents than
7049 will be used is an error.
7050 subformat: BlockdevVmdkSubformat (optional)
7052 The subformat of the VMDK image. Default: "monolithicSparse".
7053 backing-file: string (optional)
7055 The path of backing file. Default: no backing file is used.
7056 adapter-type: BlockdevVmdkAdapterType (optional)
7058 The adapter type used to fill in the descriptor. Default: ide.
7059 hwversion: string (optional)
7061 Hardware version. The meaningful options are "4" or "6". De‐
7062 fault: "4".
7063 toolsversion: string (optional)
7065 VMware guest tools version. Default: "2147483647" (Since 6.2)
7066 zeroed-grain: boolean (optional)
7068 Whether to enable zeroed-grain feature for sparse subformats.
7069 Default: false.
7070 Since
7072 4.0
7073 BlockdevCreateOptionsSsh (Object)
7075 Driver specific image creation options for SSH.
7076 Members
7078 location: BlockdevOptionsSsh
7079 Where to store the new image file
7080 size: int
7082 Size of the virtual disk in bytes
7083 Since
7085 2.12
7086 BlockdevCreateOptionsVdi (Object)
7088 Driver specific image creation options for VDI.
7089 Members
7091 file: BlockdevRef
7092 Node to create the image format on
7093 size: int
7095 Size of the virtual disk in bytes
7096 preallocation: PreallocMode (optional)
7098 Preallocation mode for the new image (default: off; allowed val‐
7099 ues: off, metadata)
7100 Since
7102 2.12
7103 BlockdevVhdxSubformat (Enum)
7105 Values
7106 dynamic
7107 Growing image file
7108 fixed Preallocated fixed-size image file
7110 Since
7112 2.12
7113 BlockdevCreateOptionsVhdx (Object)
7115 Driver specific image creation options for vhdx.
7116 Members
7118 file: BlockdevRef
7119 Node to create the image format on
7120 size: int
7122 Size of the virtual disk in bytes
7123 log-size: int (optional)
7125 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
7126 block-size: int (optional)
7128 Block size in bytes, must be a multiple of 1 MB and not larger
7129 than 256 MB (default: automatically choose a block size depend‐
7130 ing on the image size)
7131 subformat: BlockdevVhdxSubformat (optional)
7133 vhdx subformat (default: dynamic)
7134 block-state-zero: boolean (optional)
7136 Force use of payload blocks of type 'ZERO'. Non-standard, but
7137 default. Do not set to 'off' when using 'qemu-img convert' with
7138 subformat=dynamic.
7139 Since
7141 2.12
7142 BlockdevVpcSubformat (Enum)
7144 Values
7145 dynamic
7146 Growing image file
7147 fixed Preallocated fixed-size image file
7149 Since
7151 2.12
7152 BlockdevCreateOptionsVpc (Object)
7154 Driver specific image creation options for vpc (VHD).
7155 Members
7157 file: BlockdevRef
7158 Node to create the image format on
7159 size: int
7161 Size of the virtual disk in bytes
7162 subformat: BlockdevVpcSubformat (optional)
7164 vhdx subformat (default: dynamic)
7165 force-size: boolean (optional)
7167 Force use of the exact byte size instead of rounding to the next
7168 size that can be represented in CHS geometry (default: false)
7169 Since
7171 2.12
7172 BlockdevCreateOptions (Object)
7174 Options for creating an image format on a given node.
7175 Members
7177 driver: BlockdevDriver
7178 block driver to create the image format
7179 The members of BlockdevCreateOptionsFile when driver is "file"
7181 The members of BlockdevCreateOptionsGluster when driver is "gluster"
7183 The members of BlockdevCreateOptionsLUKS when driver is "luks"
7185 The members of BlockdevCreateOptionsNfs when driver is "nfs"
7187 The members of BlockdevCreateOptionsParallels when driver is "paral‐
7189 lels"
7190 The members of BlockdevCreateOptionsQcow when driver is "qcow"
7192 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
7194 The members of BlockdevCreateOptionsQed when driver is "qed"
7196 The members of BlockdevCreateOptionsRbd when driver is "rbd"
7198 The members of BlockdevCreateOptionsSsh when driver is "ssh"
7200 The members of BlockdevCreateOptionsVdi when driver is "vdi"
7202 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
7204 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
7206 The members of BlockdevCreateOptionsVpc when driver is "vpc"
7208 Since
7210 2.12
7211 blockdev-create (Command)
7213 Starts a job to create an image format on a given node. The job is au‐
7214 tomatically finalized, but a manual job-dismiss is required.
7215 Arguments
7217 job-id: string
7218 Identifier for the newly created job.
7219 options: BlockdevCreateOptions
7221 Options for the image creation.
7222 Since
7224 3.0
7225 BlockdevAmendOptionsLUKS (Object)
7227 Driver specific image amend options for LUKS.
7228 Members
7230 The members of QCryptoBlockAmendOptionsLUKS
7231 Since
7233 5.1
7234 BlockdevAmendOptionsQcow2 (Object)
7236 Driver specific image amend options for qcow2. For now, only encryp‐
7237 tion options can be amended
7238 encrypt Encryption options to be amended
7240 Members
7242 encrypt: QCryptoBlockAmendOptions (optional)
7243 Not documented
7244 Since
7246 5.1
7247 BlockdevAmendOptions (Object)
7249 Options for amending an image format
7250 Members
7252 driver: BlockdevDriver
7253 Block driver of the node to amend.
7254 The members of BlockdevAmendOptionsLUKS when driver is "luks"
7256 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
7258 Since
7260 5.1
7261 x-blockdev-amend (Command)
7263 Starts a job to amend format specific options of an existing open block
7264 device The job is automatically finalized, but a manual job-dismiss is
7265 required.
7266 Arguments
7268 job-id: string
7269 Identifier for the newly created job.
7270 node-name: string
7272 Name of the block node to work on
7273 options: BlockdevAmendOptions
7275 Options (driver specific)
7276 force: boolean (optional)
7278 Allow unsafe operations, format specific For luks that allows
7279 erase of the last active keyslot (permanent loss of data), and
7280 replacement of an active keyslot (possible loss of data if IO
7281 error happens)
7282 Features
7284 unstable
7285 This command is experimental.
7286 Since
7288 5.1
7289 BlockErrorAction (Enum)
7291 An enumeration of action that has been taken when a DISK I/O occurs
7292 Values
7294 ignore error has been ignored
7295 report error has been reported to the device
7297 stop error caused VM to be stopped
7299 Since
7301 2.1
7302 BLOCK_IMAGE_CORRUPTED (Event)
7304 Emitted when a disk image is being marked corrupt. The image can be
7305 identified by its device or node name. The 'device' field is always
7306 present for compatibility reasons, but it can be empty ("") if the im‐
7307 age does not have a device name associated.
7308 Arguments
7310 device: string
7311 device name. This is always present for compatibility reasons,
7312 but it can be empty ("") if the image does not have a device
7313 name associated.
7314 node-name: string (optional)
7316 node name (Since: 2.4)
7317 msg: string
7319 informative message for human consumption, such as the kind of
7320 corruption being detected. It should not be parsed by machine as
7321 it is not guaranteed to be stable
7322 offset: int (optional)
7324 if the corruption resulted from an image access, this is the
7325 host's access offset into the image
7326 size: int (optional)
7328 if the corruption resulted from an image access, this is the ac‐
7329 cess size
7330 fatal: boolean
7332 if set, the image is marked corrupt and therefore unusable after
7333 this event and must be repaired (Since 2.2; before, every
7334 BLOCK_IMAGE_CORRUPTED event was fatal)
7335 Note
7337 If action is "stop", a STOP event will eventually follow the
7338 BLOCK_IO_ERROR event.
7339 Example
7341 <- { "event": "BLOCK_IMAGE_CORRUPTED",
7342 "data": { "device": "", "node-name": "drive", "fatal": false,
7343 "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" },
7344 "timestamp": { "seconds": 1648243240, "microseconds": 906060 } }
7345 Since
7347 1.7
7348 BLOCK_IO_ERROR (Event)
7350 Emitted when a disk I/O error occurs
7351 Arguments
7353 device: string
7354 device name. This is always present for compatibility reasons,
7355 but it can be empty ("") if the image does not have a device
7356 name associated.
7357 node-name: string (optional)
7359 node name. Note that errors may be reported for the root node
7360 that is directly attached to a guest device rather than for the
7361 node where the error occurred. The node name is not present if
7362 the drive is empty. (Since: 2.8)
7363 operation: IoOperationType
7365 I/O operation
7366 action: BlockErrorAction
7368 action that has been taken
7369 nospace: boolean (optional)
7371 true if I/O error was caused due to a no-space condition. This
7372 key is only present if query-block's io-status is present,
7373 please see query-block documentation for more information
7374 (since: 2.2)
7375 reason: string
7377 human readable string describing the error cause. (This field
7378 is a debugging aid for humans, it should not be parsed by appli‐
7379 cations) (since: 2.2)
7380 Note
7382 If action is "stop", a STOP event will eventually follow the
7383 BLOCK_IO_ERROR event
7384 Since
7386 0.13
7387 Example
7389 <- { "event": "BLOCK_IO_ERROR",
7390 "data": { "device": "ide0-hd1",
7391 "node-name": "#block212",
7392 "operation": "write",
7393 "action": "stop",
7394 "reason": "No space left on device" },
7395 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7396 BLOCK_JOB_COMPLETED (Event)
7398 Emitted when a block job has completed
7399 Arguments
7401 type: JobType
7402 job type
7403 device: string
7405 The job identifier. Originally the device name but other values
7406 are allowed since QEMU 2.7
7407 len: int
7409 maximum progress value
7410 offset: int
7412 current progress value. On success this is equal to len. On
7413 failure this is less than len
7414 speed: int
7416 rate limit, bytes per second
7417 error: string (optional)
7419 error message. Only present on failure. This field contains a
7420 human-readable error message. There are no semantics other than
7421 that streaming has failed and clients should not try to inter‐
7422 pret the error string
7423 Since
7425 1.1
7426 Example
7428 <- { "event": "BLOCK_JOB_COMPLETED",
7429 "data": { "type": "stream", "device": "virtio-disk0",
7430 "len": 10737418240, "offset": 10737418240,
7431 "speed": 0 },
7432 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
7433 BLOCK_JOB_CANCELLED (Event)
7435 Emitted when a block job has been cancelled
7436 Arguments
7438 type: JobType
7439 job type
7440 device: string
7442 The job identifier. Originally the device name but other values
7443 are allowed since QEMU 2.7
7444 len: int
7446 maximum progress value
7447 offset: int
7449 current progress value. On success this is equal to len. On
7450 failure this is less than len
7451 speed: int
7453 rate limit, bytes per second
7454 Since
7456 1.1
7457 Example
7459 <- { "event": "BLOCK_JOB_CANCELLED",
7460 "data": { "type": "stream", "device": "virtio-disk0",
7461 "len": 10737418240, "offset": 134217728,
7462 "speed": 0 },
7463 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
7464 BLOCK_JOB_ERROR (Event)
7466 Emitted when a block job encounters an error
7467 Arguments
7469 device: string
7470 The job identifier. Originally the device name but other values
7471 are allowed since QEMU 2.7
7472 operation: IoOperationType
7474 I/O operation
7475 action: BlockErrorAction
7477 action that has been taken
7478 Since
7480 1.3
7481 Example
7483 <- { "event": "BLOCK_JOB_ERROR",
7484 "data": { "device": "ide0-hd1",
7485 "operation": "write",
7486 "action": "stop" },
7487 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7488 BLOCK_JOB_READY (Event)
7490 Emitted when a block job is ready to complete
7491 Arguments
7493 type: JobType
7494 job type
7495 device: string
7497 The job identifier. Originally the device name but other values
7498 are allowed since QEMU 2.7
7499 len: int
7501 maximum progress value
7502 offset: int
7504 current progress value. On success this is equal to len. On
7505 failure this is less than len
7506 speed: int
7508 rate limit, bytes per second
7509 Note
7511 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
7512 event
7513 Since
7515 1.3
7516 Example
7518 <- { "event": "BLOCK_JOB_READY",
7519 "data": { "device": "drive0", "type": "mirror", "speed": 0,
7520 "len": 2097152, "offset": 2097152 },
7521 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7522 BLOCK_JOB_PENDING (Event)
7524 Emitted when a block job is awaiting explicit authorization to finalize
7525 graph changes via block-job-finalize. If this job is part of a transac‐
7526 tion, it will not emit this event until the transaction has converged
7527 first.
7528 Arguments
7530 type: JobType
7531 job type
7532 id: string
7534 The job identifier.
7535 Since
7537 2.12
7538 Example
7540 <- { "event": "BLOCK_JOB_PENDING",
7541 "data": { "type": "mirror", "id": "backup_1" },
7542 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7543 PreallocMode (Enum)
7545 Preallocation mode of QEMU image file
7546 Values
7548 off no preallocation
7549 metadata
7551 preallocate only for metadata
7552 falloc like full preallocation but allocate disk space by posix_fallo‐
7554 cate() rather than writing data.
7555 full preallocate all data by writing it to the device to ensure disk
7557 space is really available. This data may or may not be zero, de‐
7558 pending on the image format and storage. full preallocation
7559 also sets up metadata correctly.
7560 Since
7562 2.2
7563 BLOCK_WRITE_THRESHOLD (Event)
7565 Emitted when writes on block device reaches or exceeds the configured
7566 write threshold. For thin-provisioned devices, this means the device
7567 should be extended to avoid pausing for disk exhaustion. The event is
7568 one shot. Once triggered, it needs to be re-registered with another
7569 block-set-write-threshold command.
7570 Arguments
7572 node-name: string
7573 graph node name on which the threshold was exceeded.
7574 amount-exceeded: int
7576 amount of data which exceeded the threshold, in bytes.
7577 write-threshold: int
7579 last configured threshold, in bytes.
7580 Since
7582 2.3
7583 block-set-write-threshold (Command)
7585 Change the write threshold for a block drive. An event will be deliv‐
7586 ered if a write to this block drive crosses the configured threshold.
7587 The threshold is an offset, thus must be non-negative. Default is no
7588 write threshold. Setting the threshold to zero disables it.
7589 This is useful to transparently resize thin-provisioned drives without
7591 the guest OS noticing.
7592 Arguments
7594 node-name: string
7595 graph node name on which the threshold must be set.
7596 write-threshold: int
7598 configured threshold for the block device, bytes. Use 0 to dis‐
7599 able the threshold.
7600 Since
7602 2.3
7603 Example
7605 -> { "execute": "block-set-write-threshold",
7606 "arguments": { "node-name": "mydev",
7607 "write-threshold": 17179869184 } }
7608 <- { "return": {} }
7609 x-blockdev-change (Command)
7611 Dynamically reconfigure the block driver state graph. It can be used to
7612 add, remove, insert or replace a graph node. Currently only the Quorum
7613 driver implements this feature to add or remove its child. This is use‐
7614 ful to fix a broken quorum child.
7615 If node is specified, it will be inserted under parent. child may not
7617 be specified in this case. If both parent and child are specified but
7618 node is not, child will be detached from parent.
7619 Arguments
7621 parent: string
7622 the id or name of the parent node.
7623 child: string (optional)
7625 the name of a child under the given parent node.
7626 node: string (optional)
7628 the name of the node that will be added.
7629 Features
7631 unstable
7632 This command is experimental, and its API is not stable. It
7633 does not support all kinds of operations, all kinds of children,
7634 nor all block drivers.
7635 FIXME Removing children from a quorum node means introducing
7637 gaps in the child indices. This cannot be represented in the
7638 'children' list of BlockdevOptionsQuorum, as returned by
7639 .bdrv_refresh_filename().
7640 Warning: The data in a new quorum child MUST be consistent with
7642 that of the rest of the array.
7643 Since
7645 2.7
7646 Example
7648 1. Add a new node to a quorum
7649 -> { "execute": "blockdev-add",
7650 "arguments": {
7651 "driver": "raw",
7652 "node-name": "new_node",
7653 "file": { "driver": "file",
7654 "filename": "test.raw" } } }
7655 <- { "return": {} }
7656 -> { "execute": "x-blockdev-change",
7657 "arguments": { "parent": "disk1",
7658 "node": "new_node" } }
7659 <- { "return": {} }
7660 2. Delete a quorum's node
7662 -> { "execute": "x-blockdev-change",
7663 "arguments": { "parent": "disk1",
7664 "child": "children.1" } }
7665 <- { "return": {} }
7666 x-blockdev-set-iothread (Command)
7668 Move node and its children into the iothread. If iothread is null then
7669 move node and its children into the main loop.
7670 The node must not be attached to a BlockBackend.
7672 Arguments
7674 node-name: string
7675 the name of the block driver node
7676 iothread: StrOrNull
7678 the name of the IOThread object or null for the main loop
7679 force: boolean (optional)
7681 true if the node and its children should be moved when a Block‐
7682 Backend is already attached
7683 Features
7685 unstable
7686 This command is experimental and intended for test cases that
7687 need control over IOThreads only.
7688 Since
7690 2.12
7691 Example
7693 1. Move a node into an IOThread
7694 -> { "execute": "x-blockdev-set-iothread",
7695 "arguments": { "node-name": "disk1",
7696 "iothread": "iothread0" } }
7697 <- { "return": {} }
7698 2. Move a node into the main loop
7700 -> { "execute": "x-blockdev-set-iothread",
7701 "arguments": { "node-name": "disk1",
7702 "iothread": null } }
7703 <- { "return": {} }
7704 QuorumOpType (Enum)
7706 An enumeration of the quorum operation types
7707 Values
7709 read read operation
7710 write write operation
7712 flush flush operation
7714 Since
7716 2.6
7717 QUORUM_FAILURE (Event)
7719 Emitted by the Quorum block driver if it fails to establish a quorum
7720 Arguments
7722 reference: string
7723 device name if defined else node name
7724 sector-num: int
7726 number of the first sector of the failed read operation
7727 sectors-count: int
7729 failed read operation sector count
7730 Note
7732 This event is rate-limited.
7733 Since
7735 2.0
7736 Example
7738 <- { "event": "QUORUM_FAILURE",
7739 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
7740 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7741 QUORUM_REPORT_BAD (Event)
7743 Emitted to report a corruption of a Quorum file
7744 Arguments
7746 type: QuorumOpType
7747 quorum operation type (Since 2.6)
7748 error: string (optional)
7750 error message. Only present on failure. This field contains a
7751 human-readable error message. There are no semantics other than
7752 that the block layer reported an error and clients should not
7753 try to interpret the error string.
7754 node-name: string
7756 the graph node name of the block driver state
7757 sector-num: int
7759 number of the first sector of the failed read operation
7760 sectors-count: int
7762 failed read operation sector count
7763 Note
7765 This event is rate-limited.
7766 Since
7768 2.0
7769 Example
7771 1. Read operation
7772 { "event": "QUORUM_REPORT_BAD",
7774 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
7775 "type": "read" },
7776 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7777 2. Flush operation
7779 { "event": "QUORUM_REPORT_BAD",
7781 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
7782 "type": "flush", "error": "Broken pipe" },
7783 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
7784 BlockdevSnapshotInternal (Object)
7786 Members
7787 device: string
7788 the device name or node-name of a root node to generate the
7789 snapshot from
7790 name: string
7792 the name of the internal snapshot to be created
7793 Notes
7795 In transaction, if name is empty, or any snapshot matching name exists,
7796 the operation will fail. Only some image formats support it, for exam‐
7797 ple, qcow2, and rbd.
7798 Since
7800 1.7
7801 blockdev-snapshot-internal-sync (Command)
7803 Synchronously take an internal snapshot of a block device, when the
7804 format of the image used supports it. If the name is an empty string,
7805 or a snapshot with name already exists, the operation will fail.
7806 For the arguments, see the documentation of BlockdevSnapshotInternal.
7808 Returns
7810 • nothing on success
7811 • If device is not a valid block device, GenericError
7813 • If any snapshot matching name exists, or name is empty, GenericError
7815 • If the format of the image used does not support it, BlockFormatFea‐
7817 tureNotSupported
7818 Since
7820 1.7
7821 Example
7823 -> { "execute": "blockdev-snapshot-internal-sync",
7824 "arguments": { "device": "ide-hd0",
7825 "name": "snapshot0" }
7826 }
7827 <- { "return": {} }
7828 blockdev-snapshot-delete-internal-sync (Command)
7830 Synchronously delete an internal snapshot of a block device, when the
7831 format of the image used support it. The snapshot is identified by name
7832 or id or both. One of the name or id is required. Return SnapshotInfo
7833 for the successfully deleted snapshot.
7834 Arguments
7836 device: string
7837 the device name or node-name of a root node to delete the snap‐
7838 shot from
7839 id: string (optional)
7841 optional the snapshot's ID to be deleted
7842 name: string (optional)
7844 optional the snapshot's name to be deleted
7845 Returns
7847 • SnapshotInfo on success
7848 • If device is not a valid block device, GenericError
7850 • If snapshot not found, GenericError
7852 • If the format of the image used does not support it, BlockFormatFea‐
7854 tureNotSupported
7855 • If id and name are both not specified, GenericError
7857 Since
7859 1.7
7860 Example
7862 -> { "execute": "blockdev-snapshot-delete-internal-sync",
7863 "arguments": { "device": "ide-hd0",
7864 "name": "snapshot0" }
7865 }
7866 <- { "return": {
7867 "id": "1",
7868 "name": "snapshot0",
7869 "vm-state-size": 0,
7870 "date-sec": 1000012,
7871 "date-nsec": 10,
7872 "vm-clock-sec": 100,
7873 "vm-clock-nsec": 20,
7874 "icount": 220414
7875 }
7876 }
7877 Block device exports
7879 NbdServerOptions (Object)
7880 Keep this type consistent with the nbd-server-start arguments. The only
7881 intended difference is using SocketAddress instead of SocketAddressLe‐
7882 gacy.
7883 Members
7885 addr: SocketAddress
7886 Address on which to listen.
7887 tls-creds: string (optional)
7889 ID of the TLS credentials object (since 2.6).
7890 tls-authz: string (optional)
7892 ID of the QAuthZ authorization object used to validate the
7893 client's x509 distinguished name. This object is is only re‐
7894 solved at time of use, so can be deleted and recreated on the
7895 fly while the NBD server is active. If missing, it will default
7896 to denying access (since 4.0).
7897 max-connections: int (optional)
7899 The maximum number of connections to allow at the same time, 0
7900 for unlimited. Setting this to 1 also stops the server from ad‐
7901 vertising multiple client support (since 5.2; default: 0)
7902 Since
7904 4.2
7905 nbd-server-start (Command)
7907 Start an NBD server listening on the given host and port. Block de‐
7908 vices can then be exported using nbd-server-add. The NBD server will
7909 present them as named exports; for example, another QEMU instance could
7910 refer to them as "nbd:HOST:PORT:exportname=NAME".
7911 Keep this type consistent with the NbdServerOptions type. The only in‐
7913 tended difference is using SocketAddressLegacy instead of SocketAd‐
7914 dress.
7915 Arguments
7917 addr: SocketAddressLegacy
7918 Address on which to listen.
7919 tls-creds: string (optional)
7921 ID of the TLS credentials object (since 2.6).
7922 tls-authz: string (optional)
7924 ID of the QAuthZ authorization object used to validate the
7925 client's x509 distinguished name. This object is is only re‐
7926 solved at time of use, so can be deleted and recreated on the
7927 fly while the NBD server is active. If missing, it will default
7928 to denying access (since 4.0).
7929 max-connections: int (optional)
7931 The maximum number of connections to allow at the same time, 0
7932 for unlimited. Setting this to 1 also stops the server from ad‐
7933 vertising multiple client support (since 5.2; default: 0).
7934 Returns
7936 error if the server is already running.
7937 Since
7939 1.3
7940 BlockExportOptionsNbdBase (Object)
7942 An NBD block export (common options shared between nbd-server-add and
7943 the NBD branch of block-export-add).
7944 Members
7946 name: string (optional)
7947 Export name. If unspecified, the device parameter is used as the
7948 export name. (Since 2.12)
7949 description: string (optional)
7951 Free-form description of the export, up to 4096 bytes. (Since
7952 5.0)
7953 Since
7955 5.0
7956 BlockExportOptionsNbd (Object)
7958 An NBD block export (distinct options used in the NBD branch of
7959 block-export-add).
7960 Members
7962 bitmaps: array of BlockDirtyBitmapOrStr (optional)
7963 Also export each of the named dirty bitmaps reachable from de‐
7964 vice, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
7965 the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
7966 each bitmap. Since 7.1 bitmap may be specified by node/name
7967 pair.
7968 allocation-depth: boolean (optional)
7970 Also export the allocation depth map for device, so the NBD
7971 client can use NBD_OPT_SET_META_CONTEXT with the metadata con‐
7972 text name "qemu:allocation-depth" to inspect allocation details.
7973 (since 5.2)
7974 The members of BlockExportOptionsNbdBase
7976 Since
7978 5.2
7979 BlockExportOptionsVhostUserBlk (Object)
7981 A vhost-user-blk block export.
7982 Members
7984 addr: SocketAddress
7985 The vhost-user socket on which to listen. Both 'unix' and 'fd'
7986 SocketAddress types are supported. Passed fds must be UNIX do‐
7987 main sockets.
7988 logical-block-size: int (optional)
7990 Logical block size in bytes. Defaults to 512 bytes.
7991 num-queues: int (optional)
7993 Number of request virtqueues. Must be greater than 0. Defaults
7994 to 1.
7995 Since
7997 5.2
7998 FuseExportAllowOther (Enum)
8000 Possible allow_other modes for FUSE exports.
8001 Values
8003 off Do not pass allow_other as a mount option.
8004 on Pass allow_other as a mount option.
8006 auto Try mounting with allow_other first, and if that fails, retry
8008 without allow_other.
8009 Since
8011 6.1
8012 BlockExportOptionsFuse (Object)
8014 Options for exporting a block graph node on some (file) mountpoint as a
8015 raw image.
8016 Members
8018 mountpoint: string
8019 Path on which to export the block device via FUSE. This must
8020 point to an existing regular file.
8021 growable: boolean (optional)
8023 Whether writes beyond the EOF should grow the block node accord‐
8024 ingly. (default: false)
8025 allow-other: FuseExportAllowOther (optional)
8027 If this is off, only qemu's user is allowed access to this ex‐
8028 port. That cannot be changed even with chmod or chown. En‐
8029 abling this option will allow other users access to the export
8030 with the FUSE mount option "allow_other". Note that using al‐
8031 low_other as a non-root user requires user_allow_other to be en‐
8032 abled in the global fuse.conf configuration file. In auto mode
8033 (the default), the FUSE export driver will first attempt to
8034 mount the export with allow_other, and if that fails, try again
8035 without. (since 6.1; default: auto)
8036 Since
8038 6.0
8039 If
8041 CONFIG_FUSE
8042 BlockExportOptionsVduseBlk (Object)
8044 A vduse-blk block export.
8045 Members
8047 name: string
8048 the name of VDUSE device (must be unique across the host).
8049 num-queues: int (optional)
8051 the number of virtqueues. Defaults to 1.
8052 queue-size: int (optional)
8054 the size of virtqueue. Defaults to 256.
8055 logical-block-size: int (optional)
8057 Logical block size in bytes. Range [512, PAGE_SIZE] and must be
8058 power of 2. Defaults to 512 bytes.
8059 serial: string (optional)
8061 the serial number of virtio block device. Defaults to empty
8062 string.
8063 Since
8065 7.1
8066 NbdServerAddOptions (Object)
8068 An NBD block export, per legacy nbd-server-add command.
8069 Members
8071 device: string
8072 The device name or node name of the node to be exported
8073 writable: boolean (optional)
8075 Whether clients should be able to write to the device via the
8076 NBD connection (default false).
8077 bitmap: string (optional)
8079 Also export a single dirty bitmap reachable from device, so the
8080 NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
8081 context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
8082 (since 4.0).
8083 The members of BlockExportOptionsNbdBase
8085 Since
8087 5.0
8088 nbd-server-add (Command)
8090 Export a block node to QEMU's embedded NBD server.
8091 The export name will be used as the id for the resulting block export.
8093 Arguments
8095 The members of NbdServerAddOptions
8096 Features
8098 deprecated
8099 This command is deprecated. Use block-export-add instead.
8100 Returns
8102 error if the server is not running, or export with the same name al‐
8103 ready exists.
8104 Since
8106 1.3
8107 BlockExportRemoveMode (Enum)
8109 Mode for removing a block export.
8110 Values
8112 safe Remove export if there are no existing connections, fail other‐
8113 wise.
8114 hard Drop all connections immediately and remove export.
8116 TODO
8118 Potential additional modes to be added in the future:
8119 hide: Just hide export from new clients, leave existing connections as
8121 is. Remove export after all clients are disconnected.
8122 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
8124 ther requests from existing clients.
8125 Since
8127 2.12
8128 nbd-server-remove (Command)
8130 Remove NBD export by name.
8131 Arguments
8133 name: string
8134 Block export id.
8135 mode: BlockExportRemoveMode (optional)
8137 Mode of command operation. See BlockExportRemoveMode descrip‐
8138 tion. Default is 'safe'.
8139 Features
8141 deprecated
8142 This command is deprecated. Use block-export-del instead.
8143 Returns
8145 error if
8146 • the server is not running
8148 • export is not found
8150 • mode is 'safe' and there are existing connections
8152 Since
8154 2.12
8155 nbd-server-stop (Command)
8157 Stop QEMU's embedded NBD server, and unregister all devices previously
8158 added via nbd-server-add.
8159 Since
8161 1.3
8162 BlockExportType (Enum)
8164 An enumeration of block export types
8165 Values
8167 nbd NBD export
8168 vhost-user-blk (If: CONFIG_VHOST_USER_BLK_SERVER)
8170 vhost-user-blk export (since 5.2)
8171 fuse (If: CONFIG_FUSE)
8173 FUSE export (since: 6.0)
8174 vduse-blk (If: CONFIG_VDUSE_BLK_EXPORT)
8176 vduse-blk export (since 7.1)
8177 Since
8179 4.2
8180 BlockExportOptions (Object)
8182 Describes a block export, i.e. how single node should be exported on an
8183 external interface.
8184 Members
8186 id: string
8187 A unique identifier for the block export (across all export
8188 types)
8189 node-name: string
8191 The node name of the block node to be exported (since: 5.2)
8192 writable: boolean (optional)
8194 True if clients should be able to write to the export (default
8195 false)
8196 writethrough: boolean (optional)
8198 If true, caches are flushed after every write request to the ex‐
8199 port before completion is signalled. (since: 5.2; default:
8200 false)
8201 iothread: string (optional)
8203 The name of the iothread object where the export will run. The
8204 default is to use the thread currently associated with the block
8205 node. (since: 5.2)
8206 fixed-iothread: boolean (optional)
8208 True prevents the block node from being moved to another thread
8209 while the export is active. If true and iothread is given, ex‐
8210 port creation fails if the block node cannot be moved to the io‐
8211 thread. The default is false. (since: 5.2)
8212 type: BlockExportType
8214 Not documented
8215 The members of BlockExportOptionsNbd when type is "nbd"
8217 The members of BlockExportOptionsVhostUserBlk when type is
8219 "vhost-user-blk" (If: CONFIG_VHOST_USER_BLK_SERVER)
8220 The members of BlockExportOptionsFuse when type is "fuse" (If: CON‐
8222 FIG_FUSE)
8223 The members of BlockExportOptionsVduseBlk when type is "vduse-blk" (If:
8225 CONFIG_VDUSE_BLK_EXPORT)
8226 Since
8228 4.2
8229 block-export-add (Command)
8231 Creates a new block export.
8232 Arguments
8234 The members of BlockExportOptions
8235 Since
8237 5.2
8238 block-export-del (Command)
8240 Request to remove a block export. This drops the user's reference to
8241 the export, but the export may still stay around after this command re‐
8242 turns until the shutdown of the export has completed.
8243 Arguments
8245 id: string
8246 Block export id.
8247 mode: BlockExportRemoveMode (optional)
8249 Mode of command operation. See BlockExportRemoveMode descrip‐
8250 tion. Default is 'safe'.
8251 Returns
8253 Error if the export is not found or mode is 'safe' and the export is
8254 still in use (e.g. by existing client connections)
8255 Since
8257 5.2
8258 BLOCK_EXPORT_DELETED (Event)
8260 Emitted when a block export is removed and its id can be reused.
8261 Arguments
8263 id: string
8264 Block export id.
8265 Since
8267 5.2
8268 BlockExportInfo (Object)
8270 Information about a single block export.
8271 Members
8273 id: string
8274 The unique identifier for the block export
8275 type: BlockExportType
8277 The block export type
8278 node-name: string
8280 The node name of the block node that is exported
8281 shutting-down: boolean
8283 True if the export is shutting down (e.g. after a block-ex‐
8284 port-del command, but before the shutdown has completed)
8285 Since
8287 5.2
8288 query-block-exports (Command)
8290 Returns
8291 A list of BlockExportInfo describing all block exports
8292 Since
8294 5.2
8295
8297 ChardevInfo (Object)
8298 Information about a character device.
8299 Members
8301 label: string
8302 the label of the character device
8303 filename: string
8305 the filename of the character device
8306 frontend-open: boolean
8308 shows whether the frontend device attached to this backend (eg.
8309 with the chardev=... option) is in open or closed state (since
8310 2.1)
8311 Notes
8313 filename is encoded using the QEMU command line character device encod‐
8314 ing. See the QEMU man page for details.
8315 Since
8317 0.14
8318 query-chardev (Command)
8320 Returns information about current character devices.
8321 Returns
8323 a list of ChardevInfo
8324 Since
8326 0.14
8327 Example
8329 -> { "execute": "query-chardev" }
8330 <- {
8331 "return": [
8332 {
8333 "label": "charchannel0",
8334 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
8335 "frontend-open": false
8336 },
8337 {
8338 "label": "charmonitor",
8339 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
8340 "frontend-open": true
8341 },
8342 {
8343 "label": "charserial0",
8344 "filename": "pty:/dev/pts/2",
8345 "frontend-open": true
8346 }
8347 ]
8348 }
8349 ChardevBackendInfo (Object)
8351 Information about a character device backend
8352 Members
8354 name: string
8355 The backend name
8356 Since
8358 2.0
8359 query-chardev-backends (Command)
8361 Returns information about character device backends.
8362 Returns
8364 a list of ChardevBackendInfo
8365 Since
8367 2.0
8368 Example
8370 -> { "execute": "query-chardev-backends" }
8371 <- {
8372 "return":[
8373 {
8374 "name":"udp"
8375 },
8376 {
8377 "name":"tcp"
8378 },
8379 {
8380 "name":"unix"
8381 },
8382 {
8383 "name":"spiceport"
8384 }
8385 ]
8386 }
8387 DataFormat (Enum)
8389 An enumeration of data format.
8390 Values
8392 utf8 Data is a UTF-8 string (RFC 3629)
8393 base64 Data is Base64 encoded binary (RFC 3548)
8395 Since
8397 1.4
8398 ringbuf-write (Command)
8400 Write to a ring buffer character device.
8401 Arguments
8403 device: string
8404 the ring buffer character device name
8405 data: string
8407 data to write
8408 format: DataFormat (optional)
8410 data encoding (default 'utf8').
8411 • base64: data must be base64 encoded text. Its binary decoding
8413 gets written.
8414 • utf8: data's UTF-8 encoding is written
8416 • data itself is always Unicode regardless of format, like any
8418 other string.
8419 Returns
8421 Nothing on success
8422 Since
8424 1.4
8425 Example
8427 -> { "execute": "ringbuf-write",
8428 "arguments": { "device": "foo",
8429 "data": "abcdefgh",
8430 "format": "utf8" } }
8431 <- { "return": {} }
8432 ringbuf-read (Command)
8434 Read from a ring buffer character device.
8435 Arguments
8437 device: string
8438 the ring buffer character device name
8439 size: int
8441 how many bytes to read at most
8442 format: DataFormat (optional)
8444 data encoding (default 'utf8').
8445 • base64: the data read is returned in base64 encoding.
8447 • utf8: the data read is interpreted as UTF-8. Bug: can screw
8449 up when the buffer contains invalid UTF-8 sequences, NUL char‐
8450 acters, after the ring buffer lost data, and when reading
8451 stops because the size limit is reached.
8452 • The return value is always Unicode regardless of format, like
8454 any other string.
8455 Returns
8457 data read from the device
8458 Since
8460 1.4
8461 Example
8463 -> { "execute": "ringbuf-read",
8464 "arguments": { "device": "foo",
8465 "size": 1000,
8466 "format": "utf8" } }
8467 <- { "return": "abcdefgh" }
8468 ChardevCommon (Object)
8470 Configuration shared across all chardev backends
8471 Members
8473 logfile: string (optional)
8474 The name of a logfile to save output
8475 logappend: boolean (optional)
8477 true to append instead of truncate (default to false to trun‐
8478 cate)
8479 Since
8481 2.6
8482 ChardevFile (Object)
8484 Configuration info for file chardevs.
8485 Members
8487 in: string (optional)
8488 The name of the input file
8489 out: string
8491 The name of the output file
8492 append: boolean (optional)
8494 Open the file in append mode (default false to truncate) (Since
8495 2.6)
8496 The members of ChardevCommon
8498 Since
8500 1.4
8501 ChardevHostdev (Object)
8503 Configuration info for device and pipe chardevs.
8504 Members
8506 device: string
8507 The name of the special file for the device, i.e. /dev/ttyS0 on
8508 Unix or COM1: on Windows
8509 The members of ChardevCommon
8511 Since
8513 1.4
8514 ChardevSocket (Object)
8516 Configuration info for (stream) socket chardevs.
8517 Members
8519 addr: SocketAddressLegacy
8520 socket address to listen on (server=true) or connect to
8521 (server=false)
8522 tls-creds: string (optional)
8524 the ID of the TLS credentials object (since 2.6)
8525 tls-authz: string (optional)
8527 the ID of the QAuthZ authorization object against which the
8528 client's x509 distinguished name will be validated. This object
8529 is only resolved at time of use, so can be deleted and recreated
8530 on the fly while the chardev server is active. If missing, it
8531 will default to denying access (since 4.0)
8532 server: boolean (optional)
8534 create server socket (default: true)
8535 wait: boolean (optional)
8537 wait for incoming connection on server sockets (default: false).
8538 Silently ignored with server: false. This use is deprecated.
8539 nodelay: boolean (optional)
8541 set TCP_NODELAY socket option (default: false)
8542 telnet: boolean (optional)
8544 enable telnet protocol on server sockets (default: false)
8545 tn3270: boolean (optional)
8547 enable tn3270 protocol on server sockets (default: false)
8548 (Since: 2.10)
8549 websocket: boolean (optional)
8551 enable websocket protocol on server sockets (default: false)
8552 (Since: 3.1)
8553 reconnect: int (optional)
8555 For a client socket, if a socket is disconnected, then attempt a
8556 reconnect after the given number of seconds. Setting this to
8557 zero disables this function. (default: 0) (Since: 2.2)
8558 The members of ChardevCommon
8560 Since
8562 1.4
8563 ChardevUdp (Object)
8565 Configuration info for datagram socket chardevs.
8566 Members
8568 remote: SocketAddressLegacy
8569 remote address
8570 local: SocketAddressLegacy (optional)
8572 local address
8573 The members of ChardevCommon
8575 Since
8577 1.5
8578 ChardevMux (Object)
8580 Configuration info for mux chardevs.
8581 Members
8583 chardev: string
8584 name of the base chardev.
8585 The members of ChardevCommon
8587 Since
8589 1.5
8590 ChardevStdio (Object)
8592 Configuration info for stdio chardevs.
8593 Members
8595 signal: boolean (optional)
8596 Allow signals (such as SIGINT triggered by ^C) be delivered to
8597 qemu. Default: true.
8598 The members of ChardevCommon
8600 Since
8602 1.5
8603 ChardevSpiceChannel (Object)
8605 Configuration info for spice vm channel chardevs.
8606 Members
8608 type: string
8609 kind of channel (for example vdagent).
8610 The members of ChardevCommon
8612 Since
8614 1.5
8615 If
8617 CONFIG_SPICE
8618 ChardevSpicePort (Object)
8620 Configuration info for spice port chardevs.
8621 Members
8623 fqdn: string
8624 name of the channel (see docs/spice-port-fqdn.txt)
8625 The members of ChardevCommon
8627 Since
8629 1.5
8630 If
8632 CONFIG_SPICE
8633 ChardevDBus (Object)
8635 Configuration info for DBus chardevs.
8636 Members
8638 name: string
8639 name of the channel (following docs/spice-port-fqdn.txt)
8640 The members of ChardevCommon
8642 Since
8644 7.0
8645 If
8647 CONFIG_DBUS_DISPLAY
8648 ChardevVC (Object)
8650 Configuration info for virtual console chardevs.
8651 Members
8653 width: int (optional)
8654 console width, in pixels
8655 height: int (optional)
8657 console height, in pixels
8658 cols: int (optional)
8660 console width, in chars
8661 rows: int (optional)
8663 console height, in chars
8664 The members of ChardevCommon
8666 Since
8668 1.5
8669 ChardevRingbuf (Object)
8671 Configuration info for ring buffer chardevs.
8672 Members
8674 size: int (optional)
8675 ring buffer size, must be power of two, default is 65536
8676 The members of ChardevCommon
8678 Since
8680 1.5
8681 ChardevQemuVDAgent (Object)
8683 Configuration info for qemu vdagent implementation.
8684 Members
8686 mouse: boolean (optional)
8687 enable/disable mouse, default is enabled.
8688 clipboard: boolean (optional)
8690 enable/disable clipboard, default is disabled.
8691 The members of ChardevCommon
8693 Since
8695 6.1
8696 If
8698 CONFIG_SPICE_PROTOCOL
8699 ChardevBackendKind (Enum)
8701 Values
8702 pipe Since 1.5
8703 udp Since 1.5
8705 mux Since 1.5
8707 msmouse
8709 Since 1.5
8710 wctablet
8712 Since 2.9
8713 braille
8715 Since 1.5
8716 testdev
8718 Since 2.2
8719 stdio Since 1.5
8721 console
8723 Since 1.5
8724 spicevmc (If: CONFIG_SPICE)
8726 Since 1.5
8727 spiceport (If: CONFIG_SPICE)
8729 Since 1.5
8730 qemu-vdagent (If: CONFIG_SPICE_PROTOCOL)
8732 Since 6.1
8733 dbus (If: CONFIG_DBUS_DISPLAY)
8735 Since 7.0
8736 vc v1.5
8738 ringbuf
8740 Since 1.6
8741 memory Since 1.5
8743 file Not documented
8745 serial Not documented
8747 parallel
8749 Not documented
8750 socket Not documented
8752 pty Not documented
8754 null Not documented
8756 Since
8758 1.4
8759 ChardevFileWrapper (Object)
8761 Members
8762 data: ChardevFile
8763 Not documented
8764 Since
8766 1.4
8767 ChardevHostdevWrapper (Object)
8769 Members
8770 data: ChardevHostdev
8771 Not documented
8772 Since
8774 1.4
8775 ChardevSocketWrapper (Object)
8777 Members
8778 data: ChardevSocket
8779 Not documented
8780 Since
8782 1.4
8783 ChardevUdpWrapper (Object)
8785 Members
8786 data: ChardevUdp
8787 Not documented
8788 Since
8790 1.5
8791 ChardevCommonWrapper (Object)
8793 Members
8794 data: ChardevCommon
8795 Not documented
8796 Since
8798 2.6
8799 ChardevMuxWrapper (Object)
8801 Members
8802 data: ChardevMux
8803 Not documented
8804 Since
8806 1.5
8807 ChardevStdioWrapper (Object)
8809 Members
8810 data: ChardevStdio
8811 Not documented
8812 Since
8814 1.5
8815 ChardevSpiceChannelWrapper (Object)
8817 Members
8818 data: ChardevSpiceChannel
8819 Not documented
8820 Since
8822 1.5
8823 If
8825 CONFIG_SPICE
8826 ChardevSpicePortWrapper (Object)
8828 Members
8829 data: ChardevSpicePort
8830 Not documented
8831 Since
8833 1.5
8834 If
8836 CONFIG_SPICE
8837 ChardevQemuVDAgentWrapper (Object)
8839 Members
8840 data: ChardevQemuVDAgent
8841 Not documented
8842 Since
8844 6.1
8845 If
8847 CONFIG_SPICE_PROTOCOL
8848 ChardevDBusWrapper (Object)
8850 Members
8851 data: ChardevDBus
8852 Not documented
8853 Since
8855 7.0
8856 If
8858 CONFIG_DBUS_DISPLAY
8859 ChardevVCWrapper (Object)
8861 Members
8862 data: ChardevVC
8863 Not documented
8864 Since
8866 1.5
8867 ChardevRingbufWrapper (Object)
8869 Members
8870 data: ChardevRingbuf
8871 Not documented
8872 Since
8874 1.5
8875 ChardevBackend (Object)
8877 Configuration info for the new chardev backend.
8878 Members
8880 type: ChardevBackendKind
8881 Not documented
8882 The members of ChardevFileWrapper when type is "file"
8884 The members of ChardevHostdevWrapper when type is "serial"
8886 The members of ChardevHostdevWrapper when type is "parallel"
8888 The members of ChardevHostdevWrapper when type is "pipe"
8890 The members of ChardevSocketWrapper when type is "socket"
8892 The members of ChardevUdpWrapper when type is "udp"
8894 The members of ChardevCommonWrapper when type is "pty"
8896 The members of ChardevCommonWrapper when type is "null"
8898 The members of ChardevMuxWrapper when type is "mux"
8900 The members of ChardevCommonWrapper when type is "msmouse"
8902 The members of ChardevCommonWrapper when type is "wctablet"
8904 The members of ChardevCommonWrapper when type is "braille"
8906 The members of ChardevCommonWrapper when type is "testdev"
8908 The members of ChardevStdioWrapper when type is "stdio"
8910 The members of ChardevCommonWrapper when type is "console"
8912 The members of ChardevSpiceChannelWrapper when type is "spicevmc" (If:
8914 CONFIG_SPICE)
8915 The members of ChardevSpicePortWrapper when type is "spiceport" (If:
8917 CONFIG_SPICE)
8918 The members of ChardevQemuVDAgentWrapper when type is "qemu-vdagent"
8920 (If: CONFIG_SPICE_PROTOCOL)
8921 The members of ChardevDBusWrapper when type is "dbus" (If: CON‐
8923 FIG_DBUS_DISPLAY)
8924 The members of ChardevVCWrapper when type is "vc"
8926 The members of ChardevRingbufWrapper when type is "ringbuf"
8928 The members of ChardevRingbufWrapper when type is "memory"
8930 Since
8932 1.4
8933 ChardevReturn (Object)
8935 Return info about the chardev backend just created.
8936 Members
8938 pty: string (optional)
8939 name of the slave pseudoterminal device, present if and only if
8940 a chardev of type 'pty' was created
8941 Since
8943 1.4
8944 chardev-add (Command)
8946 Add a character device backend
8947 Arguments
8949 id: string
8950 the chardev's ID, must be unique
8951 backend: ChardevBackend
8953 backend type and parameters
8954 Returns
8956 ChardevReturn.
8957 Since
8959 1.4
8960 Example
8962 -> { "execute" : "chardev-add",
8963 "arguments" : { "id" : "foo",
8964 "backend" : { "type" : "null", "data" : {} } } }
8965 <- { "return": {} }
8966 -> { "execute" : "chardev-add",
8968 "arguments" : { "id" : "bar",
8969 "backend" : { "type" : "file",
8970 "data" : { "out" : "/tmp/bar.log" } } } }
8971 <- { "return": {} }
8972 -> { "execute" : "chardev-add",
8974 "arguments" : { "id" : "baz",
8975 "backend" : { "type" : "pty", "data" : {} } } }
8976 <- { "return": { "pty" : "/dev/pty/42" } }
8977 chardev-change (Command)
8979 Change a character device backend
8980 Arguments
8982 id: string
8983 the chardev's ID, must exist
8984 backend: ChardevBackend
8986 new backend type and parameters
8987 Returns
8989 ChardevReturn.
8990 Since
8992 2.10
8993 Example
8995 -> { "execute" : "chardev-change",
8996 "arguments" : { "id" : "baz",
8997 "backend" : { "type" : "pty", "data" : {} } } }
8998 <- { "return": { "pty" : "/dev/pty/42" } }
8999 -> {"execute" : "chardev-change",
9001 "arguments" : {
9002 "id" : "charchannel2",
9003 "backend" : {
9004 "type" : "socket",
9005 "data" : {
9006 "addr" : {
9007 "type" : "unix" ,
9008 "data" : {
9009 "path" : "/tmp/charchannel2.socket"
9010 }
9011 },
9012 "server" : true,
9013 "wait" : false }}}}
9014 <- {"return": {}}
9015 chardev-remove (Command)
9017 Remove a character device backend
9018 Arguments
9020 id: string
9021 the chardev's ID, must exist and not be in use
9022 Returns
9024 Nothing on success
9025 Since
9027 1.4
9028 Example
9030 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
9031 <- { "return": {} }
9032 chardev-send-break (Command)
9034 Send a break to a character device
9035 Arguments
9037 id: string
9038 the chardev's ID, must exist
9039 Returns
9041 Nothing on success
9042 Since
9044 2.10
9045 Example
9047 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
9048 <- { "return": {} }
9049 VSERPORT_CHANGE (Event)
9051 Emitted when the guest opens or closes a virtio-serial port.
9052 Arguments
9054 id: string
9055 device identifier of the virtio-serial port
9056 open: boolean
9058 true if the guest has opened the virtio-serial port
9059 Note
9061 This event is rate-limited.
9062 Since
9064 2.1
9065 Example
9067 <- { "event": "VSERPORT_CHANGE",
9068 "data": { "id": "channel0", "open": true },
9069 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
9070
9072 qmp_capabilities (Command)
9073 Enable QMP capabilities.
9074 Arguments:
9076 Arguments
9078 enable: array of QMPCapability (optional)
9079 An optional list of QMPCapability values to enable. The client
9080 must not enable any capability that is not mentioned in the QMP
9081 greeting message. If the field is not provided, it means no QMP
9082 capabilities will be enabled. (since 2.12)
9083 Example
9085 -> { "execute": "qmp_capabilities",
9086 "arguments": { "enable": [ "oob" ] } }
9087 <- { "return": {} }
9088 Notes
9090 This command is valid exactly when first connecting: it must be issued
9091 before any other command will be accepted, and will fail once the moni‐
9092 tor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
9093 The QMP client needs to explicitly enable QMP capabilities, otherwise
9095 all the QMP capabilities will be turned off by default.
9096 Since
9098 0.13
9099 QMPCapability (Enum)
9101 Enumeration of capabilities to be advertised during initial client con‐
9102 nection, used for agreeing on particular QMP extension behaviors.
9103 Values
9105 oob QMP ability to support out-of-band requests. (Please refer to
9106 qmp-spec.txt for more information on OOB)
9107 Since
9109 2.12
9110 VersionTriple (Object)
9112 A three-part version number.
9113 Members
9115 major: int
9116 The major version number.
9117 minor: int
9119 The minor version number.
9120 micro: int
9122 The micro version number.
9123 Since
9125 2.4
9126 VersionInfo (Object)
9128 A description of QEMU's version.
9129 Members
9131 qemu: VersionTriple
9132 The version of QEMU. By current convention, a micro version of
9133 50 signifies a development branch. A micro version greater than
9134 or equal to 90 signifies a release candidate for the next minor
9135 version. A micro version of less than 50 signifies a stable re‐
9136 lease.
9137 package: string
9139 QEMU will always set this field to an empty string. Downstream
9140 versions of QEMU should set this to a non-empty string. The ex‐
9141 act format depends on the downstream however it highly recom‐
9142 mended that a unique name is used.
9143 Since
9145 0.14
9146 query-version (Command)
9148 Returns the current version of QEMU.
9149 Returns
9151 A VersionInfo object describing the current version of QEMU.
9152 Since
9154 0.14
9155 Example
9157 -> { "execute": "query-version" }
9158 <- {
9159 "return":{
9160 "qemu":{
9161 "major":0,
9162 "minor":11,
9163 "micro":5
9164 },
9165 "package":""
9166 }
9167 }
9168 CommandInfo (Object)
9170 Information about a QMP command
9171 Members
9173 name: string
9174 The command name
9175 Since
9177 0.14
9178 query-commands (Command)
9180 Return a list of supported QMP commands by this server
9181 Returns
9183 A list of CommandInfo for all supported commands
9184 Since
9186 0.14
9187 Example
9189 -> { "execute": "query-commands" }
9190 <- {
9191 "return":[
9192 {
9193 "name":"query-balloon"
9194 },
9195 {
9196 "name":"system_powerdown"
9197 }
9198 ]
9199 }
9200 Note
9202 This example has been shortened as the real response is too long.
9203 quit (Command)
9205 This command will cause the QEMU process to exit gracefully. While ev‐
9206 ery attempt is made to send the QMP response before terminating, this
9207 is not guaranteed. When using this interface, a premature EOF would
9208 not be unexpected.
9209 Since
9211 0.14
9212 Example
9214 -> { "execute": "quit" }
9215 <- { "return": {} }
9216 MonitorMode (Enum)
9218 An enumeration of monitor modes.
9219 Values
9221 readline
9222 HMP monitor (human-oriented command line interface)
9223 control
9225 QMP monitor (JSON-based machine interface)
9226 Since
9228 5.0
9229 MonitorOptions (Object)
9231 Options to be used for adding a new monitor.
9232 Members
9234 id: string (optional)
9235 Name of the monitor
9236 mode: MonitorMode (optional)
9238 Selects the monitor mode (default: readline in the system
9240 emulator, control in qemu-storage-daemon)
9241 pretty: boolean (optional)
9243 Enables pretty printing (QMP only)
9244 chardev: string
9246 Name of a character device to expose the monitor on
9247 Since
9249 5.0
9250
9252 query-qmp-schema (Command)
9253 Command query-qmp-schema exposes the QMP wire ABI as an array of
9254 SchemaInfo. This lets QMP clients figure out what commands and events
9255 are available in this QEMU, and their parameters and results.
9256 However, the SchemaInfo can't reflect all the rules and restrictions
9258 that apply to QMP. It's interface introspection (figuring out what's
9259 there), not interface specification. The specification is in the QAPI
9260 schema.
9261 Furthermore, while we strive to keep the QMP wire format backwards-com‐
9263 patible across qemu versions, the introspection output is not guaran‐
9264 teed to have the same stability. For example, one version of qemu may
9265 list an object member as an optional non-variant, while another lists
9266 the same member only through the object's variants; or the type of a
9267 member may change from a generic string into a specific enum or from
9268 one specific type into an alternate that includes the original type
9269 alongside something else.
9270 Returns
9272 array of SchemaInfo, where each element describes an entity in the ABI:
9273 command, event, type, ...
9274 The order of the various SchemaInfo is unspecified; however, all names
9276 are guaranteed to be unique (no name will be duplicated with different
9277 meta-types).
9278 Note
9280 the QAPI schema is also used to help define internal interfaces, by
9281 defining QAPI types. These are not part of the QMP wire ABI, and
9282 therefore not returned by this command.
9283 Since
9285 2.5
9286 SchemaMetaType (Enum)
9288 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
9289 Values
9291 builtin
9292 a predefined type such as 'int' or 'bool'.
9293 enum an enumeration type
9295 array an array type
9297 object an object type (struct or union)
9299 alternate
9301 an alternate type
9302 command
9304 a QMP command
9305 event a QMP event
9307 Since
9309 2.5
9310 SchemaInfo (Object)
9312 Members
9313 name: string
9314 the entity's name, inherited from base. The SchemaInfo is al‐
9315 ways referenced by this name. Commands and events have the name
9316 defined in the QAPI schema. Unlike command and event names,
9317 type names are not part of the wire ABI. Consequently, type
9318 names are meaningless strings here, although they are still
9319 guaranteed unique regardless of meta-type.
9320 meta-type: SchemaMetaType
9322 the entity's meta type, inherited from base.
9323 features: array of string (optional)
9325 names of features associated with the entity, in no particular
9326 order. (since 4.1 for object types, 4.2 for commands, 5.0 for
9327 the rest)
9328 The members of SchemaInfoBuiltin when meta-type is "builtin"
9330 The members of SchemaInfoEnum when meta-type is "enum"
9332 The members of SchemaInfoArray when meta-type is "array"
9334 The members of SchemaInfoObject when meta-type is "object"
9336 The members of SchemaInfoAlternate when meta-type is "alternate"
9338 The members of SchemaInfoCommand when meta-type is "command"
9340 The members of SchemaInfoEvent when meta-type is "event"
9342 Additional members depend on the value of meta-type.
9343 Since
9345 2.5
9346 SchemaInfoBuiltin (Object)
9348 Additional SchemaInfo members for meta-type 'builtin'.
9349 Members
9351 json-type: JSONType
9352 the JSON type used for this type on the wire.
9353 Since
9355 2.5
9356 JSONType (Enum)
9358 The four primitive and two structured types according to RFC 8259 sec‐
9359 tion 1, plus 'int' (split off 'number'), plus the obvious top type
9360 'value'.
9361 Values
9363 string Not documented
9364 number Not documented
9366 int Not documented
9368 boolean
9370 Not documented
9371 null Not documented
9373 object Not documented
9375 array Not documented
9377 value Not documented
9379 Since
9381 2.5
9382 SchemaInfoEnum (Object)
9384 Additional SchemaInfo members for meta-type 'enum'.
9385 Members
9387 members: array of SchemaInfoEnumMember
9388 the enum type's members, in no particular order (since 6.2).
9389 values: array of string
9391 the enumeration type's member names, in no particular order.
9392 Redundant with members. Just for backward compatibility.
9393 Features
9395 deprecated
9396 Member values is deprecated. Use members instead.
9397 Values of this type are JSON string on the wire.
9398 Since
9400 2.5
9401 SchemaInfoEnumMember (Object)
9403 An object member.
9404 Members
9406 name: string
9407 the member's name, as defined in the QAPI schema.
9408 features: array of string (optional)
9410 names of features associated with the member, in no particular
9411 order.
9412 Since
9414 6.2
9415 SchemaInfoArray (Object)
9417 Additional SchemaInfo members for meta-type 'array'.
9418 Members
9420 element-type: string
9421 the array type's element type.
9422 Values of this type are JSON array on the wire.
9423 Since
9425 2.5
9426 SchemaInfoObject (Object)
9428 Additional SchemaInfo members for meta-type 'object'.
9429 Members
9431 members: array of SchemaInfoObjectMember
9432 the object type's (non-variant) members, in no particular order.
9433 tag: string (optional)
9435 the name of the member serving as type tag. An element of mem‐
9436 bers with this name must exist.
9437 variants: array of SchemaInfoObjectVariant (optional)
9439 variant members, i.e. additional members that depend on the type
9440 tag's value. Present exactly when tag is present. The variants
9441 are in no particular order, and may even differ from the order
9442 of the values of the enum type of the tag.
9443 Values of this type are JSON object on the wire.
9444 Since
9446 2.5
9447 SchemaInfoObjectMember (Object)
9449 An object member.
9450 Members
9452 name: string
9453 the member's name, as defined in the QAPI schema.
9454 type: string
9456 the name of the member's type.
9457 default: value (optional)
9459 default when used as command parameter. If absent, the parame‐
9460 ter is mandatory. If present, the value must be null. The pa‐
9461 rameter is optional, and behavior when it's missing is not spec‐
9462 ified here. Future extension: if present and non-null, the pa‐
9463 rameter is optional, and defaults to this value.
9464 features: array of string (optional)
9466 names of features associated with the member, in no particular
9467 order. (since 5.0)
9468 Since
9470 2.5
9471 SchemaInfoObjectVariant (Object)
9473 The variant members for a value of the type tag.
9474 Members
9476 case: string
9477 a value of the type tag.
9478 type: string
9480 the name of the object type that provides the variant members
9481 when the type tag has value case.
9482 Since
9484 2.5
9485 SchemaInfoAlternate (Object)
9487 Additional SchemaInfo members for meta-type 'alternate'.
9488 Members
9490 members: array of SchemaInfoAlternateMember
9491 the alternate type's members, in no particular order. The mem‐
9492 bers' wire encoding is distinct, see docs/de‐
9493 vel/qapi-code-gen.txt section Alternate types.
9494 On the wire, this can be any of the members.
9495 Since
9497 2.5
9498 SchemaInfoAlternateMember (Object)
9500 An alternate member.
9501 Members
9503 type: string
9504 the name of the member's type.
9505 Since
9507 2.5
9508 SchemaInfoCommand (Object)
9510 Additional SchemaInfo members for meta-type 'command'.
9511 Members
9513 arg-type: string
9514 the name of the object type that provides the command's parame‐
9515 ters.
9516 ret-type: string
9518 the name of the command's result type.
9519 allow-oob: boolean (optional)
9521 whether the command allows out-of-band execution, defaults to
9522 false (Since: 2.12)
9523 TODO
9525 success-response (currently irrelevant, because it's QGA, not QMP)
9526 Since
9528 2.5
9529 SchemaInfoEvent (Object)
9531 Additional SchemaInfo members for meta-type 'event'.
9532 Members
9534 arg-type: string
9535 the name of the object type that provides the event's parame‐
9536 ters.
9537 Since
9539 2.5
9540
9542 QAuthZListPolicy (Enum)
9543 The authorization policy result
9544 Values
9546 deny deny access
9547 allow allow access
9549 Since
9551 4.0
9552 QAuthZListFormat (Enum)
9554 The authorization policy match format
9555 Values
9557 exact an exact string match
9558 glob string with ? and * shell wildcard support
9560 Since
9562 4.0
9563 QAuthZListRule (Object)
9565 A single authorization rule.
9566 Members
9568 match: string
9569 a string or glob to match against a user identity
9570 policy: QAuthZListPolicy
9572 the result to return if match evaluates to true
9573 format: QAuthZListFormat (optional)
9575 the format of the match rule (default 'exact')
9576 Since
9578 4.0
9579 AuthZListProperties (Object)
9581 Properties for authz-list objects.
9582 Members
9584 policy: QAuthZListPolicy (optional)
9585 Default policy to apply when no rule matches (default: deny)
9586 rules: array of QAuthZListRule (optional)
9588 Authorization rules based on matching user
9589 Since
9591 4.0
9592 AuthZListFileProperties (Object)
9594 Properties for authz-listfile objects.
9595 Members
9597 filename: string
9598 File name to load the configuration from. The file must contain
9599 valid JSON for AuthZListProperties.
9600 refresh: boolean (optional)
9602 If true, inotify is used to monitor the file, automatically
9603 reloading changes. If an error occurs during reloading, all au‐
9604 thorizations will fail until the file is next successfully
9605 loaded. (default: true if the binary was built with CONFIG_INO‐
9606 TIFY1, false otherwise)
9607 Since
9609 4.0
9610 AuthZPAMProperties (Object)
9612 Properties for authz-pam objects.
9613 Members
9615 service: string
9616 PAM service name to use for authorization
9617 Since
9619 4.0
9620 AuthZSimpleProperties (Object)
9622 Properties for authz-simple objects.
9623 Members
9625 identity: string
9626 Identifies the allowed user. Its format depends on the network
9627 service that authorization object is associated with. For autho‐
9628 rizing based on TLS x509 certificates, the identity must be the
9629 x509 distinguished name.
9630 Since
9632 4.0
9633
9635 ObjectPropertyInfo (Object)
9636 Members
9637 name: string
9638 the name of the property
9639 type: string
9641 the type of the property. This will typically come in one of
9642 four forms:
9643 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
9645 ble'. These types are mapped to the appropriate JSON type.
9646 2. A child type in the form 'child<subtype>' where subtype is a
9648 qdev device type name. Child properties create the composi‐
9649 tion tree.
9650 3. A link type in the form 'link<subtype>' where subtype is a
9652 qdev device type name. Link properties form the device model
9653 graph.
9654 description: string (optional)
9656 if specified, the description of the property.
9657 default-value: value (optional)
9659 the default value, if any (since 5.0)
9660 Since
9662 1.2
9663 qom-list (Command)
9665 This command will list any properties of a object given a path in the
9666 object model.
9667 Arguments
9669 path: string
9670 the path within the object model. See qom-get for a description
9671 of this parameter.
9672 Returns
9674 a list of ObjectPropertyInfo that describe the properties of the ob‐
9675 ject.
9676 Since
9678 1.2
9679 Example
9681 -> { "execute": "qom-list",
9682 "arguments": { "path": "/chardevs" } }
9683 <- { "return": [ { "name": "type", "type": "string" },
9684 { "name": "parallel0", "type": "child<chardev-vc>" },
9685 { "name": "serial0", "type": "child<chardev-vc>" },
9686 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
9687 qom-get (Command)
9689 This command will get a property from a object model path and return
9690 the value.
9691 Arguments
9693 path: string
9694 The path within the object model. There are two forms of sup‐
9695 ported paths--absolute and partial paths.
9696 Absolute paths are derived from the root object and can follow
9698 child<> or link<> properties. Since they can follow link<>
9699 properties, they can be arbitrarily long. Absolute paths look
9700 like absolute filenames and are prefixed with a leading slash.
9701 Partial paths look like relative filenames. They do not begin
9703 with a prefix. The matching rules for partial paths are subtle
9704 but designed to make specifying objects easy. At each level of
9705 the composition tree, the partial path is matched as an absolute
9706 path. The first match is not returned. At least two matches
9707 are searched for. A successful result is only returned if only
9708 one match is found. If more than one match is found, a flag is
9709 return to indicate that the match was ambiguous.
9710 property: string
9712 The property name to read
9713 Returns
9715 The property value. The type depends on the property type. child<> and
9716 link<> properties are returned as #str pathnames. All integer property
9717 types (u8, u16, etc) are returned as #int.
9718 Since
9720 1.2
9721 Example
9723 1. Use absolute path
9724 -> { "execute": "qom-get",
9726 "arguments": { "path": "/machine/unattached/device[0]",
9727 "property": "hotplugged" } }
9728 <- { "return": false }
9729 2. Use partial path
9731 -> { "execute": "qom-get",
9733 "arguments": { "path": "unattached/sysbus",
9734 "property": "type" } }
9735 <- { "return": "System" }
9736 qom-set (Command)
9738 This command will set a property from a object model path.
9739 Arguments
9741 path: string
9742 see qom-get for a description of this parameter
9743 property: string
9745 the property name to set
9746 value: value
9748 a value who's type is appropriate for the property type. See
9749 qom-get for a description of type mapping.
9750 Since
9752 1.2
9753 Example
9755 -> { "execute": "qom-set",
9756 "arguments": { "path": "/machine",
9757 "property": "graphics",
9758 "value": false } }
9759 <- { "return": {} }
9760 ObjectTypeInfo (Object)
9762 This structure describes a search result from qom-list-types
9763 Members
9765 name: string
9766 the type name found in the search
9767 abstract: boolean (optional)
9769 the type is abstract and can't be directly instantiated. Omit‐
9770 ted if false. (since 2.10)
9771 parent: string (optional)
9773 Name of parent type, if any (since 2.10)
9774 Since
9776 1.1
9777 qom-list-types (Command)
9779 This command will return a list of types given search parameters
9780 Arguments
9782 implements: string (optional)
9783 if specified, only return types that implement this type name
9784 abstract: boolean (optional)
9786 if true, include abstract types in the results
9787 Returns
9789 a list of ObjectTypeInfo or an empty list if no results are found
9790 Since
9792 1.1
9793 qom-list-properties (Command)
9795 List properties associated with a QOM object.
9796 Arguments
9798 typename: string
9799 the type name of an object
9800 Note
9802 objects can create properties at runtime, for example to describe links
9803 between different devices and/or objects. These properties are not in‐
9804 cluded in the output of this command.
9805 Returns
9807 a list of ObjectPropertyInfo describing object properties
9808 Since
9810 2.12
9811 CanHostSocketcanProperties (Object)
9813 Properties for can-host-socketcan objects.
9814 Members
9816 if: string
9817 interface name of the host system CAN bus to connect to
9818 canbus: string
9820 object ID of the can-bus object to connect to the host interface
9821 Since
9823 2.12
9824 ColoCompareProperties (Object)
9826 Properties for colo-compare objects.
9827 Members
9829 primary_in: string
9830 name of the character device backend to use for the primary in‐
9831 put (incoming packets are redirected to outdev)
9832 secondary_in: string
9834 name of the character device backend to use for secondary input
9835 (incoming packets are only compared to the input on primary_in
9836 and then dropped)
9837 outdev: string
9839 name of the character device backend to use for output
9840 iothread: string
9842 name of the iothread to run in
9843 notify_dev: string (optional)
9845 name of the character device backend to be used to communicate
9846 with the remote colo-frame (only for Xen COLO)
9847 compare_timeout: int (optional)
9849 the maximum time to hold a packet from primary_in for comparison
9850 with an incoming packet on secondary_in in milliseconds (de‐
9851 fault: 3000)
9852 expired_scan_cycle: int (optional)
9854 the interval at which colo-compare checks whether packets from
9855 primary have timed out, in milliseconds (default: 3000)
9856 max_queue_size: int (optional)
9858 the maximum number of packets to keep in the queue for comparing
9859 with incoming packets from secondary_in. If the queue is full
9860 and additional packets are received, the additional packets are
9861 dropped. (default: 1024)
9862 vnet_hdr_support: boolean (optional)
9864 if true, vnet header support is enabled (default: false)
9865 Since
9867 2.8
9868 CryptodevBackendProperties (Object)
9870 Properties for cryptodev-backend and cryptodev-backend-builtin objects.
9871 Members
9873 queues: int (optional)
9874 the number of queues for the cryptodev backend. Ignored for
9875 cryptodev-backend and must be 1 for cryptodev-backend-builtin.
9876 (default: 1)
9877 Since
9879 2.8
9880 CryptodevVhostUserProperties (Object)
9882 Properties for cryptodev-vhost-user objects.
9883 Members
9885 chardev: string
9886 the name of a Unix domain socket character device that connects
9887 to the vhost-user server
9888 The members of CryptodevBackendProperties
9890 Since
9892 2.12
9893 DBusVMStateProperties (Object)
9895 Properties for dbus-vmstate objects.
9896 Members
9898 addr: string
9899 the name of the DBus bus to connect to
9900 id-list: string (optional)
9902 a comma separated list of DBus IDs of helpers whose data should
9903 be included in the VM state on migration
9904 Since
9906 5.0
9907 NetfilterInsert (Enum)
9909 Indicates where to insert a netfilter relative to a given other filter.
9910 Values
9912 before insert before the specified filter
9913 behind insert behind the specified filter
9915 Since
9917 5.0
9918 NetfilterProperties (Object)
9920 Properties for objects of classes derived from netfilter.
9921 Members
9923 netdev: string
9924 id of the network device backend to filter
9925 queue: NetFilterDirection (optional)
9927 indicates which queue(s) to filter (default: all)
9928 status: string (optional)
9930 indicates whether the filter is enabled ("on") or disabled
9931 ("off") (default: "on")
9932 position: string (optional)
9934 specifies where the filter should be inserted in the filter
9935 list. "head" means the filter is inserted at the head of the
9936 filter list, before any existing filters. "tail" means the fil‐
9937 ter is inserted at the tail of the filter list, behind any ex‐
9938 isting filters (default). "id=<id>" means the filter is in‐
9939 serted before or behind the filter specified by <id>, depending
9940 on the insert property. (default: "tail")
9941 insert: NetfilterInsert (optional)
9943 where to insert the filter relative to the filter given in posi‐
9944 tion. Ignored if position is "head" or "tail". (default: be‐
9945 hind)
9946 Since
9948 2.5
9949 FilterBufferProperties (Object)
9951 Properties for filter-buffer objects.
9952 Members
9954 interval: int
9955 a non-zero interval in microseconds. All packets arriving in
9956 the given interval are delayed until the end of the interval.
9957 The members of NetfilterProperties
9959 Since
9961 2.5
9962 FilterDumpProperties (Object)
9964 Properties for filter-dump objects.
9965 Members
9967 file: string
9968 the filename where the dumped packets should be stored
9969 maxlen: int (optional)
9971 maximum number of bytes in a packet that are stored (default:
9972 65536)
9973 The members of NetfilterProperties
9975 Since
9977 2.5
9978 FilterMirrorProperties (Object)
9980 Properties for filter-mirror objects.
9981 Members
9983 outdev: string
9984 the name of a character device backend to which all incoming
9985 packets are mirrored
9986 vnet_hdr_support: boolean (optional)
9988 if true, vnet header support is enabled (default: false)
9989 The members of NetfilterProperties
9991 Since
9993 2.6
9994 FilterRedirectorProperties (Object)
9996 Properties for filter-redirector objects.
9997 At least one of indev or outdev must be present. If both are present,
9999 they must not refer to the same character device backend.
10000 Members
10002 indev: string (optional)
10003 the name of a character device backend from which packets are
10004 received and redirected to the filtered network device
10005 outdev: string (optional)
10007 the name of a character device backend to which all incoming
10008 packets are redirected
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 FilterRewriterProperties (Object)
10019 Properties for filter-rewriter objects.
10020 Members
10022 vnet_hdr_support: boolean (optional)
10023 if true, vnet header support is enabled (default: false)
10024 The members of NetfilterProperties
10026 Since
10028 2.8
10029 InputBarrierProperties (Object)
10031 Properties for input-barrier objects.
10032 Members
10034 name: string
10035 the screen name as declared in the screens section of bar‐
10036 rier.conf
10037 server: string (optional)
10039 hostname of the Barrier server (default: "localhost")
10040 port: string (optional)
10042 TCP port of the Barrier server (default: "24800")
10043 x-origin: string (optional)
10045 x coordinate of the leftmost pixel on the guest screen (default:
10046 "0")
10047 y-origin: string (optional)
10049 y coordinate of the topmost pixel on the guest screen (default:
10050 "0")
10051 width: string (optional)
10053 the width of secondary screen in pixels (default: "1920")
10054 height: string (optional)
10056 the height of secondary screen in pixels (default: "1080")
10057 Since
10059 4.2
10060 InputLinuxProperties (Object)
10062 Properties for input-linux objects.
10063 Members
10065 evdev: string
10066 the path of the host evdev device to use
10067 grab_all: boolean (optional)
10069 if true, grab is toggled for all devices (e.g. both keyboard and
10070 mouse) instead of just one device (default: false)
10071 repeat: boolean (optional)
10073 enables auto-repeat events (default: false)
10074 grab-toggle: GrabToggleKeys (optional)
10076 the key or key combination that toggles device grab (default:
10077 ctrl-ctrl)
10078 Since
10080 2.6
10081 EventLoopBaseProperties (Object)
10083 Common properties for event loops
10084 Members
10086 aio-max-batch: int (optional)
10087 maximum number of requests in a batch for the AIO engine, 0
10088 means that the engine will use its default. (default: 0)
10089 thread-pool-min: int (optional)
10091 minimum number of threads reserved in the thread pool (de‐
10092 fault:0)
10093 thread-pool-max: int (optional)
10095 maximum number of threads the thread pool can contain (de‐
10096 fault:64)
10097 Since
10099 7.1
10100 IothreadProperties (Object)
10102 Properties for iothread objects.
10103 Members
10105 poll-max-ns: int (optional)
10106 the maximum number of nanoseconds to busy wait for events. 0
10107 means polling is disabled (default: 32768 on POSIX hosts, 0 oth‐
10108 erwise)
10109 poll-grow: int (optional)
10111 the multiplier used to increase the polling time when the algo‐
10112 rithm detects it is missing events due to not polling long
10113 enough. 0 selects a default behaviour (default: 0)
10114 poll-shrink: int (optional)
10116 the divisor used to decrease the polling time when the algorithm
10117 detects it is spending too long polling without encountering
10118 events. 0 selects a default behaviour (default: 0)
10119 The members of EventLoopBaseProperties
10121 The aio-max-batch option is available since 6.1.
10122 Since
10124 2.0
10125 MainLoopProperties (Object)
10127 Properties for the main-loop object.
10128 Members
10130 The members of EventLoopBaseProperties
10131 Since
10133 7.1
10134 MemoryBackendProperties (Object)
10136 Properties for objects of classes derived from memory-backend.
10137 Members
10139 merge: boolean (optional)
10140 if true, mark the memory as mergeable (default depends on the
10141 machine type)
10142 dump: boolean (optional)
10144 if true, include the memory in core dumps (default depends on
10145 the machine type)
10146 host-nodes: array of int (optional)
10148 the list of NUMA host nodes to bind the memory to
10149 policy: HostMemPolicy (optional)
10151 the NUMA policy (default: 'default')
10152 prealloc: boolean (optional)
10154 if true, preallocate memory (default: false)
10155 prealloc-threads: int (optional)
10157 number of CPU threads to use for prealloc (default: 1)
10158 prealloc-context: string (optional)
10160 thread context to use for creation of preallocation threads (de‐
10161 fault: none) (since 7.2)
10162 share: boolean (optional)
10164 if false, the memory is private to QEMU; if true, it is shared
10165 (default: false)
10166 reserve: boolean (optional)
10168 if true, reserve swap space (or huge pages) if applicable (de‐
10169 fault: true) (since 6.1)
10170 size: int
10172 size of the memory region in bytes
10173 x-use-canonical-path-for-ramblock-id: boolean (optional)
10175 if true, the canonical path is used for ramblock-id. Disable
10176 this for 4.0 machine types or older to allow migration with
10177 newer QEMU versions. (default: false generally, but true for
10178 machine types <= 4.0)
10179 Note
10181 prealloc=true and reserve=false cannot be set at the same time. With
10182 reserve=true, the behavior depends on the operating system: for exam‐
10183 ple, Linux will not reserve swap space for shared file mappings -- "not
10184 applicable". In contrast, reserve=false will bail out if it cannot be
10185 configured accordingly.
10186 Since
10188 2.1
10189 MemoryBackendFileProperties (Object)
10191 Properties for memory-backend-file objects.
10192 Members
10194 align: int (optional)
10195 the base address alignment when QEMU mmap(2)s mem-path. Some
10196 backend stores specified by mem-path require an alignment dif‐
10197 ferent than the default one used by QEMU, e.g. the device DAX
10198 /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
10199 users can specify the required alignment via this option. 0 se‐
10200 lects a default alignment (currently the page size). (default:
10201 0)
10202 discard-data: boolean (optional)
10204 if true, the file contents can be destroyed when QEMU exits, to
10205 avoid unnecessarily flushing data to the backing file. Note that
10206 discard-data is only an optimization, and QEMU might not discard
10207 file contents if it aborts unexpectedly or is terminated using
10208 SIGKILL. (default: false)
10209 mem-path: string
10211 the path to either a shared memory or huge page filesystem mount
10212 pmem: boolean (optional) (If: CONFIG_LIBPMEM)
10214 specifies whether the backing file specified by mem-path is in
10215 host persistent memory that can be accessed using the SNIA NVM
10216 programming model (e.g. Intel NVDIMM).
10217 readonly: boolean (optional)
10219 if true, the backing file is opened read-only; if false, it is
10220 opened read-write. (default: false)
10221 The members of MemoryBackendProperties
10223 Since
10225 2.1
10226 MemoryBackendMemfdProperties (Object)
10228 Properties for memory-backend-memfd objects.
10229 The share boolean option is true by default with memfd.
10231 Members
10233 hugetlb: boolean (optional)
10234 if true, the file to be created resides in the hugetlbfs
10235 filesystem (default: false)
10236 hugetlbsize: int (optional)
10238 the hugetlb page size on systems that support multiple hugetlb
10239 page sizes (it must be a power of 2 value supported by the sys‐
10240 tem). 0 selects a default page size. This option is ignored if
10241 hugetlb is false. (default: 0)
10242 seal: boolean (optional)
10244 if true, create a sealed-file, which will block further resizing
10245 of the memory (default: true)
10246 The members of MemoryBackendProperties
10248 Since
10250 2.12
10251 MemoryBackendEpcProperties (Object)
10253 Properties for memory-backend-epc objects.
10254 The share boolean option is true by default with epc
10256 The merge boolean option is false by default with epc
10258 The dump boolean option is false by default with epc
10260 Members
10262 The members of MemoryBackendProperties
10263 Since
10265 6.2
10266 PrManagerHelperProperties (Object)
10268 Properties for pr-manager-helper objects.
10269 Members
10271 path: string
10272 the path to a Unix domain socket for connecting to the external
10273 helper
10274 Since
10276 2.11
10277 QtestProperties (Object)
10279 Properties for qtest objects.
10280 Members
10282 chardev: string
10283 the chardev to be used to receive qtest commands on.
10284 log: string (optional)
10286 the path to a log file
10287 Since
10289 6.0
10290 RemoteObjectProperties (Object)
10292 Properties for x-remote-object objects.
10293 Members
10295 fd: string
10296 file descriptor name previously passed via 'getfd' command
10297 devid: string
10299 the id of the device to be associated with the file descriptor
10300 Since
10302 6.0
10303 VfioUserServerProperties (Object)
10305 Properties for x-vfio-user-server objects.
10306 Members
10308 socket: SocketAddress
10309 socket to be used by the libvfio-user library
10310 device: string
10312 the ID of the device to be emulated at the server
10313 Since
10315 7.1
10316 RngProperties (Object)
10318 Properties for objects of classes derived from rng.
10319 Members
10321 opened: boolean (optional)
10322 if true, the device is opened immediately when applying this op‐
10323 tion and will probably fail when processing the next option.
10324 Don't use; only provided for compatibility. (default: false)
10325 Features
10327 deprecated
10328 Member opened is deprecated. Setting true doesn't make sense,
10329 and false is already the default.
10330 Since
10332 1.3
10333 RngEgdProperties (Object)
10335 Properties for rng-egd objects.
10336 Members
10338 chardev: string
10339 the name of a character device backend that provides the connec‐
10340 tion to the RNG daemon
10341 The members of RngProperties
10343 Since
10345 1.3
10346 RngRandomProperties (Object)
10348 Properties for rng-random objects.
10349 Members
10351 filename: string (optional)
10352 the filename of the device on the host to obtain entropy from
10353 (default: "/dev/urandom")
10354 The members of RngProperties
10356 Since
10358 1.3
10359 SevGuestProperties (Object)
10361 Properties for sev-guest objects.
10362 Members
10364 sev-device: string (optional)
10365 SEV device to use (default: "/dev/sev")
10366 dh-cert-file: string (optional)
10368 guest owners DH certificate (encoded with base64)
10369 session-file: string (optional)
10371 guest owners session parameters (encoded with base64)
10372 policy: int (optional)
10374 SEV policy value (default: 0x1)
10375 handle: int (optional)
10377 SEV firmware handle (default: 0)
10378 cbitpos: int (optional)
10380 C-bit location in page table entry (default: 0)
10381 reduced-phys-bits: int
10383 number of bits in physical addresses that become unavailable
10384 when SEV is enabled
10385 kernel-hashes: boolean (optional)
10387 if true, add hashes of kernel/initrd/cmdline to a designated
10388 guest firmware page for measured boot with -kernel (default:
10389 false) (since 6.2)
10390 Since
10392 2.12
10393 ThreadContextProperties (Object)
10395 Properties for thread context objects.
10396 Members
10398 cpu-affinity: array of int (optional)
10399 the list of host CPU numbers used as CPU affinity for all
10400 threads created in the thread context (default: QEMU main thread
10401 CPU affinity)
10402 node-affinity: array of int (optional)
10404 the list of host node numbers that will be resolved to a list of
10405 host CPU numbers used as CPU affinity. This is a shortcut for
10406 specifying the list of host CPU numbers belonging to the host
10407 nodes manually by setting cpu-affinity. (default: QEMU main
10408 thread affinity)
10409 Since
10411 7.2
10412 ObjectType (Enum)
10414 Values
10415 authz-list
10416 Not documented
10417 authz-listfile
10419 Not documented
10420 authz-pam
10422 Not documented
10423 authz-simple
10425 Not documented
10426 can-bus
10428 Not documented
10429 can-host-socketcan (If: CONFIG_LINUX)
10431 Not documented
10432 colo-compare
10434 Not documented
10435 cryptodev-backend
10437 Not documented
10438 cryptodev-backend-builtin
10440 Not documented
10441 cryptodev-backend-lkcf
10443 Not documented
10444 cryptodev-vhost-user (If: CONFIG_VHOST_CRYPTO)
10446 Not documented
10447 dbus-vmstate
10449 Not documented
10450 filter-buffer
10452 Not documented
10453 filter-dump
10455 Not documented
10456 filter-mirror
10458 Not documented
10459 filter-redirector
10461 Not documented
10462 filter-replay
10464 Not documented
10465 filter-rewriter
10467 Not documented
10468 input-barrier
10470 Not documented
10471 input-linux (If: CONFIG_LINUX)
10473 Not documented
10474 iothread
10476 Not documented
10477 main-loop
10479 Not documented
10480 memory-backend-epc (If: CONFIG_LINUX)
10482 Not documented
10483 memory-backend-file
10485 Not documented
10486 memory-backend-memfd (If: CONFIG_LINUX)
10488 Not documented
10489 memory-backend-ram
10491 Not documented
10492 pef-guest
10494 Not documented
10495 pr-manager-helper (If: CONFIG_LINUX)
10497 Not documented
10498 qtest Not documented
10500 rng-builtin
10502 Not documented
10503 rng-egd
10505 Not documented
10506 rng-random (If: CONFIG_POSIX)
10508 Not documented
10509 secret Not documented
10511 secret_keyring (If: CONFIG_SECRET_KEYRING)
10513 Not documented
10514 sev-guest
10516 Not documented
10517 thread-context
10519 Not documented
10520 s390-pv-guest
10522 Not documented
10523 throttle-group
10525 Not documented
10526 tls-creds-anon
10528 Not documented
10529 tls-creds-psk
10531 Not documented
10532 tls-creds-x509
10534 Not documented
10535 tls-cipher-suites
10537 Not documented
10538 x-remote-object
10540 Not documented
10541 x-vfio-user-server
10543 Not documented
10544 Features
10546 unstable
10547 Member x-remote-object is experimental.
10548 Since
10550 6.0
10551 ObjectOptions (Object)
10553 Describes the options of a user creatable QOM object.
10554 Members
10556 qom-type: ObjectType
10557 the class name for the object to be created
10558 id: string
10560 the name of the new object
10561 The members of AuthZListProperties when qom-type is "authz-list"
10563 The members of AuthZListFileProperties when qom-type is "authz-list‐
10565 file"
10566 The members of AuthZPAMProperties when qom-type is "authz-pam"
10568 The members of AuthZSimpleProperties when qom-type is "authz-simple"
10570 The members of CanHostSocketcanProperties when qom-type is
10572 "can-host-socketcan" (If: CONFIG_LINUX)
10573 The members of ColoCompareProperties when qom-type is "colo-compare"
10575 The members of CryptodevBackendProperties when qom-type is "cryp‐
10577 todev-backend"
10578 The members of CryptodevBackendProperties when qom-type is "cryp‐
10580 todev-backend-builtin"
10581 The members of CryptodevBackendProperties when qom-type is "cryp‐
10583 todev-backend-lkcf"
10584 The members of CryptodevVhostUserProperties when qom-type is "cryp‐
10586 todev-vhost-user" (If: CONFIG_VHOST_CRYPTO)
10587 The members of DBusVMStateProperties when qom-type is "dbus-vmstate"
10589 The members of FilterBufferProperties when qom-type is "filter-buffer"
10591 The members of FilterDumpProperties when qom-type is "filter-dump"
10593 The members of FilterMirrorProperties when qom-type is "filter-mirror"
10595 The members of FilterRedirectorProperties when qom-type is "fil‐
10597 ter-redirector"
10598 The members of NetfilterProperties when qom-type is "filter-replay"
10600 The members of FilterRewriterProperties when qom-type is "fil‐
10602 ter-rewriter"
10603 The members of InputBarrierProperties when qom-type is "input-barrier"
10605 The members of InputLinuxProperties when qom-type is "input-linux" (If:
10607 CONFIG_LINUX)
10608 The members of IothreadProperties when qom-type is "iothread"
10610 The members of MainLoopProperties when qom-type is "main-loop"
10612 The members of MemoryBackendEpcProperties when qom-type is "mem‐
10614 ory-backend-epc" (If: CONFIG_LINUX)
10615 The members of MemoryBackendFileProperties when qom-type is "mem‐
10617 ory-backend-file"
10618 The members of MemoryBackendMemfdProperties when qom-type is "mem‐
10620 ory-backend-memfd" (If: CONFIG_LINUX)
10621 The members of MemoryBackendProperties when qom-type is "memory-back‐
10623 end-ram"
10624 The members of PrManagerHelperProperties when qom-type is "pr-man‐
10626 ager-helper" (If: CONFIG_LINUX)
10627 The members of QtestProperties when qom-type is "qtest"
10629 The members of RngProperties when qom-type is "rng-builtin"
10631 The members of RngEgdProperties when qom-type is "rng-egd"
10633 The members of RngRandomProperties when qom-type is "rng-random" (If:
10635 CONFIG_POSIX)
10636 The members of SecretProperties when qom-type is "secret"
10638 The members of SecretKeyringProperties when qom-type is "se‐
10640 cret_keyring" (If: CONFIG_SECRET_KEYRING)
10641 The members of SevGuestProperties when qom-type is "sev-guest"
10643 The members of ThreadContextProperties when qom-type is "thread-con‐
10645 text"
10646 The members of ThrottleGroupProperties when qom-type is "throt‐
10648 tle-group"
10649 The members of TlsCredsAnonProperties when qom-type is "tls-creds-anon"
10651 The members of TlsCredsPskProperties when qom-type is "tls-creds-psk"
10653 The members of TlsCredsX509Properties when qom-type is "tls-creds-x509"
10655 The members of TlsCredsProperties when qom-type is "tls-cipher-suites"
10657 The members of RemoteObjectProperties when qom-type is "x-remote-ob‐
10659 ject"
10660 The members of VfioUserServerProperties when qom-type is
10662 "x-vfio-user-server"
10663 Since
10665 6.0
10666 object-add (Command)
10668 Create a QOM object.
10669 Arguments
10671 The members of ObjectOptions
10672 Returns
10674 Nothing on success Error if qom-type is not a valid class name
10675 Since
10677 2.0
10678 Example
10680 -> { "execute": "object-add",
10681 "arguments": { "qom-type": "rng-random", "id": "rng1",
10682 "filename": "/dev/hwrng" } }
10683 <- { "return": {} }
10684 object-del (Command)
10686 Remove a QOM object.
10687 Arguments
10689 id: string
10690 the name of the QOM object to remove
10691 Returns
10693 Nothing on success Error if id is not a valid id for a QOM object
10694 Since
10696 2.0
10697 Example
10699 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
10700 <- { "return": {} }
10701
10703 Abort (Object)
10704 This action can be used to test transaction failure.
10705 Since
10707 1.6
10708 ActionCompletionMode (Enum)
10710 An enumeration of Transactional completion modes.
10711 Values
10713 individual
10714 Do not attempt to cancel any other Actions if any Actions fail
10715 after the Transaction request succeeds. All Actions that can
10716 complete successfully will do so without waiting on others.
10717 This is the default.
10718 grouped
10720 If any Action fails after the Transaction succeeds, cancel all
10721 Actions. Actions do not complete until all Actions are ready to
10722 complete. May be rejected by Actions that do not support this
10723 completion mode.
10724 Since
10726 2.5
10727 TransactionActionKind (Enum)
10729 Values
10730 abort Since 1.6
10731 block-dirty-bitmap-add
10733 Since 2.5
10734 block-dirty-bitmap-remove
10736 Since 4.2
10737 block-dirty-bitmap-clear
10739 Since 2.5
10740 block-dirty-bitmap-enable
10742 Since 4.0
10743 block-dirty-bitmap-disable
10745 Since 4.0
10746 block-dirty-bitmap-merge
10748 Since 4.0
10749 blockdev-backup
10751 Since 2.3
10752 blockdev-snapshot
10754 Since 2.5
10755 blockdev-snapshot-internal-sync
10757 Since 1.7
10758 blockdev-snapshot-sync
10760 since 1.1
10761 drive-backup
10763 Since 1.6
10764 Features
10766 deprecated
10767 Member drive-backup is deprecated. Use member blockdev-backup
10768 instead.
10769 Since
10771 1.1
10772 AbortWrapper (Object)
10774 Members
10775 data: Abort
10776 Not documented
10777 Since
10779 1.6
10780 BlockDirtyBitmapAddWrapper (Object)
10782 Members
10783 data: BlockDirtyBitmapAdd
10784 Not documented
10785 Since
10787 2.5
10788 BlockDirtyBitmapWrapper (Object)
10790 Members
10791 data: BlockDirtyBitmap
10792 Not documented
10793 Since
10795 2.5
10796 BlockDirtyBitmapMergeWrapper (Object)
10798 Members
10799 data: BlockDirtyBitmapMerge
10800 Not documented
10801 Since
10803 4.0
10804 BlockdevBackupWrapper (Object)
10806 Members
10807 data: BlockdevBackup
10808 Not documented
10809 Since
10811 2.3
10812 BlockdevSnapshotWrapper (Object)
10814 Members
10815 data: BlockdevSnapshot
10816 Not documented
10817 Since
10819 2.5
10820 BlockdevSnapshotInternalWrapper (Object)
10822 Members
10823 data: BlockdevSnapshotInternal
10824 Not documented
10825 Since
10827 1.7
10828 BlockdevSnapshotSyncWrapper (Object)
10830 Members
10831 data: BlockdevSnapshotSync
10832 Not documented
10833 Since
10835 1.1
10836 DriveBackupWrapper (Object)
10838 Members
10839 data: DriveBackup
10840 Not documented
10841 Since
10843 1.6
10844 TransactionAction (Object)
10846 A discriminated record of operations that can be performed with trans‐
10847 action.
10848 Members
10850 type: TransactionActionKind
10851 Not documented
10852 The members of AbortWrapper when type is "abort"
10854 The members of BlockDirtyBitmapAddWrapper when type is
10856 "block-dirty-bitmap-add"
10857 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10859 map-remove"
10860 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10862 map-clear"
10863 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10865 map-enable"
10866 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10868 map-disable"
10869 The members of BlockDirtyBitmapMergeWrapper when type is
10871 "block-dirty-bitmap-merge"
10872 The members of BlockdevBackupWrapper when type is "blockdev-backup"
10874 The members of BlockdevSnapshotWrapper when type is "blockdev-snapshot"
10876 The members of BlockdevSnapshotInternalWrapper when type is "block‐
10878 dev-snapshot-internal-sync"
10879 The members of BlockdevSnapshotSyncWrapper when type is "blockdev-snap‐
10881 shot-sync"
10882 The members of DriveBackupWrapper when type is "drive-backup"
10884 Since
10886 1.1
10887 TransactionProperties (Object)
10889 Optional arguments to modify the behavior of a Transaction.
10890 Members
10892 completion-mode: ActionCompletionMode (optional)
10893 Controls how jobs launched asynchronously by Actions will com‐
10894 plete or fail as a group. See ActionCompletionMode for details.
10895 Since
10897 2.5
10898 transaction (Command)
10900 Executes a number of transactionable QMP commands atomically. If any
10901 operation fails, then the entire set of actions will be abandoned and
10902 the appropriate error returned.
10903 For external snapshots, the dictionary contains the device, the file to
10905 use for the new snapshot, and the format. The default format, if not
10906 specified, is qcow2.
10907 Each new snapshot defaults to being created by QEMU (wiping any con‐
10909 tents if the file already exists), but it is also possible to reuse an
10910 externally-created file. In the latter case, you should ensure that
10911 the new image file has the same contents as the current one; QEMU can‐
10912 not perform any meaningful check. Typically this is achieved by using
10913 the current image file as the backing file for the new image.
10914 On failure, the original disks pre-snapshot attempt will be used.
10916 For internal snapshots, the dictionary contains the device and the
10918 snapshot's name. If an internal snapshot matching name already exists,
10919 the request will be rejected. Only some image formats support it, for
10920 example, qcow2, and rbd,
10921 On failure, qemu will try delete the newly created internal snapshot in
10923 the transaction. When an I/O error occurs during deletion, the user
10924 needs to fix it later with qemu-img or other command.
10925 Arguments
10927 actions: array of TransactionAction
10928 List of TransactionAction; information needed for the respective
10929 operations.
10930 properties: TransactionProperties (optional)
10932 structure of additional options to control the execution of the
10933 transaction. See TransactionProperties for additional detail.
10934 Returns
10936 nothing on success
10937 Errors depend on the operations of the transaction
10939 Note
10941 The transaction aborts on the first failure. Therefore, there will be
10942 information on only one failed operation returned in an error condi‐
10943 tion, and subsequent actions will not have been attempted.
10944 Since
10946 1.1
10947 Example
10949 -> { "execute": "transaction",
10950 "arguments": { "actions": [
10951 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
10952 "snapshot-file": "/some/place/my-image",
10953 "format": "qcow2" } },
10954 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
10955 "snapshot-file": "/some/place/my-image2",
10956 "snapshot-node-name": "node3432",
10957 "mode": "existing",
10958 "format": "qcow2" } },
10959 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
10960 "snapshot-file": "/some/place/my-image2",
10961 "mode": "existing",
10962 "format": "qcow2" } },
10963 { "type": "blockdev-snapshot-internal-sync", "data" : {
10964 "device": "ide-hd2",
10965 "name": "snapshot0" } } ] } }
10966 <- { "return": {} }
10967
10969 2023, The QEMU Project Developers
109707.2.6 Sep 26, 2023 QEMU-STORAGE-DAEMON-QMP-REF(7)