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 • Cryptography
40 • QCryptoTLSCredsEndpoint (Enum)
42 • QCryptoSecretFormat (Enum)
44 • QCryptoHashAlgorithm (Enum)
46 • QCryptoCipherAlgorithm (Enum)
48 • QCryptoCipherMode (Enum)
50 • QCryptoIVGenAlgorithm (Enum)
52 • QCryptoBlockFormat (Enum)
54 • QCryptoBlockOptionsBase (Object)
56 • QCryptoBlockOptionsQCow (Object)
58 • QCryptoBlockOptionsLUKS (Object)
60 • QCryptoBlockCreateOptionsLUKS (Object)
62 • QCryptoBlockOpenOptions (Object)
64 • QCryptoBlockCreateOptions (Object)
66 • QCryptoBlockInfoBase (Object)
68 • QCryptoBlockInfoLUKSSlot (Object)
70 • QCryptoBlockInfoLUKS (Object)
72 • QCryptoBlockInfo (Object)
74 • QCryptoBlockLUKSKeyslotState (Enum)
76 • QCryptoBlockAmendOptionsLUKS (Object)
78 • QCryptoBlockAmendOptions (Object)
80 • SecretCommonProperties (Object)
82 • SecretProperties (Object)
84 • SecretKeyringProperties (Object)
86 • TlsCredsProperties (Object)
88 • TlsCredsAnonProperties (Object)
90 • TlsCredsPskProperties (Object)
92 • TlsCredsX509Properties (Object)
94 • Background jobs
96 • Socket data types
98 • NetworkAddressFamily (Enum)
100 • InetSocketAddressBase (Object)
102 • InetSocketAddress (Object)
104 • UnixSocketAddress (Object)
106 • VsockSocketAddress (Object)
108 • SocketAddressLegacy (Object)
110 • SocketAddressType (Enum)
112 • SocketAddress (Object)
114 • SnapshotInfo (Object)
116 • ImageInfoSpecificQCow2EncryptionBase (Object)
118 • ImageInfoSpecificQCow2Encryption (Object)
120 • ImageInfoSpecificQCow2 (Object)
122 • ImageInfoSpecificVmdk (Object)
124 • ImageInfoSpecificRbd (Object)
126 • ImageInfoSpecific (Object)
128 • ImageInfo (Object)
130 • ImageCheck (Object)
132 • MapEntry (Object)
134 • BlockdevCacheInfo (Object)
136 • BlockDeviceInfo (Object)
138 • BlockDeviceIoStatus (Enum)
140 • BlockDirtyInfo (Object)
142 • Qcow2BitmapInfoFlags (Enum)
144 • Qcow2BitmapInfo (Object)
146 • BlockLatencyHistogramInfo (Object)
148 • BlockInfo (Object)
150 • BlockMeasureInfo (Object)
152 • query-block (Command)
154 • BlockDeviceTimedStats (Object)
156 • BlockDeviceStats (Object)
158 • BlockStatsSpecificFile (Object)
160 • BlockStatsSpecificNvme (Object)
162 • BlockStatsSpecific (Object)
164 • BlockStats (Object)
166 • query-blockstats (Command)
168 • BlockdevOnError (Enum)
170 • MirrorSyncMode (Enum)
172 • BitmapSyncMode (Enum)
174 • MirrorCopyMode (Enum)
176 • BlockJobInfo (Object)
178 • query-block-jobs (Command)
180 • block_resize (Command)
182 • NewImageMode (Enum)
184 • BlockdevSnapshotSync (Object)
186 • BlockdevSnapshot (Object)
188 • BackupPerf (Object)
190 • BackupCommon (Object)
192 • DriveBackup (Object)
194 • BlockdevBackup (Object)
196 • blockdev-snapshot-sync (Command)
198 • blockdev-snapshot (Command)
200 • change-backing-file (Command)
202 • block-commit (Command)
204 • drive-backup (Command)
206 • blockdev-backup (Command)
208 • query-named-block-nodes (Command)
210 • XDbgBlockGraphNodeType (Enum)
212 • XDbgBlockGraphNode (Object)
214 • BlockPermission (Enum)
216 • XDbgBlockGraphEdge (Object)
218 • XDbgBlockGraph (Object)
220 • x-debug-query-block-graph (Command)
222 • drive-mirror (Command)
224 • DriveMirror (Object)
226 • BlockDirtyBitmap (Object)
228 • BlockDirtyBitmapAdd (Object)
230 • BlockDirtyBitmapMergeSource (Alternate)
232 • BlockDirtyBitmapMerge (Object)
234 • block-dirty-bitmap-add (Command)
236 • block-dirty-bitmap-remove (Command)
238 • block-dirty-bitmap-clear (Command)
240 • block-dirty-bitmap-enable (Command)
242 • block-dirty-bitmap-disable (Command)
244 • block-dirty-bitmap-merge (Command)
246 • BlockDirtyBitmapSha256 (Object)
248 • x-debug-block-dirty-bitmap-sha256 (Command)
250 • blockdev-mirror (Command)
252 • BlockIOThrottle (Object)
254 • ThrottleLimits (Object)
256 • ThrottleGroupProperties (Object)
258 • block-stream (Command)
260 • block-job-set-speed (Command)
262 • block-job-cancel (Command)
264 • block-job-pause (Command)
266 • block-job-resume (Command)
268 • block-job-complete (Command)
270 • block-job-dismiss (Command)
272 • block-job-finalize (Command)
274 • BlockdevDiscardOptions (Enum)
276 • BlockdevDetectZeroesOptions (Enum)
278 • BlockdevAioOptions (Enum)
280 • BlockdevCacheOptions (Object)
282 • BlockdevDriver (Enum)
284 • BlockdevOptionsFile (Object)
286 • BlockdevOptionsNull (Object)
288 • BlockdevOptionsNVMe (Object)
290 • BlockdevOptionsVVFAT (Object)
292 • BlockdevOptionsGenericFormat (Object)
294 • BlockdevOptionsLUKS (Object)
296 • BlockdevOptionsGenericCOWFormat (Object)
298 • Qcow2OverlapCheckMode (Enum)
300 • Qcow2OverlapCheckFlags (Object)
302 • Qcow2OverlapChecks (Alternate)
304 • BlockdevQcowEncryptionFormat (Enum)
306 • BlockdevQcowEncryption (Object)
308 • BlockdevOptionsQcow (Object)
310 • BlockdevQcow2EncryptionFormat (Enum)
312 • BlockdevQcow2Encryption (Object)
314 • BlockdevOptionsPreallocate (Object)
316 • BlockdevOptionsQcow2 (Object)
318 • SshHostKeyCheckMode (Enum)
320 • SshHostKeyCheckHashType (Enum)
322 • SshHostKeyHash (Object)
324 • SshHostKeyCheck (Object)
326 • BlockdevOptionsSsh (Object)
328 • BlkdebugEvent (Enum)
330 • BlkdebugIOType (Enum)
332 • BlkdebugInjectErrorOptions (Object)
334 • BlkdebugSetStateOptions (Object)
336 • BlockdevOptionsBlkdebug (Object)
338 • BlockdevOptionsBlklogwrites (Object)
340 • BlockdevOptionsBlkverify (Object)
342 • BlockdevOptionsBlkreplay (Object)
344 • QuorumReadPattern (Enum)
346 • BlockdevOptionsQuorum (Object)
348 • BlockdevOptionsGluster (Object)
350 • IscsiTransport (Enum)
352 • IscsiHeaderDigest (Enum)
354 • BlockdevOptionsIscsi (Object)
356 • RbdAuthMode (Enum)
358 • RbdImageEncryptionFormat (Enum)
360 • RbdEncryptionOptionsLUKSBase (Object)
362 • RbdEncryptionCreateOptionsLUKSBase (Object)
364 • RbdEncryptionOptionsLUKS (Object)
366 • RbdEncryptionOptionsLUKS2 (Object)
368 • RbdEncryptionCreateOptionsLUKS (Object)
370 • RbdEncryptionCreateOptionsLUKS2 (Object)
372 • RbdEncryptionOptions (Object)
374 • RbdEncryptionCreateOptions (Object)
376 • BlockdevOptionsRbd (Object)
378 • ReplicationMode (Enum)
380 • BlockdevOptionsReplication (Object)
382 • NFSTransport (Enum)
384 • NFSServer (Object)
386 • BlockdevOptionsNfs (Object)
388 • BlockdevOptionsCurlBase (Object)
390 • BlockdevOptionsCurlHttp (Object)
392 • BlockdevOptionsCurlHttps (Object)
394 • BlockdevOptionsCurlFtp (Object)
396 • BlockdevOptionsCurlFtps (Object)
398 • BlockdevOptionsNbd (Object)
400 • BlockdevOptionsRaw (Object)
402 • BlockdevOptionsThrottle (Object)
404 • BlockdevOptionsCor (Object)
406 • BlockdevOptions (Object)
408 • BlockdevRef (Alternate)
410 • BlockdevRefOrNull (Alternate)
412 • blockdev-add (Command)
414 • blockdev-reopen (Command)
416 • blockdev-del (Command)
418 • BlockdevCreateOptionsFile (Object)
420 • BlockdevCreateOptionsGluster (Object)
422 • BlockdevCreateOptionsLUKS (Object)
424 • BlockdevCreateOptionsNfs (Object)
426 • BlockdevCreateOptionsParallels (Object)
428 • BlockdevCreateOptionsQcow (Object)
430 • BlockdevQcow2Version (Enum)
432 • Qcow2CompressionType (Enum)
434 • BlockdevCreateOptionsQcow2 (Object)
436 • BlockdevCreateOptionsQed (Object)
438 • BlockdevCreateOptionsRbd (Object)
440 • BlockdevVmdkSubformat (Enum)
442 • BlockdevVmdkAdapterType (Enum)
444 • BlockdevCreateOptionsVmdk (Object)
446 • BlockdevCreateOptionsSsh (Object)
448 • BlockdevCreateOptionsVdi (Object)
450 • BlockdevVhdxSubformat (Enum)
452 • BlockdevCreateOptionsVhdx (Object)
454 • BlockdevVpcSubformat (Enum)
456 • BlockdevCreateOptionsVpc (Object)
458 • BlockdevCreateOptions (Object)
460 • blockdev-create (Command)
462 • BlockdevAmendOptionsLUKS (Object)
464 • BlockdevAmendOptionsQcow2 (Object)
466 • BlockdevAmendOptions (Object)
468 • x-blockdev-amend (Command)
470 • BlockErrorAction (Enum)
472 • BLOCK_IMAGE_CORRUPTED (Event)
474 • BLOCK_IO_ERROR (Event)
476 • BLOCK_JOB_COMPLETED (Event)
478 • BLOCK_JOB_CANCELLED (Event)
480 • BLOCK_JOB_ERROR (Event)
482 • BLOCK_JOB_READY (Event)
484 • BLOCK_JOB_PENDING (Event)
486 • PreallocMode (Enum)
488 • BLOCK_WRITE_THRESHOLD (Event)
490 • block-set-write-threshold (Command)
492 • x-blockdev-change (Command)
494 • x-blockdev-set-iothread (Command)
496 • QuorumOpType (Enum)
498 • QUORUM_FAILURE (Event)
500 • QUORUM_REPORT_BAD (Event)
502 • BlockdevSnapshotInternal (Object)
504 • blockdev-snapshot-internal-sync (Command)
506 • blockdev-snapshot-delete-internal-sync (Command)
508 • Block device exports
510 • Character devices
512 • ChardevInfo (Object)
514 • query-chardev (Command)
516 • ChardevBackendInfo (Object)
518 • query-chardev-backends (Command)
520 • DataFormat (Enum)
522 • ringbuf-write (Command)
524 • ringbuf-read (Command)
526 • ChardevCommon (Object)
528 • ChardevFile (Object)
530 • ChardevHostdev (Object)
532 • ChardevSocket (Object)
534 • ChardevUdp (Object)
536 • ChardevMux (Object)
538 • ChardevStdio (Object)
540 • ChardevSpiceChannel (Object)
542 • ChardevSpicePort (Object)
544 • ChardevVC (Object)
546 • ChardevRingbuf (Object)
548 • ChardevQemuVDAgent (Object)
550 • ChardevBackend (Object)
552 • ChardevReturn (Object)
554 • chardev-add (Command)
556 • chardev-change (Command)
558 • chardev-remove (Command)
560 • chardev-send-break (Command)
562 • VSERPORT_CHANGE (Event)
564 • QMP monitor control
566 • qmp_capabilities (Command)
568 • QMPCapability (Enum)
570 • VersionTriple (Object)
572 • VersionInfo (Object)
574 • query-version (Command)
576 • CommandInfo (Object)
578 • query-commands (Command)
580 • quit (Command)
582 • MonitorMode (Enum)
584 • MonitorOptions (Object)
586 • QMP introspection
588 • query-qmp-schema (Command)
590 • SchemaMetaType (Enum)
592 • SchemaInfo (Object)
594 • SchemaInfoBuiltin (Object)
596 • JSONType (Enum)
598 • SchemaInfoEnum (Object)
600 • SchemaInfoArray (Object)
602 • SchemaInfoObject (Object)
604 • SchemaInfoObjectMember (Object)
606 • SchemaInfoObjectVariant (Object)
608 • SchemaInfoAlternate (Object)
610 • SchemaInfoAlternateMember (Object)
612 • SchemaInfoCommand (Object)
614 • SchemaInfoEvent (Object)
616 • User authorization
618 • QAuthZListPolicy (Enum)
620 • QAuthZListFormat (Enum)
622 • QAuthZListRule (Object)
624 • AuthZListProperties (Object)
626 • AuthZListFileProperties (Object)
628 • AuthZPAMProperties (Object)
630 • AuthZSimpleProperties (Object)
632 • QEMU Object Model (QOM)
634 • ObjectPropertyInfo (Object)
636 • qom-list (Command)
638 • qom-get (Command)
640 • qom-set (Command)
642 • ObjectTypeInfo (Object)
644 • qom-list-types (Command)
646 • qom-list-properties (Command)
648 • CanHostSocketcanProperties (Object)
650 • ColoCompareProperties (Object)
652 • CryptodevBackendProperties (Object)
654 • CryptodevVhostUserProperties (Object)
656 • DBusVMStateProperties (Object)
658 • NetfilterInsert (Enum)
660 • NetfilterProperties (Object)
662 • FilterBufferProperties (Object)
664 • FilterDumpProperties (Object)
666 • FilterMirrorProperties (Object)
668 • FilterRedirectorProperties (Object)
670 • FilterRewriterProperties (Object)
672 • InputBarrierProperties (Object)
674 • InputLinuxProperties (Object)
676 • IothreadProperties (Object)
678 • MemoryBackendProperties (Object)
680 • MemoryBackendFileProperties (Object)
682 • MemoryBackendMemfdProperties (Object)
684 • PrManagerHelperProperties (Object)
686 • QtestProperties (Object)
688 • RemoteObjectProperties (Object)
690 • RngProperties (Object)
692 • RngEgdProperties (Object)
694 • RngRandomProperties (Object)
696 • SevGuestProperties (Object)
698 • ObjectType (Enum)
700 • ObjectOptions (Object)
702 • object-add (Command)
704 • object-del (Command)
706 • Transactions
708 • Abort (Object)
710 • ActionCompletionMode (Enum)
712 • TransactionAction (Object)
714 • TransactionProperties (Object)
716 • transaction (Command)
718
720 Block core (VM unrelated)
722 IoOperationType (Enum)
723 An enumeration of the I/O operation types
724 Values
726 read read operation
727 write write operation
729 Since
731 2.1
732 OnOffAuto (Enum)
734 An enumeration of three options: on, off, and auto
735 Values
737 auto QEMU selects the value between on and off
738 on Enabled
740 off Disabled
742 Since
744 2.2
745 OnOffSplit (Enum)
747 An enumeration of three values: on, off, and split
748 Values
750 on Enabled
751 off Disabled
753 split Mixed
755 Since
757 2.6
758 String (Object)
760 A fat type wrapping 'str', to be embedded in lists.
761 Members
763 str: string
764 Not documented
765 Since
767 1.2
768 StrOrNull (Alternate)
770 This is a string value or the explicit lack of a string (null pointer
771 in C). Intended for cases when 'optional absent' already has a differ‐
772 ent meaning.
773 Members
775 s: string
776 the string value
777 n: null
779 no string value
780 Since
782 2.10
783 OffAutoPCIBAR (Enum)
785 An enumeration of options for specifying a PCI BAR
786 Values
788 off The specified feature is disabled
789 auto The PCI BAR for the feature is automatically selected
791 bar0 PCI BAR0 is used for the feature
793 bar1 PCI BAR1 is used for the feature
795 bar2 PCI BAR2 is used for the feature
797 bar3 PCI BAR3 is used for the feature
799 bar4 PCI BAR4 is used for the feature
801 bar5 PCI BAR5 is used for the feature
803 Since
805 2.12
806 PCIELinkSpeed (Enum)
808 An enumeration of PCIe link speeds in units of GT/s
809 Values
811 2_5 2.5GT/s
812 5 5.0GT/s
814 8 8.0GT/s
816 16 16.0GT/s
818 Since
820 4.0
821 PCIELinkWidth (Enum)
823 An enumeration of PCIe link width
824 Values
826 1 x1
827 2 x2
829 4 x4
831 8 x8
833 12 x12
835 16 x16
837 32 x32
839 Since
841 4.0
842 HostMemPolicy (Enum)
844 Host memory policy types
845 Values
847 default
848 restore default policy, remove any nondefault policy
849 preferred
851 set the preferred host nodes for allocation
852 bind a strict policy that restricts memory allocation to the host
854 nodes specified
855 interleave
857 memory allocations are interleaved across the set of host nodes
858 specified
859 Since
861 2.1
862 NetFilterDirection (Enum)
864 Indicates whether a netfilter is attached to a netdev's transmit queue
865 or receive queue or both.
866 Values
868 all the filter is attached both to the receive and the transmit
869 queue of the netdev (default).
870 rx the filter is attached to the receive queue of the netdev, where
872 it will receive packets sent to the netdev.
873 tx the filter is attached to the transmit queue of the netdev,
875 where it will receive packets sent by the netdev.
876 Since
878 2.5
879 GrabToggleKeys (Enum)
881 Keys to toggle input-linux between host and guest.
882 Values
884 ctrl-ctrl
885 Not documented
886 alt-alt
888 Not documented
889 shift-shift
891 Not documented
892 meta-meta
894 Not documented
895 scrolllock
897 Not documented
898 ctrl-scrolllock
900 Not documented
901 Since
903 4.0
904
906 QCryptoTLSCredsEndpoint (Enum)
907 The type of network endpoint that will be using the credentials. Most
908 types of credential require different setup / structures depending on
909 whether they will be used in a server versus a client.
910 Values
912 client the network endpoint is acting as the client
913 server the network endpoint is acting as the server
915 Since
917 2.5
918 QCryptoSecretFormat (Enum)
920 The data format that the secret is provided in
921 Values
923 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
924 be used
925 base64 arbitrary base64 encoded binary data
927 Since
929 2.6
930 QCryptoHashAlgorithm (Enum)
932 The supported algorithms for computing content digests
933 Values
935 md5 MD5. Should not be used in any new code, legacy compat only
936 sha1 SHA-1. Should not be used in any new code, legacy compat only
938 sha224 SHA-224. (since 2.7)
940 sha256 SHA-256. Current recommended strong hash.
942 sha384 SHA-384. (since 2.7)
944 sha512 SHA-512. (since 2.7)
946 ripemd160
948 RIPEMD-160. (since 2.7)
949 Since
951 2.6
952 QCryptoCipherAlgorithm (Enum)
954 The supported algorithms for content encryption ciphers
955 Values
957 aes-128
958 AES with 128 bit / 16 byte keys
959 aes-192
961 AES with 192 bit / 24 byte keys
962 aes-256
964 AES with 256 bit / 32 byte keys
965 des DES with 56 bit / 8 byte keys. Do not use except in VNC. (since
967 6.1)
968 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
970 cast5-128
972 Cast5 with 128 bit / 16 byte keys
973 serpent-128
975 Serpent with 128 bit / 16 byte keys
976 serpent-192
978 Serpent with 192 bit / 24 byte keys
979 serpent-256
981 Serpent with 256 bit / 32 byte keys
982 twofish-128
984 Twofish with 128 bit / 16 byte keys
985 twofish-192
987 Twofish with 192 bit / 24 byte keys
988 twofish-256
990 Twofish with 256 bit / 32 byte keys
991 Since
993 2.6
994 QCryptoCipherMode (Enum)
996 The supported modes for content encryption ciphers
997 Values
999 ecb Electronic Code Book
1000 cbc Cipher Block Chaining
1002 xts XEX with tweaked code book and ciphertext stealing
1004 ctr Counter (Since 2.8)
1006 Since
1008 2.6
1009 QCryptoIVGenAlgorithm (Enum)
1011 The supported algorithms for generating initialization vectors for full
1012 disk encryption. The 'plain' generator should not be used for disks
1013 with sector numbers larger than 2^32, except where compatibility with
1014 pre-existing Linux dm-crypt volumes is required.
1015 Values
1017 plain 64-bit sector number truncated to 32-bits
1018 plain64
1020 64-bit sector number
1021 essiv 64-bit sector number encrypted with a hash of the encryption key
1023 Since
1025 2.6
1026 QCryptoBlockFormat (Enum)
1028 The supported full disk encryption formats
1029 Values
1031 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
1032 data from old images.
1033 luks LUKS encryption format. Recommended for new images
1035 Since
1037 2.6
1038 QCryptoBlockOptionsBase (Object)
1040 The common options that apply to all full disk encryption formats
1041 Members
1043 format: QCryptoBlockFormat
1044 the encryption format
1045 Since
1047 2.6
1048 QCryptoBlockOptionsQCow (Object)
1050 The options that apply to QCow/QCow2 AES-CBC encryption format
1051 Members
1053 key-secret: string (optional)
1054 the ID of a QCryptoSecret object providing the decryption key.
1055 Mandatory except when probing image for metadata only.
1056 Since
1058 2.6
1059 QCryptoBlockOptionsLUKS (Object)
1061 The options that apply to LUKS encryption format
1062 Members
1064 key-secret: string (optional)
1065 the ID of a QCryptoSecret object providing the decryption key.
1066 Mandatory except when probing image for metadata only.
1067 Since
1069 2.6
1070 QCryptoBlockCreateOptionsLUKS (Object)
1072 The options that apply to LUKS encryption format initialization
1073 Members
1075 cipher-alg: QCryptoCipherAlgorithm (optional)
1076 the cipher algorithm for data encryption Currently defaults to
1077 'aes-256'.
1078 cipher-mode: QCryptoCipherMode (optional)
1080 the cipher mode for data encryption Currently defaults to 'xts'
1081 ivgen-alg: QCryptoIVGenAlgorithm (optional)
1083 the initialization vector generator Currently defaults to
1084 'plain64'
1085 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1087 the initialization vector generator hash Currently defaults to
1088 'sha256'
1089 hash-alg: QCryptoHashAlgorithm (optional)
1091 the master key hash algorithm Currently defaults to 'sha256'
1092 iter-time: int (optional)
1094 number of milliseconds to spend in PBKDF passphrase processing.
1095 Currently defaults to 2000. (since 2.8)
1096 The members of QCryptoBlockOptionsLUKS
1098 Since
1100 2.6
1101 QCryptoBlockOpenOptions (Object)
1103 The options that are available for all encryption formats when opening
1104 an existing volume
1105 Members
1107 The members of QCryptoBlockOptionsBase
1108 The members of QCryptoBlockOptionsQCow when format is "qcow"
1110 The members of QCryptoBlockOptionsLUKS when format is "luks"
1112 Since
1114 2.6
1115 QCryptoBlockCreateOptions (Object)
1117 The options that are available for all encryption formats when initial‐
1118 izing a new volume
1119 Members
1121 The members of QCryptoBlockOptionsBase
1122 The members of QCryptoBlockOptionsQCow when format is "qcow"
1124 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
1126 Since
1128 2.6
1129 QCryptoBlockInfoBase (Object)
1131 The common information that applies to all full disk encryption formats
1132 Members
1134 format: QCryptoBlockFormat
1135 the encryption format
1136 Since
1138 2.7
1139 QCryptoBlockInfoLUKSSlot (Object)
1141 Information about the LUKS block encryption key slot options
1142 Members
1144 active: boolean
1145 whether the key slot is currently in use
1146 key-offset: int
1148 offset to the key material in bytes
1149 iters: int (optional)
1151 number of PBKDF2 iterations for key material
1152 stripes: int (optional)
1154 number of stripes for splitting key material
1155 Since
1157 2.7
1158 QCryptoBlockInfoLUKS (Object)
1160 Information about the LUKS block encryption options
1161 Members
1163 cipher-alg: QCryptoCipherAlgorithm
1164 the cipher algorithm for data encryption
1165 cipher-mode: QCryptoCipherMode
1167 the cipher mode for data encryption
1168 ivgen-alg: QCryptoIVGenAlgorithm
1170 the initialization vector generator
1171 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1173 the initialization vector generator hash
1174 hash-alg: QCryptoHashAlgorithm
1176 the master key hash algorithm
1177 payload-offset: int
1179 offset to the payload data in bytes
1180 master-key-iters: int
1182 number of PBKDF2 iterations for key material
1183 uuid: string
1185 unique identifier for the volume
1186 slots: array of QCryptoBlockInfoLUKSSlot
1188 information about each key slot
1189 Since
1191 2.7
1192 QCryptoBlockInfo (Object)
1194 Information about the block encryption options
1195 Members
1197 The members of QCryptoBlockInfoBase
1198 The members of QCryptoBlockInfoLUKS when format is "luks"
1200 Since
1202 2.7
1203 QCryptoBlockLUKSKeyslotState (Enum)
1205 Defines state of keyslots that are affected by the update
1206 Values
1208 active The slots contain the given password and marked as active
1209 inactive
1211 The slots are erased (contain garbage) and marked as inactive
1212 Since
1214 5.1
1215 QCryptoBlockAmendOptionsLUKS (Object)
1217 This struct defines the update parameters that activate/de-activate set
1218 of keyslots
1219 Members
1221 state: QCryptoBlockLUKSKeyslotState
1222 the desired state of the keyslots
1223 new-secret: string (optional)
1225 The ID of a QCryptoSecret object providing the password to be
1226 written into added active keyslots
1227 old-secret: string (optional)
1229 Optional (for deactivation only) If given will deactivate all
1230 keyslots that match password located in QCryptoSecret with this
1231 ID
1232 iter-time: int (optional)
1234 Optional (for activation only) Number of milliseconds to spend
1235 in PBKDF passphrase processing for the newly activated keyslot.
1236 Currently defaults to 2000.
1237 keyslot: int (optional)
1239 Optional. ID of the keyslot to activate/deactivate. For keyslot
1240 activation, keyslot should not be active already (this is unsafe
1241 to update an active keyslot), but possible if 'force' parameter
1242 is given. If keyslot is not given, first free keyslot will be
1243 written.
1244 For keyslot deactivation, this parameter specifies the exact
1246 keyslot to deactivate
1247 secret: string (optional)
1249 Optional. The ID of a QCryptoSecret object providing the pass‐
1250 word to use to retrieve current master key. Defaults to the
1251 same secret that was used to open the image
1252 Since 5.1
1253 QCryptoBlockAmendOptions (Object)
1255 The options that are available for all encryption formats when amending
1256 encryption settings
1257 Members
1259 The members of QCryptoBlockOptionsBase
1260 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
1262 Since
1264 5.1
1265 SecretCommonProperties (Object)
1267 Properties for objects of classes derived from secret-common.
1268 Members
1270 loaded: boolean (optional)
1271 if true, the secret is loaded immediately when applying this op‐
1272 tion and will probably fail when processing the next option.
1273 Don't use; only provided for compatibility. (default: false)
1274 format: QCryptoSecretFormat (optional)
1276 the data format that the secret is provided in (default: raw)
1277 keyid: string (optional)
1279 the name of another secret that should be used to decrypt the
1280 provided data. If not present, the data is assumed to be unen‐
1281 crypted.
1282 iv: string (optional)
1284 the random initialization vector used for encryption of this
1285 particular secret. Should be a base64 encrypted string of the
1286 16-byte IV. Mandatory if keyid is given. Ignored if keyid is ab‐
1287 sent.
1288 Features
1290 deprecated
1291 Member loaded is deprecated. Setting true doesn't make sense,
1292 and false is already the default.
1293 Since
1295 2.6
1296 SecretProperties (Object)
1298 Properties for secret objects.
1299 Either data or file must be provided, but not both.
1301 Members
1303 data: string (optional)
1304 the associated with the secret from
1305 file: string (optional)
1307 the filename to load the data associated with the secret from
1308 The members of SecretCommonProperties
1310 Since
1312 2.6
1313 SecretKeyringProperties (Object)
1315 Properties for secret_keyring objects.
1316 Members
1318 serial: int
1319 serial number that identifies a key to get from the kernel
1320 The members of SecretCommonProperties
1322 Since
1324 5.1
1325 TlsCredsProperties (Object)
1327 Properties for objects of classes derived from tls-creds.
1328 Members
1330 verify-peer: boolean (optional)
1331 if true the peer credentials will be verified once the handshake
1332 is completed. This is a no-op for anonymous credentials. (de‐
1333 fault: true)
1334 dir: string (optional)
1336 the path of the directory that contains the credential files
1337 endpoint: QCryptoTLSCredsEndpoint (optional)
1339 whether the QEMU network backend that uses the credentials will
1340 be acting as a client or as a server (default: client)
1341 priority: string (optional)
1343 a gnutls priority string as described at
1344 https://gnutls.org/manual/html_node/Priority-Strings.html
1345 Since
1347 2.5
1348 TlsCredsAnonProperties (Object)
1350 Properties for tls-creds-anon objects.
1351 Members
1353 loaded: boolean (optional)
1354 if true, the credentials are loaded immediately when applying
1355 this option and will ignore options that are processed later.
1356 Don't use; only provided for compatibility. (default: false)
1357 The members of TlsCredsProperties
1359 Features
1361 deprecated
1362 Member loaded is deprecated. Setting true doesn't make sense,
1363 and false is already the default.
1364 Since
1366 2.5
1367 TlsCredsPskProperties (Object)
1369 Properties for tls-creds-psk objects.
1370 Members
1372 loaded: boolean (optional)
1373 if true, the credentials are loaded immediately when applying
1374 this option and will ignore options that are processed later.
1375 Don't use; only provided for compatibility. (default: false)
1376 username: string (optional)
1378 the username which will be sent to the server. For clients
1379 only. If absent, "qemu" is sent and the property will read back
1380 as an empty string.
1381 The members of TlsCredsProperties
1383 Features
1385 deprecated
1386 Member loaded is deprecated. Setting true doesn't make sense,
1387 and false is already the default.
1388 Since
1390 3.0
1391 TlsCredsX509Properties (Object)
1393 Properties for tls-creds-x509 objects.
1394 Members
1396 loaded: boolean (optional)
1397 if true, the credentials are loaded immediately when applying
1398 this option and will ignore options that are processed later.
1399 Don't use; only provided for compatibility. (default: false)
1400 sanity-check: boolean (optional)
1402 if true, perform some sanity checks before using the credentials
1403 (default: true)
1404 passwordid: string (optional)
1406 For the server-key.pem and client-key.pem files which contain
1407 sensitive private keys, it is possible to use an encrypted ver‐
1408 sion by providing the passwordid parameter. This provides the
1409 ID of a previously created secret object containing the password
1410 for decryption.
1411 The members of TlsCredsProperties
1413 Features
1415 deprecated
1416 Member loaded is deprecated. Setting true doesn't make sense,
1417 and false is already the default.
1418 Since
1420 2.5
1421 Background jobs
1423 JobType (Enum)
1424 Type of a background job.
1425 Values
1427 commit block commit job type, see "block-commit"
1428 stream block stream job type, see "block-stream"
1430 mirror drive mirror job type, see "drive-mirror"
1432 backup drive backup job type, see "drive-backup"
1434 create image creation job type, see "blockdev-create" (since 3.0)
1436 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
1438 snapshot-load
1440 snapshot load job type, see "snapshot-load" (since 6.0)
1441 snapshot-save
1443 snapshot save job type, see "snapshot-save" (since 6.0)
1444 snapshot-delete
1446 snapshot delete job type, see "snapshot-delete" (since 6.0)
1447 Since
1449 1.7
1450 JobStatus (Enum)
1452 Indicates the present state of a given job in its lifetime.
1453 Values
1455 undefined
1456 Erroneous, default state. Should not ever be visible.
1457 created
1459 The job has been created, but not yet started.
1460 running
1462 The job is currently running.
1463 paused The job is running, but paused. The pause may be requested by
1465 either the QMP user or by internal processes.
1466 ready The job is running, but is ready for the user to signal comple‐
1468 tion. This is used for long-running jobs like mirror that are
1469 designed to run indefinitely.
1470 standby
1472 The job is ready, but paused. This is nearly identical to
1473 paused. The job may return to ready or otherwise be canceled.
1474 waiting
1476 The job is waiting for other jobs in the transaction to converge
1477 to the waiting state. This status will likely not be visible for
1478 the last job in a transaction.
1479 pending
1481 The job has finished its work, but has finalization steps that
1482 it needs to make prior to completing. These changes will require
1483 manual intervention via job-finalize if auto-finalize was set to
1484 false. These pending changes may still fail.
1485 aborting
1487 The job is in the process of being aborted, and will finish with
1488 an error. The job will afterwards report that it is concluded.
1489 This status may not be visible to the management process.
1490 concluded
1492 The job has finished all work. If auto-dismiss was set to false,
1493 the job will remain in the query list until it is dismissed via
1494 job-dismiss.
1495 null The job is in the process of being dismantled. This state should
1497 not ever be visible externally.
1498 Since
1500 2.12
1501 JobVerb (Enum)
1503 Represents command verbs that can be applied to a job.
1504 Values
1506 cancel see job-cancel
1507 pause see job-pause
1509 resume see job-resume
1511 set-speed
1513 see block-job-set-speed
1514 complete
1516 see job-complete
1517 dismiss
1519 see job-dismiss
1520 finalize
1522 see job-finalize
1523 Since
1525 2.12
1526 JOB_STATUS_CHANGE (Event)
1528 Emitted when a job transitions to a different status.
1529 Arguments
1531 id: string
1532 The job identifier
1533 status: JobStatus
1535 The new job status
1536 Since
1538 3.0
1539 job-pause (Command)
1541 Pause an active job.
1542 This command returns immediately after marking the active job for paus‐
1544 ing. Pausing an already paused job is an error.
1545 The job will pause as soon as possible, which means transitioning into
1547 the PAUSED state if it was RUNNING, or into STANDBY if it was READY.
1548 The corresponding JOB_STATUS_CHANGE event will be emitted.
1549 Cancelling a paused job automatically resumes it.
1551 Arguments
1553 id: string
1554 The job identifier.
1555 Since
1557 3.0
1558 job-resume (Command)
1560 Resume a paused job.
1561 This command returns immediately after resuming a paused job. Resuming
1563 an already running job is an error.
1564 id : The job identifier.
1566 Arguments
1568 id: string
1569 Not documented
1570 Since
1572 3.0
1573 job-cancel (Command)
1575 Instruct an active background job to cancel at the next opportunity.
1576 This command returns immediately after marking the active job for can‐
1577 cellation.
1578 The job will cancel as soon as possible and then emit a JOB_STA‐
1580 TUS_CHANGE event. Usually, the status will change to ABORTING, but it
1581 is possible that a job successfully completes (e.g. because it was al‐
1582 most done and there was no opportunity to cancel earlier than complet‐
1583 ing the job) and transitions to PENDING instead.
1584 Arguments
1586 id: string
1587 The job identifier.
1588 Since
1590 3.0
1591 job-complete (Command)
1593 Manually trigger completion of an active job in the READY state.
1594 Arguments
1596 id: string
1597 The job identifier.
1598 Since
1600 3.0
1601 job-dismiss (Command)
1603 Deletes a job that is in the CONCLUDED state. This command only needs
1604 to be run explicitly for jobs that don't have automatic dismiss en‐
1605 abled.
1606 This command will refuse to operate on any job that has not yet reached
1608 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of
1609 JOB_READY event, job-cancel or job-complete will still need to be used
1610 as appropriate.
1611 Arguments
1613 id: string
1614 The job identifier.
1615 Since
1617 3.0
1618 job-finalize (Command)
1620 Instructs all jobs in a transaction (or a single job if it is not part
1621 of any transaction) to finalize any graph changes and do any necessary
1622 cleanup. This command requires that all involved jobs are in the PEND‐
1623 ING state.
1624 For jobs in a transaction, instructing one job to finalize will force
1626 ALL jobs in the transaction to finalize, so it is only necessary to in‐
1627 struct a single member job to finalize.
1628 Arguments
1630 id: string
1631 The identifier of any job in the transaction, or of a job that
1632 is not part of any transaction.
1633 Since
1635 3.0
1636 JobInfo (Object)
1638 Information about a job.
1639 Members
1641 id: string
1642 The job identifier
1643 type: JobType
1645 The kind of job that is being performed
1646 status: JobStatus
1648 Current job state/status
1649 current-progress: int
1651 Progress made until now. The unit is arbitrary and the value can
1652 only meaningfully be used for the ratio of current-progress to
1653 total-progress. The value is monotonically increasing.
1654 total-progress: int
1656 Estimated current-progress value at the completion of the job.
1657 This value can arbitrarily change while the job is running, in
1658 both directions.
1659 error: string (optional)
1661 If this field is present, the job failed; if it is still missing
1662 in the CONCLUDED state, this indicates successful completion.
1663 The value is a human-readable error message to describe the rea‐
1665 son for the job failure. It should not be parsed by applica‐
1666 tions.
1667 Since
1669 3.0
1670 query-jobs (Command)
1672 Return information about jobs.
1673 Returns
1675 a list with a JobInfo for each active job
1676 Since
1678 3.0
1679
1681 NetworkAddressFamily (Enum)
1682 The network address family
1683 Values
1685 ipv4 IPV4 family
1686 ipv6 IPV6 family
1688 unix unix socket
1690 vsock vsock family (since 2.8)
1692 unknown
1694 otherwise
1695 Since
1697 2.1
1698 InetSocketAddressBase (Object)
1700 Members
1701 host: string
1702 host part of the address
1703 port: string
1705 port part of the address
1706 InetSocketAddress (Object)
1708 Captures a socket address or address range in the Internet namespace.
1709 Members
1711 numeric: boolean (optional)
1712 true if the host/port are guaranteed to be numeric, false if
1713 name resolution should be attempted. Defaults to false. (Since
1714 2.9)
1715 to: int (optional)
1717 If present, this is range of possible addresses, with port be‐
1718 tween port and to.
1719 ipv4: boolean (optional)
1721 whether to accept IPv4 addresses, default try both IPv4 and IPv6
1722 ipv6: boolean (optional)
1724 whether to accept IPv6 addresses, default try both IPv4 and IPv6
1725 keep-alive: boolean (optional)
1727 enable keep-alive when connecting to this socket. Not supported
1728 for passive sockets. (Since 4.2)
1729 mptcp: boolean (optional) (If: defined(IPPROTO_MPTCP))
1731 enable multi-path TCP. (Since 6.1)
1732 The members of InetSocketAddressBase
1734 Since
1736 1.3
1737 UnixSocketAddress (Object)
1739 Captures a socket address in the local ("Unix socket") namespace.
1740 Members
1742 path: string
1743 filesystem path to use
1744 abstract: boolean (optional) (If: defined(CONFIG_LINUX))
1746 if true, this is a Linux abstract socket address. path will be
1747 prefixed by a null byte, and optionally padded with null bytes.
1748 Defaults to false. (Since 5.1)
1749 tight: boolean (optional) (If: defined(CONFIG_LINUX))
1751 if false, pad an abstract socket address with enough null bytes
1752 to make it fill struct sockaddr_un member sun_path. Defaults to
1753 true. (Since 5.1)
1754 Since
1756 1.3
1757 VsockSocketAddress (Object)
1759 Captures a socket address in the vsock namespace.
1760 Members
1762 cid: string
1763 unique host identifier
1764 port: string
1766 port
1767 Note
1769 string types are used to allow for possible future hostname or service
1770 resolution support.
1771 Since
1773 2.8
1774 SocketAddressLegacy (Object)
1776 Captures the address of a socket, which could also be a named file de‐
1777 scriptor
1778 Members
1780 type One of inet, unix, vsock, fd
1781 data: InetSocketAddress when type is "inet"
1783 data: UnixSocketAddress when type is "unix"
1785 data: VsockSocketAddress when type is "vsock"
1787 data: String when type is "fd"
1789 Note
1791 This type is deprecated in favor of SocketAddress. The difference be‐
1792 tween SocketAddressLegacy and SocketAddress is that the latter is a
1793 flat union rather than a simple union. Flat is nicer because it avoids
1794 nesting on the wire, i.e. that form has fewer {}.
1795 Since
1797 1.3
1798 SocketAddressType (Enum)
1800 Available SocketAddress types
1801 Values
1803 inet Internet address
1804 unix Unix domain socket
1806 vsock VMCI address
1808 fd decimal is for file descriptor number, otherwise a file descrip‐
1810 tor name. Named file descriptors are permitted in monitor com‐
1811 mands, in combination with the 'getfd' command. Decimal file de‐
1812 scriptors are permitted at startup or other contexts where no
1813 monitor context is active.
1814 Since
1816 2.9
1817 SocketAddress (Object)
1819 Captures the address of a socket, which could also be a named file de‐
1820 scriptor
1821 Members
1823 type: SocketAddressType
1824 Transport type
1825 The members of InetSocketAddress when type is "inet"
1827 The members of UnixSocketAddress when type is "unix"
1829 The members of VsockSocketAddress when type is "vsock"
1831 The members of String when type is "fd"
1833 Since
1835 2.9
1836 SnapshotInfo (Object)
1838 Members
1839 id: string
1840 unique snapshot id
1841 name: string
1843 user chosen name
1844 vm-state-size: int
1846 size of the VM state
1847 date-sec: int
1849 UTC date of the snapshot in seconds
1850 date-nsec: int
1852 fractional part in nano seconds to be used with date-sec
1853 vm-clock-sec: int
1855 VM clock relative to boot in seconds
1856 vm-clock-nsec: int
1858 fractional part in nano seconds to be used with vm-clock-sec
1859 icount: int (optional)
1861 Current instruction count. Appears when execution record/replay
1862 is enabled. Used for "time-traveling" to match the moment in the
1863 recorded execution with the snapshots. This counter may be ob‐
1864 tained through query-replay command (since 5.2)
1865 Since
1867 1.3
1868 ImageInfoSpecificQCow2EncryptionBase (Object)
1870 Members
1871 format: BlockdevQcow2EncryptionFormat
1872 The encryption format
1873 Since
1875 2.10
1876 ImageInfoSpecificQCow2Encryption (Object)
1878 Members
1879 The members of ImageInfoSpecificQCow2EncryptionBase
1880 The members of QCryptoBlockInfoLUKS when format is "luks"
1882 Since
1884 2.10
1885 ImageInfoSpecificQCow2 (Object)
1887 Members
1888 compat: string
1889 compatibility level
1890 data-file: string (optional)
1892 the filename of the external data file that is stored in the im‐
1893 age and used as a default for opening the image (since: 4.0)
1894 data-file-raw: boolean (optional)
1896 True if the external data file must stay valid as a standalone
1897 (read-only) raw image without looking at qcow2 metadata (since:
1898 4.0)
1899 extended-l2: boolean (optional)
1901 true if the image has extended L2 entries; only valid for compat
1902 >= 1.1 (since 5.2)
1903 lazy-refcounts: boolean (optional)
1905 on or off; only valid for compat >= 1.1
1906 corrupt: boolean (optional)
1908 true if the image has been marked corrupt; only valid for compat
1909 >= 1.1 (since 2.2)
1910 refcount-bits: int
1912 width of a refcount entry in bits (since 2.3)
1913 encrypt: ImageInfoSpecificQCow2Encryption (optional)
1915 details about encryption parameters; only set if image is en‐
1916 crypted (since 2.10)
1917 bitmaps: array of Qcow2BitmapInfo (optional)
1919 A list of qcow2 bitmap details (since 4.0)
1920 compression-type: Qcow2CompressionType
1922 the image cluster compression method (since 5.1)
1923 Since
1925 1.7
1926 ImageInfoSpecificVmdk (Object)
1928 Members
1929 create-type: string
1930 The create type of VMDK image
1931 cid: int
1933 Content id of image
1934 parent-cid: int
1936 Parent VMDK image's cid
1937 extents: array of ImageInfo
1939 List of extent files
1940 Since
1942 1.7
1943 ImageInfoSpecificRbd (Object)
1945 Members
1946 encryption-format: RbdImageEncryptionFormat (optional)
1947 Image encryption format
1948 Since
1950 6.1
1951 ImageInfoSpecific (Object)
1953 A discriminated record of image format specific information structures.
1954 Members
1956 type One of qcow2, vmdk, luks, rbd
1957 data: ImageInfoSpecificQCow2 when type is "qcow2"
1959 data: ImageInfoSpecificVmdk when type is "vmdk"
1961 data: QCryptoBlockInfoLUKS when type is "luks"
1963 data: ImageInfoSpecificRbd when type is "rbd"
1965 Since
1967 1.7
1968 ImageInfo (Object)
1970 Information about a QEMU image file
1971 Members
1973 filename: string
1974 name of the image file
1975 format: string
1977 format of the image file
1978 virtual-size: int
1980 maximum capacity in bytes of the image
1981 actual-size: int (optional)
1983 actual size on disk in bytes of the image
1984 dirty-flag: boolean (optional)
1986 true if image is not cleanly closed
1987 cluster-size: int (optional)
1989 size of a cluster in bytes
1990 encrypted: boolean (optional)
1992 true if the image is encrypted
1993 compressed: boolean (optional)
1995 true if the image is compressed (Since 1.7)
1996 backing-filename: string (optional)
1998 name of the backing file
1999 full-backing-filename: string (optional)
2001 full path of the backing file
2002 backing-filename-format: string (optional)
2004 the format of the backing file
2005 snapshots: array of SnapshotInfo (optional)
2007 list of VM snapshots
2008 backing-image: ImageInfo (optional)
2010 info of the backing image (since 1.6)
2011 format-specific: ImageInfoSpecific (optional)
2013 structure supplying additional format-specific information
2014 (since 1.7)
2015 Since
2017 1.3
2018 ImageCheck (Object)
2020 Information about a QEMU image file check
2021 Members
2023 filename: string
2024 name of the image file checked
2025 format: string
2027 format of the image file checked
2028 check-errors: int
2030 number of unexpected errors occurred during check
2031 image-end-offset: int (optional)
2033 offset (in bytes) where the image ends, this field is present if
2034 the driver for the image format supports it
2035 corruptions: int (optional)
2037 number of corruptions found during the check if any
2038 leaks: int (optional)
2040 number of leaks found during the check if any
2041 corruptions-fixed: int (optional)
2043 number of corruptions fixed during the check if any
2044 leaks-fixed: int (optional)
2046 number of leaks fixed during the check if any
2047 total-clusters: int (optional)
2049 total number of clusters, this field is present if the driver
2050 for the image format supports it
2051 allocated-clusters: int (optional)
2053 total number of allocated clusters, this field is present if the
2054 driver for the image format supports it
2055 fragmented-clusters: int (optional)
2057 total number of fragmented clusters, this field is present if
2058 the driver for the image format supports it
2059 compressed-clusters: int (optional)
2061 total number of compressed clusters, this field is present if
2062 the driver for the image format supports it
2063 Since
2065 1.4
2066 MapEntry (Object)
2068 Mapping information from a virtual block range to a host file range
2069 Members
2071 start: int
2072 virtual (guest) offset of the first byte described by this entry
2073 length: int
2075 the number of bytes of the mapped virtual range
2076 data: boolean
2078 reading the image will actually read data from a file (in par‐
2079 ticular, if offset is present this means that the sectors are
2080 not simply preallocated, but contain actual data in raw format)
2081 zero: boolean
2083 whether the virtual blocks read as zeroes
2084 depth: int
2086 number of layers (0 = top image, 1 = top image's backing file,
2087 ..., n - 1 = bottom image (where n is the number of images in
2088 the chain)) before reaching one for which the range is allocated
2089 present: boolean
2091 true if this layer provides the data, false if adding a backing
2092 layer could impact this region (since 6.1)
2093 offset: int (optional)
2095 if present, the image file stores the data for this range in raw
2096 format at the given (host) offset
2097 filename: string (optional)
2099 filename that is referred to by offset
2100 Since
2102 2.6
2103 BlockdevCacheInfo (Object)
2105 Cache mode information for a block device
2106 Members
2108 writeback: boolean
2109 true if writeback mode is enabled
2110 direct: boolean
2112 true if the host page cache is bypassed (O_DIRECT)
2113 no-flush: boolean
2115 true if flush requests are ignored for the device
2116 Since
2118 2.3
2119 BlockDeviceInfo (Object)
2121 Information about the backing device for a block device.
2122 Members
2124 file: string
2125 the filename of the backing device
2126 node-name: string (optional)
2128 the name of the block driver node (Since 2.0)
2129 ro: boolean
2131 true if the backing device was open read-only
2132 drv: string
2134 the name of the block format used to open the backing device. As
2135 of 0.14 this can be: 'blkdebug', 'bochs', 'cloop', 'cow', 'dmg',
2136 'file', 'file', 'ftp', 'ftps', 'host_cdrom', 'host_device',
2137 'http', 'https', 'luks', 'nbd', 'parallels', 'qcow', 'qcow2',
2138 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago' added,
2139 'cow' dropped 2.3: 'host_floppy' deprecated 2.5: 'host_floppy'
2140 dropped 2.6: 'luks' added 2.8: 'replication' added, 'tftp'
2141 dropped 2.9: 'archipelago' dropped
2142 backing_file: string (optional)
2144 the name of the backing file (for copy-on-write)
2145 backing_file_depth: int
2147 number of files in the backing file chain (since: 1.2)
2148 encrypted: boolean
2150 true if the backing device is encrypted
2151 detect_zeroes: BlockdevDetectZeroesOptions
2153 detect and optimize zero writes (Since 2.1)
2154 bps: int
2156 total throughput limit in bytes per second is specified
2157 bps_rd: int
2159 read throughput limit in bytes per second is specified
2160 bps_wr: int
2162 write throughput limit in bytes per second is specified
2163 iops: int
2165 total I/O operations per second is specified
2166 iops_rd: int
2168 read I/O operations per second is specified
2169 iops_wr: int
2171 write I/O operations per second is specified
2172 image: ImageInfo
2174 the info of image used (since: 1.6)
2175 bps_max: int (optional)
2177 total throughput limit during bursts,
2179 in bytes (Since 1.7)
2180 bps_rd_max: int (optional)
2182 read throughput limit during bursts,
2184 in bytes (Since 1.7)
2185 bps_wr_max: int (optional)
2187 write throughput limit during bursts,
2189 in bytes (Since 1.7)
2190 iops_max: int (optional)
2192 total I/O operations per second during bursts,
2194 in bytes (Since 1.7)
2195 iops_rd_max: int (optional)
2197 read I/O operations per second during bursts,
2199 in bytes (Since 1.7)
2200 iops_wr_max: int (optional)
2202 write I/O operations per second during bursts,
2204 in bytes (Since 1.7)
2205 bps_max_length: int (optional)
2207 maximum length of the bps_max burst
2209 period, in seconds. (Since 2.6)
2210 bps_rd_max_length: int (optional)
2212 maximum length of the bps_rd_max
2214 burst period, in seconds. (Since 2.6)
2215 bps_wr_max_length: int (optional)
2217 maximum length of the bps_wr_max
2219 burst period, in seconds. (Since 2.6)
2220 iops_max_length: int (optional)
2222 maximum length of the iops burst
2224 period, in seconds. (Since 2.6)
2225 iops_rd_max_length: int (optional)
2227 maximum length of the iops_rd_max
2229 burst period, in seconds. (Since 2.6)
2230 iops_wr_max_length: int (optional)
2232 maximum length of the iops_wr_max
2234 burst period, in seconds. (Since 2.6)
2235 iops_size: int (optional)
2237 an I/O size in bytes (Since 1.7)
2238 group: string (optional)
2240 throttle group name (Since 2.4)
2241 cache: BlockdevCacheInfo
2243 the cache mode used for the block device (since: 2.3)
2244 write_threshold: int
2246 configured write threshold for the device. 0 if disabled.
2247 (Since 2.3)
2248 dirty-bitmaps: array of BlockDirtyInfo (optional)
2250 dirty bitmaps information (only present if node has one or more
2251 dirty bitmaps) (Since 4.2)
2252 Since
2254 0.14
2255 BlockDeviceIoStatus (Enum)
2257 An enumeration of block device I/O status.
2258 Values
2260 ok The last I/O operation has succeeded
2261 failed The last I/O operation has failed
2263 nospace
2265 The last I/O operation has failed due to a no-space condition
2266 Since
2268 1.0
2269 BlockDirtyInfo (Object)
2271 Block dirty bitmap information.
2272 Members
2274 name: string (optional)
2275 the name of the dirty bitmap (Since 2.4)
2276 count: int
2278 number of dirty bytes according to the dirty bitmap
2279 granularity: int
2281 granularity of the dirty bitmap in bytes (since 1.4)
2282 recording: boolean
2284 true if the bitmap is recording new writes from the guest. Re‐
2285 places active and disabled statuses. (since 4.0)
2286 busy: boolean
2288 true if the bitmap is in-use by some operation (NBD or jobs) and
2289 cannot be modified via QMP or used by another operation. Re‐
2290 places locked and frozen statuses. (since 4.0)
2291 persistent: boolean
2293 true if the bitmap was stored on disk, is scheduled to be stored
2294 on disk, or both. (since 4.0)
2295 inconsistent: boolean (optional)
2297 true if this is a persistent bitmap that was improperly stored.
2298 Implies persistent to be true; recording and busy to be false.
2299 This bitmap cannot be used. To remove it, use block-dirty-bit‐
2300 map-remove. (Since 4.0)
2301 Since
2303 1.3
2304 Qcow2BitmapInfoFlags (Enum)
2306 An enumeration of flags that a bitmap can report to the user.
2307 Values
2309 in-use This flag is set by any process actively modifying the qcow2
2310 file, and cleared when the updated bitmap is flushed to the
2311 qcow2 image. The presence of this flag in an offline image
2312 means that the bitmap was not saved correctly after its last us‐
2313 age, and may contain inconsistent data.
2314 auto The bitmap must reflect all changes of the virtual disk by any
2316 application that would write to this qcow2 file.
2317 Since
2319 4.0
2320 Qcow2BitmapInfo (Object)
2322 Qcow2 bitmap information.
2323 Members
2325 name: string
2326 the name of the bitmap
2327 granularity: int
2329 granularity of the bitmap in bytes
2330 flags: array of Qcow2BitmapInfoFlags
2332 flags of the bitmap
2333 Since
2335 4.0
2336 BlockLatencyHistogramInfo (Object)
2338 Block latency histogram.
2339 Members
2341 boundaries: array of int
2342 list of interval boundary values in nanoseconds, all greater
2343 than zero and in ascending order. For example, the list [10,
2344 50, 100] produces the following histogram intervals: [0, 10),
2345 [10, 50), [50, 100), [100, +inf).
2346 bins: array of int
2348 list of io request counts corresponding to histogram intervals.
2349 len(bins) = len(boundaries) + 1 For the example above, bins may
2350 be something like [3, 1, 5, 2], and corresponding histogram
2351 looks like:
2352 5| *
2354 4| *
2355 3| * *
2356 2| * * *
2357 1| * * * *
2358 +------------------
2359 10 50 100
2360 Since
2362 4.0
2363 BlockInfo (Object)
2365 Block device information. This structure describes a virtual device
2366 and the backing device associated with it.
2367 Members
2369 device: string
2370 The device name associated with the virtual device.
2371 qdev: string (optional)
2373 The qdev ID, or if no ID is assigned, the QOM path of the block
2374 device. (since 2.10)
2375 type: string
2377 This field is returned only for compatibility reasons, it should
2378 not be used (always returns 'unknown')
2379 removable: boolean
2381 True if the device supports removable media.
2382 locked: boolean
2384 True if the guest has locked this device from having its media
2385 removed
2386 tray_open: boolean (optional)
2388 True if the device's tray is open (only present if it has a
2389 tray)
2390 io-status: BlockDeviceIoStatus (optional)
2392 BlockDeviceIoStatus. Only present if the device supports it and
2393 the VM is configured to stop on errors (supported device models:
2394 virtio-blk, IDE, SCSI except scsi-generic)
2395 inserted: BlockDeviceInfo (optional)
2397 BlockDeviceInfo describing the device if media is present
2398 Since
2400 0.14
2401 BlockMeasureInfo (Object)
2403 Image file size calculation information. This structure describes the
2404 size requirements for creating a new image file.
2405 The size requirements depend on the new image file format. File size
2407 always equals virtual disk size for the 'raw' format, even for sparse
2408 POSIX files. Compact formats such as 'qcow2' represent unallocated and
2409 zero regions efficiently so file size may be smaller than virtual disk
2410 size.
2411 The values are upper bounds that are guaranteed to fit the new image
2413 file. Subsequent modification, such as internal snapshot or further
2414 bitmap creation, may require additional space and is not covered here.
2415 Members
2417 required: int
2418 Size required for a new image file, in bytes, when copying just
2419 allocated guest-visible contents.
2420 fully-allocated: int
2422 Image file size, in bytes, once data has been written to all
2423 sectors, when copying just guest-visible contents.
2424 bitmaps: int (optional)
2426 Additional size required if all the top-level bitmap metadata in
2427 the source image were to be copied to the destination, present
2428 only when source and destination both support persistent bit‐
2429 maps. (since 5.1)
2430 Since
2432 2.10
2433 query-block (Command)
2435 Get a list of BlockInfo for all virtual block devices.
2436 Returns
2438 a list of BlockInfo describing each virtual block device. Filter nodes
2439 that were created implicitly are skipped over.
2440 Since
2442 0.14
2443 Example
2445 -> { "execute": "query-block" }
2446 <- {
2447 "return":[
2448 {
2449 "io-status": "ok",
2450 "device":"ide0-hd0",
2451 "locked":false,
2452 "removable":false,
2453 "inserted":{
2454 "ro":false,
2455 "drv":"qcow2",
2456 "encrypted":false,
2457 "file":"disks/test.qcow2",
2458 "backing_file_depth":1,
2459 "bps":1000000,
2460 "bps_rd":0,
2461 "bps_wr":0,
2462 "iops":1000000,
2463 "iops_rd":0,
2464 "iops_wr":0,
2465 "bps_max": 8000000,
2466 "bps_rd_max": 0,
2467 "bps_wr_max": 0,
2468 "iops_max": 0,
2469 "iops_rd_max": 0,
2470 "iops_wr_max": 0,
2471 "iops_size": 0,
2472 "detect_zeroes": "on",
2473 "write_threshold": 0,
2474 "image":{
2475 "filename":"disks/test.qcow2",
2476 "format":"qcow2",
2477 "virtual-size":2048000,
2478 "backing_file":"base.qcow2",
2479 "full-backing-filename":"disks/base.qcow2",
2480 "backing-filename-format":"qcow2",
2481 "snapshots":[
2482 {
2483 "id": "1",
2484 "name": "snapshot1",
2485 "vm-state-size": 0,
2486 "date-sec": 10000200,
2487 "date-nsec": 12,
2488 "vm-clock-sec": 206,
2489 "vm-clock-nsec": 30
2490 }
2491 ],
2492 "backing-image":{
2493 "filename":"disks/base.qcow2",
2494 "format":"qcow2",
2495 "virtual-size":2048000
2496 }
2497 }
2498 },
2499 "qdev": "ide_disk",
2500 "type":"unknown"
2501 },
2502 {
2503 "io-status": "ok",
2504 "device":"ide1-cd0",
2505 "locked":false,
2506 "removable":true,
2507 "qdev": "/machine/unattached/device[23]",
2508 "tray_open": false,
2509 "type":"unknown"
2510 },
2511 {
2512 "device":"floppy0",
2513 "locked":false,
2514 "removable":true,
2515 "qdev": "/machine/unattached/device[20]",
2516 "type":"unknown"
2517 },
2518 {
2519 "device":"sd0",
2520 "locked":false,
2521 "removable":true,
2522 "type":"unknown"
2523 }
2524 ]
2525 }
2526 BlockDeviceTimedStats (Object)
2528 Statistics of a block device during a given interval of time.
2529 Members
2531 interval_length: int
2532 Interval used for calculating the statistics, in seconds.
2533 min_rd_latency_ns: int
2535 Minimum latency of read operations in the defined interval, in
2536 nanoseconds.
2537 min_wr_latency_ns: int
2539 Minimum latency of write operations in the defined interval, in
2540 nanoseconds.
2541 min_flush_latency_ns: int
2543 Minimum latency of flush operations in the defined interval, in
2544 nanoseconds.
2545 max_rd_latency_ns: int
2547 Maximum latency of read operations in the defined interval, in
2548 nanoseconds.
2549 max_wr_latency_ns: int
2551 Maximum latency of write operations in the defined interval, in
2552 nanoseconds.
2553 max_flush_latency_ns: int
2555 Maximum latency of flush operations in the defined interval, in
2556 nanoseconds.
2557 avg_rd_latency_ns: int
2559 Average latency of read operations in the defined interval, in
2560 nanoseconds.
2561 avg_wr_latency_ns: int
2563 Average latency of write operations in the defined interval, in
2564 nanoseconds.
2565 avg_flush_latency_ns: int
2567 Average latency of flush operations in the defined interval, in
2568 nanoseconds.
2569 avg_rd_queue_depth: number
2571 Average number of pending read operations in the defined inter‐
2572 val.
2573 avg_wr_queue_depth: number
2575 Average number of pending write operations in the defined inter‐
2576 val.
2577 Since
2579 2.5
2580 BlockDeviceStats (Object)
2582 Statistics of a virtual block device or a block backing device.
2583 Members
2585 rd_bytes: int
2586 The number of bytes read by the device.
2587 wr_bytes: int
2589 The number of bytes written by the device.
2590 unmap_bytes: int
2592 The number of bytes unmapped by the device (Since 4.2)
2593 rd_operations: int
2595 The number of read operations performed by the device.
2596 wr_operations: int
2598 The number of write operations performed by the device.
2599 flush_operations: int
2601 The number of cache flush operations performed by the device
2602 (since 0.15)
2603 unmap_operations: int
2605 The number of unmap operations performed by the device (Since
2606 4.2)
2607 rd_total_time_ns: int
2609 Total time spent on reads in nanoseconds (since 0.15).
2610 wr_total_time_ns: int
2612 Total time spent on writes in nanoseconds (since 0.15).
2613 flush_total_time_ns: int
2615 Total time spent on cache flushes in nanoseconds (since 0.15).
2616 unmap_total_time_ns: int
2618 Total time spent on unmap operations in nanoseconds (Since 4.2)
2619 wr_highest_offset: int
2621 The offset after the greatest byte written to the device. The
2622 intended use of this information is for growable sparse files
2623 (like qcow2) that are used on top of a physical device.
2624 rd_merged: int
2626 Number of read requests that have been merged into another re‐
2627 quest (Since 2.3).
2628 wr_merged: int
2630 Number of write requests that have been merged into another re‐
2631 quest (Since 2.3).
2632 unmap_merged: int
2634 Number of unmap requests that have been merged into another re‐
2635 quest (Since 4.2)
2636 idle_time_ns: int (optional)
2638 Time since the last I/O operation, in nanoseconds. If the field
2639 is absent it means that there haven't been any operations yet
2640 (Since 2.5).
2641 failed_rd_operations: int
2643 The number of failed read operations performed by the device
2644 (Since 2.5)
2645 failed_wr_operations: int
2647 The number of failed write operations performed by the device
2648 (Since 2.5)
2649 failed_flush_operations: int
2651 The number of failed flush operations performed by the device
2652 (Since 2.5)
2653 failed_unmap_operations: int
2655 The number of failed unmap operations performed by the device
2656 (Since 4.2)
2657 invalid_rd_operations: int
2659 The number of invalid read operations
2661 performed by the device (Since 2.5)
2662 invalid_wr_operations: int
2664 The number of invalid write operations performed by the device
2665 (Since 2.5)
2666 invalid_flush_operations: int
2668 The number of invalid flush operations performed by the device
2669 (Since 2.5)
2670 invalid_unmap_operations: int
2672 The number of invalid unmap operations performed by the device
2673 (Since 4.2)
2674 account_invalid: boolean
2676 Whether invalid operations are included in the last access sta‐
2677 tistics (Since 2.5)
2678 account_failed: boolean
2680 Whether failed operations are included in the latency and last
2681 access statistics (Since 2.5)
2682 timed_stats: array of BlockDeviceTimedStats
2684 Statistics specific to the set of previously defined intervals
2685 of time (Since 2.5)
2686 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
2688 BlockLatencyHistogramInfo. (Since 4.0)
2689 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
2691 BlockLatencyHistogramInfo. (Since 4.0)
2692 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
2694 BlockLatencyHistogramInfo. (Since 4.0)
2695 Since
2697 0.14
2698 BlockStatsSpecificFile (Object)
2700 File driver statistics
2701 Members
2703 discard-nb-ok: int
2704 The number of successful discard operations performed by the
2705 driver.
2706 discard-nb-failed: int
2708 The number of failed discard operations performed by the driver.
2709 discard-bytes-ok: int
2711 The number of bytes discarded by the driver.
2712 Since
2714 4.2
2715 BlockStatsSpecificNvme (Object)
2717 NVMe driver statistics
2718 Members
2720 completion-errors: int
2721 The number of completion errors.
2722 aligned-accesses: int
2724 The number of aligned accesses performed by the driver.
2725 unaligned-accesses: int
2727 The number of unaligned accesses performed by the driver.
2728 Since
2730 5.2
2731 BlockStatsSpecific (Object)
2733 Block driver specific statistics
2734 Members
2736 driver: BlockdevDriver
2737 Not documented
2738 The members of BlockStatsSpecificFile when driver is "file"
2740 The members of BlockStatsSpecificFile when driver is "host_device" (If:
2742 defined(HAVE_HOST_BLOCK_DEVICE))
2743 The members of BlockStatsSpecificNvme when driver is "nvme"
2745 Since
2747 4.2
2748 BlockStats (Object)
2750 Statistics of a virtual block device or a block backing device.
2751 Members
2753 device: string (optional)
2754 If the stats are for a virtual block device, the name corre‐
2755 sponding to the virtual block device.
2756 node-name: string (optional)
2758 The node name of the device. (Since 2.3)
2759 qdev: string (optional)
2761 The qdev ID, or if no ID is assigned, the QOM path of the block
2762 device. (since 3.0)
2763 stats: BlockDeviceStats
2765 A BlockDeviceStats for the device.
2766 driver-specific: BlockStatsSpecific (optional)
2768 Optional driver-specific stats. (Since 4.2)
2769 parent: BlockStats (optional)
2771 This describes the file block device if it has one. Contains
2772 recursively the statistics of the underlying protocol (e.g. the
2773 host file for a qcow2 image). If there is no underlying proto‐
2774 col, this field is omitted
2775 backing: BlockStats (optional)
2777 This describes the backing block device if it has one. (Since
2778 2.0)
2779 Since
2781 0.14
2782 query-blockstats (Command)
2784 Query the BlockStats for all virtual block devices.
2785 Arguments
2787 query-nodes: boolean (optional)
2788 If true, the command will query all the block nodes that have a
2789 node name, in a list which will include "parent" information,
2790 but not "backing". If false or omitted, the behavior is as be‐
2791 fore - query all the device backends, recursively including
2792 their "parent" and "backing". Filter nodes that were created im‐
2793 plicitly are skipped over in this mode. (Since 2.3)
2794 Returns
2796 A list of BlockStats for each virtual block devices.
2797 Since
2799 0.14
2800 Example
2802 -> { "execute": "query-blockstats" }
2803 <- {
2804 "return":[
2805 {
2806 "device":"ide0-hd0",
2807 "parent":{
2808 "stats":{
2809 "wr_highest_offset":3686448128,
2810 "wr_bytes":9786368,
2811 "wr_operations":751,
2812 "rd_bytes":122567168,
2813 "rd_operations":36772
2814 "wr_total_times_ns":313253456
2815 "rd_total_times_ns":3465673657
2816 "flush_total_times_ns":49653
2817 "flush_operations":61,
2818 "rd_merged":0,
2819 "wr_merged":0,
2820 "idle_time_ns":2953431879,
2821 "account_invalid":true,
2822 "account_failed":false
2823 }
2824 },
2825 "stats":{
2826 "wr_highest_offset":2821110784,
2827 "wr_bytes":9786368,
2828 "wr_operations":692,
2829 "rd_bytes":122739200,
2830 "rd_operations":36604
2831 "flush_operations":51,
2832 "wr_total_times_ns":313253456
2833 "rd_total_times_ns":3465673657
2834 "flush_total_times_ns":49653,
2835 "rd_merged":0,
2836 "wr_merged":0,
2837 "idle_time_ns":2953431879,
2838 "account_invalid":true,
2839 "account_failed":false
2840 },
2841 "qdev": "/machine/unattached/device[23]"
2842 },
2843 {
2844 "device":"ide1-cd0",
2845 "stats":{
2846 "wr_highest_offset":0,
2847 "wr_bytes":0,
2848 "wr_operations":0,
2849 "rd_bytes":0,
2850 "rd_operations":0
2851 "flush_operations":0,
2852 "wr_total_times_ns":0
2853 "rd_total_times_ns":0
2854 "flush_total_times_ns":0,
2855 "rd_merged":0,
2856 "wr_merged":0,
2857 "account_invalid":false,
2858 "account_failed":false
2859 },
2860 "qdev": "/machine/unattached/device[24]"
2861 },
2862 {
2863 "device":"floppy0",
2864 "stats":{
2865 "wr_highest_offset":0,
2866 "wr_bytes":0,
2867 "wr_operations":0,
2868 "rd_bytes":0,
2869 "rd_operations":0
2870 "flush_operations":0,
2871 "wr_total_times_ns":0
2872 "rd_total_times_ns":0
2873 "flush_total_times_ns":0,
2874 "rd_merged":0,
2875 "wr_merged":0,
2876 "account_invalid":false,
2877 "account_failed":false
2878 },
2879 "qdev": "/machine/unattached/device[16]"
2880 },
2881 {
2882 "device":"sd0",
2883 "stats":{
2884 "wr_highest_offset":0,
2885 "wr_bytes":0,
2886 "wr_operations":0,
2887 "rd_bytes":0,
2888 "rd_operations":0
2889 "flush_operations":0,
2890 "wr_total_times_ns":0
2891 "rd_total_times_ns":0
2892 "flush_total_times_ns":0,
2893 "rd_merged":0,
2894 "wr_merged":0,
2895 "account_invalid":false,
2896 "account_failed":false
2897 }
2898 }
2899 ]
2900 }
2901 BlockdevOnError (Enum)
2903 An enumeration of possible behaviors for errors on I/O operations. The
2904 exact meaning depends on whether the I/O was initiated by a guest or by
2905 a block job
2906 Values
2908 report for guest operations, report the error to the guest; for jobs,
2909 cancel the job
2910 ignore ignore the error, only report a QMP event (BLOCK_IO_ERROR or
2912 BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
2913 the failing request later and may still complete successfully.
2914 The stream block job continues to stream and will complete with
2915 an error.
2916 enospc same as stop on ENOSPC, same as report otherwise.
2918 stop for guest operations, stop the virtual machine; for jobs, pause
2920 the job
2921 auto inherit the error handling policy of the backend (since: 2.7)
2923 Since
2925 1.3
2926 MirrorSyncMode (Enum)
2928 An enumeration of possible behaviors for the initial synchronization
2929 phase of storage mirroring.
2930 Values
2932 top copies data in the topmost image to the destination
2933 full copies data from all images to the destination
2935 none only copy data written from now on
2937 incremental
2939 only copy data described by the dirty bitmap. (since: 2.4)
2940 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
2942 havior on completion is determined by the BitmapSyncMode.
2943 Since
2945 1.3
2946 BitmapSyncMode (Enum)
2948 An enumeration of possible behaviors for the synchronization of a bit‐
2949 map when used for data copy operations.
2950 Values
2952 on-success
2953 The bitmap is only synced when the operation is successful.
2954 This is the behavior always used for 'INCREMENTAL' backups.
2955 never The bitmap is never synchronized with the operation, and is
2957 treated solely as a read-only manifest of blocks to copy.
2958 always The bitmap is always synchronized with the operation, regardless
2960 of whether or not the operation was successful.
2961 Since
2963 4.2
2964 MirrorCopyMode (Enum)
2966 An enumeration whose values tell the mirror block job when to trigger
2967 writes to the target.
2968 Values
2970 background
2971 copy data in background only.
2972 write-blocking
2974 when data is written to the source, write it (synchronously) to
2975 the target as well. In addition, data is copied in background
2976 just like in background mode.
2977 Since
2979 3.0
2980 BlockJobInfo (Object)
2982 Information about a long-running block device operation.
2983 Members
2985 type: string
2986 the job type ('stream' for image streaming)
2987 device: string
2989 The job identifier. Originally the device name but other values
2990 are allowed since QEMU 2.7
2991 len: int
2993 Estimated offset value at the completion of the job. This value
2994 can arbitrarily change while the job is running, in both direc‐
2995 tions.
2996 offset: int
2998 Progress made until now. The unit is arbitrary and the value can
2999 only meaningfully be used for the ratio of offset to len. The
3000 value is monotonically increasing.
3001 busy: boolean
3003 false if the job is known to be in a quiescent state, with no
3004 pending I/O. Since 1.3.
3005 paused: boolean
3007 whether the job is paused or, if busy is true, will pause itself
3008 as soon as possible. Since 1.3.
3009 speed: int
3011 the rate limit, bytes per second
3012 io-status: BlockDeviceIoStatus
3014 the status of the job (since 1.3)
3015 ready: boolean
3017 true if the job may be completed (since 2.2)
3018 status: JobStatus
3020 Current job state/status (since 2.12)
3021 auto-finalize: boolean
3023 Job will finalize itself when PENDING, moving to the CONCLUDED
3024 state. (since 2.12)
3025 auto-dismiss: boolean
3027 Job will dismiss itself when CONCLUDED, moving to the NULL state
3028 and disappearing from the query list. (since 2.12)
3029 error: string (optional)
3031 Error information if the job did not complete successfully. Not
3032 set if the job completed successfully. (since 2.12.1)
3033 Since
3035 1.1
3036 query-block-jobs (Command)
3038 Return information about long-running block device operations.
3039 Returns
3041 a list of BlockJobInfo for each active block job
3042 Since
3044 1.1
3045 block_resize (Command)
3047 Resize a block image while a guest is running.
3048 Either device or node-name must be set but not both.
3050 Arguments
3052 device: string (optional)
3053 the name of the device to get the image resized
3054 node-name: string (optional)
3056 graph node name to get the image resized (Since 2.0)
3057 size: int
3059 new image size in bytes
3060 Returns
3062 • nothing on success
3063 • If device is not a valid block device, DeviceNotFound
3065 Since
3067 0.14
3068 Example
3070 -> { "execute": "block_resize",
3071 "arguments": { "device": "scratch", "size": 1073741824 } }
3072 <- { "return": {} }
3073 NewImageMode (Enum)
3075 An enumeration that tells QEMU how to set the backing file path in a
3076 new image file.
3077 Values
3079 existing
3080 QEMU should look for an existing image file.
3081 absolute-paths
3083 QEMU should create a new image with absolute paths for the back‐
3084 ing file. If there is no backing file available, the new image
3085 will not be backed either.
3086 Since
3088 1.1
3089 BlockdevSnapshotSync (Object)
3091 Either device or node-name must be set but not both.
3092 Members
3094 device: string (optional)
3095 the name of the device to take a snapshot of.
3096 node-name: string (optional)
3098 graph node name to generate the snapshot from (Since 2.0)
3099 snapshot-file: string
3101 the target of the new overlay image. If the file exists, or if
3102 it is a device, the overlay will be created in the existing
3103 file/device. Otherwise, a new file will be created.
3104 snapshot-node-name: string (optional)
3106 the graph node name of the new image (Since 2.0)
3107 format: string (optional)
3109 the format of the overlay image, default is 'qcow2'.
3110 mode: NewImageMode (optional)
3112 whether and how QEMU should create a new image, default is 'ab‐
3113 solute-paths'.
3114 BlockdevSnapshot (Object)
3116 Members
3117 node: string
3118 device or node name that will have a snapshot taken.
3119 overlay: string
3121 reference to the existing block device that will become the
3122 overlay of node, as part of taking the snapshot. It must not
3123 have a current backing file (this can be achieved by passing
3124 "backing": null to blockdev-add).
3125 Since
3127 2.5
3128 BackupPerf (Object)
3130 Optional parameters for backup. These parameters don't affect function‐
3131 ality, but may significantly affect performance.
3132 Members
3134 use-copy-range: boolean (optional)
3135 Use copy offloading. Default false.
3136 max-workers: int (optional)
3138 Maximum number of parallel requests for the sustained background
3139 copying process. Doesn't influence copy-before-write operations.
3140 Default 64.
3141 max-chunk: int (optional)
3143 Maximum request length for the sustained background copying
3144 process. Doesn't influence copy-before-write operations. 0
3145 means unlimited. If max-chunk is non-zero then it should not be
3146 less than job cluster size which is calculated as maximum of
3147 target image cluster size and 64k. Default 0.
3148 Since
3150 6.0
3151 BackupCommon (Object)
3153 Members
3154 job-id: string (optional)
3155 identifier for the newly-created block job. If omitted, the de‐
3156 vice name will be used. (Since 2.7)
3157 device: string
3159 the device name or node-name of a root node which should be
3160 copied.
3161 sync: MirrorSyncMode
3163 what parts of the disk image should be copied to the destination
3164 (all the disk, only the sectors allocated in the topmost image,
3165 from a dirty bitmap, or only new I/O).
3166 speed: int (optional)
3168 the maximum speed, in bytes per second. The default is 0, for
3169 unlimited.
3170 bitmap: string (optional)
3172 The name of a dirty bitmap to use. Must be present if sync is
3173 "bitmap" or "incremental". Can be present if sync is "full" or
3174 "top". Must not be present otherwise. (Since 2.4
3175 (drive-backup), 3.1 (blockdev-backup))
3176 bitmap-mode: BitmapSyncMode (optional)
3178 Specifies the type of data the bitmap should contain after the
3179 operation concludes. Must be present if a bitmap was provided,
3180 Must NOT be present otherwise. (Since 4.2)
3181 compress: boolean (optional)
3183 true to compress data, if the target format supports it. (de‐
3184 fault: false) (since 2.8)
3185 on-source-error: BlockdevOnError (optional)
3187 the action to take on an error on the source, default 'report'.
3188 'stop' and 'enospc' can only be used if the block device sup‐
3189 ports io-status (see BlockInfo).
3190 on-target-error: BlockdevOnError (optional)
3192 the action to take on an error on the target, default 'report'
3193 (no limitations, since this applies to a different block device
3194 than device).
3195 auto-finalize: boolean (optional)
3197 When false, this job will wait in a PENDING state after it has
3198 finished its work, waiting for block-job-finalize before making
3199 any block graph changes. When true, this job will automatically
3200 perform its abort or commit actions. Defaults to true. (Since
3201 2.12)
3202 auto-dismiss: boolean (optional)
3204 When false, this job will wait in a CONCLUDED state after it has
3205 completely ceased all work, and awaits block-job-dismiss. When
3206 true, this job will automatically disappear from the query list
3207 without user intervention. Defaults to true. (Since 2.12)
3208 filter-node-name: string (optional)
3210 the node name that should be assigned to the filter driver that
3211 the backup job inserts into the graph above node specified by
3212 drive. If this option is not given, a node name is autogener‐
3213 ated. (Since: 4.2)
3214 x-perf: BackupPerf (optional)
3216 Performance options. (Since 6.0)
3217 Note
3219 on-source-error and on-target-error only affect background I/O. If an
3220 error occurs during a guest write request, the device's rerror/werror
3221 actions will be used.
3222 Since
3224 4.2
3225 DriveBackup (Object)
3227 Members
3228 target: string
3229 the target of the new image. If the file exists, or if it is a
3230 device, the existing file/device will be used as the new desti‐
3231 nation. If it does not exist, a new file will be created.
3232 format: string (optional)
3234 the format of the new destination, default is to probe if mode
3235 is 'existing', else the format of the source
3236 mode: NewImageMode (optional)
3238 whether and how QEMU should create a new image, default is 'ab‐
3239 solute-paths'.
3240 The members of BackupCommon
3242 Since
3244 1.6
3245 BlockdevBackup (Object)
3247 Members
3248 target: string
3249 the device name or node-name of the backup target node.
3250 The members of BackupCommon
3252 Since
3254 2.3
3255 blockdev-snapshot-sync (Command)
3257 Takes a synchronous snapshot of a block device.
3258 For the arguments, see the documentation of BlockdevSnapshotSync.
3260 Returns
3262 • nothing on success
3263 • If device is not a valid block device, DeviceNotFound
3265 Since
3267 0.14
3268 Example
3270 -> { "execute": "blockdev-snapshot-sync",
3271 "arguments": { "device": "ide-hd0",
3272 "snapshot-file":
3273 "/some/place/my-image",
3274 "format": "qcow2" } }
3275 <- { "return": {} }
3276 blockdev-snapshot (Command)
3278 Takes a snapshot of a block device.
3279 Take a snapshot, by installing 'node' as the backing image of 'over‐
3281 lay'. Additionally, if 'node' is associated with a block device, the
3282 block device changes to using 'overlay' as its new active image.
3283 For the arguments, see the documentation of BlockdevSnapshot.
3285 Features
3287 allow-write-only-overlay
3288 If present, the check whether this operation is safe was relaxed
3289 so that it can be used to change backing file of a destination
3290 of a blockdev-mirror. (since 5.0)
3291 Since
3293 2.5
3294 Example
3296 -> { "execute": "blockdev-add",
3297 "arguments": { "driver": "qcow2",
3298 "node-name": "node1534",
3299 "file": { "driver": "file",
3300 "filename": "hd1.qcow2" },
3301 "backing": null } }
3302 <- { "return": {} }
3304 -> { "execute": "blockdev-snapshot",
3306 "arguments": { "node": "ide-hd0",
3307 "overlay": "node1534" } }
3308 <- { "return": {} }
3309 change-backing-file (Command)
3311 Change the backing file in the image file metadata. This does not
3312 cause QEMU to reopen the image file to reparse the backing filename (it
3313 may, however, perform a reopen to change permissions from r/o -> r/w ->
3314 r/o, if needed). The new backing file string is written into the image
3315 file metadata, and the QEMU internal strings are updated.
3316 Arguments
3318 image-node-name: string
3319 The name of the block driver state node of the image to modify.
3320 The "device" argument is used to verify "image-node-name" is in
3321 the chain described by "device".
3322 device: string
3324 The device name or node-name of the root node that owns im‐
3325 age-node-name.
3326 backing-file: string
3328 The string to write as the backing file. This string is not
3329 validated, so care should be taken when specifying the string or
3330 the image chain may not be able to be reopened again.
3331 Returns
3333 • Nothing on success
3334 • If "device" does not exist or cannot be determined, DeviceNotFound
3336 Since
3338 2.1
3339 block-commit (Command)
3341 Live commit of data from overlay image nodes into backing nodes - i.e.,
3342 writes data between 'top' and 'base' into 'base'.
3343 If top == base, that is an error. If top has no overlays on top of it,
3345 or if it is in use by a writer, the job will not be completed by it‐
3346 self. The user needs to complete the job with the block-job-complete
3347 command after getting the ready event. (Since 2.0)
3348 If the base image is smaller than top, then the base image will be re‐
3350 sized to be the same size as top. If top is smaller than the base im‐
3351 age, the base will not be truncated. If you want the base image size
3352 to match the size of the smaller top, you can safely truncate it your‐
3353 self once the commit operation successfully completes.
3354 Arguments
3356 job-id: string (optional)
3357 identifier for the newly-created block job. If omitted, the de‐
3358 vice name will be used. (Since 2.7)
3359 device: string
3361 the device name or node-name of a root node
3362 base-node: string (optional)
3364 The node name of the backing image to write data into. If not
3365 specified, this is the deepest backing image. (since: 3.1)
3366 base: string (optional)
3368 Same as base-node, except that it is a file name rather than a
3369 node name. This must be the exact filename string that was used
3370 to open the node; other strings, even if addressing the same
3371 file, are not accepted
3372 top-node: string (optional)
3374 The node name of the backing image within the image chain which
3375 contains the topmost data to be committed down. If not speci‐
3376 fied, this is the active layer. (since: 3.1)
3377 top: string (optional)
3379 Same as top-node, except that it is a file name rather than a
3380 node name. This must be the exact filename string that was used
3381 to open the node; other strings, even if addressing the same
3382 file, are not accepted
3383 backing-file: string (optional)
3385 The backing file string to write into the overlay image of
3386 'top'. If 'top' does not have an overlay image, or if 'top' is
3387 in use by a writer, specifying a backing file string is an er‐
3388 ror.
3389 This filename is not validated. If a pathname string is such
3391 that it cannot be resolved by QEMU, that means that subsequent
3392 QMP or HMP commands must use node-names for the image in ques‐
3393 tion, as filename lookup methods will fail.
3394 If not specified, QEMU will automatically determine the backing
3396 file string to use, or error out if there is no obvious choice.
3397 Care should be taken when specifying the string, to specify a
3398 valid filename or protocol. (Since 2.1)
3399 speed: int (optional)
3401 the maximum speed, in bytes per second
3402 on-error: BlockdevOnError (optional)
3404 the action to take on an error. 'ignore' means that the request
3405 should be retried. (default: report; Since: 5.0)
3406 filter-node-name: string (optional)
3408 the node name that should be assigned to the filter driver that
3409 the commit job inserts into the graph above top. If this option
3410 is not given, a node name is autogenerated. (Since: 2.9)
3411 auto-finalize: boolean (optional)
3413 When false, this job will wait in a PENDING state after it has
3414 finished its work, waiting for block-job-finalize before making
3415 any block graph changes. When true, this job will automatically
3416 perform its abort or commit actions. Defaults to true. (Since
3417 3.1)
3418 auto-dismiss: boolean (optional)
3420 When false, this job will wait in a CONCLUDED state after it has
3421 completely ceased all work, and awaits block-job-dismiss. When
3422 true, this job will automatically disappear from the query list
3423 without user intervention. Defaults to true. (Since 3.1)
3424 Features
3426 deprecated
3427 Members base and top are deprecated. Use base-node and top-node
3428 instead.
3429 Returns
3431 • Nothing on success
3432 • If device does not exist, DeviceNotFound
3434 • Any other error returns a GenericError.
3436 Since
3438 1.3
3439 Example
3441 -> { "execute": "block-commit",
3442 "arguments": { "device": "virtio0",
3443 "top": "/tmp/snap1.qcow2" } }
3444 <- { "return": {} }
3445 drive-backup (Command)
3447 Start a point-in-time copy of a block device to a new destination. The
3448 status of ongoing drive-backup operations can be checked with
3449 query-block-jobs where the BlockJobInfo.type field has the value
3450 'backup'. The operation can be stopped before it has completed using
3451 the block-job-cancel command.
3452 Arguments
3454 The members of DriveBackup
3455 Returns
3457 • nothing on success
3458 • If device is not a valid block device, GenericError
3460 Since
3462 1.6
3463 Example
3465 -> { "execute": "drive-backup",
3466 "arguments": { "device": "drive0",
3467 "sync": "full",
3468 "target": "backup.img" } }
3469 <- { "return": {} }
3470 blockdev-backup (Command)
3472 Start a point-in-time copy of a block device to a new destination. The
3473 status of ongoing blockdev-backup operations can be checked with
3474 query-block-jobs where the BlockJobInfo.type field has the value
3475 'backup'. The operation can be stopped before it has completed using
3476 the block-job-cancel command.
3477 Arguments
3479 The members of BlockdevBackup
3480 Returns
3482 • nothing on success
3483 • If device is not a valid block device, DeviceNotFound
3485 Since
3487 2.3
3488 Example
3490 -> { "execute": "blockdev-backup",
3491 "arguments": { "device": "src-id",
3492 "sync": "full",
3493 "target": "tgt-id" } }
3494 <- { "return": {} }
3495 query-named-block-nodes (Command)
3497 Get the named block driver list
3498 Arguments
3500 flat: boolean (optional)
3501 Omit the nested data about backing image ("backing-image" key)
3502 if true. Default is false (Since 5.0)
3503 Returns
3505 the list of BlockDeviceInfo
3506 Since
3508 2.0
3509 Example
3511 -> { "execute": "query-named-block-nodes" }
3512 <- { "return": [ { "ro":false,
3513 "drv":"qcow2",
3514 "encrypted":false,
3515 "file":"disks/test.qcow2",
3516 "node-name": "my-node",
3517 "backing_file_depth":1,
3518 "bps":1000000,
3519 "bps_rd":0,
3520 "bps_wr":0,
3521 "iops":1000000,
3522 "iops_rd":0,
3523 "iops_wr":0,
3524 "bps_max": 8000000,
3525 "bps_rd_max": 0,
3526 "bps_wr_max": 0,
3527 "iops_max": 0,
3528 "iops_rd_max": 0,
3529 "iops_wr_max": 0,
3530 "iops_size": 0,
3531 "write_threshold": 0,
3532 "image":{
3533 "filename":"disks/test.qcow2",
3534 "format":"qcow2",
3535 "virtual-size":2048000,
3536 "backing_file":"base.qcow2",
3537 "full-backing-filename":"disks/base.qcow2",
3538 "backing-filename-format":"qcow2",
3539 "snapshots":[
3540 {
3541 "id": "1",
3542 "name": "snapshot1",
3543 "vm-state-size": 0,
3544 "date-sec": 10000200,
3545 "date-nsec": 12,
3546 "vm-clock-sec": 206,
3547 "vm-clock-nsec": 30
3548 }
3549 ],
3550 "backing-image":{
3551 "filename":"disks/base.qcow2",
3552 "format":"qcow2",
3553 "virtual-size":2048000
3554 }
3555 } } ] }
3556 XDbgBlockGraphNodeType (Enum)
3558 Values
3559 block-backend
3560 corresponds to BlockBackend
3561 block-job
3563 corresponds to BlockJob
3564 block-driver
3566 corresponds to BlockDriverState
3567 Since
3569 4.0
3570 XDbgBlockGraphNode (Object)
3572 Members
3573 id: int
3574 Block graph node identifier. This id is generated only for x-de‐
3575 bug-query-block-graph and does not relate to any other identi‐
3576 fiers in Qemu.
3577 type: XDbgBlockGraphNodeType
3579 Type of graph node. Can be one of block-backend, block-job or
3580 block-driver-state.
3581 name: string
3583 Human readable name of the node. Corresponds to node-name for
3584 block-driver-state nodes; is not guaranteed to be unique in the
3585 whole graph (with block-jobs and block-backends).
3586 Since
3588 4.0
3589 BlockPermission (Enum)
3591 Enum of base block permissions.
3592 Values
3594 consistent-read
3595 A user that has the "permission" of consistent reads is guaran‐
3596 teed that their view of the contents of the block device is com‐
3597 plete and self-consistent, representing the contents of a disk
3598 at a specific point. For most block devices (including their
3599 backing files) this is true, but the property cannot be main‐
3600 tained in a few situations like for intermediate nodes of a com‐
3601 mit block job.
3602 write This permission is required to change the visible disk contents.
3604 write-unchanged
3606 This permission (which is weaker than BLK_PERM_WRITE) is both
3607 enough and required for writes to the block node when the caller
3608 promises that the visible disk content doesn't change. As the
3609 BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
3610 cient to perform an unchanging write.
3611 resize This permission is required to change the size of a block node.
3613 graph-mod
3615 This permission is required to change the node that this
3616 BdrvChild points to.
3617 Since
3619 4.0
3620 XDbgBlockGraphEdge (Object)
3622 Block Graph edge description for x-debug-query-block-graph.
3623 Members
3625 parent: int
3626 parent id
3627 child: int
3629 child id
3630 name: string
3632 name of the relation (examples are 'file' and 'backing')
3633 perm: array of BlockPermission
3635 granted permissions for the parent operating on the child
3636 shared-perm: array of BlockPermission
3638 permissions that can still be granted to other users of the
3639 child while it is still attached to this parent
3640 Since
3642 4.0
3643 XDbgBlockGraph (Object)
3645 Block Graph - list of nodes and list of edges.
3646 Members
3648 nodes: array of XDbgBlockGraphNode
3649 Not documented
3650 edges: array of XDbgBlockGraphEdge
3652 Not documented
3653 Since
3655 4.0
3656 x-debug-query-block-graph (Command)
3658 Get the block graph.
3659 Since
3661 4.0
3662 drive-mirror (Command)
3664 Start mirroring a block device's writes to a new destination. target
3665 specifies the target of the new image. If the file exists, or if it is
3666 a device, it will be used as the new destination for writes. If it does
3667 not exist, a new file will be created. format specifies the format of
3668 the mirror image, default is to probe if mode='existing', else the for‐
3669 mat of the source.
3670 Arguments
3672 The members of DriveMirror
3673 Returns
3675 • nothing on success
3676 • If device is not a valid block device, GenericError
3678 Since
3680 1.3
3681 Example
3683 -> { "execute": "drive-mirror",
3684 "arguments": { "device": "ide-hd0",
3685 "target": "/some/place/my-image",
3686 "sync": "full",
3687 "format": "qcow2" } }
3688 <- { "return": {} }
3689 DriveMirror (Object)
3691 A set of parameters describing drive mirror setup.
3692 Members
3694 job-id: string (optional)
3695 identifier for the newly-created block job. If omitted, the de‐
3696 vice name will be used. (Since 2.7)
3697 device: string
3699 the device name or node-name of a root node whose writes should
3700 be mirrored.
3701 target: string
3703 the target of the new image. If the file exists, or if it is a
3704 device, the existing file/device will be used as the new desti‐
3705 nation. If it does not exist, a new file will be created.
3706 format: string (optional)
3708 the format of the new destination, default is to probe if mode
3709 is 'existing', else the format of the source
3710 node-name: string (optional)
3712 the new block driver state node name in the graph (Since 2.1)
3713 replaces: string (optional)
3715 with sync=full graph node name to be replaced by the new image
3716 when a whole image copy is done. This can be used to repair bro‐
3717 ken Quorum files. By default, device is replaced, although im‐
3718 plicitly created filters on it are kept. (Since 2.1)
3719 mode: NewImageMode (optional)
3721 whether and how QEMU should create a new image, default is 'ab‐
3722 solute-paths'.
3723 speed: int (optional)
3725 the maximum speed, in bytes per second
3726 sync: MirrorSyncMode
3728 what parts of the disk image should be copied to the destination
3729 (all the disk, only the sectors allocated in the topmost image,
3730 or only new I/O).
3731 granularity: int (optional)
3733 granularity of the dirty bitmap, default is 64K if the image
3734 format doesn't have clusters, 4K if the clusters are smaller
3735 than that, else the cluster size. Must be a power of 2 between
3736 512 and 64M (since 1.4).
3737 buf-size: int (optional)
3739 maximum amount of data in flight from source to target (since
3740 1.4).
3741 on-source-error: BlockdevOnError (optional)
3743 the action to take on an error on the source, default 'report'.
3744 'stop' and 'enospc' can only be used if the block device sup‐
3745 ports io-status (see BlockInfo).
3746 on-target-error: BlockdevOnError (optional)
3748 the action to take on an error on the target, default 'report'
3749 (no limitations, since this applies to a different block device
3750 than device).
3751 unmap: boolean (optional)
3753 Whether to try to unmap target sectors where source has only
3754 zero. If true, and target unallocated sectors will read as zero,
3755 target image sectors will be unmapped; otherwise, zeroes will be
3756 written. Both will result in identical contents. Default is
3757 true. (Since 2.4)
3758 copy-mode: MirrorCopyMode (optional)
3760 when to copy data to the destination; defaults to 'background'
3761 (Since: 3.0)
3762 auto-finalize: boolean (optional)
3764 When false, this job will wait in a PENDING state after it has
3765 finished its work, waiting for block-job-finalize before making
3766 any block graph changes. When true, this job will automatically
3767 perform its abort or commit actions. Defaults to true. (Since
3768 3.1)
3769 auto-dismiss: boolean (optional)
3771 When false, this job will wait in a CONCLUDED state after it has
3772 completely ceased all work, and awaits block-job-dismiss. When
3773 true, this job will automatically disappear from the query list
3774 without user intervention. Defaults to true. (Since 3.1)
3775 Since
3777 1.3
3778 BlockDirtyBitmap (Object)
3780 Members
3781 node: string
3782 name of device/node which the bitmap is tracking
3783 name: string
3785 name of the dirty bitmap
3786 Since
3788 2.4
3789 BlockDirtyBitmapAdd (Object)
3791 Members
3792 node: string
3793 name of device/node which the bitmap is tracking
3794 name: string
3796 name of the dirty bitmap (must be less than 1024 bytes)
3797 granularity: int (optional)
3799 the bitmap granularity, default is 64k for block-dirty-bit‐
3800 map-add
3801 persistent: boolean (optional)
3803 the bitmap is persistent, i.e. it will be saved to the corre‐
3804 sponding block device image file on its close. For now only
3805 Qcow2 disks support persistent bitmaps. Default is false for
3806 block-dirty-bitmap-add. (Since: 2.10)
3807 disabled: boolean (optional)
3809 the bitmap is created in the disabled state, which means that it
3810 will not track drive changes. The bitmap may be enabled with
3811 block-dirty-bitmap-enable. Default is false. (Since: 4.0)
3812 Since
3814 2.4
3815 BlockDirtyBitmapMergeSource (Alternate)
3817 Members
3818 local: string
3819 name of the bitmap, attached to the same node as target bitmap.
3820 external: BlockDirtyBitmap
3822 bitmap with specified node
3823 Since
3825 4.1
3826 BlockDirtyBitmapMerge (Object)
3828 Members
3829 node: string
3830 name of device/node which the target bitmap is tracking
3831 target: string
3833 name of the destination dirty bitmap
3834 bitmaps: array of BlockDirtyBitmapMergeSource
3836 name(s) of the source dirty bitmap(s) at node and/or fully spec‐
3837 ified BlockDirtyBitmap elements. The latter are supported since
3838 4.1.
3839 Since
3841 4.0
3842 block-dirty-bitmap-add (Command)
3844 Create a dirty bitmap with a name on the node, and start tracking the
3845 writes.
3846 Returns
3848 • nothing on success
3849 • If node is not a valid block device or node, DeviceNotFound
3851 • If name is already taken, GenericError with an explanation
3853 Since
3855 2.4
3856 Example
3858 -> { "execute": "block-dirty-bitmap-add",
3859 "arguments": { "node": "drive0", "name": "bitmap0" } }
3860 <- { "return": {} }
3861 block-dirty-bitmap-remove (Command)
3863 Stop write tracking and remove the dirty bitmap that was created with
3864 block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
3865 storage too.
3866 Returns
3868 • nothing on success
3869 • If node is not a valid block device or node, DeviceNotFound
3871 • If name is not found, GenericError with an explanation
3873 • if name is frozen by an operation, GenericError
3875 Since
3877 2.4
3878 Example
3880 -> { "execute": "block-dirty-bitmap-remove",
3881 "arguments": { "node": "drive0", "name": "bitmap0" } }
3882 <- { "return": {} }
3883 block-dirty-bitmap-clear (Command)
3885 Clear (reset) a dirty bitmap on the device, so that an incremental
3886 backup from this point in time forward will only backup clusters modi‐
3887 fied after this clear operation.
3888 Returns
3890 • nothing on success
3891 • If node is not a valid block device, DeviceNotFound
3893 • If name is not found, GenericError with an explanation
3895 Since
3897 2.4
3898 Example
3900 -> { "execute": "block-dirty-bitmap-clear",
3901 "arguments": { "node": "drive0", "name": "bitmap0" } }
3902 <- { "return": {} }
3903 block-dirty-bitmap-enable (Command)
3905 Enables a dirty bitmap so that it will begin tracking disk changes.
3906 Returns
3908 • nothing on success
3909 • If node is not a valid block device, DeviceNotFound
3911 • If name is not found, GenericError with an explanation
3913 Since
3915 4.0
3916 Example
3918 -> { "execute": "block-dirty-bitmap-enable",
3919 "arguments": { "node": "drive0", "name": "bitmap0" } }
3920 <- { "return": {} }
3921 block-dirty-bitmap-disable (Command)
3923 Disables a dirty bitmap so that it will stop tracking disk changes.
3924 Returns
3926 • nothing on success
3927 • If node is not a valid block device, DeviceNotFound
3929 • If name is not found, GenericError with an explanation
3931 Since
3933 4.0
3934 Example
3936 -> { "execute": "block-dirty-bitmap-disable",
3937 "arguments": { "node": "drive0", "name": "bitmap0" } }
3938 <- { "return": {} }
3939 block-dirty-bitmap-merge (Command)
3941 Merge dirty bitmaps listed in bitmaps to the target dirty bitmap.
3942 Dirty bitmaps in bitmaps will be unchanged, except if it also appears
3943 as the target bitmap. Any bits already set in target will still be set
3944 after the merge, i.e., this operation does not clear the target. On
3945 error, target is unchanged.
3946 The resulting bitmap will count as dirty any clusters that were dirty
3948 in any of the source bitmaps. This can be used to achieve backup check‐
3949 points, or in simpler usages, to copy bitmaps.
3950 Returns
3952 • nothing on success
3953 • If node is not a valid block device, DeviceNotFound
3955 • If any bitmap in bitmaps or target is not found, GenericError
3957 • If any of the bitmaps have different sizes or granularities, Gener‐
3959 icError
3960 Since
3962 4.0
3963 Example
3965 -> { "execute": "block-dirty-bitmap-merge",
3966 "arguments": { "node": "drive0", "target": "bitmap0",
3967 "bitmaps": ["bitmap1"] } }
3968 <- { "return": {} }
3969 BlockDirtyBitmapSha256 (Object)
3971 SHA256 hash of dirty bitmap data
3972 Members
3974 sha256: string
3975 ASCII representation of SHA256 bitmap hash
3976 Since
3978 2.10
3979 x-debug-block-dirty-bitmap-sha256 (Command)
3981 Get bitmap SHA256.
3982 Returns
3984 • BlockDirtyBitmapSha256 on success
3985 • If node is not a valid block device, DeviceNotFound
3987 • If name is not found or if hashing has failed, GenericError with an
3989 explanation
3990 Since
3992 2.10
3993 blockdev-mirror (Command)
3995 Start mirroring a block device's writes to a new destination.
3996 Arguments
3998 job-id: string (optional)
3999 identifier for the newly-created block job. If omitted, the de‐
4000 vice name will be used. (Since 2.7)
4001 device: string
4003 The device name or node-name of a root node whose writes should
4004 be mirrored.
4005 target: string
4007 the id or node-name of the block device to mirror to. This
4008 mustn't be attached to guest.
4009 replaces: string (optional)
4011 with sync=full graph node name to be replaced by the new image
4012 when a whole image copy is done. This can be used to repair bro‐
4013 ken Quorum files. By default, device is replaced, although im‐
4014 plicitly created filters on it are kept.
4015 speed: int (optional)
4017 the maximum speed, in bytes per second
4018 sync: MirrorSyncMode
4020 what parts of the disk image should be copied to the destination
4021 (all the disk, only the sectors allocated in the topmost image,
4022 or only new I/O).
4023 granularity: int (optional)
4025 granularity of the dirty bitmap, default is 64K if the image
4026 format doesn't have clusters, 4K if the clusters are smaller
4027 than that, else the cluster size. Must be a power of 2 between
4028 512 and 64M
4029 buf-size: int (optional)
4031 maximum amount of data in flight from source to target
4032 on-source-error: BlockdevOnError (optional)
4034 the action to take on an error on the source, default 'report'.
4035 'stop' and 'enospc' can only be used if the block device sup‐
4036 ports io-status (see BlockInfo).
4037 on-target-error: BlockdevOnError (optional)
4039 the action to take on an error on the target, default 'report'
4040 (no limitations, since this applies to a different block device
4041 than device).
4042 filter-node-name: string (optional)
4044 the node name that should be assigned to the filter driver that
4045 the mirror job inserts into the graph above device. If this op‐
4046 tion is not given, a node name is autogenerated. (Since: 2.9)
4047 copy-mode: MirrorCopyMode (optional)
4049 when to copy data to the destination; defaults to 'background'
4050 (Since: 3.0)
4051 auto-finalize: boolean (optional)
4053 When false, this job will wait in a PENDING state after it has
4054 finished its work, waiting for block-job-finalize before making
4055 any block graph changes. When true, this job will automatically
4056 perform its abort or commit actions. Defaults to true. (Since
4057 3.1)
4058 auto-dismiss: boolean (optional)
4060 When false, this job will wait in a CONCLUDED state after it has
4061 completely ceased all work, and awaits block-job-dismiss. When
4062 true, this job will automatically disappear from the query list
4063 without user intervention. Defaults to true. (Since 3.1)
4064 Returns
4066 nothing on success.
4067 Since
4069 2.6
4070 Example
4072 -> { "execute": "blockdev-mirror",
4073 "arguments": { "device": "ide-hd0",
4074 "target": "target0",
4075 "sync": "full" } }
4076 <- { "return": {} }
4077 BlockIOThrottle (Object)
4079 A set of parameters describing block throttling.
4080 Members
4082 device: string (optional)
4083 Block device name
4084 id: string (optional)
4086 The name or QOM path of the guest device (since: 2.8)
4087 bps: int
4089 total throughput limit in bytes per second
4090 bps_rd: int
4092 read throughput limit in bytes per second
4093 bps_wr: int
4095 write throughput limit in bytes per second
4096 iops: int
4098 total I/O operations per second
4099 iops_rd: int
4101 read I/O operations per second
4102 iops_wr: int
4104 write I/O operations per second
4105 bps_max: int (optional)
4107 total throughput limit during bursts, in bytes (Since 1.7)
4108 bps_rd_max: int (optional)
4110 read throughput limit during bursts, in bytes (Since 1.7)
4111 bps_wr_max: int (optional)
4113 write throughput limit during bursts, in bytes (Since 1.7)
4114 iops_max: int (optional)
4116 total I/O operations per second during bursts, in bytes (Since
4117 1.7)
4118 iops_rd_max: int (optional)
4120 read I/O operations per second during bursts, in bytes (Since
4121 1.7)
4122 iops_wr_max: int (optional)
4124 write I/O operations per second during bursts, in bytes (Since
4125 1.7)
4126 bps_max_length: int (optional)
4128 maximum length of the bps_max burst period, in seconds. It must
4129 only be set if bps_max is set as well. Defaults to 1. (Since
4130 2.6)
4131 bps_rd_max_length: int (optional)
4133 maximum length of the bps_rd_max burst period, in seconds. It
4134 must only be set if bps_rd_max is set as well. Defaults to 1.
4135 (Since 2.6)
4136 bps_wr_max_length: int (optional)
4138 maximum length of the bps_wr_max burst period, in seconds. It
4139 must only be set if bps_wr_max is set as well. Defaults to 1.
4140 (Since 2.6)
4141 iops_max_length: int (optional)
4143 maximum length of the iops burst period, in seconds. It must
4144 only be set if iops_max is set as well. Defaults to 1. (Since
4145 2.6)
4146 iops_rd_max_length: int (optional)
4148 maximum length of the iops_rd_max burst period, in seconds. It
4149 must only be set if iops_rd_max is set as well. Defaults to 1.
4150 (Since 2.6)
4151 iops_wr_max_length: int (optional)
4153 maximum length of the iops_wr_max burst period, in seconds. It
4154 must only be set if iops_wr_max is set as well. Defaults to 1.
4155 (Since 2.6)
4156 iops_size: int (optional)
4158 an I/O size in bytes (Since 1.7)
4159 group: string (optional)
4161 throttle group name (Since 2.4)
4162 Features
4164 deprecated
4165 Member device is deprecated. Use id instead.
4166 Since
4168 1.1
4169 ThrottleLimits (Object)
4171 Limit parameters for throttling. Since some limit combinations are il‐
4172 legal, limits should always be set in one transaction. All fields are
4173 optional. When setting limits, if a field is missing the current value
4174 is not changed.
4175 Members
4177 iops-total: int (optional)
4178 limit total I/O operations per second
4179 iops-total-max: int (optional)
4181 I/O operations burst
4182 iops-total-max-length: int (optional)
4184 length of the iops-total-max burst period, in seconds It must
4185 only be set if iops-total-max is set as well.
4186 iops-read: int (optional)
4188 limit read operations per second
4189 iops-read-max: int (optional)
4191 I/O operations read burst
4192 iops-read-max-length: int (optional)
4194 length of the iops-read-max burst period, in seconds It must
4195 only be set if iops-read-max is set as well.
4196 iops-write: int (optional)
4198 limit write operations per second
4199 iops-write-max: int (optional)
4201 I/O operations write burst
4202 iops-write-max-length: int (optional)
4204 length of the iops-write-max burst period, in seconds It must
4205 only be set if iops-write-max is set as well.
4206 bps-total: int (optional)
4208 limit total bytes per second
4209 bps-total-max: int (optional)
4211 total bytes burst
4212 bps-total-max-length: int (optional)
4214 length of the bps-total-max burst period, in seconds. It must
4215 only be set if bps-total-max is set as well.
4216 bps-read: int (optional)
4218 limit read bytes per second
4219 bps-read-max: int (optional)
4221 total bytes read burst
4222 bps-read-max-length: int (optional)
4224 length of the bps-read-max burst period, in seconds It must only
4225 be set if bps-read-max is set as well.
4226 bps-write: int (optional)
4228 limit write bytes per second
4229 bps-write-max: int (optional)
4231 total bytes write burst
4232 bps-write-max-length: int (optional)
4234 length of the bps-write-max burst period, in seconds It must
4235 only be set if bps-write-max is set as well.
4236 iops-size: int (optional)
4238 when limiting by iops max size of an I/O in bytes
4239 Since
4241 2.11
4242 ThrottleGroupProperties (Object)
4244 Properties for throttle-group objects.
4245 The options starting with x- are aliases for the same key without x- in
4247 the limits object. As indicated by the x- prefix, this is not a stable
4248 interface and may be removed or changed incompatibly in the future. Use
4249 limits for a supported stable interface.
4250 Members
4252 limits: ThrottleLimits (optional)
4253 limits to apply for this throttle group
4254 x-iops-total: int (optional)
4256 Not documented
4257 x-iops-total-max: int (optional)
4259 Not documented
4260 x-iops-total-max-length: int (optional)
4262 Not documented
4263 x-iops-read: int (optional)
4265 Not documented
4266 x-iops-read-max: int (optional)
4268 Not documented
4269 x-iops-read-max-length: int (optional)
4271 Not documented
4272 x-iops-write: int (optional)
4274 Not documented
4275 x-iops-write-max: int (optional)
4277 Not documented
4278 x-iops-write-max-length: int (optional)
4280 Not documented
4281 x-bps-total: int (optional)
4283 Not documented
4284 x-bps-total-max: int (optional)
4286 Not documented
4287 x-bps-total-max-length: int (optional)
4289 Not documented
4290 x-bps-read: int (optional)
4292 Not documented
4293 x-bps-read-max: int (optional)
4295 Not documented
4296 x-bps-read-max-length: int (optional)
4298 Not documented
4299 x-bps-write: int (optional)
4301 Not documented
4302 x-bps-write-max: int (optional)
4304 Not documented
4305 x-bps-write-max-length: int (optional)
4307 Not documented
4308 x-iops-size: int (optional)
4310 Not documented
4311 Since
4313 2.11
4314 block-stream (Command)
4316 Copy data from a backing file into a block device.
4317 The block streaming operation is performed in the background until the
4319 entire backing file has been copied. This command returns immediately
4320 once streaming has started. The status of ongoing block streaming op‐
4321 erations can be checked with query-block-jobs. The operation can be
4322 stopped before it has completed using the block-job-cancel command.
4323 The node that receives the data is called the top image, can be located
4325 in any part of the chain (but always above the base image; see below)
4326 and can be specified using its device or node name. Earlier qemu ver‐
4327 sions only allowed 'device' to name the top level node; presence of the
4328 'base-node' parameter during introspection can be used as a witness of
4329 the enhanced semantics of 'device'.
4330 If a base file is specified then sectors are not copied from that base
4332 file and its backing chain. This can be used to stream a subset of the
4333 backing file chain instead of flattening the entire image. When
4334 streaming completes the image file will have the base file as its back‐
4335 ing file, unless that node was changed while the job was running. In
4336 that case, base's parent's backing (or filtered, whichever exists)
4337 child (i.e., base at the beginning of the job) will be the new backing
4338 file.
4339 On successful completion the image file is updated to drop the backing
4341 file and the BLOCK_JOB_COMPLETED event is emitted.
4342 In case device is a filter node, block-stream modifies the first
4344 non-filter overlay node below it to point to the new backing node in‐
4345 stead of modifying device itself.
4346 Arguments
4348 job-id: string (optional)
4349 identifier for the newly-created block job. If omitted, the de‐
4350 vice name will be used. (Since 2.7)
4351 device: string
4353 the device or node name of the top image
4354 base: string (optional)
4356 the common backing file name. It cannot be set if base-node or
4357 bottom is also set.
4358 base-node: string (optional)
4360 the node name of the backing file. It cannot be set if base or
4361 bottom is also set. (Since 2.8)
4362 bottom: string (optional)
4364 the last node in the chain that should be streamed into top. It
4365 cannot be set if base or base-node is also set. It cannot be
4366 filter node. (Since 6.0)
4367 backing-file: string (optional)
4369 The backing file string to write into the top image. This file‐
4370 name is not validated.
4371 If a pathname string is such that it cannot be resolved by QEMU,
4373 that means that subsequent QMP or HMP commands must use
4374 node-names for the image in question, as filename lookup methods
4375 will fail.
4376 If not specified, QEMU will automatically determine the backing
4378 file string to use, or error out if there is no obvious choice.
4379 Care should be taken when specifying the string, to specify a
4380 valid filename or protocol. (Since 2.1)
4381 speed: int (optional)
4383 the maximum speed, in bytes per second
4384 on-error: BlockdevOnError (optional)
4386 the action to take on an error (default report). 'stop' and
4387 'enospc' can only be used if the block device supports io-status
4388 (see BlockInfo). Since 1.3.
4389 filter-node-name: string (optional)
4391 the node name that should be assigned to the filter driver that
4392 the stream job inserts into the graph above device. If this op‐
4393 tion is not given, a node name is autogenerated. (Since: 6.0)
4394 auto-finalize: boolean (optional)
4396 When false, this job will wait in a PENDING state after it has
4397 finished its work, waiting for block-job-finalize before making
4398 any block graph changes. When true, this job will automatically
4399 perform its abort or commit actions. Defaults to true. (Since
4400 3.1)
4401 auto-dismiss: boolean (optional)
4403 When false, this job will wait in a CONCLUDED state after it has
4404 completely ceased all work, and awaits block-job-dismiss. When
4405 true, this job will automatically disappear from the query list
4406 without user intervention. Defaults to true. (Since 3.1)
4407 Returns
4409 • Nothing on success.
4410 • If device does not exist, DeviceNotFound.
4412 Since
4414 1.1
4415 Example
4417 -> { "execute": "block-stream",
4418 "arguments": { "device": "virtio0",
4419 "base": "/tmp/master.qcow2" } }
4420 <- { "return": {} }
4421 block-job-set-speed (Command)
4423 Set maximum speed for a background block operation.
4424 This command can only be issued when there is an active block job.
4426 Throttling can be disabled by setting the speed to 0.
4428 Arguments
4430 device: string
4431 The job identifier. This used to be a device name (hence the
4432 name of the parameter), but since QEMU 2.7 it can have other
4433 values.
4434 speed: int
4436 the maximum speed, in bytes per second, or 0 for unlimited. De‐
4437 faults to 0.
4438 Returns
4440 • Nothing on success
4441 • If no background operation is active on this device, DeviceNotActive
4443 Since
4445 1.1
4446 block-job-cancel (Command)
4448 Stop an active background block operation.
4449 This command returns immediately after marking the active background
4451 block operation for cancellation. It is an error to call this command
4452 if no operation is in progress.
4453 The operation will cancel as soon as possible and then emit the
4455 BLOCK_JOB_CANCELLED event. Before that happens the job is still visi‐
4456 ble when enumerated using query-block-jobs.
4457 Note that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
4459 dicated (via the event BLOCK_JOB_READY) that the source and destination
4460 are synchronized, then the event triggered by this command changes to
4461 BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended and the
4462 destination now has a point-in-time copy tied to the time of the can‐
4463 cellation.
4464 For streaming, the image file retains its backing file unless the
4466 streaming operation happens to complete just as it is being cancelled.
4467 A new streaming operation can be started at a later time to finish
4468 copying all data from the backing file.
4469 Arguments
4471 device: string
4472 The job identifier. This used to be a device name (hence the
4473 name of the parameter), but since QEMU 2.7 it can have other
4474 values.
4475 force: boolean (optional)
4477 If true, and the job has already emitted the event
4478 BLOCK_JOB_READY, abandon the job immediately (even if it is
4479 paused) instead of waiting for the destination to complete its
4480 final synchronization (since 1.3)
4481 Returns
4483 • Nothing on success
4484 • If no background operation is active on this device, DeviceNotActive
4486 Since
4488 1.1
4489 block-job-pause (Command)
4491 Pause an active background block operation.
4492 This command returns immediately after marking the active background
4494 block operation for pausing. It is an error to call this command if no
4495 operation is in progress or if the job is already paused.
4496 The operation will pause as soon as possible. No event is emitted when
4498 the operation is actually paused. Cancelling a paused job automati‐
4499 cally resumes it.
4500 Arguments
4502 device: string
4503 The job identifier. This used to be a device name (hence the
4504 name of the parameter), but since QEMU 2.7 it can have other
4505 values.
4506 Returns
4508 • Nothing on success
4509 • If no background operation is active on this device, DeviceNotActive
4511 Since
4513 1.3
4514 block-job-resume (Command)
4516 Resume an active background block operation.
4517 This command returns immediately after resuming a paused background
4519 block operation. It is an error to call this command if no operation
4520 is in progress or if the job is not paused.
4521 This command also clears the error status of the job.
4523 Arguments
4525 device: string
4526 The job identifier. This used to be a device name (hence the
4527 name of the parameter), but since QEMU 2.7 it can have other
4528 values.
4529 Returns
4531 • Nothing on success
4532 • If no background operation is active on this device, DeviceNotActive
4534 Since
4536 1.3
4537 block-job-complete (Command)
4539 Manually trigger completion of an active background block operation.
4540 This is supported for drive mirroring, where it also switches the de‐
4541 vice to write to the target path only. The ability to complete is sig‐
4542 naled with a BLOCK_JOB_READY event.
4543 This command completes an active background block operation syn‐
4545 chronously. The ordering of this command's return with the
4546 BLOCK_JOB_COMPLETED event is not defined. Note that if an I/O error
4547 occurs during the processing of this command: 1) the command itself
4548 will fail; 2) the error will be processed according to the rerror/wer‐
4549 ror arguments that were specified when starting the operation.
4550 A cancelled or paused job cannot be completed.
4552 Arguments
4554 device: string
4555 The job identifier. This used to be a device name (hence the
4556 name of the parameter), but since QEMU 2.7 it can have other
4557 values.
4558 Returns
4560 • Nothing on success
4561 • If no background operation is active on this device, DeviceNotActive
4563 Since
4565 1.3
4566 block-job-dismiss (Command)
4568 For jobs that have already concluded, remove them from the
4569 block-job-query list. This command only needs to be run for jobs which
4570 were started with QEMU 2.12+ job lifetime management semantics.
4571 This command will refuse to operate on any job that has not yet reached
4573 its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
4574 BLOCK_JOB_READY event, block-job-cancel or block-job-complete will
4575 still need to be used as appropriate.
4576 Arguments
4578 id: string
4579 The job identifier.
4580 Returns
4582 Nothing on success
4583 Since
4585 2.12
4586 block-job-finalize (Command)
4588 Once a job that has manual=true reaches the pending state, it can be
4589 instructed to finalize any graph changes and do any necessary cleanup
4590 via this command. For jobs in a transaction, instructing one job to
4591 finalize will force ALL jobs in the transaction to finalize, so it is
4592 only necessary to instruct a single member job to finalize.
4593 Arguments
4595 id: string
4596 The job identifier.
4597 Returns
4599 Nothing on success
4600 Since
4602 2.12
4603 BlockdevDiscardOptions (Enum)
4605 Determines how to handle discard requests.
4606 Values
4608 ignore Ignore the request
4609 unmap Forward as an unmap request
4611 Since
4613 2.9
4614 BlockdevDetectZeroesOptions (Enum)
4616 Describes the operation mode for the automatic conversion of plain zero
4617 writes by the OS to driver specific optimized zero write commands.
4618 Values
4620 off Disabled (default)
4621 on Enabled
4623 unmap Enabled and even try to unmap blocks if possible. This requires
4625 also that BlockdevDiscardOptions is set to unmap for this de‐
4626 vice.
4627 Since
4629 2.1
4630 BlockdevAioOptions (Enum)
4632 Selects the AIO backend to handle I/O requests
4633 Values
4635 threads
4636 Use qemu's thread pool
4637 native Use native AIO backend (only Linux and Windows)
4639 io_uring (If: defined(CONFIG_LINUX_IO_URING))
4641 Use linux io_uring (since 5.0)
4642 Since
4644 2.9
4645 BlockdevCacheOptions (Object)
4647 Includes cache-related options for block devices
4648 Members
4650 direct: boolean (optional)
4651 enables use of O_DIRECT (bypass the host page cache; default:
4652 false)
4653 no-flush: boolean (optional)
4655 ignore any flush requests for the device (default: false)
4656 Since
4658 2.9
4659 BlockdevDriver (Enum)
4661 Drivers that are supported in block device operations.
4662 Values
4664 throttle
4665 Since 2.11
4666 nvme Since 2.12
4668 copy-on-read
4670 Since 3.0
4671 blklogwrites
4673 Since 3.0
4674 blkreplay
4676 Since 4.2
4677 compress
4679 Since 5.0
4680 blkdebug
4682 Not documented
4683 blkverify
4685 Not documented
4686 bochs Not documented
4688 cloop Not documented
4690 dmg Not documented
4692 file Not documented
4694 ftp Not documented
4696 ftps Not documented
4698 gluster
4700 Not documented
4701 host_cdrom (If: defined(HAVE_HOST_BLOCK_DEVICE))
4703 Not documented
4704 host_device (If: defined(HAVE_HOST_BLOCK_DEVICE))
4706 Not documented
4707 http Not documented
4709 https Not documented
4711 iscsi Not documented
4713 luks Not documented
4715 nbd Not documented
4717 nfs Not documented
4719 null-aio
4721 Not documented
4722 null-co
4724 Not documented
4725 parallels
4727 Not documented
4728 preallocate
4730 Not documented
4731 qcow Not documented
4733 qcow2 Not documented
4735 qed Not documented
4737 quorum Not documented
4739 raw Not documented
4741 rbd Not documented
4743 replication (If: defined(CONFIG_REPLICATION))
4745 Not documented
4746 ssh Not documented
4748 vdi Not documented
4750 vhdx Not documented
4752 vmdk Not documented
4754 vpc Not documented
4756 vvfat Not documented
4758 Since
4760 2.9
4761 BlockdevOptionsFile (Object)
4763 Driver specific block device options for the file backend.
4764 Members
4766 filename: string
4767 path to the image file
4768 pr-manager: string (optional)
4770 the id for the object that will handle persistent reservations
4771 for this device (default: none, forward the commands via SG_IO;
4772 since 2.11)
4773 aio: BlockdevAioOptions (optional)
4775 AIO backend (default: threads) (since: 2.8)
4776 locking: OnOffAuto (optional)
4778 whether to enable file locking. If set to 'auto', only enable
4779 when Open File Descriptor (OFD) locking API is available (de‐
4780 fault: auto, since 2.10)
4781 drop-cache: boolean (optional) (If: defined(CONFIG_LINUX))
4783 invalidate page cache during live migration. This prevents
4784 stale data on the migration destination with cache.direct=off.
4785 Currently only supported on Linux hosts. (default: on, since:
4786 4.0)
4787 x-check-cache-dropped: boolean (optional)
4789 whether to check that page cache was dropped on live migration.
4790 May cause noticeable delays if the image file is large, do not
4791 use in production. (default: off) (since: 3.0)
4792 Features
4794 dynamic-auto-read-only
4795 If present, enabled auto-read-only means that the driver will
4796 open the image read-only at first, dynamically reopen the image
4797 file read-write when the first writer is attached to the node
4798 and reopen read-only when the last writer is detached. This al‐
4799 lows giving QEMU write permissions only on demand when an opera‐
4800 tion actually needs write access.
4801 Since
4803 2.9
4804 BlockdevOptionsNull (Object)
4806 Driver specific block device options for the null backend.
4807 Members
4809 size: int (optional)
4810 size of the device in bytes.
4811 latency-ns: int (optional)
4813 emulated latency (in nanoseconds) in processing requests. De‐
4814 fault to zero which completes requests immediately. (Since 2.4)
4815 read-zeroes: boolean (optional)
4817 if true, reads from the device produce zeroes; if false, the
4818 buffer is left unchanged. (default: false; since: 4.1)
4819 Since
4821 2.9
4822 BlockdevOptionsNVMe (Object)
4824 Driver specific block device options for the NVMe backend.
4825 Members
4827 device: string
4828 PCI controller address of the NVMe device in format hhhh:bb:ss.f
4829 (host:bus:slot.function)
4830 namespace: int
4832 namespace number of the device, starting from 1.
4833 Note that the PCI device must have been unbound from any host kernel
4834 driver before instructing QEMU to add the blockdev.
4835 Since
4837 2.12
4838 BlockdevOptionsVVFAT (Object)
4840 Driver specific block device options for the vvfat protocol.
4841 Members
4843 dir: string
4844 directory to be exported as FAT image
4845 fat-type: int (optional)
4847 FAT type: 12, 16 or 32
4848 floppy: boolean (optional)
4850 whether to export a floppy image (true) or partitioned hard disk
4851 (false; default)
4852 label: string (optional)
4854 set the volume label, limited to 11 bytes. FAT16 and FAT32 tra‐
4855 ditionally have some restrictions on labels, which are ignored
4856 by most operating systems. Defaults to "QEMU VVFAT". (since
4857 2.4)
4858 rw: boolean (optional)
4860 whether to allow write operations (default: false)
4861 Since
4863 2.9
4864 BlockdevOptionsGenericFormat (Object)
4866 Driver specific block device options for image format that have no op‐
4867 tion besides their data source.
4868 Members
4870 file: BlockdevRef
4871 reference to or definition of the data source block device
4872 Since
4874 2.9
4875 BlockdevOptionsLUKS (Object)
4877 Driver specific block device options for LUKS.
4878 Members
4880 key-secret: string (optional)
4881 the ID of a QCryptoSecret object providing the decryption key
4882 (since 2.6). Mandatory except when doing a metadata-only probe
4883 of the image.
4884 The members of BlockdevOptionsGenericFormat
4886 Since
4888 2.9
4889 BlockdevOptionsGenericCOWFormat (Object)
4891 Driver specific block device options for image format that have no op‐
4892 tion besides their data source and an optional backing file.
4893 Members
4895 backing: BlockdevRefOrNull (optional)
4896 reference to or definition of the backing file block device,
4897 null disables the backing file entirely. Defaults to the back‐
4898 ing file stored the image file.
4899 The members of BlockdevOptionsGenericFormat
4901 Since
4903 2.9
4904 Qcow2OverlapCheckMode (Enum)
4906 General overlap check modes.
4907 Values
4909 none Do not perform any checks
4910 constant
4912 Perform only checks which can be done in constant time and with‐
4913 out reading anything from disk
4914 cached Perform only checks which can be done without reading anything
4916 from disk
4917 all Perform all available overlap checks
4919 Since
4921 2.9
4922 Qcow2OverlapCheckFlags (Object)
4924 Structure of flags for each metadata structure. Setting a field to
4925 'true' makes qemu guard that structure against unintended overwriting.
4926 The default value is chosen according to the template given.
4927 Members
4929 template: Qcow2OverlapCheckMode (optional)
4930 Specifies a template mode which can be adjusted using the other
4931 flags, defaults to 'cached'
4932 bitmap-directory: boolean (optional)
4934 since 3.0
4935 main-header: boolean (optional)
4937 Not documented
4938 active-l1: boolean (optional)
4940 Not documented
4941 active-l2: boolean (optional)
4943 Not documented
4944 refcount-table: boolean (optional)
4946 Not documented
4947 refcount-block: boolean (optional)
4949 Not documented
4950 snapshot-table: boolean (optional)
4952 Not documented
4953 inactive-l1: boolean (optional)
4955 Not documented
4956 inactive-l2: boolean (optional)
4958 Not documented
4959 Since
4961 2.9
4962 Qcow2OverlapChecks (Alternate)
4964 Specifies which metadata structures should be guarded against unin‐
4965 tended overwriting.
4966 Members
4968 flags: Qcow2OverlapCheckFlags
4969 set of flags for separate specification of each metadata struc‐
4970 ture type
4971 mode: Qcow2OverlapCheckMode
4973 named mode which chooses a specific set of flags
4974 Since
4976 2.9
4977 BlockdevQcowEncryptionFormat (Enum)
4979 Values
4980 aes AES-CBC with plain64 initialization vectors
4981 Since
4983 2.10
4984 BlockdevQcowEncryption (Object)
4986 Members
4987 format: BlockdevQcowEncryptionFormat
4988 Not documented
4989 The members of QCryptoBlockOptionsQCow when format is "aes"
4991 Since
4993 2.10
4994 BlockdevOptionsQcow (Object)
4996 Driver specific block device options for qcow.
4997 Members
4999 encrypt: BlockdevQcowEncryption (optional)
5000 Image decryption options. Mandatory for encrypted images, except
5001 when doing a metadata-only probe of the image.
5002 The members of BlockdevOptionsGenericCOWFormat
5004 Since
5006 2.10
5007 BlockdevQcow2EncryptionFormat (Enum)
5009 Values
5010 aes AES-CBC with plain64 initialization vectors
5011 luks Not documented
5013 Since
5015 2.10
5016 BlockdevQcow2Encryption (Object)
5018 Members
5019 format: BlockdevQcow2EncryptionFormat
5020 Not documented
5021 The members of QCryptoBlockOptionsQCow when format is "aes"
5023 The members of QCryptoBlockOptionsLUKS when format is "luks"
5025 Since
5027 2.10
5028 BlockdevOptionsPreallocate (Object)
5030 Filter driver intended to be inserted between format and protocol node
5031 and do preallocation in protocol node on write.
5032 Members
5034 prealloc-align: int (optional)
5035 on preallocation, align file length to this number, default
5036 1048576 (1M)
5037 prealloc-size: int (optional)
5039 how much to preallocate, default 134217728 (128M)
5040 The members of BlockdevOptionsGenericFormat
5042 Since
5044 6.0
5045 BlockdevOptionsQcow2 (Object)
5047 Driver specific block device options for qcow2.
5048 Members
5050 lazy-refcounts: boolean (optional)
5051 whether to enable the lazy refcounts feature (default is taken
5052 from the image file)
5053 pass-discard-request: boolean (optional)
5055 whether discard requests to the qcow2 device should be forwarded
5056 to the data source
5057 pass-discard-snapshot: boolean (optional)
5059 whether discard requests for the data source should be issued
5060 when a snapshot operation (e.g. deleting a snapshot) frees
5061 clusters in the qcow2 file
5062 pass-discard-other: boolean (optional)
5064 whether discard requests for the data source should be issued on
5065 other occasions where a cluster gets freed
5066 overlap-check: Qcow2OverlapChecks (optional)
5068 which overlap checks to perform for writes to the image, de‐
5069 faults to 'cached' (since 2.2)
5070 cache-size: int (optional)
5072 the maximum total size of the L2 table and refcount block caches
5073 in bytes (since 2.2)
5074 l2-cache-size: int (optional)
5076 the maximum size of the L2 table cache in bytes (since 2.2)
5077 l2-cache-entry-size: int (optional)
5079 the size of each entry in the L2 cache in bytes. It must be a
5080 power of two between 512 and the cluster size. The default value
5081 is the cluster size (since 2.12)
5082 refcount-cache-size: int (optional)
5084 the maximum size of the refcount block cache in bytes (since
5085 2.2)
5086 cache-clean-interval: int (optional)
5088 clean unused entries in the L2 and refcount caches. The interval
5089 is in seconds. The default value is 600 on supporting platforms,
5090 and 0 on other platforms. 0 disables this feature. (since 2.5)
5091 encrypt: BlockdevQcow2Encryption (optional)
5093 Image decryption options. Mandatory for encrypted images, except
5094 when doing a metadata-only probe of the image. (since 2.10)
5095 data-file: BlockdevRef (optional)
5097 reference to or definition of the external data file. This may
5098 only be specified for images that require an external data file.
5099 If it is not specified for such an image, the data file name is
5100 loaded from the image file. (since 4.0)
5101 The members of BlockdevOptionsGenericCOWFormat
5103 Since
5105 2.9
5106 SshHostKeyCheckMode (Enum)
5108 Values
5109 none Don't check the host key at all
5110 hash Compare the host key with a given hash
5112 known_hosts
5114 Check the host key against the known_hosts file
5115 Since
5117 2.12
5118 SshHostKeyCheckHashType (Enum)
5120 Values
5121 md5 The given hash is an md5 hash
5122 sha1 The given hash is an sha1 hash
5124 sha256 The given hash is an sha256 hash
5126 Since
5128 2.12
5129 SshHostKeyHash (Object)
5131 Members
5132 type: SshHostKeyCheckHashType
5133 The hash algorithm used for the hash
5134 hash: string
5136 The expected hash value
5137 Since
5139 2.12
5140 SshHostKeyCheck (Object)
5142 Members
5143 mode: SshHostKeyCheckMode
5144 Not documented
5145 The members of SshHostKeyHash when mode is "hash"
5147 Since
5149 2.12
5150 BlockdevOptionsSsh (Object)
5152 Members
5153 server: InetSocketAddress
5154 host address
5155 path: string
5157 path to the image on the host
5158 user: string (optional)
5160 user as which to connect, defaults to current local user name
5161 host-key-check: SshHostKeyCheck (optional)
5163 Defines how and what to check the host key against (default:
5164 known_hosts)
5165 Since
5167 2.9
5168 BlkdebugEvent (Enum)
5170 Trigger events supported by blkdebug.
5171 Values
5173 l1_shrink_write_table
5174 write zeros to the l1 table to shrink image. (since 2.11)
5175 l1_shrink_free_l2_clusters
5177 discard the l2 tables. (since 2.11)
5178 cor_write
5180 a write due to copy-on-read (since 2.11)
5181 cluster_alloc_space
5183 an allocation of file space for a cluster (since 4.1)
5184 none triggers once at creation of the blkdebug node (since 4.1)
5186 l1_update
5188 Not documented
5189 l1_grow_alloc_table
5191 Not documented
5192 l1_grow_write_table
5194 Not documented
5195 l1_grow_activate_table
5197 Not documented
5198 l2_load
5200 Not documented
5201 l2_update
5203 Not documented
5204 l2_update_compressed
5206 Not documented
5207 l2_alloc_cow_read
5209 Not documented
5210 l2_alloc_write
5212 Not documented
5213 read_aio
5215 Not documented
5216 read_backing_aio
5218 Not documented
5219 read_compressed
5221 Not documented
5222 write_aio
5224 Not documented
5225 write_compressed
5227 Not documented
5228 vmstate_load
5230 Not documented
5231 vmstate_save
5233 Not documented
5234 cow_read
5236 Not documented
5237 cow_write
5239 Not documented
5240 reftable_load
5242 Not documented
5243 reftable_grow
5245 Not documented
5246 reftable_update
5248 Not documented
5249 refblock_load
5251 Not documented
5252 refblock_update
5254 Not documented
5255 refblock_update_part
5257 Not documented
5258 refblock_alloc
5260 Not documented
5261 refblock_alloc_hookup
5263 Not documented
5264 refblock_alloc_write
5266 Not documented
5267 refblock_alloc_write_blocks
5269 Not documented
5270 refblock_alloc_write_table
5272 Not documented
5273 refblock_alloc_switch_table
5275 Not documented
5276 cluster_alloc
5278 Not documented
5279 cluster_alloc_bytes
5281 Not documented
5282 cluster_free
5284 Not documented
5285 flush_to_os
5287 Not documented
5288 flush_to_disk
5290 Not documented
5291 pwritev_rmw_head
5293 Not documented
5294 pwritev_rmw_after_head
5296 Not documented
5297 pwritev_rmw_tail
5299 Not documented
5300 pwritev_rmw_after_tail
5302 Not documented
5303 pwritev
5305 Not documented
5306 pwritev_zero
5308 Not documented
5309 pwritev_done
5311 Not documented
5312 empty_image_prepare
5314 Not documented
5315 Since
5317 2.9
5318 BlkdebugIOType (Enum)
5320 Kinds of I/O that blkdebug can inject errors in.
5321 Values
5323 read .bdrv_co_preadv()
5324 write .bdrv_co_pwritev()
5326 write-zeroes
5328 .bdrv_co_pwrite_zeroes()
5329 discard
5331 .bdrv_co_pdiscard()
5332 flush .bdrv_co_flush_to_disk()
5334 block-status
5336 .bdrv_co_block_status()
5337 Since
5339 4.1
5340 BlkdebugInjectErrorOptions (Object)
5342 Describes a single error injection for blkdebug.
5343 Members
5345 event: BlkdebugEvent
5346 trigger event
5347 state: int (optional)
5349 the state identifier blkdebug needs to be in to actually trigger
5350 the event; defaults to "any"
5351 iotype: BlkdebugIOType (optional)
5353 the type of I/O operations on which this error should be in‐
5354 jected; defaults to "all read, write, write-zeroes, discard, and
5355 flush operations" (since: 4.1)
5356 errno: int (optional)
5358 error identifier (errno) to be returned; defaults to EIO
5359 sector: int (optional)
5361 specifies the sector index which has to be affected in order to
5362 actually trigger the event; defaults to "any sector"
5363 once: boolean (optional)
5365 disables further events after this one has been triggered; de‐
5366 faults to false
5367 immediately: boolean (optional)
5369 fail immediately; defaults to false
5370 Since
5372 2.9
5373 BlkdebugSetStateOptions (Object)
5375 Describes a single state-change event for blkdebug.
5376 Members
5378 event: BlkdebugEvent
5379 trigger event
5380 state: int (optional)
5382 the current state identifier blkdebug needs to be in; defaults
5383 to "any"
5384 new_state: int
5386 the state identifier blkdebug is supposed to assume if this
5387 event is triggered
5388 Since
5390 2.9
5391 BlockdevOptionsBlkdebug (Object)
5393 Driver specific block device options for blkdebug.
5394 Members
5396 image: BlockdevRef
5397 underlying raw block device (or image file)
5398 config: string (optional)
5400 filename of the configuration file
5401 align: int (optional)
5403 required alignment for requests in bytes, must be positive power
5404 of 2, or 0 for default
5405 max-transfer: int (optional)
5407 maximum size for I/O transfers in bytes, must be positive multi‐
5408 ple of align and of the underlying file's request alignment (but
5409 need not be a power of 2), or 0 for default (since 2.10)
5410 opt-write-zero: int (optional)
5412 preferred alignment for write zero requests in bytes, must be
5413 positive multiple of align and of the underlying file's request
5414 alignment (but need not be a power of 2), or 0 for default
5415 (since 2.10)
5416 max-write-zero: int (optional)
5418 maximum size for write zero requests in bytes, must be positive
5419 multiple of align, of opt-write-zero, and of the underlying
5420 file's request alignment (but need not be a power of 2), or 0
5421 for default (since 2.10)
5422 opt-discard: int (optional)
5424 preferred alignment for discard requests in bytes, must be posi‐
5425 tive multiple of align and of the underlying file's request
5426 alignment (but need not be a power of 2), or 0 for default
5427 (since 2.10)
5428 max-discard: int (optional)
5430 maximum size for discard requests in bytes, must be positive
5431 multiple of align, of opt-discard, and of the underlying file's
5432 request alignment (but need not be a power of 2), or 0 for de‐
5433 fault (since 2.10)
5434 inject-error: array of BlkdebugInjectErrorOptions (optional)
5436 array of error injection descriptions
5437 set-state: array of BlkdebugSetStateOptions (optional)
5439 array of state-change descriptions
5440 take-child-perms: array of BlockPermission (optional)
5442 Permissions to take on image in addition to what is necessary
5443 anyway (which depends on how the blkdebug node is used). De‐
5444 faults to none. (since 5.0)
5445 unshare-child-perms: array of BlockPermission (optional)
5447 Permissions not to share on image in addition to what cannot be
5448 shared anyway (which depends on how the blkdebug node is used).
5449 Defaults to none. (since 5.0)
5450 Since
5452 2.9
5453 BlockdevOptionsBlklogwrites (Object)
5455 Driver specific block device options for blklogwrites.
5456 Members
5458 file: BlockdevRef
5459 block device
5460 log: BlockdevRef
5462 block device used to log writes to file
5463 log-sector-size: int (optional)
5465 sector size used in logging writes to file, determines granular‐
5466 ity of offsets and sizes of writes (default: 512)
5467 log-append: boolean (optional)
5469 append to an existing log (default: false)
5470 log-super-update-interval: int (optional)
5472 interval of write requests after which the log super block is
5473 updated to disk (default: 4096)
5474 Since
5476 3.0
5477 BlockdevOptionsBlkverify (Object)
5479 Driver specific block device options for blkverify.
5480 Members
5482 test: BlockdevRef
5483 block device to be tested
5484 raw: BlockdevRef
5486 raw image used for verification
5487 Since
5489 2.9
5490 BlockdevOptionsBlkreplay (Object)
5492 Driver specific block device options for blkreplay.
5493 Members
5495 image: BlockdevRef
5496 disk image which should be controlled with blkreplay
5497 Since
5499 4.2
5500 QuorumReadPattern (Enum)
5502 An enumeration of quorum read patterns.
5503 Values
5505 quorum read all the children and do a quorum vote on reads
5506 fifo read only from the first child that has not failed
5508 Since
5510 2.9
5511 BlockdevOptionsQuorum (Object)
5513 Driver specific block device options for Quorum
5514 Members
5516 blkverify: boolean (optional)
5517 true if the driver must print content mismatch
5519 set to false by default
5520 children: array of BlockdevRef
5522 the children block devices to use
5523 vote-threshold: int
5525 the vote limit under which a read will fail
5526 rewrite-corrupted: boolean (optional)
5528 rewrite corrupted data when quorum is reached (Since 2.1)
5529 read-pattern: QuorumReadPattern (optional)
5531 choose read pattern and set to quorum by default (Since 2.2)
5532 Since
5534 2.9
5535 BlockdevOptionsGluster (Object)
5537 Driver specific block device options for Gluster
5538 Members
5540 volume: string
5541 name of gluster volume where VM image resides
5542 path: string
5544 absolute path to image file in gluster volume
5545 server: array of SocketAddress
5547 gluster servers description
5548 debug: int (optional)
5550 libgfapi log level (default '4' which is Error) (Since 2.8)
5551 logfile: string (optional)
5553 libgfapi log file (default /dev/stderr) (Since 2.8)
5554 Since
5556 2.9
5557 IscsiTransport (Enum)
5559 An enumeration of libiscsi transport types
5560 Values
5562 tcp Not documented
5563 iser Not documented
5565 Since
5567 2.9
5568 IscsiHeaderDigest (Enum)
5570 An enumeration of header digests supported by libiscsi
5571 Values
5573 crc32c Not documented
5574 none Not documented
5576 crc32c-none
5578 Not documented
5579 none-crc32c
5581 Not documented
5582 Since
5584 2.9
5585 BlockdevOptionsIscsi (Object)
5587 Members
5588 transport: IscsiTransport
5589 The iscsi transport type
5590 portal: string
5592 The address of the iscsi portal
5593 target: string
5595 The target iqn name
5596 lun: int (optional)
5598 LUN to connect to. Defaults to 0.
5599 user: string (optional)
5601 User name to log in with. If omitted, no CHAP authentication is
5602 performed.
5603 password-secret: string (optional)
5605 The ID of a QCryptoSecret object providing the password for the
5606 login. This option is required if user is specified.
5607 initiator-name: string (optional)
5609 The iqn name we want to identify to the target as. If this op‐
5610 tion is not specified, an initiator name is generated automati‐
5611 cally.
5612 header-digest: IscsiHeaderDigest (optional)
5614 The desired header digest. Defaults to none-crc32c.
5615 timeout: int (optional)
5617 Timeout in seconds after which a request will timeout. 0 means
5618 no timeout and is the default.
5619 Driver specific block device options for iscsi
5620 Since
5622 2.9
5623 RbdAuthMode (Enum)
5625 Values
5626 cephx Not documented
5627 none Not documented
5629 Since
5631 3.0
5632 RbdImageEncryptionFormat (Enum)
5634 Values
5635 luks Not documented
5636 luks2 Not documented
5638 Since
5640 6.1
5641 RbdEncryptionOptionsLUKSBase (Object)
5643 Members
5644 key-secret: string
5645 ID of a QCryptoSecret object providing a passphrase for unlock‐
5646 ing the encryption
5647 Since
5649 6.1
5650 RbdEncryptionCreateOptionsLUKSBase (Object)
5652 Members
5653 cipher-alg: QCryptoCipherAlgorithm (optional)
5654 The encryption algorithm
5655 The members of RbdEncryptionOptionsLUKSBase
5657 Since
5659 6.1
5660 RbdEncryptionOptionsLUKS (Object)
5662 Members
5663 The members of RbdEncryptionOptionsLUKSBase
5664 Since
5666 6.1
5667 RbdEncryptionOptionsLUKS2 (Object)
5669 Members
5670 The members of RbdEncryptionOptionsLUKSBase
5671 Since
5673 6.1
5674 RbdEncryptionCreateOptionsLUKS (Object)
5676 Members
5677 The members of RbdEncryptionCreateOptionsLUKSBase
5678 Since
5680 6.1
5681 RbdEncryptionCreateOptionsLUKS2 (Object)
5683 Members
5684 The members of RbdEncryptionCreateOptionsLUKSBase
5685 Since
5687 6.1
5688 RbdEncryptionOptions (Object)
5690 Members
5691 format: RbdImageEncryptionFormat
5692 Not documented
5693 The members of RbdEncryptionOptionsLUKS when format is "luks"
5695 The members of RbdEncryptionOptionsLUKS2 when format is "luks2"
5697 Since
5699 6.1
5700 RbdEncryptionCreateOptions (Object)
5702 Members
5703 format: RbdImageEncryptionFormat
5704 Not documented
5705 The members of RbdEncryptionCreateOptionsLUKS when format is "luks"
5707 The members of RbdEncryptionCreateOptionsLUKS2 when format is "luks2"
5709 Since
5711 6.1
5712 BlockdevOptionsRbd (Object)
5714 Members
5715 pool: string
5716 Ceph pool name.
5717 namespace: string (optional)
5719 Rados namespace name in the Ceph pool. (Since 5.0)
5720 image: string
5722 Image name in the Ceph pool.
5723 conf: string (optional)
5725 path to Ceph configuration file. Values in the configuration
5726 file will be overridden by options specified via QAPI.
5727 snapshot: string (optional)
5729 Ceph snapshot name.
5730 encrypt: RbdEncryptionOptions (optional)
5732 Image encryption options. (Since 6.1)
5733 user: string (optional)
5735 Ceph id name.
5736 auth-client-required: array of RbdAuthMode (optional)
5738 Acceptable authentication modes. This maps to Ceph configura‐
5739 tion option "auth_client_required". (Since 3.0)
5740 key-secret: string (optional)
5742 ID of a QCryptoSecret object providing a key for cephx authenti‐
5743 cation. This maps to Ceph configuration option "key". (Since
5744 3.0)
5745 server: array of InetSocketAddressBase (optional)
5747 Monitor host address and port. This maps to the "mon_host" Ceph
5748 option.
5749 Since
5751 2.9
5752 ReplicationMode (Enum)
5754 An enumeration of replication modes.
5755 Values
5757 primary
5758 Primary mode, the vm's state will be sent to secondary QEMU.
5759 secondary
5761 Secondary mode, receive the vm's state from primary QEMU.
5762 Since
5764 2.9
5765 If
5767 defined(CONFIG_REPLICATION)
5768 BlockdevOptionsReplication (Object)
5770 Driver specific block device options for replication
5771 Members
5773 mode: ReplicationMode
5774 the replication mode
5775 top-id: string (optional)
5777 In secondary mode, node name or device ID of the root node who
5778 owns the replication node chain. Must not be given in primary
5779 mode.
5780 The members of BlockdevOptionsGenericFormat
5782 Since
5784 2.9
5785 If
5787 defined(CONFIG_REPLICATION)
5788 NFSTransport (Enum)
5790 An enumeration of NFS transport types
5791 Values
5793 inet TCP transport
5794 Since
5796 2.9
5797 NFSServer (Object)
5799 Captures the address of the socket
5800 Members
5802 type: NFSTransport
5803 transport type used for NFS (only TCP supported)
5804 host: string
5806 host address for NFS server
5807 Since
5809 2.9
5810 BlockdevOptionsNfs (Object)
5812 Driver specific block device option for NFS
5813 Members
5815 server: NFSServer
5816 host address
5817 path: string
5819 path of the image on the host
5820 user: int (optional)
5822 UID value to use when talking to the server (defaults to 65534
5823 on Windows and getuid() on unix)
5824 group: int (optional)
5826 GID value to use when talking to the server (defaults to 65534
5827 on Windows and getgid() in unix)
5828 tcp-syn-count: int (optional)
5830 number of SYNs during the session establishment (defaults to
5831 libnfs default)
5832 readahead-size: int (optional)
5834 set the readahead size in bytes (defaults to libnfs default)
5835 page-cache-size: int (optional)
5837 set the pagecache size in bytes (defaults to libnfs default)
5838 debug: int (optional)
5840 set the NFS debug level (max 2) (defaults to libnfs default)
5841 Since
5843 2.9
5844 BlockdevOptionsCurlBase (Object)
5846 Driver specific block device options shared by all protocols supported
5847 by the curl backend.
5848 Members
5850 url: string
5851 URL of the image file
5852 readahead: int (optional)
5854 Size of the read-ahead cache; must be a multiple of 512 (de‐
5855 faults to 256 kB)
5856 timeout: int (optional)
5858 Timeout for connections, in seconds (defaults to 5)
5859 username: string (optional)
5861 Username for authentication (defaults to none)
5862 password-secret: string (optional)
5864 ID of a QCryptoSecret object providing a password for authenti‐
5865 cation (defaults to no password)
5866 proxy-username: string (optional)
5868 Username for proxy authentication (defaults to none)
5869 proxy-password-secret: string (optional)
5871 ID of a QCryptoSecret object providing a password for proxy au‐
5872 thentication (defaults to no password)
5873 Since
5875 2.9
5876 BlockdevOptionsCurlHttp (Object)
5878 Driver specific block device options for HTTP connections over the curl
5879 backend. URLs must start with "http://".
5880 Members
5882 cookie: string (optional)
5883 List of cookies to set; format is "name1=content1; name2=con‐
5884 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
5885 ies.
5886 cookie-secret: string (optional)
5888 ID of a QCryptoSecret object providing the cookie data in a se‐
5889 cure way. See cookie for the format. (since 2.10)
5890 The members of BlockdevOptionsCurlBase
5892 Since
5894 2.9
5895 BlockdevOptionsCurlHttps (Object)
5897 Driver specific block device options for HTTPS connections over the
5898 curl backend. URLs must start with "https://".
5899 Members
5901 cookie: string (optional)
5902 List of cookies to set; format is "name1=content1; name2=con‐
5903 tent2;" as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
5904 ies.
5905 sslverify: boolean (optional)
5907 Whether to verify the SSL certificate's validity (defaults to
5908 true)
5909 cookie-secret: string (optional)
5911 ID of a QCryptoSecret object providing the cookie data in a se‐
5912 cure way. See cookie for the format. (since 2.10)
5913 The members of BlockdevOptionsCurlBase
5915 Since
5917 2.9
5918 BlockdevOptionsCurlFtp (Object)
5920 Driver specific block device options for FTP connections over the curl
5921 backend. URLs must start with "ftp://".
5922 Members
5924 The members of BlockdevOptionsCurlBase
5925 Since
5927 2.9
5928 BlockdevOptionsCurlFtps (Object)
5930 Driver specific block device options for FTPS connections over the curl
5931 backend. URLs must start with "ftps://".
5932 Members
5934 sslverify: boolean (optional)
5935 Whether to verify the SSL certificate's validity (defaults to
5936 true)
5937 The members of BlockdevOptionsCurlBase
5939 Since
5941 2.9
5942 BlockdevOptionsNbd (Object)
5944 Driver specific block device options for NBD.
5945 Members
5947 server: SocketAddress
5948 NBD server address
5949 export: string (optional)
5951 export name
5952 tls-creds: string (optional)
5954 TLS credentials ID
5955 x-dirty-bitmap: string (optional)
5957 A metadata context name such as "qemu:dirty-bitmap:NAME" or
5958 "qemu:allocation-depth" to query in place of the traditional
5959 "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
5960 the NBD protocol; and yes, naming this option x-context would
5961 have made more sense) (since 3.0)
5962 reconnect-delay: int (optional)
5964 On an unexpected disconnect, the nbd client tries to connect
5965 again until succeeding or encountering a serious error. During
5966 the first reconnect-delay seconds, all requests are paused and
5967 will be rerun on a successful reconnect. After that time, any
5968 delayed requests and all future requests before a successful re‐
5969 connect will immediately fail. Default 0 (Since 4.2)
5970 Since
5972 2.9
5973 BlockdevOptionsRaw (Object)
5975 Driver specific block device options for the raw driver.
5976 Members
5978 offset: int (optional)
5979 position where the block device starts
5980 size: int (optional)
5982 the assumed size of the device
5983 The members of BlockdevOptionsGenericFormat
5985 Since
5987 2.9
5988 BlockdevOptionsThrottle (Object)
5990 Driver specific block device options for the throttle driver
5991 Members
5993 throttle-group: string
5994 the name of the throttle-group object to use. It must already
5995 exist.
5996 file: BlockdevRef
5998 reference to or definition of the data source block device
5999 Since
6001 2.11
6002 BlockdevOptionsCor (Object)
6004 Driver specific block device options for the copy-on-read driver.
6005 Members
6007 bottom: string (optional)
6008 The name of a non-filter node (allocation-bearing layer) that
6009 limits the COR operations in the backing chain (inclusive), so
6010 that no data below this node will be copied by this filter. If
6011 option is absent, the limit is not applied, so that data from
6012 all backing layers may be copied.
6013 The members of BlockdevOptionsGenericFormat
6015 Since
6017 6.0
6018 BlockdevOptions (Object)
6020 Options for creating a block device. Many options are available for
6021 all block devices, independent of the block driver:
6022 Members
6024 driver: BlockdevDriver
6025 block driver name
6026 node-name: string (optional)
6028 the node name of the new node (Since 2.0). This option is re‐
6029 quired on the top level of blockdev-add. Valid node names start
6030 with an alphabetic character and may contain only alphanumeric
6031 characters, '-', '.' and '_'. Their maximum length is 31 charac‐
6032 ters.
6033 discard: BlockdevDiscardOptions (optional)
6035 discard-related options (default: ignore)
6036 cache: BlockdevCacheOptions (optional)
6038 cache-related options
6039 read-only: boolean (optional)
6041 whether the block device should be read-only (default: false).
6042 Note that some block drivers support only read-only access, ei‐
6043 ther generally or in certain configurations. In this case, the
6044 default value does not work and the option must be specified ex‐
6045 plicitly.
6046 auto-read-only: boolean (optional)
6048 if true and read-only is false, QEMU may automatically decide
6049 not to open the image read-write as requested, but fall back to
6050 read-only instead (and switch between the modes later), e.g. de‐
6051 pending on whether the image file is writable or whether a writ‐
6052 ing user is attached to the node (default: false, since 3.1)
6053 detect-zeroes: BlockdevDetectZeroesOptions (optional)
6055 detect and optimize zero writes (Since 2.1) (default: off)
6056 force-share: boolean (optional)
6058 force share all permission on added nodes. Requires
6059 read-only=true. (Since 2.10)
6060 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
6062 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
6064 writes"
6065 The members of BlockdevOptionsBlkverify when driver is "blkverify"
6067 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
6069 The members of BlockdevOptionsGenericFormat when driver is "bochs"
6071 The members of BlockdevOptionsGenericFormat when driver is "cloop"
6073 The members of BlockdevOptionsGenericFormat when driver is "compress"
6075 The members of BlockdevOptionsCor when driver is "copy-on-read"
6077 The members of BlockdevOptionsGenericFormat when driver is "dmg"
6079 The members of BlockdevOptionsFile when driver is "file"
6081 The members of BlockdevOptionsCurlFtp when driver is "ftp"
6083 The members of BlockdevOptionsCurlFtps when driver is "ftps"
6085 The members of BlockdevOptionsGluster when driver is "gluster"
6087 The members of BlockdevOptionsFile when driver is "host_cdrom" (If: de‐
6089 fined(HAVE_HOST_BLOCK_DEVICE))
6090 The members of BlockdevOptionsFile when driver is "host_device" (If:
6092 defined(HAVE_HOST_BLOCK_DEVICE))
6093 The members of BlockdevOptionsCurlHttp when driver is "http"
6095 The members of BlockdevOptionsCurlHttps when driver is "https"
6097 The members of BlockdevOptionsIscsi when driver is "iscsi"
6099 The members of BlockdevOptionsLUKS when driver is "luks"
6101 The members of BlockdevOptionsNbd when driver is "nbd"
6103 The members of BlockdevOptionsNfs when driver is "nfs"
6105 The members of BlockdevOptionsNull when driver is "null-aio"
6107 The members of BlockdevOptionsNull when driver is "null-co"
6109 The members of BlockdevOptionsNVMe when driver is "nvme"
6111 The members of BlockdevOptionsGenericFormat when driver is "parallels"
6113 The members of BlockdevOptionsPreallocate when driver is "preallocate"
6115 The members of BlockdevOptionsQcow2 when driver is "qcow2"
6117 The members of BlockdevOptionsQcow when driver is "qcow"
6119 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
6121 The members of BlockdevOptionsQuorum when driver is "quorum"
6123 The members of BlockdevOptionsRaw when driver is "raw"
6125 The members of BlockdevOptionsRbd when driver is "rbd"
6127 The members of BlockdevOptionsReplication when driver is "replication"
6129 (If: defined(CONFIG_REPLICATION))
6130 The members of BlockdevOptionsSsh when driver is "ssh"
6132 The members of BlockdevOptionsThrottle when driver is "throttle"
6134 The members of BlockdevOptionsGenericFormat when driver is "vdi"
6136 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
6138 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
6140 The members of BlockdevOptionsGenericFormat when driver is "vpc"
6142 The members of BlockdevOptionsVVFAT when driver is "vvfat"
6144 Remaining options are determined by the block driver.
6145 Since
6147 2.9
6148 BlockdevRef (Alternate)
6150 Reference to a block device.
6151 Members
6153 definition: BlockdevOptions
6154 defines a new block device inline
6155 reference: string
6157 references the ID of an existing block device
6158 Since
6160 2.9
6161 BlockdevRefOrNull (Alternate)
6163 Reference to a block device.
6164 Members
6166 definition: BlockdevOptions
6167 defines a new block device inline
6168 reference: string
6170 references the ID of an existing block device. An empty string
6171 means that no block device should be referenced. Deprecated;
6172 use null instead.
6173 null: null
6175 No block device should be referenced (since 2.10)
6176 Since
6178 2.9
6179 blockdev-add (Command)
6181 Creates a new block device.
6182 Arguments
6184 The members of BlockdevOptions
6185 Since
6187 2.9
6188 Example
6190 1.
6191 -> { "execute": "blockdev-add",
6192 "arguments": {
6193 "driver": "qcow2",
6194 "node-name": "test1",
6195 "file": {
6196 "driver": "file",
6197 "filename": "test.qcow2"
6198 }
6199 }
6200 }
6201 <- { "return": {} }
6202 2.
6204 -> { "execute": "blockdev-add",
6205 "arguments": {
6206 "driver": "qcow2",
6207 "node-name": "node0",
6208 "discard": "unmap",
6209 "cache": {
6210 "direct": true
6211 },
6212 "file": {
6213 "driver": "file",
6214 "filename": "/tmp/test.qcow2"
6215 },
6216 "backing": {
6217 "driver": "raw",
6218 "file": {
6219 "driver": "file",
6220 "filename": "/dev/fdset/4"
6221 }
6222 }
6223 }
6224 }
6225 <- { "return": {} }
6227 blockdev-reopen (Command)
6229 Reopens one or more block devices using the given set of options. Any
6230 option not specified will be reset to its default value regardless of
6231 its previous status. If an option cannot be changed or a particular
6232 driver does not support reopening then the command will return an er‐
6233 ror. All devices in the list are reopened in one transaction, so if one
6234 of them fails then the whole transaction is cancelled.
6235 The command receives a list of block devices to reopen. For each one of
6237 them, the top-level node-name option (from BlockdevOptions) must be
6238 specified and is used to select the block device to be reopened. Other
6239 node-name options must be either omitted or set to the current name of
6240 the appropriate node. This command won't change any node name and any
6241 attempt to do it will result in an error.
6242 In the case of options that refer to child nodes, the behavior of this
6244 command depends on the value:
6245 1. A set of options (BlockdevOptions): the child is reopened with
6247 the specified set of options.
6248 2. A reference to the current child: the child is reopened using its
6250 existing set of options.
6251 3. A reference to a different node: the current child is replaced
6253 with the specified one.
6254 4. NULL: the current child (if any) is detached.
6256 Options (1) and (2) are supported in all cases. Option (3) is supported
6258 for file and backing, and option (4) for backing only.
6259 Unlike with blockdev-add, the backing option must always be present un‐
6261 less the node being reopened does not have a backing file and its image
6262 does not have a default backing file name as part of its metadata.
6263 Arguments
6265 options: array of BlockdevOptions
6266 Not documented
6267 Since
6269 6.1
6270 blockdev-del (Command)
6272 Deletes a block device that has been added using blockdev-add. The
6273 command will fail if the node is attached to a device or is otherwise
6274 being used.
6275 Arguments
6277 node-name: string
6278 Name of the graph node to delete.
6279 Since
6281 2.9
6282 Example
6284 -> { "execute": "blockdev-add",
6285 "arguments": {
6286 "driver": "qcow2",
6287 "node-name": "node0",
6288 "file": {
6289 "driver": "file",
6290 "filename": "test.qcow2"
6291 }
6292 }
6293 }
6294 <- { "return": {} }
6295 -> { "execute": "blockdev-del",
6297 "arguments": { "node-name": "node0" }
6298 }
6299 <- { "return": {} }
6300 BlockdevCreateOptionsFile (Object)
6302 Driver specific image creation options for file.
6303 Members
6305 filename: string
6306 Filename for the new image file
6307 size: int
6309 Size of the virtual disk in bytes
6310 preallocation: PreallocMode (optional)
6312 Preallocation mode for the new image (default: off; allowed val‐
6313 ues: off, falloc (if defined CONFIG_POSIX_FALLOCATE), full (if
6314 defined CONFIG_POSIX))
6315 nocow: boolean (optional)
6317 Turn off copy-on-write (valid only on btrfs; default: off)
6318 extent-size-hint: int (optional)
6320 Extent size hint to add to the image file; 0 for not adding an
6321 extent size hint (default: 1 MB, since 5.1)
6322 Since
6324 2.12
6325 BlockdevCreateOptionsGluster (Object)
6327 Driver specific image creation options for gluster.
6328 Members
6330 location: BlockdevOptionsGluster
6331 Where to store the new image file
6332 size: int
6334 Size of the virtual disk in bytes
6335 preallocation: PreallocMode (optional)
6337 Preallocation mode for the new image (default: off; allowed val‐
6338 ues: off, falloc (if defined CONFIG_GLUSTERFS_FALLOCATE), full
6339 (if defined CONFIG_GLUSTERFS_ZEROFILL))
6340 Since
6342 2.12
6343 BlockdevCreateOptionsLUKS (Object)
6345 Driver specific image creation options for LUKS.
6346 Members
6348 file: BlockdevRef
6349 Node to create the image format on
6350 size: int
6352 Size of the virtual disk in bytes
6353 preallocation: PreallocMode (optional)
6355 Preallocation mode for the new image (since: 4.2) (default: off;
6356 allowed values: off, metadata, falloc, full)
6357 The members of QCryptoBlockCreateOptionsLUKS
6359 Since
6361 2.12
6362 BlockdevCreateOptionsNfs (Object)
6364 Driver specific image creation options for NFS.
6365 Members
6367 location: BlockdevOptionsNfs
6368 Where to store the new image file
6369 size: int
6371 Size of the virtual disk in bytes
6372 Since
6374 2.12
6375 BlockdevCreateOptionsParallels (Object)
6377 Driver specific image creation options for parallels.
6378 Members
6380 file: BlockdevRef
6381 Node to create the image format on
6382 size: int
6384 Size of the virtual disk in bytes
6385 cluster-size: int (optional)
6387 Cluster size in bytes (default: 1 MB)
6388 Since
6390 2.12
6391 BlockdevCreateOptionsQcow (Object)
6393 Driver specific image creation options for qcow.
6394 Members
6396 file: BlockdevRef
6397 Node to create the image format on
6398 size: int
6400 Size of the virtual disk in bytes
6401 backing-file: string (optional)
6403 File name of the backing file if a backing file should be used
6404 encrypt: QCryptoBlockCreateOptions (optional)
6406 Encryption options if the image should be encrypted
6407 Since
6409 2.12
6410 BlockdevQcow2Version (Enum)
6412 Values
6413 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
6414 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
6416 Since
6418 2.12
6419 Qcow2CompressionType (Enum)
6421 Compression type used in qcow2 image file
6422 Values
6424 zlib zlib compression, see <http://zlib.net/>
6425 zstd (If: defined(CONFIG_ZSTD))
6427 zstd compression, see <http://github.com/facebook/zstd>
6428 Since
6430 5.1
6431 BlockdevCreateOptionsQcow2 (Object)
6433 Driver specific image creation options for qcow2.
6434 Members
6436 file: BlockdevRef
6437 Node to create the image format on
6438 data-file: BlockdevRef (optional)
6440 Node to use as an external data file in which all guest data is
6441 stored so that only metadata remains in the qcow2 file (since:
6442 4.0)
6443 data-file-raw: boolean (optional)
6445 True if the external data file must stay valid as a standalone
6446 (read-only) raw image without looking at qcow2 metadata (de‐
6447 fault: false; since: 4.0)
6448 extended-l2: boolean (optional)
6450 True to make the image have extended L2 entries (default: false;
6451 since 5.2)
6452 size: int
6454 Size of the virtual disk in bytes
6455 version: BlockdevQcow2Version (optional)
6457 Compatibility level (default: v3)
6458 backing-file: string (optional)
6460 File name of the backing file if a backing file should be used
6461 backing-fmt: BlockdevDriver (optional)
6463 Name of the block driver to use for the backing file
6464 encrypt: QCryptoBlockCreateOptions (optional)
6466 Encryption options if the image should be encrypted
6467 cluster-size: int (optional)
6469 qcow2 cluster size in bytes (default: 65536)
6470 preallocation: PreallocMode (optional)
6472 Preallocation mode for the new image (default: off; allowed val‐
6473 ues: off, falloc, full, metadata)
6474 lazy-refcounts: boolean (optional)
6476 True if refcounts may be updated lazily (default: off)
6477 refcount-bits: int (optional)
6479 Width of reference counts in bits (default: 16)
6480 compression-type: Qcow2CompressionType (optional)
6482 The image cluster compression method (default: zlib, since 5.1)
6483 Since
6485 2.12
6486 BlockdevCreateOptionsQed (Object)
6488 Driver specific image creation options for qed.
6489 Members
6491 file: BlockdevRef
6492 Node to create the image format on
6493 size: int
6495 Size of the virtual disk in bytes
6496 backing-file: string (optional)
6498 File name of the backing file if a backing file should be used
6499 backing-fmt: BlockdevDriver (optional)
6501 Name of the block driver to use for the backing file
6502 cluster-size: int (optional)
6504 Cluster size in bytes (default: 65536)
6505 table-size: int (optional)
6507 L1/L2 table size (in clusters)
6508 Since
6510 2.12
6511 BlockdevCreateOptionsRbd (Object)
6513 Driver specific image creation options for rbd/Ceph.
6514 Members
6516 location: BlockdevOptionsRbd
6517 Where to store the new image file. This location cannot point to
6518 a snapshot.
6519 size: int
6521 Size of the virtual disk in bytes
6522 cluster-size: int (optional)
6524 RBD object size
6525 encrypt: RbdEncryptionCreateOptions (optional)
6527 Image encryption options. (Since 6.1)
6528 Since
6530 2.12
6531 BlockdevVmdkSubformat (Enum)
6533 Subformat options for VMDK images
6534 Values
6536 monolithicSparse
6537 Single file image with sparse cluster allocation
6538 monolithicFlat
6540 Single flat data image and a descriptor file
6541 twoGbMaxExtentSparse
6543 Data is split into 2GB (per virtual LBA) sparse extent files, in
6544 addition to a descriptor file
6545 twoGbMaxExtentFlat
6547 Data is split into 2GB (per virtual LBA) flat extent files, in
6548 addition to a descriptor file
6549 streamOptimized
6551 Single file image sparse cluster allocation, optimized for
6552 streaming over network.
6553 Since
6555 4.0
6556 BlockdevVmdkAdapterType (Enum)
6558 Adapter type info for VMDK images
6559 Values
6561 ide Not documented
6562 buslogic
6564 Not documented
6565 lsilogic
6567 Not documented
6568 legacyESX
6570 Not documented
6571 Since
6573 4.0
6574 BlockdevCreateOptionsVmdk (Object)
6576 Driver specific image creation options for VMDK.
6577 Members
6579 file: BlockdevRef
6580 Where to store the new image file. This refers to the image file
6581 for monolithcSparse and streamOptimized format, or the descrip‐
6582 tor file for other formats.
6583 size: int
6585 Size of the virtual disk in bytes
6586 extents: array of BlockdevRef (optional)
6588 Where to store the data extents. Required for monolithcFlat,
6589 twoGbMaxExtentSparse and twoGbMaxExtentFlat formats. For mono‐
6590 lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
6591 mats, the number of entries required is calculated as ex‐
6592 tent_number = virtual_size / 2GB. Providing more extents than
6593 will be used is an error.
6594 subformat: BlockdevVmdkSubformat (optional)
6596 The subformat of the VMDK image. Default: "monolithicSparse".
6597 backing-file: string (optional)
6599 The path of backing file. Default: no backing file is used.
6600 adapter-type: BlockdevVmdkAdapterType (optional)
6602 The adapter type used to fill in the descriptor. Default: ide.
6603 hwversion: string (optional)
6605 Hardware version. The meaningful options are "4" or "6". De‐
6606 fault: "4".
6607 zeroed-grain: boolean (optional)
6609 Whether to enable zeroed-grain feature for sparse subformats.
6610 Default: false.
6611 Since
6613 4.0
6614 BlockdevCreateOptionsSsh (Object)
6616 Driver specific image creation options for SSH.
6617 Members
6619 location: BlockdevOptionsSsh
6620 Where to store the new image file
6621 size: int
6623 Size of the virtual disk in bytes
6624 Since
6626 2.12
6627 BlockdevCreateOptionsVdi (Object)
6629 Driver specific image creation options for VDI.
6630 Members
6632 file: BlockdevRef
6633 Node to create the image format on
6634 size: int
6636 Size of the virtual disk in bytes
6637 preallocation: PreallocMode (optional)
6639 Preallocation mode for the new image (default: off; allowed val‐
6640 ues: off, metadata)
6641 Since
6643 2.12
6644 BlockdevVhdxSubformat (Enum)
6646 Values
6647 dynamic
6648 Growing image file
6649 fixed Preallocated fixed-size image file
6651 Since
6653 2.12
6654 BlockdevCreateOptionsVhdx (Object)
6656 Driver specific image creation options for vhdx.
6657 Members
6659 file: BlockdevRef
6660 Node to create the image format on
6661 size: int
6663 Size of the virtual disk in bytes
6664 log-size: int (optional)
6666 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
6667 block-size: int (optional)
6669 Block size in bytes, must be a multiple of 1 MB and not larger
6670 than 256 MB (default: automatically choose a block size depend‐
6671 ing on the image size)
6672 subformat: BlockdevVhdxSubformat (optional)
6674 vhdx subformat (default: dynamic)
6675 block-state-zero: boolean (optional)
6677 Force use of payload blocks of type 'ZERO'. Non-standard, but
6678 default. Do not set to 'off' when using 'qemu-img convert' with
6679 subformat=dynamic.
6680 Since
6682 2.12
6683 BlockdevVpcSubformat (Enum)
6685 Values
6686 dynamic
6687 Growing image file
6688 fixed Preallocated fixed-size image file
6690 Since
6692 2.12
6693 BlockdevCreateOptionsVpc (Object)
6695 Driver specific image creation options for vpc (VHD).
6696 Members
6698 file: BlockdevRef
6699 Node to create the image format on
6700 size: int
6702 Size of the virtual disk in bytes
6703 subformat: BlockdevVpcSubformat (optional)
6705 vhdx subformat (default: dynamic)
6706 force-size: boolean (optional)
6708 Force use of the exact byte size instead of rounding to the next
6709 size that can be represented in CHS geometry (default: false)
6710 Since
6712 2.12
6713 BlockdevCreateOptions (Object)
6715 Options for creating an image format on a given node.
6716 Members
6718 driver: BlockdevDriver
6719 block driver to create the image format
6720 The members of BlockdevCreateOptionsFile when driver is "file"
6722 The members of BlockdevCreateOptionsGluster when driver is "gluster"
6724 The members of BlockdevCreateOptionsLUKS when driver is "luks"
6726 The members of BlockdevCreateOptionsNfs when driver is "nfs"
6728 The members of BlockdevCreateOptionsParallels when driver is "paral‐
6730 lels"
6731 The members of BlockdevCreateOptionsQcow when driver is "qcow"
6733 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
6735 The members of BlockdevCreateOptionsQed when driver is "qed"
6737 The members of BlockdevCreateOptionsRbd when driver is "rbd"
6739 The members of BlockdevCreateOptionsSsh when driver is "ssh"
6741 The members of BlockdevCreateOptionsVdi when driver is "vdi"
6743 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
6745 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
6747 The members of BlockdevCreateOptionsVpc when driver is "vpc"
6749 Since
6751 2.12
6752 blockdev-create (Command)
6754 Starts a job to create an image format on a given node. The job is au‐
6755 tomatically finalized, but a manual job-dismiss is required.
6756 Arguments
6758 job-id: string
6759 Identifier for the newly created job.
6760 options: BlockdevCreateOptions
6762 Options for the image creation.
6763 Since
6765 3.0
6766 BlockdevAmendOptionsLUKS (Object)
6768 Driver specific image amend options for LUKS.
6769 Members
6771 The members of QCryptoBlockAmendOptionsLUKS
6772 Since
6774 5.1
6775 BlockdevAmendOptionsQcow2 (Object)
6777 Driver specific image amend options for qcow2. For now, only encryp‐
6778 tion options can be amended
6779 encrypt Encryption options to be amended
6781 Members
6783 encrypt: QCryptoBlockAmendOptions (optional)
6784 Not documented
6785 Since
6787 5.1
6788 BlockdevAmendOptions (Object)
6790 Options for amending an image format
6791 Members
6793 driver: BlockdevDriver
6794 Block driver of the node to amend.
6795 The members of BlockdevAmendOptionsLUKS when driver is "luks"
6797 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
6799 Since
6801 5.1
6802 x-blockdev-amend (Command)
6804 Starts a job to amend format specific options of an existing open block
6805 device The job is automatically finalized, but a manual job-dismiss is
6806 required.
6807 Arguments
6809 job-id: string
6810 Identifier for the newly created job.
6811 node-name: string
6813 Name of the block node to work on
6814 options: BlockdevAmendOptions
6816 Options (driver specific)
6817 force: boolean (optional)
6819 Allow unsafe operations, format specific For luks that allows
6820 erase of the last active keyslot (permanent loss of data), and
6821 replacement of an active keyslot (possible loss of data if IO
6822 error happens)
6823 Since
6825 5.1
6826 BlockErrorAction (Enum)
6828 An enumeration of action that has been taken when a DISK I/O occurs
6829 Values
6831 ignore error has been ignored
6832 report error has been reported to the device
6834 stop error caused VM to be stopped
6836 Since
6838 2.1
6839 BLOCK_IMAGE_CORRUPTED (Event)
6841 Emitted when a disk image is being marked corrupt. The image can be
6842 identified by its device or node name. The 'device' field is always
6843 present for compatibility reasons, but it can be empty ("") if the im‐
6844 age does not have a device name associated.
6845 Arguments
6847 device: string
6848 device name. This is always present for compatibility reasons,
6849 but it can be empty ("") if the image does not have a device
6850 name associated.
6851 node-name: string (optional)
6853 node name (Since: 2.4)
6854 msg: string
6856 informative message for human consumption, such as the kind of
6857 corruption being detected. It should not be parsed by machine as
6858 it is not guaranteed to be stable
6859 offset: int (optional)
6861 if the corruption resulted from an image access, this is the
6862 host's access offset into the image
6863 size: int (optional)
6865 if the corruption resulted from an image access, this is the ac‐
6866 cess size
6867 fatal: boolean
6869 if set, the image is marked corrupt and therefore unusable after
6870 this event and must be repaired (Since 2.2; before, every
6871 BLOCK_IMAGE_CORRUPTED event was fatal)
6872 Note
6874 If action is "stop", a STOP event will eventually follow the
6875 BLOCK_IO_ERROR event.
6876 Example
6878 <- { "event": "BLOCK_IMAGE_CORRUPTED",
6879 "data": { "device": "ide0-hd0", "node-name": "node0",
6880 "msg": "Prevented active L1 table overwrite", "offset": 196608,
6881 "size": 65536 },
6882 "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
6883 Since
6885 1.7
6886 BLOCK_IO_ERROR (Event)
6888 Emitted when a disk I/O error occurs
6889 Arguments
6891 device: string
6892 device name. This is always present for compatibility reasons,
6893 but it can be empty ("") if the image does not have a device
6894 name associated.
6895 node-name: string (optional)
6897 node name. Note that errors may be reported for the root node
6898 that is directly attached to a guest device rather than for the
6899 node where the error occurred. The node name is not present if
6900 the drive is empty. (Since: 2.8)
6901 operation: IoOperationType
6903 I/O operation
6904 action: BlockErrorAction
6906 action that has been taken
6907 nospace: boolean (optional)
6909 true if I/O error was caused due to a no-space condition. This
6910 key is only present if query-block's io-status is present,
6911 please see query-block documentation for more information
6912 (since: 2.2)
6913 reason: string
6915 human readable string describing the error cause. (This field
6916 is a debugging aid for humans, it should not be parsed by appli‐
6917 cations) (since: 2.2)
6918 Note
6920 If action is "stop", a STOP event will eventually follow the
6921 BLOCK_IO_ERROR event
6922 Since
6924 0.13
6925 Example
6927 <- { "event": "BLOCK_IO_ERROR",
6928 "data": { "device": "ide0-hd1",
6929 "node-name": "#block212",
6930 "operation": "write",
6931 "action": "stop" },
6932 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6933 BLOCK_JOB_COMPLETED (Event)
6935 Emitted when a block job has completed
6936 Arguments
6938 type: JobType
6939 job type
6940 device: string
6942 The job identifier. Originally the device name but other values
6943 are allowed since QEMU 2.7
6944 len: int
6946 maximum progress value
6947 offset: int
6949 current progress value. On success this is equal to len. On
6950 failure this is less than len
6951 speed: int
6953 rate limit, bytes per second
6954 error: string (optional)
6956 error message. Only present on failure. This field contains a
6957 human-readable error message. There are no semantics other than
6958 that streaming has failed and clients should not try to inter‐
6959 pret the error string
6960 Since
6962 1.1
6963 Example
6965 <- { "event": "BLOCK_JOB_COMPLETED",
6966 "data": { "type": "stream", "device": "virtio-disk0",
6967 "len": 10737418240, "offset": 10737418240,
6968 "speed": 0 },
6969 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6970 BLOCK_JOB_CANCELLED (Event)
6972 Emitted when a block job has been cancelled
6973 Arguments
6975 type: JobType
6976 job type
6977 device: string
6979 The job identifier. Originally the device name but other values
6980 are allowed since QEMU 2.7
6981 len: int
6983 maximum progress value
6984 offset: int
6986 current progress value. On success this is equal to len. On
6987 failure this is less than len
6988 speed: int
6990 rate limit, bytes per second
6991 Since
6993 1.1
6994 Example
6996 <- { "event": "BLOCK_JOB_CANCELLED",
6997 "data": { "type": "stream", "device": "virtio-disk0",
6998 "len": 10737418240, "offset": 134217728,
6999 "speed": 0 },
7000 "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
7001 BLOCK_JOB_ERROR (Event)
7003 Emitted when a block job encounters an error
7004 Arguments
7006 device: string
7007 The job identifier. Originally the device name but other values
7008 are allowed since QEMU 2.7
7009 operation: IoOperationType
7011 I/O operation
7012 action: BlockErrorAction
7014 action that has been taken
7015 Since
7017 1.3
7018 Example
7020 <- { "event": "BLOCK_JOB_ERROR",
7021 "data": { "device": "ide0-hd1",
7022 "operation": "write",
7023 "action": "stop" },
7024 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7025 BLOCK_JOB_READY (Event)
7027 Emitted when a block job is ready to complete
7028 Arguments
7030 type: JobType
7031 job type
7032 device: string
7034 The job identifier. Originally the device name but other values
7035 are allowed since QEMU 2.7
7036 len: int
7038 maximum progress value
7039 offset: int
7041 current progress value. On success this is equal to len. On
7042 failure this is less than len
7043 speed: int
7045 rate limit, bytes per second
7046 Note
7048 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
7049 event
7050 Since
7052 1.3
7053 Example
7055 <- { "event": "BLOCK_JOB_READY",
7056 "data": { "device": "drive0", "type": "mirror", "speed": 0,
7057 "len": 2097152, "offset": 2097152 }
7058 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7059 BLOCK_JOB_PENDING (Event)
7061 Emitted when a block job is awaiting explicit authorization to finalize
7062 graph changes via block-job-finalize. If this job is part of a transac‐
7063 tion, it will not emit this event until the transaction has converged
7064 first.
7065 Arguments
7067 type: JobType
7068 job type
7069 id: string
7071 The job identifier.
7072 Since
7074 2.12
7075 Example
7077 <- { "event": "BLOCK_JOB_WAITING",
7078 "data": { "device": "drive0", "type": "mirror" },
7079 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7080 PreallocMode (Enum)
7082 Preallocation mode of QEMU image file
7083 Values
7085 off no preallocation
7086 metadata
7088 preallocate only for metadata
7089 falloc like full preallocation but allocate disk space by posix_fallo‐
7091 cate() rather than writing data.
7092 full preallocate all data by writing it to the device to ensure disk
7094 space is really available. This data may or may not be zero, de‐
7095 pending on the image format and storage. full preallocation
7096 also sets up metadata correctly.
7097 Since
7099 2.2
7100 BLOCK_WRITE_THRESHOLD (Event)
7102 Emitted when writes on block device reaches or exceeds the configured
7103 write threshold. For thin-provisioned devices, this means the device
7104 should be extended to avoid pausing for disk exhaustion. The event is
7105 one shot. Once triggered, it needs to be re-registered with another
7106 block-set-write-threshold command.
7107 Arguments
7109 node-name: string
7110 graph node name on which the threshold was exceeded.
7111 amount-exceeded: int
7113 amount of data which exceeded the threshold, in bytes.
7114 write-threshold: int
7116 last configured threshold, in bytes.
7117 Since
7119 2.3
7120 block-set-write-threshold (Command)
7122 Change the write threshold for a block drive. An event will be deliv‐
7123 ered if a write to this block drive crosses the configured threshold.
7124 The threshold is an offset, thus must be non-negative. Default is no
7125 write threshold. Setting the threshold to zero disables it.
7126 This is useful to transparently resize thin-provisioned drives without
7128 the guest OS noticing.
7129 Arguments
7131 node-name: string
7132 graph node name on which the threshold must be set.
7133 write-threshold: int
7135 configured threshold for the block device, bytes. Use 0 to dis‐
7136 able the threshold.
7137 Since
7139 2.3
7140 Example
7142 -> { "execute": "block-set-write-threshold",
7143 "arguments": { "node-name": "mydev",
7144 "write-threshold": 17179869184 } }
7145 <- { "return": {} }
7146 x-blockdev-change (Command)
7148 Dynamically reconfigure the block driver state graph. It can be used to
7149 add, remove, insert or replace a graph node. Currently only the Quorum
7150 driver implements this feature to add or remove its child. This is use‐
7151 ful to fix a broken quorum child.
7152 If node is specified, it will be inserted under parent. child may not
7154 be specified in this case. If both parent and child are specified but
7155 node is not, child will be detached from parent.
7156 Arguments
7158 parent: string
7159 the id or name of the parent node.
7160 child: string (optional)
7162 the name of a child under the given parent node.
7163 node: string (optional)
7165 the name of the node that will be added.
7166 Note
7168 this command is experimental, and its API is not stable. It does not
7169 support all kinds of operations, all kinds of children, nor all block
7170 drivers.
7171 FIXME Removing children from a quorum node means introducing gaps in
7173 the child indices. This cannot be represented in the 'children' list of
7174 BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename().
7175 Warning: The data in a new quorum child MUST be consistent with that of
7177 the rest of the array.
7178 Since
7180 2.7
7181 Example
7183 1. Add a new node to a quorum
7184 -> { "execute": "blockdev-add",
7185 "arguments": {
7186 "driver": "raw",
7187 "node-name": "new_node",
7188 "file": { "driver": "file",
7189 "filename": "test.raw" } } }
7190 <- { "return": {} }
7191 -> { "execute": "x-blockdev-change",
7192 "arguments": { "parent": "disk1",
7193 "node": "new_node" } }
7194 <- { "return": {} }
7195 2. Delete a quorum's node
7197 -> { "execute": "x-blockdev-change",
7198 "arguments": { "parent": "disk1",
7199 "child": "children.1" } }
7200 <- { "return": {} }
7201 x-blockdev-set-iothread (Command)
7203 Move node and its children into the iothread. If iothread is null then
7204 move node and its children into the main loop.
7205 The node must not be attached to a BlockBackend.
7207 Arguments
7209 node-name: string
7210 the name of the block driver node
7211 iothread: StrOrNull
7213 the name of the IOThread object or null for the main loop
7214 force: boolean (optional)
7216 true if the node and its children should be moved when a Block‐
7217 Backend is already attached
7218 Note
7220 this command is experimental and intended for test cases that need con‐
7221 trol over IOThreads only.
7222 Since
7224 2.12
7225 Example
7227 1. Move a node into an IOThread
7228 -> { "execute": "x-blockdev-set-iothread",
7229 "arguments": { "node-name": "disk1",
7230 "iothread": "iothread0" } }
7231 <- { "return": {} }
7232 2. Move a node into the main loop
7234 -> { "execute": "x-blockdev-set-iothread",
7235 "arguments": { "node-name": "disk1",
7236 "iothread": null } }
7237 <- { "return": {} }
7238 QuorumOpType (Enum)
7240 An enumeration of the quorum operation types
7241 Values
7243 read read operation
7244 write write operation
7246 flush flush operation
7248 Since
7250 2.6
7251 QUORUM_FAILURE (Event)
7253 Emitted by the Quorum block driver if it fails to establish a quorum
7254 Arguments
7256 reference: string
7257 device name if defined else node name
7258 sector-num: int
7260 number of the first sector of the failed read operation
7261 sectors-count: int
7263 failed read operation sector count
7264 Note
7266 This event is rate-limited.
7267 Since
7269 2.0
7270 Example
7272 <- { "event": "QUORUM_FAILURE",
7273 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
7274 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7275 QUORUM_REPORT_BAD (Event)
7277 Emitted to report a corruption of a Quorum file
7278 Arguments
7280 type: QuorumOpType
7281 quorum operation type (Since 2.6)
7282 error: string (optional)
7284 error message. Only present on failure. This field contains a
7285 human-readable error message. There are no semantics other than
7286 that the block layer reported an error and clients should not
7287 try to interpret the error string.
7288 node-name: string
7290 the graph node name of the block driver state
7291 sector-num: int
7293 number of the first sector of the failed read operation
7294 sectors-count: int
7296 failed read operation sector count
7297 Note
7299 This event is rate-limited.
7300 Since
7302 2.0
7303 Example
7305 1. Read operation
7306 { "event": "QUORUM_REPORT_BAD",
7308 "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
7309 "type": "read" },
7310 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7311 2. Flush operation
7313 { "event": "QUORUM_REPORT_BAD",
7315 "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
7316 "type": "flush", "error": "Broken pipe" },
7317 "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
7318 BlockdevSnapshotInternal (Object)
7320 Members
7321 device: string
7322 the device name or node-name of a root node to generate the
7323 snapshot from
7324 name: string
7326 the name of the internal snapshot to be created
7327 Notes
7329 In transaction, if name is empty, or any snapshot matching name exists,
7330 the operation will fail. Only some image formats support it, for exam‐
7331 ple, qcow2, and rbd.
7332 Since
7334 1.7
7335 blockdev-snapshot-internal-sync (Command)
7337 Synchronously take an internal snapshot of a block device, when the
7338 format of the image used supports it. If the name is an empty string,
7339 or a snapshot with name already exists, the operation will fail.
7340 For the arguments, see the documentation of BlockdevSnapshotInternal.
7342 Returns
7344 • nothing on success
7345 • If device is not a valid block device, GenericError
7347 • If any snapshot matching name exists, or name is empty, GenericError
7349 • If the format of the image used does not support it, BlockFormatFea‐
7351 tureNotSupported
7352 Since
7354 1.7
7355 Example
7357 -> { "execute": "blockdev-snapshot-internal-sync",
7358 "arguments": { "device": "ide-hd0",
7359 "name": "snapshot0" }
7360 }
7361 <- { "return": {} }
7362 blockdev-snapshot-delete-internal-sync (Command)
7364 Synchronously delete an internal snapshot of a block device, when the
7365 format of the image used support it. The snapshot is identified by name
7366 or id or both. One of the name or id is required. Return SnapshotInfo
7367 for the successfully deleted snapshot.
7368 Arguments
7370 device: string
7371 the device name or node-name of a root node to delete the snap‐
7372 shot from
7373 id: string (optional)
7375 optional the snapshot's ID to be deleted
7376 name: string (optional)
7378 optional the snapshot's name to be deleted
7379 Returns
7381 • SnapshotInfo on success
7382 • If device is not a valid block device, GenericError
7384 • If snapshot not found, GenericError
7386 • If the format of the image used does not support it, BlockFormatFea‐
7388 tureNotSupported
7389 • If id and name are both not specified, GenericError
7391 Since
7393 1.7
7394 Example
7396 -> { "execute": "blockdev-snapshot-delete-internal-sync",
7397 "arguments": { "device": "ide-hd0",
7398 "name": "snapshot0" }
7399 }
7400 <- { "return": {
7401 "id": "1",
7402 "name": "snapshot0",
7403 "vm-state-size": 0,
7404 "date-sec": 1000012,
7405 "date-nsec": 10,
7406 "vm-clock-sec": 100,
7407 "vm-clock-nsec": 20,
7408 "icount": 220414
7409 }
7410 }
7411 Block device exports
7413 NbdServerOptions (Object)
7414 Keep this type consistent with the nbd-server-start arguments. The only
7415 intended difference is using SocketAddress instead of SocketAddressLe‐
7416 gacy.
7417 Members
7419 addr: SocketAddress
7420 Address on which to listen.
7421 tls-creds: string (optional)
7423 ID of the TLS credentials object (since 2.6).
7424 tls-authz: string (optional)
7426 ID of the QAuthZ authorization object used to validate the
7427 client's x509 distinguished name. This object is is only re‐
7428 solved at time of use, so can be deleted and recreated on the
7429 fly while the NBD server is active. If missing, it will default
7430 to denying access (since 4.0).
7431 max-connections: int (optional)
7433 The maximum number of connections to allow at the same time, 0
7434 for unlimited. (since 5.2; default: 0)
7435 Since
7437 4.2
7438 nbd-server-start (Command)
7440 Start an NBD server listening on the given host and port. Block de‐
7441 vices can then be exported using nbd-server-add. The NBD server will
7442 present them as named exports; for example, another QEMU instance could
7443 refer to them as "nbd:HOST:PORT:exportname=NAME".
7444 Keep this type consistent with the NbdServerOptions type. The only in‐
7446 tended difference is using SocketAddressLegacy instead of SocketAd‐
7447 dress.
7448 Arguments
7450 addr: SocketAddressLegacy
7451 Address on which to listen.
7452 tls-creds: string (optional)
7454 ID of the TLS credentials object (since 2.6).
7455 tls-authz: string (optional)
7457 ID of the QAuthZ authorization object used to validate the
7458 client's x509 distinguished name. This object is is only re‐
7459 solved at time of use, so can be deleted and recreated on the
7460 fly while the NBD server is active. If missing, it will default
7461 to denying access (since 4.0).
7462 max-connections: int (optional)
7464 The maximum number of connections to allow at the same time, 0
7465 for unlimited. (since 5.2; default: 0)
7466 Returns
7468 error if the server is already running.
7469 Since
7471 1.3
7472 BlockExportOptionsNbdBase (Object)
7474 An NBD block export (common options shared between nbd-server-add and
7475 the NBD branch of block-export-add).
7476 Members
7478 name: string (optional)
7479 Export name. If unspecified, the device parameter is used as the
7480 export name. (Since 2.12)
7481 description: string (optional)
7483 Free-form description of the export, up to 4096 bytes. (Since
7484 5.0)
7485 Since
7487 5.0
7488 BlockExportOptionsNbd (Object)
7490 An NBD block export (distinct options used in the NBD branch of
7491 block-export-add).
7492 Members
7494 bitmaps: array of string (optional)
7495 Also export each of the named dirty bitmaps reachable from de‐
7496 vice, so the NBD client can use NBD_OPT_SET_META_CONTEXT with
7497 the metadata context name "qemu:dirty-bitmap:BITMAP" to inspect
7498 each bitmap.
7499 allocation-depth: boolean (optional)
7501 Also export the allocation depth map for device, so the NBD
7502 client can use NBD_OPT_SET_META_CONTEXT with the metadata con‐
7503 text name "qemu:allocation-depth" to inspect allocation details.
7504 (since 5.2)
7505 The members of BlockExportOptionsNbdBase
7507 Since
7509 5.2
7510 BlockExportOptionsVhostUserBlk (Object)
7512 A vhost-user-blk block export.
7513 Members
7515 addr: SocketAddress
7516 The vhost-user socket on which to listen. Both 'unix' and 'fd'
7517 SocketAddress types are supported. Passed fds must be UNIX do‐
7518 main sockets.
7519 logical-block-size: int (optional)
7521 Logical block size in bytes. Defaults to 512 bytes.
7522 num-queues: int (optional)
7524 Number of request virtqueues. Must be greater than 0. Defaults
7525 to 1.
7526 Since
7528 5.2
7529 FuseExportAllowOther (Enum)
7531 Possible allow_other modes for FUSE exports.
7532 Values
7534 off Do not pass allow_other as a mount option.
7535 on Pass allow_other as a mount option.
7537 auto Try mounting with allow_other first, and if that fails, retry
7539 without allow_other.
7540 Since
7542 6.1
7543 BlockExportOptionsFuse (Object)
7545 Options for exporting a block graph node on some (file) mountpoint as a
7546 raw image.
7547 Members
7549 mountpoint: string
7550 Path on which to export the block device via FUSE. This must
7551 point to an existing regular file.
7552 growable: boolean (optional)
7554 Whether writes beyond the EOF should grow the block node accord‐
7555 ingly. (default: false)
7556 allow-other: FuseExportAllowOther (optional)
7558 If this is off, only qemu's user is allowed access to this ex‐
7559 port. That cannot be changed even with chmod or chown. En‐
7560 abling this option will allow other users access to the export
7561 with the FUSE mount option "allow_other". Note that using al‐
7562 low_other as a non-root user requires user_allow_other to be en‐
7563 abled in the global fuse.conf configuration file. In auto mode
7564 (the default), the FUSE export driver will first attempt to
7565 mount the export with allow_other, and if that fails, try again
7566 without. (since 6.1; default: auto)
7567 Since
7569 6.0
7570 If
7572 defined(CONFIG_FUSE)
7573 NbdServerAddOptions (Object)
7575 An NBD block export, per legacy nbd-server-add command.
7576 Members
7578 device: string
7579 The device name or node name of the node to be exported
7580 writable: boolean (optional)
7582 Whether clients should be able to write to the device via the
7583 NBD connection (default false).
7584 bitmap: string (optional)
7586 Also export a single dirty bitmap reachable from device, so the
7587 NBD client can use NBD_OPT_SET_META_CONTEXT with the metadata
7588 context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap
7589 (since 4.0).
7590 The members of BlockExportOptionsNbdBase
7592 Since
7594 5.0
7595 nbd-server-add (Command)
7597 Export a block node to QEMU's embedded NBD server.
7598 The export name will be used as the id for the resulting block export.
7600 Arguments
7602 The members of NbdServerAddOptions
7603 Features
7605 deprecated
7606 This command is deprecated. Use block-export-add instead.
7607 Returns
7609 error if the server is not running, or export with the same name al‐
7610 ready exists.
7611 Since
7613 1.3
7614 BlockExportRemoveMode (Enum)
7616 Mode for removing a block export.
7617 Values
7619 safe Remove export if there are no existing connections, fail other‐
7620 wise.
7621 hard Drop all connections immediately and remove export.
7623 Potential additional modes to be added in the future:
7624 hide: Just hide export from new clients, leave existing connections as
7626 is. Remove export after all clients are disconnected.
7627 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
7629 ther requests from existing clients.
7630 Since
7632 2.12
7633 nbd-server-remove (Command)
7635 Remove NBD export by name.
7636 Arguments
7638 name: string
7639 Block export id.
7640 mode: BlockExportRemoveMode (optional)
7642 Mode of command operation. See BlockExportRemoveMode descrip‐
7643 tion. Default is 'safe'.
7644 Features
7646 deprecated
7647 This command is deprecated. Use block-export-del instead.
7648 Returns
7650 error if
7651 • the server is not running
7653 • export is not found
7655 • mode is 'safe' and there are existing connections
7657 Since
7659 2.12
7660 nbd-server-stop (Command)
7662 Stop QEMU's embedded NBD server, and unregister all devices previously
7663 added via nbd-server-add.
7664 Since
7666 1.3
7667 BlockExportType (Enum)
7669 An enumeration of block export types
7670 Values
7672 nbd NBD export
7673 vhost-user-blk
7675 vhost-user-blk export (since 5.2)
7676 fuse (If: defined(CONFIG_FUSE))
7678 FUSE export (since: 6.0)
7679 Since
7681 4.2
7682 BlockExportOptions (Object)
7684 Describes a block export, i.e. how single node should be exported on an
7685 external interface.
7686 Members
7688 id: string
7689 A unique identifier for the block export (across all export
7690 types)
7691 node-name: string
7693 The node name of the block node to be exported (since: 5.2)
7694 writable: boolean (optional)
7696 True if clients should be able to write to the export (default
7697 false)
7698 writethrough: boolean (optional)
7700 If true, caches are flushed after every write request to the ex‐
7701 port before completion is signalled. (since: 5.2; default:
7702 false)
7703 iothread: string (optional)
7705 The name of the iothread object where the export will run. The
7706 default is to use the thread currently associated with the block
7707 node. (since: 5.2)
7708 fixed-iothread: boolean (optional)
7710 True prevents the block node from being moved to another thread
7711 while the export is active. If true and iothread is given, ex‐
7712 port creation fails if the block node cannot be moved to the io‐
7713 thread. The default is false. (since: 5.2)
7714 type: BlockExportType
7716 Not documented
7717 The members of BlockExportOptionsNbd when type is "nbd"
7719 The members of BlockExportOptionsVhostUserBlk when type is
7721 "vhost-user-blk"
7722 The members of BlockExportOptionsFuse when type is "fuse" (If: de‐
7724 fined(CONFIG_FUSE))
7725 Since
7727 4.2
7728 block-export-add (Command)
7730 Creates a new block export.
7731 Arguments
7733 The members of BlockExportOptions
7734 Since
7736 5.2
7737 block-export-del (Command)
7739 Request to remove a block export. This drops the user's reference to
7740 the export, but the export may still stay around after this command re‐
7741 turns until the shutdown of the export has completed.
7742 Arguments
7744 id: string
7745 Block export id.
7746 mode: BlockExportRemoveMode (optional)
7748 Mode of command operation. See BlockExportRemoveMode descrip‐
7749 tion. Default is 'safe'.
7750 Returns
7752 Error if the export is not found or mode is 'safe' and the export is
7753 still in use (e.g. by existing client connections)
7754 Since
7756 5.2
7757 BLOCK_EXPORT_DELETED (Event)
7759 Emitted when a block export is removed and its id can be reused.
7760 Arguments
7762 id: string
7763 Block export id.
7764 Since
7766 5.2
7767 BlockExportInfo (Object)
7769 Information about a single block export.
7770 Members
7772 id: string
7773 The unique identifier for the block export
7774 type: BlockExportType
7776 The block export type
7777 node-name: string
7779 The node name of the block node that is exported
7780 shutting-down: boolean
7782 True if the export is shutting down (e.g. after a block-ex‐
7783 port-del command, but before the shutdown has completed)
7784 Since
7786 5.2
7787 query-block-exports (Command)
7789 Returns
7790 A list of BlockExportInfo describing all block exports
7791 Since
7793 5.2
7794
7796 ChardevInfo (Object)
7797 Information about a character device.
7798 Members
7800 label: string
7801 the label of the character device
7802 filename: string
7804 the filename of the character device
7805 frontend-open: boolean
7807 shows whether the frontend device attached to this backend (eg.
7808 with the chardev=... option) is in open or closed state (since
7809 2.1)
7810 Notes
7812 filename is encoded using the QEMU command line character device encod‐
7813 ing. See the QEMU man page for details.
7814 Since
7816 0.14
7817 query-chardev (Command)
7819 Returns information about current character devices.
7820 Returns
7822 a list of ChardevInfo
7823 Since
7825 0.14
7826 Example
7828 -> { "execute": "query-chardev" }
7829 <- {
7830 "return": [
7831 {
7832 "label": "charchannel0",
7833 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server=on",
7834 "frontend-open": false
7835 },
7836 {
7837 "label": "charmonitor",
7838 "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server=on",
7839 "frontend-open": true
7840 },
7841 {
7842 "label": "charserial0",
7843 "filename": "pty:/dev/pts/2",
7844 "frontend-open": true
7845 }
7846 ]
7847 }
7848 ChardevBackendInfo (Object)
7850 Information about a character device backend
7851 Members
7853 name: string
7854 The backend name
7855 Since
7857 2.0
7858 query-chardev-backends (Command)
7860 Returns information about character device backends.
7861 Returns
7863 a list of ChardevBackendInfo
7864 Since
7866 2.0
7867 Example
7869 -> { "execute": "query-chardev-backends" }
7870 <- {
7871 "return":[
7872 {
7873 "name":"udp"
7874 },
7875 {
7876 "name":"tcp"
7877 },
7878 {
7879 "name":"unix"
7880 },
7881 {
7882 "name":"spiceport"
7883 }
7884 ]
7885 }
7886 DataFormat (Enum)
7888 An enumeration of data format.
7889 Values
7891 utf8 Data is a UTF-8 string (RFC 3629)
7892 base64 Data is Base64 encoded binary (RFC 3548)
7894 Since
7896 1.4
7897 ringbuf-write (Command)
7899 Write to a ring buffer character device.
7900 Arguments
7902 device: string
7903 the ring buffer character device name
7904 data: string
7906 data to write
7907 format: DataFormat (optional)
7909 data encoding (default 'utf8').
7910 • base64: data must be base64 encoded text. Its binary decoding
7912 gets written.
7913 • utf8: data's UTF-8 encoding is written
7915 • data itself is always Unicode regardless of format, like any
7917 other string.
7918 Returns
7920 Nothing on success
7921 Since
7923 1.4
7924 Example
7926 -> { "execute": "ringbuf-write",
7927 "arguments": { "device": "foo",
7928 "data": "abcdefgh",
7929 "format": "utf8" } }
7930 <- { "return": {} }
7931 ringbuf-read (Command)
7933 Read from a ring buffer character device.
7934 Arguments
7936 device: string
7937 the ring buffer character device name
7938 size: int
7940 how many bytes to read at most
7941 format: DataFormat (optional)
7943 data encoding (default 'utf8').
7944 • base64: the data read is returned in base64 encoding.
7946 • utf8: the data read is interpreted as UTF-8. Bug: can screw
7948 up when the buffer contains invalid UTF-8 sequences, NUL char‐
7949 acters, after the ring buffer lost data, and when reading
7950 stops because the size limit is reached.
7951 • The return value is always Unicode regardless of format, like
7953 any other string.
7954 Returns
7956 data read from the device
7957 Since
7959 1.4
7960 Example
7962 -> { "execute": "ringbuf-read",
7963 "arguments": { "device": "foo",
7964 "size": 1000,
7965 "format": "utf8" } }
7966 <- { "return": "abcdefgh" }
7967 ChardevCommon (Object)
7969 Configuration shared across all chardev backends
7970 Members
7972 logfile: string (optional)
7973 The name of a logfile to save output
7974 logappend: boolean (optional)
7976 true to append instead of truncate (default to false to trun‐
7977 cate)
7978 Since
7980 2.6
7981 ChardevFile (Object)
7983 Configuration info for file chardevs.
7984 Members
7986 in: string (optional)
7987 The name of the input file
7988 out: string
7990 The name of the output file
7991 append: boolean (optional)
7993 Open the file in append mode (default false to truncate) (Since
7994 2.6)
7995 The members of ChardevCommon
7997 Since
7999 1.4
8000 ChardevHostdev (Object)
8002 Configuration info for device and pipe chardevs.
8003 Members
8005 device: string
8006 The name of the special file for the device, i.e. /dev/ttyS0 on
8007 Unix or COM1: on Windows
8008 The members of ChardevCommon
8010 Since
8012 1.4
8013 ChardevSocket (Object)
8015 Configuration info for (stream) socket chardevs.
8016 Members
8018 addr: SocketAddressLegacy
8019 socket address to listen on (server=true) or connect to
8020 (server=false)
8021 tls-creds: string (optional)
8023 the ID of the TLS credentials object (since 2.6)
8024 tls-authz: string (optional)
8026 the ID of the QAuthZ authorization object against which the
8027 client's x509 distinguished name will be validated. This object
8028 is only resolved at time of use, so can be deleted and recreated
8029 on the fly while the chardev server is active. If missing, it
8030 will default to denying access (since 4.0)
8031 server: boolean (optional)
8033 create server socket (default: true)
8034 wait: boolean (optional)
8036 wait for incoming connection on server sockets (default: false).
8037 Silently ignored with server: false. This use is deprecated.
8038 nodelay: boolean (optional)
8040 set TCP_NODELAY socket option (default: false)
8041 telnet: boolean (optional)
8043 enable telnet protocol on server sockets (default: false)
8044 tn3270: boolean (optional)
8046 enable tn3270 protocol on server sockets (default: false)
8047 (Since: 2.10)
8048 websocket: boolean (optional)
8050 enable websocket protocol on server sockets (default: false)
8051 (Since: 3.1)
8052 reconnect: int (optional)
8054 For a client socket, if a socket is disconnected, then attempt a
8055 reconnect after the given number of seconds. Setting this to
8056 zero disables this function. (default: 0) (Since: 2.2)
8057 The members of ChardevCommon
8059 Since
8061 1.4
8062 ChardevUdp (Object)
8064 Configuration info for datagram socket chardevs.
8065 Members
8067 remote: SocketAddressLegacy
8068 remote address
8069 local: SocketAddressLegacy (optional)
8071 local address
8072 The members of ChardevCommon
8074 Since
8076 1.5
8077 ChardevMux (Object)
8079 Configuration info for mux chardevs.
8080 Members
8082 chardev: string
8083 name of the base chardev.
8084 The members of ChardevCommon
8086 Since
8088 1.5
8089 ChardevStdio (Object)
8091 Configuration info for stdio chardevs.
8092 Members
8094 signal: boolean (optional)
8095 Allow signals (such as SIGINT triggered by ^C) be delivered to
8096 qemu. Default: true.
8097 The members of ChardevCommon
8099 Since
8101 1.5
8102 ChardevSpiceChannel (Object)
8104 Configuration info for spice vm channel chardevs.
8105 Members
8107 type: string
8108 kind of channel (for example vdagent).
8109 The members of ChardevCommon
8111 Since
8113 1.5
8114 If
8116 defined(CONFIG_SPICE)
8117 ChardevSpicePort (Object)
8119 Configuration info for spice port chardevs.
8120 Members
8122 fqdn: string
8123 name of the channel (see docs/spice-port-fqdn.txt)
8124 The members of ChardevCommon
8126 Since
8128 1.5
8129 If
8131 defined(CONFIG_SPICE)
8132 ChardevVC (Object)
8134 Configuration info for virtual console chardevs.
8135 Members
8137 width: int (optional)
8138 console width, in pixels
8139 height: int (optional)
8141 console height, in pixels
8142 cols: int (optional)
8144 console width, in chars
8145 rows: int (optional)
8147 console height, in chars
8148 The members of ChardevCommon
8150 Since
8152 1.5
8153 ChardevRingbuf (Object)
8155 Configuration info for ring buffer chardevs.
8156 Members
8158 size: int (optional)
8159 ring buffer size, must be power of two, default is 65536
8160 The members of ChardevCommon
8162 Since
8164 1.5
8165 ChardevQemuVDAgent (Object)
8167 Configuration info for qemu vdagent implementation.
8168 Members
8170 mouse: boolean (optional)
8171 enable/disable mouse, default is enabled.
8172 clipboard: boolean (optional)
8174 enable/disable clipboard, default is disabled.
8175 The members of ChardevCommon
8177 Since
8179 6.1
8180 If
8182 defined(CONFIG_SPICE_PROTOCOL)
8183 ChardevBackend (Object)
8185 Configuration info for the new chardev backend.
8186 Members
8188 type One of file, serial, parallel, pipe, socket, udp, pty, null,
8189 mux, msmouse, wctablet, braille, testdev, stdio, console,
8190 spicevmc, spiceport, qemu-vdagent, vc, ringbuf, memory
8191 data: ChardevFile when type is "file"
8193 data: ChardevHostdev when type is "serial"
8195 data: ChardevHostdev when type is "parallel"
8197 data: ChardevHostdev when type is "pipe"
8199 data: ChardevSocket when type is "socket"
8201 data: ChardevUdp when type is "udp"
8203 data: ChardevCommon when type is "pty"
8205 data: ChardevCommon when type is "null"
8207 data: ChardevMux when type is "mux"
8209 data: ChardevCommon when type is "msmouse"
8211 data: ChardevCommon when type is "wctablet"
8213 data: ChardevCommon when type is "braille"
8215 data: ChardevCommon when type is "testdev"
8217 data: ChardevStdio when type is "stdio"
8219 data: ChardevCommon when type is "console"
8221 data: ChardevSpiceChannel when type is "spicevmc" (If: defined(CON‐
8223 FIG_SPICE))
8224 data: ChardevSpicePort when type is "spiceport" (If: defined(CON‐
8226 FIG_SPICE))
8227 data: ChardevQemuVDAgent when type is "qemu-vdagent" (If: defined(CON‐
8229 FIG_SPICE_PROTOCOL))
8230 data: ChardevVC when type is "vc"
8232 data: ChardevRingbuf when type is "ringbuf"
8234 data: ChardevRingbuf when type is "memory"
8236 Since
8238 1.4 (testdev since 2.2, wctablet since 2.9, vdagent since 6.1)
8239 ChardevReturn (Object)
8241 Return info about the chardev backend just created.
8242 Members
8244 pty: string (optional)
8245 name of the slave pseudoterminal device, present if and only if
8246 a chardev of type 'pty' was created
8247 Since
8249 1.4
8250 chardev-add (Command)
8252 Add a character device backend
8253 Arguments
8255 id: string
8256 the chardev's ID, must be unique
8257 backend: ChardevBackend
8259 backend type and parameters
8260 Returns
8262 ChardevReturn.
8263 Since
8265 1.4
8266 Example
8268 -> { "execute" : "chardev-add",
8269 "arguments" : { "id" : "foo",
8270 "backend" : { "type" : "null", "data" : {} } } }
8271 <- { "return": {} }
8272 -> { "execute" : "chardev-add",
8274 "arguments" : { "id" : "bar",
8275 "backend" : { "type" : "file",
8276 "data" : { "out" : "/tmp/bar.log" } } } }
8277 <- { "return": {} }
8278 -> { "execute" : "chardev-add",
8280 "arguments" : { "id" : "baz",
8281 "backend" : { "type" : "pty", "data" : {} } } }
8282 <- { "return": { "pty" : "/dev/pty/42" } }
8283 chardev-change (Command)
8285 Change a character device backend
8286 Arguments
8288 id: string
8289 the chardev's ID, must exist
8290 backend: ChardevBackend
8292 new backend type and parameters
8293 Returns
8295 ChardevReturn.
8296 Since
8298 2.10
8299 Example
8301 -> { "execute" : "chardev-change",
8302 "arguments" : { "id" : "baz",
8303 "backend" : { "type" : "pty", "data" : {} } } }
8304 <- { "return": { "pty" : "/dev/pty/42" } }
8305 -> {"execute" : "chardev-change",
8307 "arguments" : {
8308 "id" : "charchannel2",
8309 "backend" : {
8310 "type" : "socket",
8311 "data" : {
8312 "addr" : {
8313 "type" : "unix" ,
8314 "data" : {
8315 "path" : "/tmp/charchannel2.socket"
8316 }
8317 },
8318 "server" : true,
8319 "wait" : false }}}}
8320 <- {"return": {}}
8321 chardev-remove (Command)
8323 Remove a character device backend
8324 Arguments
8326 id: string
8327 the chardev's ID, must exist and not be in use
8328 Returns
8330 Nothing on success
8331 Since
8333 1.4
8334 Example
8336 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
8337 <- { "return": {} }
8338 chardev-send-break (Command)
8340 Send a break to a character device
8341 Arguments
8343 id: string
8344 the chardev's ID, must exist
8345 Returns
8347 Nothing on success
8348 Since
8350 2.10
8351 Example
8353 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
8354 <- { "return": {} }
8355 VSERPORT_CHANGE (Event)
8357 Emitted when the guest opens or closes a virtio-serial port.
8358 Arguments
8360 id: string
8361 device identifier of the virtio-serial port
8362 open: boolean
8364 true if the guest has opened the virtio-serial port
8365 Note
8367 This event is rate-limited.
8368 Since
8370 2.1
8371 Example
8373 <- { "event": "VSERPORT_CHANGE",
8374 "data": { "id": "channel0", "open": true },
8375 "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
8376
8378 qmp_capabilities (Command)
8379 Enable QMP capabilities.
8380 Arguments:
8382 Arguments
8384 enable: array of QMPCapability (optional)
8385 An optional list of QMPCapability values to enable. The client
8386 must not enable any capability that is not mentioned in the QMP
8387 greeting message. If the field is not provided, it means no QMP
8388 capabilities will be enabled. (since 2.12)
8389 Example
8391 -> { "execute": "qmp_capabilities",
8392 "arguments": { "enable": [ "oob" ] } }
8393 <- { "return": {} }
8394 Notes
8396 This command is valid exactly when first connecting: it must be issued
8397 before any other command will be accepted, and will fail once the moni‐
8398 tor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
8399 The QMP client needs to explicitly enable QMP capabilities, otherwise
8401 all the QMP capabilities will be turned off by default.
8402 Since
8404 0.13
8405 QMPCapability (Enum)
8407 Enumeration of capabilities to be advertised during initial client con‐
8408 nection, used for agreeing on particular QMP extension behaviors.
8409 Values
8411 oob QMP ability to support out-of-band requests. (Please refer to
8412 qmp-spec.txt for more information on OOB)
8413 Since
8415 2.12
8416 VersionTriple (Object)
8418 A three-part version number.
8419 Members
8421 major: int
8422 The major version number.
8423 minor: int
8425 The minor version number.
8426 micro: int
8428 The micro version number.
8429 Since
8431 2.4
8432 VersionInfo (Object)
8434 A description of QEMU's version.
8435 Members
8437 qemu: VersionTriple
8438 The version of QEMU. By current convention, a micro version of
8439 50 signifies a development branch. A micro version greater than
8440 or equal to 90 signifies a release candidate for the next minor
8441 version. A micro version of less than 50 signifies a stable re‐
8442 lease.
8443 package: string
8445 QEMU will always set this field to an empty string. Downstream
8446 versions of QEMU should set this to a non-empty string. The ex‐
8447 act format depends on the downstream however it highly recom‐
8448 mended that a unique name is used.
8449 Since
8451 0.14
8452 query-version (Command)
8454 Returns the current version of QEMU.
8455 Returns
8457 A VersionInfo object describing the current version of QEMU.
8458 Since
8460 0.14
8461 Example
8463 -> { "execute": "query-version" }
8464 <- {
8465 "return":{
8466 "qemu":{
8467 "major":0,
8468 "minor":11,
8469 "micro":5
8470 },
8471 "package":""
8472 }
8473 }
8474 CommandInfo (Object)
8476 Information about a QMP command
8477 Members
8479 name: string
8480 The command name
8481 Since
8483 0.14
8484 query-commands (Command)
8486 Return a list of supported QMP commands by this server
8487 Returns
8489 A list of CommandInfo for all supported commands
8490 Since
8492 0.14
8493 Example
8495 -> { "execute": "query-commands" }
8496 <- {
8497 "return":[
8498 {
8499 "name":"query-balloon"
8500 },
8501 {
8502 "name":"system_powerdown"
8503 }
8504 ]
8505 }
8506 Note
8508 This example has been shortened as the real response is too long.
8509 quit (Command)
8511 This command will cause the QEMU process to exit gracefully. While ev‐
8512 ery attempt is made to send the QMP response before terminating, this
8513 is not guaranteed. When using this interface, a premature EOF would
8514 not be unexpected.
8515 Since
8517 0.14
8518 Example
8520 -> { "execute": "quit" }
8521 <- { "return": {} }
8522 MonitorMode (Enum)
8524 An enumeration of monitor modes.
8525 Values
8527 readline
8528 HMP monitor (human-oriented command line interface)
8529 control
8531 QMP monitor (JSON-based machine interface)
8532 Since
8534 5.0
8535 MonitorOptions (Object)
8537 Options to be used for adding a new monitor.
8538 Members
8540 id: string (optional)
8541 Name of the monitor
8542 mode: MonitorMode (optional)
8544 Selects the monitor mode (default: readline in the system emula‐
8545 tor, control in qemu-storage-daemon)
8546 pretty: boolean (optional)
8548 Enables pretty printing (QMP only)
8549 chardev: string
8551 Name of a character device to expose the monitor on
8552 Since
8554 5.0
8555
8557 query-qmp-schema (Command)
8558 Command query-qmp-schema exposes the QMP wire ABI as an array of
8559 SchemaInfo. This lets QMP clients figure out what commands and events
8560 are available in this QEMU, and their parameters and results.
8561 However, the SchemaInfo can't reflect all the rules and restrictions
8563 that apply to QMP. It's interface introspection (figuring out what's
8564 there), not interface specification. The specification is in the QAPI
8565 schema.
8566 Furthermore, while we strive to keep the QMP wire format backwards-com‐
8568 patible across qemu versions, the introspection output is not guaran‐
8569 teed to have the same stability. For example, one version of qemu may
8570 list an object member as an optional non-variant, while another lists
8571 the same member only through the object's variants; or the type of a
8572 member may change from a generic string into a specific enum or from
8573 one specific type into an alternate that includes the original type
8574 alongside something else.
8575 Returns
8577 array of SchemaInfo, where each element describes an entity in the ABI:
8578 command, event, type, ...
8579 The order of the various SchemaInfo is unspecified; however, all names
8581 are guaranteed to be unique (no name will be duplicated with different
8582 meta-types).
8583 Note
8585 the QAPI schema is also used to help define internal interfaces, by
8586 defining QAPI types. These are not part of the QMP wire ABI, and
8587 therefore not returned by this command.
8588 Since
8590 2.5
8591 SchemaMetaType (Enum)
8593 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
8594 Values
8596 builtin
8597 a predefined type such as 'int' or 'bool'.
8598 enum an enumeration type
8600 array an array type
8602 object an object type (struct or union)
8604 alternate
8606 an alternate type
8607 command
8609 a QMP command
8610 event a QMP event
8612 Since
8614 2.5
8615 SchemaInfo (Object)
8617 Members
8618 name: string
8619 the entity's name, inherited from base. The SchemaInfo is al‐
8620 ways referenced by this name. Commands and events have the name
8621 defined in the QAPI schema. Unlike command and event names,
8622 type names are not part of the wire ABI. Consequently, type
8623 names are meaningless strings here, although they are still
8624 guaranteed unique regardless of meta-type.
8625 meta-type: SchemaMetaType
8627 the entity's meta type, inherited from base.
8628 features: array of string (optional)
8630 names of features associated with the entity, in no particular
8631 order. (since 4.1 for object types, 4.2 for commands, 5.0 for
8632 the rest)
8633 The members of SchemaInfoBuiltin when meta-type is "builtin"
8635 The members of SchemaInfoEnum when meta-type is "enum"
8637 The members of SchemaInfoArray when meta-type is "array"
8639 The members of SchemaInfoObject when meta-type is "object"
8641 The members of SchemaInfoAlternate when meta-type is "alternate"
8643 The members of SchemaInfoCommand when meta-type is "command"
8645 The members of SchemaInfoEvent when meta-type is "event"
8647 Additional members depend on the value of meta-type.
8648 Since
8650 2.5
8651 SchemaInfoBuiltin (Object)
8653 Additional SchemaInfo members for meta-type 'builtin'.
8654 Members
8656 json-type: JSONType
8657 the JSON type used for this type on the wire.
8658 Since
8660 2.5
8661 JSONType (Enum)
8663 The four primitive and two structured types according to RFC 8259 sec‐
8664 tion 1, plus 'int' (split off 'number'), plus the obvious top type
8665 'value'.
8666 Values
8668 string Not documented
8669 number Not documented
8671 int Not documented
8673 boolean
8675 Not documented
8676 null Not documented
8678 object Not documented
8680 array Not documented
8682 value Not documented
8684 Since
8686 2.5
8687 SchemaInfoEnum (Object)
8689 Additional SchemaInfo members for meta-type 'enum'.
8690 Members
8692 values: array of string
8693 the enumeration type's values, in no particular order.
8694 Values of this type are JSON string on the wire.
8695 Since
8697 2.5
8698 SchemaInfoArray (Object)
8700 Additional SchemaInfo members for meta-type 'array'.
8701 Members
8703 element-type: string
8704 the array type's element type.
8705 Values of this type are JSON array on the wire.
8706 Since
8708 2.5
8709 SchemaInfoObject (Object)
8711 Additional SchemaInfo members for meta-type 'object'.
8712 Members
8714 members: array of SchemaInfoObjectMember
8715 the object type's (non-variant) members, in no particular order.
8716 tag: string (optional)
8718 the name of the member serving as type tag. An element of mem‐
8719 bers with this name must exist.
8720 variants: array of SchemaInfoObjectVariant (optional)
8722 variant members, i.e. additional members that depend on the type
8723 tag's value. Present exactly when tag is present. The variants
8724 are in no particular order, and may even differ from the order
8725 of the values of the enum type of the tag.
8726 Values of this type are JSON object on the wire.
8727 Since
8729 2.5
8730 SchemaInfoObjectMember (Object)
8732 An object member.
8733 Members
8735 name: string
8736 the member's name, as defined in the QAPI schema.
8737 type: string
8739 the name of the member's type.
8740 default: value (optional)
8742 default when used as command parameter. If absent, the parame‐
8743 ter is mandatory. If present, the value must be null. The pa‐
8744 rameter is optional, and behavior when it's missing is not spec‐
8745 ified here. Future extension: if present and non-null, the pa‐
8746 rameter is optional, and defaults to this value.
8747 features: array of string (optional)
8749 names of features associated with the member, in no particular
8750 order. (since 5.0)
8751 Since
8753 2.5
8754 SchemaInfoObjectVariant (Object)
8756 The variant members for a value of the type tag.
8757 Members
8759 case: string
8760 a value of the type tag.
8761 type: string
8763 the name of the object type that provides the variant members
8764 when the type tag has value case.
8765 Since
8767 2.5
8768 SchemaInfoAlternate (Object)
8770 Additional SchemaInfo members for meta-type 'alternate'.
8771 Members
8773 members: array of SchemaInfoAlternateMember
8774 the alternate type's members, in no particular order. The mem‐
8775 bers' wire encoding is distinct, see docs/de‐
8776 vel/qapi-code-gen.txt section Alternate types.
8777 On the wire, this can be any of the members.
8778 Since
8780 2.5
8781 SchemaInfoAlternateMember (Object)
8783 An alternate member.
8784 Members
8786 type: string
8787 the name of the member's type.
8788 Since
8790 2.5
8791 SchemaInfoCommand (Object)
8793 Additional SchemaInfo members for meta-type 'command'.
8794 Members
8796 arg-type: string
8797 the name of the object type that provides the command's parame‐
8798 ters.
8799 ret-type: string
8801 the name of the command's result type.
8802 allow-oob: boolean (optional)
8804 whether the command allows out-of-band execution, defaults to
8805 false (Since: 2.12)
8806 TODO
8808 success-response (currently irrelevant, because it's QGA, not QMP)
8809 Since
8811 2.5
8812 SchemaInfoEvent (Object)
8814 Additional SchemaInfo members for meta-type 'event'.
8815 Members
8817 arg-type: string
8818 the name of the object type that provides the event's parame‐
8819 ters.
8820 Since
8822 2.5
8823
8825 QAuthZListPolicy (Enum)
8826 The authorization policy result
8827 Values
8829 deny deny access
8830 allow allow access
8832 Since
8834 4.0
8835 QAuthZListFormat (Enum)
8837 The authorization policy match format
8838 Values
8840 exact an exact string match
8841 glob string with ? and * shell wildcard support
8843 Since
8845 4.0
8846 QAuthZListRule (Object)
8848 A single authorization rule.
8849 Members
8851 match: string
8852 a string or glob to match against a user identity
8853 policy: QAuthZListPolicy
8855 the result to return if match evaluates to true
8856 format: QAuthZListFormat (optional)
8858 the format of the match rule (default 'exact')
8859 Since
8861 4.0
8862 AuthZListProperties (Object)
8864 Properties for authz-list objects.
8865 Members
8867 policy: QAuthZListPolicy (optional)
8868 Default policy to apply when no rule matches (default: deny)
8869 rules: array of QAuthZListRule (optional)
8871 Authorization rules based on matching user
8872 Since
8874 4.0
8875 AuthZListFileProperties (Object)
8877 Properties for authz-listfile objects.
8878 Members
8880 filename: string
8881 File name to load the configuration from. The file must contain
8882 valid JSON for AuthZListProperties.
8883 refresh: boolean (optional)
8885 If true, inotify is used to monitor the file, automatically
8886 reloading changes. If an error occurs during reloading, all au‐
8887 thorizations will fail until the file is next successfully
8888 loaded. (default: true if the binary was built with CONFIG_INO‐
8889 TIFY1, false otherwise)
8890 Since
8892 4.0
8893 AuthZPAMProperties (Object)
8895 Properties for authz-pam objects.
8896 Members
8898 service: string
8899 PAM service name to use for authorization
8900 Since
8902 4.0
8903 AuthZSimpleProperties (Object)
8905 Properties for authz-simple objects.
8906 Members
8908 identity: string
8909 Identifies the allowed user. Its format depends on the network
8910 service that authorization object is associated with. For autho‐
8911 rizing based on TLS x509 certificates, the identity must be the
8912 x509 distinguished name.
8913 Since
8915 4.0
8916
8918 ObjectPropertyInfo (Object)
8919 Members
8920 name: string
8921 the name of the property
8922 type: string
8924 the type of the property. This will typically come in one of
8925 four forms:
8926 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
8928 ble'. These types are mapped to the appropriate JSON type.
8929 2. A child type in the form 'child<subtype>' where subtype is a
8931 qdev device type name. Child properties create the composi‐
8932 tion tree.
8933 3. A link type in the form 'link<subtype>' where subtype is a
8935 qdev device type name. Link properties form the device model
8936 graph.
8937 description: string (optional)
8939 if specified, the description of the property.
8940 default-value: value (optional)
8942 the default value, if any (since 5.0)
8943 Since
8945 1.2
8946 qom-list (Command)
8948 This command will list any properties of a object given a path in the
8949 object model.
8950 Arguments
8952 path: string
8953 the path within the object model. See qom-get for a description
8954 of this parameter.
8955 Returns
8957 a list of ObjectPropertyInfo that describe the properties of the ob‐
8958 ject.
8959 Since
8961 1.2
8962 Example
8964 -> { "execute": "qom-list",
8965 "arguments": { "path": "/chardevs" } }
8966 <- { "return": [ { "name": "type", "type": "string" },
8967 { "name": "parallel0", "type": "child<chardev-vc>" },
8968 { "name": "serial0", "type": "child<chardev-vc>" },
8969 { "name": "mon0", "type": "child<chardev-stdio>" } ] }
8970 qom-get (Command)
8972 This command will get a property from a object model path and return
8973 the value.
8974 Arguments
8976 path: string
8977 The path within the object model. There are two forms of sup‐
8978 ported paths--absolute and partial paths.
8979 Absolute paths are derived from the root object and can follow
8981 child<> or link<> properties. Since they can follow link<>
8982 properties, they can be arbitrarily long. Absolute paths look
8983 like absolute filenames and are prefixed with a leading slash.
8984 Partial paths look like relative filenames. They do not begin
8986 with a prefix. The matching rules for partial paths are subtle
8987 but designed to make specifying objects easy. At each level of
8988 the composition tree, the partial path is matched as an absolute
8989 path. The first match is not returned. At least two matches
8990 are searched for. A successful result is only returned if only
8991 one match is found. If more than one match is found, a flag is
8992 return to indicate that the match was ambiguous.
8993 property: string
8995 The property name to read
8996 Returns
8998 The property value. The type depends on the property type. child<> and
8999 link<> properties are returned as #str pathnames. All integer property
9000 types (u8, u16, etc) are returned as #int.
9001 Since
9003 1.2
9004 Example
9006 1. Use absolute path
9007 -> { "execute": "qom-get",
9009 "arguments": { "path": "/machine/unattached/device[0]",
9010 "property": "hotplugged" } }
9011 <- { "return": false }
9012 2. Use partial path
9014 -> { "execute": "qom-get",
9016 "arguments": { "path": "unattached/sysbus",
9017 "property": "type" } }
9018 <- { "return": "System" }
9019 qom-set (Command)
9021 This command will set a property from a object model path.
9022 Arguments
9024 path: string
9025 see qom-get for a description of this parameter
9026 property: string
9028 the property name to set
9029 value: value
9031 a value who's type is appropriate for the property type. See
9032 qom-get for a description of type mapping.
9033 Since
9035 1.2
9036 Example
9038 -> { "execute": "qom-set",
9039 "arguments": { "path": "/machine",
9040 "property": "graphics",
9041 "value": false } }
9042 <- { "return": {} }
9043 ObjectTypeInfo (Object)
9045 This structure describes a search result from qom-list-types
9046 Members
9048 name: string
9049 the type name found in the search
9050 abstract: boolean (optional)
9052 the type is abstract and can't be directly instantiated. Omit‐
9053 ted if false. (since 2.10)
9054 parent: string (optional)
9056 Name of parent type, if any (since 2.10)
9057 Since
9059 1.1
9060 qom-list-types (Command)
9062 This command will return a list of types given search parameters
9063 Arguments
9065 implements: string (optional)
9066 if specified, only return types that implement this type name
9067 abstract: boolean (optional)
9069 if true, include abstract types in the results
9070 Returns
9072 a list of ObjectTypeInfo or an empty list if no results are found
9073 Since
9075 1.1
9076 qom-list-properties (Command)
9078 List properties associated with a QOM object.
9079 Arguments
9081 typename: string
9082 the type name of an object
9083 Note
9085 objects can create properties at runtime, for example to describe links
9086 between different devices and/or objects. These properties are not in‐
9087 cluded in the output of this command.
9088 Returns
9090 a list of ObjectPropertyInfo describing object properties
9091 Since
9093 2.12
9094 CanHostSocketcanProperties (Object)
9096 Properties for can-host-socketcan objects.
9097 Members
9099 if: string
9100 interface name of the host system CAN bus to connect to
9101 canbus: string
9103 object ID of the can-bus object to connect to the host interface
9104 Since
9106 2.12
9107 ColoCompareProperties (Object)
9109 Properties for colo-compare objects.
9110 Members
9112 primary_in: string
9113 name of the character device backend to use for the primary in‐
9114 put (incoming packets are redirected to outdev)
9115 secondary_in: string
9117 name of the character device backend to use for secondary input
9118 (incoming packets are only compared to the input on primary_in
9119 and then dropped)
9120 outdev: string
9122 name of the character device backend to use for output
9123 iothread: string
9125 name of the iothread to run in
9126 notify_dev: string (optional)
9128 name of the character device backend to be used to communicate
9129 with the remote colo-frame (only for Xen COLO)
9130 compare_timeout: int (optional)
9132 the maximum time to hold a packet from primary_in for comparison
9133 with an incoming packet on secondary_in in milliseconds (de‐
9134 fault: 3000)
9135 expired_scan_cycle: int (optional)
9137 the interval at which colo-compare checks whether packets from
9138 primary have timed out, in milliseconds (default: 3000)
9139 max_queue_size: int (optional)
9141 the maximum number of packets to keep in the queue for comparing
9142 with incoming packets from secondary_in. If the queue is full
9143 and additional packets are received, the additional packets are
9144 dropped. (default: 1024)
9145 vnet_hdr_support: boolean (optional)
9147 if true, vnet header support is enabled (default: false)
9148 Since
9150 2.8
9151 CryptodevBackendProperties (Object)
9153 Properties for cryptodev-backend and cryptodev-backend-builtin objects.
9154 Members
9156 queues: int (optional)
9157 the number of queues for the cryptodev backend. Ignored for
9158 cryptodev-backend and must be 1 for cryptodev-backend-builtin.
9159 (default: 1)
9160 Since
9162 2.8
9163 CryptodevVhostUserProperties (Object)
9165 Properties for cryptodev-vhost-user objects.
9166 Members
9168 chardev: string
9169 the name of a Unix domain socket character device that connects
9170 to the vhost-user server
9171 The members of CryptodevBackendProperties
9173 Since
9175 2.12
9176 DBusVMStateProperties (Object)
9178 Properties for dbus-vmstate objects.
9179 Members
9181 addr: string
9182 the name of the DBus bus to connect to
9183 id-list: string (optional)
9185 a comma separated list of DBus IDs of helpers whose data should
9186 be included in the VM state on migration
9187 Since
9189 5.0
9190 NetfilterInsert (Enum)
9192 Indicates where to insert a netfilter relative to a given other filter.
9193 Values
9195 before insert before the specified filter
9196 behind insert behind the specified filter
9198 Since
9200 5.0
9201 NetfilterProperties (Object)
9203 Properties for objects of classes derived from netfilter.
9204 Members
9206 netdev: string
9207 id of the network device backend to filter
9208 queue: NetFilterDirection (optional)
9210 indicates which queue(s) to filter (default: all)
9211 status: string (optional)
9213 indicates whether the filter is enabled ("on") or disabled
9214 ("off") (default: "on")
9215 position: string (optional)
9217 specifies where the filter should be inserted in the filter
9218 list. "head" means the filter is inserted at the head of the
9219 filter list, before any existing filters. "tail" means the fil‐
9220 ter is inserted at the tail of the filter list, behind any ex‐
9221 isting filters (default). "id=<id>" means the filter is in‐
9222 serted before or behind the filter specified by <id>, depending
9223 on the insert property. (default: "tail")
9224 insert: NetfilterInsert (optional)
9226 where to insert the filter relative to the filter given in posi‐
9227 tion. Ignored if position is "head" or "tail". (default: be‐
9228 hind)
9229 Since
9231 2.5
9232 FilterBufferProperties (Object)
9234 Properties for filter-buffer objects.
9235 Members
9237 interval: int
9238 a non-zero interval in microseconds. All packets arriving in
9239 the given interval are delayed until the end of the interval.
9240 The members of NetfilterProperties
9242 Since
9244 2.5
9245 FilterDumpProperties (Object)
9247 Properties for filter-dump objects.
9248 Members
9250 file: string
9251 the filename where the dumped packets should be stored
9252 maxlen: int (optional)
9254 maximum number of bytes in a packet that are stored (default:
9255 65536)
9256 The members of NetfilterProperties
9258 Since
9260 2.5
9261 FilterMirrorProperties (Object)
9263 Properties for filter-mirror objects.
9264 Members
9266 outdev: string
9267 the name of a character device backend to which all incoming
9268 packets are mirrored
9269 vnet_hdr_support: boolean (optional)
9271 if true, vnet header support is enabled (default: false)
9272 The members of NetfilterProperties
9274 Since
9276 2.6
9277 FilterRedirectorProperties (Object)
9279 Properties for filter-redirector objects.
9280 At least one of indev or outdev must be present. If both are present,
9282 they must not refer to the same character device backend.
9283 Members
9285 indev: string (optional)
9286 the name of a character device backend from which packets are
9287 received and redirected to the filtered network device
9288 outdev: string (optional)
9290 the name of a character device backend to which all incoming
9291 packets are redirected
9292 vnet_hdr_support: boolean (optional)
9294 if true, vnet header support is enabled (default: false)
9295 The members of NetfilterProperties
9297 Since
9299 2.6
9300 FilterRewriterProperties (Object)
9302 Properties for filter-rewriter objects.
9303 Members
9305 vnet_hdr_support: boolean (optional)
9306 if true, vnet header support is enabled (default: false)
9307 The members of NetfilterProperties
9309 Since
9311 2.8
9312 InputBarrierProperties (Object)
9314 Properties for input-barrier objects.
9315 Members
9317 name: string
9318 the screen name as declared in the screens section of bar‐
9319 rier.conf
9320 server: string (optional)
9322 hostname of the Barrier server (default: "localhost")
9323 port: string (optional)
9325 TCP port of the Barrier server (default: "24800")
9326 x-origin: string (optional)
9328 x coordinate of the leftmost pixel on the guest screen (default:
9329 "0")
9330 y-origin: string (optional)
9332 y coordinate of the topmost pixel on the guest screen (default:
9333 "0")
9334 width: string (optional)
9336 the width of secondary screen in pixels (default: "1920")
9337 height: string (optional)
9339 the height of secondary screen in pixels (default: "1080")
9340 Since
9342 4.2
9343 InputLinuxProperties (Object)
9345 Properties for input-linux objects.
9346 Members
9348 evdev: string
9349 the path of the host evdev device to use
9350 grab_all: boolean (optional)
9352 if true, grab is toggled for all devices (e.g. both keyboard and
9353 mouse) instead of just one device (default: false)
9354 repeat: boolean (optional)
9356 enables auto-repeat events (default: false)
9357 grab-toggle: GrabToggleKeys (optional)
9359 the key or key combination that toggles device grab (default:
9360 ctrl-ctrl)
9361 Since
9363 2.6
9364 IothreadProperties (Object)
9366 Properties for iothread objects.
9367 Members
9369 poll-max-ns: int (optional)
9370 the maximum number of nanoseconds to busy wait for events. 0
9371 means polling is disabled (default: 32768 on POSIX hosts, 0 oth‐
9372 erwise)
9373 poll-grow: int (optional)
9375 the multiplier used to increase the polling time when the algo‐
9376 rithm detects it is missing events due to not polling long
9377 enough. 0 selects a default behaviour (default: 0)
9378 poll-shrink: int (optional)
9380 the divisor used to decrease the polling time when the algorithm
9381 detects it is spending too long polling without encountering
9382 events. 0 selects a default behaviour (default: 0)
9383 aio-max-batch: int (optional)
9385 maximum number of requests in a batch for the AIO engine, 0
9386 means that the engine will use its default (default:0, since
9387 6.1)
9388 Since
9390 2.0
9391 MemoryBackendProperties (Object)
9393 Properties for objects of classes derived from memory-backend.
9394 Members
9396 merge: boolean (optional)
9397 if true, mark the memory as mergeable (default depends on the
9398 machine type)
9399 dump: boolean (optional)
9401 if true, include the memory in core dumps (default depends on
9402 the machine type)
9403 host-nodes: array of int (optional)
9405 the list of NUMA host nodes to bind the memory to
9406 policy: HostMemPolicy (optional)
9408 the NUMA policy (default: 'default')
9409 prealloc: boolean (optional)
9411 if true, preallocate memory (default: false)
9412 prealloc-threads: int (optional)
9414 number of CPU threads to use for prealloc (default: 1)
9415 share: boolean (optional)
9417 if false, the memory is private to QEMU; if true, it is shared
9418 (default: false)
9419 reserve: boolean (optional)
9421 if true, reserve swap space (or huge pages) if applicable (de‐
9422 fault: true) (since 6.1)
9423 size: int
9425 size of the memory region in bytes
9426 x-use-canonical-path-for-ramblock-id: boolean (optional)
9428 if true, the canoncial path is used for ramblock-id. Disable
9429 this for 4.0 machine types or older to allow migration with
9430 newer QEMU versions. This option is considered stable despite
9431 the x- prefix. (default: false generally, but true for machine
9432 types <= 4.0)
9433 Note
9435 prealloc=true and reserve=false cannot be set at the same time. With
9436 reserve=true, the behavior depends on the operating system: for exam‐
9437 ple, Linux will not reserve swap space for shared file mappings -- "not
9438 applicable". In contrast, reserve=false will bail out if it cannot be
9439 configured accordingly.
9440 Since
9442 2.1
9443 MemoryBackendFileProperties (Object)
9445 Properties for memory-backend-file objects.
9446 Members
9448 align: int (optional)
9449 the base address alignment when QEMU mmap(2)s mem-path. Some
9450 backend stores specified by mem-path require an alignment dif‐
9451 ferent than the default one used by QEMU, e.g. the device DAX
9452 /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
9453 users can specify the required alignment via this option. 0 se‐
9454 lects a default alignment (currently the page size). (default:
9455 0)
9456 discard-data: boolean (optional)
9458 if true, the file contents can be destroyed when QEMU exits, to
9459 avoid unnecessarily flushing data to the backing file. Note that
9460 discard-data is only an optimization, and QEMU might not discard
9461 file contents if it aborts unexpectedly or is terminated using
9462 SIGKILL. (default: false)
9463 mem-path: string
9465 the path to either a shared memory or huge page filesystem mount
9466 pmem: boolean (optional) (If: defined(CONFIG_LIBPMEM))
9468 specifies whether the backing file specified by mem-path is in
9469 host persistent memory that can be accessed using the SNIA NVM
9470 programming model (e.g. Intel NVDIMM).
9471 readonly: boolean (optional)
9473 if true, the backing file is opened read-only; if false, it is
9474 opened read-write. (default: false)
9475 The members of MemoryBackendProperties
9477 Since
9479 2.1
9480 MemoryBackendMemfdProperties (Object)
9482 Properties for memory-backend-memfd objects.
9483 The share boolean option is true by default with memfd.
9485 Members
9487 hugetlb: boolean (optional)
9488 if true, the file to be created resides in the hugetlbfs
9489 filesystem (default: false)
9490 hugetlbsize: int (optional)
9492 the hugetlb page size on systems that support multiple hugetlb
9493 page sizes (it must be a power of 2 value supported by the sys‐
9494 tem). 0 selects a default page size. This option is ignored if
9495 hugetlb is false. (default: 0)
9496 seal: boolean (optional)
9498 if true, create a sealed-file, which will block further resizing
9499 of the memory (default: true)
9500 The members of MemoryBackendProperties
9502 Since
9504 2.12
9505 PrManagerHelperProperties (Object)
9507 Properties for pr-manager-helper objects.
9508 Members
9510 path: string
9511 the path to a Unix domain socket for connecting to the external
9512 helper
9513 Since
9515 2.11
9516 QtestProperties (Object)
9518 Properties for qtest objects.
9519 Members
9521 chardev: string
9522 the chardev to be used to receive qtest commands on.
9523 log: string (optional)
9525 the path to a log file
9526 Since
9528 6.0
9529 RemoteObjectProperties (Object)
9531 Properties for x-remote-object objects.
9532 Members
9534 fd: string
9535 file descriptor name previously passed via 'getfd' command
9536 devid: string
9538 the id of the device to be associated with the file descriptor
9539 Since
9541 6.0
9542 RngProperties (Object)
9544 Properties for objects of classes derived from rng.
9545 Members
9547 opened: boolean (optional)
9548 if true, the device is opened immediately when applying this op‐
9549 tion and will probably fail when processing the next option.
9550 Don't use; only provided for compatibility. (default: false)
9551 Features
9553 deprecated
9554 Member opened is deprecated. Setting true doesn't make sense,
9555 and false is already the default.
9556 Since
9558 1.3
9559 RngEgdProperties (Object)
9561 Properties for rng-egd objects.
9562 Members
9564 chardev: string
9565 the name of a character device backend that provides the connec‐
9566 tion to the RNG daemon
9567 The members of RngProperties
9569 Since
9571 1.3
9572 RngRandomProperties (Object)
9574 Properties for rng-random objects.
9575 Members
9577 filename: string (optional)
9578 the filename of the device on the host to obtain entropy from
9579 (default: "/dev/urandom")
9580 The members of RngProperties
9582 Since
9584 1.3
9585 SevGuestProperties (Object)
9587 Properties for sev-guest objects.
9588 Members
9590 sev-device: string (optional)
9591 SEV device to use (default: "/dev/sev")
9592 dh-cert-file: string (optional)
9594 guest owners DH certificate (encoded with base64)
9595 session-file: string (optional)
9597 guest owners session parameters (encoded with base64)
9598 policy: int (optional)
9600 SEV policy value (default: 0x1)
9601 handle: int (optional)
9603 SEV firmware handle (default: 0)
9604 cbitpos: int (optional)
9606 C-bit location in page table entry (default: 0)
9607 reduced-phys-bits: int
9609 number of bits in physical addresses that become unavailable
9610 when SEV is enabled
9611 Since
9613 2.12
9614 ObjectType (Enum)
9616 Values
9617 authz-list
9618 Not documented
9619 authz-listfile
9621 Not documented
9622 authz-pam
9624 Not documented
9625 authz-simple
9627 Not documented
9628 can-bus
9630 Not documented
9631 can-host-socketcan
9633 Not documented
9634 colo-compare
9636 Not documented
9637 cryptodev-backend
9639 Not documented
9640 cryptodev-backend-builtin
9642 Not documented
9643 cryptodev-vhost-user (If: defined(CONFIG_VHOST_CRYPTO))
9645 Not documented
9646 dbus-vmstate
9648 Not documented
9649 filter-buffer
9651 Not documented
9652 filter-dump
9654 Not documented
9655 filter-mirror
9657 Not documented
9658 filter-redirector
9660 Not documented
9661 filter-replay
9663 Not documented
9664 filter-rewriter
9666 Not documented
9667 input-barrier
9669 Not documented
9670 input-linux
9672 Not documented
9673 iothread
9675 Not documented
9676 memory-backend-file
9678 Not documented
9679 memory-backend-memfd (If: defined(CONFIG_LINUX))
9681 Not documented
9682 memory-backend-ram
9684 Not documented
9685 pef-guest
9687 Not documented
9688 pr-manager-helper
9690 Not documented
9691 qtest Not documented
9693 rng-builtin
9695 Not documented
9696 rng-egd
9698 Not documented
9699 rng-random
9701 Not documented
9702 secret Not documented
9704 secret_keyring
9706 Not documented
9707 sev-guest
9709 Not documented
9710 s390-pv-guest
9712 Not documented
9713 throttle-group
9715 Not documented
9716 tls-creds-anon
9718 Not documented
9719 tls-creds-psk
9721 Not documented
9722 tls-creds-x509
9724 Not documented
9725 tls-cipher-suites
9727 Not documented
9728 x-remote-object
9730 Not documented
9731 Since
9733 6.0
9734 ObjectOptions (Object)
9736 Describes the options of a user creatable QOM object.
9737 Members
9739 qom-type: ObjectType
9740 the class name for the object to be created
9741 id: string
9743 the name of the new object
9744 The members of AuthZListProperties when qom-type is "authz-list"
9746 The members of AuthZListFileProperties when qom-type is "authz-list‐
9748 file"
9749 The members of AuthZPAMProperties when qom-type is "authz-pam"
9751 The members of AuthZSimpleProperties when qom-type is "authz-simple"
9753 The members of CanHostSocketcanProperties when qom-type is
9755 "can-host-socketcan"
9756 The members of ColoCompareProperties when qom-type is "colo-compare"
9758 The members of CryptodevBackendProperties when qom-type is "cryp‐
9760 todev-backend"
9761 The members of CryptodevBackendProperties when qom-type is "cryp‐
9763 todev-backend-builtin"
9764 The members of CryptodevVhostUserProperties when qom-type is "cryp‐
9766 todev-vhost-user" (If: defined(CONFIG_VHOST_CRYPTO))
9767 The members of DBusVMStateProperties when qom-type is "dbus-vmstate"
9769 The members of FilterBufferProperties when qom-type is "filter-buffer"
9771 The members of FilterDumpProperties when qom-type is "filter-dump"
9773 The members of FilterMirrorProperties when qom-type is "filter-mirror"
9775 The members of FilterRedirectorProperties when qom-type is "fil‐
9777 ter-redirector"
9778 The members of NetfilterProperties when qom-type is "filter-replay"
9780 The members of FilterRewriterProperties when qom-type is "fil‐
9782 ter-rewriter"
9783 The members of InputBarrierProperties when qom-type is "input-barrier"
9785 The members of InputLinuxProperties when qom-type is "input-linux"
9787 The members of IothreadProperties when qom-type is "iothread"
9789 The members of MemoryBackendFileProperties when qom-type is "mem‐
9791 ory-backend-file"
9792 The members of MemoryBackendMemfdProperties when qom-type is "mem‐
9794 ory-backend-memfd" (If: defined(CONFIG_LINUX))
9795 The members of MemoryBackendProperties when qom-type is "memory-back‐
9797 end-ram"
9798 The members of PrManagerHelperProperties when qom-type is "pr-man‐
9800 ager-helper"
9801 The members of QtestProperties when qom-type is "qtest"
9803 The members of RngProperties when qom-type is "rng-builtin"
9805 The members of RngEgdProperties when qom-type is "rng-egd"
9807 The members of RngRandomProperties when qom-type is "rng-random"
9809 The members of SecretProperties when qom-type is "secret"
9811 The members of SecretKeyringProperties when qom-type is "se‐
9813 cret_keyring"
9814 The members of SevGuestProperties when qom-type is "sev-guest"
9816 The members of ThrottleGroupProperties when qom-type is "throt‐
9818 tle-group"
9819 The members of TlsCredsAnonProperties when qom-type is "tls-creds-anon"
9821 The members of TlsCredsPskProperties when qom-type is "tls-creds-psk"
9823 The members of TlsCredsX509Properties when qom-type is "tls-creds-x509"
9825 The members of TlsCredsProperties when qom-type is "tls-cipher-suites"
9827 The members of RemoteObjectProperties when qom-type is "x-remote-ob‐
9829 ject"
9830 Since
9832 6.0
9833 object-add (Command)
9835 Create a QOM object.
9836 Arguments
9838 The members of ObjectOptions
9839 Returns
9841 Nothing on success Error if qom-type is not a valid class name
9842 Since
9844 2.0
9845 Example
9847 -> { "execute": "object-add",
9848 "arguments": { "qom-type": "rng-random", "id": "rng1",
9849 "filename": "/dev/hwrng" } }
9850 <- { "return": {} }
9851 object-del (Command)
9853 Remove a QOM object.
9854 Arguments
9856 id: string
9857 the name of the QOM object to remove
9858 Returns
9860 Nothing on success Error if id is not a valid id for a QOM object
9861 Since
9863 2.0
9864 Example
9866 -> { "execute": "object-del", "arguments": { "id": "rng1" } }
9867 <- { "return": {} }
9868
9870 Abort (Object)
9871 This action can be used to test transaction failure.
9872 Since
9874 1.6
9875 ActionCompletionMode (Enum)
9877 An enumeration of Transactional completion modes.
9878 Values
9880 individual
9881 Do not attempt to cancel any other Actions if any Actions fail
9882 after the Transaction request succeeds. All Actions that can
9883 complete successfully will do so without waiting on others.
9884 This is the default.
9885 grouped
9887 If any Action fails after the Transaction succeeds, cancel all
9888 Actions. Actions do not complete until all Actions are ready to
9889 complete. May be rejected by Actions that do not support this
9890 completion mode.
9891 Since
9893 2.5
9894 TransactionAction (Object)
9896 A discriminated record of operations that can be performed with trans‐
9897 action. Action type can be:
9898 • abort: since 1.6
9900 • block-dirty-bitmap-add: since 2.5
9902 • block-dirty-bitmap-remove: since 4.2
9904 • block-dirty-bitmap-clear: since 2.5
9906 • block-dirty-bitmap-enable: since 4.0
9908 • block-dirty-bitmap-disable: since 4.0
9910 • block-dirty-bitmap-merge: since 4.0
9912 • blockdev-backup: since 2.3
9914 • blockdev-snapshot: since 2.5
9916 • blockdev-snapshot-internal-sync: since 1.7
9918 • blockdev-snapshot-sync: since 1.1
9920 • drive-backup: since 1.6
9922 Members
9924 type One of abort, block-dirty-bitmap-add, block-dirty-bitmap-remove,
9925 block-dirty-bitmap-clear, block-dirty-bitmap-enable,
9926 block-dirty-bitmap-disable, block-dirty-bitmap-merge, block‐
9927 dev-backup, blockdev-snapshot, blockdev-snapshot-internal-sync,
9928 blockdev-snapshot-sync, drive-backup
9929 data: Abort when type is "abort"
9931 data: BlockDirtyBitmapAdd when type is "block-dirty-bitmap-add"
9933 data: BlockDirtyBitmap when type is "block-dirty-bitmap-remove"
9935 data: BlockDirtyBitmap when type is "block-dirty-bitmap-clear"
9937 data: BlockDirtyBitmap when type is "block-dirty-bitmap-enable"
9939 data: BlockDirtyBitmap when type is "block-dirty-bitmap-disable"
9941 data: BlockDirtyBitmapMerge when type is "block-dirty-bitmap-merge"
9943 data: BlockdevBackup when type is "blockdev-backup"
9945 data: BlockdevSnapshot when type is "blockdev-snapshot"
9947 data: BlockdevSnapshotInternal when type is "blockdev-snapshot-inter‐
9949 nal-sync"
9950 data: BlockdevSnapshotSync when type is "blockdev-snapshot-sync"
9952 data: DriveBackup when type is "drive-backup"
9954 Since
9956 1.1
9957 TransactionProperties (Object)
9959 Optional arguments to modify the behavior of a Transaction.
9960 Members
9962 completion-mode: ActionCompletionMode (optional)
9963 Controls how jobs launched asynchronously by Actions will com‐
9964 plete or fail as a group. See ActionCompletionMode for details.
9965 Since
9967 2.5
9968 transaction (Command)
9970 Executes a number of transactionable QMP commands atomically. If any
9971 operation fails, then the entire set of actions will be abandoned and
9972 the appropriate error returned.
9973 For external snapshots, the dictionary contains the device, the file to
9975 use for the new snapshot, and the format. The default format, if not
9976 specified, is qcow2.
9977 Each new snapshot defaults to being created by QEMU (wiping any con‐
9979 tents if the file already exists), but it is also possible to reuse an
9980 externally-created file. In the latter case, you should ensure that
9981 the new image file has the same contents as the current one; QEMU can‐
9982 not perform any meaningful check. Typically this is achieved by using
9983 the current image file as the backing file for the new image.
9984 On failure, the original disks pre-snapshot attempt will be used.
9986 For internal snapshots, the dictionary contains the device and the
9988 snapshot's name. If an internal snapshot matching name already exists,
9989 the request will be rejected. Only some image formats support it, for
9990 example, qcow2, and rbd,
9991 On failure, qemu will try delete the newly created internal snapshot in
9993 the transaction. When an I/O error occurs during deletion, the user
9994 needs to fix it later with qemu-img or other command.
9995 Arguments
9997 actions: array of TransactionAction
9998 List of TransactionAction; information needed for the respective
9999 operations.
10000 properties: TransactionProperties (optional)
10002 structure of additional options to control the execution of the
10003 transaction. See TransactionProperties for additional detail.
10004 Returns
10006 nothing on success
10007 Errors depend on the operations of the transaction
10009 Note
10011 The transaction aborts on the first failure. Therefore, there will be
10012 information on only one failed operation returned in an error condi‐
10013 tion, and subsequent actions will not have been attempted.
10014 Since
10016 1.1
10017 Example
10019 -> { "execute": "transaction",
10020 "arguments": { "actions": [
10021 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
10022 "snapshot-file": "/some/place/my-image",
10023 "format": "qcow2" } },
10024 { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
10025 "snapshot-file": "/some/place/my-image2",
10026 "snapshot-node-name": "node3432",
10027 "mode": "existing",
10028 "format": "qcow2" } },
10029 { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
10030 "snapshot-file": "/some/place/my-image2",
10031 "mode": "existing",
10032 "format": "qcow2" } },
10033 { "type": "blockdev-snapshot-internal-sync", "data" : {
10034 "device": "ide-hd2",
10035 "name": "snapshot0" } } ] } }
10036 <- { "return": {} }
10037
10039 2021, The QEMU Project Developers
100406.1.0 Nov 08, 2021 QEMU-STORAGE-DAEMON-QMP-REF(7)