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 • Background jobs
98 • Socket data types
100 • NetworkAddressFamily (Enum)
102 • InetSocketAddressBase (Object)
104 • InetSocketAddress (Object)
106 • UnixSocketAddress (Object)
108 • VsockSocketAddress (Object)
110 • InetSocketAddressWrapper (Object)
112 • UnixSocketAddressWrapper (Object)
114 • VsockSocketAddressWrapper (Object)
116 • StringWrapper (Object)
118 • SocketAddressLegacy (Object)
120 • SocketAddressType (Enum)
122 • SocketAddress (Object)
124 • SnapshotInfo (Object)
126 • ImageInfoSpecificQCow2EncryptionBase (Object)
128 • ImageInfoSpecificQCow2Encryption (Object)
130 • ImageInfoSpecificQCow2 (Object)
132 • ImageInfoSpecificVmdk (Object)
134 • ImageInfoSpecificRbd (Object)
136 • ImageInfoSpecificKind (Enum)
138 • ImageInfoSpecificQCow2Wrapper (Object)
140 • ImageInfoSpecificVmdkWrapper (Object)
142 • ImageInfoSpecificLUKSWrapper (Object)
144 • ImageInfoSpecificRbdWrapper (Object)
146 • ImageInfoSpecific (Object)
148 • ImageInfo (Object)
150 • ImageCheck (Object)
152 • MapEntry (Object)
154 • BlockdevCacheInfo (Object)
156 • BlockDeviceInfo (Object)
158 • BlockDeviceIoStatus (Enum)
160 • BlockDirtyInfo (Object)
162 • Qcow2BitmapInfoFlags (Enum)
164 • Qcow2BitmapInfo (Object)
166 • BlockLatencyHistogramInfo (Object)
168 • BlockInfo (Object)
170 • BlockMeasureInfo (Object)
172 • query-block (Command)
174 • BlockDeviceTimedStats (Object)
176 • BlockDeviceStats (Object)
178 • BlockStatsSpecificFile (Object)
180 • BlockStatsSpecificNvme (Object)
182 • BlockStatsSpecific (Object)
184 • BlockStats (Object)
186 • query-blockstats (Command)
188 • BlockdevOnError (Enum)
190 • MirrorSyncMode (Enum)
192 • BitmapSyncMode (Enum)
194 • MirrorCopyMode (Enum)
196 • BlockJobInfo (Object)
198 • query-block-jobs (Command)
200 • block_resize (Command)
202 • NewImageMode (Enum)
204 • BlockdevSnapshotSync (Object)
206 • BlockdevSnapshot (Object)
208 • BackupPerf (Object)
210 • BackupCommon (Object)
212 • DriveBackup (Object)
214 • BlockdevBackup (Object)
216 • blockdev-snapshot-sync (Command)
218 • blockdev-snapshot (Command)
220 • change-backing-file (Command)
222 • block-commit (Command)
224 • drive-backup (Command)
226 • blockdev-backup (Command)
228 • query-named-block-nodes (Command)
230 • XDbgBlockGraphNodeType (Enum)
232 • XDbgBlockGraphNode (Object)
234 • BlockPermission (Enum)
236 • XDbgBlockGraphEdge (Object)
238 • XDbgBlockGraph (Object)
240 • x-debug-query-block-graph (Command)
242 • drive-mirror (Command)
244 • DriveMirror (Object)
246 • BlockDirtyBitmap (Object)
248 • BlockDirtyBitmapAdd (Object)
250 • BlockDirtyBitmapMergeSource (Alternate)
252 • BlockDirtyBitmapMerge (Object)
254 • block-dirty-bitmap-add (Command)
256 • block-dirty-bitmap-remove (Command)
258 • block-dirty-bitmap-clear (Command)
260 • block-dirty-bitmap-enable (Command)
262 • block-dirty-bitmap-disable (Command)
264 • block-dirty-bitmap-merge (Command)
266 • BlockDirtyBitmapSha256 (Object)
268 • x-debug-block-dirty-bitmap-sha256 (Command)
270 • blockdev-mirror (Command)
272 • BlockIOThrottle (Object)
274 • ThrottleLimits (Object)
276 • ThrottleGroupProperties (Object)
278 • block-stream (Command)
280 • block-job-set-speed (Command)
282 • block-job-cancel (Command)
284 • block-job-pause (Command)
286 • block-job-resume (Command)
288 • block-job-complete (Command)
290 • block-job-dismiss (Command)
292 • block-job-finalize (Command)
294 • BlockdevDiscardOptions (Enum)
296 • BlockdevDetectZeroesOptions (Enum)
298 • BlockdevAioOptions (Enum)
300 • BlockdevCacheOptions (Object)
302 • BlockdevDriver (Enum)
304 • BlockdevOptionsFile (Object)
306 • BlockdevOptionsNull (Object)
308 • BlockdevOptionsNVMe (Object)
310 • BlockdevOptionsVVFAT (Object)
312 • BlockdevOptionsGenericFormat (Object)
314 • BlockdevOptionsLUKS (Object)
316 • BlockdevOptionsGenericCOWFormat (Object)
318 • Qcow2OverlapCheckMode (Enum)
320 • Qcow2OverlapCheckFlags (Object)
322 • Qcow2OverlapChecks (Alternate)
324 • BlockdevQcowEncryptionFormat (Enum)
326 • BlockdevQcowEncryption (Object)
328 • BlockdevOptionsQcow (Object)
330 • BlockdevQcow2EncryptionFormat (Enum)
332 • BlockdevQcow2Encryption (Object)
334 • BlockdevOptionsPreallocate (Object)
336 • BlockdevOptionsQcow2 (Object)
338 • SshHostKeyCheckMode (Enum)
340 • SshHostKeyCheckHashType (Enum)
342 • SshHostKeyHash (Object)
344 • SshHostKeyCheck (Object)
346 • BlockdevOptionsSsh (Object)
348 • BlkdebugEvent (Enum)
350 • BlkdebugIOType (Enum)
352 • BlkdebugInjectErrorOptions (Object)
354 • BlkdebugSetStateOptions (Object)
356 • BlockdevOptionsBlkdebug (Object)
358 • BlockdevOptionsBlklogwrites (Object)
360 • BlockdevOptionsBlkverify (Object)
362 • BlockdevOptionsBlkreplay (Object)
364 • QuorumReadPattern (Enum)
366 • BlockdevOptionsQuorum (Object)
368 • BlockdevOptionsGluster (Object)
370 • IscsiTransport (Enum)
372 • IscsiHeaderDigest (Enum)
374 • BlockdevOptionsIscsi (Object)
376 • RbdAuthMode (Enum)
378 • RbdImageEncryptionFormat (Enum)
380 • RbdEncryptionOptionsLUKSBase (Object)
382 • RbdEncryptionCreateOptionsLUKSBase (Object)
384 • RbdEncryptionOptionsLUKS (Object)
386 • RbdEncryptionOptionsLUKS2 (Object)
388 • RbdEncryptionCreateOptionsLUKS (Object)
390 • RbdEncryptionCreateOptionsLUKS2 (Object)
392 • RbdEncryptionOptions (Object)
394 • RbdEncryptionCreateOptions (Object)
396 • BlockdevOptionsRbd (Object)
398 • ReplicationMode (Enum)
400 • BlockdevOptionsReplication (Object)
402 • NFSTransport (Enum)
404 • NFSServer (Object)
406 • BlockdevOptionsNfs (Object)
408 • BlockdevOptionsCurlBase (Object)
410 • BlockdevOptionsCurlHttp (Object)
412 • BlockdevOptionsCurlHttps (Object)
414 • BlockdevOptionsCurlFtp (Object)
416 • BlockdevOptionsCurlFtps (Object)
418 • BlockdevOptionsNbd (Object)
420 • BlockdevOptionsRaw (Object)
422 • BlockdevOptionsThrottle (Object)
424 • BlockdevOptionsCor (Object)
426 • BlockdevOptionsCbw (Object)
428 • BlockdevOptions (Object)
430 • BlockdevRef (Alternate)
432 • BlockdevRefOrNull (Alternate)
434 • blockdev-add (Command)
436 • blockdev-reopen (Command)
438 • blockdev-del (Command)
440 • BlockdevCreateOptionsFile (Object)
442 • BlockdevCreateOptionsGluster (Object)
444 • BlockdevCreateOptionsLUKS (Object)
446 • BlockdevCreateOptionsNfs (Object)
448 • BlockdevCreateOptionsParallels (Object)
450 • BlockdevCreateOptionsQcow (Object)
452 • BlockdevQcow2Version (Enum)
454 • Qcow2CompressionType (Enum)
456 • BlockdevCreateOptionsQcow2 (Object)
458 • BlockdevCreateOptionsQed (Object)
460 • BlockdevCreateOptionsRbd (Object)
462 • BlockdevVmdkSubformat (Enum)
464 • BlockdevVmdkAdapterType (Enum)
466 • BlockdevCreateOptionsVmdk (Object)
468 • BlockdevCreateOptionsSsh (Object)
470 • BlockdevCreateOptionsVdi (Object)
472 • BlockdevVhdxSubformat (Enum)
474 • BlockdevCreateOptionsVhdx (Object)
476 • BlockdevVpcSubformat (Enum)
478 • BlockdevCreateOptionsVpc (Object)
480 • BlockdevCreateOptions (Object)
482 • blockdev-create (Command)
484 • BlockdevAmendOptionsLUKS (Object)
486 • BlockdevAmendOptionsQcow2 (Object)
488 • BlockdevAmendOptions (Object)
490 • x-blockdev-amend (Command)
492 • BlockErrorAction (Enum)
494 • BLOCK_IMAGE_CORRUPTED (Event)
496 • BLOCK_IO_ERROR (Event)
498 • BLOCK_JOB_COMPLETED (Event)
500 • BLOCK_JOB_CANCELLED (Event)
502 • BLOCK_JOB_ERROR (Event)
504 • BLOCK_JOB_READY (Event)
506 • BLOCK_JOB_PENDING (Event)
508 • PreallocMode (Enum)
510 • BLOCK_WRITE_THRESHOLD (Event)
512 • block-set-write-threshold (Command)
514 • x-blockdev-change (Command)
516 • x-blockdev-set-iothread (Command)
518 • QuorumOpType (Enum)
520 • QUORUM_FAILURE (Event)
522 • QUORUM_REPORT_BAD (Event)
524 • BlockdevSnapshotInternal (Object)
526 • blockdev-snapshot-internal-sync (Command)
528 • blockdev-snapshot-delete-internal-sync (Command)
530 • Block device exports
532 • Character devices
534 • ChardevInfo (Object)
536 • query-chardev (Command)
538 • ChardevBackendInfo (Object)
540 • query-chardev-backends (Command)
542 • DataFormat (Enum)
544 • ringbuf-write (Command)
546 • ringbuf-read (Command)
548 • ChardevCommon (Object)
550 • ChardevFile (Object)
552 • ChardevHostdev (Object)
554 • ChardevSocket (Object)
556 • ChardevUdp (Object)
558 • ChardevMux (Object)
560 • ChardevStdio (Object)
562 • ChardevSpiceChannel (Object)
564 • ChardevSpicePort (Object)
566 • ChardevDBus (Object)
568 • ChardevVC (Object)
570 • ChardevRingbuf (Object)
572 • ChardevQemuVDAgent (Object)
574 • ChardevBackendKind (Enum)
576 • ChardevFileWrapper (Object)
578 • ChardevHostdevWrapper (Object)
580 • ChardevSocketWrapper (Object)
582 • ChardevUdpWrapper (Object)
584 • ChardevCommonWrapper (Object)
586 • ChardevMuxWrapper (Object)
588 • ChardevStdioWrapper (Object)
590 • ChardevSpiceChannelWrapper (Object)
592 • ChardevSpicePortWrapper (Object)
594 • ChardevQemuVDAgentWrapper (Object)
596 • ChardevDBusWrapper (Object)
598 • ChardevVCWrapper (Object)
600 • ChardevRingbufWrapper (Object)
602 • ChardevBackend (Object)
604 • ChardevReturn (Object)
606 • chardev-add (Command)
608 • chardev-change (Command)
610 • chardev-remove (Command)
612 • chardev-send-break (Command)
614 • VSERPORT_CHANGE (Event)
616 • QMP monitor control
618 • qmp_capabilities (Command)
620 • QMPCapability (Enum)
622 • VersionTriple (Object)
624 • VersionInfo (Object)
626 • query-version (Command)
628 • CommandInfo (Object)
630 • query-commands (Command)
632 • quit (Command)
634 • MonitorMode (Enum)
636 • MonitorOptions (Object)
638 • QMP introspection
640 • query-qmp-schema (Command)
642 • SchemaMetaType (Enum)
644 • SchemaInfo (Object)
646 • SchemaInfoBuiltin (Object)
648 • JSONType (Enum)
650 • SchemaInfoEnum (Object)
652 • SchemaInfoEnumMember (Object)
654 • SchemaInfoArray (Object)
656 • SchemaInfoObject (Object)
658 • SchemaInfoObjectMember (Object)
660 • SchemaInfoObjectVariant (Object)
662 • SchemaInfoAlternate (Object)
664 • SchemaInfoAlternateMember (Object)
666 • SchemaInfoCommand (Object)
668 • SchemaInfoEvent (Object)
670 • User authorization
672 • QAuthZListPolicy (Enum)
674 • QAuthZListFormat (Enum)
676 • QAuthZListRule (Object)
678 • AuthZListProperties (Object)
680 • AuthZListFileProperties (Object)
682 • AuthZPAMProperties (Object)
684 • AuthZSimpleProperties (Object)
686 • QEMU Object Model (QOM)
688 • ObjectPropertyInfo (Object)
690 • qom-list (Command)
692 • qom-get (Command)
694 • qom-set (Command)
696 • ObjectTypeInfo (Object)
698 • qom-list-types (Command)
700 • qom-list-properties (Command)
702 • CanHostSocketcanProperties (Object)
704 • ColoCompareProperties (Object)
706 • CryptodevBackendProperties (Object)
708 • CryptodevVhostUserProperties (Object)
710 • DBusVMStateProperties (Object)
712 • NetfilterInsert (Enum)
714 • NetfilterProperties (Object)
716 • FilterBufferProperties (Object)
718 • FilterDumpProperties (Object)
720 • FilterMirrorProperties (Object)
722 • FilterRedirectorProperties (Object)
724 • FilterRewriterProperties (Object)
726 • InputBarrierProperties (Object)
728 • InputLinuxProperties (Object)
730 • IothreadProperties (Object)
732 • MemoryBackendProperties (Object)
734 • MemoryBackendFileProperties (Object)
736 • MemoryBackendMemfdProperties (Object)
738 • MemoryBackendEpcProperties (Object)
740 • PrManagerHelperProperties (Object)
742 • QtestProperties (Object)
744 • RemoteObjectProperties (Object)
746 • RngProperties (Object)
748 • RngEgdProperties (Object)
750 • RngRandomProperties (Object)
752 • SevGuestProperties (Object)
754 • ObjectType (Enum)
756 • ObjectOptions (Object)
758 • object-add (Command)
760 • object-del (Command)
762 • Transactions
764 • Abort (Object)
766 • ActionCompletionMode (Enum)
768 • TransactionActionKind (Enum)
770 • AbortWrapper (Object)
772 • BlockDirtyBitmapAddWrapper (Object)
774 • BlockDirtyBitmapWrapper (Object)
776 • BlockDirtyBitmapMergeWrapper (Object)
778 • BlockdevBackupWrapper (Object)
780 • BlockdevSnapshotWrapper (Object)
782 • BlockdevSnapshotInternalWrapper (Object)
784 • BlockdevSnapshotSyncWrapper (Object)
786 • DriveBackupWrapper (Object)
788 • TransactionAction (Object)
790 • TransactionProperties (Object)
792 • transaction (Command)
794
796 Block core (VM unrelated)
798 IoOperationType (Enum)
799 An enumeration of the I/O operation types
800 Values
802 read read operation
803 write write operation
805 Since
807 2.1
808 OnOffAuto (Enum)
810 An enumeration of three options: on, off, and auto
811 Values
813 auto QEMU selects the value between on and off
814 on Enabled
816 off Disabled
818 Since
820 2.2
821 OnOffSplit (Enum)
823 An enumeration of three values: on, off, and split
824 Values
826 on Enabled
827 off Disabled
829 split Mixed
831 Since
833 2.6
834 String (Object)
836 A fat type wrapping 'str', to be embedded in lists.
837 Members
839 str: string
840 Not documented
841 Since
843 1.2
844 StrOrNull (Alternate)
846 This is a string value or the explicit lack of a string (null pointer
847 in C). Intended for cases when 'optional absent' already has a differ‐
848 ent meaning.
849 Members
851 s: string
852 the string value
853 n: null
855 no string value
856 Since
858 2.10
859 OffAutoPCIBAR (Enum)
861 An enumeration of options for specifying a PCI BAR
862 Values
864 off The specified feature is disabled
865 auto The PCI BAR for the feature is automatically selected
867 bar0 PCI BAR0 is used for the feature
869 bar1 PCI BAR1 is used for the feature
871 bar2 PCI BAR2 is used for the feature
873 bar3 PCI BAR3 is used for the feature
875 bar4 PCI BAR4 is used for the feature
877 bar5 PCI BAR5 is used for the feature
879 Since
881 2.12
882 PCIELinkSpeed (Enum)
884 An enumeration of PCIe link speeds in units of GT/s
885 Values
887 2_5 2.5GT/s
888 5 5.0GT/s
890 8 8.0GT/s
892 16 16.0GT/s
894 Since
896 4.0
897 PCIELinkWidth (Enum)
899 An enumeration of PCIe link width
900 Values
902 1 x1
903 2 x2
905 4 x4
907 8 x8
909 12 x12
911 16 x16
913 32 x32
915 Since
917 4.0
918 HostMemPolicy (Enum)
920 Host memory policy types
921 Values
923 default
924 restore default policy, remove any nondefault policy
925 preferred
927 set the preferred host nodes for allocation
928 bind a strict policy that restricts memory allocation to the host
930 nodes specified
931 interleave
933 memory allocations are interleaved across the set of host nodes
934 specified
935 Since
937 2.1
938 NetFilterDirection (Enum)
940 Indicates whether a netfilter is attached to a netdev's transmit queue
941 or receive queue or both.
942 Values
944 all the filter is attached both to the receive and the transmit
945 queue of the netdev (default).
946 rx the filter is attached to the receive queue of the netdev, where
948 it will receive packets sent to the netdev.
949 tx the filter is attached to the transmit queue of the netdev,
951 where it will receive packets sent by the netdev.
952 Since
954 2.5
955 GrabToggleKeys (Enum)
957 Keys to toggle input-linux between host and guest.
958 Values
960 ctrl-ctrl
961 Not documented
962 alt-alt
964 Not documented
965 shift-shift
967 Not documented
968 meta-meta
970 Not documented
971 scrolllock
973 Not documented
974 ctrl-scrolllock
976 Not documented
977 Since
979 4.0
980 HumanReadableText (Object)
982 Members
983 human-readable-text: string
984 Formatted output intended for humans.
985 Since
987 6.2
988
990 QCryptoTLSCredsEndpoint (Enum)
991 The type of network endpoint that will be using the credentials. Most
992 types of credential require different setup / structures depending on
993 whether they will be used in a server versus a client.
994 Values
996 client the network endpoint is acting as the client
997 server the network endpoint is acting as the server
999 Since
1001 2.5
1002 QCryptoSecretFormat (Enum)
1004 The data format that the secret is provided in
1005 Values
1007 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
1008 be used
1009 base64 arbitrary base64 encoded binary data
1011 Since
1013 2.6
1014 QCryptoHashAlgorithm (Enum)
1016 The supported algorithms for computing content digests
1017 Values
1019 md5 MD5. Should not be used in any new code, legacy compat only
1020 sha1 SHA-1. Should not be used in any new code, legacy compat only
1022 sha224 SHA-224. (since 2.7)
1024 sha256 SHA-256. Current recommended strong hash.
1026 sha384 SHA-384. (since 2.7)
1028 sha512 SHA-512. (since 2.7)
1030 ripemd160
1032 RIPEMD-160. (since 2.7)
1033 Since
1035 2.6
1036 QCryptoCipherAlgorithm (Enum)
1038 The supported algorithms for content encryption ciphers
1039 Values
1041 aes-128
1042 AES with 128 bit / 16 byte keys
1043 aes-192
1045 AES with 192 bit / 24 byte keys
1046 aes-256
1048 AES with 256 bit / 32 byte keys
1049 des DES with 56 bit / 8 byte keys. Do not use except in VNC. (since
1051 6.1)
1052 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
1054 cast5-128
1056 Cast5 with 128 bit / 16 byte keys
1057 serpent-128
1059 Serpent with 128 bit / 16 byte keys
1060 serpent-192
1062 Serpent with 192 bit / 24 byte keys
1063 serpent-256
1065 Serpent with 256 bit / 32 byte keys
1066 twofish-128
1068 Twofish with 128 bit / 16 byte keys
1069 twofish-192
1071 Twofish with 192 bit / 24 byte keys
1072 twofish-256
1074 Twofish with 256 bit / 32 byte keys
1075 Since
1077 2.6
1078 QCryptoCipherMode (Enum)
1080 The supported modes for content encryption ciphers
1081 Values
1083 ecb Electronic Code Book
1084 cbc Cipher Block Chaining
1086 xts XEX with tweaked code book and ciphertext stealing
1088 ctr Counter (Since 2.8)
1090 Since
1092 2.6
1093 QCryptoIVGenAlgorithm (Enum)
1095 The supported algorithms for generating initialization vectors for full
1096 disk encryption. The 'plain' generator should not be used for disks
1097 with sector numbers larger than 2^32, except where compatibility with
1098 pre-existing Linux dm-crypt volumes is required.
1099 Values
1101 plain 64-bit sector number truncated to 32-bits
1102 plain64
1104 64-bit sector number
1105 essiv 64-bit sector number encrypted with a hash of the encryption key
1107 Since
1109 2.6
1110 QCryptoBlockFormat (Enum)
1112 The supported full disk encryption formats
1113 Values
1115 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
1116 data from old images.
1117 luks LUKS encryption format. Recommended for new images
1119 Since
1121 2.6
1122 QCryptoBlockOptionsBase (Object)
1124 The common options that apply to all full disk encryption formats
1125 Members
1127 format: QCryptoBlockFormat
1128 the encryption format
1129 Since
1131 2.6
1132 QCryptoBlockOptionsQCow (Object)
1134 The options that apply to QCow/QCow2 AES-CBC encryption format
1135 Members
1137 key-secret: string (optional)
1138 the ID of a QCryptoSecret object providing the decryption key.
1139 Mandatory except when probing image for metadata only.
1140 Since
1142 2.6
1143 QCryptoBlockOptionsLUKS (Object)
1145 The options that apply to LUKS encryption format
1146 Members
1148 key-secret: string (optional)
1149 the ID of a QCryptoSecret object providing the decryption key.
1150 Mandatory except when probing image for metadata only.
1151 Since
1153 2.6
1154 QCryptoBlockCreateOptionsLUKS (Object)
1156 The options that apply to LUKS encryption format initialization
1157 Members
1159 cipher-alg: QCryptoCipherAlgorithm (optional)
1160 the cipher algorithm for data encryption Currently defaults to
1161 'aes-256'.
1162 cipher-mode: QCryptoCipherMode (optional)
1164 the cipher mode for data encryption Currently defaults to 'xts'
1165 ivgen-alg: QCryptoIVGenAlgorithm (optional)
1167 the initialization vector generator Currently defaults to
1168 'plain64'
1169 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1171 the initialization vector generator hash Currently defaults to
1172 'sha256'
1173 hash-alg: QCryptoHashAlgorithm (optional)
1175 the master key hash algorithm Currently defaults to 'sha256'
1176 iter-time: int (optional)
1178 number of milliseconds to spend in PBKDF passphrase processing.
1179 Currently defaults to 2000. (since 2.8)
1180 The members of QCryptoBlockOptionsLUKS
1182 Since
1184 2.6
1185 QCryptoBlockOpenOptions (Object)
1187 The options that are available for all encryption formats when opening
1188 an existing volume
1189 Members
1191 The members of QCryptoBlockOptionsBase
1192 The members of QCryptoBlockOptionsQCow when format is "qcow"
1194 The members of QCryptoBlockOptionsLUKS when format is "luks"
1196 Since
1198 2.6
1199 QCryptoBlockCreateOptions (Object)
1201 The options that are available for all encryption formats when initial‐
1202 izing a new volume
1203 Members
1205 The members of QCryptoBlockOptionsBase
1206 The members of QCryptoBlockOptionsQCow when format is "qcow"
1208 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
1210 Since
1212 2.6
1213 QCryptoBlockInfoBase (Object)
1215 The common information that applies to all full disk encryption formats
1216 Members
1218 format: QCryptoBlockFormat
1219 the encryption format
1220 Since
1222 2.7
1223 QCryptoBlockInfoLUKSSlot (Object)
1225 Information about the LUKS block encryption key slot options
1226 Members
1228 active: boolean
1229 whether the key slot is currently in use
1230 key-offset: int
1232 offset to the key material in bytes
1233 iters: int (optional)
1235 number of PBKDF2 iterations for key material
1236 stripes: int (optional)
1238 number of stripes for splitting key material
1239 Since
1241 2.7
1242 QCryptoBlockInfoLUKS (Object)
1244 Information about the LUKS block encryption options
1245 Members
1247 cipher-alg: QCryptoCipherAlgorithm
1248 the cipher algorithm for data encryption
1249 cipher-mode: QCryptoCipherMode
1251 the cipher mode for data encryption
1252 ivgen-alg: QCryptoIVGenAlgorithm
1254 the initialization vector generator
1255 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1257 the initialization vector generator hash
1258 hash-alg: QCryptoHashAlgorithm
1260 the master key hash algorithm
1261 payload-offset: int
1263 offset to the payload data in bytes
1264 master-key-iters: int
1266 number of PBKDF2 iterations for key material
1267 uuid: string
1269 unique identifier for the volume
1270 slots: array of QCryptoBlockInfoLUKSSlot
1272 information about each key slot
1273 Since
1275 2.7
1276 QCryptoBlockInfo (Object)
1278 Information about the block encryption options
1279 Members
1281 The members of QCryptoBlockInfoBase
1282 The members of QCryptoBlockInfoLUKS when format is "luks"
1284 Since
1286 2.7
1287 QCryptoBlockLUKSKeyslotState (Enum)
1289 Defines state of keyslots that are affected by the update
1290 Values
1292 active The slots contain the given password and marked as active
1293 inactive
1295 The slots are erased (contain garbage) and marked as inactive
1296 Since
1298 5.1
1299 QCryptoBlockAmendOptionsLUKS (Object)
1301 This struct defines the update parameters that activate/de-activate set
1302 of keyslots
1303 Members
1305 state: QCryptoBlockLUKSKeyslotState
1306 the desired state of the keyslots
1307 new-secret: string (optional)
1309 The ID of a QCryptoSecret object providing the password to be
1310 written into added active keyslots
1311 old-secret: string (optional)
1313 Optional (for deactivation only) If given will deactivate all
1314 keyslots that match password located in QCryptoSecret with this
1315 ID
1316 iter-time: int (optional)
1318 Optional (for activation only) Number of milliseconds to spend
1319 in PBKDF passphrase processing for the newly activated keyslot.
1320 Currently defaults to 2000.
1321 keyslot: int (optional)
1323 Optional. ID of the keyslot to activate/deactivate. For keyslot
1324 activation, keyslot should not be active already (this is unsafe
1325 to update an active keyslot), but possible if 'force' parameter
1326 is given. If keyslot is not given, first free keyslot will be
1327 written.
1328 For keyslot deactivation, this parameter specifies the exact
1330 keyslot to deactivate
1331 secret: string (optional)
1333 Optional. The ID of a QCryptoSecret object providing the pass‐
1334 word to use to retrieve current master key. Defaults to the
1335 same secret that was used to open the image
1336 Since 5.1
1337 QCryptoBlockAmendOptions (Object)
1339 The options that are available for all encryption formats when amending
1340 encryption settings
1341 Members
1343 The members of QCryptoBlockOptionsBase
1344 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
1346 Since
1348 5.1
1349 SecretCommonProperties (Object)
1351 Properties for objects of classes derived from secret-common.
1352 Members
1354 loaded: boolean (optional)
1355 if true, the secret is loaded immediately when applying this op‐
1356 tion and will probably fail when processing the next option.
1357 Don't use; only provided for compatibility. (default: false)
1358 format: QCryptoSecretFormat (optional)
1360 the data format that the secret is provided in (default: raw)
1361 keyid: string (optional)
1363 the name of another secret that should be used to decrypt the
1364 provided data. If not present, the data is assumed to be unen‐
1365 crypted.
1366 iv: string (optional)
1368 the random initialization vector used for encryption of this
1369 particular secret. Should be a base64 encrypted string of the
1370 16-byte IV. Mandatory if keyid is given. Ignored if keyid is ab‐
1371 sent.
1372 Features
1374 deprecated
1375 Member loaded is deprecated. Setting true doesn't make sense,
1376 and false is already the default.
1377 Since
1379 2.6
1380 SecretProperties (Object)
1382 Properties for secret objects.
1383 Either data or file must be provided, but not both.
1385 Members
1387 data: string (optional)
1388 the associated with the secret from
1389 file: string (optional)
1391 the filename to load the data associated with the secret from
1392 The members of SecretCommonProperties
1394 Since
1396 2.6
1397 SecretKeyringProperties (Object)
1399 Properties for secret_keyring objects.
1400 Members
1402 serial: int
1403 serial number that identifies a key to get from the kernel
1404 The members of SecretCommonProperties
1406 Since
1408 5.1
1409 TlsCredsProperties (Object)
1411 Properties for objects of classes derived from tls-creds.
1412 Members
1414 verify-peer: boolean (optional)
1415 if true the peer credentials will be verified once the handshake
1416 is completed. This is a no-op for anonymous credentials. (de‐
1417 fault: true)
1418 dir: string (optional)
1420 the path of the directory that contains the credential files
1421 endpoint: QCryptoTLSCredsEndpoint (optional)
1423 whether the QEMU network backend that uses the credentials will
1424 be acting as a client or as a server (default: client)
1425 priority: string (optional)
1427 a gnutls priority string as described at
1428 https://gnutls.org/manual/html_node/Priority-Strings.html
1429 Since
1431 2.5
1432 TlsCredsAnonProperties (Object)
1434 Properties for tls-creds-anon objects.
1435 Members
1437 loaded: boolean (optional)
1438 if true, the credentials are loaded immediately when applying
1439 this option and will ignore options that are processed later.
1440 Don't use; only provided for compatibility. (default: false)
1441 The members of TlsCredsProperties
1443 Features
1445 deprecated
1446 Member loaded is deprecated. Setting true doesn't make sense,
1447 and false is already the default.
1448 Since
1450 2.5
1451 TlsCredsPskProperties (Object)
1453 Properties for tls-creds-psk objects.
1454 Members
1456 loaded: boolean (optional)
1457 if true, the credentials are loaded immediately when applying
1458 this option and will ignore options that are processed later.
1459 Don't use; only provided for compatibility. (default: false)
1460 username: string (optional)
1462 the username which will be sent to the server. For clients
1463 only. If absent, "qemu" is sent and the property will read back
1464 as an empty string.
1465 The members of TlsCredsProperties
1467 Features
1469 deprecated
1470 Member loaded is deprecated. Setting true doesn't make sense,
1471 and false is already the default.
1472 Since
1474 3.0
1475 TlsCredsX509Properties (Object)
1477 Properties for tls-creds-x509 objects.
1478 Members
1480 loaded: boolean (optional)
1481 if true, the credentials are loaded immediately when applying
1482 this option and will ignore options that are processed later.
1483 Don't use; only provided for compatibility. (default: false)
1484 sanity-check: boolean (optional)
1486 if true, perform some sanity checks before using the credentials
1487 (default: true)
1488 passwordid: string (optional)
1490 For the server-key.pem and client-key.pem files which contain
1491 sensitive private keys, it is possible to use an encrypted ver‐
1492 sion by providing the passwordid parameter. This provides the
1493 ID of a previously created secret object containing the password
1494 for decryption.
1495 The members of TlsCredsProperties
1497 Features
1499 deprecated
1500 Member loaded is deprecated. Setting true doesn't make sense,
1501 and false is already the default.
1502 Since
1504 2.5
1505 Background jobs
1507 JobType (Enum)
1508 Type of a background job.
1509 Values
1511 commit block commit job type, see "block-commit"
1512 stream block stream job type, see "block-stream"
1514 mirror drive mirror job type, see "drive-mirror"
1516 backup drive backup job type, see "drive-backup"
1518 create image creation job type, see "blockdev-create" (since 3.0)
1520 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
1522 snapshot-load
1524 snapshot load job type, see "snapshot-load" (since 6.0)
1525 snapshot-save
1527 snapshot save job type, see "snapshot-save" (since 6.0)
1528 snapshot-delete
1530 snapshot delete job type, see "snapshot-delete" (since 6.0)
1531 Since
1533 1.7
1534 JobStatus (Enum)
1536 Indicates the present state of a given job in its lifetime.
1537 Values
1539 undefined
1540 Erroneous, default state. Should not ever be visible.
1541 created
1543 The job has been created, but not yet started.
1544 running
1546 The job is currently running.
1547 paused The job is running, but paused. The pause may be requested by
1549 either the QMP user or by internal processes.
1550 ready The job is running, but is ready for the user to signal comple‐
1552 tion. This is used for long-running jobs like mirror that are
1553 designed to run indefinitely.
1554 standby
1556 The job is ready, but paused. This is nearly identical to
1557 paused. The job may return to ready or otherwise be canceled.
1558 waiting
1560 The job is waiting for other jobs in the transaction to converge
1561 to the waiting state. This status will likely not be visible for
1562 the last job in a transaction.
1563 pending
1565 The job has finished its work, but has finalization steps that
1566 it needs to make prior to completing. These changes will require
1567 manual intervention via job-finalize if auto-finalize was set to
1568 false. These pending changes may still fail.
1569 aborting
1571 The job is in the process of being aborted, and will finish with
1572 an error. The job will afterwards report that it is concluded.
1573 This status may not be visible to the management process.
1574 concluded
1576 The job has finished all work. If auto-dismiss was set to false,
1577 the job will remain in the query list until it is dismissed via
1578 job-dismiss.
1579 null The job is in the process of being dismantled. This state should
1581 not ever be visible externally.
1582 Since
1584 2.12
1585 JobVerb (Enum)
1587 Represents command verbs that can be applied to a job.
1588 Values
1590 cancel see job-cancel
1591 pause see job-pause
1593 resume see job-resume
1595 set-speed
1597 see block-job-set-speed
1598 complete
1600 see job-complete
1601 dismiss
1603 see job-dismiss
1604 finalize
1606 see job-finalize
1607 Since
1609 2.12
1610 JOB_STATUS_CHANGE (Event)
1612 Emitted when a job transitions to a different status.
1613 Arguments
1615 id: string
1616 The job identifier
1617 status: JobStatus
1619 The new job status
1620 Since
1622 3.0
1623 job-pause (Command)
1625 Pause an active job.
1626 This command returns immediately after marking the active job for paus‐
1628 ing. Pausing an already paused job is an error.
1629 The job will pause as soon as possible, which means transitioning into
1631 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
1632 The corresponding JOB_STATUS_CHANGE event will be emitted.
1633 Cancelling a paused job automatically resumes it.
1635 Arguments
1637 id: string
1638 The job identifier.
1639 Since
1641 3.0
1642 job-resume (Command)
1644 Resume a paused job.
1645 This command returns immediately after resuming a paused job. Resuming
1647 an already running job is an error.
1648 id : The job identifier.
1650 Arguments
1652 id: string
1653 Not documented
1654 Since
1656 3.0
1657 job-cancel (Command)
1659 Instruct an active background job to cancel at the next opportunity.
1660 This command returns immediately after marking the active job for can‐
1661 cellation.
1662 The job will cancel as soon as possible and then emit a JOB_STA‐
1664 TUS_CHANGE event. Usually, the status will change to ABORTING, but it
1665 is possible that a job successfully completes (e.g. because it was al‐
1666 most done and there was no opportunity to cancel earlier than complet‐
1667 ing the job) and transitions to PENDING instead.
1668 Arguments
1670 id: string
1671 The job identifier.
1672 Since
1674 3.0
1675 job-complete (Command)
1677 Manually trigger completion of an active job in the READY state.
1678 Arguments
1680 id: string
1681 The job identifier.
1682 Since
1684 3.0
1685 job-dismiss (Command)
1687 Deletes a job that is in the CONCLUDED state. This command only needs
1688 to be run explicitly for jobs that don't have automatic dismiss en‐
1689 abled.
1690 This command will refuse to operate on any job that has not yet reached
1692 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
1693 JOB_READY event, job-cancel or job-complete will still need to be used
1694 as appropriate.
1695 Arguments
1697 id: string
1698 The job identifier.
1699 Since
1701 3.0
1702 job-finalize (Command)
1704 Instructs all jobs in a transaction (or a single job if it is not part
1705 of any transaction) to finalize any graph changes and do any necessary
1706 cleanup. This command requires that all involved jobs are in the PEND‐
1707 ING state.
1708 For jobs in a transaction, instructing one job to finalize will force
1710 ALL jobs in the transaction to finalize, so it is only necessary to in‐
1711 struct a single member job to finalize.
1712 Arguments
1714 id: string
1715 The identifier of any job in the transaction, or of a job that
1716 is not part of any transaction.
1717 Since
1719 3.0
1720 JobInfo (Object)
1722 Information about a job.
1723 Members
1725 id: string
1726 The job identifier
1727 type: JobType
1729 The kind of job that is being performed
1730 status: JobStatus
1732 Current job state/status
1733 current-progress: int
1735 Progress made until now. The unit is arbitrary and the value can
1736 only meaningfully be used for the ratio of current-progress to
1737 total-progress. The value is monotonically increasing.
1738 total-progress: int
1740 Estimated current-progress value at the completion of the job.
1741 This value can arbitrarily change while the job is running, in
1742 both directions.
1743 error: string (optional)
1745 If this field is present, the job failed; if it is still missing
1746 in the CONCLUDED state, this indicates successful completion.
1747 The value is a human-readable error message to describe the rea‐
1749 son for the job failure. It should not be parsed by applica‐
1750 tions.
1751 Since
1753 3.0
1754 query-jobs (Command)
1756 Return information about jobs.
1757 Returns
1759 a list with a JobInfo for each active job
1760 Since
1762 3.0
1763
1765 NetworkAddressFamily (Enum)
1766 The network address family
1767 Values
1769 ipv4 IPV4 family
1770 ipv6 IPV6 family
1772 unix unix socket
1774 vsock vsock family (since 2.8)
1776 unknown
1778 otherwise
1779 Since
1781 2.1
1782 InetSocketAddressBase (Object)
1784 Members
1785 host: string
1786 host part of the address
1787 port: string
1789 port part of the address
1790 InetSocketAddress (Object)
1792 Captures a socket address or address range in the Internet namespace.
1793 Members
1795 numeric: boolean (optional)
1796 true if the host/port are guaranteed to be numeric, false if
1797 name resolution should be attempted. Defaults to false. (Since
1798 2.9)
1799 to: int (optional)
1801 If present, this is range of possible addresses, with port be‐
1802 tween port and to.
1803 ipv4: boolean (optional)
1805 whether to accept IPv4 addresses, default try both IPv4 and IPv6
1806 ipv6: boolean (optional)
1808 whether to accept IPv6 addresses, default try both IPv4 and IPv6
1809 keep-alive: boolean (optional)
1811 enable keep-alive when connecting to this socket. Not supported
1812 for passive sockets. (Since 4.2)
1813 mptcp: boolean (optional) (If: HAVE_IPPROTO_MPTCP)
1815 enable multi-path TCP. (Since 6.1)
1816 The members of InetSocketAddressBase
1818 Since
1820 1.3
1821 UnixSocketAddress (Object)
1823 Captures a socket address in the local ("Unix socket") namespace.
1824 Members
1826 path: string
1827 filesystem path to use
1828 abstract: boolean (optional) (If: CONFIG_LINUX)
1830 if true, this is a Linux abstract socket address. path will be
1831 prefixed by a null byte, and optionally padded with null bytes.
1832 Defaults to false. (Since 5.1)
1833 tight: boolean (optional) (If: CONFIG_LINUX)
1835 if false, pad an abstract socket address with enough null bytes
1836 to make it fill struct sockaddr_un member sun_path. Defaults to
1837 true. (Since 5.1)
1838 Since
1840 1.3
1841 VsockSocketAddress (Object)
1843 Captures a socket address in the vsock namespace.
1844 Members
1846 cid: string
1847 unique host identifier
1848 port: string
1850 port
1851 Note
1853 string types are used to allow for possible future hostname or service
1854 resolution support.
1855 Since
1857 2.8
1858 InetSocketAddressWrapper (Object)
1860 Members
1861 data: InetSocketAddress
1862 Not documented
1863 Since
1865 1.3
1866 UnixSocketAddressWrapper (Object)
1868 Members
1869 data: UnixSocketAddress
1870 Not documented
1871 Since
1873 1.3
1874 VsockSocketAddressWrapper (Object)
1876 Members
1877 data: VsockSocketAddress
1878 Not documented
1879 Since
1881 2.8
1882 StringWrapper (Object)
1884 Members
1885 data: String
1886 Not documented
1887 Since
1889 1.3
1890 SocketAddressLegacy (Object)
1892 Captures the address of a socket, which could also be a named file de‐
1893 scriptor
1894 Members
1896 type: SocketAddressType
1897 Not documented
1898 The members of InetSocketAddressWrapper when type is "inet"
1900 The members of UnixSocketAddressWrapper when type is "unix"
1902 The members of VsockSocketAddressWrapper when type is "vsock"
1904 The members of StringWrapper when type is "fd"
1906 Note
1908 This type is deprecated in favor of SocketAddress. The difference be‐
1909 tween SocketAddressLegacy and SocketAddress is that the latter is has
1910 fewer {} on the wire.
1911 Since
1913 1.3
1914 SocketAddressType (Enum)
1916 Available SocketAddress types
1917 Values
1919 inet Internet address
1920 unix Unix domain socket
1922 vsock VMCI address
1924 fd decimal is for file descriptor number, otherwise a file descrip‐
1926 tor name. Named file descriptors are permitted in monitor com‐
1927 mands, in combination with the 'getfd' command. Decimal file de‐
1928 scriptors are permitted at startup or other contexts where no
1929 monitor context is active.
1930 Since
1932 2.9
1933 SocketAddress (Object)
1935 Captures the address of a socket, which could also be a named file de‐
1936 scriptor
1937 Members
1939 type: SocketAddressType
1940 Transport type
1941 The members of InetSocketAddress when type is "inet"
1943 The members of UnixSocketAddress when type is "unix"
1945 The members of VsockSocketAddress when type is "vsock"
1947 The members of String when type is "fd"
1949 Since
1951 2.9
1952 SnapshotInfo (Object)
1954 Members
1955 id: string
1956 unique snapshot id
1957 name: string
1959 user chosen name
1960 vm-state-size: int
1962 size of the VM state
1963 date-sec: int
1965 UTC date of the snapshot in seconds
1966 date-nsec: int
1968 fractional part in nano seconds to be used with date-sec
1969 vm-clock-sec: int
1971 VM clock relative to boot in seconds
1972 vm-clock-nsec: int
1974 fractional part in nano seconds to be used with vm-clock-sec
1975 icount: int (optional)
1977 Current instruction count. Appears when execution record/replay
1978 is enabled. Used for "time-traveling" to match the moment in the
1979 recorded execution with the snapshots. This counter may be ob‐
1980 tained through query-replay command (since 5.2)
1981 Since
1983 1.3
1984 ImageInfoSpecificQCow2EncryptionBase (Object)
1986 Members
1987 format: BlockdevQcow2EncryptionFormat
1988 The encryption format
1989 Since
1991 2.10
1992 ImageInfoSpecificQCow2Encryption (Object)
1994 Members
1995 The members of ImageInfoSpecificQCow2EncryptionBase
1996 The members of QCryptoBlockInfoLUKS when format is "luks"
1998 Since
2000 2.10
2001 ImageInfoSpecificQCow2 (Object)
2003 Members
2004 compat: string
2005 compatibility level
2006 data-file: string (optional)
2008 the filename of the external data file that is stored in the im‐
2009 age and used as a default for opening the image (since: 4.0)
2010 data-file-raw: boolean (optional)
2012 True if the external data file must stay valid as a standalone
2013 (read-only) raw image without looking at qcow2 metadata (since:
2014 4.0)
2015 extended-l2: boolean (optional)
2017 true if the image has extended L2 entries; only valid for compat
2018 >= 1.1 (since 5.2)
2019 lazy-refcounts: boolean (optional)
2021 on or off; only valid for compat >= 1.1
2022 corrupt: boolean (optional)
2024 true if the image has been marked corrupt; only valid for compat
2025 >= 1.1 (since 2.2)
2026 refcount-bits: int
2028 width of a refcount entry in bits (since 2.3)
2029 encrypt: ImageInfoSpecificQCow2Encryption (optional)
2031 details about encryption parameters; only set if image is en‐
2032 crypted (since 2.10)
2033 bitmaps: array of Qcow2BitmapInfo (optional)
2035 A list of qcow2 bitmap details (since 4.0)
2036 compression-type: Qcow2CompressionType
2038 the image cluster compression method (since 5.1)
2039 Since
2041 1.7
2042 ImageInfoSpecificVmdk (Object)
2044 Members
2045 create-type: string
2046 The create type of VMDK image
2047 cid: int
2049 Content id of image
2050 parent-cid: int
2052 Parent VMDK image's cid
2053 extents: array of ImageInfo
2055 List of extent files
2056 Since
2058 1.7
2059 ImageInfoSpecificRbd (Object)
2061 Members
2062 encryption-format: RbdImageEncryptionFormat (optional)
2063 Image encryption format
2064 Since
2066 6.1
2067 ImageInfoSpecificKind (Enum)
2069 Values
2070 luks Since 2.7
2071 rbd Since 6.1
2073 qcow2 Not documented
2075 vmdk Not documented
2077 Since
2079 1.7
2080 ImageInfoSpecificQCow2Wrapper (Object)
2082 Members
2083 data: ImageInfoSpecificQCow2
2084 Not documented
2085 Since
2087 1.7
2088 ImageInfoSpecificVmdkWrapper (Object)
2090 Members
2091 data: ImageInfoSpecificVmdk
2092 Not documented
2093 Since
2095 6.1
2096 ImageInfoSpecificLUKSWrapper (Object)
2098 Members
2099 data: QCryptoBlockInfoLUKS
2100 Not documented
2101 Since
2103 2.7
2104 ImageInfoSpecificRbdWrapper (Object)
2106 Members
2107 data: ImageInfoSpecificRbd
2108 Not documented
2109 Since
2111 6.1
2112 ImageInfoSpecific (Object)
2114 A discriminated record of image format specific information structures.
2115 Members
2117 type: ImageInfoSpecificKind
2118 Not documented
2119 The members of ImageInfoSpecificQCow2Wrapper when type is "qcow2"
2121 The members of ImageInfoSpecificVmdkWrapper when type is "vmdk"
2123 The members of ImageInfoSpecificLUKSWrapper when type is "luks"
2125 The members of ImageInfoSpecificRbdWrapper when type is "rbd"
2127 Since
2129 1.7
2130 ImageInfo (Object)
2132 Information about a QEMU image file
2133 Members
2135 filename: string
2136 name of the image file
2137 format: string
2139 format of the image file
2140 virtual-size: int
2142 maximum capacity in bytes of the image
2143 actual-size: int (optional)
2145 actual size on disk in bytes of the image
2146 dirty-flag: boolean (optional)
2148 true if image is not cleanly closed
2149 cluster-size: int (optional)
2151 size of a cluster in bytes
2152 encrypted: boolean (optional)
2154 true if the image is encrypted
2155 compressed: boolean (optional)
2157 true if the image is compressed (Since 1.7)
2158 backing-filename: string (optional)
2160 name of the backing file
2161 full-backing-filename: string (optional)
2163 full path of the backing file
2164 backing-filename-format: string (optional)
2166 the format of the backing file
2167 snapshots: array of SnapshotInfo (optional)
2169 list of VM snapshots
2170 backing-image: ImageInfo (optional)
2172 info of the backing image (since 1.6)
2173 format-specific: ImageInfoSpecific (optional)
2175 structure supplying additional format-specific information
2176 (since 1.7)
2177 Since
2179 1.3
2180 ImageCheck (Object)
2182 Information about a QEMU image file check
2183 Members
2185 filename: string
2186 name of the image file checked
2187 format: string
2189 format of the image file checked
2190 check-errors: int
2192 number of unexpected errors occurred during check
2193 image-end-offset: int (optional)
2195 offset (in bytes) where the image ends, this field is present if
2196 the driver for the image format supports it
2197 corruptions: int (optional)
2199 number of corruptions found during the check if any
2200 leaks: int (optional)
2202 number of leaks found during the check if any
2203 corruptions-fixed: int (optional)
2205 number of corruptions fixed during the check if any
2206 leaks-fixed: int (optional)
2208 number of leaks fixed during the check if any
2209 total-clusters: int (optional)
2211 total number of clusters, this field is present if the driver
2212 for the image format supports it
2213 allocated-clusters: int (optional)
2215 total number of allocated clusters, this field is present if the
2216 driver for the image format supports it
2217 fragmented-clusters: int (optional)
2219 total number of fragmented clusters, this field is present if
2220 the driver for the image format supports it
2221 compressed-clusters: int (optional)
2223 total number of compressed clusters, this field is present if
2224 the driver for the image format supports it
2225 Since
2227 1.4
2228 MapEntry (Object)
2230 Mapping information from a virtual block range to a host file range
2231 Members
2233 start: int
2234 virtual (guest) offset of the first byte described by this entry
2235 length: int
2237 the number of bytes of the mapped virtual range
2238 data: boolean
2240 reading the image will actually read data from a file (in par‐
2241 ticular, if offset is present this means that the sectors are
2242 not simply preallocated, but contain actual data in raw format)
2243 zero: boolean
2245 whether the virtual blocks read as zeroes
2246 depth: int
2248 number of layers (0 = top image, 1 = top image's backing file,
2249 ..., n - 1 = bottom image (where n is the number of images in
2250 the chain)) before reaching one for which the range is allocated
2251 present: boolean
2253 true if this layer provides the data, false if adding a backing
2254 layer could impact this region (since 6.1)
2255 offset: int (optional)
2257 if present, the image file stores the data for this range in raw
2258 format at the given (host) offset
2259 filename: string (optional)
2261 filename that is referred to by offset
2262 Since
2264 2.6
2265 BlockdevCacheInfo (Object)
2267 Cache mode information for a block device
2268 Members
2270 writeback: boolean
2271 true if writeback mode is enabled
2272 direct: boolean
2274 true if the host page cache is bypassed (O_DIRECT)
2275 no-flush: boolean
2277 true if flush requests are ignored for the device
2278 Since
2280 2.3
2281 BlockDeviceInfo (Object)
2283 Information about the backing device for a block device.
2284 Members
2286 file: string
2287 the filename of the backing device
2288 node-name: string (optional)
2290 the name of the block driver node (Since 2.0)
2291 ro: boolean
2293 true if the backing device was open read-only
2294 drv: string
2296 the name of the block format used to open the backing device. As
2297 of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
2298 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
2299 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2',
2300 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added,
2301 'cow' dropped 2.3: 'host_floppy' deprecated 2.5: 'host_floppy'
2302 dropped 2.6: 'luks' added 2.8: 'replication' added, 'tftp'
2303 dropped 2.9: 'archipelago' dropped
2304 backing_file: string (optional)
2306 the name of the backing file (for copy-on-write)
2307 backing_file_depth: int
2309 number of files in the backing file chain (since: 1.2)
2310 encrypted: boolean
2312 true if the backing device is encrypted
2313 detect_zeroes: BlockdevDetectZeroesOptions
2315 detect and optimize zero writes (Since 2.1)
2316 bps: int
2318 total throughput limit in bytes per second is specified
2319 bps_rd: int
2321 read throughput limit in bytes per second is specified
2322 bps_wr: int
2324 write throughput limit in bytes per second is specified
2325 iops: int
2327 total I/O operations per second is specified
2328 iops_rd: int
2330 read I/O operations per second is specified
2331 iops_wr: int
2333 write I/O operations per second is specified
2334 image: ImageInfo
2336 the info of image used (since: 1.6)
2337 bps_max: int (optional)
2339 total throughput limit during bursts,
2341 in bytes (Since 1.7)
2342 bps_rd_max: int (optional)
2344 read throughput limit during bursts,
2346 in bytes (Since 1.7)
2347 bps_wr_max: int (optional)
2349 write throughput limit during bursts,
2351 in bytes (Since 1.7)
2352 iops_max: int (optional)
2354 total I/O operations per second during bursts,
2356 in bytes (Since 1.7)
2357 iops_rd_max: int (optional)
2359 read I/O operations per second during bursts,
2361 in bytes (Since 1.7)
2362 iops_wr_max: int (optional)
2364 write I/O operations per second during bursts,
2366 in bytes (Since 1.7)
2367 bps_max_length: int (optional)
2369 maximum length of the bps_max burst
2371 period, in seconds. (Since 2.6)
2372 bps_rd_max_length: int (optional)
2374 maximum length of the bps_rd_max
2376 burst period, in seconds. (Since 2.6)
2377 bps_wr_max_length: int (optional)
2379 maximum length of the bps_wr_max
2381 burst period, in seconds. (Since 2.6)
2382 iops_max_length: int (optional)
2384 maximum length of the iops burst
2386 period, in seconds. (Since 2.6)
2387 iops_rd_max_length: int (optional)
2389 maximum length of the iops_rd_max
2391 burst period, in seconds. (Since 2.6)
2392 iops_wr_max_length: int (optional)
2394 maximum length of the iops_wr_max
2396 burst period, in seconds. (Since 2.6)
2397 iops_size: int (optional)
2399 an I/O size in bytes (Since 1.7)
2400 group: string (optional)
2402 throttle group name (Since 2.4)
2403 cache: BlockdevCacheInfo
2405 the cache mode used for the block device (since: 2.3)
2406 write_threshold: int
2408 configured write threshold for the device. 0 if disabled.
2409 (Since 2.3)
2410 dirty-bitmaps: array of BlockDirtyInfo (optional)
2412 dirty bitmaps information (only present if node has one or more
2413 dirty bitmaps) (Since 4.2)
2414 Since
2416 0.14
2417 BlockDeviceIoStatus (Enum)
2419 An enumeration of block device I/O status.
2420 Values
2422 ok The last I/O operation has succeeded
2423 failed The last I/O operation has failed
2425 nospace
2427 The last I/O operation has failed due to a no-space condition
2428 Since
2430 1.0
2431 BlockDirtyInfo (Object)
2433 Block dirty bitmap information.
2434 Members
2436 name: string (optional)
2437 the name of the dirty bitmap (Since 2.4)
2438 count: int
2440 number of dirty bytes according to the dirty bitmap
2441 granularity: int
2443 granularity of the dirty bitmap in bytes (since 1.4)
2444 recording: boolean
2446 true if the bitmap is recording new writes from the guest. Re‐
2447 places active and disabled statuses. (since 4.0)
2448 busy: boolean
2450 true if the bitmap is in-use by some operation (NBD or jobs) and
2451 cannot be modified via QMP or used by another operation. Re‐
2452 places locked and frozen statuses. (since 4.0)
2453 persistent: boolean
2455 true if the bitmap was stored on disk, is scheduled to be stored
2456 on disk, or both. (since 4.0)
2457 inconsistent: boolean (optional)
2459 true if this is a persistent bitmap that was improperly stored.
2460 Implies persistent to be true; recording and busy to be false.
2461 This bitmap cannot be used. To remove it, use block-dirty-bit‐
2462 map-remove. (Since 4.0)
2463 Since
2465 1.3
2466 Qcow2BitmapInfoFlags (Enum)
2468 An enumeration of flags that a bitmap can report to the user.
2469 Values
2471 in-use This flag is set by any process actively modifying the qcow2
2472 file, and cleared when the updated bitmap is flushed to the
2473 qcow2 image. The presence of this flag in an offline image
2474 means that the bitmap was not saved correctly after its last us‐
2475 age, and may contain inconsistent data.
2476 auto The bitmap must reflect all changes of the virtual disk by any
2478 application that would write to this qcow2 file.
2479 Since
2481 4.0
2482 Qcow2BitmapInfo (Object)
2484 Qcow2 bitmap information.
2485 Members
2487 name: string
2488 the name of the bitmap
2489 granularity: int
2491 granularity of the bitmap in bytes
2492 flags: array of Qcow2BitmapInfoFlags
2494 flags of the bitmap
2495 Since
2497 4.0
2498 BlockLatencyHistogramInfo (Object)
2500 Block latency histogram.
2501 Members
2503 boundaries: array of int
2504 list of interval boundary values in nanoseconds, all greater
2505 than zero and in ascending order. For example, the list [10,
2506 50, 100] produces the following histogram intervals: [0, 10),
2507 [10, 50), [50, 100), [100, +inf).
2508 bins: array of int
2510 list of io request counts corresponding to histogram intervals.
2511 len(bins) = len(boundaries) + 1 For the example above, bins may
2512 be something like [3, 1, 5, 2], and corresponding histogram
2513 looks like:
2514 5| *
2516 4| *
2517 3| * *
2518 2| * * *
2519 1| * * * *
2520 +------------------
2521 10 50 100
2522 Since
2524 4.0
2525 BlockInfo (Object)
2527 Block device information. This structure describes a virtual device
2528 and the backing device associated with it.
2529 Members
2531 device: string
2532 The device name associated with the virtual device.
2533 qdev: string (optional)
2535 The qdev ID, or if no ID is assigned, the QOM path of the block
2536 device. (since 2.10)
2537 type: string
2539 This field is returned only for compatibility reasons, it should
2540 not be used (always returns 'unknown')
2541 removable: boolean
2543 True if the device supports removable media.
2544 locked: boolean
2546 True if the guest has locked this device from having its media
2547 removed
2548 tray_open: boolean (optional)
2550 True if the device's tray is open (only present if it has a
2551 tray)
2552 io-status: BlockDeviceIoStatus (optional)
2554 BlockDeviceIoStatus. Only present if the device supports it and
2555 the VM is configured to stop on errors (supported device models:
2556 virtio-blk, IDE, SCSI except scsi-generic)
2557 inserted: BlockDeviceInfo (optional)
2559 BlockDeviceInfo describing the device if media is present
2560 Since
2562 0.14
2563 BlockMeasureInfo (Object)
2565 Image file size calculation information. This structure describes the
2566 size requirements for creating a new image file.
2567 The size requirements depend on the new image file format. File size
2569 always equals virtual disk size for the 'raw' format, even for sparse
2570 POSIX files. Compact formats such as 'qcow2' represent unallocated and
2571 zero regions efficiently so file size may be smaller than virtual disk
2572 size.
2573 The values are upper bounds that are guaranteed to fit the new image
2575 file. Subsequent modification, such as internal snapshot or further
2576 bitmap creation, may require additional space and is not covered here.
2577 Members
2579 required: int
2580 Size required for a new image file, in bytes, when copying just
2581 allocated guest-visible contents.
2582 fully-allocated: int
2584 Image file size, in bytes, once data has been written to all
2585 sectors, when copying just guest-visible contents.
2586 bitmaps: int (optional)
2588 Additional size required if all the top-level bitmap metadata in
2589 the source image were to be copied to the destination, present
2590 only when source and destination both support persistent bit‐
2591 maps. (since 5.1)
2592 Since
2594 2.10
2595 query-block (Command)
2597 Get a list of BlockInfo for all virtual block devices.
2598 Returns
2600 a list of BlockInfo describing each virtual block device. Filter nodes
2601 that were created implicitly are skipped over.
2602 Since
2604 0.14
2605 Example
2607 -> { "execute": "query-block" }
2608 <- {
2609 "return":[
2610 {
2611 "io-status": "ok",
2612 "device":"ide0-hd0",
2613 "locked":false,
2614 "removable":false,
2615 "inserted":{
2616 "ro":false,
2617 "drv":"qcow2",
2618 "encrypted":false,
2619 "file":"disks/test.qcow2",
2620 "backing_file_depth":1,
2621 "bps":1000000,
2622 "bps_rd":0,
2623 "bps_wr":0,
2624 "iops":1000000,
2625 "iops_rd":0,
2626 "iops_wr":0,
2627 "bps_max": 8000000,
2628 "bps_rd_max": 0,
2629 "bps_wr_max": 0,
2630 "iops_max": 0,
2631 "iops_rd_max": 0,
2632 "iops_wr_max": 0,
2633 "iops_size": 0,
2634 "detect_zeroes": "on",
2635 "write_threshold": 0,
2636 "image":{
2637 "filename":"disks/test.qcow2",
2638 "format":"qcow2",
2639 "virtual-size":2048000,
2640 "backing_file":"base.qcow2",
2641 "full-backing-filename":"disks/base.qcow2",
2642 "backing-filename-format":"qcow2",
2643 "snapshots":[
2644 {
2645 "id": "1",
2646 "name": "snapshot1",
2647 "vm-state-size": 0,
2648 "date-sec": 10000200,
2649 "date-nsec": 12,
2650 "vm-clock-sec": 206,
2651 "vm-clock-nsec": 30
2652 }
2653 ],
2654 "backing-image":{
2655 "filename":"disks/base.qcow2",
2656 "format":"qcow2",
2657 "virtual-size":2048000
2658 }
2659 }
2660 },
2661 "qdev": "ide_disk",
2662 "type":"unknown"
2663 },
2664 {
2665 "io-status": "ok",
2666 "device":"ide1-cd0",
2667 "locked":false,
2668 "removable":true,
2669 "qdev": "/machine/unattached/device[23]",
2670 "tray_open": false,
2671 "type":"unknown"
2672 },
2673 {
2674 "device":"floppy0",
2675 "locked":false,
2676 "removable":true,
2677 "qdev": "/machine/unattached/device[20]",
2678 "type":"unknown"
2679 },
2680 {
2681 "device":"sd0",
2682 "locked":false,
2683 "removable":true,
2684 "type":"unknown"
2685 }
2686 ]
2687 }
2688 BlockDeviceTimedStats (Object)
2690 Statistics of a block device during a given interval of time.
2691 Members
2693 interval_length: int
2694 Interval used for calculating the statistics, in seconds.
2695 min_rd_latency_ns: int
2697 Minimum latency of read operations in the defined interval, in
2698 nanoseconds.
2699 min_wr_latency_ns: int
2701 Minimum latency of write operations in the defined interval, in
2702 nanoseconds.
2703 min_flush_latency_ns: int
2705 Minimum latency of flush operations in the defined interval, in
2706 nanoseconds.
2707 max_rd_latency_ns: int
2709 Maximum latency of read operations in the defined interval, in
2710 nanoseconds.
2711 max_wr_latency_ns: int
2713 Maximum latency of write operations in the defined interval, in
2714 nanoseconds.
2715 max_flush_latency_ns: int
2717 Maximum latency of flush operations in the defined interval, in
2718 nanoseconds.
2719 avg_rd_latency_ns: int
2721 Average latency of read operations in the defined interval, in
2722 nanoseconds.
2723 avg_wr_latency_ns: int
2725 Average latency of write operations in the defined interval, in
2726 nanoseconds.
2727 avg_flush_latency_ns: int
2729 Average latency of flush operations in the defined interval, in
2730 nanoseconds.
2731 avg_rd_queue_depth: number
2733 Average number of pending read operations in the defined inter‐
2734 val.
2735 avg_wr_queue_depth: number
2737 Average number of pending write operations in the defined inter‐
2738 val.
2739 Since
2741 2.5
2742 BlockDeviceStats (Object)
2744 Statistics of a virtual block device or a block backing device.
2745 Members
2747 rd_bytes: int
2748 The number of bytes read by the device.
2749 wr_bytes: int
2751 The number of bytes written by the device.
2752 unmap_bytes: int
2754 The number of bytes unmapped by the device (Since 4.2)
2755 rd_operations: int
2757 The number of read operations performed by the device.
2758 wr_operations: int
2760 The number of write operations performed by the device.
2761 flush_operations: int
2763 The number of cache flush operations performed by the device
2764 (since 0.15)
2765 unmap_operations: int
2767 The number of unmap operations performed by the device (Since
2768 4.2)
2769 rd_total_time_ns: int
2771 Total time spent on reads in nanoseconds (since 0.15).
2772 wr_total_time_ns: int
2774 Total time spent on writes in nanoseconds (since 0.15).
2775 flush_total_time_ns: int
2777 Total time spent on cache flushes in nanoseconds (since 0.15).
2778 unmap_total_time_ns: int
2780 Total time spent on unmap operations in nanoseconds (Since 4.2)
2781 wr_highest_offset: int
2783 The offset after the greatest byte written to the device. The
2784 intended use of this information is for growable sparse files
2785 (like qcow2) that are used on top of a physical device.
2786 rd_merged: int
2788 Number of read requests that have been merged into another re‐
2789 quest (Since 2.3).
2790 wr_merged: int
2792 Number of write requests that have been merged into another re‐
2793 quest (Since 2.3).
2794 unmap_merged: int
2796 Number of unmap requests that have been merged into another re‐
2797 quest (Since 4.2)
2798 idle_time_ns: int (optional)
2800 Time since the last I/O operation, in nanoseconds. If the field
2801 is absent it means that there haven't been any operations yet
2802 (Since 2.5).
2803 failed_rd_operations: int
2805 The number of failed read operations performed by the device
2806 (Since 2.5)
2807 failed_wr_operations: int
2809 The number of failed write operations performed by the device
2810 (Since 2.5)
2811 failed_flush_operations: int
2813 The number of failed flush operations performed by the device
2814 (Since 2.5)
2815 failed_unmap_operations: int
2817 The number of failed unmap operations performed by the device
2818 (Since 4.2)
2819 invalid_rd_operations: int
2821 The number of invalid read operations
2823 performed by the device (Since 2.5)
2824 invalid_wr_operations: int
2826 The number of invalid write operations performed by the device
2827 (Since 2.5)
2828 invalid_flush_operations: int
2830 The number of invalid flush operations performed by the device
2831 (Since 2.5)
2832 invalid_unmap_operations: int
2834 The number of invalid unmap operations performed by the device
2835 (Since 4.2)
2836 account_invalid: boolean
2838 Whether invalid operations are included in the last access sta‐
2839 tistics (Since 2.5)
2840 account_failed: boolean
2842 Whether failed operations are included in the latency and last
2843 access statistics (Since 2.5)
2844 timed_stats: array of BlockDeviceTimedStats
2846 Statistics specific to the set of previously defined intervals
2847 of time (Since 2.5)
2848 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
2850 BlockLatencyHistogramInfo. (Since 4.0)
2851 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
2853 BlockLatencyHistogramInfo. (Since 4.0)
2854 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
2856 BlockLatencyHistogramInfo. (Since 4.0)
2857 Since
2859 0.14
2860 BlockStatsSpecificFile (Object)
2862 File driver statistics
2863 Members
2865 discard-nb-ok: int
2866 The number of successful discard operations performed by the
2867 driver.
2868 discard-nb-failed: int
2870 The number of failed discard operations performed by the driver.
2871 discard-bytes-ok: int
2873 The number of bytes discarded by the driver.
2874 Since
2876 4.2
2877 BlockStatsSpecificNvme (Object)
2879 NVMe driver statistics
2880 Members
2882 completion-errors: int
2883 The number of completion errors.
2884 aligned-accesses: int
2886 The number of aligned accesses performed by the driver.
2887 unaligned-accesses: int
2889 The number of unaligned accesses performed by the driver.
2890 Since
2892 5.2
2893 BlockStatsSpecific (Object)
2895 Block driver specific statistics
2896 Members
2898 driver: BlockdevDriver
2899 Not documented
2900 The members of BlockStatsSpecificFile when driver is "file"
2902 The members of BlockStatsSpecificFile when driver is "host_device" (If:
2904 HAVE_HOST_BLOCK_DEVICE)
2905 The members of BlockStatsSpecificNvme when driver is "nvme"
2907 Since
2909 4.2
2910 BlockStats (Object)
2912 Statistics of a virtual block device or a block backing device.
2913 Members
2915 device: string (optional)
2916 If the stats are for a virtual block device, the name corre‐
2917 sponding to the virtual block device.
2918 node-name: string (optional)
2920 The node name of the device. (Since 2.3)
2921 qdev: string (optional)
2923 The qdev ID, or if no ID is assigned, the QOM path of the block
2924 device. (since 3.0)
2925 stats: BlockDeviceStats
2927 A BlockDeviceStats for the device.
2928 driver-specific: BlockStatsSpecific (optional)
2930 Optional driver-specific stats. (Since 4.2)
2931 parent: BlockStats (optional)
2933 This describes the file block device if it has one. Contains
2934 recursively the statistics of the underlying protocol (e.g. the
2935 host file for a qcow2 image). If there is no underlying proto‐
2936 col, this field is omitted
2937 backing: BlockStats (optional)
2939 This describes the backing block device if it has one. (Since
2940 2.0)
2941 Since
2943 0.14
2944 query-blockstats (Command)
2946 Query the BlockStats for all virtual block devices.
2947 Arguments
2949 query-nodes: boolean (optional)
2950 If true, the command will query all the block nodes that have a
2951 node name, in a list which will include "parent" information,
2952 but not "backing". If false or omitted, the behavior is as be‐
2953 fore - query all the device backends, recursively including
2954 their "parent" and "backing". Filter nodes that were created im‐
2955 plicitly are skipped over in this mode. (Since 2.3)
2956 Returns
2958 A list of BlockStats for each virtual block devices.
2959 Since
2961 0.14
2962 Example
2964 -> { "execute": "query-blockstats" }
2965 <- {
2966 "return":[
2967 {
2968 "device":"ide0-hd0",
2969 "parent":{
2970 "stats":{
2971 "wr_highest_offset":3686448128,
2972 "wr_bytes":9786368,
2973 "wr_operations":751,
2974 "rd_bytes":122567168,
2975 "rd_operations":36772
2976 "wr_total_times_ns":313253456
2977 "rd_total_times_ns":3465673657
2978 "flush_total_times_ns":49653
2979 "flush_operations":61,
2980 "rd_merged":0,
2981 "wr_merged":0,
2982 "idle_time_ns":2953431879,
2983 "account_invalid":true,
2984 "account_failed":false
2985 }
2986 },
2987 "stats":{
2988 "wr_highest_offset":2821110784,
2989 "wr_bytes":9786368,
2990 "wr_operations":692,
2991 "rd_bytes":122739200,
2992 "rd_operations":36604
2993 "flush_operations":51,
2994 "wr_total_times_ns":313253456
2995 "rd_total_times_ns":3465673657
2996 "flush_total_times_ns":49653,
2997 "rd_merged":0,
2998 "wr_merged":0,
2999 "idle_time_ns":2953431879,
3000 "account_invalid":true,
3001 "account_failed":false
3002 },
3003 "qdev": "/machine/unattached/device[23]"
3004 },
3005 {
3006 "device":"ide1-cd0",
3007 "stats":{
3008 "wr_highest_offset":0,
3009 "wr_bytes":0,
3010 "wr_operations":0,
3011 "rd_bytes":0,
3012 "rd_operations":0
3013 "flush_operations":0,
3014 "wr_total_times_ns":0
3015 "rd_total_times_ns":0
3016 "flush_total_times_ns":0,
3017 "rd_merged":0,
3018 "wr_merged":0,
3019 "account_invalid":false,
3020 "account_failed":false
3021 },
3022 "qdev": "/machine/unattached/device[24]"
3023 },
3024 {
3025 "device":"floppy0",
3026 "stats":{
3027 "wr_highest_offset":0,
3028 "wr_bytes":0,
3029 "wr_operations":0,
3030 "rd_bytes":0,
3031 "rd_operations":0
3032 "flush_operations":0,
3033 "wr_total_times_ns":0
3034 "rd_total_times_ns":0
3035 "flush_total_times_ns":0,
3036 "rd_merged":0,
3037 "wr_merged":0,
3038 "account_invalid":false,
3039 "account_failed":false
3040 },
3041 "qdev": "/machine/unattached/device[16]"
3042 },
3043 {
3044 "device":"sd0",
3045 "stats":{
3046 "wr_highest_offset":0,
3047 "wr_bytes":0,
3048 "wr_operations":0,
3049 "rd_bytes":0,
3050 "rd_operations":0
3051 "flush_operations":0,
3052 "wr_total_times_ns":0
3053 "rd_total_times_ns":0
3054 "flush_total_times_ns":0,
3055 "rd_merged":0,
3056 "wr_merged":0,
3057 "account_invalid":false,
3058 "account_failed":false
3059 }
3060 }
3061 ]
3062 }
3063 BlockdevOnError (Enum)
3065 An enumeration of possible behaviors for errors on I/O operations. The
3066 exact meaning depends on whether the I/O was initiated by a guest or by
3067 a block job
3068 Values
3070 report for guest operations, report the error to the guest; for jobs,
3071 cancel the job
3072 ignore ignore the error, only report a QMP event (BLOCK_IO_ERROR or
3074 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
3075 the failing request later and may still complete successfully.
3076 The stream block job continues to stream and will complete with
3077 an error.
3078 enospc same as stop on ENOSPC, same as report otherwise.
3080 stop for guest operations, stop the virtual machine; for jobs, pause
3082 the job
3083 auto inherit the error handling policy of the backend (since: 2.7)
3085 Since
3087 1.3
3088 MirrorSyncMode (Enum)
3090 An enumeration of possible behaviors for the initial synchronization
3091 phase of storage mirroring.
3092 Values
3094 top copies data in the topmost image to the destination
3095 full copies data from all images to the destination
3097 none only copy data written from now on
3099 incremental
3101 only copy data described by the dirty bitmap. (since: 2.4)
3102 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
3104 havior on completion is determined by the BitmapSyncMode.
3105 Since
3107 1.3
3108 BitmapSyncMode (Enum)
3110 An enumeration of possible behaviors for the synchronization of a bit‐
3111 map when used for data copy operations.
3112 Values
3114 on-success
3115 The bitmap is only synced when the operation is successful.
3116 This is the behavior always used for 'INCREMENTAL' backups.
3117 never The bitmap is never synchronized with the operation, and is
3119 treated solely as a read-only manifest of blocks to copy.
3120 always The bitmap is always synchronized with the operation, regardless
3122 of whether or not the operation was successful.
3123 Since
3125 4.2
3126 MirrorCopyMode (Enum)
3128 An enumeration whose values tell the mirror block job when to trigger
3129 writes to the target.
3130 Values
3132 background
3133 copy data in background only.
3134 write-blocking
3136 when data is written to the source, write it (synchronously) to
3137 the target as well. In addition, data is copied in background
3138 just like in background mode.
3139 Since
3141 3.0
3142 BlockJobInfo (Object)
3144 Information about a long-running block device operation.
3145 Members
3147 type: string
3148 the job type ('stream' for image streaming)
3149 device: string
3151 The job identifier. Originally the device name but other values
3152 are allowed since QEMU 2.7
3153 len: int
3155 Estimated offset value at the completion of the job. This value
3156 can arbitrarily change while the job is running, in both direc‐
3157 tions.
3158 offset: int
3160 Progress made until now. The unit is arbitrary and the value can
3161 only meaningfully be used for the ratio of offset to len. The
3162 value is monotonically increasing.
3163 busy: boolean
3165 false if the job is known to be in a quiescent state, with no
3166 pending I/O. Since 1.3.
3167 paused: boolean
3169 whether the job is paused or, if busy is true, will pause itself
3170 as soon as possible. Since 1.3.
3171 speed: int
3173 the rate limit, bytes per second
3174 io-status: BlockDeviceIoStatus
3176 the status of the job (since 1.3)
3177 ready: boolean
3179 true if the job may be completed (since 2.2)
3180 status: JobStatus
3182 Current job state/status (since 2.12)
3183 auto-finalize: boolean
3185 Job will finalize itself when PENDING, moving to the CONCLUDED
3186 state. (since 2.12)
3187 auto-dismiss: boolean
3189 Job will dismiss itself when CONCLUDED, moving to the NULL state
3190 and disappearing from the query list. (since 2.12)
3191 error: string (optional)
3193 Error information if the job did not complete successfully. Not
3194 set if the job completed successfully. (since 2.12.1)
3195 Since
3197 1.1
3198 query-block-jobs (Command)
3200 Return information about long-running block device operations.
3201 Returns
3203 a list of BlockJobInfo for each active block job
3204 Since
3206 1.1
3207 block_resize (Command)
3209 Resize a block image while a guest is running.
3210 Either device or node-name must be set but not both.
3212 Arguments
3214 device: string (optional)
3215 the name of the device to get the image resized
3216 node-name: string (optional)
3218 graph node name to get the image resized (Since 2.0)
3219 size: int
3221 new image size in bytes
3222 Returns
3224 • nothing on success
3225 • If device is not a valid block device, DeviceNotFound
3227 Since
3229 0.14
3230 Example
3232 -> { "execute": "block_resize",
3233 "arguments": { "device": "scratch", "size": 1073741824 } }
3234 <- { "return": {} }
3235 NewImageMode (Enum)
3237 An enumeration that tells QEMU how to set the backing file path in a
3238 new image file.
3239 Values
3241 existing
3242 QEMU should look for an existing image file.
3243 absolute-paths
3245 QEMU should create a new image with absolute paths for the back‐
3246 ing file. If there is no backing file available, the new image
3247 will not be backed either.
3248 Since
3250 1.1
3251 BlockdevSnapshotSync (Object)
3253 Either device or node-name must be set but not both.
3254 Members
3256 device: string (optional)
3257 the name of the device to take a snapshot of.
3258 node-name: string (optional)
3260 graph node name to generate the snapshot from (Since 2.0)
3261 snapshot-file: string
3263 the target of the new overlay image. If the file exists, or if
3264 it is a device, the overlay will be created in the existing
3265 file/device. Otherwise, a new file will be created.
3266 snapshot-node-name: string (optional)
3268 the graph node name of the new image (Since 2.0)
3269 format: string (optional)
3271 the format of the overlay image, default is 'qcow2'.
3272 mode: NewImageMode (optional)
3274 whether and how QEMU should create a new image, default is 'ab‐
3275 solute-paths'.
3276 BlockdevSnapshot (Object)
3278 Members
3279 node: string
3280 device or node name that will have a snapshot taken.
3281 overlay: string
3283 reference to the existing block device that will become the
3284 overlay of node, as part of taking the snapshot. It must not
3285 have a current backing file (this can be achieved by passing
3286 "backing": null to blockdev-add).
3287 Since
3289 2.5
3290 BackupPerf (Object)
3292 Optional parameters for backup. These parameters don't affect function‐
3293 ality, but may significantly affect performance.
3294 Members
3296 use-copy-range: boolean (optional)
3297 Use copy offloading. Default false.
3298 max-workers: int (optional)
3300 Maximum number of parallel requests for the sustained background
3301 copying process. Doesn't influence copy-before-write operations.
3302 Default 64.
3303 max-chunk: int (optional)
3305 Maximum request length for the sustained background copying
3306 process. Doesn't influence copy-before-write operations. 0
3307 means unlimited. If max-chunk is non-zero then it should not be
3308 less than job cluster size which is calculated as maximum of
3309 target image cluster size and 64k. Default 0.
3310 Since
3312 6.0
3313 BackupCommon (Object)
3315 Members
3316 job-id: string (optional)
3317 identifier for the newly-created block job. If omitted, the de‐
3318 vice name will be used. (Since 2.7)
3319 device: string
3321 the device name or node-name of a root node which should be
3322 copied.
3323 sync: MirrorSyncMode
3325 what parts of the disk image should be copied to the destination
3326 (all the disk, only the sectors allocated in the topmost image,
3327 from a dirty bitmap, or only new I/O).
3328 speed: int (optional)
3330 the maximum speed, in bytes per second. The default is 0, for
3331 unlimited.
3332 bitmap: string (optional)
3334 The name of a dirty bitmap to use. Must be present if sync is
3335 "bitmap" or "incremental". Can be present if sync is "full" or
3336 "top". Must not be present otherwise. (Since 2.4
3337 (drive-backup), 3.1 (blockdev-backup))
3338 bitmap-mode: BitmapSyncMode (optional)
3340 Specifies the type of data the bitmap should contain after the
3341 operation concludes. Must be present if a bitmap was provided,
3342 Must NOT be present otherwise. (Since 4.2)
3343 compress: boolean (optional)
3345 true to compress data, if the target format supports it. (de‐
3346 fault: false) (since 2.8)
3347 on-source-error: BlockdevOnError (optional)
3349 the action to take on an error on the source, default 'report'.
3350 'stop' and 'enospc' can only be used if the block device sup‐
3351 ports io-status (see BlockInfo).
3352 on-target-error: BlockdevOnError (optional)
3354 the action to take on an error on the target, default 'report'
3355 (no limitations, since this applies to a different block device
3356 than device).
3357 auto-finalize: boolean (optional)
3359 When false, this job will wait in a PENDING state after it has
3360 finished its work, waiting for block-job-finalize before making
3361 any block graph changes. When true, this job will automatically
3362 perform its abort or commit actions. Defaults to true. (Since
3363 2.12)
3364 auto-dismiss: boolean (optional)
3366 When false, this job will wait in a CONCLUDED state after it has
3367 completely ceased all work, and awaits block-job-dismiss. When
3368 true, this job will automatically disappear from the query list
3369 without user intervention. Defaults to true. (Since 2.12)
3370 filter-node-name: string (optional)
3372 the node name that should be assigned to the filter driver that
3373 the backup job inserts into the graph above node specified by
3374 drive. If this option is not given, a node name is autogener‐
3375 ated. (Since: 4.2)
3376 x-perf: BackupPerf (optional)
3378 Performance options. (Since 6.0)
3379 Features
3381 unstable
3382 Member x-perf is experimental.
3383 Note
3385 on-source-error and on-target-error only affect background I/O. If an
3386 error occurs during a guest write request, the device's rerror/werror
3387 actions will be used.
3388 Since
3390 4.2
3391 DriveBackup (Object)
3393 Members
3394 target: string
3395 the target of the new image. If the file exists, or if it is a
3396 device, the existing file/device will be used as the new desti‐
3397 nation. If it does not exist, a new file will be created.
3398 format: string (optional)
3400 the format of the new destination, default is to probe if mode
3401 is 'existing', else the format of the source
3402 mode: NewImageMode (optional)
3404 whether and how QEMU should create a new image, default is 'ab‐
3405 solute-paths'.
3406 The members of BackupCommon
3408 Since
3410 1.6
3411 BlockdevBackup (Object)
3413 Members
3414 target: string
3415 the device name or node-name of the backup target node.
3416 The members of BackupCommon
3418 Since
3420 2.3
3421 blockdev-snapshot-sync (Command)
3423 Takes a synchronous snapshot of a block device.
3424 For the arguments, see the documentation of BlockdevSnapshotSync.
3426 Returns
3428 • nothing on success
3429 • If device is not a valid block device, DeviceNotFound
3431 Since
3433 0.14
3434 Example
3436 -> { "execute": "blockdev-snapshot-sync",
3437 "arguments": { "device": "ide-hd0",
3438 "snapshot-file":
3439 "/some/place/my-image",
3440 "format": "qcow2" } }
3441 <- { "return": {} }
3442 blockdev-snapshot (Command)
3444 Takes a snapshot of a block device.
3445 Take a snapshot, by installing 'node' as the backing image of 'over‐
3447 lay'. Additionally, if 'node' is associated with a block device, the
3448 block device changes to using 'overlay' as its new active image.
3449 For the arguments, see the documentation of BlockdevSnapshot.
3451 Features
3453 allow-write-only-overlay
3454 If present, the check whether this operation is safe was relaxed
3455 so that it can be used to change backing file of a destination
3456 of a blockdev-mirror. (since 5.0)
3457 Since
3459 2.5
3460 Example
3462 -> { "execute": "blockdev-add",
3463 "arguments": { "driver": "qcow2",
3464 "node-name": "node1534",
3465 "file": { "driver": "file",
3466 "filename": "hd1.qcow2" },
3467 "backing": null } }
3468 <- { "return": {} }
3470 -> { "execute": "blockdev-snapshot",
3472 "arguments": { "node": "ide-hd0",
3473 "overlay": "node1534" } }
3474 <- { "return": {} }
3475 change-backing-file (Command)
3477 Change the backing file in the image file metadata. This does not
3478 cause QEMU to reopen the image file to reparse the backing filename (it
3479 may, however, perform a reopen to change permissions from r/o -> r/w ->
3480 r/o, if needed). The new backing file string is written into the image
3481 file metadata, and the QEMU internal strings are updated.
3482 Arguments
3484 image-node-name: string
3485 The name of the block driver state node of the image to modify.
3486 The "device" argument is used to verify "image-node-name" is in
3487 the chain described by "device".
3488 device: string
3490 The device name or node-name of the root node that owns im‐
3491 age-node-name.
3492 backing-file: string
3494 The string to write as the backing file. This string is not
3495 validated, so care should be taken when specifying the string or
3496 the image chain may not be able to be reopened again.
3497 Returns
3499 • Nothing on success
3500 • If "device" does not exist or cannot be determined, DeviceNotFound
3502 Since
3504 2.1
3505 block-commit (Command)
3507 Live commit of data from overlay image nodes into backing nodes - i.e.,
3508 writes data between 'top' and 'base' into 'base'.
3509 If top == base, that is an error. If top has no overlays on top of it,
3511 or if it is in use by a writer, the job will not be completed by it‐
3512 self. The user needs to complete the job with the block-job-complete
3513 command after getting the ready event. (Since 2.0)
3514 If the base image is smaller than top, then the base image will be re‐
3516 sized to be the same size as top. If top is smaller than the base im‐
3517 age, the base will not be truncated. If you want the base image size
3518 to match the size of the smaller top, you can safely truncate it your‐
3519 self once the commit operation successfully completes.
3520 Arguments
3522 job-id: string (optional)
3523 identifier for the newly-created block job. If omitted, the de‐
3524 vice name will be used. (Since 2.7)
3525 device: string
3527 the device name or node-name of a root node
3528 base-node: string (optional)
3530 The node name of the backing image to write data into. If not
3531 specified, this is the deepest backing image. (since: 3.1)
3532 base: string (optional)
3534 Same as base-node, except that it is a file name rather than a
3535 node name. This must be the exact filename string that was used
3536 to open the node; other strings, even if addressing the same
3537 file, are not accepted
3538 top-node: string (optional)
3540 The node name of the backing image within the image chain which
3541 contains the topmost data to be committed down. If not speci‐
3542 fied, this is the active layer. (since: 3.1)
3543 top: string (optional)
3545 Same as top-node, except that it is a file name rather than a
3546 node name. This must be the exact filename string that was used
3547 to open the node; other strings, even if addressing the same
3548 file, are not accepted
3549 backing-file: string (optional)
3551 The backing file string to write into the overlay image of
3552 'top'. If 'top' does not have an overlay image, or if 'top' is
3553 in use by a writer, specifying a backing file string is an er‐
3554 ror.
3555 This filename is not validated. If a pathname string is such
3557 that it cannot be resolved by QEMU, that means that subsequent
3558 QMP or HMP commands must use node-names for the image in ques‐
3559 tion, as filename lookup methods will fail.
3560 If not specified, QEMU will automatically determine the backing
3562 file string to use, or error out if there is no obvious choice.
3563 Care should be taken when specifying the string, to specify a
3564 valid filename or protocol. (Since 2.1)
3565 speed: int (optional)
3567 the maximum speed, in bytes per second
3568 on-error: BlockdevOnError (optional)
3570 the action to take on an error. 'ignore' means that the request
3571 should be retried. (default: report; Since: 5.0)
3572 filter-node-name: string (optional)
3574 the node name that should be assigned to the filter driver that
3575 the commit job inserts into the graph above top. If this option
3576 is not given, a node name is autogenerated. (Since: 2.9)
3577 auto-finalize: boolean (optional)
3579 When false, this job will wait in a PENDING state after it has
3580 finished its work, waiting for block-job-finalize before making
3581 any block graph changes. When true, this job will automatically
3582 perform its abort or commit actions. Defaults to true. (Since
3583 3.1)
3584 auto-dismiss: boolean (optional)
3586 When false, this job will wait in a CONCLUDED state after it has
3587 completely ceased all work, and awaits block-job-dismiss. When
3588 true, this job will automatically disappear from the query list
3589 without user intervention. Defaults to true. (Since 3.1)
3590 Features
3592 deprecated
3593 Members base and top are deprecated. Use base-node and top-node
3594 instead.
3595 Returns
3597 • Nothing on success
3598 • If device does not exist, DeviceNotFound
3600 • Any other error returns a GenericError.
3602 Since
3604 1.3
3605 Example
3607 -> { "execute": "block-commit",
3608 "arguments": { "device": "virtio0",
3609 "top": "/tmp/snap1.qcow2" } }
3610 <- { "return": {} }
3611 drive-backup (Command)
3613 Start a point-in-time copy of a block device to a new destination. The
3614 status of ongoing drive-backup operations can be checked with
3615 query-block-jobs where the BlockJobInfo.type field has the value
3616 'backup'. The operation can be stopped before it has completed using
3617 the block-job-cancel command.
3618 Arguments
3620 The members of DriveBackup
3621 Features
3623 deprecated
3624 This command is deprecated. Use blockdev-backup instead.
3625 Returns
3627 • nothing on success
3628 • If device is not a valid block device, GenericError
3630 Since
3632 1.6
3633 Example
3635 -> { "execute": "drive-backup",
3636 "arguments": { "device": "drive0",
3637 "sync": "full",
3638 "target": "backup.img" } }
3639 <- { "return": {} }
3640 blockdev-backup (Command)
3642 Start a point-in-time copy of a block device to a new destination. The
3643 status of ongoing blockdev-backup operations can be checked with
3644 query-block-jobs where the BlockJobInfo.type field has the value
3645 'backup'. The operation can be stopped before it has completed using
3646 the block-job-cancel command.
3647 Arguments
3649 The members of BlockdevBackup
3650 Returns
3652 • nothing on success
3653 • If device is not a valid block device, DeviceNotFound
3655 Since
3657 2.3
3658 Example
3660 -> { "execute": "blockdev-backup",
3661 "arguments": { "device": "src-id",
3662 "sync": "full",
3663 "target": "tgt-id" } }
3664 <- { "return": {} }
3665 query-named-block-nodes (Command)
3667 Get the named block driver list
3668 Arguments
3670 flat: boolean (optional)
3671 Omit the nested data about backing image ("backing-image" key)
3672 if true. Default is false (Since 5.0)
3673 Returns
3675 the list of BlockDeviceInfo
3676 Since
3678 2.0
3679 Example
3681 -> { "execute": "query-named-block-nodes" }
3682 <- { "return": [ { "ro":false,
3683 "drv":"qcow2",
3684 "encrypted":false,
3685 "file":"disks/test.qcow2",
3686 "node-name": "my-node",
3687 "backing_file_depth":1,
3688 "detect_zeroes":"off",
3689 "bps":1000000,
3690 "bps_rd":0,
3691 "bps_wr":0,
3692 "iops":1000000,
3693 "iops_rd":0,
3694 "iops_wr":0,
3695 "bps_max": 8000000,
3696 "bps_rd_max": 0,
3697 "bps_wr_max": 0,
3698 "iops_max": 0,
3699 "iops_rd_max": 0,
3700 "iops_wr_max": 0,
3701 "iops_size": 0,
3702 "write_threshold": 0,
3703 "image":{
3704 "filename":"disks/test.qcow2",
3705 "format":"qcow2",
3706 "virtual-size":2048000,
3707 "backing_file":"base.qcow2",
3708 "full-backing-filename":"disks/base.qcow2",
3709 "backing-filename-format":"qcow2",
3710 "snapshots":[
3711 {
3712 "id": "1",
3713 "name": "snapshot1",
3714 "vm-state-size": 0,
3715 "date-sec": 10000200,
3716 "date-nsec": 12,
3717 "vm-clock-sec": 206,
3718 "vm-clock-nsec": 30
3719 }
3720 ],
3721 "backing-image":{
3722 "filename":"disks/base.qcow2",
3723 "format":"qcow2",
3724 "virtual-size":2048000
3725 }
3726 } } ] }
3727 XDbgBlockGraphNodeType (Enum)
3729 Values
3730 block-backend
3731 corresponds to BlockBackend
3732 block-job
3734 corresponds to BlockJob
3735 block-driver
3737 corresponds to BlockDriverState
3738 Since
3740 4.0
3741 XDbgBlockGraphNode (Object)
3743 Members
3744 id: int
3745 Block graph node identifier. This id is generated only for x-de‐
3746 bug-query-block-graph and does not relate to any other identi‐
3747 fiers in Qemu.
3748 type: XDbgBlockGraphNodeType
3750 Type of graph node. Can be one of block-backend, block-job or
3751 block-driver-state.
3752 name: string
3754 Human readable name of the node. Corresponds to node-name for
3755 block-driver-state nodes; is not guaranteed to be unique in the
3756 whole graph (with block-jobs and block-backends).
3757 Since
3759 4.0
3760 BlockPermission (Enum)
3762 Enum of base block permissions.
3763 Values
3765 consistent-read
3766 A user that has the "permission" of consistent reads is guaran‐
3767 teed that their view of the contents of the block device is com‐
3768 plete and self-consistent, representing the contents of a disk
3769 at a specific point. For most block devices (including their
3770 backing files) this is true, but the property cannot be main‐
3771 tained in a few situations like for intermediate nodes of a com‐
3772 mit block job.
3773 write This permission is required to change the visible disk contents.
3775 write-unchanged
3777 This permission (which is weaker than BLK_PERM_WRITE) is both
3778 enough and required for writes to the block node when the caller
3779 promises that the visible disk content doesn't change. As the
3780 BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
3781 cient to perform an unchanging write.
3782 resize This permission is required to change the size of a block node.
3784 Since
3786 4.0
3787 XDbgBlockGraphEdge (Object)
3789 Block Graph edge description for x-debug-query-block-graph.
3790 Members
3792 parent: int
3793 parent id
3794 child: int
3796 child id
3797 name: string
3799 name of the relation (examples are 'file' and 'backing')
3800 perm: array of BlockPermission
3802 granted permissions for the parent operating on the child
3803 shared-perm: array of BlockPermission
3805 permissions that can still be granted to other users of the
3806 child while it is still attached to this parent
3807 Since
3809 4.0
3810 XDbgBlockGraph (Object)
3812 Block Graph - list of nodes and list of edges.
3813 Members
3815 nodes: array of XDbgBlockGraphNode
3816 Not documented
3817 edges: array of XDbgBlockGraphEdge
3819 Not documented
3820 Since
3822 4.0
3823 x-debug-query-block-graph (Command)
3825 Get the block graph.
3826 Features
3828 unstable
3829 This command is meant for debugging.
3830 Since
3832 4.0
3833 drive-mirror (Command)
3835 Start mirroring a block device's writes to a new destination. target
3836 specifies the target of the new image. If the file exists, or if it is
3837 a device, it will be used as the new destination for writes. If it does
3838 not exist, a new file will be created. format specifies the format of
3839 the mirror image, default is to probe if mode='existing', else the for‐
3840 mat of the source.
3841 Arguments
3843 The members of DriveMirror
3844 Returns
3846 • nothing on success
3847 • If device is not a valid block device, GenericError
3849 Since
3851 1.3
3852 Example
3854 -> { "execute": "drive-mirror",
3855 "arguments": { "device": "ide-hd0",
3856 "target": "/some/place/my-image",
3857 "sync": "full",
3858 "format": "qcow2" } }
3859 <- { "return": {} }
3860 DriveMirror (Object)
3862 A set of parameters describing drive mirror setup.
3863 Members
3865 job-id: string (optional)
3866 identifier for the newly-created block job. If omitted, the de‐
3867 vice name will be used. (Since 2.7)
3868 device: string
3870 the device name or node-name of a root node whose writes should
3871 be mirrored.
3872 target: string
3874 the target of the new image. If the file exists, or if it is a
3875 device, the existing file/device will be used as the new desti‐
3876 nation. If it does not exist, a new file will be created.
3877 format: string (optional)
3879 the format of the new destination, default is to probe if mode
3880 is 'existing', else the format of the source
3881 node-name: string (optional)
3883 the new block driver state node name in the graph (Since 2.1)
3884 replaces: string (optional)
3886 with sync=full graph node name to be replaced by the new image
3887 when a whole image copy is done. This can be used to repair bro‐
3888 ken Quorum files. By default, device is replaced, although im‐
3889 plicitly created filters on it are kept. (Since 2.1)
3890 mode: NewImageMode (optional)
3892 whether and how QEMU should create a new image, default is 'ab‐
3893 solute-paths'.
3894 speed: int (optional)
3896 the maximum speed, in bytes per second
3897 sync: MirrorSyncMode
3899 what parts of the disk image should be copied to the destination
3900 (all the disk, only the sectors allocated in the topmost image,
3901 or only new I/O).
3902 granularity: int (optional)
3904 granularity of the dirty bitmap, default is 64K if the image
3905 format doesn't have clusters, 4K if the clusters are smaller
3906 than that, else the cluster size. Must be a power of 2 between
3907 512 and 64M (since 1.4).
3908 buf-size: int (optional)
3910 maximum amount of data in flight from source to target (since
3911 1.4).
3912 on-source-error: BlockdevOnError (optional)
3914 the action to take on an error on the source, default 'report'.
3915 'stop' and 'enospc' can only be used if the block device sup‐
3916 ports io-status (see BlockInfo).
3917 on-target-error: BlockdevOnError (optional)
3919 the action to take on an error on the target, default 'report'
3920 (no limitations, since this applies to a different block device
3921 than device).
3922 unmap: boolean (optional)
3924 Whether to try to unmap target sectors where source has only
3925 zero. If true, and target unallocated sectors will read as zero,
3926 target image sectors will be unmapped; otherwise, zeroes will be
3927 written. Both will result in identical contents. Default is
3928 true. (Since 2.4)
3929 copy-mode: MirrorCopyMode (optional)
3931 when to copy data to the destination; defaults to 'background'
3932 (Since: 3.0)
3933 auto-finalize: boolean (optional)
3935 When false, this job will wait in a PENDING state after it has
3936 finished its work, waiting for block-job-finalize before making
3937 any block graph changes. When true, this job will automatically
3938 perform its abort or commit actions. Defaults to true. (Since
3939 3.1)
3940 auto-dismiss: boolean (optional)
3942 When false, this job will wait in a CONCLUDED state after it has
3943 completely ceased all work, and awaits block-job-dismiss. When
3944 true, this job will automatically disappear from the query list
3945 without user intervention. Defaults to true. (Since 3.1)
3946 Since
3948 1.3
3949 BlockDirtyBitmap (Object)
3951 Members
3952 node: string
3953 name of device/node which the bitmap is tracking
3954 name: string
3956 name of the dirty bitmap
3957 Since
3959 2.4
3960 BlockDirtyBitmapAdd (Object)
3962 Members
3963 node: string
3964 name of device/node which the bitmap is tracking
3965 name: string
3967 name of the dirty bitmap (must be less than 1024 bytes)
3968 granularity: int (optional)
3970 the bitmap granularity, default is 64k for block-dirty-bit‐
3971 map-add
3972 persistent: boolean (optional)
3974 the bitmap is persistent, i.e. it will be saved to the corre‐
3975 sponding block device image file on its close. For now only
3976 Qcow2 disks support persistent bitmaps. Default is false for
3977 block-dirty-bitmap-add. (Since: 2.10)
3978 disabled: boolean (optional)
3980 the bitmap is created in the disabled state, which means that it
3981 will not track drive changes. The bitmap may be enabled with
3982 block-dirty-bitmap-enable. Default is false. (Since: 4.0)
3983 Since
3985 2.4
3986 BlockDirtyBitmapMergeSource (Alternate)
3988 Members
3989 local: string
3990 name of the bitmap, attached to the same node as target bitmap.
3991 external: BlockDirtyBitmap
3993 bitmap with specified node
3994 Since
3996 4.1
3997 BlockDirtyBitmapMerge (Object)
3999 Members
4000 node: string
4001 name of device/node which the target bitmap is tracking
4002 target: string
4004 name of the destination dirty bitmap
4005 bitmaps: array of BlockDirtyBitmapMergeSource
4007 name(s) of the source dirty bitmap(s) at node and/or fully spec‐
4008 ified BlockDirtyBitmap elements. The latter are supported since
4009 4.1.
4010 Since
4012 4.0
4013 block-dirty-bitmap-add (Command)
4015 Create a dirty bitmap with a name on the node, and start tracking the
4016 writes.
4017 Returns
4019 • nothing on success
4020 • If node is not a valid block device or node, DeviceNotFound
4022 • If name is already taken, GenericError with an explanation
4024 Since
4026 2.4
4027 Example
4029 -> { "execute": "block-dirty-bitmap-add",
4030 "arguments": { "node": "drive0", "name": "bitmap0" } }
4031 <- { "return": {} }
4032 block-dirty-bitmap-remove (Command)
4034 Stop write tracking and remove the dirty bitmap that was created with
4035 block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
4036 storage too.
4037 Returns
4039 • nothing on success
4040 • If node is not a valid block device or node, DeviceNotFound
4042 • If name is not found, GenericError with an explanation
4044 • if name is frozen by an operation, GenericError
4046 Since
4048 2.4
4049 Example
4051 -> { "execute": "block-dirty-bitmap-remove",
4052 "arguments": { "node": "drive0", "name": "bitmap0" } }
4053 <- { "return": {} }
4054 block-dirty-bitmap-clear (Command)
4056 Clear (reset) a dirty bitmap on the device, so that an incremental
4057 backup from this point in time forward will only backup clusters modi‐
4058 fied after this clear operation.
4059 Returns
4061 • nothing on success
4062 • If node is not a valid block device, DeviceNotFound
4064 • If name is not found, GenericError with an explanation
4066 Since
4068 2.4
4069 Example
4071 -> { "execute": "block-dirty-bitmap-clear",
4072 "arguments": { "node": "drive0", "name": "bitmap0" } }
4073 <- { "return": {} }
4074 block-dirty-bitmap-enable (Command)
4076 Enables a dirty bitmap so that it will begin tracking disk changes.
4077 Returns
4079 • nothing on success
4080 • If node is not a valid block device, DeviceNotFound
4082 • If name is not found, GenericError with an explanation
4084 Since
4086 4.0
4087 Example
4089 -> { "execute": "block-dirty-bitmap-enable",
4090 "arguments": { "node": "drive0", "name": "bitmap0" } }
4091 <- { "return": {} }
4092 block-dirty-bitmap-disable (Command)
4094 Disables a dirty bitmap so that it will stop tracking disk changes.
4095 Returns
4097 • nothing on success
4098 • If node is not a valid block device, DeviceNotFound
4100 • If name is not found, GenericError with an explanation
4102 Since
4104 4.0
4105 Example
4107 -> { "execute": "block-dirty-bitmap-disable",
4108 "arguments": { "node": "drive0", "name": "bitmap0" } }
4109 <- { "return": {} }
4110 block-dirty-bitmap-merge (Command)
4112 Merge dirty bitmaps listed in bitmaps to the target dirty bitmap.
4113 Dirty bitmaps in bitmaps will be unchanged, except if it also appears
4114 as the target bitmap. Any bits already set in target will still be set
4115 after the merge, i.e., this operation does not clear the target. On
4116 error, target is unchanged.
4117 The resulting bitmap will count as dirty any clusters that were dirty
4119 in any of the source bitmaps. This can be used to achieve backup check‐
4120 points, or in simpler usages, to copy bitmaps.
4121 Returns
4123 • nothing on success
4124 • If node is not a valid block device, DeviceNotFound
4126 • If any bitmap in bitmaps or target is not found, GenericError
4128 • If any of the bitmaps have different sizes or granularities, Gener‐
4130 icError
4131 Since
4133 4.0
4134 Example
4136 -> { "execute": "block-dirty-bitmap-merge",
4137 "arguments": { "node": "drive0", "target": "bitmap0",
4138 "bitmaps": ["bitmap1"] } }
4139 <- { "return": {} }
4140 BlockDirtyBitmapSha256 (Object)
4142 SHA256 hash of dirty bitmap data
4143 Members
4145 sha256: string
4146 ASCII representation of SHA256 bitmap hash
4147 Since
4149 2.10
4150 x-debug-block-dirty-bitmap-sha256 (Command)
4152 Get bitmap SHA256.
4153 Features
4155 unstable
4156 This command is meant for debugging.
4157 Returns
4159 • BlockDirtyBitmapSha256 on success
4160 • If node is not a valid block device, DeviceNotFound
4162 • If name is not found or if hashing has failed, GenericError with an
4164 explanation
4165 Since
4167 2.10
4168 blockdev-mirror (Command)
4170 Start mirroring a block device's writes to a new destination.
4171 Arguments
4173 job-id: string (optional)
4174 identifier for the newly-created block job. If omitted, the de‐
4175 vice name will be used. (Since 2.7)
4176 device: string
4178 The device name or node-name of a root node whose writes should
4179 be mirrored.
4180 target: string
4182 the id or node-name of the block device to mirror to. This
4183 mustn't be attached to guest.
4184 replaces: string (optional)
4186 with sync=full graph node name to be replaced by the new image
4187 when a whole image copy is done. This can be used to repair bro‐
4188 ken Quorum files. By default, device is replaced, although im‐
4189 plicitly created filters on it are kept.
4190 speed: int (optional)
4192 the maximum speed, in bytes per second
4193 sync: MirrorSyncMode
4195 what parts of the disk image should be copied to the destination
4196 (all the disk, only the sectors allocated in the topmost image,
4197 or only new I/O).
4198 granularity: int (optional)
4200 granularity of the dirty bitmap, default is 64K if the image
4201 format doesn't have clusters, 4K if the clusters are smaller
4202 than that, else the cluster size. Must be a power of 2 between
4203 512 and 64M
4204 buf-size: int (optional)
4206 maximum amount of data in flight from source to target
4207 on-source-error: BlockdevOnError (optional)
4209 the action to take on an error on the source, default 'report'.
4210 'stop' and 'enospc' can only be used if the block device sup‐
4211 ports io-status (see BlockInfo).
4212 on-target-error: BlockdevOnError (optional)
4214 the action to take on an error on the target, default 'report'
4215 (no limitations, since this applies to a different block device
4216 than device).
4217 filter-node-name: string (optional)
4219 the node name that should be assigned to the filter driver that
4220 the mirror job inserts into the graph above device. If this op‐
4221 tion is not given, a node name is autogenerated. (Since: 2.9)
4222 copy-mode: MirrorCopyMode (optional)
4224 when to copy data to the destination; defaults to 'background'
4225 (Since: 3.0)
4226 auto-finalize: boolean (optional)
4228 When false, this job will wait in a PENDING state after it has
4229 finished its work, waiting for block-job-finalize before making
4230 any block graph changes. When true, this job will automatically
4231 perform its abort or commit actions. Defaults to true. (Since
4232 3.1)
4233 auto-dismiss: boolean (optional)
4235 When false, this job will wait in a CONCLUDED state after it has
4236 completely ceased all work, and awaits block-job-dismiss. When
4237 true, this job will automatically disappear from the query list
4238 without user intervention. Defaults to true. (Since 3.1)
4239 Returns
4241 nothing on success.
4242 Since
4244 2.6
4245 Example
4247 -> { "execute": "blockdev-mirror",
4248 "arguments": { "device": "ide-hd0",
4249 "target": "target0",
4250 "sync": "full" } }
4251 <- { "return": {} }
4252 BlockIOThrottle (Object)
4254 A set of parameters describing block throttling.
4255 Members
4257 device: string (optional)
4258 Block device name
4259 id: string (optional)
4261 The name or QOM path of the guest device (since: 2.8)
4262 bps: int
4264 total throughput limit in bytes per second
4265 bps_rd: int
4267 read throughput limit in bytes per second
4268 bps_wr: int
4270 write throughput limit in bytes per second
4271 iops: int
4273 total I/O operations per second
4274 iops_rd: int
4276 read I/O operations per second
4277 iops_wr: int
4279 write I/O operations per second
4280 bps_max: int (optional)
4282 total throughput limit during bursts, in bytes (Since 1.7)
4283 bps_rd_max: int (optional)
4285 read throughput limit during bursts, in bytes (Since 1.7)
4286 bps_wr_max: int (optional)
4288 write throughput limit during bursts, in bytes (Since 1.7)
4289 iops_max: int (optional)
4291 total I/O operations per second during bursts, in bytes (Since
4292 1.7)
4293 iops_rd_max: int (optional)
4295 read I/O operations per second during bursts, in bytes (Since
4296 1.7)
4297 iops_wr_max: int (optional)
4299 write I/O operations per second during bursts, in bytes (Since
4300 1.7)
4301 bps_max_length: int (optional)
4303 maximum length of the bps_max burst period, in seconds. It must
4304 only be set if bps_max is set as well. Defaults to 1. (Since
4305 2.6)
4306 bps_rd_max_length: int (optional)
4308 maximum length of the bps_rd_max burst period, in seconds. It
4309 must only be set if bps_rd_max is set as well. Defaults to 1.
4310 (Since 2.6)
4311 bps_wr_max_length: int (optional)
4313 maximum length of the bps_wr_max burst period, in seconds. It
4314 must only be set if bps_wr_max is set as well. Defaults to 1.
4315 (Since 2.6)
4316 iops_max_length: int (optional)
4318 maximum length of the iops burst period, in seconds. It must
4319 only be set if iops_max is set as well. Defaults to 1. (Since
4320 2.6)
4321 iops_rd_max_length: int (optional)
4323 maximum length of the iops_rd_max burst period, in seconds. It
4324 must only be set if iops_rd_max is set as well. Defaults to 1.
4325 (Since 2.6)
4326 iops_wr_max_length: int (optional)
4328 maximum length of the iops_wr_max burst period, in seconds. It
4329 must only be set if iops_wr_max is set as well. Defaults to 1.
4330 (Since 2.6)
4331 iops_size: int (optional)
4333 an I/O size in bytes (Since 1.7)
4334 group: string (optional)
4336 throttle group name (Since 2.4)
4337 Features
4339 deprecated
4340 Member device is deprecated. Use id instead.
4341 Since
4343 1.1
4344 ThrottleLimits (Object)
4346 Limit parameters for throttling. Since some limit combinations are il‐
4347 legal, limits should always be set in one transaction. All fields are
4348 optional. When setting limits, if a field is missing the current value
4349 is not changed.
4350 Members
4352 iops-total: int (optional)
4353 limit total I/O operations per second
4354 iops-total-max: int (optional)
4356 I/O operations burst
4357 iops-total-max-length: int (optional)
4359 length of the iops-total-max burst period, in seconds It must
4360 only be set if iops-total-max is set as well.
4361 iops-read: int (optional)
4363 limit read operations per second
4364 iops-read-max: int (optional)
4366 I/O operations read burst
4367 iops-read-max-length: int (optional)
4369 length of the iops-read-max burst period, in seconds It must
4370 only be set if iops-read-max is set as well.
4371 iops-write: int (optional)
4373 limit write operations per second
4374 iops-write-max: int (optional)
4376 I/O operations write burst
4377 iops-write-max-length: int (optional)
4379 length of the iops-write-max burst period, in seconds It must
4380 only be set if iops-write-max is set as well.
4381 bps-total: int (optional)
4383 limit total bytes per second
4384 bps-total-max: int (optional)
4386 total bytes burst
4387 bps-total-max-length: int (optional)
4389 length of the bps-total-max burst period, in seconds. It must
4390 only be set if bps-total-max is set as well.
4391 bps-read: int (optional)
4393 limit read bytes per second
4394 bps-read-max: int (optional)
4396 total bytes read burst
4397 bps-read-max-length: int (optional)
4399 length of the bps-read-max burst period, in seconds It must only
4400 be set if bps-read-max is set as well.
4401 bps-write: int (optional)
4403 limit write bytes per second
4404 bps-write-max: int (optional)
4406 total bytes write burst
4407 bps-write-max-length: int (optional)
4409 length of the bps-write-max burst period, in seconds It must
4410 only be set if bps-write-max is set as well.
4411 iops-size: int (optional)
4413 when limiting by iops max size of an I/O in bytes
4414 Since
4416 2.11
4417 ThrottleGroupProperties (Object)
4419 Properties for throttle-group objects.
4420 Members
4422 limits: ThrottleLimits (optional)
4423 limits to apply for this throttle group
4424 x-iops-total: int (optional)
4426 Not documented
4427 x-iops-total-max: int (optional)
4429 Not documented
4430 x-iops-total-max-length: int (optional)
4432 Not documented
4433 x-iops-read: int (optional)
4435 Not documented
4436 x-iops-read-max: int (optional)
4438 Not documented
4439 x-iops-read-max-length: int (optional)
4441 Not documented
4442 x-iops-write: int (optional)
4444 Not documented
4445 x-iops-write-max: int (optional)
4447 Not documented
4448 x-iops-write-max-length: int (optional)
4450 Not documented
4451 x-bps-total: int (optional)
4453 Not documented
4454 x-bps-total-max: int (optional)
4456 Not documented
4457 x-bps-total-max-length: int (optional)
4459 Not documented
4460 x-bps-read: int (optional)
4462 Not documented
4463 x-bps-read-max: int (optional)
4465 Not documented
4466 x-bps-read-max-length: int (optional)
4468 Not documented
4469 x-bps-write: int (optional)
4471 Not documented
4472 x-bps-write-max: int (optional)
4474 Not documented
4475 x-bps-write-max-length: int (optional)
4477 Not documented
4478 x-iops-size: int (optional)
4480 Not documented
4481 Features
4483 unstable
4484 All members starting with x- are aliases for the same key with‐
4485 out x- in the limits object. This is not a stable interface and
4486 may be removed or changed incompatibly in the future. Use lim‐
4487 its for a supported stable interface.
4488 Since
4490 2.11
4491 block-stream (Command)
4493 Copy data from a backing file into a block device.
4494 The block streaming operation is performed in the background until the
4496 entire backing file has been copied. This command returns immediately
4497 once streaming has started. The status of ongoing block streaming op‐
4498 erations can be checked with query-block-jobs. The operation can be
4499 stopped before it has completed using the block-job-cancel command.
4500 The node that receives the data is called the top image, can be located
4502 in any part of the chain (but always above the base image; see below)
4503 and can be specified using its device or node name. Earlier qemu ver‐
4504 sions only allowed 'device' to name the top level node; presence of the
4505 'base-node' parameter during introspection can be used as a witness of
4506 the enhanced semantics of 'device'.
4507 If a base file is specified then sectors are not copied from that base
4509 file and its backing chain. This can be used to stream a subset of the
4510 backing file chain instead of flattening the entire image. When
4511 streaming completes the image file will have the base file as its back‐
4512 ing file, unless that node was changed while the job was running. In
4513 that case, base's parent's backing (or filtered, whichever exists)
4514 child (i.e., base at the beginning of the job) will be the new backing
4515 file.
4516 On successful completion the image file is updated to drop the backing
4518 file and the BLOCK_JOB_COMPLETED event is emitted.
4519 In case device is a filter node, block-stream modifies the first
4521 non-filter overlay node below it to point to the new backing node in‐
4522 stead of modifying device itself.
4523 Arguments
4525 job-id: string (optional)
4526 identifier for the newly-created block job. If omitted, the de‐
4527 vice name will be used. (Since 2.7)
4528 device: string
4530 the device or node name of the top image
4531 base: string (optional)
4533 the common backing file name. It cannot be set if base-node or
4534 bottom is also set.
4535 base-node: string (optional)
4537 the node name of the backing file. It cannot be set if base or
4538 bottom is also set. (Since 2.8)
4539 bottom: string (optional)
4541 the last node in the chain that should be streamed into top. It
4542 cannot be set if base or base-node is also set. It cannot be
4543 filter node. (Since 6.0)
4544 backing-file: string (optional)
4546 The backing file string to write into the top image. This file‐
4547 name is not validated.
4548 If a pathname string is such that it cannot be resolved by QEMU,
4550 that means that subsequent QMP or HMP commands must use
4551 node-names for the image in question, as filename lookup methods
4552 will fail.
4553 If not specified, QEMU will automatically determine the backing
4555 file string to use, or error out if there is no obvious choice.
4556 Care should be taken when specifying the string, to specify a
4557 valid filename or protocol. (Since 2.1)
4558 speed: int (optional)
4560 the maximum speed, in bytes per second
4561 on-error: BlockdevOnError (optional)
4563 the action to take on an error (default report). 'stop' and
4564 'enospc' can only be used if the block device supports io-status
4565 (see BlockInfo). Since 1.3.
4566 filter-node-name: string (optional)
4568 the node name that should be assigned to the filter driver that
4569 the stream job inserts into the graph above device. If this op‐
4570 tion is not given, a node name is autogenerated. (Since: 6.0)
4571 auto-finalize: boolean (optional)
4573 When false, this job will wait in a PENDING state after it has
4574 finished its work, waiting for block-job-finalize before making
4575 any block graph changes. When true, this job will automatically
4576 perform its abort or commit actions. Defaults to true. (Since
4577 3.1)
4578 auto-dismiss: boolean (optional)
4580 When false, this job will wait in a CONCLUDED state after it has
4581 completely ceased all work, and awaits block-job-dismiss. When
4582 true, this job will automatically disappear from the query list
4583 without user intervention. Defaults to true. (Since 3.1)
4584 Returns
4586 • Nothing on success.
4587 • If device does not exist, DeviceNotFound.
4589 Since
4591 1.1
4592 Example
4594 -> { "execute": "block-stream",
4595 "arguments": { "device": "virtio0",
4596 "base": "/tmp/master.qcow2" } }
4597 <- { "return": {} }
4598 block-job-set-speed (Command)
4600 Set maximum speed for a background block operation.
4601 This command can only be issued when there is an active block job.
4603 Throttling can be disabled by setting the speed to 0.
4605 Arguments
4607 device: string
4608 The job identifier. This used to be a device name (hence the
4609 name of the parameter), but since QEMU 2.7 it can have other
4610 values.
4611 speed: int
4613 the maximum speed, in bytes per second, or 0 for unlimited. De‐
4614 faults to 0.
4615 Returns
4617 • Nothing on success
4618 • If no background operation is active on this device, DeviceNotActive
4620 Since
4622 1.1
4623 block-job-cancel (Command)
4625 Stop an active background block operation.
4626 This command returns immediately after marking the active background
4628 block operation for cancellation. It is an error to call this command
4629 if no operation is in progress.
4630 The operation will cancel as soon as possible and then emit the
4632 BLOCK_JOB_CANCELLED event. Before that happens the job is still visi‐
4633 ble when enumerated using query-block-jobs.
4634 Note that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
4636 dicated (via the event BLOCK_JOB_READY) that the source and destination
4637 are synchronized, then the event triggered by this command changes to
4638 BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
4639 destination now has a point-in-time copy tied to the time of the can‐
4640 cellation.
4641 For streaming, the image file retains its backing file unless the
4643 streaming operation happens to complete just as it is being cancelled.
4644 A new streaming operation can be started at a later time to finish
4645 copying all data from the backing file.
4646 Arguments
4648 device: string
4649 The job identifier. This used to be a device name (hence the
4650 name of the parameter), but since QEMU 2.7 it can have other
4651 values.
4652 force: boolean (optional)
4654 If true, and the job has already emitted the event
4655 BLOCK_JOB_READY, abandon the job immediately (even if it is
4656 paused) instead of waiting for the destination to complete its
4657 final synchronization (since 1.3)
4658 Returns
4660 • Nothing on success
4661 • If no background operation is active on this device, DeviceNotActive
4663 Since
4665 1.1
4666 block-job-pause (Command)
4668 Pause an active background block operation.
4669 This command returns immediately after marking the active background
4671 block operation for pausing. It is an error to call this command if no
4672 operation is in progress or if the job is already paused.
4673 The operation will pause as soon as possible. No event is emitted when
4675 the operation is actually paused. Cancelling a paused job automati‐
4676 cally resumes it.
4677 Arguments
4679 device: string
4680 The job identifier. This used to be a device name (hence the
4681 name of the parameter), but since QEMU 2.7 it can have other
4682 values.
4683 Returns
4685 • Nothing on success
4686 • If no background operation is active on this device, DeviceNotActive
4688 Since
4690 1.3
4691 block-job-resume (Command)
4693 Resume an active background block operation.
4694 This command returns immediately after resuming a paused background
4696 block operation. It is an error to call this command if no operation
4697 is in progress or if the job is not paused.
4698 This command also clears the error status of the job.
4700 Arguments
4702 device: string
4703 The job identifier. This used to be a device name (hence the
4704 name of the parameter), but since QEMU 2.7 it can have other
4705 values.
4706 Returns
4708 • Nothing on success
4709 • If no background operation is active on this device, DeviceNotActive
4711 Since
4713 1.3
4714 block-job-complete (Command)
4716 Manually trigger completion of an active background block operation.
4717 This is supported for drive mirroring, where it also switches the de‐
4718 vice to write to the target path only. The ability to complete is sig‐
4719 naled with a BLOCK_JOB_READY event.
4720 This command completes an active background block operation syn‐
4722 chronously. The ordering of this command's return with the
4723 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
4724 occurs during the processing of this command: 1) the command itself
4725 will fail; 2) the error will be processed according to the rerror/wer‐
4726 ror arguments that were specified when starting the operation.
4727 A cancelled or paused job cannot be completed.
4729 Arguments
4731 device: string
4732 The job identifier. This used to be a device name (hence the
4733 name of the parameter), but since QEMU 2.7 it can have other
4734 values.
4735 Returns
4737 • Nothing on success
4738 • If no background operation is active on this device, DeviceNotActive
4740 Since
4742 1.3
4743 block-job-dismiss (Command)
4745 For jobs that have already concluded, remove them from the
4746 block-job-query list. This command only needs to be run for jobs which
4747 were started with QEMU 2.12+ job lifetime management semantics.
4748 This command will refuse to operate on any job that has not yet reached
4750 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
4751 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
4752 still need to be used as appropriate.
4753 Arguments
4755 id: string
4756 The job identifier.
4757 Returns
4759 Nothing on success
4760 Since
4762 2.12
4763 block-job-finalize (Command)
4765 Once a job that has manual=true reaches the pending state, it can be
4766 instructed to finalize any graph changes and do any necessary cleanup
4767 via this command. For jobs in a transaction, instructing one job to
4768 finalize will force ALL jobs in the transaction to finalize, so it is
4769 only necessary to instruct a single member job to finalize.
4770 Arguments
4772 id: string
4773 The job identifier.
4774 Returns
4776 Nothing on success
4777 Since
4779 2.12
4780 BlockdevDiscardOptions (Enum)
4782 Determines how to handle discard requests.
4783 Values
4785 ignore Ignore the request
4786 unmap Forward as an unmap request
4788 Since
4790 2.9
4791 BlockdevDetectZeroesOptions (Enum)
4793 Describes the operation mode for the automatic conversion of plain zero
4794 writes by the OS to driver specific optimized zero write commands.
4795 Values
4797 off Disabled (default)
4798 on Enabled
4800 unmap Enabled and even try to unmap blocks if possible. This requires
4802 also that BlockdevDiscardOptions is set to unmap for this de‐
4803 vice.
4804 Since
4806 2.1
4807 BlockdevAioOptions (Enum)
4809 Selects the AIO backend to handle I/O requests
4810 Values
4812 threads
4813 Use qemu's thread pool
4814 native Use native AIO backend (only Linux and Windows)
4816 io_uring (If: CONFIG_LINUX_IO_URING)
4818 Use linux io_uring (since 5.0)
4819 Since
4821 2.9
4822 BlockdevCacheOptions (Object)
4824 Includes cache-related options for block devices
4825 Members
4827 direct: boolean (optional)
4828 enables use of O_DIRECT (bypass the host page cache; default:
4829 false)
4830 no-flush: boolean (optional)
4832 ignore any flush requests for the device (default: false)
4833 Since
4835 2.9
4836 BlockdevDriver (Enum)
4838 Drivers that are supported in block device operations.
4839 Values
4841 throttle
4842 Since 2.11
4843 nvme Since 2.12
4845 copy-on-read
4847 Since 3.0
4848 blklogwrites
4850 Since 3.0
4851 blkreplay
4853 Since 4.2
4854 compress
4856 Since 5.0
4857 copy-before-write
4859 Since 6.2
4860 snapshot-access
4862 Since 7.0
4863 blkdebug
4865 Not documented
4866 blkverify
4868 Not documented
4869 bochs Not documented
4871 cloop Not documented
4873 dmg Not documented
4875 file Not documented
4877 ftp Not documented
4879 ftps Not documented
4881 gluster
4883 Not documented
4884 host_cdrom (If: HAVE_HOST_BLOCK_DEVICE)
4886 Not documented
4887 host_device (If: HAVE_HOST_BLOCK_DEVICE)
4889 Not documented
4890 http Not documented
4892 https Not documented
4894 iscsi Not documented
4896 luks Not documented
4898 nbd Not documented
4900 nfs Not documented
4902 null-aio
4904 Not documented
4905 null-co
4907 Not documented
4908 parallels
4910 Not documented
4911 preallocate
4913 Not documented
4914 qcow Not documented
4916 qcow2 Not documented
4918 qed Not documented
4920 quorum Not documented
4922 raw Not documented
4924 rbd Not documented
4926 replication (If: CONFIG_REPLICATION)
4928 Not documented
4929 ssh Not documented
4931 vdi Not documented
4933 vhdx Not documented
4935 vmdk Not documented
4937 vpc Not documented
4939 vvfat Not documented
4941 Since
4943 2.9
4944 BlockdevOptionsFile (Object)
4946 Driver specific block device options for the file backend.
4947 Members
4949 filename: string
4950 path to the image file
4951 pr-manager: string (optional)
4953 the id for the object that will handle persistent reservations
4954 for this device (default: none, forward the commands via SG_IO;
4955 since 2.11)
4956 aio: BlockdevAioOptions (optional)
4958 AIO backend (default: threads) (since: 2.8)
4959 aio-max-batch: int (optional)
4961 maximum number of requests to batch together into a single sub‐
4962 mission in the AIO backend. The smallest value between this and
4963 the aio-max-batch value of the IOThread object is chosen. 0
4964 means that the AIO backend will handle it automatically. (de‐
4965 fault: 0, since 6.2)
4966 locking: OnOffAuto (optional)
4968 whether to enable file locking. If set to 'auto', only enable
4969 when Open File Descriptor (OFD) locking API is available (de‐
4970 fault: auto, since 2.10)
4971 drop-cache: boolean (optional) (If: CONFIG_LINUX)
4973 invalidate page cache during live migration. This prevents
4974 stale data on the migration destination with cache.direct=off.
4975 Currently only supported on Linux hosts. (default: on, since:
4976 4.0)
4977 x-check-cache-dropped: boolean (optional)
4979 whether to check that page cache was dropped on live migration.
4980 May cause noticeable delays if the image file is large, do not
4981 use in production. (default: off) (since: 3.0)
4982 Features
4984 dynamic-auto-read-only
4985 If present, enabled auto-read-only means that the driver will
4986 open the image read-only at first, dynamically reopen the image
4987 file read-write when the first writer is attached to the node
4988 and reopen read-only when the last writer is detached. This al‐
4989 lows giving QEMU write permissions only on demand when an opera‐
4990 tion actually needs write access.
4991 unstable
4993 Member x-check-cache-dropped is meant for debugging.
4994 Since
4996 2.9
4997 BlockdevOptionsNull (Object)
4999 Driver specific block device options for the null backend.
5000 Members
5002 size: int (optional)
5003 size of the device in bytes.
5004 latency-ns: int (optional)
5006 emulated latency (in nanoseconds) in processing requests. De‐
5007 fault to zero which completes requests immediately. (Since 2.4)
5008 read-zeroes: boolean (optional)
5010 if true, reads from the device produce zeroes; if false, the
5011 buffer is left unchanged. (default: false; since: 4.1)
5012 Since
5014 2.9
5015 BlockdevOptionsNVMe (Object)
5017 Driver specific block device options for the NVMe backend.
5018 Members
5020 device: string
5021 PCI controller address of the NVMe device in format hhhh:bb:ss.f
5022 (host:bus:slot.function)
5023 namespace: int
5025 namespace number of the device, starting from 1.
5026 Note that the PCI device must have been unbound from any host kernel
5027 driver before instructing QEMU to add the blockdev.
5028 Since
5030 2.12
5031 BlockdevOptionsVVFAT (Object)
5033 Driver specific block device options for the vvfat protocol.
5034 Members
5036 dir: string
5037 directory to be exported as FAT image
5038 fat-type: int (optional)
5040 FAT type: 12, 16 or 32
5041 floppy: boolean (optional)
5043 whether to export a floppy image (true) or partitioned hard disk
5044 (false; default)
5045 label: string (optional)
5047 set the volume label, limited to 11 bytes. FAT16 and FAT32 tra‐
5048 ditionally have some restrictions on labels, which are ignored
5049 by most operating systems. Defaults to "QEMU VVFAT". (since
5050 2.4)
5051 rw: boolean (optional)
5053 whether to allow write operations (default: false)
5054 Since
5056 2.9
5057 BlockdevOptionsGenericFormat (Object)
5059 Driver specific block device options for image format that have no op‐
5060 tion besides their data source.
5061 Members
5063 file: BlockdevRef
5064 reference to or definition of the data source block device
5065 Since
5067 2.9
5068 BlockdevOptionsLUKS (Object)
5070 Driver specific block device options for LUKS.
5071 Members
5073 key-secret: string (optional)
5074 the ID of a QCryptoSecret object providing the decryption key
5075 (since 2.6). Mandatory except when doing a metadata-only probe
5076 of the image.
5077 The members of BlockdevOptionsGenericFormat
5079 Since
5081 2.9
5082 BlockdevOptionsGenericCOWFormat (Object)
5084 Driver specific block device options for image format that have no op‐
5085 tion besides their data source and an optional backing file.
5086 Members
5088 backing: BlockdevRefOrNull (optional)
5089 reference to or definition of the backing file block device,
5090 null disables the backing file entirely. Defaults to the back‐
5091 ing file stored the image file.
5092 The members of BlockdevOptionsGenericFormat
5094 Since
5096 2.9
5097 Qcow2OverlapCheckMode (Enum)
5099 General overlap check modes.
5100 Values
5102 none Do not perform any checks
5103 constant
5105 Perform only checks which can be done in constant time and with‐
5106 out reading anything from disk
5107 cached Perform only checks which can be done without reading anything
5109 from disk
5110 all Perform all available overlap checks
5112 Since
5114 2.9
5115 Qcow2OverlapCheckFlags (Object)
5117 Structure of flags for each metadata structure. Setting a field to
5118 'true' makes qemu guard that structure against unintended overwriting.
5119 The default value is chosen according to the template given.
5120 Members
5122 template: Qcow2OverlapCheckMode (optional)
5123 Specifies a template mode which can be adjusted using the other
5124 flags, defaults to 'cached'
5125 bitmap-directory: boolean (optional)
5127 since 3.0
5128 main-header: boolean (optional)
5130 Not documented
5131 active-l1: boolean (optional)
5133 Not documented
5134 active-l2: boolean (optional)
5136 Not documented
5137 refcount-table: boolean (optional)
5139 Not documented
5140 refcount-block: boolean (optional)
5142 Not documented
5143 snapshot-table: boolean (optional)
5145 Not documented
5146 inactive-l1: boolean (optional)
5148 Not documented
5149 inactive-l2: boolean (optional)
5151 Not documented
5152 Since
5154 2.9
5155 Qcow2OverlapChecks (Alternate)
5157 Specifies which metadata structures should be guarded against unin‐
5158 tended overwriting.
5159 Members
5161 flags: Qcow2OverlapCheckFlags
5162 set of flags for separate specification of each metadata struc‐
5163 ture type
5164 mode: Qcow2OverlapCheckMode
5166 named mode which chooses a specific set of flags
5167 Since
5169 2.9
5170 BlockdevQcowEncryptionFormat (Enum)
5172 Values
5173 aes AES-CBC with plain64 initialization vectors
5174 Since
5176 2.10
5177 BlockdevQcowEncryption (Object)
5179 Members
5180 format: BlockdevQcowEncryptionFormat
5181 Not documented
5182 The members of QCryptoBlockOptionsQCow when format is "aes"
5184 Since
5186 2.10
5187 BlockdevOptionsQcow (Object)
5189 Driver specific block device options for qcow.
5190 Members
5192 encrypt: BlockdevQcowEncryption (optional)
5193 Image decryption options. Mandatory for encrypted images, except
5194 when doing a metadata-only probe of the image.
5195 The members of BlockdevOptionsGenericCOWFormat
5197 Since
5199 2.10
5200 BlockdevQcow2EncryptionFormat (Enum)
5202 Values
5203 aes AES-CBC with plain64 initialization vectors
5204 luks Not documented
5206 Since
5208 2.10
5209 BlockdevQcow2Encryption (Object)
5211 Members
5212 format: BlockdevQcow2EncryptionFormat
5213 Not documented
5214 The members of QCryptoBlockOptionsQCow when format is "aes"
5216 The members of QCryptoBlockOptionsLUKS when format is "luks"
5218 Since
5220 2.10
5221 BlockdevOptionsPreallocate (Object)
5223 Filter driver intended to be inserted between format and protocol node
5224 and do preallocation in protocol node on write.
5225 Members
5227 prealloc-align: int (optional)
5228 on preallocation, align file length to this number, default
5229 1048576 (1M)
5230 prealloc-size: int (optional)
5232 how much to preallocate, default 134217728 (128M)
5233 The members of BlockdevOptionsGenericFormat
5235 Since
5237 6.0
5238 BlockdevOptionsQcow2 (Object)
5240 Driver specific block device options for qcow2.
5241 Members
5243 lazy-refcounts: boolean (optional)
5244 whether to enable the lazy refcounts feature (default is taken
5245 from the image file)
5246 pass-discard-request: boolean (optional)
5248 whether discard requests to the qcow2 device should be forwarded
5249 to the data source
5250 pass-discard-snapshot: boolean (optional)
5252 whether discard requests for the data source should be issued
5253 when a snapshot operation (e.g. deleting a snapshot) frees
5254 clusters in the qcow2 file
5255 pass-discard-other: boolean (optional)
5257 whether discard requests for the data source should be issued on
5258 other occasions where a cluster gets freed
5259 overlap-check: Qcow2OverlapChecks (optional)
5261 which overlap checks to perform for writes to the image, de‐
5262 faults to 'cached' (since 2.2)
5263 cache-size: int (optional)
5265 the maximum total size of the L2 table and refcount block caches
5266 in bytes (since 2.2)
5267 l2-cache-size: int (optional)
5269 the maximum size of the L2 table cache in bytes (since 2.2)
5270 l2-cache-entry-size: int (optional)
5272 the size of each entry in the L2 cache in bytes. It must be a
5273 power of two between 512 and the cluster size. The default value
5274 is the cluster size (since 2.12)
5275 refcount-cache-size: int (optional)
5277 the maximum size of the refcount block cache in bytes (since
5278 2.2)
5279 cache-clean-interval: int (optional)
5281 clean unused entries in the L2 and refcount caches. The interval
5282 is in seconds. The default value is 600 on supporting platforms,
5283 and 0 on other platforms. 0 disables this feature. (since 2.5)
5284 encrypt: BlockdevQcow2Encryption (optional)
5286 Image decryption options. Mandatory for encrypted images, except
5287 when doing a metadata-only probe of the image. (since 2.10)
5288 data-file: BlockdevRef (optional)
5290 reference to or definition of the external data file. This may
5291 only be specified for images that require an external data file.
5292 If it is not specified for such an image, the data file name is
5293 loaded from the image file. (since 4.0)
5294 The members of BlockdevOptionsGenericCOWFormat
5296 Since
5298 2.9
5299 SshHostKeyCheckMode (Enum)
5301 Values
5302 none Don't check the host key at all
5303 hash Compare the host key with a given hash
5305 known_hosts
5307 Check the host key against the known_hosts file
5308 Since
5310 2.12
5311 SshHostKeyCheckHashType (Enum)
5313 Values
5314 md5 The given hash is an md5 hash
5315 sha1 The given hash is an sha1 hash
5317 sha256 The given hash is an sha256 hash
5319 Since
5321 2.12
5322 SshHostKeyHash (Object)
5324 Members
5325 type: SshHostKeyCheckHashType
5326 The hash algorithm used for the hash
5327 hash: string
5329 The expected hash value
5330 Since
5332 2.12
5333 SshHostKeyCheck (Object)
5335 Members
5336 mode: SshHostKeyCheckMode
5337 Not documented
5338 The members of SshHostKeyHash when mode is "hash"
5340 Since
5342 2.12
5343 BlockdevOptionsSsh (Object)
5345 Members
5346 server: InetSocketAddress
5347 host address
5348 path: string
5350 path to the image on the host
5351 user: string (optional)
5353 user as which to connect, defaults to current local user name
5354 host-key-check: SshHostKeyCheck (optional)
5356 Defines how and what to check the host key against (default:
5357 known_hosts)
5358 Since
5360 2.9
5361 BlkdebugEvent (Enum)
5363 Trigger events supported by blkdebug.
5364 Values
5366 l1_shrink_write_table
5367 write zeros to the l1 table to shrink image. (since 2.11)
5368 l1_shrink_free_l2_clusters
5370 discard the l2 tables. (since 2.11)
5371 cor_write
5373 a write due to copy-on-read (since 2.11)
5374 cluster_alloc_space
5376 an allocation of file space for a cluster (since 4.1)
5377 none triggers once at creation of the blkdebug node (since 4.1)
5379 l1_update
5381 Not documented
5382 l1_grow_alloc_table
5384 Not documented
5385 l1_grow_write_table
5387 Not documented
5388 l1_grow_activate_table
5390 Not documented
5391 l2_load
5393 Not documented
5394 l2_update
5396 Not documented
5397 l2_update_compressed
5399 Not documented
5400 l2_alloc_cow_read
5402 Not documented
5403 l2_alloc_write
5405 Not documented
5406 read_aio
5408 Not documented
5409 read_backing_aio
5411 Not documented
5412 read_compressed
5414 Not documented
5415 write_aio
5417 Not documented
5418 write_compressed
5420 Not documented
5421 vmstate_load
5423 Not documented
5424 vmstate_save
5426 Not documented
5427 cow_read
5429 Not documented
5430 cow_write
5432 Not documented
5433 reftable_load
5435 Not documented
5436 reftable_grow
5438 Not documented
5439 reftable_update
5441 Not documented
5442 refblock_load
5444 Not documented
5445 refblock_update
5447 Not documented
5448 refblock_update_part
5450 Not documented
5451 refblock_alloc
5453 Not documented
5454 refblock_alloc_hookup
5456 Not documented
5457 refblock_alloc_write
5459 Not documented
5460 refblock_alloc_write_blocks
5462 Not documented
5463 refblock_alloc_write_table
5465 Not documented
5466 refblock_alloc_switch_table
5468 Not documented
5469 cluster_alloc
5471 Not documented
5472 cluster_alloc_bytes
5474 Not documented
5475 cluster_free
5477 Not documented
5478 flush_to_os
5480 Not documented
5481 flush_to_disk
5483 Not documented
5484 pwritev_rmw_head
5486 Not documented
5487 pwritev_rmw_after_head
5489 Not documented
5490 pwritev_rmw_tail
5492 Not documented
5493 pwritev_rmw_after_tail
5495 Not documented
5496 pwritev
5498 Not documented
5499 pwritev_zero
5501 Not documented
5502 pwritev_done
5504 Not documented
5505 empty_image_prepare
5507 Not documented
5508 Since
5510 2.9
5511 BlkdebugIOType (Enum)
5513 Kinds of I/O that blkdebug can inject errors in.
5514 Values
5516 read .bdrv_co_preadv()
5517 write .bdrv_co_pwritev()
5519 write-zeroes
5521 .bdrv_co_pwrite_zeroes()
5522 discard
5524 .bdrv_co_pdiscard()
5525 flush .bdrv_co_flush_to_disk()
5527 block-status
5529 .bdrv_co_block_status()
5530 Since
5532 4.1
5533 BlkdebugInjectErrorOptions (Object)
5535 Describes a single error injection for blkdebug.
5536 Members
5538 event: BlkdebugEvent
5539 trigger event
5540 state: int (optional)
5542 the state identifier blkdebug needs to be in to actually trigger
5543 the event; defaults to "any"
5544 iotype: BlkdebugIOType (optional)
5546 the type of I/O operations on which this error should be in‐
5547 jected; defaults to "all read, write, write-zeroes, discard, and
5548 flush operations" (since: 4.1)
5549 errno: int (optional)
5551 error identifier (errno) to be returned; defaults to EIO
5552 sector: int (optional)
5554 specifies the sector index which has to be affected in order to
5555 actually trigger the event; defaults to "any sector"
5556 once: boolean (optional)
5558 disables further events after this one has been triggered; de‐
5559 faults to false
5560 immediately: boolean (optional)
5562 fail immediately; defaults to false
5563 Since
5565 2.9
5566 BlkdebugSetStateOptions (Object)
5568 Describes a single state-change event for blkdebug.
5569 Members
5571 event: BlkdebugEvent
5572 trigger event
5573 state: int (optional)
5575 the current state identifier blkdebug needs to be in; defaults
5576 to "any"
5577 new_state: int
5579 the state identifier blkdebug is supposed to assume if this
5580 event is triggered
5581 Since
5583 2.9
5584 BlockdevOptionsBlkdebug (Object)
5586 Driver specific block device options for blkdebug.
5587 Members
5589 image: BlockdevRef
5590 underlying raw block device (or image file)
5591 config: string (optional)
5593 filename of the configuration file
5594 align: int (optional)
5596 required alignment for requests in bytes, must be positive power
5597 of 2, or 0 for default
5598 max-transfer: int (optional)
5600 maximum size for I/O transfers in bytes, must be positive multi‐
5601 ple of align and of the underlying file's request alignment (but
5602 need not be a power of 2), or 0 for default (since 2.10)
5603 opt-write-zero: int (optional)
5605 preferred alignment for write zero requests in bytes, must be
5606 positive multiple of align and of the underlying file's request
5607 alignment (but need not be a power of 2), or 0 for default
5608 (since 2.10)
5609 max-write-zero: int (optional)
5611 maximum size for write zero requests in bytes, must be positive
5612 multiple of align, of opt-write-zero, and of the underlying
5613 file's request alignment (but need not be a power of 2), or 0
5614 for default (since 2.10)
5615 opt-discard: int (optional)
5617 preferred alignment for discard requests in bytes, must be posi‐
5618 tive multiple of align and of the underlying file's request
5619 alignment (but need not be a power of 2), or 0 for default
5620 (since 2.10)
5621 max-discard: int (optional)
5623 maximum size for discard requests in bytes, must be positive
5624 multiple of align, of opt-discard, and of the underlying file's
5625 request alignment (but need not be a power of 2), or 0 for de‐
5626 fault (since 2.10)
5627 inject-error: array of BlkdebugInjectErrorOptions (optional)
5629 array of error injection descriptions
5630 set-state: array of BlkdebugSetStateOptions (optional)
5632 array of state-change descriptions
5633 take-child-perms: array of BlockPermission (optional)
5635 Permissions to take on image in addition to what is necessary
5636 anyway (which depends on how the blkdebug node is used). De‐
5637 faults to none. (since 5.0)
5638 unshare-child-perms: array of BlockPermission (optional)
5640 Permissions not to share on image in addition to what cannot be
5641 shared anyway (which depends on how the blkdebug node is used).
5642 Defaults to none. (since 5.0)
5643 Since
5645 2.9
5646 BlockdevOptionsBlklogwrites (Object)
5648 Driver specific block device options for blklogwrites.
5649 Members
5651 file: BlockdevRef
5652 block device
5653 log: BlockdevRef
5655 block device used to log writes to file
5656 log-sector-size: int (optional)
5658 sector size used in logging writes to file, determines granular‐
5659 ity of offsets and sizes of writes (default: 512)
5660 log-append: boolean (optional)
5662 append to an existing log (default: false)
5663 log-super-update-interval: int (optional)
5665 interval of write requests after which the log super block is
5666 updated to disk (default: 4096)
5667 Since
5669 3.0
5670 BlockdevOptionsBlkverify (Object)
5672 Driver specific block device options for blkverify.
5673 Members
5675 test: BlockdevRef
5676 block device to be tested
5677 raw: BlockdevRef
5679 raw image used for verification
5680 Since
5682 2.9
5683 BlockdevOptionsBlkreplay (Object)
5685 Driver specific block device options for blkreplay.
5686 Members
5688 image: BlockdevRef
5689 disk image which should be controlled with blkreplay
5690 Since
5692 4.2
5693 QuorumReadPattern (Enum)
5695 An enumeration of quorum read patterns.
5696 Values
5698 quorum read all the children and do a quorum vote on reads
5699 fifo read only from the first child that has not failed
5701 Since
5703 2.9
5704 BlockdevOptionsQuorum (Object)
5706 Driver specific block device options for Quorum
5707 Members
5709 blkverify: boolean (optional)
5710 true if the driver must print content mismatch
5712 set to false by default
5713 children: array of BlockdevRef
5715 the children block devices to use
5716 vote-threshold: int
5718 the vote limit under which a read will fail
5719 rewrite-corrupted: boolean (optional)
5721 rewrite corrupted data when quorum is reached (Since 2.1)
5722 read-pattern: QuorumReadPattern (optional)
5724 choose read pattern and set to quorum by default (Since 2.2)
5725 Since
5727 2.9
5728 BlockdevOptionsGluster (Object)
5730 Driver specific block device options for Gluster
5731 Members
5733 volume: string
5734 name of gluster volume where VM image resides
5735 path: string
5737 absolute path to image file in gluster volume
5738 server: array of SocketAddress
5740 gluster servers description
5741 debug: int (optional)
5743 libgfapi log level (default '4' which is Error) (Since 2.8)
5744 logfile: string (optional)
5746 libgfapi log file (default /dev/stderr) (Since 2.8)
5747 Since
5749 2.9
5750 IscsiTransport (Enum)
5752 An enumeration of libiscsi transport types
5753 Values
5755 tcp Not documented
5756 iser Not documented
5758 Since
5760 2.9
5761 IscsiHeaderDigest (Enum)
5763 An enumeration of header digests supported by libiscsi
5764 Values
5766 crc32c Not documented
5767 none Not documented
5769 crc32c-none
5771 Not documented
5772 none-crc32c
5774 Not documented
5775 Since
5777 2.9
5778 BlockdevOptionsIscsi (Object)
5780 Members
5781 transport: IscsiTransport
5782 The iscsi transport type
5783 portal: string
5785 The address of the iscsi portal
5786 target: string
5788 The target iqn name
5789 lun: int (optional)
5791 LUN to connect to. Defaults to 0.
5792 user: string (optional)
5794 User name to log in with. If omitted, no CHAP authentication is
5795 performed.
5796 password-secret: string (optional)
5798 The ID of a QCryptoSecret object providing the password for the
5799 login. This option is required if user is specified.
5800 initiator-name: string (optional)
5802 The iqn name we want to identify to the target as. If this op‐
5803 tion is not specified, an initiator name is generated automati‐
5804 cally.
5805 header-digest: IscsiHeaderDigest (optional)
5807 The desired header digest. Defaults to none-crc32c.
5808 timeout: int (optional)
5810 Timeout in seconds after which a request will timeout. 0 means
5811 no timeout and is the default.
5812 Driver specific block device options for iscsi
5813 Since
5815 2.9
5816 RbdAuthMode (Enum)
5818 Values
5819 cephx Not documented
5820 none Not documented
5822 Since
5824 3.0
5825 RbdImageEncryptionFormat (Enum)
5827 Values
5828 luks Not documented
5829 luks2 Not documented
5831 Since
5833 6.1
5834 RbdEncryptionOptionsLUKSBase (Object)
5836 Members
5837 key-secret: string
5838 ID of a QCryptoSecret object providing a passphrase for unlock‐
5839 ing the encryption
5840 Since
5842 6.1
5843 RbdEncryptionCreateOptionsLUKSBase (Object)
5845 Members
5846 cipher-alg: QCryptoCipherAlgorithm (optional)
5847 The encryption algorithm
5848 The members of RbdEncryptionOptionsLUKSBase
5850 Since
5852 6.1
5853 RbdEncryptionOptionsLUKS (Object)
5855 Members
5856 The members of RbdEncryptionOptionsLUKSBase
5857 Since
5859 6.1
5860 RbdEncryptionOptionsLUKS2 (Object)
5862 Members
5863 The members of RbdEncryptionOptionsLUKSBase
5864 Since
5866 6.1
5867 RbdEncryptionCreateOptionsLUKS (Object)
5869 Members
5870 The members of RbdEncryptionCreateOptionsLUKSBase
5871 Since
5873 6.1
5874 RbdEncryptionCreateOptionsLUKS2 (Object)
5876 Members
5877 The members of RbdEncryptionCreateOptionsLUKSBase
5878 Since
5880 6.1
5881 RbdEncryptionOptions (Object)
5883 Members
5884 format: RbdImageEncryptionFormat
5885 Not documented
5886 The members of RbdEncryptionOptionsLUKS when format is "luks"
5888 The members of RbdEncryptionOptionsLUKS2 when format is "luks2"
5890 Since
5892 6.1
5893 RbdEncryptionCreateOptions (Object)
5895 Members
5896 format: RbdImageEncryptionFormat
5897 Not documented
5898 The members of RbdEncryptionCreateOptionsLUKS when format is "luks"
5900 The members of RbdEncryptionCreateOptionsLUKS2 when format is "luks2"
5902 Since
5904 6.1
5905 BlockdevOptionsRbd (Object)
5907 Members
5908 pool: string
5909 Ceph pool name.
5910 namespace: string (optional)
5912 Rados namespace name in the Ceph pool. (Since 5.0)
5913 image: string
5915 Image name in the Ceph pool.
5916 conf: string (optional)
5918 path to Ceph configuration file. Values in the configuration
5919 file will be overridden by options specified via QAPI.
5920 snapshot: string (optional)
5922 Ceph snapshot name.
5923 encrypt: RbdEncryptionOptions (optional)
5925 Image encryption options. (Since 6.1)
5926 user: string (optional)
5928 Ceph id name.
5929 auth-client-required: array of RbdAuthMode (optional)
5931 Acceptable authentication modes. This maps to Ceph configura‐
5932 tion option "auth_client_required". (Since 3.0)
5933 key-secret: string (optional)
5935 ID of a QCryptoSecret object providing a key for cephx authenti‐
5936 cation. This maps to Ceph configuration option "key". (Since
5937 3.0)
5938 server: array of InetSocketAddressBase (optional)
5940 Monitor host address and port. This maps to the "mon_host" Ceph
5941 option.
5942 Since
5944 2.9
5945 ReplicationMode (Enum)
5947 An enumeration of replication modes.
5948 Values
5950 primary
5951 Primary mode, the vm's state will be sent to secondary QEMU.
5952 secondary
5954 Secondary mode, receive the vm's state from primary QEMU.
5955 Since
5957 2.9
5958 If
5960 CONFIG_REPLICATION
5961 BlockdevOptionsReplication (Object)
5963 Driver specific block device options for replication
5964 Members
5966 mode: ReplicationMode
5967 the replication mode
5968 top-id: string (optional)
5970 In secondary mode, node name or device ID of the root node who
5971 owns the replication node chain. Must not be given in primary
5972 mode.
5973 The members of BlockdevOptionsGenericFormat
5975 Since
5977 2.9
5978 If
5980 CONFIG_REPLICATION
5981 NFSTransport (Enum)
5983 An enumeration of NFS transport types
5984 Values
5986 inet TCP transport
5987 Since
5989 2.9
5990 NFSServer (Object)
5992 Captures the address of the socket
5993 Members
5995 type: NFSTransport
5996 transport type used for NFS (only TCP supported)
5997 host: string
5999 host address for NFS server
6000 Since
6002 2.9
6003 BlockdevOptionsNfs (Object)
6005 Driver specific block device option for NFS
6006 Members
6008 server: NFSServer
6009 host address
6010 path: string
6012 path of the image on the host
6013 user: int (optional)
6015 UID value to use when talking to the server (defaults to 65534
6016 on Windows and getuid() on unix)
6017 group: int (optional)
6019 GID value to use when talking to the server (defaults to 65534
6020 on Windows and getgid() in unix)
6021 tcp-syn-count: int (optional)
6023 number of SYNs during the session establishment (defaults to
6024 libnfs default)
6025 readahead-size: int (optional)
6027 set the readahead size in bytes (defaults to libnfs default)
6028 page-cache-size: int (optional)
6030 set the pagecache size in bytes (defaults to libnfs default)
6031 debug: int (optional)
6033 set the NFS debug level (max 2) (defaults to libnfs default)
6034 Since
6036 2.9
6037 BlockdevOptionsCurlBase (Object)
6039 Driver specific block device options shared by all protocols supported
6040 by the curl backend.
6041 Members
6043 url: string
6044 URL of the image file
6045 readahead: int (optional)
6047 Size of the read-ahead cache; must be a multiple of 512 (de‐
6048 faults to 256 kB)
6049 timeout: int (optional)
6051 Timeout for connections, in seconds (defaults to 5)
6052 username: string (optional)
6054 Username for authentication (defaults to none)
6055 password-secret: string (optional)
6057 ID of a QCryptoSecret object providing a password for authenti‐
6058 cation (defaults to no password)
6059 proxy-username: string (optional)
6061 Username for proxy authentication (defaults to none)
6062 proxy-password-secret: string (optional)
6064 ID of a QCryptoSecret object providing a password for proxy au‐
6065 thentication (defaults to no password)
6066 Since
6068 2.9
6069 BlockdevOptionsCurlHttp (Object)
6071 Driver specific block device options for HTTP connections over the curl
6072 backend. URLs must start with "http://".
6073 Members
6075 cookie: string (optional)
6076 List of cookies to set; format is "name1=content1; name2=con‐
6077 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
6078 ies.
6079 cookie-secret: string (optional)
6081 ID of a QCryptoSecret object providing the cookie data in a se‐
6082 cure way. See cookie for the format. (since 2.10)
6083 The members of BlockdevOptionsCurlBase
6085 Since
6087 2.9
6088 BlockdevOptionsCurlHttps (Object)
6090 Driver specific block device options for HTTPS connections over the
6091 curl backend. URLs must start with "https://".
6092 Members
6094 cookie: string (optional)
6095 List of cookies to set; format is "name1=content1; name2=con‐
6096 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
6097 ies.
6098 sslverify: boolean (optional)
6100 Whether to verify the SSL certificate's validity (defaults to
6101 true)
6102 cookie-secret: string (optional)
6104 ID of a QCryptoSecret object providing the cookie data in a se‐
6105 cure way. See cookie for the format. (since 2.10)
6106 The members of BlockdevOptionsCurlBase
6108 Since
6110 2.9
6111 BlockdevOptionsCurlFtp (Object)
6113 Driver specific block device options for FTP connections over the curl
6114 backend. URLs must start with "ftp://".
6115 Members
6117 The members of BlockdevOptionsCurlBase
6118 Since
6120 2.9
6121 BlockdevOptionsCurlFtps (Object)
6123 Driver specific block device options for FTPS connections over the curl
6124 backend. URLs must start with "ftps://".
6125 Members
6127 sslverify: boolean (optional)
6128 Whether to verify the SSL certificate's validity (defaults to
6129 true)
6130 The members of BlockdevOptionsCurlBase
6132 Since
6134 2.9
6135 BlockdevOptionsNbd (Object)
6137 Driver specific block device options for NBD.
6138 Members
6140 server: SocketAddress
6141 NBD server address
6142 export: string (optional)
6144 export name
6145 tls-creds: string (optional)
6147 TLS credentials ID
6148 tls-hostname: string (optional)
6150 TLS hostname override for certificate validation (Since 7.0)
6151 x-dirty-bitmap: string (optional)
6153 A metadata context name such as "qemu:dirty-bitmap:NAME" or
6154 "qemu:allocation-depth" to query in place of the traditional
6155 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
6156 the NBD protocol; and yes, naming this option x-context would
6157 have made more sense) (since 3.0)
6158 reconnect-delay: int (optional)
6160 On an unexpected disconnect, the nbd client tries to connect
6161 again until succeeding or encountering a serious error. During
6162 the first reconnect-delay seconds, all requests are paused and
6163 will be rerun on a successful reconnect. After that time, any
6164 delayed requests and all future requests before a successful re‐
6165 connect will immediately fail. Default 0 (Since 4.2)
6166 open-timeout: int (optional)
6168 In seconds. If zero, the nbd driver tries the connection only
6169 once, and fails to open if the connection fails. If non-zero,
6170 the nbd driver will repeat connection attempts until successful
6171 or until open-timeout seconds have elapsed. Default 0 (Since
6172 7.0)
6173 Features
6175 unstable
6176 Member x-dirty-bitmap is experimental.
6177 Since
6179 2.9
6180 BlockdevOptionsRaw (Object)
6182 Driver specific block device options for the raw driver.
6183 Members
6185 offset: int (optional)
6186 position where the block device starts
6187 size: int (optional)
6189 the assumed size of the device
6190 The members of BlockdevOptionsGenericFormat
6192 Since
6194 2.9
6195 BlockdevOptionsThrottle (Object)
6197 Driver specific block device options for the throttle driver
6198 Members
6200 throttle-group: string
6201 the name of the throttle-group object to use. It must already
6202 exist.
6203 file: BlockdevRef
6205 reference to or definition of the data source block device
6206 Since
6208 2.11
6209 BlockdevOptionsCor (Object)
6211 Driver specific block device options for the copy-on-read driver.
6212 Members
6214 bottom: string (optional)
6215 The name of a non-filter node (allocation-bearing layer) that
6216 limits the COR operations in the backing chain (inclusive), so
6217 that no data below this node will be copied by this filter. If
6218 option is absent, the limit is not applied, so that data from
6219 all backing layers may be copied.
6220 The members of BlockdevOptionsGenericFormat
6222 Since
6224 6.0
6225 BlockdevOptionsCbw (Object)
6227 Driver specific block device options for the copy-before-write driver,
6228 which does so called copy-before-write operations: when data is written
6229 to the filter, the filter first reads corresponding blocks from its
6230 file child and copies them to target child. After successfully copying,
6231 the write request is propagated to file child. If copying fails, the
6232 original write request is failed too and no data is written to file
6233 child.
6234 Members
6236 target: BlockdevRef
6237 The target for copy-before-write operations.
6238 bitmap: BlockDirtyBitmap (optional)
6240 If specified, copy-before-write filter will do copy-before-write
6241 operations only for dirty regions of the bitmap. Bitmap size
6242 must be equal to length of file and target child of the filter.
6243 Note also, that bitmap is used only to initialize internal bit‐
6244 map of the process, so further modifications (or removing) of
6245 specified bitmap doesn't influence the filter. (Since 7.0)
6246 The members of BlockdevOptionsGenericFormat
6248 Since
6250 6.2
6251 BlockdevOptions (Object)
6253 Options for creating a block device. Many options are available for
6254 all block devices, independent of the block driver:
6255 Members
6257 driver: BlockdevDriver
6258 block driver name
6259 node-name: string (optional)
6261 the node name of the new node (Since 2.0). This option is re‐
6262 quired on the top level of blockdev-add. Valid node names start
6263 with an alphabetic character and may contain only alphanumeric
6264 characters, '-', '.' and '_'. Their maximum length is 31 charac‐
6265 ters.
6266 discard: BlockdevDiscardOptions (optional)
6268 discard-related options (default: ignore)
6269 cache: BlockdevCacheOptions (optional)
6271 cache-related options
6272 read-only: boolean (optional)
6274 whether the block device should be read-only (default: false).
6275 Note that some block drivers support only read-only access, ei‐
6276 ther generally or in certain configurations. In this case, the
6277 default value does not work and the option must be specified ex‐
6278 plicitly.
6279 auto-read-only: boolean (optional)
6281 if true and read-only is false, QEMU may automatically decide
6282 not to open the image read-write as requested, but fall back to
6283 read-only instead (and switch between the modes later), e.g. de‐
6284 pending on whether the image file is writable or whether a writ‐
6285 ing user is attached to the node (default: false, since 3.1)
6286 detect-zeroes: BlockdevDetectZeroesOptions (optional)
6288 detect and optimize zero writes (Since 2.1) (default: off)
6289 force-share: boolean (optional)
6291 force share all permission on added nodes. Requires
6292 read-only=true. (Since 2.10)
6293 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
6295 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
6297 writes"
6298 The members of BlockdevOptionsBlkverify when driver is "blkverify"
6300 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
6302 The members of BlockdevOptionsGenericFormat when driver is "bochs"
6304 The members of BlockdevOptionsGenericFormat when driver is "cloop"
6306 The members of BlockdevOptionsGenericFormat when driver is "compress"
6308 The members of BlockdevOptionsCbw when driver is "copy-before-write"
6310 The members of BlockdevOptionsCor when driver is "copy-on-read"
6312 The members of BlockdevOptionsGenericFormat when driver is "dmg"
6314 The members of BlockdevOptionsFile when driver is "file"
6316 The members of BlockdevOptionsCurlFtp when driver is "ftp"
6318 The members of BlockdevOptionsCurlFtps when driver is "ftps"
6320 The members of BlockdevOptionsGluster when driver is "gluster"
6322 The members of BlockdevOptionsFile when driver is "host_cdrom" (If:
6324 HAVE_HOST_BLOCK_DEVICE)
6325 The members of BlockdevOptionsFile when driver is "host_device" (If:
6327 HAVE_HOST_BLOCK_DEVICE)
6328 The members of BlockdevOptionsCurlHttp when driver is "http"
6330 The members of BlockdevOptionsCurlHttps when driver is "https"
6332 The members of BlockdevOptionsIscsi when driver is "iscsi"
6334 The members of BlockdevOptionsLUKS when driver is "luks"
6336 The members of BlockdevOptionsNbd when driver is "nbd"
6338 The members of BlockdevOptionsNfs when driver is "nfs"
6340 The members of BlockdevOptionsNull when driver is "null-aio"
6342 The members of BlockdevOptionsNull when driver is "null-co"
6344 The members of BlockdevOptionsNVMe when driver is "nvme"
6346 The members of BlockdevOptionsGenericFormat when driver is "parallels"
6348 The members of BlockdevOptionsPreallocate when driver is "preallocate"
6350 The members of BlockdevOptionsQcow2 when driver is "qcow2"
6352 The members of BlockdevOptionsQcow when driver is "qcow"
6354 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
6356 The members of BlockdevOptionsQuorum when driver is "quorum"
6358 The members of BlockdevOptionsRaw when driver is "raw"
6360 The members of BlockdevOptionsRbd when driver is "rbd"
6362 The members of BlockdevOptionsReplication when driver is "replication"
6364 (If: CONFIG_REPLICATION)
6365 The members of BlockdevOptionsGenericFormat when driver is "snap‐
6367 shot-access"
6368 The members of BlockdevOptionsSsh when driver is "ssh"
6370 The members of BlockdevOptionsThrottle when driver is "throttle"
6372 The members of BlockdevOptionsGenericFormat when driver is "vdi"
6374 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
6376 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
6378 The members of BlockdevOptionsGenericFormat when driver is "vpc"
6380 The members of BlockdevOptionsVVFAT when driver is "vvfat"
6382 Remaining options are determined by the block driver.
6383 Since
6385 2.9
6386 BlockdevRef (Alternate)
6388 Reference to a block device.
6389 Members
6391 definition: BlockdevOptions
6392 defines a new block device inline
6393 reference: string
6395 references the ID of an existing block device
6396 Since
6398 2.9
6399 BlockdevRefOrNull (Alternate)
6401 Reference to a block device.
6402 Members
6404 definition: BlockdevOptions
6405 defines a new block device inline
6406 reference: string
6408 references the ID of an existing block device. An empty string
6409 means that no block device should be referenced. Deprecated;
6410 use null instead.
6411 null: null
6413 No block device should be referenced (since 2.10)
6414 Since
6416 2.9
6417 blockdev-add (Command)
6419 Creates a new block device.
6420 Arguments
6422 The members of BlockdevOptions
6423 Since
6425 2.9
6426 Example
6428 1.
6429 -> { "execute": "blockdev-add",
6430 "arguments": {
6431 "driver": "qcow2",
6432 "node-name": "test1",
6433 "file": {
6434 "driver": "file",
6435 "filename": "test.qcow2"
6436 }
6437 }
6438 }
6439 <- { "return": {} }
6440 2.
6442 -> { "execute": "blockdev-add",
6443 "arguments": {
6444 "driver": "qcow2",
6445 "node-name": "node0",
6446 "discard": "unmap",
6447 "cache": {
6448 "direct": true
6449 },
6450 "file": {
6451 "driver": "file",
6452 "filename": "/tmp/test.qcow2"
6453 },
6454 "backing": {
6455 "driver": "raw",
6456 "file": {
6457 "driver": "file",
6458 "filename": "/dev/fdset/4"
6459 }
6460 }
6461 }
6462 }
6463 <- { "return": {} }
6465 blockdev-reopen (Command)
6467 Reopens one or more block devices using the given set of options. Any
6468 option not specified will be reset to its default value regardless of
6469 its previous status. If an option cannot be changed or a particular
6470 driver does not support reopening then the command will return an er‐
6471 ror. All devices in the list are reopened in one transaction, so if one
6472 of them fails then the whole transaction is cancelled.
6473 The command receives a list of block devices to reopen. For each one of
6475 them, the top-level node-name option (from BlockdevOptions) must be
6476 specified and is used to select the block device to be reopened. Other
6477 node-name options must be either omitted or set to the current name of
6478 the appropriate node. This command won't change any node name and any
6479 attempt to do it will result in an error.
6480 In the case of options that refer to child nodes, the behavior of this
6482 command depends on the value:
6483 1. A set of options (BlockdevOptions): the child is reopened with
6485 the specified set of options.
6486 2. A reference to the current child: the child is reopened using its
6488 existing set of options.
6489 3. A reference to a different node: the current child is replaced
6491 with the specified one.
6492 4. NULL: the current child (if any) is detached.
6494 Options (1) and (2) are supported in all cases. Option (3) is supported
6496 for file and backing, and option (4) for backing only.
6497 Unlike with blockdev-add, the backing option must always be present un‐
6499 less the node being reopened does not have a backing file and its image
6500 does not have a default backing file name as part of its metadata.
6501 Arguments
6503 options: array of BlockdevOptions
6504 Not documented
6505 Since
6507 6.1
6508 blockdev-del (Command)
6510 Deletes a block device that has been added using blockdev-add. The
6511 command will fail if the node is attached to a device or is otherwise
6512 being used.
6513 Arguments
6515 node-name: string
6516 Name of the graph node to delete.
6517 Since
6519 2.9
6520 Example
6522 -> { "execute": "blockdev-add",
6523 "arguments": {
6524 "driver": "qcow2",
6525 "node-name": "node0",
6526 "file": {
6527 "driver": "file",
6528 "filename": "test.qcow2"
6529 }
6530 }
6531 }
6532 <- { "return": {} }
6533 -> { "execute": "blockdev-del",
6535 "arguments": { "node-name": "node0" }
6536 }
6537 <- { "return": {} }
6538 BlockdevCreateOptionsFile (Object)
6540 Driver specific image creation options for file.
6541 Members
6543 filename: string
6544 Filename for the new image file
6545 size: int
6547 Size of the virtual disk in bytes
6548 preallocation: PreallocMode (optional)
6550 Preallocation mode for the new image (default: off; allowed val‐
6551 ues: off, falloc (if CONFIG_POSIX_FALLOCATE), full (if CON‐
6552 FIG_POSIX))
6553 nocow: boolean (optional)
6555 Turn off copy-on-write (valid only on btrfs; default: off)
6556 extent-size-hint: int (optional)
6558 Extent size hint to add to the image file; 0 for not adding an
6559 extent size hint (default: 1 MB, since 5.1)
6560 Since
6562 2.12
6563 BlockdevCreateOptionsGluster (Object)
6565 Driver specific image creation options for gluster.
6566 Members
6568 location: BlockdevOptionsGluster
6569 Where to store the new image file
6570 size: int
6572 Size of the virtual disk in bytes
6573 preallocation: PreallocMode (optional)
6575 Preallocation mode for the new image (default: off; allowed val‐
6576 ues: off, falloc (if CONFIG_GLUSTERFS_FALLOCATE), full (if CON‐
6577 FIG_GLUSTERFS_ZEROFILL))
6578 Since
6580 2.12
6581 BlockdevCreateOptionsLUKS (Object)
6583 Driver specific image creation options for LUKS.
6584 Members
6586 file: BlockdevRef
6587 Node to create the image format on
6588 size: int
6590 Size of the virtual disk in bytes
6591 preallocation: PreallocMode (optional)
6593 Preallocation mode for the new image (since: 4.2) (default: off;
6594 allowed values: off, metadata, falloc, full)
6595 The members of QCryptoBlockCreateOptionsLUKS
6597 Since
6599 2.12
6600 BlockdevCreateOptionsNfs (Object)
6602 Driver specific image creation options for NFS.
6603 Members
6605 location: BlockdevOptionsNfs
6606 Where to store the new image file
6607 size: int
6609 Size of the virtual disk in bytes
6610 Since
6612 2.12
6613 BlockdevCreateOptionsParallels (Object)
6615 Driver specific image creation options for parallels.
6616 Members
6618 file: BlockdevRef
6619 Node to create the image format on
6620 size: int
6622 Size of the virtual disk in bytes
6623 cluster-size: int (optional)
6625 Cluster size in bytes (default: 1 MB)
6626 Since
6628 2.12
6629 BlockdevCreateOptionsQcow (Object)
6631 Driver specific image creation options for qcow.
6632 Members
6634 file: BlockdevRef
6635 Node to create the image format on
6636 size: int
6638 Size of the virtual disk in bytes
6639 backing-file: string (optional)
6641 File name of the backing file if a backing file should be used
6642 encrypt: QCryptoBlockCreateOptions (optional)
6644 Encryption options if the image should be encrypted
6645 Since
6647 2.12
6648 BlockdevQcow2Version (Enum)
6650 Values
6651 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
6652 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
6654 Since
6656 2.12
6657 Qcow2CompressionType (Enum)
6659 Compression type used in qcow2 image file
6660 Values
6662 zlib zlib compression, see <http://zlib.net/>
6663 zstd (If: CONFIG_ZSTD)
6665 zstd compression, see <http://github.com/facebook/zstd>
6666 Since
6668 5.1
6669 BlockdevCreateOptionsQcow2 (Object)
6671 Driver specific image creation options for qcow2.
6672 Members
6674 file: BlockdevRef
6675 Node to create the image format on
6676 data-file: BlockdevRef (optional)
6678 Node to use as an external data file in which all guest data is
6679 stored so that only metadata remains in the qcow2 file (since:
6680 4.0)
6681 data-file-raw: boolean (optional)
6683 True if the external data file must stay valid as a standalone
6684 (read-only) raw image without looking at qcow2 metadata (de‐
6685 fault: false; since: 4.0)
6686 extended-l2: boolean (optional)
6688 True to make the image have extended L2 entries (default: false;
6689 since 5.2)
6690 size: int
6692 Size of the virtual disk in bytes
6693 version: BlockdevQcow2Version (optional)
6695 Compatibility level (default: v3)
6696 backing-file: string (optional)
6698 File name of the backing file if a backing file should be used
6699 backing-fmt: BlockdevDriver (optional)
6701 Name of the block driver to use for the backing file
6702 encrypt: QCryptoBlockCreateOptions (optional)
6704 Encryption options if the image should be encrypted
6705 cluster-size: int (optional)
6707 qcow2 cluster size in bytes (default: 65536)
6708 preallocation: PreallocMode (optional)
6710 Preallocation mode for the new image (default: off; allowed val‐
6711 ues: off, falloc, full, metadata)
6712 lazy-refcounts: boolean (optional)
6714 True if refcounts may be updated lazily (default: off)
6715 refcount-bits: int (optional)
6717 Width of reference counts in bits (default: 16)
6718 compression-type: Qcow2CompressionType (optional)
6720 The image cluster compression method (default: zlib, since 5.1)
6721 Since
6723 2.12
6724 BlockdevCreateOptionsQed (Object)
6726 Driver specific image creation options for qed.
6727 Members
6729 file: BlockdevRef
6730 Node to create the image format on
6731 size: int
6733 Size of the virtual disk in bytes
6734 backing-file: string (optional)
6736 File name of the backing file if a backing file should be used
6737 backing-fmt: BlockdevDriver (optional)
6739 Name of the block driver to use for the backing file
6740 cluster-size: int (optional)
6742 Cluster size in bytes (default: 65536)
6743 table-size: int (optional)
6745 L1/L2 table size (in clusters)
6746 Since
6748 2.12
6749 BlockdevCreateOptionsRbd (Object)
6751 Driver specific image creation options for rbd/Ceph.
6752 Members
6754 location: BlockdevOptionsRbd
6755 Where to store the new image file. This location cannot point to
6756 a snapshot.
6757 size: int
6759 Size of the virtual disk in bytes
6760 cluster-size: int (optional)
6762 RBD object size
6763 encrypt: RbdEncryptionCreateOptions (optional)
6765 Image encryption options. (Since 6.1)
6766 Since
6768 2.12
6769 BlockdevVmdkSubformat (Enum)
6771 Subformat options for VMDK images
6772 Values
6774 monolithicSparse
6775 Single file image with sparse cluster allocation
6776 monolithicFlat
6778 Single flat data image and a descriptor file
6779 twoGbMaxExtentSparse
6781 Data is split into 2GB (per virtual LBA) sparse extent files, in
6782 addition to a descriptor file
6783 twoGbMaxExtentFlat
6785 Data is split into 2GB (per virtual LBA) flat extent files, in
6786 addition to a descriptor file
6787 streamOptimized
6789 Single file image sparse cluster allocation, optimized for
6790 streaming over network.
6791 Since
6793 4.0
6794 BlockdevVmdkAdapterType (Enum)
6796 Adapter type info for VMDK images
6797 Values
6799 ide Not documented
6800 buslogic
6802 Not documented
6803 lsilogic
6805 Not documented
6806 legacyESX
6808 Not documented
6809 Since
6811 4.0
6812 BlockdevCreateOptionsVmdk (Object)
6814 Driver specific image creation options for VMDK.
6815 Members
6817 file: BlockdevRef
6818 Where to store the new image file. This refers to the image file
6819 for monolithcSparse and streamOptimized format, or the descrip‐
6820 tor file for other formats.
6821 size: int
6823 Size of the virtual disk in bytes
6824 extents: array of BlockdevRef (optional)
6826 Where to store the data extents. Required for monolithcFlat,
6827 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For mono‐
6828 lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
6829 mats, the number of entries required is calculated as ex‐
6830 tent_number = virtual_size / 2GB. Providing more extents than
6831 will be used is an error.
6832 subformat: BlockdevVmdkSubformat (optional)
6834 The subformat of the VMDK image. Default: "monolithicSparse".
6835 backing-file: string (optional)
6837 The path of backing file. Default: no backing file is used.
6838 adapter-type: BlockdevVmdkAdapterType (optional)
6840 The adapter type used to fill in the descriptor. Default: ide.
6841 hwversion: string (optional)
6843 Hardware version. The meaningful options are "4" or "6". De‐
6844 fault: "4".
6845 toolsversion: string (optional)
6847 VMware guest tools version. Default: "2147483647" (Since 6.2)
6848 zeroed-grain: boolean (optional)
6850 Whether to enable zeroed-grain feature for sparse subformats.
6851 Default: false.
6852 Since
6854 4.0
6855 BlockdevCreateOptionsSsh (Object)
6857 Driver specific image creation options for SSH.
6858 Members
6860 location: BlockdevOptionsSsh
6861 Where to store the new image file
6862 size: int
6864 Size of the virtual disk in bytes
6865 Since
6867 2.12
6868 BlockdevCreateOptionsVdi (Object)
6870 Driver specific image creation options for VDI.
6871 Members
6873 file: BlockdevRef
6874 Node to create the image format on
6875 size: int
6877 Size of the virtual disk in bytes
6878 preallocation: PreallocMode (optional)
6880 Preallocation mode for the new image (default: off; allowed val‐
6881 ues: off, metadata)
6882 Since
6884 2.12
6885 BlockdevVhdxSubformat (Enum)
6887 Values
6888 dynamic
6889 Growing image file
6890 fixed Preallocated fixed-size image file
6892 Since
6894 2.12
6895 BlockdevCreateOptionsVhdx (Object)
6897 Driver specific image creation options for vhdx.
6898 Members
6900 file: BlockdevRef
6901 Node to create the image format on
6902 size: int
6904 Size of the virtual disk in bytes
6905 log-size: int (optional)
6907 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
6908 block-size: int (optional)
6910 Block size in bytes, must be a multiple of 1 MB and not larger
6911 than 256 MB (default: automatically choose a block size depend‐
6912 ing on the image size)
6913 subformat: BlockdevVhdxSubformat (optional)
6915 vhdx subformat (default: dynamic)
6916 block-state-zero: boolean (optional)
6918 Force use of payload blocks of type 'ZERO'. Non-standard, but
6919 default. Do not set to 'off' when using 'qemu-img convert' with
6920 subformat=dynamic.
6921 Since
6923 2.12
6924 BlockdevVpcSubformat (Enum)
6926 Values
6927 dynamic
6928 Growing image file
6929 fixed Preallocated fixed-size image file
6931 Since
6933 2.12
6934 BlockdevCreateOptionsVpc (Object)
6936 Driver specific image creation options for vpc (VHD).
6937 Members
6939 file: BlockdevRef
6940 Node to create the image format on
6941 size: int
6943 Size of the virtual disk in bytes
6944 subformat: BlockdevVpcSubformat (optional)
6946 vhdx subformat (default: dynamic)
6947 force-size: boolean (optional)
6949 Force use of the exact byte size instead of rounding to the next
6950 size that can be represented in CHS geometry (default: false)
6951 Since
6953 2.12
6954 BlockdevCreateOptions (Object)
6956 Options for creating an image format on a given node.
6957 Members
6959 driver: BlockdevDriver
6960 block driver to create the image format
6961 The members of BlockdevCreateOptionsFile when driver is "file"
6963 The members of BlockdevCreateOptionsGluster when driver is "gluster"
6965 The members of BlockdevCreateOptionsLUKS when driver is "luks"
6967 The members of BlockdevCreateOptionsNfs when driver is "nfs"
6969 The members of BlockdevCreateOptionsParallels when driver is "paral‐
6971 lels"
6972 The members of BlockdevCreateOptionsQcow when driver is "qcow"
6974 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
6976 The members of BlockdevCreateOptionsQed when driver is "qed"
6978 The members of BlockdevCreateOptionsRbd when driver is "rbd"
6980 The members of BlockdevCreateOptionsSsh when driver is "ssh"
6982 The members of BlockdevCreateOptionsVdi when driver is "vdi"
6984 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
6986 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
6988 The members of BlockdevCreateOptionsVpc when driver is "vpc"
6990 Since
6992 2.12
6993 blockdev-create (Command)
6995 Starts a job to create an image format on a given node. The job is au‐
6996 tomatically finalized, but a manual job-dismiss is required.
6997 Arguments
6999 job-id: string
7000 Identifier for the newly created job.
7001 options: BlockdevCreateOptions
7003 Options for the image creation.
7004 Since
7006 3.0
7007 BlockdevAmendOptionsLUKS (Object)
7009 Driver specific image amend options for LUKS.
7010 Members
7012 The members of QCryptoBlockAmendOptionsLUKS
7013 Since
7015 5.1
7016 BlockdevAmendOptionsQcow2 (Object)
7018 Driver specific image amend options for qcow2. For now, only encryp‐
7019 tion options can be amended
7020 encrypt Encryption options to be amended
7022 Members
7024 encrypt: QCryptoBlockAmendOptions (optional)
7025 Not documented
7026 Since
7028 5.1
7029 BlockdevAmendOptions (Object)
7031 Options for amending an image format
7032 Members
7034 driver: BlockdevDriver
7035 Block driver of the node to amend.
7036 The members of BlockdevAmendOptionsLUKS when driver is "luks"
7038 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
7040 Since
7042 5.1
7043 x-blockdev-amend (Command)
7045 Starts a job to amend format specific options of an existing open block
7046 device The job is automatically finalized, but a manual job-dismiss is
7047 required.
7048 Arguments
7050 job-id: string
7051 Identifier for the newly created job.
7052 node-name: string
7054 Name of the block node to work on
7055 options: BlockdevAmendOptions
7057 Options (driver specific)
7058 force: boolean (optional)
7060 Allow unsafe operations, format specific For luks that allows
7061 erase of the last active keyslot (permanent loss of data), and
7062 replacement of an active keyslot (possible loss of data if IO
7063 error happens)
7064 Features
7066 unstable
7067 This command is experimental.
7068 Since
7070 5.1
7071 BlockErrorAction (Enum)
7073 An enumeration of action that has been taken when a DISK I/O occurs
7074 Values
7076 ignore error has been ignored
7077 report error has been reported to the device
7079 stop error caused VM to be stopped
7081 Since
7083 2.1
7084 BLOCK_IMAGE_CORRUPTED (Event)
7086 Emitted when a disk image is being marked corrupt. The image can be
7087 identified by its device or node name. The 'device' field is always
7088 present for compatibility reasons, but it can be empty ("") if the im‐
7089 age does not have a device name associated.
7090 Arguments
7092 device: string
7093 device name. This is always present for compatibility reasons,
7094 but it can be empty ("") if the image does not have a device
7095 name associated.
7096 node-name: string (optional)
7098 node name (Since: 2.4)
7099 msg: string
7101 informative message for human consumption, such as the kind of
7102 corruption being detected. It should not be parsed by machine as
7103 it is not guaranteed to be stable
7104 offset: int (optional)
7106 if the corruption resulted from an image access, this is the
7107 host's access offset into the image
7108 size: int (optional)
7110 if the corruption resulted from an image access, this is the ac‐
7111 cess size
7112 fatal: boolean
7114 if set, the image is marked corrupt and therefore unusable after
7115 this event and must be repaired (Since 2.2; before, every
7116 BLOCK_IMAGE_CORRUPTED event was fatal)
7117 Note
7119 If action is "stop", a STOP event will eventually follow the
7120 BLOCK_IO_ERROR event.
7121 Example
7123 <- { "event": "BLOCK_IMAGE_CORRUPTED",
7124 "data": { "device": "", "node-name": "drive", "fatal": false,
7125 "msg": "L2 table offset 0x2a2a2a00 unaligned (L1 index: 0)" },
7126 "timestamp": { "seconds": 1648243240, "microseconds": 906060 } }
7127 Since
7129 1.7
7130 BLOCK_IO_ERROR (Event)
7132 Emitted when a disk I/O error occurs
7133 Arguments
7135 device: string
7136 device name. This is always present for compatibility reasons,
7137 but it can be empty ("") if the image does not have a device
7138 name associated.
7139 node-name: string (optional)
7141 node name. Note that errors may be reported for the root node
7142 that is directly attached to a guest device rather than for the
7143 node where the error occurred. The node name is not present if
7144 the drive is empty. (Since: 2.8)
7145 operation: IoOperationType
7147 I/O operation
7148 action: BlockErrorAction
7150 action that has been taken
7151 nospace: boolean (optional)
7153 true if I/O error was caused due to a no-space condition. This
7154 key is only present if query-block's io-status is present,
7155 please see query-block documentation for more information
7156 (since: 2.2)
7157 reason: string
7159 human readable string describing the error cause. (This field
7160 is a debugging aid for humans, it should not be parsed by appli‐
7161 cations) (since: 2.2)
7162 Note
7164 If action is "stop", a STOP event will eventually follow the
7165 BLOCK_IO_ERROR event
7166 Since
7168 0.13
7169 Example
7171 <- { "event": "BLOCK_IO_ERROR",
7172 "data": { "device": "ide0-hd1",
7173 "node-name": "#block212",
7174 "operation": "write",
7175 "action": "stop",
7176 "reason": "No space left on device" },
7177 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7178 BLOCK_JOB_COMPLETED (Event)
7180 Emitted when a block job has completed
7181 Arguments
7183 type: JobType
7184 job type
7185 device: string
7187 The job identifier. Originally the device name but other values
7188 are allowed since QEMU 2.7
7189 len: int
7191 maximum progress value
7192 offset: int
7194 current progress value. On success this is equal to len. On
7195 failure this is less than len
7196 speed: int
7198 rate limit, bytes per second
7199 error: string (optional)
7201 error message. Only present on failure. This field contains a
7202 human-readable error message. There are no semantics other than
7203 that streaming has failed and clients should not try to inter‐
7204 pret the error string
7205 Since
7207 1.1
7208 Example
7210 <- { "event": "BLOCK_JOB_COMPLETED",
7211 "data": { "type": "stream", "device": "virtio-disk0",
7212 "len": 10737418240, "offset": 10737418240,
7213 "speed": 0 },
7214 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
7215 BLOCK_JOB_CANCELLED (Event)
7217 Emitted when a block job has been cancelled
7218 Arguments
7220 type: JobType
7221 job type
7222 device: string
7224 The job identifier. Originally the device name but other values
7225 are allowed since QEMU 2.7
7226 len: int
7228 maximum progress value
7229 offset: int
7231 current progress value. On success this is equal to len. On
7232 failure this is less than len
7233 speed: int
7235 rate limit, bytes per second
7236 Since
7238 1.1
7239 Example
7241 <- { "event": "BLOCK_JOB_CANCELLED",
7242 "data": { "type": "stream", "device": "virtio-disk0",
7243 "len": 10737418240, "offset": 134217728,
7244 "speed": 0 },
7245 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
7246 BLOCK_JOB_ERROR (Event)
7248 Emitted when a block job encounters an error
7249 Arguments
7251 device: string
7252 The job identifier. Originally the device name but other values
7253 are allowed since QEMU 2.7
7254 operation: IoOperationType
7256 I/O operation
7257 action: BlockErrorAction
7259 action that has been taken
7260 Since
7262 1.3
7263 Example
7265 <- { "event": "BLOCK_JOB_ERROR",
7266 "data": { "device": "ide0-hd1",
7267 "operation": "write",
7268 "action": "stop" },
7269 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7270 BLOCK_JOB_READY (Event)
7272 Emitted when a block job is ready to complete
7273 Arguments
7275 type: JobType
7276 job type
7277 device: string
7279 The job identifier. Originally the device name but other values
7280 are allowed since QEMU 2.7
7281 len: int
7283 maximum progress value
7284 offset: int
7286 current progress value. On success this is equal to len. On
7287 failure this is less than len
7288 speed: int
7290 rate limit, bytes per second
7291 Note
7293 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
7294 event
7295 Since
7297 1.3
7298 Example
7300 <- { "event": "BLOCK_JOB_READY",
7301 "data": { "device": "drive0", "type": "mirror", "speed": 0,
7302 "len": 2097152, "offset": 2097152 }
7303 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7304 BLOCK_JOB_PENDING (Event)
7306 Emitted when a block job is awaiting explicit authorization to finalize
7307 graph changes via block-job-finalize. If this job is part of a transac‐
7308 tion, it will not emit this event until the transaction has converged
7309 first.
7310 Arguments
7312 type: JobType
7313 job type
7314 id: string
7316 The job identifier.
7317 Since
7319 2.12
7320 Example
7322 <- { "event": "BLOCK_JOB_PENDING",
7323 "data": { "type": "mirror", "id": "backup_1" },
7324 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7325 PreallocMode (Enum)
7327 Preallocation mode of QEMU image file
7328 Values
7330 off no preallocation
7331 metadata
7333 preallocate only for metadata
7334 falloc like full preallocation but allocate disk space by posix_fallo‐
7336 cate() rather than writing data.
7337 full preallocate all data by writing it to the device to ensure disk
7339 space is really available. This data may or may not be zero, de‐
7340 pending on the image format and storage. full preallocation
7341 also sets up metadata correctly.
7342 Since
7344 2.2
7345 BLOCK_WRITE_THRESHOLD (Event)
7347 Emitted when writes on block device reaches or exceeds the configured
7348 write threshold. For thin-provisioned devices, this means the device
7349 should be extended to avoid pausing for disk exhaustion. The event is
7350 one shot. Once triggered, it needs to be re-registered with another
7351 block-set-write-threshold command.
7352 Arguments
7354 node-name: string
7355 graph node name on which the threshold was exceeded.
7356 amount-exceeded: int
7358 amount of data which exceeded the threshold, in bytes.
7359 write-threshold: int
7361 last configured threshold, in bytes.
7362 Since
7364 2.3
7365 block-set-write-threshold (Command)
7367 Change the write threshold for a block drive. An event will be deliv‐
7368 ered if a write to this block drive crosses the configured threshold.
7369 The threshold is an offset, thus must be non-negative. Default is no
7370 write threshold. Setting the threshold to zero disables it.
7371 This is useful to transparently resize thin-provisioned drives without
7373 the guest OS noticing.
7374 Arguments
7376 node-name: string
7377 graph node name on which the threshold must be set.
7378 write-threshold: int
7380 configured threshold for the block device, bytes. Use 0 to dis‐
7381 able the threshold.
7382 Since
7384 2.3
7385 Example
7387 -> { "execute": "block-set-write-threshold",
7388 "arguments": { "node-name": "mydev",
7389 "write-threshold": 17179869184 } }
7390 <- { "return": {} }
7391 x-blockdev-change (Command)
7393 Dynamically reconfigure the block driver state graph. It can be used to
7394 add, remove, insert or replace a graph node. Currently only the Quorum
7395 driver implements this feature to add or remove its child. This is use‐
7396 ful to fix a broken quorum child.
7397 If node is specified, it will be inserted under parent. child may not
7399 be specified in this case. If both parent and child are specified but
7400 node is not, child will be detached from parent.
7401 Arguments
7403 parent: string
7404 the id or name of the parent node.
7405 child: string (optional)
7407 the name of a child under the given parent node.
7408 node: string (optional)
7410 the name of the node that will be added.
7411 Features
7413 unstable
7414 This command is experimental, and its API is not stable. It
7415 does not support all kinds of operations, all kinds of children,
7416 nor all block drivers.
7417 FIXME Removing children from a quorum node means introducing
7419 gaps in the child indices. This cannot be represented in the
7420 'children' list of BlockdevOptionsQuorum, as returned by
7421 .bdrv_refresh_filename().
7422 Warning: The data in a new quorum child MUST be consistent with
7424 that of the rest of the array.
7425 Since
7427 2.7
7428 Example
7430 1. Add a new node to a quorum
7431 -> { "execute": "blockdev-add",
7432 "arguments": {
7433 "driver": "raw",
7434 "node-name": "new_node",
7435 "file": { "driver": "file",
7436 "filename": "test.raw" } } }
7437 <- { "return": {} }
7438 -> { "execute": "x-blockdev-change",
7439 "arguments": { "parent": "disk1",
7440 "node": "new_node" } }
7441 <- { "return": {} }
7442 2. Delete a quorum's node
7444 -> { "execute": "x-blockdev-change",
7445 "arguments": { "parent": "disk1",
7446 "child": "children.1" } }
7447 <- { "return": {} }
7448 x-blockdev-set-iothread (Command)
7450 Move node and its children into the iothread. If iothread is null then
7451 move node and its children into the main loop.
7452 The node must not be attached to a BlockBackend.
7454 Arguments
7456 node-name: string
7457 the name of the block driver node
7458 iothread: StrOrNull
7460 the name of the IOThread object or null for the main loop
7461 force: boolean (optional)
7463 true if the node and its children should be moved when a Block‐
7464 Backend is already attached
7465 Features
7467 unstable
7468 This command is experimental and intended for test cases that
7469 need control over IOThreads only.
7470 Since
7472 2.12
7473 Example
7475 1. Move a node into an IOThread
7476 -> { "execute": "x-blockdev-set-iothread",
7477 "arguments": { "node-name": "disk1",
7478 "iothread": "iothread0" } }
7479 <- { "return": {} }
7480 2. Move a node into the main loop
7482 -> { "execute": "x-blockdev-set-iothread",
7483 "arguments": { "node-name": "disk1",
7484 "iothread": null } }
7485 <- { "return": {} }
7486 QuorumOpType (Enum)
7488 An enumeration of the quorum operation types
7489 Values
7491 read read operation
7492 write write operation
7494 flush flush operation
7496 Since
7498 2.6
7499 QUORUM_FAILURE (Event)
7501 Emitted by the Quorum block driver if it fails to establish a quorum
7502 Arguments
7504 reference: string
7505 device name if defined else node name
7506 sector-num: int
7508 number of the first sector of the failed read operation
7509 sectors-count: int
7511 failed read operation sector count
7512 Note
7514 This event is rate-limited.
7515 Since
7517 2.0
7518 Example
7520 <- { "event": "QUORUM_FAILURE",
7521 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
7522 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7523 QUORUM_REPORT_BAD (Event)
7525 Emitted to report a corruption of a Quorum file
7526 Arguments
7528 type: QuorumOpType
7529 quorum operation type (Since 2.6)
7530 error: string (optional)
7532 error message. Only present on failure. This field contains a
7533 human-readable error message. There are no semantics other than
7534 that the block layer reported an error and clients should not
7535 try to interpret the error string.
7536 node-name: string
7538 the graph node name of the block driver state
7539 sector-num: int
7541 number of the first sector of the failed read operation
7542 sectors-count: int
7544 failed read operation sector count
7545 Note
7547 This event is rate-limited.
7548 Since
7550 2.0
7551 Example
7553 1. Read operation
7554 { "event": "QUORUM_REPORT_BAD",
7556 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
7557 "type": "read" },
7558 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7559 2. Flush operation
7561 { "event": "QUORUM_REPORT_BAD",
7563 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
7564 "type": "flush", "error": "Broken pipe" },
7565 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
7566 BlockdevSnapshotInternal (Object)
7568 Members
7569 device: string
7570 the device name or node-name of a root node to generate the
7571 snapshot from
7572 name: string
7574 the name of the internal snapshot to be created
7575 Notes
7577 In transaction, if name is empty, or any snapshot matching name exists,
7578 the operation will fail. Only some image formats support it, for exam‐
7579 ple, qcow2, and rbd.
7580 Since
7582 1.7
7583 blockdev-snapshot-internal-sync (Command)
7585 Synchronously take an internal snapshot of a block device, when the
7586 format of the image used supports it. If the name is an empty string,
7587 or a snapshot with name already exists, the operation will fail.
7588 For the arguments, see the documentation of BlockdevSnapshotInternal.
7590 Returns
7592 • nothing on success
7593 • If device is not a valid block device, GenericError
7595 • If any snapshot matching name exists, or name is empty, GenericError
7597 • If the format of the image used does not support it, BlockFormatFea‐
7599 tureNotSupported
7600 Since
7602 1.7
7603 Example
7605 -> { "execute": "blockdev-snapshot-internal-sync",
7606 "arguments": { "device": "ide-hd0",
7607 "name": "snapshot0" }
7608 }
7609 <- { "return": {} }
7610 blockdev-snapshot-delete-internal-sync (Command)
7612 Synchronously delete an internal snapshot of a block device, when the
7613 format of the image used support it. The snapshot is identified by name
7614 or id or both. One of the name or id is required. Return SnapshotInfo
7615 for the successfully deleted snapshot.
7616 Arguments
7618 device: string
7619 the device name or node-name of a root node to delete the snap‐
7620 shot from
7621 id: string (optional)
7623 optional the snapshot's ID to be deleted
7624 name: string (optional)
7626 optional the snapshot's name to be deleted
7627 Returns
7629 • SnapshotInfo on success
7630 • If device is not a valid block device, GenericError
7632 • If snapshot not found, GenericError
7634 • If the format of the image used does not support it, BlockFormatFea‐
7636 tureNotSupported
7637 • If id and name are both not specified, GenericError
7639 Since
7641 1.7
7642 Example
7644 -> { "execute": "blockdev-snapshot-delete-internal-sync",
7645 "arguments": { "device": "ide-hd0",
7646 "name": "snapshot0" }
7647 }
7648 <- { "return": {
7649 "id": "1",
7650 "name": "snapshot0",
7651 "vm-state-size": 0,
7652 "date-sec": 1000012,
7653 "date-nsec": 10,
7654 "vm-clock-sec": 100,
7655 "vm-clock-nsec": 20,
7656 "icount": 220414
7657 }
7658 }
7659 Block device exports
7661 NbdServerOptions (Object)
7662 Keep this type consistent with the nbd-server-start arguments. The only
7663 intended difference is using SocketAddress instead of SocketAddressLe‐
7664 gacy.
7665 Members
7667 addr: SocketAddress
7668 Address on which to listen.
7669 tls-creds: string (optional)
7671 ID of the TLS credentials object (since 2.6).
7672 tls-authz: string (optional)
7674 ID of the QAuthZ authorization object used to validate the
7675 client's x509 distinguished name. This object is is only re‐
7676 solved at time of use, so can be deleted and recreated on the
7677 fly while the NBD server is active. If missing, it will default
7678 to denying access (since 4.0).
7679 max-connections: int (optional)
7681 The maximum number of connections to allow at the same time, 0
7682 for unlimited. (since 5.2; default: 0)
7683 Since
7685 4.2
7686 nbd-server-start (Command)
7688 Start an NBD server listening on the given host and port. Block de‐
7689 vices can then be exported using nbd-server-add. The NBD server will
7690 present them as named exports; for example, another QEMU instance could
7691 refer to them as "nbd:HOST:PORT:exportname=NAME".
7692 Keep this type consistent with the NbdServerOptions type. The only in‐
7694 tended difference is using SocketAddressLegacy instead of SocketAd‐
7695 dress.
7696 Arguments
7698 addr: SocketAddressLegacy
7699 Address on which to listen.
7700 tls-creds: string (optional)
7702 ID of the TLS credentials object (since 2.6).
7703 tls-authz: string (optional)
7705 ID of the QAuthZ authorization object used to validate the
7706 client's x509 distinguished name. This object is is only re‐
7707 solved at time of use, so can be deleted and recreated on the
7708 fly while the NBD server is active. If missing, it will default
7709 to denying access (since 4.0).
7710 max-connections: int (optional)
7712 The maximum number of connections to allow at the same time, 0
7713 for unlimited. (since 5.2; default: 0)
7714 Returns
7716 error if the server is already running.
7717 Since
7719 1.3
7720 BlockExportOptionsNbdBase (Object)
7722 An NBD block export (common options shared between nbd-server-add and
7723 the NBD branch of block-export-add).
7724 Members
7726 name: string (optional)
7727 Export name. If unspecified, the device parameter is used as the
7728 export name. (Since 2.12)
7729 description: string (optional)
7731 Free-form description of the export, up to 4096 bytes. (Since
7732 5.0)
7733 Since
7735 5.0
7736 BlockExportOptionsNbd (Object)
7738 An NBD block export (distinct options used in the NBD branch of
7739 block-export-add).
7740 Members
7742 bitmaps: array of string (optional)
7743 Also export each of the named dirty bitmaps reachable from de‐
7744 vice, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
7745 the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
7746 each bitmap.
7747 allocation-depth: boolean (optional)
7749 Also export the allocation depth map for device, so the NBD
7750 client can use NBD_OPT_SET_META_CONTEXT with the metadata con‐
7751 text name "qemu:allocation-depth" to inspect allocation details.
7752 (since 5.2)
7753 The members of BlockExportOptionsNbdBase
7755 Since
7757 5.2
7758 BlockExportOptionsVhostUserBlk (Object)
7760 A vhost-user-blk block export.
7761 Members
7763 addr: SocketAddress
7764 The vhost-user socket on which to listen. Both 'unix' and 'fd'
7765 SocketAddress types are supported. Passed fds must be UNIX do‐
7766 main sockets.
7767 logical-block-size: int (optional)
7769 Logical block size in bytes. Defaults to 512 bytes.
7770 num-queues: int (optional)
7772 Number of request virtqueues. Must be greater than 0. Defaults
7773 to 1.
7774 Since
7776 5.2
7777 FuseExportAllowOther (Enum)
7779 Possible allow_other modes for FUSE exports.
7780 Values
7782 off Do not pass allow_other as a mount option.
7783 on Pass allow_other as a mount option.
7785 auto Try mounting with allow_other first, and if that fails, retry
7787 without allow_other.
7788 Since
7790 6.1
7791 BlockExportOptionsFuse (Object)
7793 Options for exporting a block graph node on some (file) mountpoint as a
7794 raw image.
7795 Members
7797 mountpoint: string
7798 Path on which to export the block device via FUSE. This must
7799 point to an existing regular file.
7800 growable: boolean (optional)
7802 Whether writes beyond the EOF should grow the block node accord‐
7803 ingly. (default: false)
7804 allow-other: FuseExportAllowOther (optional)
7806 If this is off, only qemu's user is allowed access to this ex‐
7807 port. That cannot be changed even with chmod or chown. En‐
7808 abling this option will allow other users access to the export
7809 with the FUSE mount option "allow_other". Note that using al‐
7810 low_other as a non-root user requires user_allow_other to be en‐
7811 abled in the global fuse.conf configuration file. In auto mode
7812 (the default), the FUSE export driver will first attempt to
7813 mount the export with allow_other, and if that fails, try again
7814 without. (since 6.1; default: auto)
7815 Since
7817 6.0
7818 If
7820 CONFIG_FUSE
7821 NbdServerAddOptions (Object)
7823 An NBD block export, per legacy nbd-server-add command.
7824 Members
7826 device: string
7827 The device name or node name of the node to be exported
7828 writable: boolean (optional)
7830 Whether clients should be able to write to the device via the
7831 NBD connection (default false).
7832 bitmap: string (optional)
7834 Also export a single dirty bitmap reachable from device, so the
7835 NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
7836 context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
7837 (since 4.0).
7838 The members of BlockExportOptionsNbdBase
7840 Since
7842 5.0
7843 nbd-server-add (Command)
7845 Export a block node to QEMU's embedded NBD server.
7846 The export name will be used as the id for the resulting block export.
7848 Arguments
7850 The members of NbdServerAddOptions
7851 Features
7853 deprecated
7854 This command is deprecated. Use block-export-add instead.
7855 Returns
7857 error if the server is not running, or export with the same name al‐
7858 ready exists.
7859 Since
7861 1.3
7862 BlockExportRemoveMode (Enum)
7864 Mode for removing a block export.
7865 Values
7867 safe Remove export if there are no existing connections, fail other‐
7868 wise.
7869 hard Drop all connections immediately and remove export.
7871 TODO
7873 Potential additional modes to be added in the future:
7874 hide: Just hide export from new clients, leave existing connections as
7876 is. Remove export after all clients are disconnected.
7877 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
7879 ther requests from existing clients.
7880 Since
7882 2.12
7883 nbd-server-remove (Command)
7885 Remove NBD export by name.
7886 Arguments
7888 name: string
7889 Block export id.
7890 mode: BlockExportRemoveMode (optional)
7892 Mode of command operation. See BlockExportRemoveMode descrip‐
7893 tion. Default is 'safe'.
7894 Features
7896 deprecated
7897 This command is deprecated. Use block-export-del instead.
7898 Returns
7900 error if
7901 • the server is not running
7903 • export is not found
7905 • mode is 'safe' and there are existing connections
7907 Since
7909 2.12
7910 nbd-server-stop (Command)
7912 Stop QEMU's embedded NBD server, and unregister all devices previously
7913 added via nbd-server-add.
7914 Since
7916 1.3
7917 BlockExportType (Enum)
7919 An enumeration of block export types
7920 Values
7922 nbd NBD export
7923 vhost-user-blk (If: CONFIG_VHOST_USER_BLK_SERVER)
7925 vhost-user-blk export (since 5.2)
7926 fuse (If: CONFIG_FUSE)
7928 FUSE export (since: 6.0)
7929 Since
7931 4.2
7932 BlockExportOptions (Object)
7934 Describes a block export, i.e. how single node should be exported on an
7935 external interface.
7936 Members
7938 id: string
7939 A unique identifier for the block export (across all export
7940 types)
7941 node-name: string
7943 The node name of the block node to be exported (since: 5.2)
7944 writable: boolean (optional)
7946 True if clients should be able to write to the export (default
7947 false)
7948 writethrough: boolean (optional)
7950 If true, caches are flushed after every write request to the ex‐
7951 port before completion is signalled. (since: 5.2; default:
7952 false)
7953 iothread: string (optional)
7955 The name of the iothread object where the export will run. The
7956 default is to use the thread currently associated with the block
7957 node. (since: 5.2)
7958 fixed-iothread: boolean (optional)
7960 True prevents the block node from being moved to another thread
7961 while the export is active. If true and iothread is given, ex‐
7962 port creation fails if the block node cannot be moved to the io‐
7963 thread. The default is false. (since: 5.2)
7964 type: BlockExportType
7966 Not documented
7967 The members of BlockExportOptionsNbd when type is "nbd"
7969 The members of BlockExportOptionsVhostUserBlk when type is
7971 "vhost-user-blk" (If: CONFIG_VHOST_USER_BLK_SERVER)
7972 The members of BlockExportOptionsFuse when type is "fuse" (If: CON‐
7974 FIG_FUSE)
7975 Since
7977 4.2
7978 block-export-add (Command)
7980 Creates a new block export.
7981 Arguments
7983 The members of BlockExportOptions
7984 Since
7986 5.2
7987 block-export-del (Command)
7989 Request to remove a block export. This drops the user's reference to
7990 the export, but the export may still stay around after this command re‐
7991 turns until the shutdown of the export has completed.
7992 Arguments
7994 id: string
7995 Block export id.
7996 mode: BlockExportRemoveMode (optional)
7998 Mode of command operation. See BlockExportRemoveMode descrip‐
7999 tion. Default is 'safe'.
8000 Returns
8002 Error if the export is not found or mode is 'safe' and the export is
8003 still in use (e.g. by existing client connections)
8004 Since
8006 5.2
8007 BLOCK_EXPORT_DELETED (Event)
8009 Emitted when a block export is removed and its id can be reused.
8010 Arguments
8012 id: string
8013 Block export id.
8014 Since
8016 5.2
8017 BlockExportInfo (Object)
8019 Information about a single block export.
8020 Members
8022 id: string
8023 The unique identifier for the block export
8024 type: BlockExportType
8026 The block export type
8027 node-name: string
8029 The node name of the block node that is exported
8030 shutting-down: boolean
8032 True if the export is shutting down (e.g. after a block-ex‐
8033 port-del command, but before the shutdown has completed)
8034 Since
8036 5.2
8037 query-block-exports (Command)
8039 Returns
8040 A list of BlockExportInfo describing all block exports
8041 Since
8043 5.2
8044
8046 ChardevInfo (Object)
8047 Information about a character device.
8048 Members
8050 label: string
8051 the label of the character device
8052 filename: string
8054 the filename of the character device
8055 frontend-open: boolean
8057 shows whether the frontend device attached to this backend (eg.
8058 with the chardev=... option) is in open or closed state (since
8059 2.1)
8060 Notes
8062 filename is encoded using the QEMU command line character device encod‐
8063 ing. See the QEMU man page for details.
8064 Since
8066 0.14
8067 query-chardev (Command)
8069 Returns information about current character devices.
8070 Returns
8072 a list of ChardevInfo
8073 Since
8075 0.14
8076 Example
8078 -> { "execute": "query-chardev" }
8079 <- {
8080 "return": [
8081 {
8082 "label": "charchannel0",
8083 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
8084 "frontend-open": false
8085 },
8086 {
8087 "label": "charmonitor",
8088 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
8089 "frontend-open": true
8090 },
8091 {
8092 "label": "charserial0",
8093 "filename": "pty:/dev/pts/2",
8094 "frontend-open": true
8095 }
8096 ]
8097 }
8098 ChardevBackendInfo (Object)
8100 Information about a character device backend
8101 Members
8103 name: string
8104 The backend name
8105 Since
8107 2.0
8108 query-chardev-backends (Command)
8110 Returns information about character device backends.
8111 Returns
8113 a list of ChardevBackendInfo
8114 Since
8116 2.0
8117 Example
8119 -> { "execute": "query-chardev-backends" }
8120 <- {
8121 "return":[
8122 {
8123 "name":"udp"
8124 },
8125 {
8126 "name":"tcp"
8127 },
8128 {
8129 "name":"unix"
8130 },
8131 {
8132 "name":"spiceport"
8133 }
8134 ]
8135 }
8136 DataFormat (Enum)
8138 An enumeration of data format.
8139 Values
8141 utf8 Data is a UTF-8 string (RFC 3629)
8142 base64 Data is Base64 encoded binary (RFC 3548)
8144 Since
8146 1.4
8147 ringbuf-write (Command)
8149 Write to a ring buffer character device.
8150 Arguments
8152 device: string
8153 the ring buffer character device name
8154 data: string
8156 data to write
8157 format: DataFormat (optional)
8159 data encoding (default 'utf8').
8160 • base64: data must be base64 encoded text. Its binary decoding
8162 gets written.
8163 • utf8: data's UTF-8 encoding is written
8165 • data itself is always Unicode regardless of format, like any
8167 other string.
8168 Returns
8170 Nothing on success
8171 Since
8173 1.4
8174 Example
8176 -> { "execute": "ringbuf-write",
8177 "arguments": { "device": "foo",
8178 "data": "abcdefgh",
8179 "format": "utf8" } }
8180 <- { "return": {} }
8181 ringbuf-read (Command)
8183 Read from a ring buffer character device.
8184 Arguments
8186 device: string
8187 the ring buffer character device name
8188 size: int
8190 how many bytes to read at most
8191 format: DataFormat (optional)
8193 data encoding (default 'utf8').
8194 • base64: the data read is returned in base64 encoding.
8196 • utf8: the data read is interpreted as UTF-8. Bug: can screw
8198 up when the buffer contains invalid UTF-8 sequences, NUL char‐
8199 acters, after the ring buffer lost data, and when reading
8200 stops because the size limit is reached.
8201 • The return value is always Unicode regardless of format, like
8203 any other string.
8204 Returns
8206 data read from the device
8207 Since
8209 1.4
8210 Example
8212 -> { "execute": "ringbuf-read",
8213 "arguments": { "device": "foo",
8214 "size": 1000,
8215 "format": "utf8" } }
8216 <- { "return": "abcdefgh" }
8217 ChardevCommon (Object)
8219 Configuration shared across all chardev backends
8220 Members
8222 logfile: string (optional)
8223 The name of a logfile to save output
8224 logappend: boolean (optional)
8226 true to append instead of truncate (default to false to trun‐
8227 cate)
8228 Since
8230 2.6
8231 ChardevFile (Object)
8233 Configuration info for file chardevs.
8234 Members
8236 in: string (optional)
8237 The name of the input file
8238 out: string
8240 The name of the output file
8241 append: boolean (optional)
8243 Open the file in append mode (default false to truncate) (Since
8244 2.6)
8245 The members of ChardevCommon
8247 Since
8249 1.4
8250 ChardevHostdev (Object)
8252 Configuration info for device and pipe chardevs.
8253 Members
8255 device: string
8256 The name of the special file for the device, i.e. /dev/ttyS0 on
8257 Unix or COM1: on Windows
8258 The members of ChardevCommon
8260 Since
8262 1.4
8263 ChardevSocket (Object)
8265 Configuration info for (stream) socket chardevs.
8266 Members
8268 addr: SocketAddressLegacy
8269 socket address to listen on (server=true) or connect to
8270 (server=false)
8271 tls-creds: string (optional)
8273 the ID of the TLS credentials object (since 2.6)
8274 tls-authz: string (optional)
8276 the ID of the QAuthZ authorization object against which the
8277 client's x509 distinguished name will be validated. This object
8278 is only resolved at time of use, so can be deleted and recreated
8279 on the fly while the chardev server is active. If missing, it
8280 will default to denying access (since 4.0)
8281 server: boolean (optional)
8283 create server socket (default: true)
8284 wait: boolean (optional)
8286 wait for incoming connection on server sockets (default: false).
8287 Silently ignored with server: false. This use is deprecated.
8288 nodelay: boolean (optional)
8290 set TCP_NODELAY socket option (default: false)
8291 telnet: boolean (optional)
8293 enable telnet protocol on server sockets (default: false)
8294 tn3270: boolean (optional)
8296 enable tn3270 protocol on server sockets (default: false)
8297 (Since: 2.10)
8298 websocket: boolean (optional)
8300 enable websocket protocol on server sockets (default: false)
8301 (Since: 3.1)
8302 reconnect: int (optional)
8304 For a client socket, if a socket is disconnected, then attempt a
8305 reconnect after the given number of seconds. Setting this to
8306 zero disables this function. (default: 0) (Since: 2.2)
8307 The members of ChardevCommon
8309 Since
8311 1.4
8312 ChardevUdp (Object)
8314 Configuration info for datagram socket chardevs.
8315 Members
8317 remote: SocketAddressLegacy
8318 remote address
8319 local: SocketAddressLegacy (optional)
8321 local address
8322 The members of ChardevCommon
8324 Since
8326 1.5
8327 ChardevMux (Object)
8329 Configuration info for mux chardevs.
8330 Members
8332 chardev: string
8333 name of the base chardev.
8334 The members of ChardevCommon
8336 Since
8338 1.5
8339 ChardevStdio (Object)
8341 Configuration info for stdio chardevs.
8342 Members
8344 signal: boolean (optional)
8345 Allow signals (such as SIGINT triggered by ^C) be delivered to
8346 qemu. Default: true.
8347 The members of ChardevCommon
8349 Since
8351 1.5
8352 ChardevSpiceChannel (Object)
8354 Configuration info for spice vm channel chardevs.
8355 Members
8357 type: string
8358 kind of channel (for example vdagent).
8359 The members of ChardevCommon
8361 Since
8363 1.5
8364 If
8366 CONFIG_SPICE
8367 ChardevSpicePort (Object)
8369 Configuration info for spice port chardevs.
8370 Members
8372 fqdn: string
8373 name of the channel (see docs/spice-port-fqdn.txt)
8374 The members of ChardevCommon
8376 Since
8378 1.5
8379 If
8381 CONFIG_SPICE
8382 ChardevDBus (Object)
8384 Configuration info for DBus chardevs.
8385 Members
8387 name: string
8388 name of the channel (following docs/spice-port-fqdn.txt)
8389 The members of ChardevCommon
8391 Since
8393 7.0
8394 If
8396 CONFIG_DBUS_DISPLAY
8397 ChardevVC (Object)
8399 Configuration info for virtual console chardevs.
8400 Members
8402 width: int (optional)
8403 console width, in pixels
8404 height: int (optional)
8406 console height, in pixels
8407 cols: int (optional)
8409 console width, in chars
8410 rows: int (optional)
8412 console height, in chars
8413 The members of ChardevCommon
8415 Since
8417 1.5
8418 ChardevRingbuf (Object)
8420 Configuration info for ring buffer chardevs.
8421 Members
8423 size: int (optional)
8424 ring buffer size, must be power of two, default is 65536
8425 The members of ChardevCommon
8427 Since
8429 1.5
8430 ChardevQemuVDAgent (Object)
8432 Configuration info for qemu vdagent implementation.
8433 Members
8435 mouse: boolean (optional)
8436 enable/disable mouse, default is enabled.
8437 clipboard: boolean (optional)
8439 enable/disable clipboard, default is disabled.
8440 The members of ChardevCommon
8442 Since
8444 6.1
8445 If
8447 CONFIG_SPICE_PROTOCOL
8448 ChardevBackendKind (Enum)
8450 Values
8451 pipe Since 1.5
8452 udp Since 1.5
8454 mux Since 1.5
8456 msmouse
8458 Since 1.5
8459 wctablet
8461 Since 2.9
8462 braille
8464 Since 1.5
8465 testdev
8467 Since 2.2
8468 stdio Since 1.5
8470 console
8472 Since 1.5
8473 spicevmc (If: CONFIG_SPICE)
8475 Since 1.5
8476 spiceport (If: CONFIG_SPICE)
8478 Since 1.5
8479 qemu-vdagent (If: CONFIG_SPICE_PROTOCOL)
8481 Since 6.1
8482 dbus (If: CONFIG_DBUS_DISPLAY)
8484 Since 7.0
8485 vc v1.5
8487 ringbuf
8489 Since 1.6
8490 memory Since 1.5
8492 file Not documented
8494 serial Not documented
8496 parallel
8498 Not documented
8499 socket Not documented
8501 pty Not documented
8503 null Not documented
8505 Since
8507 1.4
8508 ChardevFileWrapper (Object)
8510 Members
8511 data: ChardevFile
8512 Not documented
8513 Since
8515 1.4
8516 ChardevHostdevWrapper (Object)
8518 Members
8519 data: ChardevHostdev
8520 Not documented
8521 Since
8523 1.4
8524 ChardevSocketWrapper (Object)
8526 Members
8527 data: ChardevSocket
8528 Not documented
8529 Since
8531 1.4
8532 ChardevUdpWrapper (Object)
8534 Members
8535 data: ChardevUdp
8536 Not documented
8537 Since
8539 1.5
8540 ChardevCommonWrapper (Object)
8542 Members
8543 data: ChardevCommon
8544 Not documented
8545 Since
8547 2.6
8548 ChardevMuxWrapper (Object)
8550 Members
8551 data: ChardevMux
8552 Not documented
8553 Since
8555 1.5
8556 ChardevStdioWrapper (Object)
8558 Members
8559 data: ChardevStdio
8560 Not documented
8561 Since
8563 1.5
8564 ChardevSpiceChannelWrapper (Object)
8566 Members
8567 data: ChardevSpiceChannel
8568 Not documented
8569 Since
8571 1.5
8572 If
8574 CONFIG_SPICE
8575 ChardevSpicePortWrapper (Object)
8577 Members
8578 data: ChardevSpicePort
8579 Not documented
8580 Since
8582 1.5
8583 If
8585 CONFIG_SPICE
8586 ChardevQemuVDAgentWrapper (Object)
8588 Members
8589 data: ChardevQemuVDAgent
8590 Not documented
8591 Since
8593 6.1
8594 If
8596 CONFIG_SPICE_PROTOCOL
8597 ChardevDBusWrapper (Object)
8599 Members
8600 data: ChardevDBus
8601 Not documented
8602 Since
8604 7.0
8605 If
8607 CONFIG_DBUS_DISPLAY
8608 ChardevVCWrapper (Object)
8610 Members
8611 data: ChardevVC
8612 Not documented
8613 Since
8615 1.5
8616 ChardevRingbufWrapper (Object)
8618 Members
8619 data: ChardevRingbuf
8620 Not documented
8621 Since
8623 1.5
8624 ChardevBackend (Object)
8626 Configuration info for the new chardev backend.
8627 Members
8629 type: ChardevBackendKind
8630 Not documented
8631 The members of ChardevFileWrapper when type is "file"
8633 The members of ChardevHostdevWrapper when type is "serial"
8635 The members of ChardevHostdevWrapper when type is "parallel"
8637 The members of ChardevHostdevWrapper when type is "pipe"
8639 The members of ChardevSocketWrapper when type is "socket"
8641 The members of ChardevUdpWrapper when type is "udp"
8643 The members of ChardevCommonWrapper when type is "pty"
8645 The members of ChardevCommonWrapper when type is "null"
8647 The members of ChardevMuxWrapper when type is "mux"
8649 The members of ChardevCommonWrapper when type is "msmouse"
8651 The members of ChardevCommonWrapper when type is "wctablet"
8653 The members of ChardevCommonWrapper when type is "braille"
8655 The members of ChardevCommonWrapper when type is "testdev"
8657 The members of ChardevStdioWrapper when type is "stdio"
8659 The members of ChardevCommonWrapper when type is "console"
8661 The members of ChardevSpiceChannelWrapper when type is "spicevmc" (If:
8663 CONFIG_SPICE)
8664 The members of ChardevSpicePortWrapper when type is "spiceport" (If:
8666 CONFIG_SPICE)
8667 The members of ChardevQemuVDAgentWrapper when type is "qemu-vdagent"
8669 (If: CONFIG_SPICE_PROTOCOL)
8670 The members of ChardevDBusWrapper when type is "dbus" (If: CON‐
8672 FIG_DBUS_DISPLAY)
8673 The members of ChardevVCWrapper when type is "vc"
8675 The members of ChardevRingbufWrapper when type is "ringbuf"
8677 The members of ChardevRingbufWrapper when type is "memory"
8679 Since
8681 1.4
8682 ChardevReturn (Object)
8684 Return info about the chardev backend just created.
8685 Members
8687 pty: string (optional)
8688 name of the slave pseudoterminal device, present if and only if
8689 a chardev of type 'pty' was created
8690 Since
8692 1.4
8693 chardev-add (Command)
8695 Add a character device backend
8696 Arguments
8698 id: string
8699 the chardev's ID, must be unique
8700 backend: ChardevBackend
8702 backend type and parameters
8703 Returns
8705 ChardevReturn.
8706 Since
8708 1.4
8709 Example
8711 -> { "execute" : "chardev-add",
8712 "arguments" : { "id" : "foo",
8713 "backend" : { "type" : "null", "data" : {} } } }
8714 <- { "return": {} }
8715 -> { "execute" : "chardev-add",
8717 "arguments" : { "id" : "bar",
8718 "backend" : { "type" : "file",
8719 "data" : { "out" : "/tmp/bar.log" } } } }
8720 <- { "return": {} }
8721 -> { "execute" : "chardev-add",
8723 "arguments" : { "id" : "baz",
8724 "backend" : { "type" : "pty", "data" : {} } } }
8725 <- { "return": { "pty" : "/dev/pty/42" } }
8726 chardev-change (Command)
8728 Change a character device backend
8729 Arguments
8731 id: string
8732 the chardev's ID, must exist
8733 backend: ChardevBackend
8735 new backend type and parameters
8736 Returns
8738 ChardevReturn.
8739 Since
8741 2.10
8742 Example
8744 -> { "execute" : "chardev-change",
8745 "arguments" : { "id" : "baz",
8746 "backend" : { "type" : "pty", "data" : {} } } }
8747 <- { "return": { "pty" : "/dev/pty/42" } }
8748 -> {"execute" : "chardev-change",
8750 "arguments" : {
8751 "id" : "charchannel2",
8752 "backend" : {
8753 "type" : "socket",
8754 "data" : {
8755 "addr" : {
8756 "type" : "unix" ,
8757 "data" : {
8758 "path" : "/tmp/charchannel2.socket"
8759 }
8760 },
8761 "server" : true,
8762 "wait" : false }}}}
8763 <- {"return": {}}
8764 chardev-remove (Command)
8766 Remove a character device backend
8767 Arguments
8769 id: string
8770 the chardev's ID, must exist and not be in use
8771 Returns
8773 Nothing on success
8774 Since
8776 1.4
8777 Example
8779 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
8780 <- { "return": {} }
8781 chardev-send-break (Command)
8783 Send a break to a character device
8784 Arguments
8786 id: string
8787 the chardev's ID, must exist
8788 Returns
8790 Nothing on success
8791 Since
8793 2.10
8794 Example
8796 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
8797 <- { "return": {} }
8798 VSERPORT_CHANGE (Event)
8800 Emitted when the guest opens or closes a virtio-serial port.
8801 Arguments
8803 id: string
8804 device identifier of the virtio-serial port
8805 open: boolean
8807 true if the guest has opened the virtio-serial port
8808 Note
8810 This event is rate-limited.
8811 Since
8813 2.1
8814 Example
8816 <- { "event": "VSERPORT_CHANGE",
8817 "data": { "id": "channel0", "open": true },
8818 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
8819
8821 qmp_capabilities (Command)
8822 Enable QMP capabilities.
8823 Arguments:
8825 Arguments
8827 enable: array of QMPCapability (optional)
8828 An optional list of QMPCapability values to enable. The client
8829 must not enable any capability that is not mentioned in the QMP
8830 greeting message. If the field is not provided, it means no QMP
8831 capabilities will be enabled. (since 2.12)
8832 Example
8834 -> { "execute": "qmp_capabilities",
8835 "arguments": { "enable": [ "oob" ] } }
8836 <- { "return": {} }
8837 Notes
8839 This command is valid exactly when first connecting: it must be issued
8840 before any other command will be accepted, and will fail once the moni‐
8841 tor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
8842 The QMP client needs to explicitly enable QMP capabilities, otherwise
8844 all the QMP capabilities will be turned off by default.
8845 Since
8847 0.13
8848 QMPCapability (Enum)
8850 Enumeration of capabilities to be advertised during initial client con‐
8851 nection, used for agreeing on particular QMP extension behaviors.
8852 Values
8854 oob QMP ability to support out-of-band requests. (Please refer to
8855 qmp-spec.txt for more information on OOB)
8856 Since
8858 2.12
8859 VersionTriple (Object)
8861 A three-part version number.
8862 Members
8864 major: int
8865 The major version number.
8866 minor: int
8868 The minor version number.
8869 micro: int
8871 The micro version number.
8872 Since
8874 2.4
8875 VersionInfo (Object)
8877 A description of QEMU's version.
8878 Members
8880 qemu: VersionTriple
8881 The version of QEMU. By current convention, a micro version of
8882 50 signifies a development branch. A micro version greater than
8883 or equal to 90 signifies a release candidate for the next minor
8884 version. A micro version of less than 50 signifies a stable re‐
8885 lease.
8886 package: string
8888 QEMU will always set this field to an empty string. Downstream
8889 versions of QEMU should set this to a non-empty string. The ex‐
8890 act format depends on the downstream however it highly recom‐
8891 mended that a unique name is used.
8892 Since
8894 0.14
8895 query-version (Command)
8897 Returns the current version of QEMU.
8898 Returns
8900 A VersionInfo object describing the current version of QEMU.
8901 Since
8903 0.14
8904 Example
8906 -> { "execute": "query-version" }
8907 <- {
8908 "return":{
8909 "qemu":{
8910 "major":0,
8911 "minor":11,
8912 "micro":5
8913 },
8914 "package":""
8915 }
8916 }
8917 CommandInfo (Object)
8919 Information about a QMP command
8920 Members
8922 name: string
8923 The command name
8924 Since
8926 0.14
8927 query-commands (Command)
8929 Return a list of supported QMP commands by this server
8930 Returns
8932 A list of CommandInfo for all supported commands
8933 Since
8935 0.14
8936 Example
8938 -> { "execute": "query-commands" }
8939 <- {
8940 "return":[
8941 {
8942 "name":"query-balloon"
8943 },
8944 {
8945 "name":"system_powerdown"
8946 }
8947 ]
8948 }
8949 Note
8951 This example has been shortened as the real response is too long.
8952 quit (Command)
8954 This command will cause the QEMU process to exit gracefully. While ev‐
8955 ery attempt is made to send the QMP response before terminating, this
8956 is not guaranteed. When using this interface, a premature EOF would
8957 not be unexpected.
8958 Since
8960 0.14
8961 Example
8963 -> { "execute": "quit" }
8964 <- { "return": {} }
8965 MonitorMode (Enum)
8967 An enumeration of monitor modes.
8968 Values
8970 readline
8971 HMP monitor (human-oriented command line interface)
8972 control
8974 QMP monitor (JSON-based machine interface)
8975 Since
8977 5.0
8978 MonitorOptions (Object)
8980 Options to be used for adding a new monitor.
8981 Members
8983 id: string (optional)
8984 Name of the monitor
8985 mode: MonitorMode (optional)
8987 Selects the monitor mode (default: readline in the system emula‐
8988 tor, control in qemu-storage-daemon)
8989 pretty: boolean (optional)
8991 Enables pretty printing (QMP only)
8992 chardev: string
8994 Name of a character device to expose the monitor on
8995 Since
8997 5.0
8998
9000 query-qmp-schema (Command)
9001 Command query-qmp-schema exposes the QMP wire ABI as an array of
9002 SchemaInfo. This lets QMP clients figure out what commands and events
9003 are available in this QEMU, and their parameters and results.
9004 However, the SchemaInfo can't reflect all the rules and restrictions
9006 that apply to QMP. It's interface introspection (figuring out what's
9007 there), not interface specification. The specification is in the QAPI
9008 schema.
9009 Furthermore, while we strive to keep the QMP wire format backwards-com‐
9011 patible across qemu versions, the introspection output is not guaran‐
9012 teed to have the same stability. For example, one version of qemu may
9013 list an object member as an optional non-variant, while another lists
9014 the same member only through the object's variants; or the type of a
9015 member may change from a generic string into a specific enum or from
9016 one specific type into an alternate that includes the original type
9017 alongside something else.
9018 Returns
9020 array of SchemaInfo, where each element describes an entity in the ABI:
9021 command, event, type, ...
9022 The order of the various SchemaInfo is unspecified; however, all names
9024 are guaranteed to be unique (no name will be duplicated with different
9025 meta-types).
9026 Note
9028 the QAPI schema is also used to help define internal interfaces, by
9029 defining QAPI types. These are not part of the QMP wire ABI, and
9030 therefore not returned by this command.
9031 Since
9033 2.5
9034 SchemaMetaType (Enum)
9036 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
9037 Values
9039 builtin
9040 a predefined type such as 'int' or 'bool'.
9041 enum an enumeration type
9043 array an array type
9045 object an object type (struct or union)
9047 alternate
9049 an alternate type
9050 command
9052 a QMP command
9053 event a QMP event
9055 Since
9057 2.5
9058 SchemaInfo (Object)
9060 Members
9061 name: string
9062 the entity's name, inherited from base. The SchemaInfo is al‐
9063 ways referenced by this name. Commands and events have the name
9064 defined in the QAPI schema. Unlike command and event names,
9065 type names are not part of the wire ABI. Consequently, type
9066 names are meaningless strings here, although they are still
9067 guaranteed unique regardless of meta-type.
9068 meta-type: SchemaMetaType
9070 the entity's meta type, inherited from base.
9071 features: array of string (optional)
9073 names of features associated with the entity, in no particular
9074 order. (since 4.1 for object types, 4.2 for commands, 5.0 for
9075 the rest)
9076 The members of SchemaInfoBuiltin when meta-type is "builtin"
9078 The members of SchemaInfoEnum when meta-type is "enum"
9080 The members of SchemaInfoArray when meta-type is "array"
9082 The members of SchemaInfoObject when meta-type is "object"
9084 The members of SchemaInfoAlternate when meta-type is "alternate"
9086 The members of SchemaInfoCommand when meta-type is "command"
9088 The members of SchemaInfoEvent when meta-type is "event"
9090 Additional members depend on the value of meta-type.
9091 Since
9093 2.5
9094 SchemaInfoBuiltin (Object)
9096 Additional SchemaInfo members for meta-type 'builtin'.
9097 Members
9099 json-type: JSONType
9100 the JSON type used for this type on the wire.
9101 Since
9103 2.5
9104 JSONType (Enum)
9106 The four primitive and two structured types according to RFC 8259 sec‐
9107 tion 1, plus 'int' (split off 'number'), plus the obvious top type
9108 'value'.
9109 Values
9111 string Not documented
9112 number Not documented
9114 int Not documented
9116 boolean
9118 Not documented
9119 null Not documented
9121 object Not documented
9123 array Not documented
9125 value Not documented
9127 Since
9129 2.5
9130 SchemaInfoEnum (Object)
9132 Additional SchemaInfo members for meta-type 'enum'.
9133 Members
9135 members: array of SchemaInfoEnumMember
9136 the enum type's members, in no particular order (since 6.2).
9137 values: array of string
9139 the enumeration type's member names, in no particular order.
9140 Redundant with members. Just for backward compatibility.
9141 Features
9143 deprecated
9144 Member values is deprecated. Use members instead.
9145 Values of this type are JSON string on the wire.
9146 Since
9148 2.5
9149 SchemaInfoEnumMember (Object)
9151 An object member.
9152 Members
9154 name: string
9155 the member's name, as defined in the QAPI schema.
9156 features: array of string (optional)
9158 names of features associated with the member, in no particular
9159 order.
9160 Since
9162 6.2
9163 SchemaInfoArray (Object)
9165 Additional SchemaInfo members for meta-type 'array'.
9166 Members
9168 element-type: string
9169 the array type's element type.
9170 Values of this type are JSON array on the wire.
9171 Since
9173 2.5
9174 SchemaInfoObject (Object)
9176 Additional SchemaInfo members for meta-type 'object'.
9177 Members
9179 members: array of SchemaInfoObjectMember
9180 the object type's (non-variant) members, in no particular order.
9181 tag: string (optional)
9183 the name of the member serving as type tag. An element of mem‐
9184 bers with this name must exist.
9185 variants: array of SchemaInfoObjectVariant (optional)
9187 variant members, i.e. additional members that depend on the type
9188 tag's value. Present exactly when tag is present. The variants
9189 are in no particular order, and may even differ from the order
9190 of the values of the enum type of the tag.
9191 Values of this type are JSON object on the wire.
9192 Since
9194 2.5
9195 SchemaInfoObjectMember (Object)
9197 An object member.
9198 Members
9200 name: string
9201 the member's name, as defined in the QAPI schema.
9202 type: string
9204 the name of the member's type.
9205 default: value (optional)
9207 default when used as command parameter. If absent, the parame‐
9208 ter is mandatory. If present, the value must be null. The pa‐
9209 rameter is optional, and behavior when it's missing is not spec‐
9210 ified here. Future extension: if present and non-null, the pa‐
9211 rameter is optional, and defaults to this value.
9212 features: array of string (optional)
9214 names of features associated with the member, in no particular
9215 order. (since 5.0)
9216 Since
9218 2.5
9219 SchemaInfoObjectVariant (Object)
9221 The variant members for a value of the type tag.
9222 Members
9224 case: string
9225 a value of the type tag.
9226 type: string
9228 the name of the object type that provides the variant members
9229 when the type tag has value case.
9230 Since
9232 2.5
9233 SchemaInfoAlternate (Object)
9235 Additional SchemaInfo members for meta-type 'alternate'.
9236 Members
9238 members: array of SchemaInfoAlternateMember
9239 the alternate type's members, in no particular order. The mem‐
9240 bers' wire encoding is distinct, see docs/de‐
9241 vel/qapi-code-gen.txt section Alternate types.
9242 On the wire, this can be any of the members.
9243 Since
9245 2.5
9246 SchemaInfoAlternateMember (Object)
9248 An alternate member.
9249 Members
9251 type: string
9252 the name of the member's type.
9253 Since
9255 2.5
9256 SchemaInfoCommand (Object)
9258 Additional SchemaInfo members for meta-type 'command'.
9259 Members
9261 arg-type: string
9262 the name of the object type that provides the command's parame‐
9263 ters.
9264 ret-type: string
9266 the name of the command's result type.
9267 allow-oob: boolean (optional)
9269 whether the command allows out-of-band execution, defaults to
9270 false (Since: 2.12)
9271 TODO
9273 success-response (currently irrelevant, because it's QGA, not QMP)
9274 Since
9276 2.5
9277 SchemaInfoEvent (Object)
9279 Additional SchemaInfo members for meta-type 'event'.
9280 Members
9282 arg-type: string
9283 the name of the object type that provides the event's parame‐
9284 ters.
9285 Since
9287 2.5
9288
9290 QAuthZListPolicy (Enum)
9291 The authorization policy result
9292 Values
9294 deny deny access
9295 allow allow access
9297 Since
9299 4.0
9300 QAuthZListFormat (Enum)
9302 The authorization policy match format
9303 Values
9305 exact an exact string match
9306 glob string with ? and * shell wildcard support
9308 Since
9310 4.0
9311 QAuthZListRule (Object)
9313 A single authorization rule.
9314 Members
9316 match: string
9317 a string or glob to match against a user identity
9318 policy: QAuthZListPolicy
9320 the result to return if match evaluates to true
9321 format: QAuthZListFormat (optional)
9323 the format of the match rule (default 'exact')
9324 Since
9326 4.0
9327 AuthZListProperties (Object)
9329 Properties for authz-list objects.
9330 Members
9332 policy: QAuthZListPolicy (optional)
9333 Default policy to apply when no rule matches (default: deny)
9334 rules: array of QAuthZListRule (optional)
9336 Authorization rules based on matching user
9337 Since
9339 4.0
9340 AuthZListFileProperties (Object)
9342 Properties for authz-listfile objects.
9343 Members
9345 filename: string
9346 File name to load the configuration from. The file must contain
9347 valid JSON for AuthZListProperties.
9348 refresh: boolean (optional)
9350 If true, inotify is used to monitor the file, automatically
9351 reloading changes. If an error occurs during reloading, all au‐
9352 thorizations will fail until the file is next successfully
9353 loaded. (default: true if the binary was built with CONFIG_INO‐
9354 TIFY1, false otherwise)
9355 Since
9357 4.0
9358 AuthZPAMProperties (Object)
9360 Properties for authz-pam objects.
9361 Members
9363 service: string
9364 PAM service name to use for authorization
9365 Since
9367 4.0
9368 AuthZSimpleProperties (Object)
9370 Properties for authz-simple objects.
9371 Members
9373 identity: string
9374 Identifies the allowed user. Its format depends on the network
9375 service that authorization object is associated with. For autho‐
9376 rizing based on TLS x509 certificates, the identity must be the
9377 x509 distinguished name.
9378 Since
9380 4.0
9381
9383 ObjectPropertyInfo (Object)
9384 Members
9385 name: string
9386 the name of the property
9387 type: string
9389 the type of the property. This will typically come in one of
9390 four forms:
9391 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
9393 ble'. These types are mapped to the appropriate JSON type.
9394 2. A child type in the form 'child<subtype>' where subtype is a
9396 qdev device type name. Child properties create the composi‐
9397 tion tree.
9398 3. A link type in the form 'link<subtype>' where subtype is a
9400 qdev device type name. Link properties form the device model
9401 graph.
9402 description: string (optional)
9404 if specified, the description of the property.
9405 default-value: value (optional)
9407 the default value, if any (since 5.0)
9408 Since
9410 1.2
9411 qom-list (Command)
9413 This command will list any properties of a object given a path in the
9414 object model.
9415 Arguments
9417 path: string
9418 the path within the object model. See qom-get for a description
9419 of this parameter.
9420 Returns
9422 a list of ObjectPropertyInfo that describe the properties of the ob‐
9423 ject.
9424 Since
9426 1.2
9427 Example
9429 -> { "execute": "qom-list",
9430 "arguments": { "path": "/chardevs" } }
9431 <- { "return": [ { "name": "type", "type": "string" },
9432 { "name": "parallel0", "type": "child<chardev-vc>" },
9433 { "name": "serial0", "type": "child<chardev-vc>" },
9434 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
9435 qom-get (Command)
9437 This command will get a property from a object model path and return
9438 the value.
9439 Arguments
9441 path: string
9442 The path within the object model. There are two forms of sup‐
9443 ported paths--absolute and partial paths.
9444 Absolute paths are derived from the root object and can follow
9446 child<> or link<> properties. Since they can follow link<>
9447 properties, they can be arbitrarily long. Absolute paths look
9448 like absolute filenames and are prefixed with a leading slash.
9449 Partial paths look like relative filenames. They do not begin
9451 with a prefix. The matching rules for partial paths are subtle
9452 but designed to make specifying objects easy. At each level of
9453 the composition tree, the partial path is matched as an absolute
9454 path. The first match is not returned. At least two matches
9455 are searched for. A successful result is only returned if only
9456 one match is found. If more than one match is found, a flag is
9457 return to indicate that the match was ambiguous.
9458 property: string
9460 The property name to read
9461 Returns
9463 The property value. The type depends on the property type. child<> and
9464 link<> properties are returned as #str pathnames. All integer property
9465 types (u8, u16, etc) are returned as #int.
9466 Since
9468 1.2
9469 Example
9471 1. Use absolute path
9472 -> { "execute": "qom-get",
9474 "arguments": { "path": "/machine/unattached/device[0]",
9475 "property": "hotplugged" } }
9476 <- { "return": false }
9477 2. Use partial path
9479 -> { "execute": "qom-get",
9481 "arguments": { "path": "unattached/sysbus",
9482 "property": "type" } }
9483 <- { "return": "System" }
9484 qom-set (Command)
9486 This command will set a property from a object model path.
9487 Arguments
9489 path: string
9490 see qom-get for a description of this parameter
9491 property: string
9493 the property name to set
9494 value: value
9496 a value who's type is appropriate for the property type. See
9497 qom-get for a description of type mapping.
9498 Since
9500 1.2
9501 Example
9503 -> { "execute": "qom-set",
9504 "arguments": { "path": "/machine",
9505 "property": "graphics",
9506 "value": false } }
9507 <- { "return": {} }
9508 ObjectTypeInfo (Object)
9510 This structure describes a search result from qom-list-types
9511 Members
9513 name: string
9514 the type name found in the search
9515 abstract: boolean (optional)
9517 the type is abstract and can't be directly instantiated. Omit‐
9518 ted if false. (since 2.10)
9519 parent: string (optional)
9521 Name of parent type, if any (since 2.10)
9522 Since
9524 1.1
9525 qom-list-types (Command)
9527 This command will return a list of types given search parameters
9528 Arguments
9530 implements: string (optional)
9531 if specified, only return types that implement this type name
9532 abstract: boolean (optional)
9534 if true, include abstract types in the results
9535 Returns
9537 a list of ObjectTypeInfo or an empty list if no results are found
9538 Since
9540 1.1
9541 qom-list-properties (Command)
9543 List properties associated with a QOM object.
9544 Arguments
9546 typename: string
9547 the type name of an object
9548 Note
9550 objects can create properties at runtime, for example to describe links
9551 between different devices and/or objects. These properties are not in‐
9552 cluded in the output of this command.
9553 Returns
9555 a list of ObjectPropertyInfo describing object properties
9556 Since
9558 2.12
9559 CanHostSocketcanProperties (Object)
9561 Properties for can-host-socketcan objects.
9562 Members
9564 if: string
9565 interface name of the host system CAN bus to connect to
9566 canbus: string
9568 object ID of the can-bus object to connect to the host interface
9569 Since
9571 2.12
9572 ColoCompareProperties (Object)
9574 Properties for colo-compare objects.
9575 Members
9577 primary_in: string
9578 name of the character device backend to use for the primary in‐
9579 put (incoming packets are redirected to outdev)
9580 secondary_in: string
9582 name of the character device backend to use for secondary input
9583 (incoming packets are only compared to the input on primary_in
9584 and then dropped)
9585 outdev: string
9587 name of the character device backend to use for output
9588 iothread: string
9590 name of the iothread to run in
9591 notify_dev: string (optional)
9593 name of the character device backend to be used to communicate
9594 with the remote colo-frame (only for Xen COLO)
9595 compare_timeout: int (optional)
9597 the maximum time to hold a packet from primary_in for comparison
9598 with an incoming packet on secondary_in in milliseconds (de‐
9599 fault: 3000)
9600 expired_scan_cycle: int (optional)
9602 the interval at which colo-compare checks whether packets from
9603 primary have timed out, in milliseconds (default: 3000)
9604 max_queue_size: int (optional)
9606 the maximum number of packets to keep in the queue for comparing
9607 with incoming packets from secondary_in. If the queue is full
9608 and additional packets are received, the additional packets are
9609 dropped. (default: 1024)
9610 vnet_hdr_support: boolean (optional)
9612 if true, vnet header support is enabled (default: false)
9613 Since
9615 2.8
9616 CryptodevBackendProperties (Object)
9618 Properties for cryptodev-backend and cryptodev-backend-builtin objects.
9619 Members
9621 queues: int (optional)
9622 the number of queues for the cryptodev backend. Ignored for
9623 cryptodev-backend and must be 1 for cryptodev-backend-builtin.
9624 (default: 1)
9625 Since
9627 2.8
9628 CryptodevVhostUserProperties (Object)
9630 Properties for cryptodev-vhost-user objects.
9631 Members
9633 chardev: string
9634 the name of a Unix domain socket character device that connects
9635 to the vhost-user server
9636 The members of CryptodevBackendProperties
9638 Since
9640 2.12
9641 DBusVMStateProperties (Object)
9643 Properties for dbus-vmstate objects.
9644 Members
9646 addr: string
9647 the name of the DBus bus to connect to
9648 id-list: string (optional)
9650 a comma separated list of DBus IDs of helpers whose data should
9651 be included in the VM state on migration
9652 Since
9654 5.0
9655 NetfilterInsert (Enum)
9657 Indicates where to insert a netfilter relative to a given other filter.
9658 Values
9660 before insert before the specified filter
9661 behind insert behind the specified filter
9663 Since
9665 5.0
9666 NetfilterProperties (Object)
9668 Properties for objects of classes derived from netfilter.
9669 Members
9671 netdev: string
9672 id of the network device backend to filter
9673 queue: NetFilterDirection (optional)
9675 indicates which queue(s) to filter (default: all)
9676 status: string (optional)
9678 indicates whether the filter is enabled ("on") or disabled
9679 ("off") (default: "on")
9680 position: string (optional)
9682 specifies where the filter should be inserted in the filter
9683 list. "head" means the filter is inserted at the head of the
9684 filter list, before any existing filters. "tail" means the fil‐
9685 ter is inserted at the tail of the filter list, behind any ex‐
9686 isting filters (default). "id=<id>" means the filter is in‐
9687 serted before or behind the filter specified by <id>, depending
9688 on the insert property. (default: "tail")
9689 insert: NetfilterInsert (optional)
9691 where to insert the filter relative to the filter given in posi‐
9692 tion. Ignored if position is "head" or "tail". (default: be‐
9693 hind)
9694 Since
9696 2.5
9697 FilterBufferProperties (Object)
9699 Properties for filter-buffer objects.
9700 Members
9702 interval: int
9703 a non-zero interval in microseconds. All packets arriving in
9704 the given interval are delayed until the end of the interval.
9705 The members of NetfilterProperties
9707 Since
9709 2.5
9710 FilterDumpProperties (Object)
9712 Properties for filter-dump objects.
9713 Members
9715 file: string
9716 the filename where the dumped packets should be stored
9717 maxlen: int (optional)
9719 maximum number of bytes in a packet that are stored (default:
9720 65536)
9721 The members of NetfilterProperties
9723 Since
9725 2.5
9726 FilterMirrorProperties (Object)
9728 Properties for filter-mirror objects.
9729 Members
9731 outdev: string
9732 the name of a character device backend to which all incoming
9733 packets are mirrored
9734 vnet_hdr_support: boolean (optional)
9736 if true, vnet header support is enabled (default: false)
9737 The members of NetfilterProperties
9739 Since
9741 2.6
9742 FilterRedirectorProperties (Object)
9744 Properties for filter-redirector objects.
9745 At least one of indev or outdev must be present. If both are present,
9747 they must not refer to the same character device backend.
9748 Members
9750 indev: string (optional)
9751 the name of a character device backend from which packets are
9752 received and redirected to the filtered network device
9753 outdev: string (optional)
9755 the name of a character device backend to which all incoming
9756 packets are redirected
9757 vnet_hdr_support: boolean (optional)
9759 if true, vnet header support is enabled (default: false)
9760 The members of NetfilterProperties
9762 Since
9764 2.6
9765 FilterRewriterProperties (Object)
9767 Properties for filter-rewriter objects.
9768 Members
9770 vnet_hdr_support: boolean (optional)
9771 if true, vnet header support is enabled (default: false)
9772 The members of NetfilterProperties
9774 Since
9776 2.8
9777 InputBarrierProperties (Object)
9779 Properties for input-barrier objects.
9780 Members
9782 name: string
9783 the screen name as declared in the screens section of bar‐
9784 rier.conf
9785 server: string (optional)
9787 hostname of the Barrier server (default: "localhost")
9788 port: string (optional)
9790 TCP port of the Barrier server (default: "24800")
9791 x-origin: string (optional)
9793 x coordinate of the leftmost pixel on the guest screen (default:
9794 "0")
9795 y-origin: string (optional)
9797 y coordinate of the topmost pixel on the guest screen (default:
9798 "0")
9799 width: string (optional)
9801 the width of secondary screen in pixels (default: "1920")
9802 height: string (optional)
9804 the height of secondary screen in pixels (default: "1080")
9805 Since
9807 4.2
9808 InputLinuxProperties (Object)
9810 Properties for input-linux objects.
9811 Members
9813 evdev: string
9814 the path of the host evdev device to use
9815 grab_all: boolean (optional)
9817 if true, grab is toggled for all devices (e.g. both keyboard and
9818 mouse) instead of just one device (default: false)
9819 repeat: boolean (optional)
9821 enables auto-repeat events (default: false)
9822 grab-toggle: GrabToggleKeys (optional)
9824 the key or key combination that toggles device grab (default:
9825 ctrl-ctrl)
9826 Since
9828 2.6
9829 IothreadProperties (Object)
9831 Properties for iothread objects.
9832 Members
9834 poll-max-ns: int (optional)
9835 the maximum number of nanoseconds to busy wait for events. 0
9836 means polling is disabled (default: 32768 on POSIX hosts, 0 oth‐
9837 erwise)
9838 poll-grow: int (optional)
9840 the multiplier used to increase the polling time when the algo‐
9841 rithm detects it is missing events due to not polling long
9842 enough. 0 selects a default behaviour (default: 0)
9843 poll-shrink: int (optional)
9845 the divisor used to decrease the polling time when the algorithm
9846 detects it is spending too long polling without encountering
9847 events. 0 selects a default behaviour (default: 0)
9848 aio-max-batch: int (optional)
9850 maximum number of requests in a batch for the AIO engine, 0
9851 means that the engine will use its default (default:0, since
9852 6.1)
9853 Since
9855 2.0
9856 MemoryBackendProperties (Object)
9858 Properties for objects of classes derived from memory-backend.
9859 Members
9861 merge: boolean (optional)
9862 if true, mark the memory as mergeable (default depends on the
9863 machine type)
9864 dump: boolean (optional)
9866 if true, include the memory in core dumps (default depends on
9867 the machine type)
9868 host-nodes: array of int (optional)
9870 the list of NUMA host nodes to bind the memory to
9871 policy: HostMemPolicy (optional)
9873 the NUMA policy (default: 'default')
9874 prealloc: boolean (optional)
9876 if true, preallocate memory (default: false)
9877 prealloc-threads: int (optional)
9879 number of CPU threads to use for prealloc (default: 1)
9880 share: boolean (optional)
9882 if false, the memory is private to QEMU; if true, it is shared
9883 (default: false)
9884 reserve: boolean (optional)
9886 if true, reserve swap space (or huge pages) if applicable (de‐
9887 fault: true) (since 6.1)
9888 size: int
9890 size of the memory region in bytes
9891 x-use-canonical-path-for-ramblock-id: boolean (optional)
9893 if true, the canoncial path is used for ramblock-id. Disable
9894 this for 4.0 machine types or older to allow migration with
9895 newer QEMU versions. (default: false generally, but true for
9896 machine types <= 4.0)
9897 Note
9899 prealloc=true and reserve=false cannot be set at the same time. With
9900 reserve=true, the behavior depends on the operating system: for exam‐
9901 ple, Linux will not reserve swap space for shared file mappings -- "not
9902 applicable". In contrast, reserve=false will bail out if it cannot be
9903 configured accordingly.
9904 Since
9906 2.1
9907 MemoryBackendFileProperties (Object)
9909 Properties for memory-backend-file objects.
9910 Members
9912 align: int (optional)
9913 the base address alignment when QEMU mmap(2)s mem-path. Some
9914 backend stores specified by mem-path require an alignment dif‐
9915 ferent than the default one used by QEMU, e.g. the device DAX
9916 /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
9917 users can specify the required alignment via this option. 0 se‐
9918 lects a default alignment (currently the page size). (default:
9919 0)
9920 discard-data: boolean (optional)
9922 if true, the file contents can be destroyed when QEMU exits, to
9923 avoid unnecessarily flushing data to the backing file. Note that
9924 discard-data is only an optimization, and QEMU might not discard
9925 file contents if it aborts unexpectedly or is terminated using
9926 SIGKILL. (default: false)
9927 mem-path: string
9929 the path to either a shared memory or huge page filesystem mount
9930 pmem: boolean (optional) (If: CONFIG_LIBPMEM)
9932 specifies whether the backing file specified by mem-path is in
9933 host persistent memory that can be accessed using the SNIA NVM
9934 programming model (e.g. Intel NVDIMM).
9935 readonly: boolean (optional)
9937 if true, the backing file is opened read-only; if false, it is
9938 opened read-write. (default: false)
9939 The members of MemoryBackendProperties
9941 Since
9943 2.1
9944 MemoryBackendMemfdProperties (Object)
9946 Properties for memory-backend-memfd objects.
9947 The share boolean option is true by default with memfd.
9949 Members
9951 hugetlb: boolean (optional)
9952 if true, the file to be created resides in the hugetlbfs
9953 filesystem (default: false)
9954 hugetlbsize: int (optional)
9956 the hugetlb page size on systems that support multiple hugetlb
9957 page sizes (it must be a power of 2 value supported by the sys‐
9958 tem). 0 selects a default page size. This option is ignored if
9959 hugetlb is false. (default: 0)
9960 seal: boolean (optional)
9962 if true, create a sealed-file, which will block further resizing
9963 of the memory (default: true)
9964 The members of MemoryBackendProperties
9966 Since
9968 2.12
9969 MemoryBackendEpcProperties (Object)
9971 Properties for memory-backend-epc objects.
9972 The share boolean option is true by default with epc
9974 The merge boolean option is false by default with epc
9976 The dump boolean option is false by default with epc
9978 Members
9980 The members of MemoryBackendProperties
9981 Since
9983 6.2
9984 PrManagerHelperProperties (Object)
9986 Properties for pr-manager-helper objects.
9987 Members
9989 path: string
9990 the path to a Unix domain socket for connecting to the external
9991 helper
9992 Since
9994 2.11
9995 QtestProperties (Object)
9997 Properties for qtest objects.
9998 Members
10000 chardev: string
10001 the chardev to be used to receive qtest commands on.
10002 log: string (optional)
10004 the path to a log file
10005 Since
10007 6.0
10008 RemoteObjectProperties (Object)
10010 Properties for x-remote-object objects.
10011 Members
10013 fd: string
10014 file descriptor name previously passed via 'getfd' command
10015 devid: string
10017 the id of the device to be associated with the file descriptor
10018 Since
10020 6.0
10021 RngProperties (Object)
10023 Properties for objects of classes derived from rng.
10024 Members
10026 opened: boolean (optional)
10027 if true, the device is opened immediately when applying this op‐
10028 tion and will probably fail when processing the next option.
10029 Don't use; only provided for compatibility. (default: false)
10030 Features
10032 deprecated
10033 Member opened is deprecated. Setting true doesn't make sense,
10034 and false is already the default.
10035 Since
10037 1.3
10038 RngEgdProperties (Object)
10040 Properties for rng-egd objects.
10041 Members
10043 chardev: string
10044 the name of a character device backend that provides the connec‐
10045 tion to the RNG daemon
10046 The members of RngProperties
10048 Since
10050 1.3
10051 RngRandomProperties (Object)
10053 Properties for rng-random objects.
10054 Members
10056 filename: string (optional)
10057 the filename of the device on the host to obtain entropy from
10058 (default: "/dev/urandom")
10059 The members of RngProperties
10061 Since
10063 1.3
10064 SevGuestProperties (Object)
10066 Properties for sev-guest objects.
10067 Members
10069 sev-device: string (optional)
10070 SEV device to use (default: "/dev/sev")
10071 dh-cert-file: string (optional)
10073 guest owners DH certificate (encoded with base64)
10074 session-file: string (optional)
10076 guest owners session parameters (encoded with base64)
10077 policy: int (optional)
10079 SEV policy value (default: 0x1)
10080 handle: int (optional)
10082 SEV firmware handle (default: 0)
10083 cbitpos: int (optional)
10085 C-bit location in page table entry (default: 0)
10086 reduced-phys-bits: int
10088 number of bits in physical addresses that become unavailable
10089 when SEV is enabled
10090 kernel-hashes: boolean (optional)
10092 if true, add hashes of kernel/initrd/cmdline to a designated
10093 guest firmware page for measured boot with -kernel (default:
10094 false) (since 6.2)
10095 Since
10097 2.12
10098 ObjectType (Enum)
10100 Values
10101 authz-list
10102 Not documented
10103 authz-listfile
10105 Not documented
10106 authz-pam
10108 Not documented
10109 authz-simple
10111 Not documented
10112 can-bus
10114 Not documented
10115 can-host-socketcan (If: CONFIG_LINUX)
10117 Not documented
10118 colo-compare
10120 Not documented
10121 cryptodev-backend
10123 Not documented
10124 cryptodev-backend-builtin
10126 Not documented
10127 cryptodev-vhost-user (If: CONFIG_VHOST_CRYPTO)
10129 Not documented
10130 dbus-vmstate
10132 Not documented
10133 filter-buffer
10135 Not documented
10136 filter-dump
10138 Not documented
10139 filter-mirror
10141 Not documented
10142 filter-redirector
10144 Not documented
10145 filter-replay
10147 Not documented
10148 filter-rewriter
10150 Not documented
10151 input-barrier
10153 Not documented
10154 input-linux (If: CONFIG_LINUX)
10156 Not documented
10157 iothread
10159 Not documented
10160 memory-backend-epc (If: CONFIG_LINUX)
10162 Not documented
10163 memory-backend-file
10165 Not documented
10166 memory-backend-memfd (If: CONFIG_LINUX)
10168 Not documented
10169 memory-backend-ram
10171 Not documented
10172 pef-guest
10174 Not documented
10175 pr-manager-helper (If: CONFIG_LINUX)
10177 Not documented
10178 qtest Not documented
10180 rng-builtin
10182 Not documented
10183 rng-egd
10185 Not documented
10186 rng-random (If: CONFIG_POSIX)
10188 Not documented
10189 secret Not documented
10191 secret_keyring (If: CONFIG_SECRET_KEYRING)
10193 Not documented
10194 sev-guest
10196 Not documented
10197 s390-pv-guest
10199 Not documented
10200 throttle-group
10202 Not documented
10203 tls-creds-anon
10205 Not documented
10206 tls-creds-psk
10208 Not documented
10209 tls-creds-x509
10211 Not documented
10212 tls-cipher-suites
10214 Not documented
10215 x-remote-object
10217 Not documented
10218 Features
10220 unstable
10221 Member x-remote-object is experimental.
10222 Since
10224 6.0
10225 ObjectOptions (Object)
10227 Describes the options of a user creatable QOM object.
10228 Members
10230 qom-type: ObjectType
10231 the class name for the object to be created
10232 id: string
10234 the name of the new object
10235 The members of AuthZListProperties when qom-type is "authz-list"
10237 The members of AuthZListFileProperties when qom-type is "authz-list‐
10239 file"
10240 The members of AuthZPAMProperties when qom-type is "authz-pam"
10242 The members of AuthZSimpleProperties when qom-type is "authz-simple"
10244 The members of CanHostSocketcanProperties when qom-type is
10246 "can-host-socketcan" (If: CONFIG_LINUX)
10247 The members of ColoCompareProperties when qom-type is "colo-compare"
10249 The members of CryptodevBackendProperties when qom-type is "cryp‐
10251 todev-backend"
10252 The members of CryptodevBackendProperties when qom-type is "cryp‐
10254 todev-backend-builtin"
10255 The members of CryptodevVhostUserProperties when qom-type is "cryp‐
10257 todev-vhost-user" (If: CONFIG_VHOST_CRYPTO)
10258 The members of DBusVMStateProperties when qom-type is "dbus-vmstate"
10260 The members of FilterBufferProperties when qom-type is "filter-buffer"
10262 The members of FilterDumpProperties when qom-type is "filter-dump"
10264 The members of FilterMirrorProperties when qom-type is "filter-mirror"
10266 The members of FilterRedirectorProperties when qom-type is "fil‐
10268 ter-redirector"
10269 The members of NetfilterProperties when qom-type is "filter-replay"
10271 The members of FilterRewriterProperties when qom-type is "fil‐
10273 ter-rewriter"
10274 The members of InputBarrierProperties when qom-type is "input-barrier"
10276 The members of InputLinuxProperties when qom-type is "input-linux" (If:
10278 CONFIG_LINUX)
10279 The members of IothreadProperties when qom-type is "iothread"
10281 The members of MemoryBackendEpcProperties when qom-type is "mem‐
10283 ory-backend-epc" (If: CONFIG_LINUX)
10284 The members of MemoryBackendFileProperties when qom-type is "mem‐
10286 ory-backend-file"
10287 The members of MemoryBackendMemfdProperties when qom-type is "mem‐
10289 ory-backend-memfd" (If: CONFIG_LINUX)
10290 The members of MemoryBackendProperties when qom-type is "memory-back‐
10292 end-ram"
10293 The members of PrManagerHelperProperties when qom-type is "pr-man‐
10295 ager-helper" (If: CONFIG_LINUX)
10296 The members of QtestProperties when qom-type is "qtest"
10298 The members of RngProperties when qom-type is "rng-builtin"
10300 The members of RngEgdProperties when qom-type is "rng-egd"
10302 The members of RngRandomProperties when qom-type is "rng-random" (If:
10304 CONFIG_POSIX)
10305 The members of SecretProperties when qom-type is "secret"
10307 The members of SecretKeyringProperties when qom-type is "se‐
10309 cret_keyring" (If: CONFIG_SECRET_KEYRING)
10310 The members of SevGuestProperties when qom-type is "sev-guest"
10312 The members of ThrottleGroupProperties when qom-type is "throt‐
10314 tle-group"
10315 The members of TlsCredsAnonProperties when qom-type is "tls-creds-anon"
10317 The members of TlsCredsPskProperties when qom-type is "tls-creds-psk"
10319 The members of TlsCredsX509Properties when qom-type is "tls-creds-x509"
10321 The members of TlsCredsProperties when qom-type is "tls-cipher-suites"
10323 The members of RemoteObjectProperties when qom-type is "x-remote-ob‐
10325 ject"
10326 Since
10328 6.0
10329 object-add (Command)
10331 Create a QOM object.
10332 Arguments
10334 The members of ObjectOptions
10335 Returns
10337 Nothing on success Error if qom-type is not a valid class name
10338 Since
10340 2.0
10341 Example
10343 -> { "execute": "object-add",
10344 "arguments": { "qom-type": "rng-random", "id": "rng1",
10345 "filename": "/dev/hwrng" } }
10346 <- { "return": {} }
10347 object-del (Command)
10349 Remove a QOM object.
10350 Arguments
10352 id: string
10353 the name of the QOM object to remove
10354 Returns
10356 Nothing on success Error if id is not a valid id for a QOM object
10357 Since
10359 2.0
10360 Example
10362 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
10363 <- { "return": {} }
10364
10366 Abort (Object)
10367 This action can be used to test transaction failure.
10368 Since
10370 1.6
10371 ActionCompletionMode (Enum)
10373 An enumeration of Transactional completion modes.
10374 Values
10376 individual
10377 Do not attempt to cancel any other Actions if any Actions fail
10378 after the Transaction request succeeds. All Actions that can
10379 complete successfully will do so without waiting on others.
10380 This is the default.
10381 grouped
10383 If any Action fails after the Transaction succeeds, cancel all
10384 Actions. Actions do not complete until all Actions are ready to
10385 complete. May be rejected by Actions that do not support this
10386 completion mode.
10387 Since
10389 2.5
10390 TransactionActionKind (Enum)
10392 Values
10393 abort Since 1.6
10394 block-dirty-bitmap-add
10396 Since 2.5
10397 block-dirty-bitmap-remove
10399 Since 4.2
10400 block-dirty-bitmap-clear
10402 Since 2.5
10403 block-dirty-bitmap-enable
10405 Since 4.0
10406 block-dirty-bitmap-disable
10408 Since 4.0
10409 block-dirty-bitmap-merge
10411 Since 4.0
10412 blockdev-backup
10414 Since 2.3
10415 blockdev-snapshot
10417 Since 2.5
10418 blockdev-snapshot-internal-sync
10420 Since 1.7
10421 blockdev-snapshot-sync
10423 since 1.1
10424 drive-backup
10426 Since 1.6
10427 Features
10429 deprecated
10430 Member drive-backup is deprecated. Use member blockdev-backup
10431 instead.
10432 Since
10434 1.1
10435 AbortWrapper (Object)
10437 Members
10438 data: Abort
10439 Not documented
10440 Since
10442 1.6
10443 BlockDirtyBitmapAddWrapper (Object)
10445 Members
10446 data: BlockDirtyBitmapAdd
10447 Not documented
10448 Since
10450 2.5
10451 BlockDirtyBitmapWrapper (Object)
10453 Members
10454 data: BlockDirtyBitmap
10455 Not documented
10456 Since
10458 2.5
10459 BlockDirtyBitmapMergeWrapper (Object)
10461 Members
10462 data: BlockDirtyBitmapMerge
10463 Not documented
10464 Since
10466 4.0
10467 BlockdevBackupWrapper (Object)
10469 Members
10470 data: BlockdevBackup
10471 Not documented
10472 Since
10474 2.3
10475 BlockdevSnapshotWrapper (Object)
10477 Members
10478 data: BlockdevSnapshot
10479 Not documented
10480 Since
10482 2.5
10483 BlockdevSnapshotInternalWrapper (Object)
10485 Members
10486 data: BlockdevSnapshotInternal
10487 Not documented
10488 Since
10490 1.7
10491 BlockdevSnapshotSyncWrapper (Object)
10493 Members
10494 data: BlockdevSnapshotSync
10495 Not documented
10496 Since
10498 1.1
10499 DriveBackupWrapper (Object)
10501 Members
10502 data: DriveBackup
10503 Not documented
10504 Since
10506 1.6
10507 TransactionAction (Object)
10509 A discriminated record of operations that can be performed with trans‐
10510 action.
10511 Members
10513 type: TransactionActionKind
10514 Not documented
10515 The members of AbortWrapper when type is "abort"
10517 The members of BlockDirtyBitmapAddWrapper when type is
10519 "block-dirty-bitmap-add"
10520 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10522 map-remove"
10523 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10525 map-clear"
10526 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10528 map-enable"
10529 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10531 map-disable"
10532 The members of BlockDirtyBitmapMergeWrapper when type is
10534 "block-dirty-bitmap-merge"
10535 The members of BlockdevBackupWrapper when type is "blockdev-backup"
10537 The members of BlockdevSnapshotWrapper when type is "blockdev-snapshot"
10539 The members of BlockdevSnapshotInternalWrapper when type is "block‐
10541 dev-snapshot-internal-sync"
10542 The members of BlockdevSnapshotSyncWrapper when type is "blockdev-snap‐
10544 shot-sync"
10545 The members of DriveBackupWrapper when type is "drive-backup"
10547 Since
10549 1.1
10550 TransactionProperties (Object)
10552 Optional arguments to modify the behavior of a Transaction.
10553 Members
10555 completion-mode: ActionCompletionMode (optional)
10556 Controls how jobs launched asynchronously by Actions will com‐
10557 plete or fail as a group. See ActionCompletionMode for details.
10558 Since
10560 2.5
10561 transaction (Command)
10563 Executes a number of transactionable QMP commands atomically. If any
10564 operation fails, then the entire set of actions will be abandoned and
10565 the appropriate error returned.
10566 For external snapshots, the dictionary contains the device, the file to
10568 use for the new snapshot, and the format. The default format, if not
10569 specified, is qcow2.
10570 Each new snapshot defaults to being created by QEMU (wiping any con‐
10572 tents if the file already exists), but it is also possible to reuse an
10573 externally-created file. In the latter case, you should ensure that
10574 the new image file has the same contents as the current one; QEMU can‐
10575 not perform any meaningful check. Typically this is achieved by using
10576 the current image file as the backing file for the new image.
10577 On failure, the original disks pre-snapshot attempt will be used.
10579 For internal snapshots, the dictionary contains the device and the
10581 snapshot's name. If an internal snapshot matching name already exists,
10582 the request will be rejected. Only some image formats support it, for
10583 example, qcow2, and rbd,
10584 On failure, qemu will try delete the newly created internal snapshot in
10586 the transaction. When an I/O error occurs during deletion, the user
10587 needs to fix it later with qemu-img or other command.
10588 Arguments
10590 actions: array of TransactionAction
10591 List of TransactionAction; information needed for the respective
10592 operations.
10593 properties: TransactionProperties (optional)
10595 structure of additional options to control the execution of the
10596 transaction. See TransactionProperties for additional detail.
10597 Returns
10599 nothing on success
10600 Errors depend on the operations of the transaction
10602 Note
10604 The transaction aborts on the first failure. Therefore, there will be
10605 information on only one failed operation returned in an error condi‐
10606 tion, and subsequent actions will not have been attempted.
10607 Since
10609 1.1
10610 Example
10612 -> { "execute": "transaction",
10613 "arguments": { "actions": [
10614 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
10615 "snapshot-file": "/some/place/my-image",
10616 "format": "qcow2" } },
10617 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
10618 "snapshot-file": "/some/place/my-image2",
10619 "snapshot-node-name": "node3432",
10620 "mode": "existing",
10621 "format": "qcow2" } },
10622 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
10623 "snapshot-file": "/some/place/my-image2",
10624 "mode": "existing",
10625 "format": "qcow2" } },
10626 { "type": "blockdev-snapshot-internal-sync", "data" : {
10627 "device": "ide-hd2",
10628 "name": "snapshot0" } } ] } }
10629 <- { "return": {} }
10630
10632 2023, The QEMU Project Developers
106337.0.0 Jan 19, 2023 QEMU-STORAGE-DAEMON-QMP-REF(7)