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 • ChardevVC (Object)
568 • ChardevRingbuf (Object)
570 • ChardevQemuVDAgent (Object)
572 • ChardevBackendKind (Enum)
574 • ChardevFileWrapper (Object)
576 • ChardevHostdevWrapper (Object)
578 • ChardevSocketWrapper (Object)
580 • ChardevUdpWrapper (Object)
582 • ChardevCommonWrapper (Object)
584 • ChardevMuxWrapper (Object)
586 • ChardevStdioWrapper (Object)
588 • ChardevSpiceChannelWrapper (Object)
590 • ChardevSpicePortWrapper (Object)
592 • ChardevQemuVDAgentWrapper (Object)
594 • ChardevVCWrapper (Object)
596 • ChardevRingbufWrapper (Object)
598 • ChardevBackend (Object)
600 • ChardevReturn (Object)
602 • chardev-add (Command)
604 • chardev-change (Command)
606 • chardev-remove (Command)
608 • chardev-send-break (Command)
610 • VSERPORT_CHANGE (Event)
612 • QMP monitor control
614 • qmp_capabilities (Command)
616 • QMPCapability (Enum)
618 • VersionTriple (Object)
620 • VersionInfo (Object)
622 • query-version (Command)
624 • CommandInfo (Object)
626 • query-commands (Command)
628 • quit (Command)
630 • MonitorMode (Enum)
632 • MonitorOptions (Object)
634 • QMP introspection
636 • query-qmp-schema (Command)
638 • SchemaMetaType (Enum)
640 • SchemaInfo (Object)
642 • SchemaInfoBuiltin (Object)
644 • JSONType (Enum)
646 • SchemaInfoEnum (Object)
648 • SchemaInfoEnumMember (Object)
650 • SchemaInfoArray (Object)
652 • SchemaInfoObject (Object)
654 • SchemaInfoObjectMember (Object)
656 • SchemaInfoObjectVariant (Object)
658 • SchemaInfoAlternate (Object)
660 • SchemaInfoAlternateMember (Object)
662 • SchemaInfoCommand (Object)
664 • SchemaInfoEvent (Object)
666 • User authorization
668 • QAuthZListPolicy (Enum)
670 • QAuthZListFormat (Enum)
672 • QAuthZListRule (Object)
674 • AuthZListProperties (Object)
676 • AuthZListFileProperties (Object)
678 • AuthZPAMProperties (Object)
680 • AuthZSimpleProperties (Object)
682 • QEMU Object Model (QOM)
684 • ObjectPropertyInfo (Object)
686 • qom-list (Command)
688 • qom-get (Command)
690 • qom-set (Command)
692 • ObjectTypeInfo (Object)
694 • qom-list-types (Command)
696 • qom-list-properties (Command)
698 • CanHostSocketcanProperties (Object)
700 • ColoCompareProperties (Object)
702 • CryptodevBackendProperties (Object)
704 • CryptodevVhostUserProperties (Object)
706 • DBusVMStateProperties (Object)
708 • NetfilterInsert (Enum)
710 • NetfilterProperties (Object)
712 • FilterBufferProperties (Object)
714 • FilterDumpProperties (Object)
716 • FilterMirrorProperties (Object)
718 • FilterRedirectorProperties (Object)
720 • FilterRewriterProperties (Object)
722 • InputBarrierProperties (Object)
724 • InputLinuxProperties (Object)
726 • IothreadProperties (Object)
728 • MemoryBackendProperties (Object)
730 • MemoryBackendFileProperties (Object)
732 • MemoryBackendMemfdProperties (Object)
734 • MemoryBackendEpcProperties (Object)
736 • PrManagerHelperProperties (Object)
738 • QtestProperties (Object)
740 • RemoteObjectProperties (Object)
742 • RngProperties (Object)
744 • RngEgdProperties (Object)
746 • RngRandomProperties (Object)
748 • SevGuestProperties (Object)
750 • ObjectType (Enum)
752 • ObjectOptions (Object)
754 • object-add (Command)
756 • object-del (Command)
758 • Transactions
760 • Abort (Object)
762 • ActionCompletionMode (Enum)
764 • TransactionActionKind (Enum)
766 • AbortWrapper (Object)
768 • BlockDirtyBitmapAddWrapper (Object)
770 • BlockDirtyBitmapWrapper (Object)
772 • BlockDirtyBitmapMergeWrapper (Object)
774 • BlockdevBackupWrapper (Object)
776 • BlockdevSnapshotWrapper (Object)
778 • BlockdevSnapshotInternalWrapper (Object)
780 • BlockdevSnapshotSyncWrapper (Object)
782 • DriveBackupWrapper (Object)
784 • TransactionAction (Object)
786 • TransactionProperties (Object)
788 • transaction (Command)
790
792 Block core (VM unrelated)
794 IoOperationType (Enum)
795 An enumeration of the I/O operation types
796 Values
798 read read operation
799 write write operation
801 Since
803 2.1
804 OnOffAuto (Enum)
806 An enumeration of three options: on, off, and auto
807 Values
809 auto QEMU selects the value between on and off
810 on Enabled
812 off Disabled
814 Since
816 2.2
817 OnOffSplit (Enum)
819 An enumeration of three values: on, off, and split
820 Values
822 on Enabled
823 off Disabled
825 split Mixed
827 Since
829 2.6
830 String (Object)
832 A fat type wrapping 'str', to be embedded in lists.
833 Members
835 str: string
836 Not documented
837 Since
839 1.2
840 StrOrNull (Alternate)
842 This is a string value or the explicit lack of a string (null pointer
843 in C). Intended for cases when 'optional absent' already has a differ‐
844 ent meaning.
845 Members
847 s: string
848 the string value
849 n: null
851 no string value
852 Since
854 2.10
855 OffAutoPCIBAR (Enum)
857 An enumeration of options for specifying a PCI BAR
858 Values
860 off The specified feature is disabled
861 auto The PCI BAR for the feature is automatically selected
863 bar0 PCI BAR0 is used for the feature
865 bar1 PCI BAR1 is used for the feature
867 bar2 PCI BAR2 is used for the feature
869 bar3 PCI BAR3 is used for the feature
871 bar4 PCI BAR4 is used for the feature
873 bar5 PCI BAR5 is used for the feature
875 Since
877 2.12
878 PCIELinkSpeed (Enum)
880 An enumeration of PCIe link speeds in units of GT/s
881 Values
883 2_5 2.5GT/s
884 5 5.0GT/s
886 8 8.0GT/s
888 16 16.0GT/s
890 Since
892 4.0
893 PCIELinkWidth (Enum)
895 An enumeration of PCIe link width
896 Values
898 1 x1
899 2 x2
901 4 x4
903 8 x8
905 12 x12
907 16 x16
909 32 x32
911 Since
913 4.0
914 HostMemPolicy (Enum)
916 Host memory policy types
917 Values
919 default
920 restore default policy, remove any nondefault policy
921 preferred
923 set the preferred host nodes for allocation
924 bind a strict policy that restricts memory allocation to the host
926 nodes specified
927 interleave
929 memory allocations are interleaved across the set of host nodes
930 specified
931 Since
933 2.1
934 NetFilterDirection (Enum)
936 Indicates whether a netfilter is attached to a netdev's transmit queue
937 or receive queue or both.
938 Values
940 all the filter is attached both to the receive and the transmit
941 queue of the netdev (default).
942 rx the filter is attached to the receive queue of the netdev, where
944 it will receive packets sent to the netdev.
945 tx the filter is attached to the transmit queue of the netdev,
947 where it will receive packets sent by the netdev.
948 Since
950 2.5
951 GrabToggleKeys (Enum)
953 Keys to toggle input-linux between host and guest.
954 Values
956 ctrl-ctrl
957 Not documented
958 alt-alt
960 Not documented
961 shift-shift
963 Not documented
964 meta-meta
966 Not documented
967 scrolllock
969 Not documented
970 ctrl-scrolllock
972 Not documented
973 Since
975 4.0
976 HumanReadableText (Object)
978 Members
979 human-readable-text: string
980 Formatted output intended for humans.
981 Since
983 6.2
984
986 QCryptoTLSCredsEndpoint (Enum)
987 The type of network endpoint that will be using the credentials. Most
988 types of credential require different setup / structures depending on
989 whether they will be used in a server versus a client.
990 Values
992 client the network endpoint is acting as the client
993 server the network endpoint is acting as the server
995 Since
997 2.5
998 QCryptoSecretFormat (Enum)
1000 The data format that the secret is provided in
1001 Values
1003 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
1004 be used
1005 base64 arbitrary base64 encoded binary data
1007 Since
1009 2.6
1010 QCryptoHashAlgorithm (Enum)
1012 The supported algorithms for computing content digests
1013 Values
1015 md5 MD5. Should not be used in any new code, legacy compat only
1016 sha1 SHA-1. Should not be used in any new code, legacy compat only
1018 sha224 SHA-224. (since 2.7)
1020 sha256 SHA-256. Current recommended strong hash.
1022 sha384 SHA-384. (since 2.7)
1024 sha512 SHA-512. (since 2.7)
1026 ripemd160
1028 RIPEMD-160. (since 2.7)
1029 Since
1031 2.6
1032 QCryptoCipherAlgorithm (Enum)
1034 The supported algorithms for content encryption ciphers
1035 Values
1037 aes-128
1038 AES with 128 bit / 16 byte keys
1039 aes-192
1041 AES with 192 bit / 24 byte keys
1042 aes-256
1044 AES with 256 bit / 32 byte keys
1045 des DES with 56 bit / 8 byte keys. Do not use except in VNC. (since
1047 6.1)
1048 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
1050 cast5-128
1052 Cast5 with 128 bit / 16 byte keys
1053 serpent-128
1055 Serpent with 128 bit / 16 byte keys
1056 serpent-192
1058 Serpent with 192 bit / 24 byte keys
1059 serpent-256
1061 Serpent with 256 bit / 32 byte keys
1062 twofish-128
1064 Twofish with 128 bit / 16 byte keys
1065 twofish-192
1067 Twofish with 192 bit / 24 byte keys
1068 twofish-256
1070 Twofish with 256 bit / 32 byte keys
1071 Since
1073 2.6
1074 QCryptoCipherMode (Enum)
1076 The supported modes for content encryption ciphers
1077 Values
1079 ecb Electronic Code Book
1080 cbc Cipher Block Chaining
1082 xts XEX with tweaked code book and ciphertext stealing
1084 ctr Counter (Since 2.8)
1086 Since
1088 2.6
1089 QCryptoIVGenAlgorithm (Enum)
1091 The supported algorithms for generating initialization vectors for full
1092 disk encryption. The 'plain' generator should not be used for disks
1093 with sector numbers larger than 2^32, except where compatibility with
1094 pre-existing Linux dm-crypt volumes is required.
1095 Values
1097 plain 64-bit sector number truncated to 32-bits
1098 plain64
1100 64-bit sector number
1101 essiv 64-bit sector number encrypted with a hash of the encryption key
1103 Since
1105 2.6
1106 QCryptoBlockFormat (Enum)
1108 The supported full disk encryption formats
1109 Values
1111 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
1112 data from old images.
1113 luks LUKS encryption format. Recommended for new images
1115 Since
1117 2.6
1118 QCryptoBlockOptionsBase (Object)
1120 The common options that apply to all full disk encryption formats
1121 Members
1123 format: QCryptoBlockFormat
1124 the encryption format
1125 Since
1127 2.6
1128 QCryptoBlockOptionsQCow (Object)
1130 The options that apply to QCow/QCow2 AES-CBC encryption format
1131 Members
1133 key-secret: string (optional)
1134 the ID of a QCryptoSecret object providing the decryption key.
1135 Mandatory except when probing image for metadata only.
1136 Since
1138 2.6
1139 QCryptoBlockOptionsLUKS (Object)
1141 The options that apply to LUKS encryption format
1142 Members
1144 key-secret: string (optional)
1145 the ID of a QCryptoSecret object providing the decryption key.
1146 Mandatory except when probing image for metadata only.
1147 Since
1149 2.6
1150 QCryptoBlockCreateOptionsLUKS (Object)
1152 The options that apply to LUKS encryption format initialization
1153 Members
1155 cipher-alg: QCryptoCipherAlgorithm (optional)
1156 the cipher algorithm for data encryption Currently defaults to
1157 'aes-256'.
1158 cipher-mode: QCryptoCipherMode (optional)
1160 the cipher mode for data encryption Currently defaults to 'xts'
1161 ivgen-alg: QCryptoIVGenAlgorithm (optional)
1163 the initialization vector generator Currently defaults to
1164 'plain64'
1165 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1167 the initialization vector generator hash Currently defaults to
1168 'sha256'
1169 hash-alg: QCryptoHashAlgorithm (optional)
1171 the master key hash algorithm Currently defaults to 'sha256'
1172 iter-time: int (optional)
1174 number of milliseconds to spend in PBKDF passphrase processing.
1175 Currently defaults to 2000. (since 2.8)
1176 The members of QCryptoBlockOptionsLUKS
1178 Since
1180 2.6
1181 QCryptoBlockOpenOptions (Object)
1183 The options that are available for all encryption formats when opening
1184 an existing volume
1185 Members
1187 The members of QCryptoBlockOptionsBase
1188 The members of QCryptoBlockOptionsQCow when format is "qcow"
1190 The members of QCryptoBlockOptionsLUKS when format is "luks"
1192 Since
1194 2.6
1195 QCryptoBlockCreateOptions (Object)
1197 The options that are available for all encryption formats when initial‐
1198 izing a new volume
1199 Members
1201 The members of QCryptoBlockOptionsBase
1202 The members of QCryptoBlockOptionsQCow when format is "qcow"
1204 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
1206 Since
1208 2.6
1209 QCryptoBlockInfoBase (Object)
1211 The common information that applies to all full disk encryption formats
1212 Members
1214 format: QCryptoBlockFormat
1215 the encryption format
1216 Since
1218 2.7
1219 QCryptoBlockInfoLUKSSlot (Object)
1221 Information about the LUKS block encryption key slot options
1222 Members
1224 active: boolean
1225 whether the key slot is currently in use
1226 key-offset: int
1228 offset to the key material in bytes
1229 iters: int (optional)
1231 number of PBKDF2 iterations for key material
1232 stripes: int (optional)
1234 number of stripes for splitting key material
1235 Since
1237 2.7
1238 QCryptoBlockInfoLUKS (Object)
1240 Information about the LUKS block encryption options
1241 Members
1243 cipher-alg: QCryptoCipherAlgorithm
1244 the cipher algorithm for data encryption
1245 cipher-mode: QCryptoCipherMode
1247 the cipher mode for data encryption
1248 ivgen-alg: QCryptoIVGenAlgorithm
1250 the initialization vector generator
1251 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1253 the initialization vector generator hash
1254 hash-alg: QCryptoHashAlgorithm
1256 the master key hash algorithm
1257 payload-offset: int
1259 offset to the payload data in bytes
1260 master-key-iters: int
1262 number of PBKDF2 iterations for key material
1263 uuid: string
1265 unique identifier for the volume
1266 slots: array of QCryptoBlockInfoLUKSSlot
1268 information about each key slot
1269 Since
1271 2.7
1272 QCryptoBlockInfo (Object)
1274 Information about the block encryption options
1275 Members
1277 The members of QCryptoBlockInfoBase
1278 The members of QCryptoBlockInfoLUKS when format is "luks"
1280 Since
1282 2.7
1283 QCryptoBlockLUKSKeyslotState (Enum)
1285 Defines state of keyslots that are affected by the update
1286 Values
1288 active The slots contain the given password and marked as active
1289 inactive
1291 The slots are erased (contain garbage) and marked as inactive
1292 Since
1294 5.1
1295 QCryptoBlockAmendOptionsLUKS (Object)
1297 This struct defines the update parameters that activate/de-activate set
1298 of keyslots
1299 Members
1301 state: QCryptoBlockLUKSKeyslotState
1302 the desired state of the keyslots
1303 new-secret: string (optional)
1305 The ID of a QCryptoSecret object providing the password to be
1306 written into added active keyslots
1307 old-secret: string (optional)
1309 Optional (for deactivation only) If given will deactivate all
1310 keyslots that match password located in QCryptoSecret with this
1311 ID
1312 iter-time: int (optional)
1314 Optional (for activation only) Number of milliseconds to spend
1315 in PBKDF passphrase processing for the newly activated keyslot.
1316 Currently defaults to 2000.
1317 keyslot: int (optional)
1319 Optional. ID of the keyslot to activate/deactivate. For keyslot
1320 activation, keyslot should not be active already (this is unsafe
1321 to update an active keyslot), but possible if 'force' parameter
1322 is given. If keyslot is not given, first free keyslot will be
1323 written.
1324 For keyslot deactivation, this parameter specifies the exact
1326 keyslot to deactivate
1327 secret: string (optional)
1329 Optional. The ID of a QCryptoSecret object providing the pass‐
1330 word to use to retrieve current master key. Defaults to the
1331 same secret that was used to open the image
1332 Since 5.1
1333 QCryptoBlockAmendOptions (Object)
1335 The options that are available for all encryption formats when amending
1336 encryption settings
1337 Members
1339 The members of QCryptoBlockOptionsBase
1340 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
1342 Since
1344 5.1
1345 SecretCommonProperties (Object)
1347 Properties for objects of classes derived from secret-common.
1348 Members
1350 loaded: boolean (optional)
1351 if true, the secret is loaded immediately when applying this op‐
1352 tion and will probably fail when processing the next option.
1353 Don't use; only provided for compatibility. (default: false)
1354 format: QCryptoSecretFormat (optional)
1356 the data format that the secret is provided in (default: raw)
1357 keyid: string (optional)
1359 the name of another secret that should be used to decrypt the
1360 provided data. If not present, the data is assumed to be unen‐
1361 crypted.
1362 iv: string (optional)
1364 the random initialization vector used for encryption of this
1365 particular secret. Should be a base64 encrypted string of the
1366 16-byte IV. Mandatory if keyid is given. Ignored if keyid is ab‐
1367 sent.
1368 Features
1370 deprecated
1371 Member loaded is deprecated. Setting true doesn't make sense,
1372 and false is already the default.
1373 Since
1375 2.6
1376 SecretProperties (Object)
1378 Properties for secret objects.
1379 Either data or file must be provided, but not both.
1381 Members
1383 data: string (optional)
1384 the associated with the secret from
1385 file: string (optional)
1387 the filename to load the data associated with the secret from
1388 The members of SecretCommonProperties
1390 Since
1392 2.6
1393 SecretKeyringProperties (Object)
1395 Properties for secret_keyring objects.
1396 Members
1398 serial: int
1399 serial number that identifies a key to get from the kernel
1400 The members of SecretCommonProperties
1402 Since
1404 5.1
1405 TlsCredsProperties (Object)
1407 Properties for objects of classes derived from tls-creds.
1408 Members
1410 verify-peer: boolean (optional)
1411 if true the peer credentials will be verified once the handshake
1412 is completed. This is a no-op for anonymous credentials. (de‐
1413 fault: true)
1414 dir: string (optional)
1416 the path of the directory that contains the credential files
1417 endpoint: QCryptoTLSCredsEndpoint (optional)
1419 whether the QEMU network backend that uses the credentials will
1420 be acting as a client or as a server (default: client)
1421 priority: string (optional)
1423 a gnutls priority string as described at
1424 https://gnutls.org/manual/html_node/Priority-Strings.html
1425 Since
1427 2.5
1428 TlsCredsAnonProperties (Object)
1430 Properties for tls-creds-anon objects.
1431 Members
1433 loaded: boolean (optional)
1434 if true, the credentials are loaded immediately when applying
1435 this option and will ignore options that are processed later.
1436 Don't use; only provided for compatibility. (default: false)
1437 The members of TlsCredsProperties
1439 Features
1441 deprecated
1442 Member loaded is deprecated. Setting true doesn't make sense,
1443 and false is already the default.
1444 Since
1446 2.5
1447 TlsCredsPskProperties (Object)
1449 Properties for tls-creds-psk objects.
1450 Members
1452 loaded: boolean (optional)
1453 if true, the credentials are loaded immediately when applying
1454 this option and will ignore options that are processed later.
1455 Don't use; only provided for compatibility. (default: false)
1456 username: string (optional)
1458 the username which will be sent to the server. For clients
1459 only. If absent, "qemu" is sent and the property will read back
1460 as an empty string.
1461 The members of TlsCredsProperties
1463 Features
1465 deprecated
1466 Member loaded is deprecated. Setting true doesn't make sense,
1467 and false is already the default.
1468 Since
1470 3.0
1471 TlsCredsX509Properties (Object)
1473 Properties for tls-creds-x509 objects.
1474 Members
1476 loaded: boolean (optional)
1477 if true, the credentials are loaded immediately when applying
1478 this option and will ignore options that are processed later.
1479 Don't use; only provided for compatibility. (default: false)
1480 sanity-check: boolean (optional)
1482 if true, perform some sanity checks before using the credentials
1483 (default: true)
1484 passwordid: string (optional)
1486 For the server-key.pem and client-key.pem files which contain
1487 sensitive private keys, it is possible to use an encrypted ver‐
1488 sion by providing the passwordid parameter. This provides the
1489 ID of a previously created secret object containing the password
1490 for decryption.
1491 The members of TlsCredsProperties
1493 Features
1495 deprecated
1496 Member loaded is deprecated. Setting true doesn't make sense,
1497 and false is already the default.
1498 Since
1500 2.5
1501 Background jobs
1503 JobType (Enum)
1504 Type of a background job.
1505 Values
1507 commit block commit job type, see "block-commit"
1508 stream block stream job type, see "block-stream"
1510 mirror drive mirror job type, see "drive-mirror"
1512 backup drive backup job type, see "drive-backup"
1514 create image creation job type, see "blockdev-create" (since 3.0)
1516 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
1518 snapshot-load
1520 snapshot load job type, see "snapshot-load" (since 6.0)
1521 snapshot-save
1523 snapshot save job type, see "snapshot-save" (since 6.0)
1524 snapshot-delete
1526 snapshot delete job type, see "snapshot-delete" (since 6.0)
1527 Since
1529 1.7
1530 JobStatus (Enum)
1532 Indicates the present state of a given job in its lifetime.
1533 Values
1535 undefined
1536 Erroneous, default state. Should not ever be visible.
1537 created
1539 The job has been created, but not yet started.
1540 running
1542 The job is currently running.
1543 paused The job is running, but paused. The pause may be requested by
1545 either the QMP user or by internal processes.
1546 ready The job is running, but is ready for the user to signal comple‐
1548 tion. This is used for long-running jobs like mirror that are
1549 designed to run indefinitely.
1550 standby
1552 The job is ready, but paused. This is nearly identical to
1553 paused. The job may return to ready or otherwise be canceled.
1554 waiting
1556 The job is waiting for other jobs in the transaction to converge
1557 to the waiting state. This status will likely not be visible for
1558 the last job in a transaction.
1559 pending
1561 The job has finished its work, but has finalization steps that
1562 it needs to make prior to completing. These changes will require
1563 manual intervention via job-finalize if auto-finalize was set to
1564 false. These pending changes may still fail.
1565 aborting
1567 The job is in the process of being aborted, and will finish with
1568 an error. The job will afterwards report that it is concluded.
1569 This status may not be visible to the management process.
1570 concluded
1572 The job has finished all work. If auto-dismiss was set to false,
1573 the job will remain in the query list until it is dismissed via
1574 job-dismiss.
1575 null The job is in the process of being dismantled. This state should
1577 not ever be visible externally.
1578 Since
1580 2.12
1581 JobVerb (Enum)
1583 Represents command verbs that can be applied to a job.
1584 Values
1586 cancel see job-cancel
1587 pause see job-pause
1589 resume see job-resume
1591 set-speed
1593 see block-job-set-speed
1594 complete
1596 see job-complete
1597 dismiss
1599 see job-dismiss
1600 finalize
1602 see job-finalize
1603 Since
1605 2.12
1606 JOB_STATUS_CHANGE (Event)
1608 Emitted when a job transitions to a different status.
1609 Arguments
1611 id: string
1612 The job identifier
1613 status: JobStatus
1615 The new job status
1616 Since
1618 3.0
1619 job-pause (Command)
1621 Pause an active job.
1622 This command returns immediately after marking the active job for paus‐
1624 ing. Pausing an already paused job is an error.
1625 The job will pause as soon as possible, which means transitioning into
1627 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
1628 The corresponding JOB_STATUS_CHANGE event will be emitted.
1629 Cancelling a paused job automatically resumes it.
1631 Arguments
1633 id: string
1634 The job identifier.
1635 Since
1637 3.0
1638 job-resume (Command)
1640 Resume a paused job.
1641 This command returns immediately after resuming a paused job. Resuming
1643 an already running job is an error.
1644 id : The job identifier.
1646 Arguments
1648 id: string
1649 Not documented
1650 Since
1652 3.0
1653 job-cancel (Command)
1655 Instruct an active background job to cancel at the next opportunity.
1656 This command returns immediately after marking the active job for can‐
1657 cellation.
1658 The job will cancel as soon as possible and then emit a JOB_STA‐
1660 TUS_CHANGE event. Usually, the status will change to ABORTING, but it
1661 is possible that a job successfully completes (e.g. because it was al‐
1662 most done and there was no opportunity to cancel earlier than complet‐
1663 ing the job) and transitions to PENDING instead.
1664 Arguments
1666 id: string
1667 The job identifier.
1668 Since
1670 3.0
1671 job-complete (Command)
1673 Manually trigger completion of an active job in the READY state.
1674 Arguments
1676 id: string
1677 The job identifier.
1678 Since
1680 3.0
1681 job-dismiss (Command)
1683 Deletes a job that is in the CONCLUDED state. This command only needs
1684 to be run explicitly for jobs that don't have automatic dismiss en‐
1685 abled.
1686 This command will refuse to operate on any job that has not yet reached
1688 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
1689 JOB_READY event, job-cancel or job-complete will still need to be used
1690 as appropriate.
1691 Arguments
1693 id: string
1694 The job identifier.
1695 Since
1697 3.0
1698 job-finalize (Command)
1700 Instructs all jobs in a transaction (or a single job if it is not part
1701 of any transaction) to finalize any graph changes and do any necessary
1702 cleanup. This command requires that all involved jobs are in the PEND‐
1703 ING state.
1704 For jobs in a transaction, instructing one job to finalize will force
1706 ALL jobs in the transaction to finalize, so it is only necessary to in‐
1707 struct a single member job to finalize.
1708 Arguments
1710 id: string
1711 The identifier of any job in the transaction, or of a job that
1712 is not part of any transaction.
1713 Since
1715 3.0
1716 JobInfo (Object)
1718 Information about a job.
1719 Members
1721 id: string
1722 The job identifier
1723 type: JobType
1725 The kind of job that is being performed
1726 status: JobStatus
1728 Current job state/status
1729 current-progress: int
1731 Progress made until now. The unit is arbitrary and the value can
1732 only meaningfully be used for the ratio of current-progress to
1733 total-progress. The value is monotonically increasing.
1734 total-progress: int
1736 Estimated current-progress value at the completion of the job.
1737 This value can arbitrarily change while the job is running, in
1738 both directions.
1739 error: string (optional)
1741 If this field is present, the job failed; if it is still missing
1742 in the CONCLUDED state, this indicates successful completion.
1743 The value is a human-readable error message to describe the rea‐
1745 son for the job failure. It should not be parsed by applica‐
1746 tions.
1747 Since
1749 3.0
1750 query-jobs (Command)
1752 Return information about jobs.
1753 Returns
1755 a list with a JobInfo for each active job
1756 Since
1758 3.0
1759
1761 NetworkAddressFamily (Enum)
1762 The network address family
1763 Values
1765 ipv4 IPV4 family
1766 ipv6 IPV6 family
1768 unix unix socket
1770 vsock vsock family (since 2.8)
1772 unknown
1774 otherwise
1775 Since
1777 2.1
1778 InetSocketAddressBase (Object)
1780 Members
1781 host: string
1782 host part of the address
1783 port: string
1785 port part of the address
1786 InetSocketAddress (Object)
1788 Captures a socket address or address range in the Internet namespace.
1789 Members
1791 numeric: boolean (optional)
1792 true if the host/port are guaranteed to be numeric, false if
1793 name resolution should be attempted. Defaults to false. (Since
1794 2.9)
1795 to: int (optional)
1797 If present, this is range of possible addresses, with port be‐
1798 tween port and to.
1799 ipv4: boolean (optional)
1801 whether to accept IPv4 addresses, default try both IPv4 and IPv6
1802 ipv6: boolean (optional)
1804 whether to accept IPv6 addresses, default try both IPv4 and IPv6
1805 keep-alive: boolean (optional)
1807 enable keep-alive when connecting to this socket. Not supported
1808 for passive sockets. (Since 4.2)
1809 mptcp: boolean (optional) (If: HAVE_IPPROTO_MPTCP)
1811 enable multi-path TCP. (Since 6.1)
1812 The members of InetSocketAddressBase
1814 Since
1816 1.3
1817 UnixSocketAddress (Object)
1819 Captures a socket address in the local ("Unix socket") namespace.
1820 Members
1822 path: string
1823 filesystem path to use
1824 abstract: boolean (optional) (If: CONFIG_LINUX)
1826 if true, this is a Linux abstract socket address. path will be
1827 prefixed by a null byte, and optionally padded with null bytes.
1828 Defaults to false. (Since 5.1)
1829 tight: boolean (optional) (If: CONFIG_LINUX)
1831 if false, pad an abstract socket address with enough null bytes
1832 to make it fill struct sockaddr_un member sun_path. Defaults to
1833 true. (Since 5.1)
1834 Since
1836 1.3
1837 VsockSocketAddress (Object)
1839 Captures a socket address in the vsock namespace.
1840 Members
1842 cid: string
1843 unique host identifier
1844 port: string
1846 port
1847 Note
1849 string types are used to allow for possible future hostname or service
1850 resolution support.
1851 Since
1853 2.8
1854 InetSocketAddressWrapper (Object)
1856 Members
1857 data: InetSocketAddress
1858 Not documented
1859 Since
1861 1.3
1862 UnixSocketAddressWrapper (Object)
1864 Members
1865 data: UnixSocketAddress
1866 Not documented
1867 Since
1869 1.3
1870 VsockSocketAddressWrapper (Object)
1872 Members
1873 data: VsockSocketAddress
1874 Not documented
1875 Since
1877 2.8
1878 StringWrapper (Object)
1880 Members
1881 data: String
1882 Not documented
1883 Since
1885 1.3
1886 SocketAddressLegacy (Object)
1888 Captures the address of a socket, which could also be a named file de‐
1889 scriptor
1890 Members
1892 type: SocketAddressType
1893 Not documented
1894 The members of InetSocketAddressWrapper when type is "inet"
1896 The members of UnixSocketAddressWrapper when type is "unix"
1898 The members of VsockSocketAddressWrapper when type is "vsock"
1900 The members of StringWrapper when type is "fd"
1902 Note
1904 This type is deprecated in favor of SocketAddress. The difference be‐
1905 tween SocketAddressLegacy and SocketAddress is that the latter is has
1906 fewer {} on the wire.
1907 Since
1909 1.3
1910 SocketAddressType (Enum)
1912 Available SocketAddress types
1913 Values
1915 inet Internet address
1916 unix Unix domain socket
1918 vsock VMCI address
1920 fd decimal is for file descriptor number, otherwise a file descrip‐
1922 tor name. Named file descriptors are permitted in monitor com‐
1923 mands, in combination with the 'getfd' command. Decimal file de‐
1924 scriptors are permitted at startup or other contexts where no
1925 monitor context is active.
1926 Since
1928 2.9
1929 SocketAddress (Object)
1931 Captures the address of a socket, which could also be a named file de‐
1932 scriptor
1933 Members
1935 type: SocketAddressType
1936 Transport type
1937 The members of InetSocketAddress when type is "inet"
1939 The members of UnixSocketAddress when type is "unix"
1941 The members of VsockSocketAddress when type is "vsock"
1943 The members of String when type is "fd"
1945 Since
1947 2.9
1948 SnapshotInfo (Object)
1950 Members
1951 id: string
1952 unique snapshot id
1953 name: string
1955 user chosen name
1956 vm-state-size: int
1958 size of the VM state
1959 date-sec: int
1961 UTC date of the snapshot in seconds
1962 date-nsec: int
1964 fractional part in nano seconds to be used with date-sec
1965 vm-clock-sec: int
1967 VM clock relative to boot in seconds
1968 vm-clock-nsec: int
1970 fractional part in nano seconds to be used with vm-clock-sec
1971 icount: int (optional)
1973 Current instruction count. Appears when execution record/replay
1974 is enabled. Used for "time-traveling" to match the moment in the
1975 recorded execution with the snapshots. This counter may be ob‐
1976 tained through query-replay command (since 5.2)
1977 Since
1979 1.3
1980 ImageInfoSpecificQCow2EncryptionBase (Object)
1982 Members
1983 format: BlockdevQcow2EncryptionFormat
1984 The encryption format
1985 Since
1987 2.10
1988 ImageInfoSpecificQCow2Encryption (Object)
1990 Members
1991 The members of ImageInfoSpecificQCow2EncryptionBase
1992 The members of QCryptoBlockInfoLUKS when format is "luks"
1994 Since
1996 2.10
1997 ImageInfoSpecificQCow2 (Object)
1999 Members
2000 compat: string
2001 compatibility level
2002 data-file: string (optional)
2004 the filename of the external data file that is stored in the im‐
2005 age and used as a default for opening the image (since: 4.0)
2006 data-file-raw: boolean (optional)
2008 True if the external data file must stay valid as a standalone
2009 (read-only) raw image without looking at qcow2 metadata (since:
2010 4.0)
2011 extended-l2: boolean (optional)
2013 true if the image has extended L2 entries; only valid for compat
2014 >= 1.1 (since 5.2)
2015 lazy-refcounts: boolean (optional)
2017 on or off; only valid for compat >= 1.1
2018 corrupt: boolean (optional)
2020 true if the image has been marked corrupt; only valid for compat
2021 >= 1.1 (since 2.2)
2022 refcount-bits: int
2024 width of a refcount entry in bits (since 2.3)
2025 encrypt: ImageInfoSpecificQCow2Encryption (optional)
2027 details about encryption parameters; only set if image is en‐
2028 crypted (since 2.10)
2029 bitmaps: array of Qcow2BitmapInfo (optional)
2031 A list of qcow2 bitmap details (since 4.0)
2032 compression-type: Qcow2CompressionType
2034 the image cluster compression method (since 5.1)
2035 Since
2037 1.7
2038 ImageInfoSpecificVmdk (Object)
2040 Members
2041 create-type: string
2042 The create type of VMDK image
2043 cid: int
2045 Content id of image
2046 parent-cid: int
2048 Parent VMDK image's cid
2049 extents: array of ImageInfo
2051 List of extent files
2052 Since
2054 1.7
2055 ImageInfoSpecificRbd (Object)
2057 Members
2058 encryption-format: RbdImageEncryptionFormat (optional)
2059 Image encryption format
2060 Since
2062 6.1
2063 ImageInfoSpecificKind (Enum)
2065 Values
2066 luks Since 2.7
2067 rbd Since 6.1
2069 qcow2 Not documented
2071 vmdk Not documented
2073 Since
2075 1.7
2076 ImageInfoSpecificQCow2Wrapper (Object)
2078 Members
2079 data: ImageInfoSpecificQCow2
2080 Not documented
2081 Since
2083 1.7
2084 ImageInfoSpecificVmdkWrapper (Object)
2086 Members
2087 data: ImageInfoSpecificVmdk
2088 Not documented
2089 Since
2091 6.1
2092 ImageInfoSpecificLUKSWrapper (Object)
2094 Members
2095 data: QCryptoBlockInfoLUKS
2096 Not documented
2097 Since
2099 2.7
2100 ImageInfoSpecificRbdWrapper (Object)
2102 Members
2103 data: ImageInfoSpecificRbd
2104 Not documented
2105 Since
2107 6.1
2108 ImageInfoSpecific (Object)
2110 A discriminated record of image format specific information structures.
2111 Members
2113 type: ImageInfoSpecificKind
2114 Not documented
2115 The members of ImageInfoSpecificQCow2Wrapper when type is "qcow2"
2117 The members of ImageInfoSpecificVmdkWrapper when type is "vmdk"
2119 The members of ImageInfoSpecificLUKSWrapper when type is "luks"
2121 The members of ImageInfoSpecificRbdWrapper when type is "rbd"
2123 Since
2125 1.7
2126 ImageInfo (Object)
2128 Information about a QEMU image file
2129 Members
2131 filename: string
2132 name of the image file
2133 format: string
2135 format of the image file
2136 virtual-size: int
2138 maximum capacity in bytes of the image
2139 actual-size: int (optional)
2141 actual size on disk in bytes of the image
2142 dirty-flag: boolean (optional)
2144 true if image is not cleanly closed
2145 cluster-size: int (optional)
2147 size of a cluster in bytes
2148 encrypted: boolean (optional)
2150 true if the image is encrypted
2151 compressed: boolean (optional)
2153 true if the image is compressed (Since 1.7)
2154 backing-filename: string (optional)
2156 name of the backing file
2157 full-backing-filename: string (optional)
2159 full path of the backing file
2160 backing-filename-format: string (optional)
2162 the format of the backing file
2163 snapshots: array of SnapshotInfo (optional)
2165 list of VM snapshots
2166 backing-image: ImageInfo (optional)
2168 info of the backing image (since 1.6)
2169 format-specific: ImageInfoSpecific (optional)
2171 structure supplying additional format-specific information
2172 (since 1.7)
2173 Since
2175 1.3
2176 ImageCheck (Object)
2178 Information about a QEMU image file check
2179 Members
2181 filename: string
2182 name of the image file checked
2183 format: string
2185 format of the image file checked
2186 check-errors: int
2188 number of unexpected errors occurred during check
2189 image-end-offset: int (optional)
2191 offset (in bytes) where the image ends, this field is present if
2192 the driver for the image format supports it
2193 corruptions: int (optional)
2195 number of corruptions found during the check if any
2196 leaks: int (optional)
2198 number of leaks found during the check if any
2199 corruptions-fixed: int (optional)
2201 number of corruptions fixed during the check if any
2202 leaks-fixed: int (optional)
2204 number of leaks fixed during the check if any
2205 total-clusters: int (optional)
2207 total number of clusters, this field is present if the driver
2208 for the image format supports it
2209 allocated-clusters: int (optional)
2211 total number of allocated clusters, this field is present if the
2212 driver for the image format supports it
2213 fragmented-clusters: int (optional)
2215 total number of fragmented clusters, this field is present if
2216 the driver for the image format supports it
2217 compressed-clusters: int (optional)
2219 total number of compressed clusters, this field is present if
2220 the driver for the image format supports it
2221 Since
2223 1.4
2224 MapEntry (Object)
2226 Mapping information from a virtual block range to a host file range
2227 Members
2229 start: int
2230 virtual (guest) offset of the first byte described by this entry
2231 length: int
2233 the number of bytes of the mapped virtual range
2234 data: boolean
2236 reading the image will actually read data from a file (in par‐
2237 ticular, if offset is present this means that the sectors are
2238 not simply preallocated, but contain actual data in raw format)
2239 zero: boolean
2241 whether the virtual blocks read as zeroes
2242 depth: int
2244 number of layers (0 = top image, 1 = top image's backing file,
2245 ..., n - 1 = bottom image (where n is the number of images in
2246 the chain)) before reaching one for which the range is allocated
2247 present: boolean
2249 true if this layer provides the data, false if adding a backing
2250 layer could impact this region (since 6.1)
2251 offset: int (optional)
2253 if present, the image file stores the data for this range in raw
2254 format at the given (host) offset
2255 filename: string (optional)
2257 filename that is referred to by offset
2258 Since
2260 2.6
2261 BlockdevCacheInfo (Object)
2263 Cache mode information for a block device
2264 Members
2266 writeback: boolean
2267 true if writeback mode is enabled
2268 direct: boolean
2270 true if the host page cache is bypassed (O_DIRECT)
2271 no-flush: boolean
2273 true if flush requests are ignored for the device
2274 Since
2276 2.3
2277 BlockDeviceInfo (Object)
2279 Information about the backing device for a block device.
2280 Members
2282 file: string
2283 the filename of the backing device
2284 node-name: string (optional)
2286 the name of the block driver node (Since 2.0)
2287 ro: boolean
2289 true if the backing device was open read-only
2290 drv: string
2292 the name of the block format used to open the backing device. As
2293 of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
2294 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
2295 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2',
2296 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added,
2297 'cow' dropped 2.3: 'host_floppy' deprecated 2.5: 'host_floppy'
2298 dropped 2.6: 'luks' added 2.8: 'replication' added, 'tftp'
2299 dropped 2.9: 'archipelago' dropped
2300 backing_file: string (optional)
2302 the name of the backing file (for copy-on-write)
2303 backing_file_depth: int
2305 number of files in the backing file chain (since: 1.2)
2306 encrypted: boolean
2308 true if the backing device is encrypted
2309 detect_zeroes: BlockdevDetectZeroesOptions
2311 detect and optimize zero writes (Since 2.1)
2312 bps: int
2314 total throughput limit in bytes per second is specified
2315 bps_rd: int
2317 read throughput limit in bytes per second is specified
2318 bps_wr: int
2320 write throughput limit in bytes per second is specified
2321 iops: int
2323 total I/O operations per second is specified
2324 iops_rd: int
2326 read I/O operations per second is specified
2327 iops_wr: int
2329 write I/O operations per second is specified
2330 image: ImageInfo
2332 the info of image used (since: 1.6)
2333 bps_max: int (optional)
2335 total throughput limit during bursts,
2337 in bytes (Since 1.7)
2338 bps_rd_max: int (optional)
2340 read throughput limit during bursts,
2342 in bytes (Since 1.7)
2343 bps_wr_max: int (optional)
2345 write throughput limit during bursts,
2347 in bytes (Since 1.7)
2348 iops_max: int (optional)
2350 total I/O operations per second during bursts,
2352 in bytes (Since 1.7)
2353 iops_rd_max: int (optional)
2355 read I/O operations per second during bursts,
2357 in bytes (Since 1.7)
2358 iops_wr_max: int (optional)
2360 write I/O operations per second during bursts,
2362 in bytes (Since 1.7)
2363 bps_max_length: int (optional)
2365 maximum length of the bps_max burst
2367 period, in seconds. (Since 2.6)
2368 bps_rd_max_length: int (optional)
2370 maximum length of the bps_rd_max
2372 burst period, in seconds. (Since 2.6)
2373 bps_wr_max_length: int (optional)
2375 maximum length of the bps_wr_max
2377 burst period, in seconds. (Since 2.6)
2378 iops_max_length: int (optional)
2380 maximum length of the iops burst
2382 period, in seconds. (Since 2.6)
2383 iops_rd_max_length: int (optional)
2385 maximum length of the iops_rd_max
2387 burst period, in seconds. (Since 2.6)
2388 iops_wr_max_length: int (optional)
2390 maximum length of the iops_wr_max
2392 burst period, in seconds. (Since 2.6)
2393 iops_size: int (optional)
2395 an I/O size in bytes (Since 1.7)
2396 group: string (optional)
2398 throttle group name (Since 2.4)
2399 cache: BlockdevCacheInfo
2401 the cache mode used for the block device (since: 2.3)
2402 write_threshold: int
2404 configured write threshold for the device. 0 if disabled.
2405 (Since 2.3)
2406 dirty-bitmaps: array of BlockDirtyInfo (optional)
2408 dirty bitmaps information (only present if node has one or more
2409 dirty bitmaps) (Since 4.2)
2410 Since
2412 0.14
2413 BlockDeviceIoStatus (Enum)
2415 An enumeration of block device I/O status.
2416 Values
2418 ok The last I/O operation has succeeded
2419 failed The last I/O operation has failed
2421 nospace
2423 The last I/O operation has failed due to a no-space condition
2424 Since
2426 1.0
2427 BlockDirtyInfo (Object)
2429 Block dirty bitmap information.
2430 Members
2432 name: string (optional)
2433 the name of the dirty bitmap (Since 2.4)
2434 count: int
2436 number of dirty bytes according to the dirty bitmap
2437 granularity: int
2439 granularity of the dirty bitmap in bytes (since 1.4)
2440 recording: boolean
2442 true if the bitmap is recording new writes from the guest. Re‐
2443 places active and disabled statuses. (since 4.0)
2444 busy: boolean
2446 true if the bitmap is in-use by some operation (NBD or jobs) and
2447 cannot be modified via QMP or used by another operation. Re‐
2448 places locked and frozen statuses. (since 4.0)
2449 persistent: boolean
2451 true if the bitmap was stored on disk, is scheduled to be stored
2452 on disk, or both. (since 4.0)
2453 inconsistent: boolean (optional)
2455 true if this is a persistent bitmap that was improperly stored.
2456 Implies persistent to be true; recording and busy to be false.
2457 This bitmap cannot be used. To remove it, use block-dirty-bit‐
2458 map-remove. (Since 4.0)
2459 Since
2461 1.3
2462 Qcow2BitmapInfoFlags (Enum)
2464 An enumeration of flags that a bitmap can report to the user.
2465 Values
2467 in-use This flag is set by any process actively modifying the qcow2
2468 file, and cleared when the updated bitmap is flushed to the
2469 qcow2 image. The presence of this flag in an offline image
2470 means that the bitmap was not saved correctly after its last us‐
2471 age, and may contain inconsistent data.
2472 auto The bitmap must reflect all changes of the virtual disk by any
2474 application that would write to this qcow2 file.
2475 Since
2477 4.0
2478 Qcow2BitmapInfo (Object)
2480 Qcow2 bitmap information.
2481 Members
2483 name: string
2484 the name of the bitmap
2485 granularity: int
2487 granularity of the bitmap in bytes
2488 flags: array of Qcow2BitmapInfoFlags
2490 flags of the bitmap
2491 Since
2493 4.0
2494 BlockLatencyHistogramInfo (Object)
2496 Block latency histogram.
2497 Members
2499 boundaries: array of int
2500 list of interval boundary values in nanoseconds, all greater
2501 than zero and in ascending order. For example, the list [10,
2502 50, 100] produces the following histogram intervals: [0, 10),
2503 [10, 50), [50, 100), [100, +inf).
2504 bins: array of int
2506 list of io request counts corresponding to histogram intervals.
2507 len(bins) = len(boundaries) + 1 For the example above, bins may
2508 be something like [3, 1, 5, 2], and corresponding histogram
2509 looks like:
2510 5| *
2512 4| *
2513 3| * *
2514 2| * * *
2515 1| * * * *
2516 +------------------
2517 10 50 100
2518 Since
2520 4.0
2521 BlockInfo (Object)
2523 Block device information. This structure describes a virtual device
2524 and the backing device associated with it.
2525 Members
2527 device: string
2528 The device name associated with the virtual device.
2529 qdev: string (optional)
2531 The qdev ID, or if no ID is assigned, the QOM path of the block
2532 device. (since 2.10)
2533 type: string
2535 This field is returned only for compatibility reasons, it should
2536 not be used (always returns 'unknown')
2537 removable: boolean
2539 True if the device supports removable media.
2540 locked: boolean
2542 True if the guest has locked this device from having its media
2543 removed
2544 tray_open: boolean (optional)
2546 True if the device's tray is open (only present if it has a
2547 tray)
2548 io-status: BlockDeviceIoStatus (optional)
2550 BlockDeviceIoStatus. Only present if the device supports it and
2551 the VM is configured to stop on errors (supported device models:
2552 virtio-blk, IDE, SCSI except scsi-generic)
2553 inserted: BlockDeviceInfo (optional)
2555 BlockDeviceInfo describing the device if media is present
2556 Since
2558 0.14
2559 BlockMeasureInfo (Object)
2561 Image file size calculation information. This structure describes the
2562 size requirements for creating a new image file.
2563 The size requirements depend on the new image file format. File size
2565 always equals virtual disk size for the 'raw' format, even for sparse
2566 POSIX files. Compact formats such as 'qcow2' represent unallocated and
2567 zero regions efficiently so file size may be smaller than virtual disk
2568 size.
2569 The values are upper bounds that are guaranteed to fit the new image
2571 file. Subsequent modification, such as internal snapshot or further
2572 bitmap creation, may require additional space and is not covered here.
2573 Members
2575 required: int
2576 Size required for a new image file, in bytes, when copying just
2577 allocated guest-visible contents.
2578 fully-allocated: int
2580 Image file size, in bytes, once data has been written to all
2581 sectors, when copying just guest-visible contents.
2582 bitmaps: int (optional)
2584 Additional size required if all the top-level bitmap metadata in
2585 the source image were to be copied to the destination, present
2586 only when source and destination both support persistent bit‐
2587 maps. (since 5.1)
2588 Since
2590 2.10
2591 query-block (Command)
2593 Get a list of BlockInfo for all virtual block devices.
2594 Returns
2596 a list of BlockInfo describing each virtual block device. Filter nodes
2597 that were created implicitly are skipped over.
2598 Since
2600 0.14
2601 Example
2603 -> { "execute": "query-block" }
2604 <- {
2605 "return":[
2606 {
2607 "io-status": "ok",
2608 "device":"ide0-hd0",
2609 "locked":false,
2610 "removable":false,
2611 "inserted":{
2612 "ro":false,
2613 "drv":"qcow2",
2614 "encrypted":false,
2615 "file":"disks/test.qcow2",
2616 "backing_file_depth":1,
2617 "bps":1000000,
2618 "bps_rd":0,
2619 "bps_wr":0,
2620 "iops":1000000,
2621 "iops_rd":0,
2622 "iops_wr":0,
2623 "bps_max": 8000000,
2624 "bps_rd_max": 0,
2625 "bps_wr_max": 0,
2626 "iops_max": 0,
2627 "iops_rd_max": 0,
2628 "iops_wr_max": 0,
2629 "iops_size": 0,
2630 "detect_zeroes": "on",
2631 "write_threshold": 0,
2632 "image":{
2633 "filename":"disks/test.qcow2",
2634 "format":"qcow2",
2635 "virtual-size":2048000,
2636 "backing_file":"base.qcow2",
2637 "full-backing-filename":"disks/base.qcow2",
2638 "backing-filename-format":"qcow2",
2639 "snapshots":[
2640 {
2641 "id": "1",
2642 "name": "snapshot1",
2643 "vm-state-size": 0,
2644 "date-sec": 10000200,
2645 "date-nsec": 12,
2646 "vm-clock-sec": 206,
2647 "vm-clock-nsec": 30
2648 }
2649 ],
2650 "backing-image":{
2651 "filename":"disks/base.qcow2",
2652 "format":"qcow2",
2653 "virtual-size":2048000
2654 }
2655 }
2656 },
2657 "qdev": "ide_disk",
2658 "type":"unknown"
2659 },
2660 {
2661 "io-status": "ok",
2662 "device":"ide1-cd0",
2663 "locked":false,
2664 "removable":true,
2665 "qdev": "/machine/unattached/device[23]",
2666 "tray_open": false,
2667 "type":"unknown"
2668 },
2669 {
2670 "device":"floppy0",
2671 "locked":false,
2672 "removable":true,
2673 "qdev": "/machine/unattached/device[20]",
2674 "type":"unknown"
2675 },
2676 {
2677 "device":"sd0",
2678 "locked":false,
2679 "removable":true,
2680 "type":"unknown"
2681 }
2682 ]
2683 }
2684 BlockDeviceTimedStats (Object)
2686 Statistics of a block device during a given interval of time.
2687 Members
2689 interval_length: int
2690 Interval used for calculating the statistics, in seconds.
2691 min_rd_latency_ns: int
2693 Minimum latency of read operations in the defined interval, in
2694 nanoseconds.
2695 min_wr_latency_ns: int
2697 Minimum latency of write operations in the defined interval, in
2698 nanoseconds.
2699 min_flush_latency_ns: int
2701 Minimum latency of flush operations in the defined interval, in
2702 nanoseconds.
2703 max_rd_latency_ns: int
2705 Maximum latency of read operations in the defined interval, in
2706 nanoseconds.
2707 max_wr_latency_ns: int
2709 Maximum latency of write operations in the defined interval, in
2710 nanoseconds.
2711 max_flush_latency_ns: int
2713 Maximum latency of flush operations in the defined interval, in
2714 nanoseconds.
2715 avg_rd_latency_ns: int
2717 Average latency of read operations in the defined interval, in
2718 nanoseconds.
2719 avg_wr_latency_ns: int
2721 Average latency of write operations in the defined interval, in
2722 nanoseconds.
2723 avg_flush_latency_ns: int
2725 Average latency of flush operations in the defined interval, in
2726 nanoseconds.
2727 avg_rd_queue_depth: number
2729 Average number of pending read operations in the defined inter‐
2730 val.
2731 avg_wr_queue_depth: number
2733 Average number of pending write operations in the defined inter‐
2734 val.
2735 Since
2737 2.5
2738 BlockDeviceStats (Object)
2740 Statistics of a virtual block device or a block backing device.
2741 Members
2743 rd_bytes: int
2744 The number of bytes read by the device.
2745 wr_bytes: int
2747 The number of bytes written by the device.
2748 unmap_bytes: int
2750 The number of bytes unmapped by the device (Since 4.2)
2751 rd_operations: int
2753 The number of read operations performed by the device.
2754 wr_operations: int
2756 The number of write operations performed by the device.
2757 flush_operations: int
2759 The number of cache flush operations performed by the device
2760 (since 0.15)
2761 unmap_operations: int
2763 The number of unmap operations performed by the device (Since
2764 4.2)
2765 rd_total_time_ns: int
2767 Total time spent on reads in nanoseconds (since 0.15).
2768 wr_total_time_ns: int
2770 Total time spent on writes in nanoseconds (since 0.15).
2771 flush_total_time_ns: int
2773 Total time spent on cache flushes in nanoseconds (since 0.15).
2774 unmap_total_time_ns: int
2776 Total time spent on unmap operations in nanoseconds (Since 4.2)
2777 wr_highest_offset: int
2779 The offset after the greatest byte written to the device. The
2780 intended use of this information is for growable sparse files
2781 (like qcow2) that are used on top of a physical device.
2782 rd_merged: int
2784 Number of read requests that have been merged into another re‐
2785 quest (Since 2.3).
2786 wr_merged: int
2788 Number of write requests that have been merged into another re‐
2789 quest (Since 2.3).
2790 unmap_merged: int
2792 Number of unmap requests that have been merged into another re‐
2793 quest (Since 4.2)
2794 idle_time_ns: int (optional)
2796 Time since the last I/O operation, in nanoseconds. If the field
2797 is absent it means that there haven't been any operations yet
2798 (Since 2.5).
2799 failed_rd_operations: int
2801 The number of failed read operations performed by the device
2802 (Since 2.5)
2803 failed_wr_operations: int
2805 The number of failed write operations performed by the device
2806 (Since 2.5)
2807 failed_flush_operations: int
2809 The number of failed flush operations performed by the device
2810 (Since 2.5)
2811 failed_unmap_operations: int
2813 The number of failed unmap operations performed by the device
2814 (Since 4.2)
2815 invalid_rd_operations: int
2817 The number of invalid read operations
2819 performed by the device (Since 2.5)
2820 invalid_wr_operations: int
2822 The number of invalid write operations performed by the device
2823 (Since 2.5)
2824 invalid_flush_operations: int
2826 The number of invalid flush operations performed by the device
2827 (Since 2.5)
2828 invalid_unmap_operations: int
2830 The number of invalid unmap operations performed by the device
2831 (Since 4.2)
2832 account_invalid: boolean
2834 Whether invalid operations are included in the last access sta‐
2835 tistics (Since 2.5)
2836 account_failed: boolean
2838 Whether failed operations are included in the latency and last
2839 access statistics (Since 2.5)
2840 timed_stats: array of BlockDeviceTimedStats
2842 Statistics specific to the set of previously defined intervals
2843 of time (Since 2.5)
2844 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
2846 BlockLatencyHistogramInfo. (Since 4.0)
2847 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
2849 BlockLatencyHistogramInfo. (Since 4.0)
2850 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
2852 BlockLatencyHistogramInfo. (Since 4.0)
2853 Since
2855 0.14
2856 BlockStatsSpecificFile (Object)
2858 File driver statistics
2859 Members
2861 discard-nb-ok: int
2862 The number of successful discard operations performed by the
2863 driver.
2864 discard-nb-failed: int
2866 The number of failed discard operations performed by the driver.
2867 discard-bytes-ok: int
2869 The number of bytes discarded by the driver.
2870 Since
2872 4.2
2873 BlockStatsSpecificNvme (Object)
2875 NVMe driver statistics
2876 Members
2878 completion-errors: int
2879 The number of completion errors.
2880 aligned-accesses: int
2882 The number of aligned accesses performed by the driver.
2883 unaligned-accesses: int
2885 The number of unaligned accesses performed by the driver.
2886 Since
2888 5.2
2889 BlockStatsSpecific (Object)
2891 Block driver specific statistics
2892 Members
2894 driver: BlockdevDriver
2895 Not documented
2896 The members of BlockStatsSpecificFile when driver is "file"
2898 The members of BlockStatsSpecificFile when driver is "host_device" (If:
2900 HAVE_HOST_BLOCK_DEVICE)
2901 The members of BlockStatsSpecificNvme when driver is "nvme"
2903 Since
2905 4.2
2906 BlockStats (Object)
2908 Statistics of a virtual block device or a block backing device.
2909 Members
2911 device: string (optional)
2912 If the stats are for a virtual block device, the name corre‐
2913 sponding to the virtual block device.
2914 node-name: string (optional)
2916 The node name of the device. (Since 2.3)
2917 qdev: string (optional)
2919 The qdev ID, or if no ID is assigned, the QOM path of the block
2920 device. (since 3.0)
2921 stats: BlockDeviceStats
2923 A BlockDeviceStats for the device.
2924 driver-specific: BlockStatsSpecific (optional)
2926 Optional driver-specific stats. (Since 4.2)
2927 parent: BlockStats (optional)
2929 This describes the file block device if it has one. Contains
2930 recursively the statistics of the underlying protocol (e.g. the
2931 host file for a qcow2 image). If there is no underlying proto‐
2932 col, this field is omitted
2933 backing: BlockStats (optional)
2935 This describes the backing block device if it has one. (Since
2936 2.0)
2937 Since
2939 0.14
2940 query-blockstats (Command)
2942 Query the BlockStats for all virtual block devices.
2943 Arguments
2945 query-nodes: boolean (optional)
2946 If true, the command will query all the block nodes that have a
2947 node name, in a list which will include "parent" information,
2948 but not "backing". If false or omitted, the behavior is as be‐
2949 fore - query all the device backends, recursively including
2950 their "parent" and "backing". Filter nodes that were created im‐
2951 plicitly are skipped over in this mode. (Since 2.3)
2952 Returns
2954 A list of BlockStats for each virtual block devices.
2955 Since
2957 0.14
2958 Example
2960 -> { "execute": "query-blockstats" }
2961 <- {
2962 "return":[
2963 {
2964 "device":"ide0-hd0",
2965 "parent":{
2966 "stats":{
2967 "wr_highest_offset":3686448128,
2968 "wr_bytes":9786368,
2969 "wr_operations":751,
2970 "rd_bytes":122567168,
2971 "rd_operations":36772
2972 "wr_total_times_ns":313253456
2973 "rd_total_times_ns":3465673657
2974 "flush_total_times_ns":49653
2975 "flush_operations":61,
2976 "rd_merged":0,
2977 "wr_merged":0,
2978 "idle_time_ns":2953431879,
2979 "account_invalid":true,
2980 "account_failed":false
2981 }
2982 },
2983 "stats":{
2984 "wr_highest_offset":2821110784,
2985 "wr_bytes":9786368,
2986 "wr_operations":692,
2987 "rd_bytes":122739200,
2988 "rd_operations":36604
2989 "flush_operations":51,
2990 "wr_total_times_ns":313253456
2991 "rd_total_times_ns":3465673657
2992 "flush_total_times_ns":49653,
2993 "rd_merged":0,
2994 "wr_merged":0,
2995 "idle_time_ns":2953431879,
2996 "account_invalid":true,
2997 "account_failed":false
2998 },
2999 "qdev": "/machine/unattached/device[23]"
3000 },
3001 {
3002 "device":"ide1-cd0",
3003 "stats":{
3004 "wr_highest_offset":0,
3005 "wr_bytes":0,
3006 "wr_operations":0,
3007 "rd_bytes":0,
3008 "rd_operations":0
3009 "flush_operations":0,
3010 "wr_total_times_ns":0
3011 "rd_total_times_ns":0
3012 "flush_total_times_ns":0,
3013 "rd_merged":0,
3014 "wr_merged":0,
3015 "account_invalid":false,
3016 "account_failed":false
3017 },
3018 "qdev": "/machine/unattached/device[24]"
3019 },
3020 {
3021 "device":"floppy0",
3022 "stats":{
3023 "wr_highest_offset":0,
3024 "wr_bytes":0,
3025 "wr_operations":0,
3026 "rd_bytes":0,
3027 "rd_operations":0
3028 "flush_operations":0,
3029 "wr_total_times_ns":0
3030 "rd_total_times_ns":0
3031 "flush_total_times_ns":0,
3032 "rd_merged":0,
3033 "wr_merged":0,
3034 "account_invalid":false,
3035 "account_failed":false
3036 },
3037 "qdev": "/machine/unattached/device[16]"
3038 },
3039 {
3040 "device":"sd0",
3041 "stats":{
3042 "wr_highest_offset":0,
3043 "wr_bytes":0,
3044 "wr_operations":0,
3045 "rd_bytes":0,
3046 "rd_operations":0
3047 "flush_operations":0,
3048 "wr_total_times_ns":0
3049 "rd_total_times_ns":0
3050 "flush_total_times_ns":0,
3051 "rd_merged":0,
3052 "wr_merged":0,
3053 "account_invalid":false,
3054 "account_failed":false
3055 }
3056 }
3057 ]
3058 }
3059 BlockdevOnError (Enum)
3061 An enumeration of possible behaviors for errors on I/O operations. The
3062 exact meaning depends on whether the I/O was initiated by a guest or by
3063 a block job
3064 Values
3066 report for guest operations, report the error to the guest; for jobs,
3067 cancel the job
3068 ignore ignore the error, only report a QMP event (BLOCK_IO_ERROR or
3070 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
3071 the failing request later and may still complete successfully.
3072 The stream block job continues to stream and will complete with
3073 an error.
3074 enospc same as stop on ENOSPC, same as report otherwise.
3076 stop for guest operations, stop the virtual machine; for jobs, pause
3078 the job
3079 auto inherit the error handling policy of the backend (since: 2.7)
3081 Since
3083 1.3
3084 MirrorSyncMode (Enum)
3086 An enumeration of possible behaviors for the initial synchronization
3087 phase of storage mirroring.
3088 Values
3090 top copies data in the topmost image to the destination
3091 full copies data from all images to the destination
3093 none only copy data written from now on
3095 incremental
3097 only copy data described by the dirty bitmap. (since: 2.4)
3098 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
3100 havior on completion is determined by the BitmapSyncMode.
3101 Since
3103 1.3
3104 BitmapSyncMode (Enum)
3106 An enumeration of possible behaviors for the synchronization of a bit‐
3107 map when used for data copy operations.
3108 Values
3110 on-success
3111 The bitmap is only synced when the operation is successful.
3112 This is the behavior always used for 'INCREMENTAL' backups.
3113 never The bitmap is never synchronized with the operation, and is
3115 treated solely as a read-only manifest of blocks to copy.
3116 always The bitmap is always synchronized with the operation, regardless
3118 of whether or not the operation was successful.
3119 Since
3121 4.2
3122 MirrorCopyMode (Enum)
3124 An enumeration whose values tell the mirror block job when to trigger
3125 writes to the target.
3126 Values
3128 background
3129 copy data in background only.
3130 write-blocking
3132 when data is written to the source, write it (synchronously) to
3133 the target as well. In addition, data is copied in background
3134 just like in background mode.
3135 Since
3137 3.0
3138 BlockJobInfo (Object)
3140 Information about a long-running block device operation.
3141 Members
3143 type: string
3144 the job type ('stream' for image streaming)
3145 device: string
3147 The job identifier. Originally the device name but other values
3148 are allowed since QEMU 2.7
3149 len: int
3151 Estimated offset value at the completion of the job. This value
3152 can arbitrarily change while the job is running, in both direc‐
3153 tions.
3154 offset: int
3156 Progress made until now. The unit is arbitrary and the value can
3157 only meaningfully be used for the ratio of offset to len. The
3158 value is monotonically increasing.
3159 busy: boolean
3161 false if the job is known to be in a quiescent state, with no
3162 pending I/O. Since 1.3.
3163 paused: boolean
3165 whether the job is paused or, if busy is true, will pause itself
3166 as soon as possible. Since 1.3.
3167 speed: int
3169 the rate limit, bytes per second
3170 io-status: BlockDeviceIoStatus
3172 the status of the job (since 1.3)
3173 ready: boolean
3175 true if the job may be completed (since 2.2)
3176 status: JobStatus
3178 Current job state/status (since 2.12)
3179 auto-finalize: boolean
3181 Job will finalize itself when PENDING, moving to the CONCLUDED
3182 state. (since 2.12)
3183 auto-dismiss: boolean
3185 Job will dismiss itself when CONCLUDED, moving to the NULL state
3186 and disappearing from the query list. (since 2.12)
3187 error: string (optional)
3189 Error information if the job did not complete successfully. Not
3190 set if the job completed successfully. (since 2.12.1)
3191 Since
3193 1.1
3194 query-block-jobs (Command)
3196 Return information about long-running block device operations.
3197 Returns
3199 a list of BlockJobInfo for each active block job
3200 Since
3202 1.1
3203 block_resize (Command)
3205 Resize a block image while a guest is running.
3206 Either device or node-name must be set but not both.
3208 Arguments
3210 device: string (optional)
3211 the name of the device to get the image resized
3212 node-name: string (optional)
3214 graph node name to get the image resized (Since 2.0)
3215 size: int
3217 new image size in bytes
3218 Returns
3220 • nothing on success
3221 • If device is not a valid block device, DeviceNotFound
3223 Since
3225 0.14
3226 Example
3228 -> { "execute": "block_resize",
3229 "arguments": { "device": "scratch", "size": 1073741824 } }
3230 <- { "return": {} }
3231 NewImageMode (Enum)
3233 An enumeration that tells QEMU how to set the backing file path in a
3234 new image file.
3235 Values
3237 existing
3238 QEMU should look for an existing image file.
3239 absolute-paths
3241 QEMU should create a new image with absolute paths for the back‐
3242 ing file. If there is no backing file available, the new image
3243 will not be backed either.
3244 Since
3246 1.1
3247 BlockdevSnapshotSync (Object)
3249 Either device or node-name must be set but not both.
3250 Members
3252 device: string (optional)
3253 the name of the device to take a snapshot of.
3254 node-name: string (optional)
3256 graph node name to generate the snapshot from (Since 2.0)
3257 snapshot-file: string
3259 the target of the new overlay image. If the file exists, or if
3260 it is a device, the overlay will be created in the existing
3261 file/device. Otherwise, a new file will be created.
3262 snapshot-node-name: string (optional)
3264 the graph node name of the new image (Since 2.0)
3265 format: string (optional)
3267 the format of the overlay image, default is 'qcow2'.
3268 mode: NewImageMode (optional)
3270 whether and how QEMU should create a new image, default is 'ab‐
3271 solute-paths'.
3272 BlockdevSnapshot (Object)
3274 Members
3275 node: string
3276 device or node name that will have a snapshot taken.
3277 overlay: string
3279 reference to the existing block device that will become the
3280 overlay of node, as part of taking the snapshot. It must not
3281 have a current backing file (this can be achieved by passing
3282 "backing": null to blockdev-add).
3283 Since
3285 2.5
3286 BackupPerf (Object)
3288 Optional parameters for backup. These parameters don't affect function‐
3289 ality, but may significantly affect performance.
3290 Members
3292 use-copy-range: boolean (optional)
3293 Use copy offloading. Default false.
3294 max-workers: int (optional)
3296 Maximum number of parallel requests for the sustained background
3297 copying process. Doesn't influence copy-before-write operations.
3298 Default 64.
3299 max-chunk: int (optional)
3301 Maximum request length for the sustained background copying
3302 process. Doesn't influence copy-before-write operations. 0
3303 means unlimited. If max-chunk is non-zero then it should not be
3304 less than job cluster size which is calculated as maximum of
3305 target image cluster size and 64k. Default 0.
3306 Since
3308 6.0
3309 BackupCommon (Object)
3311 Members
3312 job-id: string (optional)
3313 identifier for the newly-created block job. If omitted, the de‐
3314 vice name will be used. (Since 2.7)
3315 device: string
3317 the device name or node-name of a root node which should be
3318 copied.
3319 sync: MirrorSyncMode
3321 what parts of the disk image should be copied to the destination
3322 (all the disk, only the sectors allocated in the topmost image,
3323 from a dirty bitmap, or only new I/O).
3324 speed: int (optional)
3326 the maximum speed, in bytes per second. The default is 0, for
3327 unlimited.
3328 bitmap: string (optional)
3330 The name of a dirty bitmap to use. Must be present if sync is
3331 "bitmap" or "incremental". Can be present if sync is "full" or
3332 "top". Must not be present otherwise. (Since 2.4
3333 (drive-backup), 3.1 (blockdev-backup))
3334 bitmap-mode: BitmapSyncMode (optional)
3336 Specifies the type of data the bitmap should contain after the
3337 operation concludes. Must be present if a bitmap was provided,
3338 Must NOT be present otherwise. (Since 4.2)
3339 compress: boolean (optional)
3341 true to compress data, if the target format supports it. (de‐
3342 fault: false) (since 2.8)
3343 on-source-error: BlockdevOnError (optional)
3345 the action to take on an error on the source, default 'report'.
3346 'stop' and 'enospc' can only be used if the block device sup‐
3347 ports io-status (see BlockInfo).
3348 on-target-error: BlockdevOnError (optional)
3350 the action to take on an error on the target, default 'report'
3351 (no limitations, since this applies to a different block device
3352 than device).
3353 auto-finalize: boolean (optional)
3355 When false, this job will wait in a PENDING state after it has
3356 finished its work, waiting for block-job-finalize before making
3357 any block graph changes. When true, this job will automatically
3358 perform its abort or commit actions. Defaults to true. (Since
3359 2.12)
3360 auto-dismiss: boolean (optional)
3362 When false, this job will wait in a CONCLUDED state after it has
3363 completely ceased all work, and awaits block-job-dismiss. When
3364 true, this job will automatically disappear from the query list
3365 without user intervention. Defaults to true. (Since 2.12)
3366 filter-node-name: string (optional)
3368 the node name that should be assigned to the filter driver that
3369 the backup job inserts into the graph above node specified by
3370 drive. If this option is not given, a node name is autogener‐
3371 ated. (Since: 4.2)
3372 x-perf: BackupPerf (optional)
3374 Performance options. (Since 6.0)
3375 Features
3377 unstable
3378 Member x-perf is experimental.
3379 Note
3381 on-source-error and on-target-error only affect background I/O. If an
3382 error occurs during a guest write request, the device's rerror/werror
3383 actions will be used.
3384 Since
3386 4.2
3387 DriveBackup (Object)
3389 Members
3390 target: string
3391 the target of the new image. If the file exists, or if it is a
3392 device, the existing file/device will be used as the new desti‐
3393 nation. If it does not exist, a new file will be created.
3394 format: string (optional)
3396 the format of the new destination, default is to probe if mode
3397 is 'existing', else the format of the source
3398 mode: NewImageMode (optional)
3400 whether and how QEMU should create a new image, default is 'ab‐
3401 solute-paths'.
3402 The members of BackupCommon
3404 Since
3406 1.6
3407 BlockdevBackup (Object)
3409 Members
3410 target: string
3411 the device name or node-name of the backup target node.
3412 The members of BackupCommon
3414 Since
3416 2.3
3417 blockdev-snapshot-sync (Command)
3419 Takes a synchronous snapshot of a block device.
3420 For the arguments, see the documentation of BlockdevSnapshotSync.
3422 Returns
3424 • nothing on success
3425 • If device is not a valid block device, DeviceNotFound
3427 Since
3429 0.14
3430 Example
3432 -> { "execute": "blockdev-snapshot-sync",
3433 "arguments": { "device": "ide-hd0",
3434 "snapshot-file":
3435 "/some/place/my-image",
3436 "format": "qcow2" } }
3437 <- { "return": {} }
3438 blockdev-snapshot (Command)
3440 Takes a snapshot of a block device.
3441 Take a snapshot, by installing 'node' as the backing image of 'over‐
3443 lay'. Additionally, if 'node' is associated with a block device, the
3444 block device changes to using 'overlay' as its new active image.
3445 For the arguments, see the documentation of BlockdevSnapshot.
3447 Features
3449 allow-write-only-overlay
3450 If present, the check whether this operation is safe was relaxed
3451 so that it can be used to change backing file of a destination
3452 of a blockdev-mirror. (since 5.0)
3453 Since
3455 2.5
3456 Example
3458 -> { "execute": "blockdev-add",
3459 "arguments": { "driver": "qcow2",
3460 "node-name": "node1534",
3461 "file": { "driver": "file",
3462 "filename": "hd1.qcow2" },
3463 "backing": null } }
3464 <- { "return": {} }
3466 -> { "execute": "blockdev-snapshot",
3468 "arguments": { "node": "ide-hd0",
3469 "overlay": "node1534" } }
3470 <- { "return": {} }
3471 change-backing-file (Command)
3473 Change the backing file in the image file metadata. This does not
3474 cause QEMU to reopen the image file to reparse the backing filename (it
3475 may, however, perform a reopen to change permissions from r/o -> r/w ->
3476 r/o, if needed). The new backing file string is written into the image
3477 file metadata, and the QEMU internal strings are updated.
3478 Arguments
3480 image-node-name: string
3481 The name of the block driver state node of the image to modify.
3482 The "device" argument is used to verify "image-node-name" is in
3483 the chain described by "device".
3484 device: string
3486 The device name or node-name of the root node that owns im‐
3487 age-node-name.
3488 backing-file: string
3490 The string to write as the backing file. This string is not
3491 validated, so care should be taken when specifying the string or
3492 the image chain may not be able to be reopened again.
3493 Returns
3495 • Nothing on success
3496 • If "device" does not exist or cannot be determined, DeviceNotFound
3498 Since
3500 2.1
3501 block-commit (Command)
3503 Live commit of data from overlay image nodes into backing nodes - i.e.,
3504 writes data between 'top' and 'base' into 'base'.
3505 If top == base, that is an error. If top has no overlays on top of it,
3507 or if it is in use by a writer, the job will not be completed by it‐
3508 self. The user needs to complete the job with the block-job-complete
3509 command after getting the ready event. (Since 2.0)
3510 If the base image is smaller than top, then the base image will be re‐
3512 sized to be the same size as top. If top is smaller than the base im‐
3513 age, the base will not be truncated. If you want the base image size
3514 to match the size of the smaller top, you can safely truncate it your‐
3515 self once the commit operation successfully completes.
3516 Arguments
3518 job-id: string (optional)
3519 identifier for the newly-created block job. If omitted, the de‐
3520 vice name will be used. (Since 2.7)
3521 device: string
3523 the device name or node-name of a root node
3524 base-node: string (optional)
3526 The node name of the backing image to write data into. If not
3527 specified, this is the deepest backing image. (since: 3.1)
3528 base: string (optional)
3530 Same as base-node, except that it is a file name rather than a
3531 node name. This must be the exact filename string that was used
3532 to open the node; other strings, even if addressing the same
3533 file, are not accepted
3534 top-node: string (optional)
3536 The node name of the backing image within the image chain which
3537 contains the topmost data to be committed down. If not speci‐
3538 fied, this is the active layer. (since: 3.1)
3539 top: string (optional)
3541 Same as top-node, except that it is a file name rather than a
3542 node name. This must be the exact filename string that was used
3543 to open the node; other strings, even if addressing the same
3544 file, are not accepted
3545 backing-file: string (optional)
3547 The backing file string to write into the overlay image of
3548 'top'. If 'top' does not have an overlay image, or if 'top' is
3549 in use by a writer, specifying a backing file string is an er‐
3550 ror.
3551 This filename is not validated. If a pathname string is such
3553 that it cannot be resolved by QEMU, that means that subsequent
3554 QMP or HMP commands must use node-names for the image in ques‐
3555 tion, as filename lookup methods will fail.
3556 If not specified, QEMU will automatically determine the backing
3558 file string to use, or error out if there is no obvious choice.
3559 Care should be taken when specifying the string, to specify a
3560 valid filename or protocol. (Since 2.1)
3561 speed: int (optional)
3563 the maximum speed, in bytes per second
3564 on-error: BlockdevOnError (optional)
3566 the action to take on an error. 'ignore' means that the request
3567 should be retried. (default: report; Since: 5.0)
3568 filter-node-name: string (optional)
3570 the node name that should be assigned to the filter driver that
3571 the commit job inserts into the graph above top. If this option
3572 is not given, a node name is autogenerated. (Since: 2.9)
3573 auto-finalize: boolean (optional)
3575 When false, this job will wait in a PENDING state after it has
3576 finished its work, waiting for block-job-finalize before making
3577 any block graph changes. When true, this job will automatically
3578 perform its abort or commit actions. Defaults to true. (Since
3579 3.1)
3580 auto-dismiss: boolean (optional)
3582 When false, this job will wait in a CONCLUDED state after it has
3583 completely ceased all work, and awaits block-job-dismiss. When
3584 true, this job will automatically disappear from the query list
3585 without user intervention. Defaults to true. (Since 3.1)
3586 Features
3588 deprecated
3589 Members base and top are deprecated. Use base-node and top-node
3590 instead.
3591 Returns
3593 • Nothing on success
3594 • If device does not exist, DeviceNotFound
3596 • Any other error returns a GenericError.
3598 Since
3600 1.3
3601 Example
3603 -> { "execute": "block-commit",
3604 "arguments": { "device": "virtio0",
3605 "top": "/tmp/snap1.qcow2" } }
3606 <- { "return": {} }
3607 drive-backup (Command)
3609 Start a point-in-time copy of a block device to a new destination. The
3610 status of ongoing drive-backup operations can be checked with
3611 query-block-jobs where the BlockJobInfo.type field has the value
3612 'backup'. The operation can be stopped before it has completed using
3613 the block-job-cancel command.
3614 Arguments
3616 The members of DriveBackup
3617 Features
3619 deprecated
3620 This command is deprecated. Use blockdev-backup instead.
3621 Returns
3623 • nothing on success
3624 • If device is not a valid block device, GenericError
3626 Since
3628 1.6
3629 Example
3631 -> { "execute": "drive-backup",
3632 "arguments": { "device": "drive0",
3633 "sync": "full",
3634 "target": "backup.img" } }
3635 <- { "return": {} }
3636 blockdev-backup (Command)
3638 Start a point-in-time copy of a block device to a new destination. The
3639 status of ongoing blockdev-backup operations can be checked with
3640 query-block-jobs where the BlockJobInfo.type field has the value
3641 'backup'. The operation can be stopped before it has completed using
3642 the block-job-cancel command.
3643 Arguments
3645 The members of BlockdevBackup
3646 Returns
3648 • nothing on success
3649 • If device is not a valid block device, DeviceNotFound
3651 Since
3653 2.3
3654 Example
3656 -> { "execute": "blockdev-backup",
3657 "arguments": { "device": "src-id",
3658 "sync": "full",
3659 "target": "tgt-id" } }
3660 <- { "return": {} }
3661 query-named-block-nodes (Command)
3663 Get the named block driver list
3664 Arguments
3666 flat: boolean (optional)
3667 Omit the nested data about backing image ("backing-image" key)
3668 if true. Default is false (Since 5.0)
3669 Returns
3671 the list of BlockDeviceInfo
3672 Since
3674 2.0
3675 Example
3677 -> { "execute": "query-named-block-nodes" }
3678 <- { "return": [ { "ro":false,
3679 "drv":"qcow2",
3680 "encrypted":false,
3681 "file":"disks/test.qcow2",
3682 "node-name": "my-node",
3683 "backing_file_depth":1,
3684 "bps":1000000,
3685 "bps_rd":0,
3686 "bps_wr":0,
3687 "iops":1000000,
3688 "iops_rd":0,
3689 "iops_wr":0,
3690 "bps_max": 8000000,
3691 "bps_rd_max": 0,
3692 "bps_wr_max": 0,
3693 "iops_max": 0,
3694 "iops_rd_max": 0,
3695 "iops_wr_max": 0,
3696 "iops_size": 0,
3697 "write_threshold": 0,
3698 "image":{
3699 "filename":"disks/test.qcow2",
3700 "format":"qcow2",
3701 "virtual-size":2048000,
3702 "backing_file":"base.qcow2",
3703 "full-backing-filename":"disks/base.qcow2",
3704 "backing-filename-format":"qcow2",
3705 "snapshots":[
3706 {
3707 "id": "1",
3708 "name": "snapshot1",
3709 "vm-state-size": 0,
3710 "date-sec": 10000200,
3711 "date-nsec": 12,
3712 "vm-clock-sec": 206,
3713 "vm-clock-nsec": 30
3714 }
3715 ],
3716 "backing-image":{
3717 "filename":"disks/base.qcow2",
3718 "format":"qcow2",
3719 "virtual-size":2048000
3720 }
3721 } } ] }
3722 XDbgBlockGraphNodeType (Enum)
3724 Values
3725 block-backend
3726 corresponds to BlockBackend
3727 block-job
3729 corresponds to BlockJob
3730 block-driver
3732 corresponds to BlockDriverState
3733 Since
3735 4.0
3736 XDbgBlockGraphNode (Object)
3738 Members
3739 id: int
3740 Block graph node identifier. This id is generated only for x-de‐
3741 bug-query-block-graph and does not relate to any other identi‐
3742 fiers in Qemu.
3743 type: XDbgBlockGraphNodeType
3745 Type of graph node. Can be one of block-backend, block-job or
3746 block-driver-state.
3747 name: string
3749 Human readable name of the node. Corresponds to node-name for
3750 block-driver-state nodes; is not guaranteed to be unique in the
3751 whole graph (with block-jobs and block-backends).
3752 Since
3754 4.0
3755 BlockPermission (Enum)
3757 Enum of base block permissions.
3758 Values
3760 consistent-read
3761 A user that has the "permission" of consistent reads is guaran‐
3762 teed that their view of the contents of the block device is com‐
3763 plete and self-consistent, representing the contents of a disk
3764 at a specific point. For most block devices (including their
3765 backing files) this is true, but the property cannot be main‐
3766 tained in a few situations like for intermediate nodes of a com‐
3767 mit block job.
3768 write This permission is required to change the visible disk contents.
3770 write-unchanged
3772 This permission (which is weaker than BLK_PERM_WRITE) is both
3773 enough and required for writes to the block node when the caller
3774 promises that the visible disk content doesn't change. As the
3775 BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
3776 cient to perform an unchanging write.
3777 resize This permission is required to change the size of a block node.
3779 graph-mod
3781 This permission is required to change the node that this
3782 BdrvChild points to.
3783 Since
3785 4.0
3786 XDbgBlockGraphEdge (Object)
3788 Block Graph edge description for x-debug-query-block-graph.
3789 Members
3791 parent: int
3792 parent id
3793 child: int
3795 child id
3796 name: string
3798 name of the relation (examples are 'file' and 'backing')
3799 perm: array of BlockPermission
3801 granted permissions for the parent operating on the child
3802 shared-perm: array of BlockPermission
3804 permissions that can still be granted to other users of the
3805 child while it is still attached to this parent
3806 Since
3808 4.0
3809 XDbgBlockGraph (Object)
3811 Block Graph - list of nodes and list of edges.
3812 Members
3814 nodes: array of XDbgBlockGraphNode
3815 Not documented
3816 edges: array of XDbgBlockGraphEdge
3818 Not documented
3819 Since
3821 4.0
3822 x-debug-query-block-graph (Command)
3824 Get the block graph.
3825 Features
3827 unstable
3828 This command is meant for debugging.
3829 Since
3831 4.0
3832 drive-mirror (Command)
3834 Start mirroring a block device's writes to a new destination. target
3835 specifies the target of the new image. If the file exists, or if it is
3836 a device, it will be used as the new destination for writes. If it does
3837 not exist, a new file will be created. format specifies the format of
3838 the mirror image, default is to probe if mode='existing', else the for‐
3839 mat of the source.
3840 Arguments
3842 The members of DriveMirror
3843 Returns
3845 • nothing on success
3846 • If device is not a valid block device, GenericError
3848 Since
3850 1.3
3851 Example
3853 -> { "execute": "drive-mirror",
3854 "arguments": { "device": "ide-hd0",
3855 "target": "/some/place/my-image",
3856 "sync": "full",
3857 "format": "qcow2" } }
3858 <- { "return": {} }
3859 DriveMirror (Object)
3861 A set of parameters describing drive mirror setup.
3862 Members
3864 job-id: string (optional)
3865 identifier for the newly-created block job. If omitted, the de‐
3866 vice name will be used. (Since 2.7)
3867 device: string
3869 the device name or node-name of a root node whose writes should
3870 be mirrored.
3871 target: string
3873 the target of the new image. If the file exists, or if it is a
3874 device, the existing file/device will be used as the new desti‐
3875 nation. If it does not exist, a new file will be created.
3876 format: string (optional)
3878 the format of the new destination, default is to probe if mode
3879 is 'existing', else the format of the source
3880 node-name: string (optional)
3882 the new block driver state node name in the graph (Since 2.1)
3883 replaces: string (optional)
3885 with sync=full graph node name to be replaced by the new image
3886 when a whole image copy is done. This can be used to repair bro‐
3887 ken Quorum files. By default, device is replaced, although im‐
3888 plicitly created filters on it are kept. (Since 2.1)
3889 mode: NewImageMode (optional)
3891 whether and how QEMU should create a new image, default is 'ab‐
3892 solute-paths'.
3893 speed: int (optional)
3895 the maximum speed, in bytes per second
3896 sync: MirrorSyncMode
3898 what parts of the disk image should be copied to the destination
3899 (all the disk, only the sectors allocated in the topmost image,
3900 or only new I/O).
3901 granularity: int (optional)
3903 granularity of the dirty bitmap, default is 64K if the image
3904 format doesn't have clusters, 4K if the clusters are smaller
3905 than that, else the cluster size. Must be a power of 2 between
3906 512 and 64M (since 1.4).
3907 buf-size: int (optional)
3909 maximum amount of data in flight from source to target (since
3910 1.4).
3911 on-source-error: BlockdevOnError (optional)
3913 the action to take on an error on the source, default 'report'.
3914 'stop' and 'enospc' can only be used if the block device sup‐
3915 ports io-status (see BlockInfo).
3916 on-target-error: BlockdevOnError (optional)
3918 the action to take on an error on the target, default 'report'
3919 (no limitations, since this applies to a different block device
3920 than device).
3921 unmap: boolean (optional)
3923 Whether to try to unmap target sectors where source has only
3924 zero. If true, and target unallocated sectors will read as zero,
3925 target image sectors will be unmapped; otherwise, zeroes will be
3926 written. Both will result in identical contents. Default is
3927 true. (Since 2.4)
3928 copy-mode: MirrorCopyMode (optional)
3930 when to copy data to the destination; defaults to 'background'
3931 (Since: 3.0)
3932 auto-finalize: boolean (optional)
3934 When false, this job will wait in a PENDING state after it has
3935 finished its work, waiting for block-job-finalize before making
3936 any block graph changes. When true, this job will automatically
3937 perform its abort or commit actions. Defaults to true. (Since
3938 3.1)
3939 auto-dismiss: boolean (optional)
3941 When false, this job will wait in a CONCLUDED state after it has
3942 completely ceased all work, and awaits block-job-dismiss. When
3943 true, this job will automatically disappear from the query list
3944 without user intervention. Defaults to true. (Since 3.1)
3945 Since
3947 1.3
3948 BlockDirtyBitmap (Object)
3950 Members
3951 node: string
3952 name of device/node which the bitmap is tracking
3953 name: string
3955 name of the dirty bitmap
3956 Since
3958 2.4
3959 BlockDirtyBitmapAdd (Object)
3961 Members
3962 node: string
3963 name of device/node which the bitmap is tracking
3964 name: string
3966 name of the dirty bitmap (must be less than 1024 bytes)
3967 granularity: int (optional)
3969 the bitmap granularity, default is 64k for block-dirty-bit‐
3970 map-add
3971 persistent: boolean (optional)
3973 the bitmap is persistent, i.e. it will be saved to the corre‐
3974 sponding block device image file on its close. For now only
3975 Qcow2 disks support persistent bitmaps. Default is false for
3976 block-dirty-bitmap-add. (Since: 2.10)
3977 disabled: boolean (optional)
3979 the bitmap is created in the disabled state, which means that it
3980 will not track drive changes. The bitmap may be enabled with
3981 block-dirty-bitmap-enable. Default is false. (Since: 4.0)
3982 Since
3984 2.4
3985 BlockDirtyBitmapMergeSource (Alternate)
3987 Members
3988 local: string
3989 name of the bitmap, attached to the same node as target bitmap.
3990 external: BlockDirtyBitmap
3992 bitmap with specified node
3993 Since
3995 4.1
3996 BlockDirtyBitmapMerge (Object)
3998 Members
3999 node: string
4000 name of device/node which the target bitmap is tracking
4001 target: string
4003 name of the destination dirty bitmap
4004 bitmaps: array of BlockDirtyBitmapMergeSource
4006 name(s) of the source dirty bitmap(s) at node and/or fully spec‐
4007 ified BlockDirtyBitmap elements. The latter are supported since
4008 4.1.
4009 Since
4011 4.0
4012 block-dirty-bitmap-add (Command)
4014 Create a dirty bitmap with a name on the node, and start tracking the
4015 writes.
4016 Returns
4018 • nothing on success
4019 • If node is not a valid block device or node, DeviceNotFound
4021 • If name is already taken, GenericError with an explanation
4023 Since
4025 2.4
4026 Example
4028 -> { "execute": "block-dirty-bitmap-add",
4029 "arguments": { "node": "drive0", "name": "bitmap0" } }
4030 <- { "return": {} }
4031 block-dirty-bitmap-remove (Command)
4033 Stop write tracking and remove the dirty bitmap that was created with
4034 block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
4035 storage too.
4036 Returns
4038 • nothing on success
4039 • If node is not a valid block device or node, DeviceNotFound
4041 • If name is not found, GenericError with an explanation
4043 • if name is frozen by an operation, GenericError
4045 Since
4047 2.4
4048 Example
4050 -> { "execute": "block-dirty-bitmap-remove",
4051 "arguments": { "node": "drive0", "name": "bitmap0" } }
4052 <- { "return": {} }
4053 block-dirty-bitmap-clear (Command)
4055 Clear (reset) a dirty bitmap on the device, so that an incremental
4056 backup from this point in time forward will only backup clusters modi‐
4057 fied after this clear operation.
4058 Returns
4060 • nothing on success
4061 • If node is not a valid block device, DeviceNotFound
4063 • If name is not found, GenericError with an explanation
4065 Since
4067 2.4
4068 Example
4070 -> { "execute": "block-dirty-bitmap-clear",
4071 "arguments": { "node": "drive0", "name": "bitmap0" } }
4072 <- { "return": {} }
4073 block-dirty-bitmap-enable (Command)
4075 Enables a dirty bitmap so that it will begin tracking disk changes.
4076 Returns
4078 • nothing on success
4079 • If node is not a valid block device, DeviceNotFound
4081 • If name is not found, GenericError with an explanation
4083 Since
4085 4.0
4086 Example
4088 -> { "execute": "block-dirty-bitmap-enable",
4089 "arguments": { "node": "drive0", "name": "bitmap0" } }
4090 <- { "return": {} }
4091 block-dirty-bitmap-disable (Command)
4093 Disables a dirty bitmap so that it will stop tracking disk changes.
4094 Returns
4096 • nothing on success
4097 • If node is not a valid block device, DeviceNotFound
4099 • If name is not found, GenericError with an explanation
4101 Since
4103 4.0
4104 Example
4106 -> { "execute": "block-dirty-bitmap-disable",
4107 "arguments": { "node": "drive0", "name": "bitmap0" } }
4108 <- { "return": {} }
4109 block-dirty-bitmap-merge (Command)
4111 Merge dirty bitmaps listed in bitmaps to the target dirty bitmap.
4112 Dirty bitmaps in bitmaps will be unchanged, except if it also appears
4113 as the target bitmap. Any bits already set in target will still be set
4114 after the merge, i.e., this operation does not clear the target. On
4115 error, target is unchanged.
4116 The resulting bitmap will count as dirty any clusters that were dirty
4118 in any of the source bitmaps. This can be used to achieve backup check‐
4119 points, or in simpler usages, to copy bitmaps.
4120 Returns
4122 • nothing on success
4123 • If node is not a valid block device, DeviceNotFound
4125 • If any bitmap in bitmaps or target is not found, GenericError
4127 • If any of the bitmaps have different sizes or granularities, Gener‐
4129 icError
4130 Since
4132 4.0
4133 Example
4135 -> { "execute": "block-dirty-bitmap-merge",
4136 "arguments": { "node": "drive0", "target": "bitmap0",
4137 "bitmaps": ["bitmap1"] } }
4138 <- { "return": {} }
4139 BlockDirtyBitmapSha256 (Object)
4141 SHA256 hash of dirty bitmap data
4142 Members
4144 sha256: string
4145 ASCII representation of SHA256 bitmap hash
4146 Since
4148 2.10
4149 x-debug-block-dirty-bitmap-sha256 (Command)
4151 Get bitmap SHA256.
4152 Features
4154 unstable
4155 This command is meant for debugging.
4156 Returns
4158 • BlockDirtyBitmapSha256 on success
4159 • If node is not a valid block device, DeviceNotFound
4161 • If name is not found or if hashing has failed, GenericError with an
4163 explanation
4164 Since
4166 2.10
4167 blockdev-mirror (Command)
4169 Start mirroring a block device's writes to a new destination.
4170 Arguments
4172 job-id: string (optional)
4173 identifier for the newly-created block job. If omitted, the de‐
4174 vice name will be used. (Since 2.7)
4175 device: string
4177 The device name or node-name of a root node whose writes should
4178 be mirrored.
4179 target: string
4181 the id or node-name of the block device to mirror to. This
4182 mustn't be attached to guest.
4183 replaces: string (optional)
4185 with sync=full graph node name to be replaced by the new image
4186 when a whole image copy is done. This can be used to repair bro‐
4187 ken Quorum files. By default, device is replaced, although im‐
4188 plicitly created filters on it are kept.
4189 speed: int (optional)
4191 the maximum speed, in bytes per second
4192 sync: MirrorSyncMode
4194 what parts of the disk image should be copied to the destination
4195 (all the disk, only the sectors allocated in the topmost image,
4196 or only new I/O).
4197 granularity: int (optional)
4199 granularity of the dirty bitmap, default is 64K if the image
4200 format doesn't have clusters, 4K if the clusters are smaller
4201 than that, else the cluster size. Must be a power of 2 between
4202 512 and 64M
4203 buf-size: int (optional)
4205 maximum amount of data in flight from source to target
4206 on-source-error: BlockdevOnError (optional)
4208 the action to take on an error on the source, default 'report'.
4209 'stop' and 'enospc' can only be used if the block device sup‐
4210 ports io-status (see BlockInfo).
4211 on-target-error: BlockdevOnError (optional)
4213 the action to take on an error on the target, default 'report'
4214 (no limitations, since this applies to a different block device
4215 than device).
4216 filter-node-name: string (optional)
4218 the node name that should be assigned to the filter driver that
4219 the mirror job inserts into the graph above device. If this op‐
4220 tion is not given, a node name is autogenerated. (Since: 2.9)
4221 copy-mode: MirrorCopyMode (optional)
4223 when to copy data to the destination; defaults to 'background'
4224 (Since: 3.0)
4225 auto-finalize: boolean (optional)
4227 When false, this job will wait in a PENDING state after it has
4228 finished its work, waiting for block-job-finalize before making
4229 any block graph changes. When true, this job will automatically
4230 perform its abort or commit actions. Defaults to true. (Since
4231 3.1)
4232 auto-dismiss: boolean (optional)
4234 When false, this job will wait in a CONCLUDED state after it has
4235 completely ceased all work, and awaits block-job-dismiss. When
4236 true, this job will automatically disappear from the query list
4237 without user intervention. Defaults to true. (Since 3.1)
4238 Returns
4240 nothing on success.
4241 Since
4243 2.6
4244 Example
4246 -> { "execute": "blockdev-mirror",
4247 "arguments": { "device": "ide-hd0",
4248 "target": "target0",
4249 "sync": "full" } }
4250 <- { "return": {} }
4251 BlockIOThrottle (Object)
4253 A set of parameters describing block throttling.
4254 Members
4256 device: string (optional)
4257 Block device name
4258 id: string (optional)
4260 The name or QOM path of the guest device (since: 2.8)
4261 bps: int
4263 total throughput limit in bytes per second
4264 bps_rd: int
4266 read throughput limit in bytes per second
4267 bps_wr: int
4269 write throughput limit in bytes per second
4270 iops: int
4272 total I/O operations per second
4273 iops_rd: int
4275 read I/O operations per second
4276 iops_wr: int
4278 write I/O operations per second
4279 bps_max: int (optional)
4281 total throughput limit during bursts, in bytes (Since 1.7)
4282 bps_rd_max: int (optional)
4284 read throughput limit during bursts, in bytes (Since 1.7)
4285 bps_wr_max: int (optional)
4287 write throughput limit during bursts, in bytes (Since 1.7)
4288 iops_max: int (optional)
4290 total I/O operations per second during bursts, in bytes (Since
4291 1.7)
4292 iops_rd_max: int (optional)
4294 read I/O operations per second during bursts, in bytes (Since
4295 1.7)
4296 iops_wr_max: int (optional)
4298 write I/O operations per second during bursts, in bytes (Since
4299 1.7)
4300 bps_max_length: int (optional)
4302 maximum length of the bps_max burst period, in seconds. It must
4303 only be set if bps_max is set as well. Defaults to 1. (Since
4304 2.6)
4305 bps_rd_max_length: int (optional)
4307 maximum length of the bps_rd_max burst period, in seconds. It
4308 must only be set if bps_rd_max is set as well. Defaults to 1.
4309 (Since 2.6)
4310 bps_wr_max_length: int (optional)
4312 maximum length of the bps_wr_max burst period, in seconds. It
4313 must only be set if bps_wr_max is set as well. Defaults to 1.
4314 (Since 2.6)
4315 iops_max_length: int (optional)
4317 maximum length of the iops burst period, in seconds. It must
4318 only be set if iops_max is set as well. Defaults to 1. (Since
4319 2.6)
4320 iops_rd_max_length: int (optional)
4322 maximum length of the iops_rd_max burst period, in seconds. It
4323 must only be set if iops_rd_max is set as well. Defaults to 1.
4324 (Since 2.6)
4325 iops_wr_max_length: int (optional)
4327 maximum length of the iops_wr_max burst period, in seconds. It
4328 must only be set if iops_wr_max is set as well. Defaults to 1.
4329 (Since 2.6)
4330 iops_size: int (optional)
4332 an I/O size in bytes (Since 1.7)
4333 group: string (optional)
4335 throttle group name (Since 2.4)
4336 Features
4338 deprecated
4339 Member device is deprecated. Use id instead.
4340 Since
4342 1.1
4343 ThrottleLimits (Object)
4345 Limit parameters for throttling. Since some limit combinations are il‐
4346 legal, limits should always be set in one transaction. All fields are
4347 optional. When setting limits, if a field is missing the current value
4348 is not changed.
4349 Members
4351 iops-total: int (optional)
4352 limit total I/O operations per second
4353 iops-total-max: int (optional)
4355 I/O operations burst
4356 iops-total-max-length: int (optional)
4358 length of the iops-total-max burst period, in seconds It must
4359 only be set if iops-total-max is set as well.
4360 iops-read: int (optional)
4362 limit read operations per second
4363 iops-read-max: int (optional)
4365 I/O operations read burst
4366 iops-read-max-length: int (optional)
4368 length of the iops-read-max burst period, in seconds It must
4369 only be set if iops-read-max is set as well.
4370 iops-write: int (optional)
4372 limit write operations per second
4373 iops-write-max: int (optional)
4375 I/O operations write burst
4376 iops-write-max-length: int (optional)
4378 length of the iops-write-max burst period, in seconds It must
4379 only be set if iops-write-max is set as well.
4380 bps-total: int (optional)
4382 limit total bytes per second
4383 bps-total-max: int (optional)
4385 total bytes burst
4386 bps-total-max-length: int (optional)
4388 length of the bps-total-max burst period, in seconds. It must
4389 only be set if bps-total-max is set as well.
4390 bps-read: int (optional)
4392 limit read bytes per second
4393 bps-read-max: int (optional)
4395 total bytes read burst
4396 bps-read-max-length: int (optional)
4398 length of the bps-read-max burst period, in seconds It must only
4399 be set if bps-read-max is set as well.
4400 bps-write: int (optional)
4402 limit write bytes per second
4403 bps-write-max: int (optional)
4405 total bytes write burst
4406 bps-write-max-length: int (optional)
4408 length of the bps-write-max burst period, in seconds It must
4409 only be set if bps-write-max is set as well.
4410 iops-size: int (optional)
4412 when limiting by iops max size of an I/O in bytes
4413 Since
4415 2.11
4416 ThrottleGroupProperties (Object)
4418 Properties for throttle-group objects.
4419 Members
4421 limits: ThrottleLimits (optional)
4422 limits to apply for this throttle group
4423 x-iops-total: int (optional)
4425 Not documented
4426 x-iops-total-max: int (optional)
4428 Not documented
4429 x-iops-total-max-length: int (optional)
4431 Not documented
4432 x-iops-read: int (optional)
4434 Not documented
4435 x-iops-read-max: int (optional)
4437 Not documented
4438 x-iops-read-max-length: int (optional)
4440 Not documented
4441 x-iops-write: int (optional)
4443 Not documented
4444 x-iops-write-max: int (optional)
4446 Not documented
4447 x-iops-write-max-length: int (optional)
4449 Not documented
4450 x-bps-total: int (optional)
4452 Not documented
4453 x-bps-total-max: int (optional)
4455 Not documented
4456 x-bps-total-max-length: int (optional)
4458 Not documented
4459 x-bps-read: int (optional)
4461 Not documented
4462 x-bps-read-max: int (optional)
4464 Not documented
4465 x-bps-read-max-length: int (optional)
4467 Not documented
4468 x-bps-write: int (optional)
4470 Not documented
4471 x-bps-write-max: int (optional)
4473 Not documented
4474 x-bps-write-max-length: int (optional)
4476 Not documented
4477 x-iops-size: int (optional)
4479 Not documented
4480 Features
4482 unstable
4483 All members starting with x- are aliases for the same key with‐
4484 out x- in the limits object. This is not a stable interface and
4485 may be removed or changed incompatibly in the future. Use lim‐
4486 its for a supported stable interface.
4487 Since
4489 2.11
4490 block-stream (Command)
4492 Copy data from a backing file into a block device.
4493 The block streaming operation is performed in the background until the
4495 entire backing file has been copied. This command returns immediately
4496 once streaming has started. The status of ongoing block streaming op‐
4497 erations can be checked with query-block-jobs. The operation can be
4498 stopped before it has completed using the block-job-cancel command.
4499 The node that receives the data is called the top image, can be located
4501 in any part of the chain (but always above the base image; see below)
4502 and can be specified using its device or node name. Earlier qemu ver‐
4503 sions only allowed 'device' to name the top level node; presence of the
4504 'base-node' parameter during introspection can be used as a witness of
4505 the enhanced semantics of 'device'.
4506 If a base file is specified then sectors are not copied from that base
4508 file and its backing chain. This can be used to stream a subset of the
4509 backing file chain instead of flattening the entire image. When
4510 streaming completes the image file will have the base file as its back‐
4511 ing file, unless that node was changed while the job was running. In
4512 that case, base's parent's backing (or filtered, whichever exists)
4513 child (i.e., base at the beginning of the job) will be the new backing
4514 file.
4515 On successful completion the image file is updated to drop the backing
4517 file and the BLOCK_JOB_COMPLETED event is emitted.
4518 In case device is a filter node, block-stream modifies the first
4520 non-filter overlay node below it to point to the new backing node in‐
4521 stead of modifying device itself.
4522 Arguments
4524 job-id: string (optional)
4525 identifier for the newly-created block job. If omitted, the de‐
4526 vice name will be used. (Since 2.7)
4527 device: string
4529 the device or node name of the top image
4530 base: string (optional)
4532 the common backing file name. It cannot be set if base-node or
4533 bottom is also set.
4534 base-node: string (optional)
4536 the node name of the backing file. It cannot be set if base or
4537 bottom is also set. (Since 2.8)
4538 bottom: string (optional)
4540 the last node in the chain that should be streamed into top. It
4541 cannot be set if base or base-node is also set. It cannot be
4542 filter node. (Since 6.0)
4543 backing-file: string (optional)
4545 The backing file string to write into the top image. This file‐
4546 name is not validated.
4547 If a pathname string is such that it cannot be resolved by QEMU,
4549 that means that subsequent QMP or HMP commands must use
4550 node-names for the image in question, as filename lookup methods
4551 will fail.
4552 If not specified, QEMU will automatically determine the backing
4554 file string to use, or error out if there is no obvious choice.
4555 Care should be taken when specifying the string, to specify a
4556 valid filename or protocol. (Since 2.1)
4557 speed: int (optional)
4559 the maximum speed, in bytes per second
4560 on-error: BlockdevOnError (optional)
4562 the action to take on an error (default report). 'stop' and
4563 'enospc' can only be used if the block device supports io-status
4564 (see BlockInfo). Since 1.3.
4565 filter-node-name: string (optional)
4567 the node name that should be assigned to the filter driver that
4568 the stream job inserts into the graph above device. If this op‐
4569 tion is not given, a node name is autogenerated. (Since: 6.0)
4570 auto-finalize: boolean (optional)
4572 When false, this job will wait in a PENDING state after it has
4573 finished its work, waiting for block-job-finalize before making
4574 any block graph changes. When true, this job will automatically
4575 perform its abort or commit actions. Defaults to true. (Since
4576 3.1)
4577 auto-dismiss: boolean (optional)
4579 When false, this job will wait in a CONCLUDED state after it has
4580 completely ceased all work, and awaits block-job-dismiss. When
4581 true, this job will automatically disappear from the query list
4582 without user intervention. Defaults to true. (Since 3.1)
4583 Returns
4585 • Nothing on success.
4586 • If device does not exist, DeviceNotFound.
4588 Since
4590 1.1
4591 Example
4593 -> { "execute": "block-stream",
4594 "arguments": { "device": "virtio0",
4595 "base": "/tmp/master.qcow2" } }
4596 <- { "return": {} }
4597 block-job-set-speed (Command)
4599 Set maximum speed for a background block operation.
4600 This command can only be issued when there is an active block job.
4602 Throttling can be disabled by setting the speed to 0.
4604 Arguments
4606 device: string
4607 The job identifier. This used to be a device name (hence the
4608 name of the parameter), but since QEMU 2.7 it can have other
4609 values.
4610 speed: int
4612 the maximum speed, in bytes per second, or 0 for unlimited. De‐
4613 faults to 0.
4614 Returns
4616 • Nothing on success
4617 • If no background operation is active on this device, DeviceNotActive
4619 Since
4621 1.1
4622 block-job-cancel (Command)
4624 Stop an active background block operation.
4625 This command returns immediately after marking the active background
4627 block operation for cancellation. It is an error to call this command
4628 if no operation is in progress.
4629 The operation will cancel as soon as possible and then emit the
4631 BLOCK_JOB_CANCELLED event. Before that happens the job is still visi‐
4632 ble when enumerated using query-block-jobs.
4633 Note that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
4635 dicated (via the event BLOCK_JOB_READY) that the source and destination
4636 are synchronized, then the event triggered by this command changes to
4637 BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
4638 destination now has a point-in-time copy tied to the time of the can‐
4639 cellation.
4640 For streaming, the image file retains its backing file unless the
4642 streaming operation happens to complete just as it is being cancelled.
4643 A new streaming operation can be started at a later time to finish
4644 copying all data from the backing file.
4645 Arguments
4647 device: string
4648 The job identifier. This used to be a device name (hence the
4649 name of the parameter), but since QEMU 2.7 it can have other
4650 values.
4651 force: boolean (optional)
4653 If true, and the job has already emitted the event
4654 BLOCK_JOB_READY, abandon the job immediately (even if it is
4655 paused) instead of waiting for the destination to complete its
4656 final synchronization (since 1.3)
4657 Returns
4659 • Nothing on success
4660 • If no background operation is active on this device, DeviceNotActive
4662 Since
4664 1.1
4665 block-job-pause (Command)
4667 Pause an active background block operation.
4668 This command returns immediately after marking the active background
4670 block operation for pausing. It is an error to call this command if no
4671 operation is in progress or if the job is already paused.
4672 The operation will pause as soon as possible. No event is emitted when
4674 the operation is actually paused. Cancelling a paused job automati‐
4675 cally resumes it.
4676 Arguments
4678 device: string
4679 The job identifier. This used to be a device name (hence the
4680 name of the parameter), but since QEMU 2.7 it can have other
4681 values.
4682 Returns
4684 • Nothing on success
4685 • If no background operation is active on this device, DeviceNotActive
4687 Since
4689 1.3
4690 block-job-resume (Command)
4692 Resume an active background block operation.
4693 This command returns immediately after resuming a paused background
4695 block operation. It is an error to call this command if no operation
4696 is in progress or if the job is not paused.
4697 This command also clears the error status of the job.
4699 Arguments
4701 device: string
4702 The job identifier. This used to be a device name (hence the
4703 name of the parameter), but since QEMU 2.7 it can have other
4704 values.
4705 Returns
4707 • Nothing on success
4708 • If no background operation is active on this device, DeviceNotActive
4710 Since
4712 1.3
4713 block-job-complete (Command)
4715 Manually trigger completion of an active background block operation.
4716 This is supported for drive mirroring, where it also switches the de‐
4717 vice to write to the target path only. The ability to complete is sig‐
4718 naled with a BLOCK_JOB_READY event.
4719 This command completes an active background block operation syn‐
4721 chronously. The ordering of this command's return with the
4722 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
4723 occurs during the processing of this command: 1) the command itself
4724 will fail; 2) the error will be processed according to the rerror/wer‐
4725 ror arguments that were specified when starting the operation.
4726 A cancelled or paused job cannot be completed.
4728 Arguments
4730 device: string
4731 The job identifier. This used to be a device name (hence the
4732 name of the parameter), but since QEMU 2.7 it can have other
4733 values.
4734 Returns
4736 • Nothing on success
4737 • If no background operation is active on this device, DeviceNotActive
4739 Since
4741 1.3
4742 block-job-dismiss (Command)
4744 For jobs that have already concluded, remove them from the
4745 block-job-query list. This command only needs to be run for jobs which
4746 were started with QEMU 2.12+ job lifetime management semantics.
4747 This command will refuse to operate on any job that has not yet reached
4749 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
4750 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
4751 still need to be used as appropriate.
4752 Arguments
4754 id: string
4755 The job identifier.
4756 Returns
4758 Nothing on success
4759 Since
4761 2.12
4762 block-job-finalize (Command)
4764 Once a job that has manual=true reaches the pending state, it can be
4765 instructed to finalize any graph changes and do any necessary cleanup
4766 via this command. For jobs in a transaction, instructing one job to
4767 finalize will force ALL jobs in the transaction to finalize, so it is
4768 only necessary to instruct a single member job to finalize.
4769 Arguments
4771 id: string
4772 The job identifier.
4773 Returns
4775 Nothing on success
4776 Since
4778 2.12
4779 BlockdevDiscardOptions (Enum)
4781 Determines how to handle discard requests.
4782 Values
4784 ignore Ignore the request
4785 unmap Forward as an unmap request
4787 Since
4789 2.9
4790 BlockdevDetectZeroesOptions (Enum)
4792 Describes the operation mode for the automatic conversion of plain zero
4793 writes by the OS to driver specific optimized zero write commands.
4794 Values
4796 off Disabled (default)
4797 on Enabled
4799 unmap Enabled and even try to unmap blocks if possible. This requires
4801 also that BlockdevDiscardOptions is set to unmap for this de‐
4802 vice.
4803 Since
4805 2.1
4806 BlockdevAioOptions (Enum)
4808 Selects the AIO backend to handle I/O requests
4809 Values
4811 threads
4812 Use qemu's thread pool
4813 native Use native AIO backend (only Linux and Windows)
4815 io_uring (If: CONFIG_LINUX_IO_URING)
4817 Use linux io_uring (since 5.0)
4818 Since
4820 2.9
4821 BlockdevCacheOptions (Object)
4823 Includes cache-related options for block devices
4824 Members
4826 direct: boolean (optional)
4827 enables use of O_DIRECT (bypass the host page cache; default:
4828 false)
4829 no-flush: boolean (optional)
4831 ignore any flush requests for the device (default: false)
4832 Since
4834 2.9
4835 BlockdevDriver (Enum)
4837 Drivers that are supported in block device operations.
4838 Values
4840 throttle
4841 Since 2.11
4842 nvme Since 2.12
4844 copy-on-read
4846 Since 3.0
4847 blklogwrites
4849 Since 3.0
4850 blkreplay
4852 Since 4.2
4853 compress
4855 Since 5.0
4856 copy-before-write
4858 Since 6.2
4859 blkdebug
4861 Not documented
4862 blkverify
4864 Not documented
4865 bochs Not documented
4867 cloop Not documented
4869 dmg Not documented
4871 file Not documented
4873 ftp Not documented
4875 ftps Not documented
4877 gluster
4879 Not documented
4880 host_cdrom (If: HAVE_HOST_BLOCK_DEVICE)
4882 Not documented
4883 host_device (If: HAVE_HOST_BLOCK_DEVICE)
4885 Not documented
4886 http Not documented
4888 https Not documented
4890 iscsi Not documented
4892 luks Not documented
4894 nbd Not documented
4896 nfs Not documented
4898 null-aio
4900 Not documented
4901 null-co
4903 Not documented
4904 parallels
4906 Not documented
4907 preallocate
4909 Not documented
4910 qcow Not documented
4912 qcow2 Not documented
4914 qed Not documented
4916 quorum Not documented
4918 raw Not documented
4920 rbd Not documented
4922 replication (If: CONFIG_REPLICATION)
4924 Not documented
4925 ssh Not documented
4927 vdi Not documented
4929 vhdx Not documented
4931 vmdk Not documented
4933 vpc Not documented
4935 vvfat Not documented
4937 Since
4939 2.9
4940 BlockdevOptionsFile (Object)
4942 Driver specific block device options for the file backend.
4943 Members
4945 filename: string
4946 path to the image file
4947 pr-manager: string (optional)
4949 the id for the object that will handle persistent reservations
4950 for this device (default: none, forward the commands via SG_IO;
4951 since 2.11)
4952 aio: BlockdevAioOptions (optional)
4954 AIO backend (default: threads) (since: 2.8)
4955 aio-max-batch: int (optional)
4957 maximum number of requests to batch together into a single sub‐
4958 mission in the AIO backend. The smallest value between this and
4959 the aio-max-batch value of the IOThread object is chosen. 0
4960 means that the AIO backend will handle it automatically. (de‐
4961 fault: 0, since 6.2)
4962 locking: OnOffAuto (optional)
4964 whether to enable file locking. If set to 'auto', only enable
4965 when Open File Descriptor (OFD) locking API is available (de‐
4966 fault: auto, since 2.10)
4967 drop-cache: boolean (optional) (If: CONFIG_LINUX)
4969 invalidate page cache during live migration. This prevents
4970 stale data on the migration destination with cache.direct=off.
4971 Currently only supported on Linux hosts. (default: on, since:
4972 4.0)
4973 x-check-cache-dropped: boolean (optional)
4975 whether to check that page cache was dropped on live migration.
4976 May cause noticeable delays if the image file is large, do not
4977 use in production. (default: off) (since: 3.0)
4978 Features
4980 dynamic-auto-read-only
4981 If present, enabled auto-read-only means that the driver will
4982 open the image read-only at first, dynamically reopen the image
4983 file read-write when the first writer is attached to the node
4984 and reopen read-only when the last writer is detached. This al‐
4985 lows giving QEMU write permissions only on demand when an opera‐
4986 tion actually needs write access.
4987 unstable
4989 Member x-check-cache-dropped is meant for debugging.
4990 Since
4992 2.9
4993 BlockdevOptionsNull (Object)
4995 Driver specific block device options for the null backend.
4996 Members
4998 size: int (optional)
4999 size of the device in bytes.
5000 latency-ns: int (optional)
5002 emulated latency (in nanoseconds) in processing requests. De‐
5003 fault to zero which completes requests immediately. (Since 2.4)
5004 read-zeroes: boolean (optional)
5006 if true, reads from the device produce zeroes; if false, the
5007 buffer is left unchanged. (default: false; since: 4.1)
5008 Since
5010 2.9
5011 BlockdevOptionsNVMe (Object)
5013 Driver specific block device options for the NVMe backend.
5014 Members
5016 device: string
5017 PCI controller address of the NVMe device in format hhhh:bb:ss.f
5018 (host:bus:slot.function)
5019 namespace: int
5021 namespace number of the device, starting from 1.
5022 Note that the PCI device must have been unbound from any host kernel
5023 driver before instructing QEMU to add the blockdev.
5024 Since
5026 2.12
5027 BlockdevOptionsVVFAT (Object)
5029 Driver specific block device options for the vvfat protocol.
5030 Members
5032 dir: string
5033 directory to be exported as FAT image
5034 fat-type: int (optional)
5036 FAT type: 12, 16 or 32
5037 floppy: boolean (optional)
5039 whether to export a floppy image (true) or partitioned hard disk
5040 (false; default)
5041 label: string (optional)
5043 set the volume label, limited to 11 bytes. FAT16 and FAT32 tra‐
5044 ditionally have some restrictions on labels, which are ignored
5045 by most operating systems. Defaults to "QEMU VVFAT". (since
5046 2.4)
5047 rw: boolean (optional)
5049 whether to allow write operations (default: false)
5050 Since
5052 2.9
5053 BlockdevOptionsGenericFormat (Object)
5055 Driver specific block device options for image format that have no op‐
5056 tion besides their data source.
5057 Members
5059 file: BlockdevRef
5060 reference to or definition of the data source block device
5061 Since
5063 2.9
5064 BlockdevOptionsLUKS (Object)
5066 Driver specific block device options for LUKS.
5067 Members
5069 key-secret: string (optional)
5070 the ID of a QCryptoSecret object providing the decryption key
5071 (since 2.6). Mandatory except when doing a metadata-only probe
5072 of the image.
5073 The members of BlockdevOptionsGenericFormat
5075 Since
5077 2.9
5078 BlockdevOptionsGenericCOWFormat (Object)
5080 Driver specific block device options for image format that have no op‐
5081 tion besides their data source and an optional backing file.
5082 Members
5084 backing: BlockdevRefOrNull (optional)
5085 reference to or definition of the backing file block device,
5086 null disables the backing file entirely. Defaults to the back‐
5087 ing file stored the image file.
5088 The members of BlockdevOptionsGenericFormat
5090 Since
5092 2.9
5093 Qcow2OverlapCheckMode (Enum)
5095 General overlap check modes.
5096 Values
5098 none Do not perform any checks
5099 constant
5101 Perform only checks which can be done in constant time and with‐
5102 out reading anything from disk
5103 cached Perform only checks which can be done without reading anything
5105 from disk
5106 all Perform all available overlap checks
5108 Since
5110 2.9
5111 Qcow2OverlapCheckFlags (Object)
5113 Structure of flags for each metadata structure. Setting a field to
5114 'true' makes qemu guard that structure against unintended overwriting.
5115 The default value is chosen according to the template given.
5116 Members
5118 template: Qcow2OverlapCheckMode (optional)
5119 Specifies a template mode which can be adjusted using the other
5120 flags, defaults to 'cached'
5121 bitmap-directory: boolean (optional)
5123 since 3.0
5124 main-header: boolean (optional)
5126 Not documented
5127 active-l1: boolean (optional)
5129 Not documented
5130 active-l2: boolean (optional)
5132 Not documented
5133 refcount-table: boolean (optional)
5135 Not documented
5136 refcount-block: boolean (optional)
5138 Not documented
5139 snapshot-table: boolean (optional)
5141 Not documented
5142 inactive-l1: boolean (optional)
5144 Not documented
5145 inactive-l2: boolean (optional)
5147 Not documented
5148 Since
5150 2.9
5151 Qcow2OverlapChecks (Alternate)
5153 Specifies which metadata structures should be guarded against unin‐
5154 tended overwriting.
5155 Members
5157 flags: Qcow2OverlapCheckFlags
5158 set of flags for separate specification of each metadata struc‐
5159 ture type
5160 mode: Qcow2OverlapCheckMode
5162 named mode which chooses a specific set of flags
5163 Since
5165 2.9
5166 BlockdevQcowEncryptionFormat (Enum)
5168 Values
5169 aes AES-CBC with plain64 initialization vectors
5170 Since
5172 2.10
5173 BlockdevQcowEncryption (Object)
5175 Members
5176 format: BlockdevQcowEncryptionFormat
5177 Not documented
5178 The members of QCryptoBlockOptionsQCow when format is "aes"
5180 Since
5182 2.10
5183 BlockdevOptionsQcow (Object)
5185 Driver specific block device options for qcow.
5186 Members
5188 encrypt: BlockdevQcowEncryption (optional)
5189 Image decryption options. Mandatory for encrypted images, except
5190 when doing a metadata-only probe of the image.
5191 The members of BlockdevOptionsGenericCOWFormat
5193 Since
5195 2.10
5196 BlockdevQcow2EncryptionFormat (Enum)
5198 Values
5199 aes AES-CBC with plain64 initialization vectors
5200 luks Not documented
5202 Since
5204 2.10
5205 BlockdevQcow2Encryption (Object)
5207 Members
5208 format: BlockdevQcow2EncryptionFormat
5209 Not documented
5210 The members of QCryptoBlockOptionsQCow when format is "aes"
5212 The members of QCryptoBlockOptionsLUKS when format is "luks"
5214 Since
5216 2.10
5217 BlockdevOptionsPreallocate (Object)
5219 Filter driver intended to be inserted between format and protocol node
5220 and do preallocation in protocol node on write.
5221 Members
5223 prealloc-align: int (optional)
5224 on preallocation, align file length to this number, default
5225 1048576 (1M)
5226 prealloc-size: int (optional)
5228 how much to preallocate, default 134217728 (128M)
5229 The members of BlockdevOptionsGenericFormat
5231 Since
5233 6.0
5234 BlockdevOptionsQcow2 (Object)
5236 Driver specific block device options for qcow2.
5237 Members
5239 lazy-refcounts: boolean (optional)
5240 whether to enable the lazy refcounts feature (default is taken
5241 from the image file)
5242 pass-discard-request: boolean (optional)
5244 whether discard requests to the qcow2 device should be forwarded
5245 to the data source
5246 pass-discard-snapshot: boolean (optional)
5248 whether discard requests for the data source should be issued
5249 when a snapshot operation (e.g. deleting a snapshot) frees
5250 clusters in the qcow2 file
5251 pass-discard-other: boolean (optional)
5253 whether discard requests for the data source should be issued on
5254 other occasions where a cluster gets freed
5255 overlap-check: Qcow2OverlapChecks (optional)
5257 which overlap checks to perform for writes to the image, de‐
5258 faults to 'cached' (since 2.2)
5259 cache-size: int (optional)
5261 the maximum total size of the L2 table and refcount block caches
5262 in bytes (since 2.2)
5263 l2-cache-size: int (optional)
5265 the maximum size of the L2 table cache in bytes (since 2.2)
5266 l2-cache-entry-size: int (optional)
5268 the size of each entry in the L2 cache in bytes. It must be a
5269 power of two between 512 and the cluster size. The default value
5270 is the cluster size (since 2.12)
5271 refcount-cache-size: int (optional)
5273 the maximum size of the refcount block cache in bytes (since
5274 2.2)
5275 cache-clean-interval: int (optional)
5277 clean unused entries in the L2 and refcount caches. The interval
5278 is in seconds. The default value is 600 on supporting platforms,
5279 and 0 on other platforms. 0 disables this feature. (since 2.5)
5280 encrypt: BlockdevQcow2Encryption (optional)
5282 Image decryption options. Mandatory for encrypted images, except
5283 when doing a metadata-only probe of the image. (since 2.10)
5284 data-file: BlockdevRef (optional)
5286 reference to or definition of the external data file. This may
5287 only be specified for images that require an external data file.
5288 If it is not specified for such an image, the data file name is
5289 loaded from the image file. (since 4.0)
5290 The members of BlockdevOptionsGenericCOWFormat
5292 Since
5294 2.9
5295 SshHostKeyCheckMode (Enum)
5297 Values
5298 none Don't check the host key at all
5299 hash Compare the host key with a given hash
5301 known_hosts
5303 Check the host key against the known_hosts file
5304 Since
5306 2.12
5307 SshHostKeyCheckHashType (Enum)
5309 Values
5310 md5 The given hash is an md5 hash
5311 sha1 The given hash is an sha1 hash
5313 sha256 The given hash is an sha256 hash
5315 Since
5317 2.12
5318 SshHostKeyHash (Object)
5320 Members
5321 type: SshHostKeyCheckHashType
5322 The hash algorithm used for the hash
5323 hash: string
5325 The expected hash value
5326 Since
5328 2.12
5329 SshHostKeyCheck (Object)
5331 Members
5332 mode: SshHostKeyCheckMode
5333 Not documented
5334 The members of SshHostKeyHash when mode is "hash"
5336 Since
5338 2.12
5339 BlockdevOptionsSsh (Object)
5341 Members
5342 server: InetSocketAddress
5343 host address
5344 path: string
5346 path to the image on the host
5347 user: string (optional)
5349 user as which to connect, defaults to current local user name
5350 host-key-check: SshHostKeyCheck (optional)
5352 Defines how and what to check the host key against (default:
5353 known_hosts)
5354 Since
5356 2.9
5357 BlkdebugEvent (Enum)
5359 Trigger events supported by blkdebug.
5360 Values
5362 l1_shrink_write_table
5363 write zeros to the l1 table to shrink image. (since 2.11)
5364 l1_shrink_free_l2_clusters
5366 discard the l2 tables. (since 2.11)
5367 cor_write
5369 a write due to copy-on-read (since 2.11)
5370 cluster_alloc_space
5372 an allocation of file space for a cluster (since 4.1)
5373 none triggers once at creation of the blkdebug node (since 4.1)
5375 l1_update
5377 Not documented
5378 l1_grow_alloc_table
5380 Not documented
5381 l1_grow_write_table
5383 Not documented
5384 l1_grow_activate_table
5386 Not documented
5387 l2_load
5389 Not documented
5390 l2_update
5392 Not documented
5393 l2_update_compressed
5395 Not documented
5396 l2_alloc_cow_read
5398 Not documented
5399 l2_alloc_write
5401 Not documented
5402 read_aio
5404 Not documented
5405 read_backing_aio
5407 Not documented
5408 read_compressed
5410 Not documented
5411 write_aio
5413 Not documented
5414 write_compressed
5416 Not documented
5417 vmstate_load
5419 Not documented
5420 vmstate_save
5422 Not documented
5423 cow_read
5425 Not documented
5426 cow_write
5428 Not documented
5429 reftable_load
5431 Not documented
5432 reftable_grow
5434 Not documented
5435 reftable_update
5437 Not documented
5438 refblock_load
5440 Not documented
5441 refblock_update
5443 Not documented
5444 refblock_update_part
5446 Not documented
5447 refblock_alloc
5449 Not documented
5450 refblock_alloc_hookup
5452 Not documented
5453 refblock_alloc_write
5455 Not documented
5456 refblock_alloc_write_blocks
5458 Not documented
5459 refblock_alloc_write_table
5461 Not documented
5462 refblock_alloc_switch_table
5464 Not documented
5465 cluster_alloc
5467 Not documented
5468 cluster_alloc_bytes
5470 Not documented
5471 cluster_free
5473 Not documented
5474 flush_to_os
5476 Not documented
5477 flush_to_disk
5479 Not documented
5480 pwritev_rmw_head
5482 Not documented
5483 pwritev_rmw_after_head
5485 Not documented
5486 pwritev_rmw_tail
5488 Not documented
5489 pwritev_rmw_after_tail
5491 Not documented
5492 pwritev
5494 Not documented
5495 pwritev_zero
5497 Not documented
5498 pwritev_done
5500 Not documented
5501 empty_image_prepare
5503 Not documented
5504 Since
5506 2.9
5507 BlkdebugIOType (Enum)
5509 Kinds of I/O that blkdebug can inject errors in.
5510 Values
5512 read .bdrv_co_preadv()
5513 write .bdrv_co_pwritev()
5515 write-zeroes
5517 .bdrv_co_pwrite_zeroes()
5518 discard
5520 .bdrv_co_pdiscard()
5521 flush .bdrv_co_flush_to_disk()
5523 block-status
5525 .bdrv_co_block_status()
5526 Since
5528 4.1
5529 BlkdebugInjectErrorOptions (Object)
5531 Describes a single error injection for blkdebug.
5532 Members
5534 event: BlkdebugEvent
5535 trigger event
5536 state: int (optional)
5538 the state identifier blkdebug needs to be in to actually trigger
5539 the event; defaults to "any"
5540 iotype: BlkdebugIOType (optional)
5542 the type of I/O operations on which this error should be in‐
5543 jected; defaults to "all read, write, write-zeroes, discard, and
5544 flush operations" (since: 4.1)
5545 errno: int (optional)
5547 error identifier (errno) to be returned; defaults to EIO
5548 sector: int (optional)
5550 specifies the sector index which has to be affected in order to
5551 actually trigger the event; defaults to "any sector"
5552 once: boolean (optional)
5554 disables further events after this one has been triggered; de‐
5555 faults to false
5556 immediately: boolean (optional)
5558 fail immediately; defaults to false
5559 Since
5561 2.9
5562 BlkdebugSetStateOptions (Object)
5564 Describes a single state-change event for blkdebug.
5565 Members
5567 event: BlkdebugEvent
5568 trigger event
5569 state: int (optional)
5571 the current state identifier blkdebug needs to be in; defaults
5572 to "any"
5573 new_state: int
5575 the state identifier blkdebug is supposed to assume if this
5576 event is triggered
5577 Since
5579 2.9
5580 BlockdevOptionsBlkdebug (Object)
5582 Driver specific block device options for blkdebug.
5583 Members
5585 image: BlockdevRef
5586 underlying raw block device (or image file)
5587 config: string (optional)
5589 filename of the configuration file
5590 align: int (optional)
5592 required alignment for requests in bytes, must be positive power
5593 of 2, or 0 for default
5594 max-transfer: int (optional)
5596 maximum size for I/O transfers in bytes, must be positive multi‐
5597 ple of align and of the underlying file's request alignment (but
5598 need not be a power of 2), or 0 for default (since 2.10)
5599 opt-write-zero: int (optional)
5601 preferred alignment for write zero requests in bytes, must be
5602 positive multiple of align and of the underlying file's request
5603 alignment (but need not be a power of 2), or 0 for default
5604 (since 2.10)
5605 max-write-zero: int (optional)
5607 maximum size for write zero requests in bytes, must be positive
5608 multiple of align, of opt-write-zero, and of the underlying
5609 file's request alignment (but need not be a power of 2), or 0
5610 for default (since 2.10)
5611 opt-discard: int (optional)
5613 preferred alignment for discard requests in bytes, must be posi‐
5614 tive multiple of align and of the underlying file's request
5615 alignment (but need not be a power of 2), or 0 for default
5616 (since 2.10)
5617 max-discard: int (optional)
5619 maximum size for discard requests in bytes, must be positive
5620 multiple of align, of opt-discard, and of the underlying file's
5621 request alignment (but need not be a power of 2), or 0 for de‐
5622 fault (since 2.10)
5623 inject-error: array of BlkdebugInjectErrorOptions (optional)
5625 array of error injection descriptions
5626 set-state: array of BlkdebugSetStateOptions (optional)
5628 array of state-change descriptions
5629 take-child-perms: array of BlockPermission (optional)
5631 Permissions to take on image in addition to what is necessary
5632 anyway (which depends on how the blkdebug node is used). De‐
5633 faults to none. (since 5.0)
5634 unshare-child-perms: array of BlockPermission (optional)
5636 Permissions not to share on image in addition to what cannot be
5637 shared anyway (which depends on how the blkdebug node is used).
5638 Defaults to none. (since 5.0)
5639 Since
5641 2.9
5642 BlockdevOptionsBlklogwrites (Object)
5644 Driver specific block device options for blklogwrites.
5645 Members
5647 file: BlockdevRef
5648 block device
5649 log: BlockdevRef
5651 block device used to log writes to file
5652 log-sector-size: int (optional)
5654 sector size used in logging writes to file, determines granular‐
5655 ity of offsets and sizes of writes (default: 512)
5656 log-append: boolean (optional)
5658 append to an existing log (default: false)
5659 log-super-update-interval: int (optional)
5661 interval of write requests after which the log super block is
5662 updated to disk (default: 4096)
5663 Since
5665 3.0
5666 BlockdevOptionsBlkverify (Object)
5668 Driver specific block device options for blkverify.
5669 Members
5671 test: BlockdevRef
5672 block device to be tested
5673 raw: BlockdevRef
5675 raw image used for verification
5676 Since
5678 2.9
5679 BlockdevOptionsBlkreplay (Object)
5681 Driver specific block device options for blkreplay.
5682 Members
5684 image: BlockdevRef
5685 disk image which should be controlled with blkreplay
5686 Since
5688 4.2
5689 QuorumReadPattern (Enum)
5691 An enumeration of quorum read patterns.
5692 Values
5694 quorum read all the children and do a quorum vote on reads
5695 fifo read only from the first child that has not failed
5697 Since
5699 2.9
5700 BlockdevOptionsQuorum (Object)
5702 Driver specific block device options for Quorum
5703 Members
5705 blkverify: boolean (optional)
5706 true if the driver must print content mismatch
5708 set to false by default
5709 children: array of BlockdevRef
5711 the children block devices to use
5712 vote-threshold: int
5714 the vote limit under which a read will fail
5715 rewrite-corrupted: boolean (optional)
5717 rewrite corrupted data when quorum is reached (Since 2.1)
5718 read-pattern: QuorumReadPattern (optional)
5720 choose read pattern and set to quorum by default (Since 2.2)
5721 Since
5723 2.9
5724 BlockdevOptionsGluster (Object)
5726 Driver specific block device options for Gluster
5727 Members
5729 volume: string
5730 name of gluster volume where VM image resides
5731 path: string
5733 absolute path to image file in gluster volume
5734 server: array of SocketAddress
5736 gluster servers description
5737 debug: int (optional)
5739 libgfapi log level (default '4' which is Error) (Since 2.8)
5740 logfile: string (optional)
5742 libgfapi log file (default /dev/stderr) (Since 2.8)
5743 Since
5745 2.9
5746 IscsiTransport (Enum)
5748 An enumeration of libiscsi transport types
5749 Values
5751 tcp Not documented
5752 iser Not documented
5754 Since
5756 2.9
5757 IscsiHeaderDigest (Enum)
5759 An enumeration of header digests supported by libiscsi
5760 Values
5762 crc32c Not documented
5763 none Not documented
5765 crc32c-none
5767 Not documented
5768 none-crc32c
5770 Not documented
5771 Since
5773 2.9
5774 BlockdevOptionsIscsi (Object)
5776 Members
5777 transport: IscsiTransport
5778 The iscsi transport type
5779 portal: string
5781 The address of the iscsi portal
5782 target: string
5784 The target iqn name
5785 lun: int (optional)
5787 LUN to connect to. Defaults to 0.
5788 user: string (optional)
5790 User name to log in with. If omitted, no CHAP authentication is
5791 performed.
5792 password-secret: string (optional)
5794 The ID of a QCryptoSecret object providing the password for the
5795 login. This option is required if user is specified.
5796 initiator-name: string (optional)
5798 The iqn name we want to identify to the target as. If this op‐
5799 tion is not specified, an initiator name is generated automati‐
5800 cally.
5801 header-digest: IscsiHeaderDigest (optional)
5803 The desired header digest. Defaults to none-crc32c.
5804 timeout: int (optional)
5806 Timeout in seconds after which a request will timeout. 0 means
5807 no timeout and is the default.
5808 Driver specific block device options for iscsi
5809 Since
5811 2.9
5812 RbdAuthMode (Enum)
5814 Values
5815 cephx Not documented
5816 none Not documented
5818 Since
5820 3.0
5821 RbdImageEncryptionFormat (Enum)
5823 Values
5824 luks Not documented
5825 luks2 Not documented
5827 Since
5829 6.1
5830 RbdEncryptionOptionsLUKSBase (Object)
5832 Members
5833 key-secret: string
5834 ID of a QCryptoSecret object providing a passphrase for unlock‐
5835 ing the encryption
5836 Since
5838 6.1
5839 RbdEncryptionCreateOptionsLUKSBase (Object)
5841 Members
5842 cipher-alg: QCryptoCipherAlgorithm (optional)
5843 The encryption algorithm
5844 The members of RbdEncryptionOptionsLUKSBase
5846 Since
5848 6.1
5849 RbdEncryptionOptionsLUKS (Object)
5851 Members
5852 The members of RbdEncryptionOptionsLUKSBase
5853 Since
5855 6.1
5856 RbdEncryptionOptionsLUKS2 (Object)
5858 Members
5859 The members of RbdEncryptionOptionsLUKSBase
5860 Since
5862 6.1
5863 RbdEncryptionCreateOptionsLUKS (Object)
5865 Members
5866 The members of RbdEncryptionCreateOptionsLUKSBase
5867 Since
5869 6.1
5870 RbdEncryptionCreateOptionsLUKS2 (Object)
5872 Members
5873 The members of RbdEncryptionCreateOptionsLUKSBase
5874 Since
5876 6.1
5877 RbdEncryptionOptions (Object)
5879 Members
5880 format: RbdImageEncryptionFormat
5881 Not documented
5882 The members of RbdEncryptionOptionsLUKS when format is "luks"
5884 The members of RbdEncryptionOptionsLUKS2 when format is "luks2"
5886 Since
5888 6.1
5889 RbdEncryptionCreateOptions (Object)
5891 Members
5892 format: RbdImageEncryptionFormat
5893 Not documented
5894 The members of RbdEncryptionCreateOptionsLUKS when format is "luks"
5896 The members of RbdEncryptionCreateOptionsLUKS2 when format is "luks2"
5898 Since
5900 6.1
5901 BlockdevOptionsRbd (Object)
5903 Members
5904 pool: string
5905 Ceph pool name.
5906 namespace: string (optional)
5908 Rados namespace name in the Ceph pool. (Since 5.0)
5909 image: string
5911 Image name in the Ceph pool.
5912 conf: string (optional)
5914 path to Ceph configuration file. Values in the configuration
5915 file will be overridden by options specified via QAPI.
5916 snapshot: string (optional)
5918 Ceph snapshot name.
5919 encrypt: RbdEncryptionOptions (optional)
5921 Image encryption options. (Since 6.1)
5922 user: string (optional)
5924 Ceph id name.
5925 auth-client-required: array of RbdAuthMode (optional)
5927 Acceptable authentication modes. This maps to Ceph configura‐
5928 tion option "auth_client_required". (Since 3.0)
5929 key-secret: string (optional)
5931 ID of a QCryptoSecret object providing a key for cephx authenti‐
5932 cation. This maps to Ceph configuration option "key". (Since
5933 3.0)
5934 server: array of InetSocketAddressBase (optional)
5936 Monitor host address and port. This maps to the "mon_host" Ceph
5937 option.
5938 Since
5940 2.9
5941 ReplicationMode (Enum)
5943 An enumeration of replication modes.
5944 Values
5946 primary
5947 Primary mode, the vm's state will be sent to secondary QEMU.
5948 secondary
5950 Secondary mode, receive the vm's state from primary QEMU.
5951 Since
5953 2.9
5954 If
5956 CONFIG_REPLICATION
5957 BlockdevOptionsReplication (Object)
5959 Driver specific block device options for replication
5960 Members
5962 mode: ReplicationMode
5963 the replication mode
5964 top-id: string (optional)
5966 In secondary mode, node name or device ID of the root node who
5967 owns the replication node chain. Must not be given in primary
5968 mode.
5969 The members of BlockdevOptionsGenericFormat
5971 Since
5973 2.9
5974 If
5976 CONFIG_REPLICATION
5977 NFSTransport (Enum)
5979 An enumeration of NFS transport types
5980 Values
5982 inet TCP transport
5983 Since
5985 2.9
5986 NFSServer (Object)
5988 Captures the address of the socket
5989 Members
5991 type: NFSTransport
5992 transport type used for NFS (only TCP supported)
5993 host: string
5995 host address for NFS server
5996 Since
5998 2.9
5999 BlockdevOptionsNfs (Object)
6001 Driver specific block device option for NFS
6002 Members
6004 server: NFSServer
6005 host address
6006 path: string
6008 path of the image on the host
6009 user: int (optional)
6011 UID value to use when talking to the server (defaults to 65534
6012 on Windows and getuid() on unix)
6013 group: int (optional)
6015 GID value to use when talking to the server (defaults to 65534
6016 on Windows and getgid() in unix)
6017 tcp-syn-count: int (optional)
6019 number of SYNs during the session establishment (defaults to
6020 libnfs default)
6021 readahead-size: int (optional)
6023 set the readahead size in bytes (defaults to libnfs default)
6024 page-cache-size: int (optional)
6026 set the pagecache size in bytes (defaults to libnfs default)
6027 debug: int (optional)
6029 set the NFS debug level (max 2) (defaults to libnfs default)
6030 Since
6032 2.9
6033 BlockdevOptionsCurlBase (Object)
6035 Driver specific block device options shared by all protocols supported
6036 by the curl backend.
6037 Members
6039 url: string
6040 URL of the image file
6041 readahead: int (optional)
6043 Size of the read-ahead cache; must be a multiple of 512 (de‐
6044 faults to 256 kB)
6045 timeout: int (optional)
6047 Timeout for connections, in seconds (defaults to 5)
6048 username: string (optional)
6050 Username for authentication (defaults to none)
6051 password-secret: string (optional)
6053 ID of a QCryptoSecret object providing a password for authenti‐
6054 cation (defaults to no password)
6055 proxy-username: string (optional)
6057 Username for proxy authentication (defaults to none)
6058 proxy-password-secret: string (optional)
6060 ID of a QCryptoSecret object providing a password for proxy au‐
6061 thentication (defaults to no password)
6062 Since
6064 2.9
6065 BlockdevOptionsCurlHttp (Object)
6067 Driver specific block device options for HTTP connections over the curl
6068 backend. URLs must start with "http://".
6069 Members
6071 cookie: string (optional)
6072 List of cookies to set; format is "name1=content1; name2=con‐
6073 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
6074 ies.
6075 cookie-secret: string (optional)
6077 ID of a QCryptoSecret object providing the cookie data in a se‐
6078 cure way. See cookie for the format. (since 2.10)
6079 The members of BlockdevOptionsCurlBase
6081 Since
6083 2.9
6084 BlockdevOptionsCurlHttps (Object)
6086 Driver specific block device options for HTTPS connections over the
6087 curl backend. URLs must start with "https://".
6088 Members
6090 cookie: string (optional)
6091 List of cookies to set; format is "name1=content1; name2=con‐
6092 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
6093 ies.
6094 sslverify: boolean (optional)
6096 Whether to verify the SSL certificate's validity (defaults to
6097 true)
6098 cookie-secret: string (optional)
6100 ID of a QCryptoSecret object providing the cookie data in a se‐
6101 cure way. See cookie for the format. (since 2.10)
6102 The members of BlockdevOptionsCurlBase
6104 Since
6106 2.9
6107 BlockdevOptionsCurlFtp (Object)
6109 Driver specific block device options for FTP connections over the curl
6110 backend. URLs must start with "ftp://".
6111 Members
6113 The members of BlockdevOptionsCurlBase
6114 Since
6116 2.9
6117 BlockdevOptionsCurlFtps (Object)
6119 Driver specific block device options for FTPS connections over the curl
6120 backend. URLs must start with "ftps://".
6121 Members
6123 sslverify: boolean (optional)
6124 Whether to verify the SSL certificate's validity (defaults to
6125 true)
6126 The members of BlockdevOptionsCurlBase
6128 Since
6130 2.9
6131 BlockdevOptionsNbd (Object)
6133 Driver specific block device options for NBD.
6134 Members
6136 server: SocketAddress
6137 NBD server address
6138 export: string (optional)
6140 export name
6141 tls-creds: string (optional)
6143 TLS credentials ID
6144 x-dirty-bitmap: string (optional)
6146 A metadata context name such as "qemu:dirty-bitmap:NAME" or
6147 "qemu:allocation-depth" to query in place of the traditional
6148 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
6149 the NBD protocol; and yes, naming this option x-context would
6150 have made more sense) (since 3.0)
6151 reconnect-delay: int (optional)
6153 On an unexpected disconnect, the nbd client tries to connect
6154 again until succeeding or encountering a serious error. During
6155 the first reconnect-delay seconds, all requests are paused and
6156 will be rerun on a successful reconnect. After that time, any
6157 delayed requests and all future requests before a successful re‐
6158 connect will immediately fail. Default 0 (Since 4.2)
6159 Features
6161 unstable
6162 Member x-dirty-bitmap is experimental.
6163 Since
6165 2.9
6166 BlockdevOptionsRaw (Object)
6168 Driver specific block device options for the raw driver.
6169 Members
6171 offset: int (optional)
6172 position where the block device starts
6173 size: int (optional)
6175 the assumed size of the device
6176 The members of BlockdevOptionsGenericFormat
6178 Since
6180 2.9
6181 BlockdevOptionsThrottle (Object)
6183 Driver specific block device options for the throttle driver
6184 Members
6186 throttle-group: string
6187 the name of the throttle-group object to use. It must already
6188 exist.
6189 file: BlockdevRef
6191 reference to or definition of the data source block device
6192 Since
6194 2.11
6195 BlockdevOptionsCor (Object)
6197 Driver specific block device options for the copy-on-read driver.
6198 Members
6200 bottom: string (optional)
6201 The name of a non-filter node (allocation-bearing layer) that
6202 limits the COR operations in the backing chain (inclusive), so
6203 that no data below this node will be copied by this filter. If
6204 option is absent, the limit is not applied, so that data from
6205 all backing layers may be copied.
6206 The members of BlockdevOptionsGenericFormat
6208 Since
6210 6.0
6211 BlockdevOptionsCbw (Object)
6213 Driver specific block device options for the copy-before-write driver,
6214 which does so called copy-before-write operations: when data is written
6215 to the filter, the filter first reads corresponding blocks from its
6216 file child and copies them to target child. After successfully copying,
6217 the write request is propagated to file child. If copying fails, the
6218 original write request is failed too and no data is written to file
6219 child.
6220 Members
6222 target: BlockdevRef
6223 The target for copy-before-write operations.
6224 The members of BlockdevOptionsGenericFormat
6226 Since
6228 6.2
6229 BlockdevOptions (Object)
6231 Options for creating a block device. Many options are available for
6232 all block devices, independent of the block driver:
6233 Members
6235 driver: BlockdevDriver
6236 block driver name
6237 node-name: string (optional)
6239 the node name of the new node (Since 2.0). This option is re‐
6240 quired on the top level of blockdev-add. Valid node names start
6241 with an alphabetic character and may contain only alphanumeric
6242 characters, '-', '.' and '_'. Their maximum length is 31 charac‐
6243 ters.
6244 discard: BlockdevDiscardOptions (optional)
6246 discard-related options (default: ignore)
6247 cache: BlockdevCacheOptions (optional)
6249 cache-related options
6250 read-only: boolean (optional)
6252 whether the block device should be read-only (default: false).
6253 Note that some block drivers support only read-only access, ei‐
6254 ther generally or in certain configurations. In this case, the
6255 default value does not work and the option must be specified ex‐
6256 plicitly.
6257 auto-read-only: boolean (optional)
6259 if true and read-only is false, QEMU may automatically decide
6260 not to open the image read-write as requested, but fall back to
6261 read-only instead (and switch between the modes later), e.g. de‐
6262 pending on whether the image file is writable or whether a writ‐
6263 ing user is attached to the node (default: false, since 3.1)
6264 detect-zeroes: BlockdevDetectZeroesOptions (optional)
6266 detect and optimize zero writes (Since 2.1) (default: off)
6267 force-share: boolean (optional)
6269 force share all permission on added nodes. Requires
6270 read-only=true. (Since 2.10)
6271 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
6273 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
6275 writes"
6276 The members of BlockdevOptionsBlkverify when driver is "blkverify"
6278 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
6280 The members of BlockdevOptionsGenericFormat when driver is "bochs"
6282 The members of BlockdevOptionsGenericFormat when driver is "cloop"
6284 The members of BlockdevOptionsGenericFormat when driver is "compress"
6286 The members of BlockdevOptionsCbw when driver is "copy-before-write"
6288 The members of BlockdevOptionsCor when driver is "copy-on-read"
6290 The members of BlockdevOptionsGenericFormat when driver is "dmg"
6292 The members of BlockdevOptionsFile when driver is "file"
6294 The members of BlockdevOptionsCurlFtp when driver is "ftp"
6296 The members of BlockdevOptionsCurlFtps when driver is "ftps"
6298 The members of BlockdevOptionsGluster when driver is "gluster"
6300 The members of BlockdevOptionsFile when driver is "host_cdrom" (If:
6302 HAVE_HOST_BLOCK_DEVICE)
6303 The members of BlockdevOptionsFile when driver is "host_device" (If:
6305 HAVE_HOST_BLOCK_DEVICE)
6306 The members of BlockdevOptionsCurlHttp when driver is "http"
6308 The members of BlockdevOptionsCurlHttps when driver is "https"
6310 The members of BlockdevOptionsIscsi when driver is "iscsi"
6312 The members of BlockdevOptionsLUKS when driver is "luks"
6314 The members of BlockdevOptionsNbd when driver is "nbd"
6316 The members of BlockdevOptionsNfs when driver is "nfs"
6318 The members of BlockdevOptionsNull when driver is "null-aio"
6320 The members of BlockdevOptionsNull when driver is "null-co"
6322 The members of BlockdevOptionsNVMe when driver is "nvme"
6324 The members of BlockdevOptionsGenericFormat when driver is "parallels"
6326 The members of BlockdevOptionsPreallocate when driver is "preallocate"
6328 The members of BlockdevOptionsQcow2 when driver is "qcow2"
6330 The members of BlockdevOptionsQcow when driver is "qcow"
6332 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
6334 The members of BlockdevOptionsQuorum when driver is "quorum"
6336 The members of BlockdevOptionsRaw when driver is "raw"
6338 The members of BlockdevOptionsRbd when driver is "rbd"
6340 The members of BlockdevOptionsReplication when driver is "replication"
6342 (If: CONFIG_REPLICATION)
6343 The members of BlockdevOptionsSsh when driver is "ssh"
6345 The members of BlockdevOptionsThrottle when driver is "throttle"
6347 The members of BlockdevOptionsGenericFormat when driver is "vdi"
6349 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
6351 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
6353 The members of BlockdevOptionsGenericFormat when driver is "vpc"
6355 The members of BlockdevOptionsVVFAT when driver is "vvfat"
6357 Remaining options are determined by the block driver.
6358 Since
6360 2.9
6361 BlockdevRef (Alternate)
6363 Reference to a block device.
6364 Members
6366 definition: BlockdevOptions
6367 defines a new block device inline
6368 reference: string
6370 references the ID of an existing block device
6371 Since
6373 2.9
6374 BlockdevRefOrNull (Alternate)
6376 Reference to a block device.
6377 Members
6379 definition: BlockdevOptions
6380 defines a new block device inline
6381 reference: string
6383 references the ID of an existing block device. An empty string
6384 means that no block device should be referenced. Deprecated;
6385 use null instead.
6386 null: null
6388 No block device should be referenced (since 2.10)
6389 Since
6391 2.9
6392 blockdev-add (Command)
6394 Creates a new block device.
6395 Arguments
6397 The members of BlockdevOptions
6398 Since
6400 2.9
6401 Example
6403 1.
6404 -> { "execute": "blockdev-add",
6405 "arguments": {
6406 "driver": "qcow2",
6407 "node-name": "test1",
6408 "file": {
6409 "driver": "file",
6410 "filename": "test.qcow2"
6411 }
6412 }
6413 }
6414 <- { "return": {} }
6415 2.
6417 -> { "execute": "blockdev-add",
6418 "arguments": {
6419 "driver": "qcow2",
6420 "node-name": "node0",
6421 "discard": "unmap",
6422 "cache": {
6423 "direct": true
6424 },
6425 "file": {
6426 "driver": "file",
6427 "filename": "/tmp/test.qcow2"
6428 },
6429 "backing": {
6430 "driver": "raw",
6431 "file": {
6432 "driver": "file",
6433 "filename": "/dev/fdset/4"
6434 }
6435 }
6436 }
6437 }
6438 <- { "return": {} }
6440 blockdev-reopen (Command)
6442 Reopens one or more block devices using the given set of options. Any
6443 option not specified will be reset to its default value regardless of
6444 its previous status. If an option cannot be changed or a particular
6445 driver does not support reopening then the command will return an er‐
6446 ror. All devices in the list are reopened in one transaction, so if one
6447 of them fails then the whole transaction is cancelled.
6448 The command receives a list of block devices to reopen. For each one of
6450 them, the top-level node-name option (from BlockdevOptions) must be
6451 specified and is used to select the block device to be reopened. Other
6452 node-name options must be either omitted or set to the current name of
6453 the appropriate node. This command won't change any node name and any
6454 attempt to do it will result in an error.
6455 In the case of options that refer to child nodes, the behavior of this
6457 command depends on the value:
6458 1. A set of options (BlockdevOptions): the child is reopened with
6460 the specified set of options.
6461 2. A reference to the current child: the child is reopened using its
6463 existing set of options.
6464 3. A reference to a different node: the current child is replaced
6466 with the specified one.
6467 4. NULL: the current child (if any) is detached.
6469 Options (1) and (2) are supported in all cases. Option (3) is supported
6471 for file and backing, and option (4) for backing only.
6472 Unlike with blockdev-add, the backing option must always be present un‐
6474 less the node being reopened does not have a backing file and its image
6475 does not have a default backing file name as part of its metadata.
6476 Arguments
6478 options: array of BlockdevOptions
6479 Not documented
6480 Since
6482 6.1
6483 blockdev-del (Command)
6485 Deletes a block device that has been added using blockdev-add. The
6486 command will fail if the node is attached to a device or is otherwise
6487 being used.
6488 Arguments
6490 node-name: string
6491 Name of the graph node to delete.
6492 Since
6494 2.9
6495 Example
6497 -> { "execute": "blockdev-add",
6498 "arguments": {
6499 "driver": "qcow2",
6500 "node-name": "node0",
6501 "file": {
6502 "driver": "file",
6503 "filename": "test.qcow2"
6504 }
6505 }
6506 }
6507 <- { "return": {} }
6508 -> { "execute": "blockdev-del",
6510 "arguments": { "node-name": "node0" }
6511 }
6512 <- { "return": {} }
6513 BlockdevCreateOptionsFile (Object)
6515 Driver specific image creation options for file.
6516 Members
6518 filename: string
6519 Filename for the new image file
6520 size: int
6522 Size of the virtual disk in bytes
6523 preallocation: PreallocMode (optional)
6525 Preallocation mode for the new image (default: off; allowed val‐
6526 ues: off, falloc (if CONFIG_POSIX_FALLOCATE), full (if CON‐
6527 FIG_POSIX))
6528 nocow: boolean (optional)
6530 Turn off copy-on-write (valid only on btrfs; default: off)
6531 extent-size-hint: int (optional)
6533 Extent size hint to add to the image file; 0 for not adding an
6534 extent size hint (default: 1 MB, since 5.1)
6535 Since
6537 2.12
6538 BlockdevCreateOptionsGluster (Object)
6540 Driver specific image creation options for gluster.
6541 Members
6543 location: BlockdevOptionsGluster
6544 Where to store 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_GLUSTERFS_FALLOCATE), full (if CON‐
6552 FIG_GLUSTERFS_ZEROFILL))
6553 Since
6555 2.12
6556 BlockdevCreateOptionsLUKS (Object)
6558 Driver specific image creation options for LUKS.
6559 Members
6561 file: BlockdevRef
6562 Node to create the image format on
6563 size: int
6565 Size of the virtual disk in bytes
6566 preallocation: PreallocMode (optional)
6568 Preallocation mode for the new image (since: 4.2) (default: off;
6569 allowed values: off, metadata, falloc, full)
6570 The members of QCryptoBlockCreateOptionsLUKS
6572 Since
6574 2.12
6575 BlockdevCreateOptionsNfs (Object)
6577 Driver specific image creation options for NFS.
6578 Members
6580 location: BlockdevOptionsNfs
6581 Where to store the new image file
6582 size: int
6584 Size of the virtual disk in bytes
6585 Since
6587 2.12
6588 BlockdevCreateOptionsParallels (Object)
6590 Driver specific image creation options for parallels.
6591 Members
6593 file: BlockdevRef
6594 Node to create the image format on
6595 size: int
6597 Size of the virtual disk in bytes
6598 cluster-size: int (optional)
6600 Cluster size in bytes (default: 1 MB)
6601 Since
6603 2.12
6604 BlockdevCreateOptionsQcow (Object)
6606 Driver specific image creation options for qcow.
6607 Members
6609 file: BlockdevRef
6610 Node to create the image format on
6611 size: int
6613 Size of the virtual disk in bytes
6614 backing-file: string (optional)
6616 File name of the backing file if a backing file should be used
6617 encrypt: QCryptoBlockCreateOptions (optional)
6619 Encryption options if the image should be encrypted
6620 Since
6622 2.12
6623 BlockdevQcow2Version (Enum)
6625 Values
6626 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
6627 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
6629 Since
6631 2.12
6632 Qcow2CompressionType (Enum)
6634 Compression type used in qcow2 image file
6635 Values
6637 zlib zlib compression, see <http://zlib.net/>
6638 zstd (If: CONFIG_ZSTD)
6640 zstd compression, see <http://github.com/facebook/zstd>
6641 Since
6643 5.1
6644 BlockdevCreateOptionsQcow2 (Object)
6646 Driver specific image creation options for qcow2.
6647 Members
6649 file: BlockdevRef
6650 Node to create the image format on
6651 data-file: BlockdevRef (optional)
6653 Node to use as an external data file in which all guest data is
6654 stored so that only metadata remains in the qcow2 file (since:
6655 4.0)
6656 data-file-raw: boolean (optional)
6658 True if the external data file must stay valid as a standalone
6659 (read-only) raw image without looking at qcow2 metadata (de‐
6660 fault: false; since: 4.0)
6661 extended-l2: boolean (optional)
6663 True to make the image have extended L2 entries (default: false;
6664 since 5.2)
6665 size: int
6667 Size of the virtual disk in bytes
6668 version: BlockdevQcow2Version (optional)
6670 Compatibility level (default: v3)
6671 backing-file: string (optional)
6673 File name of the backing file if a backing file should be used
6674 backing-fmt: BlockdevDriver (optional)
6676 Name of the block driver to use for the backing file
6677 encrypt: QCryptoBlockCreateOptions (optional)
6679 Encryption options if the image should be encrypted
6680 cluster-size: int (optional)
6682 qcow2 cluster size in bytes (default: 65536)
6683 preallocation: PreallocMode (optional)
6685 Preallocation mode for the new image (default: off; allowed val‐
6686 ues: off, falloc, full, metadata)
6687 lazy-refcounts: boolean (optional)
6689 True if refcounts may be updated lazily (default: off)
6690 refcount-bits: int (optional)
6692 Width of reference counts in bits (default: 16)
6693 compression-type: Qcow2CompressionType (optional)
6695 The image cluster compression method (default: zlib, since 5.1)
6696 Since
6698 2.12
6699 BlockdevCreateOptionsQed (Object)
6701 Driver specific image creation options for qed.
6702 Members
6704 file: BlockdevRef
6705 Node to create the image format on
6706 size: int
6708 Size of the virtual disk in bytes
6709 backing-file: string (optional)
6711 File name of the backing file if a backing file should be used
6712 backing-fmt: BlockdevDriver (optional)
6714 Name of the block driver to use for the backing file
6715 cluster-size: int (optional)
6717 Cluster size in bytes (default: 65536)
6718 table-size: int (optional)
6720 L1/L2 table size (in clusters)
6721 Since
6723 2.12
6724 BlockdevCreateOptionsRbd (Object)
6726 Driver specific image creation options for rbd/Ceph.
6727 Members
6729 location: BlockdevOptionsRbd
6730 Where to store the new image file. This location cannot point to
6731 a snapshot.
6732 size: int
6734 Size of the virtual disk in bytes
6735 cluster-size: int (optional)
6737 RBD object size
6738 encrypt: RbdEncryptionCreateOptions (optional)
6740 Image encryption options. (Since 6.1)
6741 Since
6743 2.12
6744 BlockdevVmdkSubformat (Enum)
6746 Subformat options for VMDK images
6747 Values
6749 monolithicSparse
6750 Single file image with sparse cluster allocation
6751 monolithicFlat
6753 Single flat data image and a descriptor file
6754 twoGbMaxExtentSparse
6756 Data is split into 2GB (per virtual LBA) sparse extent files, in
6757 addition to a descriptor file
6758 twoGbMaxExtentFlat
6760 Data is split into 2GB (per virtual LBA) flat extent files, in
6761 addition to a descriptor file
6762 streamOptimized
6764 Single file image sparse cluster allocation, optimized for
6765 streaming over network.
6766 Since
6768 4.0
6769 BlockdevVmdkAdapterType (Enum)
6771 Adapter type info for VMDK images
6772 Values
6774 ide Not documented
6775 buslogic
6777 Not documented
6778 lsilogic
6780 Not documented
6781 legacyESX
6783 Not documented
6784 Since
6786 4.0
6787 BlockdevCreateOptionsVmdk (Object)
6789 Driver specific image creation options for VMDK.
6790 Members
6792 file: BlockdevRef
6793 Where to store the new image file. This refers to the image file
6794 for monolithcSparse and streamOptimized format, or the descrip‐
6795 tor file for other formats.
6796 size: int
6798 Size of the virtual disk in bytes
6799 extents: array of BlockdevRef (optional)
6801 Where to store the data extents. Required for monolithcFlat,
6802 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For mono‐
6803 lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
6804 mats, the number of entries required is calculated as ex‐
6805 tent_number = virtual_size / 2GB. Providing more extents than
6806 will be used is an error.
6807 subformat: BlockdevVmdkSubformat (optional)
6809 The subformat of the VMDK image. Default: "monolithicSparse".
6810 backing-file: string (optional)
6812 The path of backing file. Default: no backing file is used.
6813 adapter-type: BlockdevVmdkAdapterType (optional)
6815 The adapter type used to fill in the descriptor. Default: ide.
6816 hwversion: string (optional)
6818 Hardware version. The meaningful options are "4" or "6". De‐
6819 fault: "4".
6820 toolsversion: string (optional)
6822 VMware guest tools version. Default: "2147483647" (Since 6.2)
6823 zeroed-grain: boolean (optional)
6825 Whether to enable zeroed-grain feature for sparse subformats.
6826 Default: false.
6827 Since
6829 4.0
6830 BlockdevCreateOptionsSsh (Object)
6832 Driver specific image creation options for SSH.
6833 Members
6835 location: BlockdevOptionsSsh
6836 Where to store the new image file
6837 size: int
6839 Size of the virtual disk in bytes
6840 Since
6842 2.12
6843 BlockdevCreateOptionsVdi (Object)
6845 Driver specific image creation options for VDI.
6846 Members
6848 file: BlockdevRef
6849 Node to create the image format on
6850 size: int
6852 Size of the virtual disk in bytes
6853 preallocation: PreallocMode (optional)
6855 Preallocation mode for the new image (default: off; allowed val‐
6856 ues: off, metadata)
6857 Since
6859 2.12
6860 BlockdevVhdxSubformat (Enum)
6862 Values
6863 dynamic
6864 Growing image file
6865 fixed Preallocated fixed-size image file
6867 Since
6869 2.12
6870 BlockdevCreateOptionsVhdx (Object)
6872 Driver specific image creation options for vhdx.
6873 Members
6875 file: BlockdevRef
6876 Node to create the image format on
6877 size: int
6879 Size of the virtual disk in bytes
6880 log-size: int (optional)
6882 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
6883 block-size: int (optional)
6885 Block size in bytes, must be a multiple of 1 MB and not larger
6886 than 256 MB (default: automatically choose a block size depend‐
6887 ing on the image size)
6888 subformat: BlockdevVhdxSubformat (optional)
6890 vhdx subformat (default: dynamic)
6891 block-state-zero: boolean (optional)
6893 Force use of payload blocks of type 'ZERO'. Non-standard, but
6894 default. Do not set to 'off' when using 'qemu-img convert' with
6895 subformat=dynamic.
6896 Since
6898 2.12
6899 BlockdevVpcSubformat (Enum)
6901 Values
6902 dynamic
6903 Growing image file
6904 fixed Preallocated fixed-size image file
6906 Since
6908 2.12
6909 BlockdevCreateOptionsVpc (Object)
6911 Driver specific image creation options for vpc (VHD).
6912 Members
6914 file: BlockdevRef
6915 Node to create the image format on
6916 size: int
6918 Size of the virtual disk in bytes
6919 subformat: BlockdevVpcSubformat (optional)
6921 vhdx subformat (default: dynamic)
6922 force-size: boolean (optional)
6924 Force use of the exact byte size instead of rounding to the next
6925 size that can be represented in CHS geometry (default: false)
6926 Since
6928 2.12
6929 BlockdevCreateOptions (Object)
6931 Options for creating an image format on a given node.
6932 Members
6934 driver: BlockdevDriver
6935 block driver to create the image format
6936 The members of BlockdevCreateOptionsFile when driver is "file"
6938 The members of BlockdevCreateOptionsGluster when driver is "gluster"
6940 The members of BlockdevCreateOptionsLUKS when driver is "luks"
6942 The members of BlockdevCreateOptionsNfs when driver is "nfs"
6944 The members of BlockdevCreateOptionsParallels when driver is "paral‐
6946 lels"
6947 The members of BlockdevCreateOptionsQcow when driver is "qcow"
6949 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
6951 The members of BlockdevCreateOptionsQed when driver is "qed"
6953 The members of BlockdevCreateOptionsRbd when driver is "rbd"
6955 The members of BlockdevCreateOptionsSsh when driver is "ssh"
6957 The members of BlockdevCreateOptionsVdi when driver is "vdi"
6959 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
6961 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
6963 The members of BlockdevCreateOptionsVpc when driver is "vpc"
6965 Since
6967 2.12
6968 blockdev-create (Command)
6970 Starts a job to create an image format on a given node. The job is au‐
6971 tomatically finalized, but a manual job-dismiss is required.
6972 Arguments
6974 job-id: string
6975 Identifier for the newly created job.
6976 options: BlockdevCreateOptions
6978 Options for the image creation.
6979 Since
6981 3.0
6982 BlockdevAmendOptionsLUKS (Object)
6984 Driver specific image amend options for LUKS.
6985 Members
6987 The members of QCryptoBlockAmendOptionsLUKS
6988 Since
6990 5.1
6991 BlockdevAmendOptionsQcow2 (Object)
6993 Driver specific image amend options for qcow2. For now, only encryp‐
6994 tion options can be amended
6995 encrypt Encryption options to be amended
6997 Members
6999 encrypt: QCryptoBlockAmendOptions (optional)
7000 Not documented
7001 Since
7003 5.1
7004 BlockdevAmendOptions (Object)
7006 Options for amending an image format
7007 Members
7009 driver: BlockdevDriver
7010 Block driver of the node to amend.
7011 The members of BlockdevAmendOptionsLUKS when driver is "luks"
7013 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
7015 Since
7017 5.1
7018 x-blockdev-amend (Command)
7020 Starts a job to amend format specific options of an existing open block
7021 device The job is automatically finalized, but a manual job-dismiss is
7022 required.
7023 Arguments
7025 job-id: string
7026 Identifier for the newly created job.
7027 node-name: string
7029 Name of the block node to work on
7030 options: BlockdevAmendOptions
7032 Options (driver specific)
7033 force: boolean (optional)
7035 Allow unsafe operations, format specific For luks that allows
7036 erase of the last active keyslot (permanent loss of data), and
7037 replacement of an active keyslot (possible loss of data if IO
7038 error happens)
7039 Features
7041 unstable
7042 This command is experimental.
7043 Since
7045 5.1
7046 BlockErrorAction (Enum)
7048 An enumeration of action that has been taken when a DISK I/O occurs
7049 Values
7051 ignore error has been ignored
7052 report error has been reported to the device
7054 stop error caused VM to be stopped
7056 Since
7058 2.1
7059 BLOCK_IMAGE_CORRUPTED (Event)
7061 Emitted when a disk image is being marked corrupt. The image can be
7062 identified by its device or node name. The 'device' field is always
7063 present for compatibility reasons, but it can be empty ("") if the im‐
7064 age does not have a device name associated.
7065 Arguments
7067 device: string
7068 device name. This is always present for compatibility reasons,
7069 but it can be empty ("") if the image does not have a device
7070 name associated.
7071 node-name: string (optional)
7073 node name (Since: 2.4)
7074 msg: string
7076 informative message for human consumption, such as the kind of
7077 corruption being detected. It should not be parsed by machine as
7078 it is not guaranteed to be stable
7079 offset: int (optional)
7081 if the corruption resulted from an image access, this is the
7082 host's access offset into the image
7083 size: int (optional)
7085 if the corruption resulted from an image access, this is the ac‐
7086 cess size
7087 fatal: boolean
7089 if set, the image is marked corrupt and therefore unusable after
7090 this event and must be repaired (Since 2.2; before, every
7091 BLOCK_IMAGE_CORRUPTED event was fatal)
7092 Note
7094 If action is "stop", a STOP event will eventually follow the
7095 BLOCK_IO_ERROR event.
7096 Example
7098 <- { "event": "BLOCK_IMAGE_CORRUPTED",
7099 "data": { "device": "ide0-hd0", "node-name": "node0",
7100 "msg": "Prevented active L1 table overwrite", "offset": 196608,
7101 "size": 65536 },
7102 "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
7103 Since
7105 1.7
7106 BLOCK_IO_ERROR (Event)
7108 Emitted when a disk I/O error occurs
7109 Arguments
7111 device: string
7112 device name. This is always present for compatibility reasons,
7113 but it can be empty ("") if the image does not have a device
7114 name associated.
7115 node-name: string (optional)
7117 node name. Note that errors may be reported for the root node
7118 that is directly attached to a guest device rather than for the
7119 node where the error occurred. The node name is not present if
7120 the drive is empty. (Since: 2.8)
7121 operation: IoOperationType
7123 I/O operation
7124 action: BlockErrorAction
7126 action that has been taken
7127 nospace: boolean (optional)
7129 true if I/O error was caused due to a no-space condition. This
7130 key is only present if query-block's io-status is present,
7131 please see query-block documentation for more information
7132 (since: 2.2)
7133 reason: string
7135 human readable string describing the error cause. (This field
7136 is a debugging aid for humans, it should not be parsed by appli‐
7137 cations) (since: 2.2)
7138 Note
7140 If action is "stop", a STOP event will eventually follow the
7141 BLOCK_IO_ERROR event
7142 Since
7144 0.13
7145 Example
7147 <- { "event": "BLOCK_IO_ERROR",
7148 "data": { "device": "ide0-hd1",
7149 "node-name": "#block212",
7150 "operation": "write",
7151 "action": "stop" },
7152 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7153 BLOCK_JOB_COMPLETED (Event)
7155 Emitted when a block job has completed
7156 Arguments
7158 type: JobType
7159 job type
7160 device: string
7162 The job identifier. Originally the device name but other values
7163 are allowed since QEMU 2.7
7164 len: int
7166 maximum progress value
7167 offset: int
7169 current progress value. On success this is equal to len. On
7170 failure this is less than len
7171 speed: int
7173 rate limit, bytes per second
7174 error: string (optional)
7176 error message. Only present on failure. This field contains a
7177 human-readable error message. There are no semantics other than
7178 that streaming has failed and clients should not try to inter‐
7179 pret the error string
7180 Since
7182 1.1
7183 Example
7185 <- { "event": "BLOCK_JOB_COMPLETED",
7186 "data": { "type": "stream", "device": "virtio-disk0",
7187 "len": 10737418240, "offset": 10737418240,
7188 "speed": 0 },
7189 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
7190 BLOCK_JOB_CANCELLED (Event)
7192 Emitted when a block job has been cancelled
7193 Arguments
7195 type: JobType
7196 job type
7197 device: string
7199 The job identifier. Originally the device name but other values
7200 are allowed since QEMU 2.7
7201 len: int
7203 maximum progress value
7204 offset: int
7206 current progress value. On success this is equal to len. On
7207 failure this is less than len
7208 speed: int
7210 rate limit, bytes per second
7211 Since
7213 1.1
7214 Example
7216 <- { "event": "BLOCK_JOB_CANCELLED",
7217 "data": { "type": "stream", "device": "virtio-disk0",
7218 "len": 10737418240, "offset": 134217728,
7219 "speed": 0 },
7220 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
7221 BLOCK_JOB_ERROR (Event)
7223 Emitted when a block job encounters an error
7224 Arguments
7226 device: string
7227 The job identifier. Originally the device name but other values
7228 are allowed since QEMU 2.7
7229 operation: IoOperationType
7231 I/O operation
7232 action: BlockErrorAction
7234 action that has been taken
7235 Since
7237 1.3
7238 Example
7240 <- { "event": "BLOCK_JOB_ERROR",
7241 "data": { "device": "ide0-hd1",
7242 "operation": "write",
7243 "action": "stop" },
7244 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7245 BLOCK_JOB_READY (Event)
7247 Emitted when a block job is ready to complete
7248 Arguments
7250 type: JobType
7251 job type
7252 device: string
7254 The job identifier. Originally the device name but other values
7255 are allowed since QEMU 2.7
7256 len: int
7258 maximum progress value
7259 offset: int
7261 current progress value. On success this is equal to len. On
7262 failure this is less than len
7263 speed: int
7265 rate limit, bytes per second
7266 Note
7268 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
7269 event
7270 Since
7272 1.3
7273 Example
7275 <- { "event": "BLOCK_JOB_READY",
7276 "data": { "device": "drive0", "type": "mirror", "speed": 0,
7277 "len": 2097152, "offset": 2097152 }
7278 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7279 BLOCK_JOB_PENDING (Event)
7281 Emitted when a block job is awaiting explicit authorization to finalize
7282 graph changes via block-job-finalize. If this job is part of a transac‐
7283 tion, it will not emit this event until the transaction has converged
7284 first.
7285 Arguments
7287 type: JobType
7288 job type
7289 id: string
7291 The job identifier.
7292 Since
7294 2.12
7295 Example
7297 <- { "event": "BLOCK_JOB_WAITING",
7298 "data": { "device": "drive0", "type": "mirror" },
7299 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7300 PreallocMode (Enum)
7302 Preallocation mode of QEMU image file
7303 Values
7305 off no preallocation
7306 metadata
7308 preallocate only for metadata
7309 falloc like full preallocation but allocate disk space by posix_fallo‐
7311 cate() rather than writing data.
7312 full preallocate all data by writing it to the device to ensure disk
7314 space is really available. This data may or may not be zero, de‐
7315 pending on the image format and storage. full preallocation
7316 also sets up metadata correctly.
7317 Since
7319 2.2
7320 BLOCK_WRITE_THRESHOLD (Event)
7322 Emitted when writes on block device reaches or exceeds the configured
7323 write threshold. For thin-provisioned devices, this means the device
7324 should be extended to avoid pausing for disk exhaustion. The event is
7325 one shot. Once triggered, it needs to be re-registered with another
7326 block-set-write-threshold command.
7327 Arguments
7329 node-name: string
7330 graph node name on which the threshold was exceeded.
7331 amount-exceeded: int
7333 amount of data which exceeded the threshold, in bytes.
7334 write-threshold: int
7336 last configured threshold, in bytes.
7337 Since
7339 2.3
7340 block-set-write-threshold (Command)
7342 Change the write threshold for a block drive. An event will be deliv‐
7343 ered if a write to this block drive crosses the configured threshold.
7344 The threshold is an offset, thus must be non-negative. Default is no
7345 write threshold. Setting the threshold to zero disables it.
7346 This is useful to transparently resize thin-provisioned drives without
7348 the guest OS noticing.
7349 Arguments
7351 node-name: string
7352 graph node name on which the threshold must be set.
7353 write-threshold: int
7355 configured threshold for the block device, bytes. Use 0 to dis‐
7356 able the threshold.
7357 Since
7359 2.3
7360 Example
7362 -> { "execute": "block-set-write-threshold",
7363 "arguments": { "node-name": "mydev",
7364 "write-threshold": 17179869184 } }
7365 <- { "return": {} }
7366 x-blockdev-change (Command)
7368 Dynamically reconfigure the block driver state graph. It can be used to
7369 add, remove, insert or replace a graph node. Currently only the Quorum
7370 driver implements this feature to add or remove its child. This is use‐
7371 ful to fix a broken quorum child.
7372 If node is specified, it will be inserted under parent. child may not
7374 be specified in this case. If both parent and child are specified but
7375 node is not, child will be detached from parent.
7376 Arguments
7378 parent: string
7379 the id or name of the parent node.
7380 child: string (optional)
7382 the name of a child under the given parent node.
7383 node: string (optional)
7385 the name of the node that will be added.
7386 Features
7388 unstable
7389 This command is experimental, and its API is not stable. It
7390 does not support all kinds of operations, all kinds of children,
7391 nor all block drivers.
7392 FIXME Removing children from a quorum node means introducing
7394 gaps in the child indices. This cannot be represented in the
7395 'children' list of BlockdevOptionsQuorum, as returned by
7396 .bdrv_refresh_filename().
7397 Warning: The data in a new quorum child MUST be consistent with
7399 that of the rest of the array.
7400 Since
7402 2.7
7403 Example
7405 1. Add a new node to a quorum
7406 -> { "execute": "blockdev-add",
7407 "arguments": {
7408 "driver": "raw",
7409 "node-name": "new_node",
7410 "file": { "driver": "file",
7411 "filename": "test.raw" } } }
7412 <- { "return": {} }
7413 -> { "execute": "x-blockdev-change",
7414 "arguments": { "parent": "disk1",
7415 "node": "new_node" } }
7416 <- { "return": {} }
7417 2. Delete a quorum's node
7419 -> { "execute": "x-blockdev-change",
7420 "arguments": { "parent": "disk1",
7421 "child": "children.1" } }
7422 <- { "return": {} }
7423 x-blockdev-set-iothread (Command)
7425 Move node and its children into the iothread. If iothread is null then
7426 move node and its children into the main loop.
7427 The node must not be attached to a BlockBackend.
7429 Arguments
7431 node-name: string
7432 the name of the block driver node
7433 iothread: StrOrNull
7435 the name of the IOThread object or null for the main loop
7436 force: boolean (optional)
7438 true if the node and its children should be moved when a Block‐
7439 Backend is already attached
7440 Features
7442 unstable
7443 This command is experimental and intended for test cases that
7444 need control over IOThreads only.
7445 Since
7447 2.12
7448 Example
7450 1. Move a node into an IOThread
7451 -> { "execute": "x-blockdev-set-iothread",
7452 "arguments": { "node-name": "disk1",
7453 "iothread": "iothread0" } }
7454 <- { "return": {} }
7455 2. Move a node into the main loop
7457 -> { "execute": "x-blockdev-set-iothread",
7458 "arguments": { "node-name": "disk1",
7459 "iothread": null } }
7460 <- { "return": {} }
7461 QuorumOpType (Enum)
7463 An enumeration of the quorum operation types
7464 Values
7466 read read operation
7467 write write operation
7469 flush flush operation
7471 Since
7473 2.6
7474 QUORUM_FAILURE (Event)
7476 Emitted by the Quorum block driver if it fails to establish a quorum
7477 Arguments
7479 reference: string
7480 device name if defined else node name
7481 sector-num: int
7483 number of the first sector of the failed read operation
7484 sectors-count: int
7486 failed read operation sector count
7487 Note
7489 This event is rate-limited.
7490 Since
7492 2.0
7493 Example
7495 <- { "event": "QUORUM_FAILURE",
7496 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
7497 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7498 QUORUM_REPORT_BAD (Event)
7500 Emitted to report a corruption of a Quorum file
7501 Arguments
7503 type: QuorumOpType
7504 quorum operation type (Since 2.6)
7505 error: string (optional)
7507 error message. Only present on failure. This field contains a
7508 human-readable error message. There are no semantics other than
7509 that the block layer reported an error and clients should not
7510 try to interpret the error string.
7511 node-name: string
7513 the graph node name of the block driver state
7514 sector-num: int
7516 number of the first sector of the failed read operation
7517 sectors-count: int
7519 failed read operation sector count
7520 Note
7522 This event is rate-limited.
7523 Since
7525 2.0
7526 Example
7528 1. Read operation
7529 { "event": "QUORUM_REPORT_BAD",
7531 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
7532 "type": "read" },
7533 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7534 2. Flush operation
7536 { "event": "QUORUM_REPORT_BAD",
7538 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
7539 "type": "flush", "error": "Broken pipe" },
7540 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
7541 BlockdevSnapshotInternal (Object)
7543 Members
7544 device: string
7545 the device name or node-name of a root node to generate the
7546 snapshot from
7547 name: string
7549 the name of the internal snapshot to be created
7550 Notes
7552 In transaction, if name is empty, or any snapshot matching name exists,
7553 the operation will fail. Only some image formats support it, for exam‐
7554 ple, qcow2, and rbd.
7555 Since
7557 1.7
7558 blockdev-snapshot-internal-sync (Command)
7560 Synchronously take an internal snapshot of a block device, when the
7561 format of the image used supports it. If the name is an empty string,
7562 or a snapshot with name already exists, the operation will fail.
7563 For the arguments, see the documentation of BlockdevSnapshotInternal.
7565 Returns
7567 • nothing on success
7568 • If device is not a valid block device, GenericError
7570 • If any snapshot matching name exists, or name is empty, GenericError
7572 • If the format of the image used does not support it, BlockFormatFea‐
7574 tureNotSupported
7575 Since
7577 1.7
7578 Example
7580 -> { "execute": "blockdev-snapshot-internal-sync",
7581 "arguments": { "device": "ide-hd0",
7582 "name": "snapshot0" }
7583 }
7584 <- { "return": {} }
7585 blockdev-snapshot-delete-internal-sync (Command)
7587 Synchronously delete an internal snapshot of a block device, when the
7588 format of the image used support it. The snapshot is identified by name
7589 or id or both. One of the name or id is required. Return SnapshotInfo
7590 for the successfully deleted snapshot.
7591 Arguments
7593 device: string
7594 the device name or node-name of a root node to delete the snap‐
7595 shot from
7596 id: string (optional)
7598 optional the snapshot's ID to be deleted
7599 name: string (optional)
7601 optional the snapshot's name to be deleted
7602 Returns
7604 • SnapshotInfo on success
7605 • If device is not a valid block device, GenericError
7607 • If snapshot not found, GenericError
7609 • If the format of the image used does not support it, BlockFormatFea‐
7611 tureNotSupported
7612 • If id and name are both not specified, GenericError
7614 Since
7616 1.7
7617 Example
7619 -> { "execute": "blockdev-snapshot-delete-internal-sync",
7620 "arguments": { "device": "ide-hd0",
7621 "name": "snapshot0" }
7622 }
7623 <- { "return": {
7624 "id": "1",
7625 "name": "snapshot0",
7626 "vm-state-size": 0,
7627 "date-sec": 1000012,
7628 "date-nsec": 10,
7629 "vm-clock-sec": 100,
7630 "vm-clock-nsec": 20,
7631 "icount": 220414
7632 }
7633 }
7634 Block device exports
7636 NbdServerOptions (Object)
7637 Keep this type consistent with the nbd-server-start arguments. The only
7638 intended difference is using SocketAddress instead of SocketAddressLe‐
7639 gacy.
7640 Members
7642 addr: SocketAddress
7643 Address on which to listen.
7644 tls-creds: string (optional)
7646 ID of the TLS credentials object (since 2.6).
7647 tls-authz: string (optional)
7649 ID of the QAuthZ authorization object used to validate the
7650 client's x509 distinguished name. This object is is only re‐
7651 solved at time of use, so can be deleted and recreated on the
7652 fly while the NBD server is active. If missing, it will default
7653 to denying access (since 4.0).
7654 max-connections: int (optional)
7656 The maximum number of connections to allow at the same time, 0
7657 for unlimited. (since 5.2; default: 0)
7658 Since
7660 4.2
7661 nbd-server-start (Command)
7663 Start an NBD server listening on the given host and port. Block de‐
7664 vices can then be exported using nbd-server-add. The NBD server will
7665 present them as named exports; for example, another QEMU instance could
7666 refer to them as "nbd:HOST:PORT:exportname=NAME".
7667 Keep this type consistent with the NbdServerOptions type. The only in‐
7669 tended difference is using SocketAddressLegacy instead of SocketAd‐
7670 dress.
7671 Arguments
7673 addr: SocketAddressLegacy
7674 Address on which to listen.
7675 tls-creds: string (optional)
7677 ID of the TLS credentials object (since 2.6).
7678 tls-authz: string (optional)
7680 ID of the QAuthZ authorization object used to validate the
7681 client's x509 distinguished name. This object is is only re‐
7682 solved at time of use, so can be deleted and recreated on the
7683 fly while the NBD server is active. If missing, it will default
7684 to denying access (since 4.0).
7685 max-connections: int (optional)
7687 The maximum number of connections to allow at the same time, 0
7688 for unlimited. (since 5.2; default: 0)
7689 Returns
7691 error if the server is already running.
7692 Since
7694 1.3
7695 BlockExportOptionsNbdBase (Object)
7697 An NBD block export (common options shared between nbd-server-add and
7698 the NBD branch of block-export-add).
7699 Members
7701 name: string (optional)
7702 Export name. If unspecified, the device parameter is used as the
7703 export name. (Since 2.12)
7704 description: string (optional)
7706 Free-form description of the export, up to 4096 bytes. (Since
7707 5.0)
7708 Since
7710 5.0
7711 BlockExportOptionsNbd (Object)
7713 An NBD block export (distinct options used in the NBD branch of
7714 block-export-add).
7715 Members
7717 bitmaps: array of string (optional)
7718 Also export each of the named dirty bitmaps reachable from de‐
7719 vice, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
7720 the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
7721 each bitmap.
7722 allocation-depth: boolean (optional)
7724 Also export the allocation depth map for device, so the NBD
7725 client can use NBD_OPT_SET_META_CONTEXT with the metadata con‐
7726 text name "qemu:allocation-depth" to inspect allocation details.
7727 (since 5.2)
7728 The members of BlockExportOptionsNbdBase
7730 Since
7732 5.2
7733 BlockExportOptionsVhostUserBlk (Object)
7735 A vhost-user-blk block export.
7736 Members
7738 addr: SocketAddress
7739 The vhost-user socket on which to listen. Both 'unix' and 'fd'
7740 SocketAddress types are supported. Passed fds must be UNIX do‐
7741 main sockets.
7742 logical-block-size: int (optional)
7744 Logical block size in bytes. Defaults to 512 bytes.
7745 num-queues: int (optional)
7747 Number of request virtqueues. Must be greater than 0. Defaults
7748 to 1.
7749 Since
7751 5.2
7752 FuseExportAllowOther (Enum)
7754 Possible allow_other modes for FUSE exports.
7755 Values
7757 off Do not pass allow_other as a mount option.
7758 on Pass allow_other as a mount option.
7760 auto Try mounting with allow_other first, and if that fails, retry
7762 without allow_other.
7763 Since
7765 6.1
7766 BlockExportOptionsFuse (Object)
7768 Options for exporting a block graph node on some (file) mountpoint as a
7769 raw image.
7770 Members
7772 mountpoint: string
7773 Path on which to export the block device via FUSE. This must
7774 point to an existing regular file.
7775 growable: boolean (optional)
7777 Whether writes beyond the EOF should grow the block node accord‐
7778 ingly. (default: false)
7779 allow-other: FuseExportAllowOther (optional)
7781 If this is off, only qemu's user is allowed access to this ex‐
7782 port. That cannot be changed even with chmod or chown. En‐
7783 abling this option will allow other users access to the export
7784 with the FUSE mount option "allow_other". Note that using al‐
7785 low_other as a non-root user requires user_allow_other to be en‐
7786 abled in the global fuse.conf configuration file. In auto mode
7787 (the default), the FUSE export driver will first attempt to
7788 mount the export with allow_other, and if that fails, try again
7789 without. (since 6.1; default: auto)
7790 Since
7792 6.0
7793 If
7795 CONFIG_FUSE
7796 NbdServerAddOptions (Object)
7798 An NBD block export, per legacy nbd-server-add command.
7799 Members
7801 device: string
7802 The device name or node name of the node to be exported
7803 writable: boolean (optional)
7805 Whether clients should be able to write to the device via the
7806 NBD connection (default false).
7807 bitmap: string (optional)
7809 Also export a single dirty bitmap reachable from device, so the
7810 NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
7811 context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
7812 (since 4.0).
7813 The members of BlockExportOptionsNbdBase
7815 Since
7817 5.0
7818 nbd-server-add (Command)
7820 Export a block node to QEMU's embedded NBD server.
7821 The export name will be used as the id for the resulting block export.
7823 Arguments
7825 The members of NbdServerAddOptions
7826 Features
7828 deprecated
7829 This command is deprecated. Use block-export-add instead.
7830 Returns
7832 error if the server is not running, or export with the same name al‐
7833 ready exists.
7834 Since
7836 1.3
7837 BlockExportRemoveMode (Enum)
7839 Mode for removing a block export.
7840 Values
7842 safe Remove export if there are no existing connections, fail other‐
7843 wise.
7844 hard Drop all connections immediately and remove export.
7846 Potential additional modes to be added in the future:
7847 hide: Just hide export from new clients, leave existing connections as
7849 is. Remove export after all clients are disconnected.
7850 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
7852 ther requests from existing clients.
7853 Since
7855 2.12
7856 nbd-server-remove (Command)
7858 Remove NBD export by name.
7859 Arguments
7861 name: string
7862 Block export id.
7863 mode: BlockExportRemoveMode (optional)
7865 Mode of command operation. See BlockExportRemoveMode descrip‐
7866 tion. Default is 'safe'.
7867 Features
7869 deprecated
7870 This command is deprecated. Use block-export-del instead.
7871 Returns
7873 error if
7874 • the server is not running
7876 • export is not found
7878 • mode is 'safe' and there are existing connections
7880 Since
7882 2.12
7883 nbd-server-stop (Command)
7885 Stop QEMU's embedded NBD server, and unregister all devices previously
7886 added via nbd-server-add.
7887 Since
7889 1.3
7890 BlockExportType (Enum)
7892 An enumeration of block export types
7893 Values
7895 nbd NBD export
7896 vhost-user-blk
7898 vhost-user-blk export (since 5.2)
7899 fuse (If: CONFIG_FUSE)
7901 FUSE export (since: 6.0)
7902 Since
7904 4.2
7905 BlockExportOptions (Object)
7907 Describes a block export, i.e. how single node should be exported on an
7908 external interface.
7909 Members
7911 id: string
7912 A unique identifier for the block export (across all export
7913 types)
7914 node-name: string
7916 The node name of the block node to be exported (since: 5.2)
7917 writable: boolean (optional)
7919 True if clients should be able to write to the export (default
7920 false)
7921 writethrough: boolean (optional)
7923 If true, caches are flushed after every write request to the ex‐
7924 port before completion is signalled. (since: 5.2; default:
7925 false)
7926 iothread: string (optional)
7928 The name of the iothread object where the export will run. The
7929 default is to use the thread currently associated with the block
7930 node. (since: 5.2)
7931 fixed-iothread: boolean (optional)
7933 True prevents the block node from being moved to another thread
7934 while the export is active. If true and iothread is given, ex‐
7935 port creation fails if the block node cannot be moved to the io‐
7936 thread. The default is false. (since: 5.2)
7937 type: BlockExportType
7939 Not documented
7940 The members of BlockExportOptionsNbd when type is "nbd"
7942 The members of BlockExportOptionsVhostUserBlk when type is
7944 "vhost-user-blk"
7945 The members of BlockExportOptionsFuse when type is "fuse" (If: CON‐
7947 FIG_FUSE)
7948 Since
7950 4.2
7951 block-export-add (Command)
7953 Creates a new block export.
7954 Arguments
7956 The members of BlockExportOptions
7957 Since
7959 5.2
7960 block-export-del (Command)
7962 Request to remove a block export. This drops the user's reference to
7963 the export, but the export may still stay around after this command re‐
7964 turns until the shutdown of the export has completed.
7965 Arguments
7967 id: string
7968 Block export id.
7969 mode: BlockExportRemoveMode (optional)
7971 Mode of command operation. See BlockExportRemoveMode descrip‐
7972 tion. Default is 'safe'.
7973 Returns
7975 Error if the export is not found or mode is 'safe' and the export is
7976 still in use (e.g. by existing client connections)
7977 Since
7979 5.2
7980 BLOCK_EXPORT_DELETED (Event)
7982 Emitted when a block export is removed and its id can be reused.
7983 Arguments
7985 id: string
7986 Block export id.
7987 Since
7989 5.2
7990 BlockExportInfo (Object)
7992 Information about a single block export.
7993 Members
7995 id: string
7996 The unique identifier for the block export
7997 type: BlockExportType
7999 The block export type
8000 node-name: string
8002 The node name of the block node that is exported
8003 shutting-down: boolean
8005 True if the export is shutting down (e.g. after a block-ex‐
8006 port-del command, but before the shutdown has completed)
8007 Since
8009 5.2
8010 query-block-exports (Command)
8012 Returns
8013 A list of BlockExportInfo describing all block exports
8014 Since
8016 5.2
8017
8019 ChardevInfo (Object)
8020 Information about a character device.
8021 Members
8023 label: string
8024 the label of the character device
8025 filename: string
8027 the filename of the character device
8028 frontend-open: boolean
8030 shows whether the frontend device attached to this backend (eg.
8031 with the chardev=... option) is in open or closed state (since
8032 2.1)
8033 Notes
8035 filename is encoded using the QEMU command line character device encod‐
8036 ing. See the QEMU man page for details.
8037 Since
8039 0.14
8040 query-chardev (Command)
8042 Returns information about current character devices.
8043 Returns
8045 a list of ChardevInfo
8046 Since
8048 0.14
8049 Example
8051 -> { "execute": "query-chardev" }
8052 <- {
8053 "return": [
8054 {
8055 "label": "charchannel0",
8056 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
8057 "frontend-open": false
8058 },
8059 {
8060 "label": "charmonitor",
8061 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
8062 "frontend-open": true
8063 },
8064 {
8065 "label": "charserial0",
8066 "filename": "pty:/dev/pts/2",
8067 "frontend-open": true
8068 }
8069 ]
8070 }
8071 ChardevBackendInfo (Object)
8073 Information about a character device backend
8074 Members
8076 name: string
8077 The backend name
8078 Since
8080 2.0
8081 query-chardev-backends (Command)
8083 Returns information about character device backends.
8084 Returns
8086 a list of ChardevBackendInfo
8087 Since
8089 2.0
8090 Example
8092 -> { "execute": "query-chardev-backends" }
8093 <- {
8094 "return":[
8095 {
8096 "name":"udp"
8097 },
8098 {
8099 "name":"tcp"
8100 },
8101 {
8102 "name":"unix"
8103 },
8104 {
8105 "name":"spiceport"
8106 }
8107 ]
8108 }
8109 DataFormat (Enum)
8111 An enumeration of data format.
8112 Values
8114 utf8 Data is a UTF-8 string (RFC 3629)
8115 base64 Data is Base64 encoded binary (RFC 3548)
8117 Since
8119 1.4
8120 ringbuf-write (Command)
8122 Write to a ring buffer character device.
8123 Arguments
8125 device: string
8126 the ring buffer character device name
8127 data: string
8129 data to write
8130 format: DataFormat (optional)
8132 data encoding (default 'utf8').
8133 • base64: data must be base64 encoded text. Its binary decoding
8135 gets written.
8136 • utf8: data's UTF-8 encoding is written
8138 • data itself is always Unicode regardless of format, like any
8140 other string.
8141 Returns
8143 Nothing on success
8144 Since
8146 1.4
8147 Example
8149 -> { "execute": "ringbuf-write",
8150 "arguments": { "device": "foo",
8151 "data": "abcdefgh",
8152 "format": "utf8" } }
8153 <- { "return": {} }
8154 ringbuf-read (Command)
8156 Read from a ring buffer character device.
8157 Arguments
8159 device: string
8160 the ring buffer character device name
8161 size: int
8163 how many bytes to read at most
8164 format: DataFormat (optional)
8166 data encoding (default 'utf8').
8167 • base64: the data read is returned in base64 encoding.
8169 • utf8: the data read is interpreted as UTF-8. Bug: can screw
8171 up when the buffer contains invalid UTF-8 sequences, NUL char‐
8172 acters, after the ring buffer lost data, and when reading
8173 stops because the size limit is reached.
8174 • The return value is always Unicode regardless of format, like
8176 any other string.
8177 Returns
8179 data read from the device
8180 Since
8182 1.4
8183 Example
8185 -> { "execute": "ringbuf-read",
8186 "arguments": { "device": "foo",
8187 "size": 1000,
8188 "format": "utf8" } }
8189 <- { "return": "abcdefgh" }
8190 ChardevCommon (Object)
8192 Configuration shared across all chardev backends
8193 Members
8195 logfile: string (optional)
8196 The name of a logfile to save output
8197 logappend: boolean (optional)
8199 true to append instead of truncate (default to false to trun‐
8200 cate)
8201 Since
8203 2.6
8204 ChardevFile (Object)
8206 Configuration info for file chardevs.
8207 Members
8209 in: string (optional)
8210 The name of the input file
8211 out: string
8213 The name of the output file
8214 append: boolean (optional)
8216 Open the file in append mode (default false to truncate) (Since
8217 2.6)
8218 The members of ChardevCommon
8220 Since
8222 1.4
8223 ChardevHostdev (Object)
8225 Configuration info for device and pipe chardevs.
8226 Members
8228 device: string
8229 The name of the special file for the device, i.e. /dev/ttyS0 on
8230 Unix or COM1: on Windows
8231 The members of ChardevCommon
8233 Since
8235 1.4
8236 ChardevSocket (Object)
8238 Configuration info for (stream) socket chardevs.
8239 Members
8241 addr: SocketAddressLegacy
8242 socket address to listen on (server=true) or connect to
8243 (server=false)
8244 tls-creds: string (optional)
8246 the ID of the TLS credentials object (since 2.6)
8247 tls-authz: string (optional)
8249 the ID of the QAuthZ authorization object against which the
8250 client's x509 distinguished name will be validated. This object
8251 is only resolved at time of use, so can be deleted and recreated
8252 on the fly while the chardev server is active. If missing, it
8253 will default to denying access (since 4.0)
8254 server: boolean (optional)
8256 create server socket (default: true)
8257 wait: boolean (optional)
8259 wait for incoming connection on server sockets (default: false).
8260 Silently ignored with server: false. This use is deprecated.
8261 nodelay: boolean (optional)
8263 set TCP_NODELAY socket option (default: false)
8264 telnet: boolean (optional)
8266 enable telnet protocol on server sockets (default: false)
8267 tn3270: boolean (optional)
8269 enable tn3270 protocol on server sockets (default: false)
8270 (Since: 2.10)
8271 websocket: boolean (optional)
8273 enable websocket protocol on server sockets (default: false)
8274 (Since: 3.1)
8275 reconnect: int (optional)
8277 For a client socket, if a socket is disconnected, then attempt a
8278 reconnect after the given number of seconds. Setting this to
8279 zero disables this function. (default: 0) (Since: 2.2)
8280 The members of ChardevCommon
8282 Since
8284 1.4
8285 ChardevUdp (Object)
8287 Configuration info for datagram socket chardevs.
8288 Members
8290 remote: SocketAddressLegacy
8291 remote address
8292 local: SocketAddressLegacy (optional)
8294 local address
8295 The members of ChardevCommon
8297 Since
8299 1.5
8300 ChardevMux (Object)
8302 Configuration info for mux chardevs.
8303 Members
8305 chardev: string
8306 name of the base chardev.
8307 The members of ChardevCommon
8309 Since
8311 1.5
8312 ChardevStdio (Object)
8314 Configuration info for stdio chardevs.
8315 Members
8317 signal: boolean (optional)
8318 Allow signals (such as SIGINT triggered by ^C) be delivered to
8319 qemu. Default: true.
8320 The members of ChardevCommon
8322 Since
8324 1.5
8325 ChardevSpiceChannel (Object)
8327 Configuration info for spice vm channel chardevs.
8328 Members
8330 type: string
8331 kind of channel (for example vdagent).
8332 The members of ChardevCommon
8334 Since
8336 1.5
8337 If
8339 CONFIG_SPICE
8340 ChardevSpicePort (Object)
8342 Configuration info for spice port chardevs.
8343 Members
8345 fqdn: string
8346 name of the channel (see docs/spice-port-fqdn.txt)
8347 The members of ChardevCommon
8349 Since
8351 1.5
8352 If
8354 CONFIG_SPICE
8355 ChardevVC (Object)
8357 Configuration info for virtual console chardevs.
8358 Members
8360 width: int (optional)
8361 console width, in pixels
8362 height: int (optional)
8364 console height, in pixels
8365 cols: int (optional)
8367 console width, in chars
8368 rows: int (optional)
8370 console height, in chars
8371 The members of ChardevCommon
8373 Since
8375 1.5
8376 ChardevRingbuf (Object)
8378 Configuration info for ring buffer chardevs.
8379 Members
8381 size: int (optional)
8382 ring buffer size, must be power of two, default is 65536
8383 The members of ChardevCommon
8385 Since
8387 1.5
8388 ChardevQemuVDAgent (Object)
8390 Configuration info for qemu vdagent implementation.
8391 Members
8393 mouse: boolean (optional)
8394 enable/disable mouse, default is enabled.
8395 clipboard: boolean (optional)
8397 enable/disable clipboard, default is disabled.
8398 The members of ChardevCommon
8400 Since
8402 6.1
8403 If
8405 CONFIG_SPICE_PROTOCOL
8406 ChardevBackendKind (Enum)
8408 Values
8409 pipe Since 1.5
8410 udp Since 1.5
8412 mux Since 1.5
8414 msmouse
8416 Since 1.5
8417 wctablet
8419 Since 2.9
8420 braille
8422 Since 1.5
8423 testdev
8425 Since 2.2
8426 stdio Since 1.5
8428 console
8430 Since 1.5
8431 spicevmc (If: CONFIG_SPICE)
8433 Since 1.5
8434 spiceport (If: CONFIG_SPICE)
8436 Since 1.5
8437 qemu-vdagent (If: CONFIG_SPICE_PROTOCOL)
8439 Since 6.1
8440 vc v1.5
8442 ringbuf
8444 Since 1.6
8445 memory Since 1.5
8447 file Not documented
8449 serial Not documented
8451 parallel
8453 Not documented
8454 socket Not documented
8456 pty Not documented
8458 null Not documented
8460 Since
8462 1.4
8463 ChardevFileWrapper (Object)
8465 Members
8466 data: ChardevFile
8467 Not documented
8468 Since
8470 1.4
8471 ChardevHostdevWrapper (Object)
8473 Members
8474 data: ChardevHostdev
8475 Not documented
8476 Since
8478 1.4
8479 ChardevSocketWrapper (Object)
8481 Members
8482 data: ChardevSocket
8483 Not documented
8484 Since
8486 1.4
8487 ChardevUdpWrapper (Object)
8489 Members
8490 data: ChardevUdp
8491 Not documented
8492 Since
8494 1.5
8495 ChardevCommonWrapper (Object)
8497 Members
8498 data: ChardevCommon
8499 Not documented
8500 Since
8502 2.6
8503 ChardevMuxWrapper (Object)
8505 Members
8506 data: ChardevMux
8507 Not documented
8508 Since
8510 1.5
8511 ChardevStdioWrapper (Object)
8513 Members
8514 data: ChardevStdio
8515 Not documented
8516 Since
8518 1.5
8519 ChardevSpiceChannelWrapper (Object)
8521 Members
8522 data: ChardevSpiceChannel
8523 Not documented
8524 Since
8526 1.5
8527 If
8529 CONFIG_SPICE
8530 ChardevSpicePortWrapper (Object)
8532 Members
8533 data: ChardevSpicePort
8534 Not documented
8535 Since
8537 1.5
8538 If
8540 CONFIG_SPICE
8541 ChardevQemuVDAgentWrapper (Object)
8543 Members
8544 data: ChardevQemuVDAgent
8545 Not documented
8546 Since
8548 6.1
8549 If
8551 CONFIG_SPICE_PROTOCOL
8552 ChardevVCWrapper (Object)
8554 Members
8555 data: ChardevVC
8556 Not documented
8557 Since
8559 1.5
8560 ChardevRingbufWrapper (Object)
8562 Members
8563 data: ChardevRingbuf
8564 Not documented
8565 Since
8567 1.5
8568 ChardevBackend (Object)
8570 Configuration info for the new chardev backend.
8571 Members
8573 type: ChardevBackendKind
8574 Not documented
8575 The members of ChardevFileWrapper when type is "file"
8577 The members of ChardevHostdevWrapper when type is "serial"
8579 The members of ChardevHostdevWrapper when type is "parallel"
8581 The members of ChardevHostdevWrapper when type is "pipe"
8583 The members of ChardevSocketWrapper when type is "socket"
8585 The members of ChardevUdpWrapper when type is "udp"
8587 The members of ChardevCommonWrapper when type is "pty"
8589 The members of ChardevCommonWrapper when type is "null"
8591 The members of ChardevMuxWrapper when type is "mux"
8593 The members of ChardevCommonWrapper when type is "msmouse"
8595 The members of ChardevCommonWrapper when type is "wctablet"
8597 The members of ChardevCommonWrapper when type is "braille"
8599 The members of ChardevCommonWrapper when type is "testdev"
8601 The members of ChardevStdioWrapper when type is "stdio"
8603 The members of ChardevCommonWrapper when type is "console"
8605 The members of ChardevSpiceChannelWrapper when type is "spicevmc" (If:
8607 CONFIG_SPICE)
8608 The members of ChardevSpicePortWrapper when type is "spiceport" (If:
8610 CONFIG_SPICE)
8611 The members of ChardevQemuVDAgentWrapper when type is "qemu-vdagent"
8613 (If: CONFIG_SPICE_PROTOCOL)
8614 The members of ChardevVCWrapper when type is "vc"
8616 The members of ChardevRingbufWrapper when type is "ringbuf"
8618 The members of ChardevRingbufWrapper when type is "memory"
8620 Since
8622 1.4
8623 ChardevReturn (Object)
8625 Return info about the chardev backend just created.
8626 Members
8628 pty: string (optional)
8629 name of the slave pseudoterminal device, present if and only if
8630 a chardev of type 'pty' was created
8631 Since
8633 1.4
8634 chardev-add (Command)
8636 Add a character device backend
8637 Arguments
8639 id: string
8640 the chardev's ID, must be unique
8641 backend: ChardevBackend
8643 backend type and parameters
8644 Returns
8646 ChardevReturn.
8647 Since
8649 1.4
8650 Example
8652 -> { "execute" : "chardev-add",
8653 "arguments" : { "id" : "foo",
8654 "backend" : { "type" : "null", "data" : {} } } }
8655 <- { "return": {} }
8656 -> { "execute" : "chardev-add",
8658 "arguments" : { "id" : "bar",
8659 "backend" : { "type" : "file",
8660 "data" : { "out" : "/tmp/bar.log" } } } }
8661 <- { "return": {} }
8662 -> { "execute" : "chardev-add",
8664 "arguments" : { "id" : "baz",
8665 "backend" : { "type" : "pty", "data" : {} } } }
8666 <- { "return": { "pty" : "/dev/pty/42" } }
8667 chardev-change (Command)
8669 Change a character device backend
8670 Arguments
8672 id: string
8673 the chardev's ID, must exist
8674 backend: ChardevBackend
8676 new backend type and parameters
8677 Returns
8679 ChardevReturn.
8680 Since
8682 2.10
8683 Example
8685 -> { "execute" : "chardev-change",
8686 "arguments" : { "id" : "baz",
8687 "backend" : { "type" : "pty", "data" : {} } } }
8688 <- { "return": { "pty" : "/dev/pty/42" } }
8689 -> {"execute" : "chardev-change",
8691 "arguments" : {
8692 "id" : "charchannel2",
8693 "backend" : {
8694 "type" : "socket",
8695 "data" : {
8696 "addr" : {
8697 "type" : "unix" ,
8698 "data" : {
8699 "path" : "/tmp/charchannel2.socket"
8700 }
8701 },
8702 "server" : true,
8703 "wait" : false }}}}
8704 <- {"return": {}}
8705 chardev-remove (Command)
8707 Remove a character device backend
8708 Arguments
8710 id: string
8711 the chardev's ID, must exist and not be in use
8712 Returns
8714 Nothing on success
8715 Since
8717 1.4
8718 Example
8720 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
8721 <- { "return": {} }
8722 chardev-send-break (Command)
8724 Send a break to a character device
8725 Arguments
8727 id: string
8728 the chardev's ID, must exist
8729 Returns
8731 Nothing on success
8732 Since
8734 2.10
8735 Example
8737 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
8738 <- { "return": {} }
8739 VSERPORT_CHANGE (Event)
8741 Emitted when the guest opens or closes a virtio-serial port.
8742 Arguments
8744 id: string
8745 device identifier of the virtio-serial port
8746 open: boolean
8748 true if the guest has opened the virtio-serial port
8749 Note
8751 This event is rate-limited.
8752 Since
8754 2.1
8755 Example
8757 <- { "event": "VSERPORT_CHANGE",
8758 "data": { "id": "channel0", "open": true },
8759 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
8760
8762 qmp_capabilities (Command)
8763 Enable QMP capabilities.
8764 Arguments:
8766 Arguments
8768 enable: array of QMPCapability (optional)
8769 An optional list of QMPCapability values to enable. The client
8770 must not enable any capability that is not mentioned in the QMP
8771 greeting message. If the field is not provided, it means no QMP
8772 capabilities will be enabled. (since 2.12)
8773 Example
8775 -> { "execute": "qmp_capabilities",
8776 "arguments": { "enable": [ "oob" ] } }
8777 <- { "return": {} }
8778 Notes
8780 This command is valid exactly when first connecting: it must be issued
8781 before any other command will be accepted, and will fail once the moni‐
8782 tor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
8783 The QMP client needs to explicitly enable QMP capabilities, otherwise
8785 all the QMP capabilities will be turned off by default.
8786 Since
8788 0.13
8789 QMPCapability (Enum)
8791 Enumeration of capabilities to be advertised during initial client con‐
8792 nection, used for agreeing on particular QMP extension behaviors.
8793 Values
8795 oob QMP ability to support out-of-band requests. (Please refer to
8796 qmp-spec.txt for more information on OOB)
8797 Since
8799 2.12
8800 VersionTriple (Object)
8802 A three-part version number.
8803 Members
8805 major: int
8806 The major version number.
8807 minor: int
8809 The minor version number.
8810 micro: int
8812 The micro version number.
8813 Since
8815 2.4
8816 VersionInfo (Object)
8818 A description of QEMU's version.
8819 Members
8821 qemu: VersionTriple
8822 The version of QEMU. By current convention, a micro version of
8823 50 signifies a development branch. A micro version greater than
8824 or equal to 90 signifies a release candidate for the next minor
8825 version. A micro version of less than 50 signifies a stable re‐
8826 lease.
8827 package: string
8829 QEMU will always set this field to an empty string. Downstream
8830 versions of QEMU should set this to a non-empty string. The ex‐
8831 act format depends on the downstream however it highly recom‐
8832 mended that a unique name is used.
8833 Since
8835 0.14
8836 query-version (Command)
8838 Returns the current version of QEMU.
8839 Returns
8841 A VersionInfo object describing the current version of QEMU.
8842 Since
8844 0.14
8845 Example
8847 -> { "execute": "query-version" }
8848 <- {
8849 "return":{
8850 "qemu":{
8851 "major":0,
8852 "minor":11,
8853 "micro":5
8854 },
8855 "package":""
8856 }
8857 }
8858 CommandInfo (Object)
8860 Information about a QMP command
8861 Members
8863 name: string
8864 The command name
8865 Since
8867 0.14
8868 query-commands (Command)
8870 Return a list of supported QMP commands by this server
8871 Returns
8873 A list of CommandInfo for all supported commands
8874 Since
8876 0.14
8877 Example
8879 -> { "execute": "query-commands" }
8880 <- {
8881 "return":[
8882 {
8883 "name":"query-balloon"
8884 },
8885 {
8886 "name":"system_powerdown"
8887 }
8888 ]
8889 }
8890 Note
8892 This example has been shortened as the real response is too long.
8893 quit (Command)
8895 This command will cause the QEMU process to exit gracefully. While ev‐
8896 ery attempt is made to send the QMP response before terminating, this
8897 is not guaranteed. When using this interface, a premature EOF would
8898 not be unexpected.
8899 Since
8901 0.14
8902 Example
8904 -> { "execute": "quit" }
8905 <- { "return": {} }
8906 MonitorMode (Enum)
8908 An enumeration of monitor modes.
8909 Values
8911 readline
8912 HMP monitor (human-oriented command line interface)
8913 control
8915 QMP monitor (JSON-based machine interface)
8916 Since
8918 5.0
8919 MonitorOptions (Object)
8921 Options to be used for adding a new monitor.
8922 Members
8924 id: string (optional)
8925 Name of the monitor
8926 mode: MonitorMode (optional)
8928 Selects the monitor mode (default: readline in the system emula‐
8929 tor, control in qemu-storage-daemon)
8930 pretty: boolean (optional)
8932 Enables pretty printing (QMP only)
8933 chardev: string
8935 Name of a character device to expose the monitor on
8936 Since
8938 5.0
8939
8941 query-qmp-schema (Command)
8942 Command query-qmp-schema exposes the QMP wire ABI as an array of
8943 SchemaInfo. This lets QMP clients figure out what commands and events
8944 are available in this QEMU, and their parameters and results.
8945 However, the SchemaInfo can't reflect all the rules and restrictions
8947 that apply to QMP. It's interface introspection (figuring out what's
8948 there), not interface specification. The specification is in the QAPI
8949 schema.
8950 Furthermore, while we strive to keep the QMP wire format backwards-com‐
8952 patible across qemu versions, the introspection output is not guaran‐
8953 teed to have the same stability. For example, one version of qemu may
8954 list an object member as an optional non-variant, while another lists
8955 the same member only through the object's variants; or the type of a
8956 member may change from a generic string into a specific enum or from
8957 one specific type into an alternate that includes the original type
8958 alongside something else.
8959 Returns
8961 array of SchemaInfo, where each element describes an entity in the ABI:
8962 command, event, type, ...
8963 The order of the various SchemaInfo is unspecified; however, all names
8965 are guaranteed to be unique (no name will be duplicated with different
8966 meta-types).
8967 Note
8969 the QAPI schema is also used to help define internal interfaces, by
8970 defining QAPI types. These are not part of the QMP wire ABI, and
8971 therefore not returned by this command.
8972 Since
8974 2.5
8975 SchemaMetaType (Enum)
8977 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
8978 Values
8980 builtin
8981 a predefined type such as 'int' or 'bool'.
8982 enum an enumeration type
8984 array an array type
8986 object an object type (struct or union)
8988 alternate
8990 an alternate type
8991 command
8993 a QMP command
8994 event a QMP event
8996 Since
8998 2.5
8999 SchemaInfo (Object)
9001 Members
9002 name: string
9003 the entity's name, inherited from base. The SchemaInfo is al‐
9004 ways referenced by this name. Commands and events have the name
9005 defined in the QAPI schema. Unlike command and event names,
9006 type names are not part of the wire ABI. Consequently, type
9007 names are meaningless strings here, although they are still
9008 guaranteed unique regardless of meta-type.
9009 meta-type: SchemaMetaType
9011 the entity's meta type, inherited from base.
9012 features: array of string (optional)
9014 names of features associated with the entity, in no particular
9015 order. (since 4.1 for object types, 4.2 for commands, 5.0 for
9016 the rest)
9017 The members of SchemaInfoBuiltin when meta-type is "builtin"
9019 The members of SchemaInfoEnum when meta-type is "enum"
9021 The members of SchemaInfoArray when meta-type is "array"
9023 The members of SchemaInfoObject when meta-type is "object"
9025 The members of SchemaInfoAlternate when meta-type is "alternate"
9027 The members of SchemaInfoCommand when meta-type is "command"
9029 The members of SchemaInfoEvent when meta-type is "event"
9031 Additional members depend on the value of meta-type.
9032 Since
9034 2.5
9035 SchemaInfoBuiltin (Object)
9037 Additional SchemaInfo members for meta-type 'builtin'.
9038 Members
9040 json-type: JSONType
9041 the JSON type used for this type on the wire.
9042 Since
9044 2.5
9045 JSONType (Enum)
9047 The four primitive and two structured types according to RFC 8259 sec‐
9048 tion 1, plus 'int' (split off 'number'), plus the obvious top type
9049 'value'.
9050 Values
9052 string Not documented
9053 number Not documented
9055 int Not documented
9057 boolean
9059 Not documented
9060 null Not documented
9062 object Not documented
9064 array Not documented
9066 value Not documented
9068 Since
9070 2.5
9071 SchemaInfoEnum (Object)
9073 Additional SchemaInfo members for meta-type 'enum'.
9074 Members
9076 members: array of SchemaInfoEnumMember
9077 the enum type's members, in no particular order (since 6.2).
9078 values: array of string
9080 the enumeration type's member names, in no particular order.
9081 Redundant with members. Just for backward compatibility.
9082 Features
9084 deprecated
9085 Member values is deprecated. Use members instead.
9086 Values of this type are JSON string on the wire.
9087 Since
9089 2.5
9090 SchemaInfoEnumMember (Object)
9092 An object member.
9093 Members
9095 name: string
9096 the member's name, as defined in the QAPI schema.
9097 features: array of string (optional)
9099 names of features associated with the member, in no particular
9100 order.
9101 Since
9103 6.2
9104 SchemaInfoArray (Object)
9106 Additional SchemaInfo members for meta-type 'array'.
9107 Members
9109 element-type: string
9110 the array type's element type.
9111 Values of this type are JSON array on the wire.
9112 Since
9114 2.5
9115 SchemaInfoObject (Object)
9117 Additional SchemaInfo members for meta-type 'object'.
9118 Members
9120 members: array of SchemaInfoObjectMember
9121 the object type's (non-variant) members, in no particular order.
9122 tag: string (optional)
9124 the name of the member serving as type tag. An element of mem‐
9125 bers with this name must exist.
9126 variants: array of SchemaInfoObjectVariant (optional)
9128 variant members, i.e. additional members that depend on the type
9129 tag's value. Present exactly when tag is present. The variants
9130 are in no particular order, and may even differ from the order
9131 of the values of the enum type of the tag.
9132 Values of this type are JSON object on the wire.
9133 Since
9135 2.5
9136 SchemaInfoObjectMember (Object)
9138 An object member.
9139 Members
9141 name: string
9142 the member's name, as defined in the QAPI schema.
9143 type: string
9145 the name of the member's type.
9146 default: value (optional)
9148 default when used as command parameter. If absent, the parame‐
9149 ter is mandatory. If present, the value must be null. The pa‐
9150 rameter is optional, and behavior when it's missing is not spec‐
9151 ified here. Future extension: if present and non-null, the pa‐
9152 rameter is optional, and defaults to this value.
9153 features: array of string (optional)
9155 names of features associated with the member, in no particular
9156 order. (since 5.0)
9157 Since
9159 2.5
9160 SchemaInfoObjectVariant (Object)
9162 The variant members for a value of the type tag.
9163 Members
9165 case: string
9166 a value of the type tag.
9167 type: string
9169 the name of the object type that provides the variant members
9170 when the type tag has value case.
9171 Since
9173 2.5
9174 SchemaInfoAlternate (Object)
9176 Additional SchemaInfo members for meta-type 'alternate'.
9177 Members
9179 members: array of SchemaInfoAlternateMember
9180 the alternate type's members, in no particular order. The mem‐
9181 bers' wire encoding is distinct, see docs/de‐
9182 vel/qapi-code-gen.txt section Alternate types.
9183 On the wire, this can be any of the members.
9184 Since
9186 2.5
9187 SchemaInfoAlternateMember (Object)
9189 An alternate member.
9190 Members
9192 type: string
9193 the name of the member's type.
9194 Since
9196 2.5
9197 SchemaInfoCommand (Object)
9199 Additional SchemaInfo members for meta-type 'command'.
9200 Members
9202 arg-type: string
9203 the name of the object type that provides the command's parame‐
9204 ters.
9205 ret-type: string
9207 the name of the command's result type.
9208 allow-oob: boolean (optional)
9210 whether the command allows out-of-band execution, defaults to
9211 false (Since: 2.12)
9212 TODO
9214 success-response (currently irrelevant, because it's QGA, not QMP)
9215 Since
9217 2.5
9218 SchemaInfoEvent (Object)
9220 Additional SchemaInfo members for meta-type 'event'.
9221 Members
9223 arg-type: string
9224 the name of the object type that provides the event's parame‐
9225 ters.
9226 Since
9228 2.5
9229
9231 QAuthZListPolicy (Enum)
9232 The authorization policy result
9233 Values
9235 deny deny access
9236 allow allow access
9238 Since
9240 4.0
9241 QAuthZListFormat (Enum)
9243 The authorization policy match format
9244 Values
9246 exact an exact string match
9247 glob string with ? and * shell wildcard support
9249 Since
9251 4.0
9252 QAuthZListRule (Object)
9254 A single authorization rule.
9255 Members
9257 match: string
9258 a string or glob to match against a user identity
9259 policy: QAuthZListPolicy
9261 the result to return if match evaluates to true
9262 format: QAuthZListFormat (optional)
9264 the format of the match rule (default 'exact')
9265 Since
9267 4.0
9268 AuthZListProperties (Object)
9270 Properties for authz-list objects.
9271 Members
9273 policy: QAuthZListPolicy (optional)
9274 Default policy to apply when no rule matches (default: deny)
9275 rules: array of QAuthZListRule (optional)
9277 Authorization rules based on matching user
9278 Since
9280 4.0
9281 AuthZListFileProperties (Object)
9283 Properties for authz-listfile objects.
9284 Members
9286 filename: string
9287 File name to load the configuration from. The file must contain
9288 valid JSON for AuthZListProperties.
9289 refresh: boolean (optional)
9291 If true, inotify is used to monitor the file, automatically
9292 reloading changes. If an error occurs during reloading, all au‐
9293 thorizations will fail until the file is next successfully
9294 loaded. (default: true if the binary was built with CONFIG_INO‐
9295 TIFY1, false otherwise)
9296 Since
9298 4.0
9299 AuthZPAMProperties (Object)
9301 Properties for authz-pam objects.
9302 Members
9304 service: string
9305 PAM service name to use for authorization
9306 Since
9308 4.0
9309 AuthZSimpleProperties (Object)
9311 Properties for authz-simple objects.
9312 Members
9314 identity: string
9315 Identifies the allowed user. Its format depends on the network
9316 service that authorization object is associated with. For autho‐
9317 rizing based on TLS x509 certificates, the identity must be the
9318 x509 distinguished name.
9319 Since
9321 4.0
9322
9324 ObjectPropertyInfo (Object)
9325 Members
9326 name: string
9327 the name of the property
9328 type: string
9330 the type of the property. This will typically come in one of
9331 four forms:
9332 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
9334 ble'. These types are mapped to the appropriate JSON type.
9335 2. A child type in the form 'child<subtype>' where subtype is a
9337 qdev device type name. Child properties create the composi‐
9338 tion tree.
9339 3. A link type in the form 'link<subtype>' where subtype is a
9341 qdev device type name. Link properties form the device model
9342 graph.
9343 description: string (optional)
9345 if specified, the description of the property.
9346 default-value: value (optional)
9348 the default value, if any (since 5.0)
9349 Since
9351 1.2
9352 qom-list (Command)
9354 This command will list any properties of a object given a path in the
9355 object model.
9356 Arguments
9358 path: string
9359 the path within the object model. See qom-get for a description
9360 of this parameter.
9361 Returns
9363 a list of ObjectPropertyInfo that describe the properties of the ob‐
9364 ject.
9365 Since
9367 1.2
9368 Example
9370 -> { "execute": "qom-list",
9371 "arguments": { "path": "/chardevs" } }
9372 <- { "return": [ { "name": "type", "type": "string" },
9373 { "name": "parallel0", "type": "child<chardev-vc>" },
9374 { "name": "serial0", "type": "child<chardev-vc>" },
9375 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
9376 qom-get (Command)
9378 This command will get a property from a object model path and return
9379 the value.
9380 Arguments
9382 path: string
9383 The path within the object model. There are two forms of sup‐
9384 ported paths--absolute and partial paths.
9385 Absolute paths are derived from the root object and can follow
9387 child<> or link<> properties. Since they can follow link<>
9388 properties, they can be arbitrarily long. Absolute paths look
9389 like absolute filenames and are prefixed with a leading slash.
9390 Partial paths look like relative filenames. They do not begin
9392 with a prefix. The matching rules for partial paths are subtle
9393 but designed to make specifying objects easy. At each level of
9394 the composition tree, the partial path is matched as an absolute
9395 path. The first match is not returned. At least two matches
9396 are searched for. A successful result is only returned if only
9397 one match is found. If more than one match is found, a flag is
9398 return to indicate that the match was ambiguous.
9399 property: string
9401 The property name to read
9402 Returns
9404 The property value. The type depends on the property type. child<> and
9405 link<> properties are returned as #str pathnames. All integer property
9406 types (u8, u16, etc) are returned as #int.
9407 Since
9409 1.2
9410 Example
9412 1. Use absolute path
9413 -> { "execute": "qom-get",
9415 "arguments": { "path": "/machine/unattached/device[0]",
9416 "property": "hotplugged" } }
9417 <- { "return": false }
9418 2. Use partial path
9420 -> { "execute": "qom-get",
9422 "arguments": { "path": "unattached/sysbus",
9423 "property": "type" } }
9424 <- { "return": "System" }
9425 qom-set (Command)
9427 This command will set a property from a object model path.
9428 Arguments
9430 path: string
9431 see qom-get for a description of this parameter
9432 property: string
9434 the property name to set
9435 value: value
9437 a value who's type is appropriate for the property type. See
9438 qom-get for a description of type mapping.
9439 Since
9441 1.2
9442 Example
9444 -> { "execute": "qom-set",
9445 "arguments": { "path": "/machine",
9446 "property": "graphics",
9447 "value": false } }
9448 <- { "return": {} }
9449 ObjectTypeInfo (Object)
9451 This structure describes a search result from qom-list-types
9452 Members
9454 name: string
9455 the type name found in the search
9456 abstract: boolean (optional)
9458 the type is abstract and can't be directly instantiated. Omit‐
9459 ted if false. (since 2.10)
9460 parent: string (optional)
9462 Name of parent type, if any (since 2.10)
9463 Since
9465 1.1
9466 qom-list-types (Command)
9468 This command will return a list of types given search parameters
9469 Arguments
9471 implements: string (optional)
9472 if specified, only return types that implement this type name
9473 abstract: boolean (optional)
9475 if true, include abstract types in the results
9476 Returns
9478 a list of ObjectTypeInfo or an empty list if no results are found
9479 Since
9481 1.1
9482 qom-list-properties (Command)
9484 List properties associated with a QOM object.
9485 Arguments
9487 typename: string
9488 the type name of an object
9489 Note
9491 objects can create properties at runtime, for example to describe links
9492 between different devices and/or objects. These properties are not in‐
9493 cluded in the output of this command.
9494 Returns
9496 a list of ObjectPropertyInfo describing object properties
9497 Since
9499 2.12
9500 CanHostSocketcanProperties (Object)
9502 Properties for can-host-socketcan objects.
9503 Members
9505 if: string
9506 interface name of the host system CAN bus to connect to
9507 canbus: string
9509 object ID of the can-bus object to connect to the host interface
9510 Since
9512 2.12
9513 ColoCompareProperties (Object)
9515 Properties for colo-compare objects.
9516 Members
9518 primary_in: string
9519 name of the character device backend to use for the primary in‐
9520 put (incoming packets are redirected to outdev)
9521 secondary_in: string
9523 name of the character device backend to use for secondary input
9524 (incoming packets are only compared to the input on primary_in
9525 and then dropped)
9526 outdev: string
9528 name of the character device backend to use for output
9529 iothread: string
9531 name of the iothread to run in
9532 notify_dev: string (optional)
9534 name of the character device backend to be used to communicate
9535 with the remote colo-frame (only for Xen COLO)
9536 compare_timeout: int (optional)
9538 the maximum time to hold a packet from primary_in for comparison
9539 with an incoming packet on secondary_in in milliseconds (de‐
9540 fault: 3000)
9541 expired_scan_cycle: int (optional)
9543 the interval at which colo-compare checks whether packets from
9544 primary have timed out, in milliseconds (default: 3000)
9545 max_queue_size: int (optional)
9547 the maximum number of packets to keep in the queue for comparing
9548 with incoming packets from secondary_in. If the queue is full
9549 and additional packets are received, the additional packets are
9550 dropped. (default: 1024)
9551 vnet_hdr_support: boolean (optional)
9553 if true, vnet header support is enabled (default: false)
9554 Since
9556 2.8
9557 CryptodevBackendProperties (Object)
9559 Properties for cryptodev-backend and cryptodev-backend-builtin objects.
9560 Members
9562 queues: int (optional)
9563 the number of queues for the cryptodev backend. Ignored for
9564 cryptodev-backend and must be 1 for cryptodev-backend-builtin.
9565 (default: 1)
9566 Since
9568 2.8
9569 CryptodevVhostUserProperties (Object)
9571 Properties for cryptodev-vhost-user objects.
9572 Members
9574 chardev: string
9575 the name of a Unix domain socket character device that connects
9576 to the vhost-user server
9577 The members of CryptodevBackendProperties
9579 Since
9581 2.12
9582 DBusVMStateProperties (Object)
9584 Properties for dbus-vmstate objects.
9585 Members
9587 addr: string
9588 the name of the DBus bus to connect to
9589 id-list: string (optional)
9591 a comma separated list of DBus IDs of helpers whose data should
9592 be included in the VM state on migration
9593 Since
9595 5.0
9596 NetfilterInsert (Enum)
9598 Indicates where to insert a netfilter relative to a given other filter.
9599 Values
9601 before insert before the specified filter
9602 behind insert behind the specified filter
9604 Since
9606 5.0
9607 NetfilterProperties (Object)
9609 Properties for objects of classes derived from netfilter.
9610 Members
9612 netdev: string
9613 id of the network device backend to filter
9614 queue: NetFilterDirection (optional)
9616 indicates which queue(s) to filter (default: all)
9617 status: string (optional)
9619 indicates whether the filter is enabled ("on") or disabled
9620 ("off") (default: "on")
9621 position: string (optional)
9623 specifies where the filter should be inserted in the filter
9624 list. "head" means the filter is inserted at the head of the
9625 filter list, before any existing filters. "tail" means the fil‐
9626 ter is inserted at the tail of the filter list, behind any ex‐
9627 isting filters (default). "id=<id>" means the filter is in‐
9628 serted before or behind the filter specified by <id>, depending
9629 on the insert property. (default: "tail")
9630 insert: NetfilterInsert (optional)
9632 where to insert the filter relative to the filter given in posi‐
9633 tion. Ignored if position is "head" or "tail". (default: be‐
9634 hind)
9635 Since
9637 2.5
9638 FilterBufferProperties (Object)
9640 Properties for filter-buffer objects.
9641 Members
9643 interval: int
9644 a non-zero interval in microseconds. All packets arriving in
9645 the given interval are delayed until the end of the interval.
9646 The members of NetfilterProperties
9648 Since
9650 2.5
9651 FilterDumpProperties (Object)
9653 Properties for filter-dump objects.
9654 Members
9656 file: string
9657 the filename where the dumped packets should be stored
9658 maxlen: int (optional)
9660 maximum number of bytes in a packet that are stored (default:
9661 65536)
9662 The members of NetfilterProperties
9664 Since
9666 2.5
9667 FilterMirrorProperties (Object)
9669 Properties for filter-mirror objects.
9670 Members
9672 outdev: string
9673 the name of a character device backend to which all incoming
9674 packets are mirrored
9675 vnet_hdr_support: boolean (optional)
9677 if true, vnet header support is enabled (default: false)
9678 The members of NetfilterProperties
9680 Since
9682 2.6
9683 FilterRedirectorProperties (Object)
9685 Properties for filter-redirector objects.
9686 At least one of indev or outdev must be present. If both are present,
9688 they must not refer to the same character device backend.
9689 Members
9691 indev: string (optional)
9692 the name of a character device backend from which packets are
9693 received and redirected to the filtered network device
9694 outdev: string (optional)
9696 the name of a character device backend to which all incoming
9697 packets are redirected
9698 vnet_hdr_support: boolean (optional)
9700 if true, vnet header support is enabled (default: false)
9701 The members of NetfilterProperties
9703 Since
9705 2.6
9706 FilterRewriterProperties (Object)
9708 Properties for filter-rewriter objects.
9709 Members
9711 vnet_hdr_support: boolean (optional)
9712 if true, vnet header support is enabled (default: false)
9713 The members of NetfilterProperties
9715 Since
9717 2.8
9718 InputBarrierProperties (Object)
9720 Properties for input-barrier objects.
9721 Members
9723 name: string
9724 the screen name as declared in the screens section of bar‐
9725 rier.conf
9726 server: string (optional)
9728 hostname of the Barrier server (default: "localhost")
9729 port: string (optional)
9731 TCP port of the Barrier server (default: "24800")
9732 x-origin: string (optional)
9734 x coordinate of the leftmost pixel on the guest screen (default:
9735 "0")
9736 y-origin: string (optional)
9738 y coordinate of the topmost pixel on the guest screen (default:
9739 "0")
9740 width: string (optional)
9742 the width of secondary screen in pixels (default: "1920")
9743 height: string (optional)
9745 the height of secondary screen in pixels (default: "1080")
9746 Since
9748 4.2
9749 InputLinuxProperties (Object)
9751 Properties for input-linux objects.
9752 Members
9754 evdev: string
9755 the path of the host evdev device to use
9756 grab_all: boolean (optional)
9758 if true, grab is toggled for all devices (e.g. both keyboard and
9759 mouse) instead of just one device (default: false)
9760 repeat: boolean (optional)
9762 enables auto-repeat events (default: false)
9763 grab-toggle: GrabToggleKeys (optional)
9765 the key or key combination that toggles device grab (default:
9766 ctrl-ctrl)
9767 Since
9769 2.6
9770 IothreadProperties (Object)
9772 Properties for iothread objects.
9773 Members
9775 poll-max-ns: int (optional)
9776 the maximum number of nanoseconds to busy wait for events. 0
9777 means polling is disabled (default: 32768 on POSIX hosts, 0 oth‐
9778 erwise)
9779 poll-grow: int (optional)
9781 the multiplier used to increase the polling time when the algo‐
9782 rithm detects it is missing events due to not polling long
9783 enough. 0 selects a default behaviour (default: 0)
9784 poll-shrink: int (optional)
9786 the divisor used to decrease the polling time when the algorithm
9787 detects it is spending too long polling without encountering
9788 events. 0 selects a default behaviour (default: 0)
9789 aio-max-batch: int (optional)
9791 maximum number of requests in a batch for the AIO engine, 0
9792 means that the engine will use its default (default:0, since
9793 6.1)
9794 Since
9796 2.0
9797 MemoryBackendProperties (Object)
9799 Properties for objects of classes derived from memory-backend.
9800 Members
9802 merge: boolean (optional)
9803 if true, mark the memory as mergeable (default depends on the
9804 machine type)
9805 dump: boolean (optional)
9807 if true, include the memory in core dumps (default depends on
9808 the machine type)
9809 host-nodes: array of int (optional)
9811 the list of NUMA host nodes to bind the memory to
9812 policy: HostMemPolicy (optional)
9814 the NUMA policy (default: 'default')
9815 prealloc: boolean (optional)
9817 if true, preallocate memory (default: false)
9818 prealloc-threads: int (optional)
9820 number of CPU threads to use for prealloc (default: 1)
9821 share: boolean (optional)
9823 if false, the memory is private to QEMU; if true, it is shared
9824 (default: false)
9825 reserve: boolean (optional)
9827 if true, reserve swap space (or huge pages) if applicable (de‐
9828 fault: true) (since 6.1)
9829 size: int
9831 size of the memory region in bytes
9832 x-use-canonical-path-for-ramblock-id: boolean (optional)
9834 if true, the canoncial path is used for ramblock-id. Disable
9835 this for 4.0 machine types or older to allow migration with
9836 newer QEMU versions. (default: false generally, but true for
9837 machine types <= 4.0)
9838 Note
9840 prealloc=true and reserve=false cannot be set at the same time. With
9841 reserve=true, the behavior depends on the operating system: for exam‐
9842 ple, Linux will not reserve swap space for shared file mappings -- "not
9843 applicable". In contrast, reserve=false will bail out if it cannot be
9844 configured accordingly.
9845 Since
9847 2.1
9848 MemoryBackendFileProperties (Object)
9850 Properties for memory-backend-file objects.
9851 Members
9853 align: int (optional)
9854 the base address alignment when QEMU mmap(2)s mem-path. Some
9855 backend stores specified by mem-path require an alignment dif‐
9856 ferent than the default one used by QEMU, e.g. the device DAX
9857 /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
9858 users can specify the required alignment via this option. 0 se‐
9859 lects a default alignment (currently the page size). (default:
9860 0)
9861 discard-data: boolean (optional)
9863 if true, the file contents can be destroyed when QEMU exits, to
9864 avoid unnecessarily flushing data to the backing file. Note that
9865 discard-data is only an optimization, and QEMU might not discard
9866 file contents if it aborts unexpectedly or is terminated using
9867 SIGKILL. (default: false)
9868 mem-path: string
9870 the path to either a shared memory or huge page filesystem mount
9871 pmem: boolean (optional) (If: CONFIG_LIBPMEM)
9873 specifies whether the backing file specified by mem-path is in
9874 host persistent memory that can be accessed using the SNIA NVM
9875 programming model (e.g. Intel NVDIMM).
9876 readonly: boolean (optional)
9878 if true, the backing file is opened read-only; if false, it is
9879 opened read-write. (default: false)
9880 The members of MemoryBackendProperties
9882 Since
9884 2.1
9885 MemoryBackendMemfdProperties (Object)
9887 Properties for memory-backend-memfd objects.
9888 The share boolean option is true by default with memfd.
9890 Members
9892 hugetlb: boolean (optional)
9893 if true, the file to be created resides in the hugetlbfs
9894 filesystem (default: false)
9895 hugetlbsize: int (optional)
9897 the hugetlb page size on systems that support multiple hugetlb
9898 page sizes (it must be a power of 2 value supported by the sys‐
9899 tem). 0 selects a default page size. This option is ignored if
9900 hugetlb is false. (default: 0)
9901 seal: boolean (optional)
9903 if true, create a sealed-file, which will block further resizing
9904 of the memory (default: true)
9905 The members of MemoryBackendProperties
9907 Since
9909 2.12
9910 MemoryBackendEpcProperties (Object)
9912 Properties for memory-backend-epc objects.
9913 The share boolean option is true by default with epc
9915 The merge boolean option is false by default with epc
9917 The dump boolean option is false by default with epc
9919 Members
9921 The members of MemoryBackendProperties
9922 Since
9924 6.2
9925 PrManagerHelperProperties (Object)
9927 Properties for pr-manager-helper objects.
9928 Members
9930 path: string
9931 the path to a Unix domain socket for connecting to the external
9932 helper
9933 Since
9935 2.11
9936 QtestProperties (Object)
9938 Properties for qtest objects.
9939 Members
9941 chardev: string
9942 the chardev to be used to receive qtest commands on.
9943 log: string (optional)
9945 the path to a log file
9946 Since
9948 6.0
9949 RemoteObjectProperties (Object)
9951 Properties for x-remote-object objects.
9952 Members
9954 fd: string
9955 file descriptor name previously passed via 'getfd' command
9956 devid: string
9958 the id of the device to be associated with the file descriptor
9959 Since
9961 6.0
9962 RngProperties (Object)
9964 Properties for objects of classes derived from rng.
9965 Members
9967 opened: boolean (optional)
9968 if true, the device is opened immediately when applying this op‐
9969 tion and will probably fail when processing the next option.
9970 Don't use; only provided for compatibility. (default: false)
9971 Features
9973 deprecated
9974 Member opened is deprecated. Setting true doesn't make sense,
9975 and false is already the default.
9976 Since
9978 1.3
9979 RngEgdProperties (Object)
9981 Properties for rng-egd objects.
9982 Members
9984 chardev: string
9985 the name of a character device backend that provides the connec‐
9986 tion to the RNG daemon
9987 The members of RngProperties
9989 Since
9991 1.3
9992 RngRandomProperties (Object)
9994 Properties for rng-random objects.
9995 Members
9997 filename: string (optional)
9998 the filename of the device on the host to obtain entropy from
9999 (default: "/dev/urandom")
10000 The members of RngProperties
10002 Since
10004 1.3
10005 SevGuestProperties (Object)
10007 Properties for sev-guest objects.
10008 Members
10010 sev-device: string (optional)
10011 SEV device to use (default: "/dev/sev")
10012 dh-cert-file: string (optional)
10014 guest owners DH certificate (encoded with base64)
10015 session-file: string (optional)
10017 guest owners session parameters (encoded with base64)
10018 policy: int (optional)
10020 SEV policy value (default: 0x1)
10021 handle: int (optional)
10023 SEV firmware handle (default: 0)
10024 cbitpos: int (optional)
10026 C-bit location in page table entry (default: 0)
10027 reduced-phys-bits: int
10029 number of bits in physical addresses that become unavailable
10030 when SEV is enabled
10031 kernel-hashes: boolean (optional)
10033 if true, add hashes of kernel/initrd/cmdline to a designated
10034 guest firmware page for measured boot with -kernel (default:
10035 false) (since 6.2)
10036 Since
10038 2.12
10039 ObjectType (Enum)
10041 Values
10042 authz-list
10043 Not documented
10044 authz-listfile
10046 Not documented
10047 authz-pam
10049 Not documented
10050 authz-simple
10052 Not documented
10053 can-bus
10055 Not documented
10056 can-host-socketcan (If: CONFIG_LINUX)
10058 Not documented
10059 colo-compare
10061 Not documented
10062 cryptodev-backend
10064 Not documented
10065 cryptodev-backend-builtin
10067 Not documented
10068 cryptodev-vhost-user (If: CONFIG_VHOST_CRYPTO)
10070 Not documented
10071 dbus-vmstate
10073 Not documented
10074 filter-buffer
10076 Not documented
10077 filter-dump
10079 Not documented
10080 filter-mirror
10082 Not documented
10083 filter-redirector
10085 Not documented
10086 filter-replay
10088 Not documented
10089 filter-rewriter
10091 Not documented
10092 input-barrier
10094 Not documented
10095 input-linux (If: CONFIG_LINUX)
10097 Not documented
10098 iothread
10100 Not documented
10101 memory-backend-epc (If: CONFIG_LINUX)
10103 Not documented
10104 memory-backend-file
10106 Not documented
10107 memory-backend-memfd (If: CONFIG_LINUX)
10109 Not documented
10110 memory-backend-ram
10112 Not documented
10113 pef-guest
10115 Not documented
10116 pr-manager-helper (If: CONFIG_LINUX)
10118 Not documented
10119 qtest Not documented
10121 rng-builtin
10123 Not documented
10124 rng-egd
10126 Not documented
10127 rng-random (If: CONFIG_POSIX)
10129 Not documented
10130 secret Not documented
10132 secret_keyring (If: CONFIG_SECRET_KEYRING)
10134 Not documented
10135 sev-guest
10137 Not documented
10138 s390-pv-guest
10140 Not documented
10141 throttle-group
10143 Not documented
10144 tls-creds-anon
10146 Not documented
10147 tls-creds-psk
10149 Not documented
10150 tls-creds-x509
10152 Not documented
10153 tls-cipher-suites
10155 Not documented
10156 x-remote-object
10158 Not documented
10159 Features
10161 unstable
10162 Member x-remote-object is experimental.
10163 Since
10165 6.0
10166 ObjectOptions (Object)
10168 Describes the options of a user creatable QOM object.
10169 Members
10171 qom-type: ObjectType
10172 the class name for the object to be created
10173 id: string
10175 the name of the new object
10176 The members of AuthZListProperties when qom-type is "authz-list"
10178 The members of AuthZListFileProperties when qom-type is "authz-list‐
10180 file"
10181 The members of AuthZPAMProperties when qom-type is "authz-pam"
10183 The members of AuthZSimpleProperties when qom-type is "authz-simple"
10185 The members of CanHostSocketcanProperties when qom-type is
10187 "can-host-socketcan" (If: CONFIG_LINUX)
10188 The members of ColoCompareProperties when qom-type is "colo-compare"
10190 The members of CryptodevBackendProperties when qom-type is "cryp‐
10192 todev-backend"
10193 The members of CryptodevBackendProperties when qom-type is "cryp‐
10195 todev-backend-builtin"
10196 The members of CryptodevVhostUserProperties when qom-type is "cryp‐
10198 todev-vhost-user" (If: CONFIG_VHOST_CRYPTO)
10199 The members of DBusVMStateProperties when qom-type is "dbus-vmstate"
10201 The members of FilterBufferProperties when qom-type is "filter-buffer"
10203 The members of FilterDumpProperties when qom-type is "filter-dump"
10205 The members of FilterMirrorProperties when qom-type is "filter-mirror"
10207 The members of FilterRedirectorProperties when qom-type is "fil‐
10209 ter-redirector"
10210 The members of NetfilterProperties when qom-type is "filter-replay"
10212 The members of FilterRewriterProperties when qom-type is "fil‐
10214 ter-rewriter"
10215 The members of InputBarrierProperties when qom-type is "input-barrier"
10217 The members of InputLinuxProperties when qom-type is "input-linux" (If:
10219 CONFIG_LINUX)
10220 The members of IothreadProperties when qom-type is "iothread"
10222 The members of MemoryBackendEpcProperties when qom-type is "mem‐
10224 ory-backend-epc" (If: CONFIG_LINUX)
10225 The members of MemoryBackendFileProperties when qom-type is "mem‐
10227 ory-backend-file"
10228 The members of MemoryBackendMemfdProperties when qom-type is "mem‐
10230 ory-backend-memfd" (If: CONFIG_LINUX)
10231 The members of MemoryBackendProperties when qom-type is "memory-back‐
10233 end-ram"
10234 The members of PrManagerHelperProperties when qom-type is "pr-man‐
10236 ager-helper" (If: CONFIG_LINUX)
10237 The members of QtestProperties when qom-type is "qtest"
10239 The members of RngProperties when qom-type is "rng-builtin"
10241 The members of RngEgdProperties when qom-type is "rng-egd"
10243 The members of RngRandomProperties when qom-type is "rng-random" (If:
10245 CONFIG_POSIX)
10246 The members of SecretProperties when qom-type is "secret"
10248 The members of SecretKeyringProperties when qom-type is "se‐
10250 cret_keyring" (If: CONFIG_SECRET_KEYRING)
10251 The members of SevGuestProperties when qom-type is "sev-guest"
10253 The members of ThrottleGroupProperties when qom-type is "throt‐
10255 tle-group"
10256 The members of TlsCredsAnonProperties when qom-type is "tls-creds-anon"
10258 The members of TlsCredsPskProperties when qom-type is "tls-creds-psk"
10260 The members of TlsCredsX509Properties when qom-type is "tls-creds-x509"
10262 The members of TlsCredsProperties when qom-type is "tls-cipher-suites"
10264 The members of RemoteObjectProperties when qom-type is "x-remote-ob‐
10266 ject"
10267 Since
10269 6.0
10270 object-add (Command)
10272 Create a QOM object.
10273 Arguments
10275 The members of ObjectOptions
10276 Returns
10278 Nothing on success Error if qom-type is not a valid class name
10279 Since
10281 2.0
10282 Example
10284 -> { "execute": "object-add",
10285 "arguments": { "qom-type": "rng-random", "id": "rng1",
10286 "filename": "/dev/hwrng" } }
10287 <- { "return": {} }
10288 object-del (Command)
10290 Remove a QOM object.
10291 Arguments
10293 id: string
10294 the name of the QOM object to remove
10295 Returns
10297 Nothing on success Error if id is not a valid id for a QOM object
10298 Since
10300 2.0
10301 Example
10303 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
10304 <- { "return": {} }
10305
10307 Abort (Object)
10308 This action can be used to test transaction failure.
10309 Since
10311 1.6
10312 ActionCompletionMode (Enum)
10314 An enumeration of Transactional completion modes.
10315 Values
10317 individual
10318 Do not attempt to cancel any other Actions if any Actions fail
10319 after the Transaction request succeeds. All Actions that can
10320 complete successfully will do so without waiting on others.
10321 This is the default.
10322 grouped
10324 If any Action fails after the Transaction succeeds, cancel all
10325 Actions. Actions do not complete until all Actions are ready to
10326 complete. May be rejected by Actions that do not support this
10327 completion mode.
10328 Since
10330 2.5
10331 TransactionActionKind (Enum)
10333 Values
10334 abort Since 1.6
10335 block-dirty-bitmap-add
10337 Since 2.5
10338 block-dirty-bitmap-remove
10340 Since 4.2
10341 block-dirty-bitmap-clear
10343 Since 2.5
10344 block-dirty-bitmap-enable
10346 Since 4.0
10347 block-dirty-bitmap-disable
10349 Since 4.0
10350 block-dirty-bitmap-merge
10352 Since 4.0
10353 blockdev-backup
10355 Since 2.3
10356 blockdev-snapshot
10358 Since 2.5
10359 blockdev-snapshot-internal-sync
10361 Since 1.7
10362 blockdev-snapshot-sync
10364 since 1.1
10365 drive-backup
10367 Since 1.6
10368 Features
10370 deprecated
10371 Member drive-backup is deprecated. Use member blockdev-backup
10372 instead.
10373 Since
10375 1.1
10376 AbortWrapper (Object)
10378 Members
10379 data: Abort
10380 Not documented
10381 Since
10383 1.6
10384 BlockDirtyBitmapAddWrapper (Object)
10386 Members
10387 data: BlockDirtyBitmapAdd
10388 Not documented
10389 Since
10391 2.5
10392 BlockDirtyBitmapWrapper (Object)
10394 Members
10395 data: BlockDirtyBitmap
10396 Not documented
10397 Since
10399 2.5
10400 BlockDirtyBitmapMergeWrapper (Object)
10402 Members
10403 data: BlockDirtyBitmapMerge
10404 Not documented
10405 Since
10407 4.0
10408 BlockdevBackupWrapper (Object)
10410 Members
10411 data: BlockdevBackup
10412 Not documented
10413 Since
10415 2.3
10416 BlockdevSnapshotWrapper (Object)
10418 Members
10419 data: BlockdevSnapshot
10420 Not documented
10421 Since
10423 2.5
10424 BlockdevSnapshotInternalWrapper (Object)
10426 Members
10427 data: BlockdevSnapshotInternal
10428 Not documented
10429 Since
10431 1.7
10432 BlockdevSnapshotSyncWrapper (Object)
10434 Members
10435 data: BlockdevSnapshotSync
10436 Not documented
10437 Since
10439 1.1
10440 DriveBackupWrapper (Object)
10442 Members
10443 data: DriveBackup
10444 Not documented
10445 Since
10447 1.6
10448 TransactionAction (Object)
10450 A discriminated record of operations that can be performed with trans‐
10451 action.
10452 Members
10454 type: TransactionActionKind
10455 Not documented
10456 The members of AbortWrapper when type is "abort"
10458 The members of BlockDirtyBitmapAddWrapper when type is
10460 "block-dirty-bitmap-add"
10461 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10463 map-remove"
10464 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10466 map-clear"
10467 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10469 map-enable"
10470 The members of BlockDirtyBitmapWrapper when type is "block-dirty-bit‐
10472 map-disable"
10473 The members of BlockDirtyBitmapMergeWrapper when type is
10475 "block-dirty-bitmap-merge"
10476 The members of BlockdevBackupWrapper when type is "blockdev-backup"
10478 The members of BlockdevSnapshotWrapper when type is "blockdev-snapshot"
10480 The members of BlockdevSnapshotInternalWrapper when type is "block‐
10482 dev-snapshot-internal-sync"
10483 The members of BlockdevSnapshotSyncWrapper when type is "blockdev-snap‐
10485 shot-sync"
10486 The members of DriveBackupWrapper when type is "drive-backup"
10488 Since
10490 1.1
10491 TransactionProperties (Object)
10493 Optional arguments to modify the behavior of a Transaction.
10494 Members
10496 completion-mode: ActionCompletionMode (optional)
10497 Controls how jobs launched asynchronously by Actions will com‐
10498 plete or fail as a group. See ActionCompletionMode for details.
10499 Since
10501 2.5
10502 transaction (Command)
10504 Executes a number of transactionable QMP commands atomically. If any
10505 operation fails, then the entire set of actions will be abandoned and
10506 the appropriate error returned.
10507 For external snapshots, the dictionary contains the device, the file to
10509 use for the new snapshot, and the format. The default format, if not
10510 specified, is qcow2.
10511 Each new snapshot defaults to being created by QEMU (wiping any con‐
10513 tents if the file already exists), but it is also possible to reuse an
10514 externally-created file. In the latter case, you should ensure that
10515 the new image file has the same contents as the current one; QEMU can‐
10516 not perform any meaningful check. Typically this is achieved by using
10517 the current image file as the backing file for the new image.
10518 On failure, the original disks pre-snapshot attempt will be used.
10520 For internal snapshots, the dictionary contains the device and the
10522 snapshot's name. If an internal snapshot matching name already exists,
10523 the request will be rejected. Only some image formats support it, for
10524 example, qcow2, and rbd,
10525 On failure, qemu will try delete the newly created internal snapshot in
10527 the transaction. When an I/O error occurs during deletion, the user
10528 needs to fix it later with qemu-img or other command.
10529 Arguments
10531 actions: array of TransactionAction
10532 List of TransactionAction; information needed for the respective
10533 operations.
10534 properties: TransactionProperties (optional)
10536 structure of additional options to control the execution of the
10537 transaction. See TransactionProperties for additional detail.
10538 Returns
10540 nothing on success
10541 Errors depend on the operations of the transaction
10543 Note
10545 The transaction aborts on the first failure. Therefore, there will be
10546 information on only one failed operation returned in an error condi‐
10547 tion, and subsequent actions will not have been attempted.
10548 Since
10550 1.1
10551 Example
10553 -> { "execute": "transaction",
10554 "arguments": { "actions": [
10555 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
10556 "snapshot-file": "/some/place/my-image",
10557 "format": "qcow2" } },
10558 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
10559 "snapshot-file": "/some/place/my-image2",
10560 "snapshot-node-name": "node3432",
10561 "mode": "existing",
10562 "format": "qcow2" } },
10563 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
10564 "snapshot-file": "/some/place/my-image2",
10565 "mode": "existing",
10566 "format": "qcow2" } },
10567 { "type": "blockdev-snapshot-internal-sync", "data" : {
10568 "device": "ide-hd2",
10569 "name": "snapshot0" } } ] } }
10570 <- { "return": {} }
10571
10573 2022, The QEMU Project Developers
105746.2.0 Jun 11, 2022 QEMU-STORAGE-DAEMON-QMP-REF(7)