1QEMU-STORAGE-DAEMON-QMP-REF(7) QEMU QEMU-STORAGE-DAEMON-QMP-REF(7)
2
3
4
6 qemu-storage-daemon-qmp-ref - QEMU Storage Daemon QMP Reference Manual
7
8 Contents
9 • QEMU Storage Daemon QMP Reference Manual
10
11 • Block devices
12
13 • Block core (VM unrelated)
14
15 • Common data types
16
17 • IoOperationType (Enum)
18
19 • OnOffAuto (Enum)
20
21 • OnOffSplit (Enum)
22
23 • String (Object)
24
25 • StrOrNull (Alternate)
26
27 • OffAutoPCIBAR (Enum)
28
29 • PCIELinkSpeed (Enum)
30
31 • PCIELinkWidth (Enum)
32
33 • HostMemPolicy (Enum)
34
35 • NetFilterDirection (Enum)
36
37 • GrabToggleKeys (Enum)
38
39 • Cryptography
40
41 • QCryptoTLSCredsEndpoint (Enum)
42
43 • QCryptoSecretFormat (Enum)
44
45 • QCryptoHashAlgorithm (Enum)
46
47 • QCryptoCipherAlgorithm (Enum)
48
49 • QCryptoCipherMode (Enum)
50
51 • QCryptoIVGenAlgorithm (Enum)
52
53 • QCryptoBlockFormat (Enum)
54
55 • QCryptoBlockOptionsBase (Object)
56
57 • QCryptoBlockOptionsQCow (Object)
58
59 • QCryptoBlockOptionsLUKS (Object)
60
61 • QCryptoBlockCreateOptionsLUKS (Object)
62
63 • QCryptoBlockOpenOptions (Object)
64
65 • QCryptoBlockCreateOptions (Object)
66
67 • QCryptoBlockInfoBase (Object)
68
69 • QCryptoBlockInfoLUKSSlot (Object)
70
71 • QCryptoBlockInfoLUKS (Object)
72
73 • QCryptoBlockInfo (Object)
74
75 • QCryptoBlockLUKSKeyslotState (Enum)
76
77 • QCryptoBlockAmendOptionsLUKS (Object)
78
79 • QCryptoBlockAmendOptions (Object)
80
81 • SecretCommonProperties (Object)
82
83 • SecretProperties (Object)
84
85 • SecretKeyringProperties (Object)
86
87 • TlsCredsProperties (Object)
88
89 • TlsCredsAnonProperties (Object)
90
91 • TlsCredsPskProperties (Object)
92
93 • TlsCredsX509Properties (Object)
94
95 • Background jobs
96
97 • Socket data types
98
99 • NetworkAddressFamily (Enum)
100
101 • InetSocketAddressBase (Object)
102
103 • InetSocketAddress (Object)
104
105 • UnixSocketAddress (Object)
106
107 • VsockSocketAddress (Object)
108
109 • SocketAddressLegacy (Object)
110
111 • SocketAddressType (Enum)
112
113 • SocketAddress (Object)
114
115 • SnapshotInfo (Object)
116
117 • ImageInfoSpecificQCow2EncryptionBase (Object)
118
119 • ImageInfoSpecificQCow2Encryption (Object)
120
121 • ImageInfoSpecificQCow2 (Object)
122
123 • ImageInfoSpecificVmdk (Object)
124
125 • ImageInfoSpecificRbd (Object)
126
127 • ImageInfoSpecific (Object)
128
129 • ImageInfo (Object)
130
131 • ImageCheck (Object)
132
133 • MapEntry (Object)
134
135 • BlockdevCacheInfo (Object)
136
137 • BlockDeviceInfo (Object)
138
139 • BlockDeviceIoStatus (Enum)
140
141 • BlockDirtyInfo (Object)
142
143 • Qcow2BitmapInfoFlags (Enum)
144
145 • Qcow2BitmapInfo (Object)
146
147 • BlockLatencyHistogramInfo (Object)
148
149 • BlockInfo (Object)
150
151 • BlockMeasureInfo (Object)
152
153 • query-block (Command)
154
155 • BlockDeviceTimedStats (Object)
156
157 • BlockDeviceStats (Object)
158
159 • BlockStatsSpecificFile (Object)
160
161 • BlockStatsSpecificNvme (Object)
162
163 • BlockStatsSpecific (Object)
164
165 • BlockStats (Object)
166
167 • query-blockstats (Command)
168
169 • BlockdevOnError (Enum)
170
171 • MirrorSyncMode (Enum)
172
173 • BitmapSyncMode (Enum)
174
175 • MirrorCopyMode (Enum)
176
177 • BlockJobInfo (Object)
178
179 • query-block-jobs (Command)
180
181 • block_resize (Command)
182
183 • NewImageMode (Enum)
184
185 • BlockdevSnapshotSync (Object)
186
187 • BlockdevSnapshot (Object)
188
189 • BackupPerf (Object)
190
191 • BackupCommon (Object)
192
193 • DriveBackup (Object)
194
195 • BlockdevBackup (Object)
196
197 • blockdev-snapshot-sync (Command)
198
199 • blockdev-snapshot (Command)
200
201 • change-backing-file (Command)
202
203 • block-commit (Command)
204
205 • drive-backup (Command)
206
207 • blockdev-backup (Command)
208
209 • query-named-block-nodes (Command)
210
211 • XDbgBlockGraphNodeType (Enum)
212
213 • XDbgBlockGraphNode (Object)
214
215 • BlockPermission (Enum)
216
217 • XDbgBlockGraphEdge (Object)
218
219 • XDbgBlockGraph (Object)
220
221 • x-debug-query-block-graph (Command)
222
223 • drive-mirror (Command)
224
225 • DriveMirror (Object)
226
227 • BlockDirtyBitmap (Object)
228
229 • BlockDirtyBitmapAdd (Object)
230
231 • BlockDirtyBitmapMergeSource (Alternate)
232
233 • BlockDirtyBitmapMerge (Object)
234
235 • block-dirty-bitmap-add (Command)
236
237 • block-dirty-bitmap-remove (Command)
238
239 • block-dirty-bitmap-clear (Command)
240
241 • block-dirty-bitmap-enable (Command)
242
243 • block-dirty-bitmap-disable (Command)
244
245 • block-dirty-bitmap-merge (Command)
246
247 • BlockDirtyBitmapSha256 (Object)
248
249 • x-debug-block-dirty-bitmap-sha256 (Command)
250
251 • blockdev-mirror (Command)
252
253 • BlockIOThrottle (Object)
254
255 • ThrottleLimits (Object)
256
257 • ThrottleGroupProperties (Object)
258
259 • block-stream (Command)
260
261 • block-job-set-speed (Command)
262
263 • block-job-cancel (Command)
264
265 • block-job-pause (Command)
266
267 • block-job-resume (Command)
268
269 • block-job-complete (Command)
270
271 • block-job-dismiss (Command)
272
273 • block-job-finalize (Command)
274
275 • BlockdevDiscardOptions (Enum)
276
277 • BlockdevDetectZeroesOptions (Enum)
278
279 • BlockdevAioOptions (Enum)
280
281 • BlockdevCacheOptions (Object)
282
283 • BlockdevDriver (Enum)
284
285 • BlockdevOptionsFile (Object)
286
287 • BlockdevOptionsNull (Object)
288
289 • BlockdevOptionsNVMe (Object)
290
291 • BlockdevOptionsVVFAT (Object)
292
293 • BlockdevOptionsGenericFormat (Object)
294
295 • BlockdevOptionsLUKS (Object)
296
297 • BlockdevOptionsGenericCOWFormat (Object)
298
299 • Qcow2OverlapCheckMode (Enum)
300
301 • Qcow2OverlapCheckFlags (Object)
302
303 • Qcow2OverlapChecks (Alternate)
304
305 • BlockdevQcowEncryptionFormat (Enum)
306
307 • BlockdevQcowEncryption (Object)
308
309 • BlockdevOptionsQcow (Object)
310
311 • BlockdevQcow2EncryptionFormat (Enum)
312
313 • BlockdevQcow2Encryption (Object)
314
315 • BlockdevOptionsPreallocate (Object)
316
317 • BlockdevOptionsQcow2 (Object)
318
319 • SshHostKeyCheckMode (Enum)
320
321 • SshHostKeyCheckHashType (Enum)
322
323 • SshHostKeyHash (Object)
324
325 • SshHostKeyCheck (Object)
326
327 • BlockdevOptionsSsh (Object)
328
329 • BlkdebugEvent (Enum)
330
331 • BlkdebugIOType (Enum)
332
333 • BlkdebugInjectErrorOptions (Object)
334
335 • BlkdebugSetStateOptions (Object)
336
337 • BlockdevOptionsBlkdebug (Object)
338
339 • BlockdevOptionsBlklogwrites (Object)
340
341 • BlockdevOptionsBlkverify (Object)
342
343 • BlockdevOptionsBlkreplay (Object)
344
345 • QuorumReadPattern (Enum)
346
347 • BlockdevOptionsQuorum (Object)
348
349 • BlockdevOptionsGluster (Object)
350
351 • IscsiTransport (Enum)
352
353 • IscsiHeaderDigest (Enum)
354
355 • BlockdevOptionsIscsi (Object)
356
357 • RbdAuthMode (Enum)
358
359 • RbdImageEncryptionFormat (Enum)
360
361 • RbdEncryptionOptionsLUKSBase (Object)
362
363 • RbdEncryptionCreateOptionsLUKSBase (Object)
364
365 • RbdEncryptionOptionsLUKS (Object)
366
367 • RbdEncryptionOptionsLUKS2 (Object)
368
369 • RbdEncryptionCreateOptionsLUKS (Object)
370
371 • RbdEncryptionCreateOptionsLUKS2 (Object)
372
373 • RbdEncryptionOptions (Object)
374
375 • RbdEncryptionCreateOptions (Object)
376
377 • BlockdevOptionsRbd (Object)
378
379 • ReplicationMode (Enum)
380
381 • BlockdevOptionsReplication (Object)
382
383 • NFSTransport (Enum)
384
385 • NFSServer (Object)
386
387 • BlockdevOptionsNfs (Object)
388
389 • BlockdevOptionsCurlBase (Object)
390
391 • BlockdevOptionsCurlHttp (Object)
392
393 • BlockdevOptionsCurlHttps (Object)
394
395 • BlockdevOptionsCurlFtp (Object)
396
397 • BlockdevOptionsCurlFtps (Object)
398
399 • BlockdevOptionsNbd (Object)
400
401 • BlockdevOptionsRaw (Object)
402
403 • BlockdevOptionsThrottle (Object)
404
405 • BlockdevOptionsCor (Object)
406
407 • BlockdevOptions (Object)
408
409 • BlockdevRef (Alternate)
410
411 • BlockdevRefOrNull (Alternate)
412
413 • blockdev-add (Command)
414
415 • blockdev-reopen (Command)
416
417 • blockdev-del (Command)
418
419 • BlockdevCreateOptionsFile (Object)
420
421 • BlockdevCreateOptionsGluster (Object)
422
423 • BlockdevCreateOptionsLUKS (Object)
424
425 • BlockdevCreateOptionsNfs (Object)
426
427 • BlockdevCreateOptionsParallels (Object)
428
429 • BlockdevCreateOptionsQcow (Object)
430
431 • BlockdevQcow2Version (Enum)
432
433 • Qcow2CompressionType (Enum)
434
435 • BlockdevCreateOptionsQcow2 (Object)
436
437 • BlockdevCreateOptionsQed (Object)
438
439 • BlockdevCreateOptionsRbd (Object)
440
441 • BlockdevVmdkSubformat (Enum)
442
443 • BlockdevVmdkAdapterType (Enum)
444
445 • BlockdevCreateOptionsVmdk (Object)
446
447 • BlockdevCreateOptionsSsh (Object)
448
449 • BlockdevCreateOptionsVdi (Object)
450
451 • BlockdevVhdxSubformat (Enum)
452
453 • BlockdevCreateOptionsVhdx (Object)
454
455 • BlockdevVpcSubformat (Enum)
456
457 • BlockdevCreateOptionsVpc (Object)
458
459 • BlockdevCreateOptions (Object)
460
461 • blockdev-create (Command)
462
463 • BlockdevAmendOptionsLUKS (Object)
464
465 • BlockdevAmendOptionsQcow2 (Object)
466
467 • BlockdevAmendOptions (Object)
468
469 • x-blockdev-amend (Command)
470
471 • BlockErrorAction (Enum)
472
473 • BLOCK_IMAGE_CORRUPTED (Event)
474
475 • BLOCK_IO_ERROR (Event)
476
477 • BLOCK_JOB_COMPLETED (Event)
478
479 • BLOCK_JOB_CANCELLED (Event)
480
481 • BLOCK_JOB_ERROR (Event)
482
483 • BLOCK_JOB_READY (Event)
484
485 • BLOCK_JOB_PENDING (Event)
486
487 • PreallocMode (Enum)
488
489 • BLOCK_WRITE_THRESHOLD (Event)
490
491 • block-set-write-threshold (Command)
492
493 • x-blockdev-change (Command)
494
495 • x-blockdev-set-iothread (Command)
496
497 • QuorumOpType (Enum)
498
499 • QUORUM_FAILURE (Event)
500
501 • QUORUM_REPORT_BAD (Event)
502
503 • BlockdevSnapshotInternal (Object)
504
505 • blockdev-snapshot-internal-sync (Command)
506
507 • blockdev-snapshot-delete-internal-sync (Command)
508
509 • Block device exports
510
511 • Character devices
512
513 • ChardevInfo (Object)
514
515 • query-chardev (Command)
516
517 • ChardevBackendInfo (Object)
518
519 • query-chardev-backends (Command)
520
521 • DataFormat (Enum)
522
523 • ringbuf-write (Command)
524
525 • ringbuf-read (Command)
526
527 • ChardevCommon (Object)
528
529 • ChardevFile (Object)
530
531 • ChardevHostdev (Object)
532
533 • ChardevSocket (Object)
534
535 • ChardevUdp (Object)
536
537 • ChardevMux (Object)
538
539 • ChardevStdio (Object)
540
541 • ChardevSpiceChannel (Object)
542
543 • ChardevSpicePort (Object)
544
545 • ChardevVC (Object)
546
547 • ChardevRingbuf (Object)
548
549 • ChardevQemuVDAgent (Object)
550
551 • ChardevBackend (Object)
552
553 • ChardevReturn (Object)
554
555 • chardev-add (Command)
556
557 • chardev-change (Command)
558
559 • chardev-remove (Command)
560
561 • chardev-send-break (Command)
562
563 • VSERPORT_CHANGE (Event)
564
565 • QMP monitor control
566
567 • qmp_capabilities (Command)
568
569 • QMPCapability (Enum)
570
571 • VersionTriple (Object)
572
573 • VersionInfo (Object)
574
575 • query-version (Command)
576
577 • CommandInfo (Object)
578
579 • query-commands (Command)
580
581 • quit (Command)
582
583 • MonitorMode (Enum)
584
585 • MonitorOptions (Object)
586
587 • QMP introspection
588
589 • query-qmp-schema (Command)
590
591 • SchemaMetaType (Enum)
592
593 • SchemaInfo (Object)
594
595 • SchemaInfoBuiltin (Object)
596
597 • JSONType (Enum)
598
599 • SchemaInfoEnum (Object)
600
601 • SchemaInfoArray (Object)
602
603 • SchemaInfoObject (Object)
604
605 • SchemaInfoObjectMember (Object)
606
607 • SchemaInfoObjectVariant (Object)
608
609 • SchemaInfoAlternate (Object)
610
611 • SchemaInfoAlternateMember (Object)
612
613 • SchemaInfoCommand (Object)
614
615 • SchemaInfoEvent (Object)
616
617 • User authorization
618
619 • QAuthZListPolicy (Enum)
620
621 • QAuthZListFormat (Enum)
622
623 • QAuthZListRule (Object)
624
625 • AuthZListProperties (Object)
626
627 • AuthZListFileProperties (Object)
628
629 • AuthZPAMProperties (Object)
630
631 • AuthZSimpleProperties (Object)
632
633 • QEMU Object Model (QOM)
634
635 • ObjectPropertyInfo (Object)
636
637 • qom-list (Command)
638
639 • qom-get (Command)
640
641 • qom-set (Command)
642
643 • ObjectTypeInfo (Object)
644
645 • qom-list-types (Command)
646
647 • qom-list-properties (Command)
648
649 • CanHostSocketcanProperties (Object)
650
651 • ColoCompareProperties (Object)
652
653 • CryptodevBackendProperties (Object)
654
655 • CryptodevVhostUserProperties (Object)
656
657 • DBusVMStateProperties (Object)
658
659 • NetfilterInsert (Enum)
660
661 • NetfilterProperties (Object)
662
663 • FilterBufferProperties (Object)
664
665 • FilterDumpProperties (Object)
666
667 • FilterMirrorProperties (Object)
668
669 • FilterRedirectorProperties (Object)
670
671 • FilterRewriterProperties (Object)
672
673 • InputBarrierProperties (Object)
674
675 • InputLinuxProperties (Object)
676
677 • IothreadProperties (Object)
678
679 • MemoryBackendProperties (Object)
680
681 • MemoryBackendFileProperties (Object)
682
683 • MemoryBackendMemfdProperties (Object)
684
685 • PrManagerHelperProperties (Object)
686
687 • QtestProperties (Object)
688
689 • RemoteObjectProperties (Object)
690
691 • RngProperties (Object)
692
693 • RngEgdProperties (Object)
694
695 • RngRandomProperties (Object)
696
697 • SevGuestProperties (Object)
698
699 • ObjectType (Enum)
700
701 • ObjectOptions (Object)
702
703 • object-add (Command)
704
705 • object-del (Command)
706
707 • Transactions
708
709 • Abort (Object)
710
711 • ActionCompletionMode (Enum)
712
713 • TransactionAction (Object)
714
715 • TransactionProperties (Object)
716
717 • transaction (Command)
718
720 Block core (VM unrelated)
722 IoOperationType (Enum)
723 An enumeration of the I/O operation types
724
725 Values
726 read read operation
727
728 write write operation
729
730 Since
731 2.1
732
733 OnOffAuto (Enum)
734 An enumeration of three options: on, off, and auto
735
736 Values
737 auto QEMU selects the value between on and off
738
739 on Enabled
740
741 off Disabled
742
743 Since
744 2.2
745
746 OnOffSplit (Enum)
747 An enumeration of three values: on, off, and split
748
749 Values
750 on Enabled
751
752 off Disabled
753
754 split Mixed
755
756 Since
757 2.6
758
759 String (Object)
760 A fat type wrapping 'str', to be embedded in lists.
761
762 Members
763 str: string
764 Not documented
765
766 Since
767 1.2
768
769 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
774 Members
775 s: string
776 the string value
777
778 n: null
779 no string value
780
781 Since
782 2.10
783
784 OffAutoPCIBAR (Enum)
785 An enumeration of options for specifying a PCI BAR
786
787 Values
788 off The specified feature is disabled
789
790 auto The PCI BAR for the feature is automatically selected
791
792 bar0 PCI BAR0 is used for the feature
793
794 bar1 PCI BAR1 is used for the feature
795
796 bar2 PCI BAR2 is used for the feature
797
798 bar3 PCI BAR3 is used for the feature
799
800 bar4 PCI BAR4 is used for the feature
801
802 bar5 PCI BAR5 is used for the feature
803
804 Since
805 2.12
806
807 PCIELinkSpeed (Enum)
808 An enumeration of PCIe link speeds in units of GT/s
809
810 Values
811 2_5 2.5GT/s
812
813 5 5.0GT/s
814
815 8 8.0GT/s
816
817 16 16.0GT/s
818
819 Since
820 4.0
821
822 PCIELinkWidth (Enum)
823 An enumeration of PCIe link width
824
825 Values
826 1 x1
827
828 2 x2
829
830 4 x4
831
832 8 x8
833
834 12 x12
835
836 16 x16
837
838 32 x32
839
840 Since
841 4.0
842
843 HostMemPolicy (Enum)
844 Host memory policy types
845
846 Values
847 default
848 restore default policy, remove any nondefault policy
849
850 preferred
851 set the preferred host nodes for allocation
852
853 bind a strict policy that restricts memory allocation to the host
854 nodes specified
855
856 interleave
857 memory allocations are interleaved across the set of host nodes
858 specified
859
860 Since
861 2.1
862
863 NetFilterDirection (Enum)
864 Indicates whether a netfilter is attached to a netdev's transmit queue
865 or receive queue or both.
866
867 Values
868 all the filter is attached both to the receive and the transmit
869 queue of the netdev (default).
870
871 rx the filter is attached to the receive queue of the netdev, where
872 it will receive packets sent to the netdev.
873
874 tx the filter is attached to the transmit queue of the netdev,
875 where it will receive packets sent by the netdev.
876
877 Since
878 2.5
879
880 GrabToggleKeys (Enum)
881 Keys to toggle input-linux between host and guest.
882
883 Values
884 ctrl-ctrl
885 Not documented
886
887 alt-alt
888 Not documented
889
890 shift-shift
891 Not documented
892
893 meta-meta
894 Not documented
895
896 scrolllock
897 Not documented
898
899 ctrl-scrolllock
900 Not documented
901
902 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
911 Values
912 client the network endpoint is acting as the client
913
914 server the network endpoint is acting as the server
915
916 Since
917 2.5
918
919 QCryptoSecretFormat (Enum)
920 The data format that the secret is provided in
921
922 Values
923 raw raw bytes. When encoded in JSON only valid UTF-8 sequences can
924 be used
925
926 base64 arbitrary base64 encoded binary data
927
928 Since
929 2.6
930
931 QCryptoHashAlgorithm (Enum)
932 The supported algorithms for computing content digests
933
934 Values
935 md5 MD5. Should not be used in any new code, legacy compat only
936
937 sha1 SHA-1. Should not be used in any new code, legacy compat only
938
939 sha224 SHA-224. (since 2.7)
940
941 sha256 SHA-256. Current recommended strong hash.
942
943 sha384 SHA-384. (since 2.7)
944
945 sha512 SHA-512. (since 2.7)
946
947 ripemd160
948 RIPEMD-160. (since 2.7)
949
950 Since
951 2.6
952
953 QCryptoCipherAlgorithm (Enum)
954 The supported algorithms for content encryption ciphers
955
956 Values
957 aes-128
958 AES with 128 bit / 16 byte keys
959
960 aes-192
961 AES with 192 bit / 24 byte keys
962
963 aes-256
964 AES with 256 bit / 32 byte keys
965
966 des DES with 56 bit / 8 byte keys. Do not use except in VNC. (since
967 6.1)
968
969 3des 3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
970
971 cast5-128
972 Cast5 with 128 bit / 16 byte keys
973
974 serpent-128
975 Serpent with 128 bit / 16 byte keys
976
977 serpent-192
978 Serpent with 192 bit / 24 byte keys
979
980 serpent-256
981 Serpent with 256 bit / 32 byte keys
982
983 twofish-128
984 Twofish with 128 bit / 16 byte keys
985
986 twofish-192
987 Twofish with 192 bit / 24 byte keys
988
989 twofish-256
990 Twofish with 256 bit / 32 byte keys
991
992 Since
993 2.6
994
995 QCryptoCipherMode (Enum)
996 The supported modes for content encryption ciphers
997
998 Values
999 ecb Electronic Code Book
1000
1001 cbc Cipher Block Chaining
1002
1003 xts XEX with tweaked code book and ciphertext stealing
1004
1005 ctr Counter (Since 2.8)
1006
1007 Since
1008 2.6
1009
1010 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
1016 Values
1017 plain 64-bit sector number truncated to 32-bits
1018
1019 plain64
1020 64-bit sector number
1021
1022 essiv 64-bit sector number encrypted with a hash of the encryption key
1023
1024 Since
1025 2.6
1026
1027 QCryptoBlockFormat (Enum)
1028 The supported full disk encryption formats
1029
1030 Values
1031 qcow QCow/QCow2 built-in AES-CBC encryption. Use only for liberating
1032 data from old images.
1033
1034 luks LUKS encryption format. Recommended for new images
1035
1036 Since
1037 2.6
1038
1039 QCryptoBlockOptionsBase (Object)
1040 The common options that apply to all full disk encryption formats
1041
1042 Members
1043 format: QCryptoBlockFormat
1044 the encryption format
1045
1046 Since
1047 2.6
1048
1049 QCryptoBlockOptionsQCow (Object)
1050 The options that apply to QCow/QCow2 AES-CBC encryption format
1051
1052 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
1057 Since
1058 2.6
1059
1060 QCryptoBlockOptionsLUKS (Object)
1061 The options that apply to LUKS encryption format
1062
1063 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
1068 Since
1069 2.6
1070
1071 QCryptoBlockCreateOptionsLUKS (Object)
1072 The options that apply to LUKS encryption format initialization
1073
1074 Members
1075 cipher-alg: QCryptoCipherAlgorithm (optional)
1076 the cipher algorithm for data encryption Currently defaults to
1077 'aes-256'.
1078
1079 cipher-mode: QCryptoCipherMode (optional)
1080 the cipher mode for data encryption Currently defaults to 'xts'
1081
1082 ivgen-alg: QCryptoIVGenAlgorithm (optional)
1083 the initialization vector generator Currently defaults to
1084 'plain64'
1085
1086 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1087 the initialization vector generator hash Currently defaults to
1088 'sha256'
1089
1090 hash-alg: QCryptoHashAlgorithm (optional)
1091 the master key hash algorithm Currently defaults to 'sha256'
1092
1093 iter-time: int (optional)
1094 number of milliseconds to spend in PBKDF passphrase processing.
1095 Currently defaults to 2000. (since 2.8)
1096
1097 The members of QCryptoBlockOptionsLUKS
1098
1099 Since
1100 2.6
1101
1102 QCryptoBlockOpenOptions (Object)
1103 The options that are available for all encryption formats when opening
1104 an existing volume
1105
1106 Members
1107 The members of QCryptoBlockOptionsBase
1108
1109 The members of QCryptoBlockOptionsQCow when format is "qcow"
1110
1111 The members of QCryptoBlockOptionsLUKS when format is "luks"
1112
1113 Since
1114 2.6
1115
1116 QCryptoBlockCreateOptions (Object)
1117 The options that are available for all encryption formats when initial‐
1118 izing a new volume
1119
1120 Members
1121 The members of QCryptoBlockOptionsBase
1122
1123 The members of QCryptoBlockOptionsQCow when format is "qcow"
1124
1125 The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
1126
1127 Since
1128 2.6
1129
1130 QCryptoBlockInfoBase (Object)
1131 The common information that applies to all full disk encryption formats
1132
1133 Members
1134 format: QCryptoBlockFormat
1135 the encryption format
1136
1137 Since
1138 2.7
1139
1140 QCryptoBlockInfoLUKSSlot (Object)
1141 Information about the LUKS block encryption key slot options
1142
1143 Members
1144 active: boolean
1145 whether the key slot is currently in use
1146
1147 key-offset: int
1148 offset to the key material in bytes
1149
1150 iters: int (optional)
1151 number of PBKDF2 iterations for key material
1152
1153 stripes: int (optional)
1154 number of stripes for splitting key material
1155
1156 Since
1157 2.7
1158
1159 QCryptoBlockInfoLUKS (Object)
1160 Information about the LUKS block encryption options
1161
1162 Members
1163 cipher-alg: QCryptoCipherAlgorithm
1164 the cipher algorithm for data encryption
1165
1166 cipher-mode: QCryptoCipherMode
1167 the cipher mode for data encryption
1168
1169 ivgen-alg: QCryptoIVGenAlgorithm
1170 the initialization vector generator
1171
1172 ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1173 the initialization vector generator hash
1174
1175 hash-alg: QCryptoHashAlgorithm
1176 the master key hash algorithm
1177
1178 payload-offset: int
1179 offset to the payload data in bytes
1180
1181 master-key-iters: int
1182 number of PBKDF2 iterations for key material
1183
1184 uuid: string
1185 unique identifier for the volume
1186
1187 slots: array of QCryptoBlockInfoLUKSSlot
1188 information about each key slot
1189
1190 Since
1191 2.7
1192
1193 QCryptoBlockInfo (Object)
1194 Information about the block encryption options
1195
1196 Members
1197 The members of QCryptoBlockInfoBase
1198
1199 The members of QCryptoBlockInfoLUKS when format is "luks"
1200
1201 Since
1202 2.7
1203
1204 QCryptoBlockLUKSKeyslotState (Enum)
1205 Defines state of keyslots that are affected by the update
1206
1207 Values
1208 active The slots contain the given password and marked as active
1209
1210 inactive
1211 The slots are erased (contain garbage) and marked as inactive
1212
1213 Since
1214 5.1
1215
1216 QCryptoBlockAmendOptionsLUKS (Object)
1217 This struct defines the update parameters that activate/de-activate set
1218 of keyslots
1219
1220 Members
1221 state: QCryptoBlockLUKSKeyslotState
1222 the desired state of the keyslots
1223
1224 new-secret: string (optional)
1225 The ID of a QCryptoSecret object providing the password to be
1226 written into added active keyslots
1227
1228 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
1233 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
1238 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
1245 For keyslot deactivation, this parameter specifies the exact
1246 keyslot to deactivate
1247
1248 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
1254 QCryptoBlockAmendOptions (Object)
1255 The options that are available for all encryption formats when amending
1256 encryption settings
1257
1258 Members
1259 The members of QCryptoBlockOptionsBase
1260
1261 The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
1262
1263 Since
1264 5.1
1265
1266 SecretCommonProperties (Object)
1267 Properties for objects of classes derived from secret-common.
1268
1269 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
1275 format: QCryptoSecretFormat (optional)
1276 the data format that the secret is provided in (default: raw)
1277
1278 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
1283 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
1289 Features
1290 deprecated
1291 Member loaded is deprecated. Setting true doesn't make sense,
1292 and false is already the default.
1293
1294 Since
1295 2.6
1296
1297 SecretProperties (Object)
1298 Properties for secret objects.
1299
1300 Either data or file must be provided, but not both.
1301
1302 Members
1303 data: string (optional)
1304 the associated with the secret from
1305
1306 file: string (optional)
1307 the filename to load the data associated with the secret from
1308
1309 The members of SecretCommonProperties
1310
1311 Since
1312 2.6
1313
1314 SecretKeyringProperties (Object)
1315 Properties for secret_keyring objects.
1316
1317 Members
1318 serial: int
1319 serial number that identifies a key to get from the kernel
1320
1321 The members of SecretCommonProperties
1322
1323 Since
1324 5.1
1325
1326 TlsCredsProperties (Object)
1327 Properties for objects of classes derived from tls-creds.
1328
1329 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
1335 dir: string (optional)
1336 the path of the directory that contains the credential files
1337
1338 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
1342 priority: string (optional)
1343 a gnutls priority string as described at
1344 https://gnutls.org/manual/html_node/Priority-Strings.html
1345
1346 Since
1347 2.5
1348
1349 TlsCredsAnonProperties (Object)
1350 Properties for tls-creds-anon objects.
1351
1352 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
1358 The members of TlsCredsProperties
1359
1360 Features
1361 deprecated
1362 Member loaded is deprecated. Setting true doesn't make sense,
1363 and false is already the default.
1364
1365 Since
1366 2.5
1367
1368 TlsCredsPskProperties (Object)
1369 Properties for tls-creds-psk objects.
1370
1371 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
1377 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
1382 The members of TlsCredsProperties
1383
1384 Features
1385 deprecated
1386 Member loaded is deprecated. Setting true doesn't make sense,
1387 and false is already the default.
1388
1389 Since
1390 3.0
1391
1392 TlsCredsX509Properties (Object)
1393 Properties for tls-creds-x509 objects.
1394
1395 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
1401 sanity-check: boolean (optional)
1402 if true, perform some sanity checks before using the credentials
1403 (default: true)
1404
1405 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
1412 The members of TlsCredsProperties
1413
1414 Features
1415 deprecated
1416 Member loaded is deprecated. Setting true doesn't make sense,
1417 and false is already the default.
1418
1419 Since
1420 2.5
1421
1422 Background jobs
1423 JobType (Enum)
1424 Type of a background job.
1425
1426 Values
1427 commit block commit job type, see "block-commit"
1428
1429 stream block stream job type, see "block-stream"
1430
1431 mirror drive mirror job type, see "drive-mirror"
1432
1433 backup drive backup job type, see "drive-backup"
1434
1435 create image creation job type, see "blockdev-create" (since 3.0)
1436
1437 amend image options amend job type, see "x-blockdev-amend" (since 5.1)
1438
1439 snapshot-load
1440 snapshot load job type, see "snapshot-load" (since 6.0)
1441
1442 snapshot-save
1443 snapshot save job type, see "snapshot-save" (since 6.0)
1444
1445 snapshot-delete
1446 snapshot delete job type, see "snapshot-delete" (since 6.0)
1447
1448 Since
1449 1.7
1450
1451 JobStatus (Enum)
1452 Indicates the present state of a given job in its lifetime.
1453
1454 Values
1455 undefined
1456 Erroneous, default state. Should not ever be visible.
1457
1458 created
1459 The job has been created, but not yet started.
1460
1461 running
1462 The job is currently running.
1463
1464 paused The job is running, but paused. The pause may be requested by
1465 either the QMP user or by internal processes.
1466
1467 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
1471 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
1475 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
1480 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
1486 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
1491 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
1496 null The job is in the process of being dismantled. This state should
1497 not ever be visible externally.
1498
1499 Since
1500 2.12
1501
1502 JobVerb (Enum)
1503 Represents command verbs that can be applied to a job.
1504
1505 Values
1506 cancel see job-cancel
1507
1508 pause see job-pause
1509
1510 resume see job-resume
1511
1512 set-speed
1513 see block-job-set-speed
1514
1515 complete
1516 see job-complete
1517
1518 dismiss
1519 see job-dismiss
1520
1521 finalize
1522 see job-finalize
1523
1524 Since
1525 2.12
1526
1527 JOB_STATUS_CHANGE (Event)
1528 Emitted when a job transitions to a different status.
1529
1530 Arguments
1531 id: string
1532 The job identifier
1533
1534 status: JobStatus
1535 The new job status
1536
1537 Since
1538 3.0
1539
1540 job-pause (Command)
1541 Pause an active job.
1542
1543 This command returns immediately after marking the active job for paus‐
1544 ing. Pausing an already paused job is an error.
1545
1546 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
1550 Cancelling a paused job automatically resumes it.
1551
1552 Arguments
1553 id: string
1554 The job identifier.
1555
1556 Since
1557 3.0
1558
1559 job-resume (Command)
1560 Resume a paused job.
1561
1562 This command returns immediately after resuming a paused job. Resuming
1563 an already running job is an error.
1564
1565 id : The job identifier.
1566
1567 Arguments
1568 id: string
1569 Not documented
1570
1571 Since
1572 3.0
1573
1574 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
1579 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
1585 Arguments
1586 id: string
1587 The job identifier.
1588
1589 Since
1590 3.0
1591
1592 job-complete (Command)
1593 Manually trigger completion of an active job in the READY state.
1594
1595 Arguments
1596 id: string
1597 The job identifier.
1598
1599 Since
1600 3.0
1601
1602 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
1607 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
1612 Arguments
1613 id: string
1614 The job identifier.
1615
1616 Since
1617 3.0
1618
1619 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
1625 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
1629 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
1634 Since
1635 3.0
1636
1637 JobInfo (Object)
1638 Information about a job.
1639
1640 Members
1641 id: string
1642 The job identifier
1643
1644 type: JobType
1645 The kind of job that is being performed
1646
1647 status: JobStatus
1648 Current job state/status
1649
1650 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
1655 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
1660 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
1664 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
1668 Since
1669 3.0
1670
1671 query-jobs (Command)
1672 Return information about jobs.
1673
1674 Returns
1675 a list with a JobInfo for each active job
1676
1677 Since
1678 3.0
1679
1681 NetworkAddressFamily (Enum)
1682 The network address family
1683
1684 Values
1685 ipv4 IPV4 family
1686
1687 ipv6 IPV6 family
1688
1689 unix unix socket
1690
1691 vsock vsock family (since 2.8)
1692
1693 unknown
1694 otherwise
1695
1696 Since
1697 2.1
1698
1699 InetSocketAddressBase (Object)
1700 Members
1701 host: string
1702 host part of the address
1703
1704 port: string
1705 port part of the address
1706
1707 InetSocketAddress (Object)
1708 Captures a socket address or address range in the Internet namespace.
1709
1710 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
1716 to: int (optional)
1717 If present, this is range of possible addresses, with port be‐
1718 tween port and to.
1719
1720 ipv4: boolean (optional)
1721 whether to accept IPv4 addresses, default try both IPv4 and IPv6
1722
1723 ipv6: boolean (optional)
1724 whether to accept IPv6 addresses, default try both IPv4 and IPv6
1725
1726 keep-alive: boolean (optional)
1727 enable keep-alive when connecting to this socket. Not supported
1728 for passive sockets. (Since 4.2)
1729
1730 mptcp: boolean (optional) (If: defined(IPPROTO_MPTCP))
1731 enable multi-path TCP. (Since 6.1)
1732
1733 The members of InetSocketAddressBase
1734
1735 Since
1736 1.3
1737
1738 UnixSocketAddress (Object)
1739 Captures a socket address in the local ("Unix socket") namespace.
1740
1741 Members
1742 path: string
1743 filesystem path to use
1744
1745 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
1750 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
1755 Since
1756 1.3
1757
1758 VsockSocketAddress (Object)
1759 Captures a socket address in the vsock namespace.
1760
1761 Members
1762 cid: string
1763 unique host identifier
1764
1765 port: string
1766 port
1767
1768 Note
1769 string types are used to allow for possible future hostname or service
1770 resolution support.
1771
1772 Since
1773 2.8
1774
1775 SocketAddressLegacy (Object)
1776 Captures the address of a socket, which could also be a named file de‐
1777 scriptor
1778
1779 Members
1780 type One of inet, unix, vsock, fd
1781
1782 data: InetSocketAddress when type is "inet"
1783
1784 data: UnixSocketAddress when type is "unix"
1785
1786 data: VsockSocketAddress when type is "vsock"
1787
1788 data: String when type is "fd"
1789
1790 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
1796 Since
1797 1.3
1798
1799 SocketAddressType (Enum)
1800 Available SocketAddress types
1801
1802 Values
1803 inet Internet address
1804
1805 unix Unix domain socket
1806
1807 vsock VMCI address
1808
1809 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
1815 Since
1816 2.9
1817
1818 SocketAddress (Object)
1819 Captures the address of a socket, which could also be a named file de‐
1820 scriptor
1821
1822 Members
1823 type: SocketAddressType
1824 Transport type
1825
1826 The members of InetSocketAddress when type is "inet"
1827
1828 The members of UnixSocketAddress when type is "unix"
1829
1830 The members of VsockSocketAddress when type is "vsock"
1831
1832 The members of String when type is "fd"
1833
1834 Since
1835 2.9
1836
1837 SnapshotInfo (Object)
1838 Members
1839 id: string
1840 unique snapshot id
1841
1842 name: string
1843 user chosen name
1844
1845 vm-state-size: int
1846 size of the VM state
1847
1848 date-sec: int
1849 UTC date of the snapshot in seconds
1850
1851 date-nsec: int
1852 fractional part in nano seconds to be used with date-sec
1853
1854 vm-clock-sec: int
1855 VM clock relative to boot in seconds
1856
1857 vm-clock-nsec: int
1858 fractional part in nano seconds to be used with vm-clock-sec
1859
1860 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
1866 Since
1867 1.3
1868
1869 ImageInfoSpecificQCow2EncryptionBase (Object)
1870 Members
1871 format: BlockdevQcow2EncryptionFormat
1872 The encryption format
1873
1874 Since
1875 2.10
1876
1877 ImageInfoSpecificQCow2Encryption (Object)
1878 Members
1879 The members of ImageInfoSpecificQCow2EncryptionBase
1880
1881 The members of QCryptoBlockInfoLUKS when format is "luks"
1882
1883 Since
1884 2.10
1885
1886 ImageInfoSpecificQCow2 (Object)
1887 Members
1888 compat: string
1889 compatibility level
1890
1891 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
1895 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
1900 extended-l2: boolean (optional)
1901 true if the image has extended L2 entries; only valid for compat
1902 >= 1.1 (since 5.2)
1903
1904 lazy-refcounts: boolean (optional)
1905 on or off; only valid for compat >= 1.1
1906
1907 corrupt: boolean (optional)
1908 true if the image has been marked corrupt; only valid for compat
1909 >= 1.1 (since 2.2)
1910
1911 refcount-bits: int
1912 width of a refcount entry in bits (since 2.3)
1913
1914 encrypt: ImageInfoSpecificQCow2Encryption (optional)
1915 details about encryption parameters; only set if image is en‐
1916 crypted (since 2.10)
1917
1918 bitmaps: array of Qcow2BitmapInfo (optional)
1919 A list of qcow2 bitmap details (since 4.0)
1920
1921 compression-type: Qcow2CompressionType
1922 the image cluster compression method (since 5.1)
1923
1924 Since
1925 1.7
1926
1927 ImageInfoSpecificVmdk (Object)
1928 Members
1929 create-type: string
1930 The create type of VMDK image
1931
1932 cid: int
1933 Content id of image
1934
1935 parent-cid: int
1936 Parent VMDK image's cid
1937
1938 extents: array of ImageInfo
1939 List of extent files
1940
1941 Since
1942 1.7
1943
1944 ImageInfoSpecificRbd (Object)
1945 Members
1946 encryption-format: RbdImageEncryptionFormat (optional)
1947 Image encryption format
1948
1949 Since
1950 6.1
1951
1952 ImageInfoSpecific (Object)
1953 A discriminated record of image format specific information structures.
1954
1955 Members
1956 type One of qcow2, vmdk, luks, rbd
1957
1958 data: ImageInfoSpecificQCow2 when type is "qcow2"
1959
1960 data: ImageInfoSpecificVmdk when type is "vmdk"
1961
1962 data: QCryptoBlockInfoLUKS when type is "luks"
1963
1964 data: ImageInfoSpecificRbd when type is "rbd"
1965
1966 Since
1967 1.7
1968
1969 ImageInfo (Object)
1970 Information about a QEMU image file
1971
1972 Members
1973 filename: string
1974 name of the image file
1975
1976 format: string
1977 format of the image file
1978
1979 virtual-size: int
1980 maximum capacity in bytes of the image
1981
1982 actual-size: int (optional)
1983 actual size on disk in bytes of the image
1984
1985 dirty-flag: boolean (optional)
1986 true if image is not cleanly closed
1987
1988 cluster-size: int (optional)
1989 size of a cluster in bytes
1990
1991 encrypted: boolean (optional)
1992 true if the image is encrypted
1993
1994 compressed: boolean (optional)
1995 true if the image is compressed (Since 1.7)
1996
1997 backing-filename: string (optional)
1998 name of the backing file
1999
2000 full-backing-filename: string (optional)
2001 full path of the backing file
2002
2003 backing-filename-format: string (optional)
2004 the format of the backing file
2005
2006 snapshots: array of SnapshotInfo (optional)
2007 list of VM snapshots
2008
2009 backing-image: ImageInfo (optional)
2010 info of the backing image (since 1.6)
2011
2012 format-specific: ImageInfoSpecific (optional)
2013 structure supplying additional format-specific information
2014 (since 1.7)
2015
2016 Since
2017 1.3
2018
2019 ImageCheck (Object)
2020 Information about a QEMU image file check
2021
2022 Members
2023 filename: string
2024 name of the image file checked
2025
2026 format: string
2027 format of the image file checked
2028
2029 check-errors: int
2030 number of unexpected errors occurred during check
2031
2032 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
2036 corruptions: int (optional)
2037 number of corruptions found during the check if any
2038
2039 leaks: int (optional)
2040 number of leaks found during the check if any
2041
2042 corruptions-fixed: int (optional)
2043 number of corruptions fixed during the check if any
2044
2045 leaks-fixed: int (optional)
2046 number of leaks fixed during the check if any
2047
2048 total-clusters: int (optional)
2049 total number of clusters, this field is present if the driver
2050 for the image format supports it
2051
2052 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
2056 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
2060 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
2064 Since
2065 1.4
2066
2067 MapEntry (Object)
2068 Mapping information from a virtual block range to a host file range
2069
2070 Members
2071 start: int
2072 virtual (guest) offset of the first byte described by this entry
2073
2074 length: int
2075 the number of bytes of the mapped virtual range
2076
2077 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
2082 zero: boolean
2083 whether the virtual blocks read as zeroes
2084
2085 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
2090 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
2094 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
2098 filename: string (optional)
2099 filename that is referred to by offset
2100
2101 Since
2102 2.6
2103
2104 BlockdevCacheInfo (Object)
2105 Cache mode information for a block device
2106
2107 Members
2108 writeback: boolean
2109 true if writeback mode is enabled
2110
2111 direct: boolean
2112 true if the host page cache is bypassed (O_DIRECT)
2113
2114 no-flush: boolean
2115 true if flush requests are ignored for the device
2116
2117 Since
2118 2.3
2119
2120 BlockDeviceInfo (Object)
2121 Information about the backing device for a block device.
2122
2123 Members
2124 file: string
2125 the filename of the backing device
2126
2127 node-name: string (optional)
2128 the name of the block driver node (Since 2.0)
2129
2130 ro: boolean
2131 true if the backing device was open read-only
2132
2133 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
2143 backing_file: string (optional)
2144 the name of the backing file (for copy-on-write)
2145
2146 backing_file_depth: int
2147 number of files in the backing file chain (since: 1.2)
2148
2149 encrypted: boolean
2150 true if the backing device is encrypted
2151
2152 detect_zeroes: BlockdevDetectZeroesOptions
2153 detect and optimize zero writes (Since 2.1)
2154
2155 bps: int
2156 total throughput limit in bytes per second is specified
2157
2158 bps_rd: int
2159 read throughput limit in bytes per second is specified
2160
2161 bps_wr: int
2162 write throughput limit in bytes per second is specified
2163
2164 iops: int
2165 total I/O operations per second is specified
2166
2167 iops_rd: int
2168 read I/O operations per second is specified
2169
2170 iops_wr: int
2171 write I/O operations per second is specified
2172
2173 image: ImageInfo
2174 the info of image used (since: 1.6)
2175
2176 bps_max: int (optional)
2177
2178 total throughput limit during bursts,
2179 in bytes (Since 1.7)
2180
2181 bps_rd_max: int (optional)
2182
2183 read throughput limit during bursts,
2184 in bytes (Since 1.7)
2185
2186 bps_wr_max: int (optional)
2187
2188 write throughput limit during bursts,
2189 in bytes (Since 1.7)
2190
2191 iops_max: int (optional)
2192
2193 total I/O operations per second during bursts,
2194 in bytes (Since 1.7)
2195
2196 iops_rd_max: int (optional)
2197
2198 read I/O operations per second during bursts,
2199 in bytes (Since 1.7)
2200
2201 iops_wr_max: int (optional)
2202
2203 write I/O operations per second during bursts,
2204 in bytes (Since 1.7)
2205
2206 bps_max_length: int (optional)
2207
2208 maximum length of the bps_max burst
2209 period, in seconds. (Since 2.6)
2210
2211 bps_rd_max_length: int (optional)
2212
2213 maximum length of the bps_rd_max
2214 burst period, in seconds. (Since 2.6)
2215
2216 bps_wr_max_length: int (optional)
2217
2218 maximum length of the bps_wr_max
2219 burst period, in seconds. (Since 2.6)
2220
2221 iops_max_length: int (optional)
2222
2223 maximum length of the iops burst
2224 period, in seconds. (Since 2.6)
2225
2226 iops_rd_max_length: int (optional)
2227
2228 maximum length of the iops_rd_max
2229 burst period, in seconds. (Since 2.6)
2230
2231 iops_wr_max_length: int (optional)
2232
2233 maximum length of the iops_wr_max
2234 burst period, in seconds. (Since 2.6)
2235
2236 iops_size: int (optional)
2237 an I/O size in bytes (Since 1.7)
2238
2239 group: string (optional)
2240 throttle group name (Since 2.4)
2241
2242 cache: BlockdevCacheInfo
2243 the cache mode used for the block device (since: 2.3)
2244
2245 write_threshold: int
2246 configured write threshold for the device. 0 if disabled.
2247 (Since 2.3)
2248
2249 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
2253 Since
2254 0.14
2255
2256 BlockDeviceIoStatus (Enum)
2257 An enumeration of block device I/O status.
2258
2259 Values
2260 ok The last I/O operation has succeeded
2261
2262 failed The last I/O operation has failed
2263
2264 nospace
2265 The last I/O operation has failed due to a no-space condition
2266
2267 Since
2268 1.0
2269
2270 BlockDirtyInfo (Object)
2271 Block dirty bitmap information.
2272
2273 Members
2274 name: string (optional)
2275 the name of the dirty bitmap (Since 2.4)
2276
2277 count: int
2278 number of dirty bytes according to the dirty bitmap
2279
2280 granularity: int
2281 granularity of the dirty bitmap in bytes (since 1.4)
2282
2283 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
2287 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
2292 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
2296 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
2302 Since
2303 1.3
2304
2305 Qcow2BitmapInfoFlags (Enum)
2306 An enumeration of flags that a bitmap can report to the user.
2307
2308 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
2315 auto The bitmap must reflect all changes of the virtual disk by any
2316 application that would write to this qcow2 file.
2317
2318 Since
2319 4.0
2320
2321 Qcow2BitmapInfo (Object)
2322 Qcow2 bitmap information.
2323
2324 Members
2325 name: string
2326 the name of the bitmap
2327
2328 granularity: int
2329 granularity of the bitmap in bytes
2330
2331 flags: array of Qcow2BitmapInfoFlags
2332 flags of the bitmap
2333
2334 Since
2335 4.0
2336
2337 BlockLatencyHistogramInfo (Object)
2338 Block latency histogram.
2339
2340 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
2347 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
2353 5| *
2354 4| *
2355 3| * *
2356 2| * * *
2357 1| * * * *
2358 +------------------
2359 10 50 100
2360
2361 Since
2362 4.0
2363
2364 BlockInfo (Object)
2365 Block device information. This structure describes a virtual device
2366 and the backing device associated with it.
2367
2368 Members
2369 device: string
2370 The device name associated with the virtual device.
2371
2372 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
2376 type: string
2377 This field is returned only for compatibility reasons, it should
2378 not be used (always returns 'unknown')
2379
2380 removable: boolean
2381 True if the device supports removable media.
2382
2383 locked: boolean
2384 True if the guest has locked this device from having its media
2385 removed
2386
2387 tray_open: boolean (optional)
2388 True if the device's tray is open (only present if it has a
2389 tray)
2390
2391 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
2396 inserted: BlockDeviceInfo (optional)
2397 BlockDeviceInfo describing the device if media is present
2398
2399 Since
2400 0.14
2401
2402 BlockMeasureInfo (Object)
2403 Image file size calculation information. This structure describes the
2404 size requirements for creating a new image file.
2405
2406 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
2412 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
2416 Members
2417 required: int
2418 Size required for a new image file, in bytes, when copying just
2419 allocated guest-visible contents.
2420
2421 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
2425 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
2431 Since
2432 2.10
2433
2434 query-block (Command)
2435 Get a list of BlockInfo for all virtual block devices.
2436
2437 Returns
2438 a list of BlockInfo describing each virtual block device. Filter nodes
2439 that were created implicitly are skipped over.
2440
2441 Since
2442 0.14
2443
2444 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
2527 BlockDeviceTimedStats (Object)
2528 Statistics of a block device during a given interval of time.
2529
2530 Members
2531 interval_length: int
2532 Interval used for calculating the statistics, in seconds.
2533
2534 min_rd_latency_ns: int
2535 Minimum latency of read operations in the defined interval, in
2536 nanoseconds.
2537
2538 min_wr_latency_ns: int
2539 Minimum latency of write operations in the defined interval, in
2540 nanoseconds.
2541
2542 min_flush_latency_ns: int
2543 Minimum latency of flush operations in the defined interval, in
2544 nanoseconds.
2545
2546 max_rd_latency_ns: int
2547 Maximum latency of read operations in the defined interval, in
2548 nanoseconds.
2549
2550 max_wr_latency_ns: int
2551 Maximum latency of write operations in the defined interval, in
2552 nanoseconds.
2553
2554 max_flush_latency_ns: int
2555 Maximum latency of flush operations in the defined interval, in
2556 nanoseconds.
2557
2558 avg_rd_latency_ns: int
2559 Average latency of read operations in the defined interval, in
2560 nanoseconds.
2561
2562 avg_wr_latency_ns: int
2563 Average latency of write operations in the defined interval, in
2564 nanoseconds.
2565
2566 avg_flush_latency_ns: int
2567 Average latency of flush operations in the defined interval, in
2568 nanoseconds.
2569
2570 avg_rd_queue_depth: number
2571 Average number of pending read operations in the defined inter‐
2572 val.
2573
2574 avg_wr_queue_depth: number
2575 Average number of pending write operations in the defined inter‐
2576 val.
2577
2578 Since
2579 2.5
2580
2581 BlockDeviceStats (Object)
2582 Statistics of a virtual block device or a block backing device.
2583
2584 Members
2585 rd_bytes: int
2586 The number of bytes read by the device.
2587
2588 wr_bytes: int
2589 The number of bytes written by the device.
2590
2591 unmap_bytes: int
2592 The number of bytes unmapped by the device (Since 4.2)
2593
2594 rd_operations: int
2595 The number of read operations performed by the device.
2596
2597 wr_operations: int
2598 The number of write operations performed by the device.
2599
2600 flush_operations: int
2601 The number of cache flush operations performed by the device
2602 (since 0.15)
2603
2604 unmap_operations: int
2605 The number of unmap operations performed by the device (Since
2606 4.2)
2607
2608 rd_total_time_ns: int
2609 Total time spent on reads in nanoseconds (since 0.15).
2610
2611 wr_total_time_ns: int
2612 Total time spent on writes in nanoseconds (since 0.15).
2613
2614 flush_total_time_ns: int
2615 Total time spent on cache flushes in nanoseconds (since 0.15).
2616
2617 unmap_total_time_ns: int
2618 Total time spent on unmap operations in nanoseconds (Since 4.2)
2619
2620 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
2625 rd_merged: int
2626 Number of read requests that have been merged into another re‐
2627 quest (Since 2.3).
2628
2629 wr_merged: int
2630 Number of write requests that have been merged into another re‐
2631 quest (Since 2.3).
2632
2633 unmap_merged: int
2634 Number of unmap requests that have been merged into another re‐
2635 quest (Since 4.2)
2636
2637 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
2642 failed_rd_operations: int
2643 The number of failed read operations performed by the device
2644 (Since 2.5)
2645
2646 failed_wr_operations: int
2647 The number of failed write operations performed by the device
2648 (Since 2.5)
2649
2650 failed_flush_operations: int
2651 The number of failed flush operations performed by the device
2652 (Since 2.5)
2653
2654 failed_unmap_operations: int
2655 The number of failed unmap operations performed by the device
2656 (Since 4.2)
2657
2658 invalid_rd_operations: int
2659
2660 The number of invalid read operations
2661 performed by the device (Since 2.5)
2662
2663 invalid_wr_operations: int
2664 The number of invalid write operations performed by the device
2665 (Since 2.5)
2666
2667 invalid_flush_operations: int
2668 The number of invalid flush operations performed by the device
2669 (Since 2.5)
2670
2671 invalid_unmap_operations: int
2672 The number of invalid unmap operations performed by the device
2673 (Since 4.2)
2674
2675 account_invalid: boolean
2676 Whether invalid operations are included in the last access sta‐
2677 tistics (Since 2.5)
2678
2679 account_failed: boolean
2680 Whether failed operations are included in the latency and last
2681 access statistics (Since 2.5)
2682
2683 timed_stats: array of BlockDeviceTimedStats
2684 Statistics specific to the set of previously defined intervals
2685 of time (Since 2.5)
2686
2687 rd_latency_histogram: BlockLatencyHistogramInfo (optional)
2688 BlockLatencyHistogramInfo. (Since 4.0)
2689
2690 wr_latency_histogram: BlockLatencyHistogramInfo (optional)
2691 BlockLatencyHistogramInfo. (Since 4.0)
2692
2693 flush_latency_histogram: BlockLatencyHistogramInfo (optional)
2694 BlockLatencyHistogramInfo. (Since 4.0)
2695
2696 Since
2697 0.14
2698
2699 BlockStatsSpecificFile (Object)
2700 File driver statistics
2701
2702 Members
2703 discard-nb-ok: int
2704 The number of successful discard operations performed by the
2705 driver.
2706
2707 discard-nb-failed: int
2708 The number of failed discard operations performed by the driver.
2709
2710 discard-bytes-ok: int
2711 The number of bytes discarded by the driver.
2712
2713 Since
2714 4.2
2715
2716 BlockStatsSpecificNvme (Object)
2717 NVMe driver statistics
2718
2719 Members
2720 completion-errors: int
2721 The number of completion errors.
2722
2723 aligned-accesses: int
2724 The number of aligned accesses performed by the driver.
2725
2726 unaligned-accesses: int
2727 The number of unaligned accesses performed by the driver.
2728
2729 Since
2730 5.2
2731
2732 BlockStatsSpecific (Object)
2733 Block driver specific statistics
2734
2735 Members
2736 driver: BlockdevDriver
2737 Not documented
2738
2739 The members of BlockStatsSpecificFile when driver is "file"
2740
2741 The members of BlockStatsSpecificFile when driver is "host_device" (If:
2742 defined(HAVE_HOST_BLOCK_DEVICE))
2743
2744 The members of BlockStatsSpecificNvme when driver is "nvme"
2745
2746 Since
2747 4.2
2748
2749 BlockStats (Object)
2750 Statistics of a virtual block device or a block backing device.
2751
2752 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
2757 node-name: string (optional)
2758 The node name of the device. (Since 2.3)
2759
2760 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
2764 stats: BlockDeviceStats
2765 A BlockDeviceStats for the device.
2766
2767 driver-specific: BlockStatsSpecific (optional)
2768 Optional driver-specific stats. (Since 4.2)
2769
2770 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
2776 backing: BlockStats (optional)
2777 This describes the backing block device if it has one. (Since
2778 2.0)
2779
2780 Since
2781 0.14
2782
2783 query-blockstats (Command)
2784 Query the BlockStats for all virtual block devices.
2785
2786 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
2795 Returns
2796 A list of BlockStats for each virtual block devices.
2797
2798 Since
2799 0.14
2800
2801 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
2902 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
2907 Values
2908 report for guest operations, report the error to the guest; for jobs,
2909 cancel the job
2910
2911 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
2917 enospc same as stop on ENOSPC, same as report otherwise.
2918
2919 stop for guest operations, stop the virtual machine; for jobs, pause
2920 the job
2921
2922 auto inherit the error handling policy of the backend (since: 2.7)
2923
2924 Since
2925 1.3
2926
2927 MirrorSyncMode (Enum)
2928 An enumeration of possible behaviors for the initial synchronization
2929 phase of storage mirroring.
2930
2931 Values
2932 top copies data in the topmost image to the destination
2933
2934 full copies data from all images to the destination
2935
2936 none only copy data written from now on
2937
2938 incremental
2939 only copy data described by the dirty bitmap. (since: 2.4)
2940
2941 bitmap only copy data described by the dirty bitmap. (since: 4.2) Be‐
2942 havior on completion is determined by the BitmapSyncMode.
2943
2944 Since
2945 1.3
2946
2947 BitmapSyncMode (Enum)
2948 An enumeration of possible behaviors for the synchronization of a bit‐
2949 map when used for data copy operations.
2950
2951 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
2956 never The bitmap is never synchronized with the operation, and is
2957 treated solely as a read-only manifest of blocks to copy.
2958
2959 always The bitmap is always synchronized with the operation, regardless
2960 of whether or not the operation was successful.
2961
2962 Since
2963 4.2
2964
2965 MirrorCopyMode (Enum)
2966 An enumeration whose values tell the mirror block job when to trigger
2967 writes to the target.
2968
2969 Values
2970 background
2971 copy data in background only.
2972
2973 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
2978 Since
2979 3.0
2980
2981 BlockJobInfo (Object)
2982 Information about a long-running block device operation.
2983
2984 Members
2985 type: string
2986 the job type ('stream' for image streaming)
2987
2988 device: string
2989 The job identifier. Originally the device name but other values
2990 are allowed since QEMU 2.7
2991
2992 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
2997 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
3002 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
3006 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
3010 speed: int
3011 the rate limit, bytes per second
3012
3013 io-status: BlockDeviceIoStatus
3014 the status of the job (since 1.3)
3015
3016 ready: boolean
3017 true if the job may be completed (since 2.2)
3018
3019 status: JobStatus
3020 Current job state/status (since 2.12)
3021
3022 auto-finalize: boolean
3023 Job will finalize itself when PENDING, moving to the CONCLUDED
3024 state. (since 2.12)
3025
3026 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
3030 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
3034 Since
3035 1.1
3036
3037 query-block-jobs (Command)
3038 Return information about long-running block device operations.
3039
3040 Returns
3041 a list of BlockJobInfo for each active block job
3042
3043 Since
3044 1.1
3045
3046 block_resize (Command)
3047 Resize a block image while a guest is running.
3048
3049 Either device or node-name must be set but not both.
3050
3051 Arguments
3052 device: string (optional)
3053 the name of the device to get the image resized
3054
3055 node-name: string (optional)
3056 graph node name to get the image resized (Since 2.0)
3057
3058 size: int
3059 new image size in bytes
3060
3061 Returns
3062 • nothing on success
3063
3064 • If device is not a valid block device, DeviceNotFound
3065
3066 Since
3067 0.14
3068
3069 Example
3070 -> { "execute": "block_resize",
3071 "arguments": { "device": "scratch", "size": 1073741824 } }
3072 <- { "return": {} }
3073
3074 NewImageMode (Enum)
3075 An enumeration that tells QEMU how to set the backing file path in a
3076 new image file.
3077
3078 Values
3079 existing
3080 QEMU should look for an existing image file.
3081
3082 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
3087 Since
3088 1.1
3089
3090 BlockdevSnapshotSync (Object)
3091 Either device or node-name must be set but not both.
3092
3093 Members
3094 device: string (optional)
3095 the name of the device to take a snapshot of.
3096
3097 node-name: string (optional)
3098 graph node name to generate the snapshot from (Since 2.0)
3099
3100 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
3105 snapshot-node-name: string (optional)
3106 the graph node name of the new image (Since 2.0)
3107
3108 format: string (optional)
3109 the format of the overlay image, default is 'qcow2'.
3110
3111 mode: NewImageMode (optional)
3112 whether and how QEMU should create a new image, default is 'ab‐
3113 solute-paths'.
3114
3115 BlockdevSnapshot (Object)
3116 Members
3117 node: string
3118 device or node name that will have a snapshot taken.
3119
3120 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
3126 Since
3127 2.5
3128
3129 BackupPerf (Object)
3130 Optional parameters for backup. These parameters don't affect function‐
3131 ality, but may significantly affect performance.
3132
3133 Members
3134 use-copy-range: boolean (optional)
3135 Use copy offloading. Default false.
3136
3137 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
3142 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
3149 Since
3150 6.0
3151
3152 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
3158 device: string
3159 the device name or node-name of a root node which should be
3160 copied.
3161
3162 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
3167 speed: int (optional)
3168 the maximum speed, in bytes per second. The default is 0, for
3169 unlimited.
3170
3171 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
3177 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
3182 compress: boolean (optional)
3183 true to compress data, if the target format supports it. (de‐
3184 fault: false) (since 2.8)
3185
3186 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
3191 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
3196 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
3203 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
3209 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
3215 x-perf: BackupPerf (optional)
3216 Performance options. (Since 6.0)
3217
3218 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
3223 Since
3224 4.2
3225
3226 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
3233 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
3237 mode: NewImageMode (optional)
3238 whether and how QEMU should create a new image, default is 'ab‐
3239 solute-paths'.
3240
3241 The members of BackupCommon
3242
3243 Since
3244 1.6
3245
3246 BlockdevBackup (Object)
3247 Members
3248 target: string
3249 the device name or node-name of the backup target node.
3250
3251 The members of BackupCommon
3252
3253 Since
3254 2.3
3255
3256 blockdev-snapshot-sync (Command)
3257 Takes a synchronous snapshot of a block device.
3258
3259 For the arguments, see the documentation of BlockdevSnapshotSync.
3260
3261 Returns
3262 • nothing on success
3263
3264 • If device is not a valid block device, DeviceNotFound
3265
3266 Since
3267 0.14
3268
3269 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
3277 blockdev-snapshot (Command)
3278 Takes a snapshot of a block device.
3279
3280 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
3284 For the arguments, see the documentation of BlockdevSnapshot.
3285
3286 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
3292 Since
3293 2.5
3294
3295 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
3303 <- { "return": {} }
3304
3305 -> { "execute": "blockdev-snapshot",
3306 "arguments": { "node": "ide-hd0",
3307 "overlay": "node1534" } }
3308 <- { "return": {} }
3309
3310 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
3317 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
3323 device: string
3324 The device name or node-name of the root node that owns im‐
3325 age-node-name.
3326
3327 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
3332 Returns
3333 • Nothing on success
3334
3335 • If "device" does not exist or cannot be determined, DeviceNotFound
3336
3337 Since
3338 2.1
3339
3340 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
3344 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
3349 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
3355 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
3360 device: string
3361 the device name or node-name of a root node
3362
3363 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
3367 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
3373 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
3378 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
3384 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
3390 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
3395 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
3400 speed: int (optional)
3401 the maximum speed, in bytes per second
3402
3403 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
3407 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
3412 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
3419 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
3425 Features
3426 deprecated
3427 Members base and top are deprecated. Use base-node and top-node
3428 instead.
3429
3430 Returns
3431 • Nothing on success
3432
3433 • If device does not exist, DeviceNotFound
3434
3435 • Any other error returns a GenericError.
3436
3437 Since
3438 1.3
3439
3440 Example
3441 -> { "execute": "block-commit",
3442 "arguments": { "device": "virtio0",
3443 "top": "/tmp/snap1.qcow2" } }
3444 <- { "return": {} }
3445
3446 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
3453 Arguments
3454 The members of DriveBackup
3455
3456 Returns
3457 • nothing on success
3458
3459 • If device is not a valid block device, GenericError
3460
3461 Since
3462 1.6
3463
3464 Example
3465 -> { "execute": "drive-backup",
3466 "arguments": { "device": "drive0",
3467 "sync": "full",
3468 "target": "backup.img" } }
3469 <- { "return": {} }
3470
3471 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
3478 Arguments
3479 The members of BlockdevBackup
3480
3481 Returns
3482 • nothing on success
3483
3484 • If device is not a valid block device, DeviceNotFound
3485
3486 Since
3487 2.3
3488
3489 Example
3490 -> { "execute": "blockdev-backup",
3491 "arguments": { "device": "src-id",
3492 "sync": "full",
3493 "target": "tgt-id" } }
3494 <- { "return": {} }
3495
3496 query-named-block-nodes (Command)
3497 Get the named block driver list
3498
3499 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
3504 Returns
3505 the list of BlockDeviceInfo
3506
3507 Since
3508 2.0
3509
3510 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
3557 XDbgBlockGraphNodeType (Enum)
3558 Values
3559 block-backend
3560 corresponds to BlockBackend
3561
3562 block-job
3563 corresponds to BlockJob
3564
3565 block-driver
3566 corresponds to BlockDriverState
3567
3568 Since
3569 4.0
3570
3571 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
3578 type: XDbgBlockGraphNodeType
3579 Type of graph node. Can be one of block-backend, block-job or
3580 block-driver-state.
3581
3582 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
3587 Since
3588 4.0
3589
3590 BlockPermission (Enum)
3591 Enum of base block permissions.
3592
3593 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
3603 write This permission is required to change the visible disk contents.
3604
3605 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
3612 resize This permission is required to change the size of a block node.
3613
3614 graph-mod
3615 This permission is required to change the node that this
3616 BdrvChild points to.
3617
3618 Since
3619 4.0
3620
3621 XDbgBlockGraphEdge (Object)
3622 Block Graph edge description for x-debug-query-block-graph.
3623
3624 Members
3625 parent: int
3626 parent id
3627
3628 child: int
3629 child id
3630
3631 name: string
3632 name of the relation (examples are 'file' and 'backing')
3633
3634 perm: array of BlockPermission
3635 granted permissions for the parent operating on the child
3636
3637 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
3641 Since
3642 4.0
3643
3644 XDbgBlockGraph (Object)
3645 Block Graph - list of nodes and list of edges.
3646
3647 Members
3648 nodes: array of XDbgBlockGraphNode
3649 Not documented
3650
3651 edges: array of XDbgBlockGraphEdge
3652 Not documented
3653
3654 Since
3655 4.0
3656
3657 x-debug-query-block-graph (Command)
3658 Get the block graph.
3659
3660 Since
3661 4.0
3662
3663 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
3671 Arguments
3672 The members of DriveMirror
3673
3674 Returns
3675 • nothing on success
3676
3677 • If device is not a valid block device, GenericError
3678
3679 Since
3680 1.3
3681
3682 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
3690 DriveMirror (Object)
3691 A set of parameters describing drive mirror setup.
3692
3693 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
3698 device: string
3699 the device name or node-name of a root node whose writes should
3700 be mirrored.
3701
3702 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
3707 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
3711 node-name: string (optional)
3712 the new block driver state node name in the graph (Since 2.1)
3713
3714 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
3720 mode: NewImageMode (optional)
3721 whether and how QEMU should create a new image, default is 'ab‐
3722 solute-paths'.
3723
3724 speed: int (optional)
3725 the maximum speed, in bytes per second
3726
3727 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
3732 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
3738 buf-size: int (optional)
3739 maximum amount of data in flight from source to target (since
3740 1.4).
3741
3742 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
3747 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
3752 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
3759 copy-mode: MirrorCopyMode (optional)
3760 when to copy data to the destination; defaults to 'background'
3761 (Since: 3.0)
3762
3763 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
3770 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
3776 Since
3777 1.3
3778
3779 BlockDirtyBitmap (Object)
3780 Members
3781 node: string
3782 name of device/node which the bitmap is tracking
3783
3784 name: string
3785 name of the dirty bitmap
3786
3787 Since
3788 2.4
3789
3790 BlockDirtyBitmapAdd (Object)
3791 Members
3792 node: string
3793 name of device/node which the bitmap is tracking
3794
3795 name: string
3796 name of the dirty bitmap (must be less than 1024 bytes)
3797
3798 granularity: int (optional)
3799 the bitmap granularity, default is 64k for block-dirty-bit‐
3800 map-add
3801
3802 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
3808 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
3813 Since
3814 2.4
3815
3816 BlockDirtyBitmapMergeSource (Alternate)
3817 Members
3818 local: string
3819 name of the bitmap, attached to the same node as target bitmap.
3820
3821 external: BlockDirtyBitmap
3822 bitmap with specified node
3823
3824 Since
3825 4.1
3826
3827 BlockDirtyBitmapMerge (Object)
3828 Members
3829 node: string
3830 name of device/node which the target bitmap is tracking
3831
3832 target: string
3833 name of the destination dirty bitmap
3834
3835 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
3840 Since
3841 4.0
3842
3843 block-dirty-bitmap-add (Command)
3844 Create a dirty bitmap with a name on the node, and start tracking the
3845 writes.
3846
3847 Returns
3848 • nothing on success
3849
3850 • If node is not a valid block device or node, DeviceNotFound
3851
3852 • If name is already taken, GenericError with an explanation
3853
3854 Since
3855 2.4
3856
3857 Example
3858 -> { "execute": "block-dirty-bitmap-add",
3859 "arguments": { "node": "drive0", "name": "bitmap0" } }
3860 <- { "return": {} }
3861
3862 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
3867 Returns
3868 • nothing on success
3869
3870 • If node is not a valid block device or node, DeviceNotFound
3871
3872 • If name is not found, GenericError with an explanation
3873
3874 • if name is frozen by an operation, GenericError
3875
3876 Since
3877 2.4
3878
3879 Example
3880 -> { "execute": "block-dirty-bitmap-remove",
3881 "arguments": { "node": "drive0", "name": "bitmap0" } }
3882 <- { "return": {} }
3883
3884 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
3889 Returns
3890 • nothing on success
3891
3892 • If node is not a valid block device, DeviceNotFound
3893
3894 • If name is not found, GenericError with an explanation
3895
3896 Since
3897 2.4
3898
3899 Example
3900 -> { "execute": "block-dirty-bitmap-clear",
3901 "arguments": { "node": "drive0", "name": "bitmap0" } }
3902 <- { "return": {} }
3903
3904 block-dirty-bitmap-enable (Command)
3905 Enables a dirty bitmap so that it will begin tracking disk changes.
3906
3907 Returns
3908 • nothing on success
3909
3910 • If node is not a valid block device, DeviceNotFound
3911
3912 • If name is not found, GenericError with an explanation
3913
3914 Since
3915 4.0
3916
3917 Example
3918 -> { "execute": "block-dirty-bitmap-enable",
3919 "arguments": { "node": "drive0", "name": "bitmap0" } }
3920 <- { "return": {} }
3921
3922 block-dirty-bitmap-disable (Command)
3923 Disables a dirty bitmap so that it will stop tracking disk changes.
3924
3925 Returns
3926 • nothing on success
3927
3928 • If node is not a valid block device, DeviceNotFound
3929
3930 • If name is not found, GenericError with an explanation
3931
3932 Since
3933 4.0
3934
3935 Example
3936 -> { "execute": "block-dirty-bitmap-disable",
3937 "arguments": { "node": "drive0", "name": "bitmap0" } }
3938 <- { "return": {} }
3939
3940 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
3947 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
3951 Returns
3952 • nothing on success
3953
3954 • If node is not a valid block device, DeviceNotFound
3955
3956 • If any bitmap in bitmaps or target is not found, GenericError
3957
3958 • If any of the bitmaps have different sizes or granularities, Gener‐
3959 icError
3960
3961 Since
3962 4.0
3963
3964 Example
3965 -> { "execute": "block-dirty-bitmap-merge",
3966 "arguments": { "node": "drive0", "target": "bitmap0",
3967 "bitmaps": ["bitmap1"] } }
3968 <- { "return": {} }
3969
3970 BlockDirtyBitmapSha256 (Object)
3971 SHA256 hash of dirty bitmap data
3972
3973 Members
3974 sha256: string
3975 ASCII representation of SHA256 bitmap hash
3976
3977 Since
3978 2.10
3979
3980 x-debug-block-dirty-bitmap-sha256 (Command)
3981 Get bitmap SHA256.
3982
3983 Returns
3984 • BlockDirtyBitmapSha256 on success
3985
3986 • If node is not a valid block device, DeviceNotFound
3987
3988 • If name is not found or if hashing has failed, GenericError with an
3989 explanation
3990
3991 Since
3992 2.10
3993
3994 blockdev-mirror (Command)
3995 Start mirroring a block device's writes to a new destination.
3996
3997 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
4002 device: string
4003 The device name or node-name of a root node whose writes should
4004 be mirrored.
4005
4006 target: string
4007 the id or node-name of the block device to mirror to. This
4008 mustn't be attached to guest.
4009
4010 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
4016 speed: int (optional)
4017 the maximum speed, in bytes per second
4018
4019 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
4024 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
4030 buf-size: int (optional)
4031 maximum amount of data in flight from source to target
4032
4033 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
4038 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
4043 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
4048 copy-mode: MirrorCopyMode (optional)
4049 when to copy data to the destination; defaults to 'background'
4050 (Since: 3.0)
4051
4052 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
4059 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
4065 Returns
4066 nothing on success.
4067
4068 Since
4069 2.6
4070
4071 Example
4072 -> { "execute": "blockdev-mirror",
4073 "arguments": { "device": "ide-hd0",
4074 "target": "target0",
4075 "sync": "full" } }
4076 <- { "return": {} }
4077
4078 BlockIOThrottle (Object)
4079 A set of parameters describing block throttling.
4080
4081 Members
4082 device: string (optional)
4083 Block device name
4084
4085 id: string (optional)
4086 The name or QOM path of the guest device (since: 2.8)
4087
4088 bps: int
4089 total throughput limit in bytes per second
4090
4091 bps_rd: int
4092 read throughput limit in bytes per second
4093
4094 bps_wr: int
4095 write throughput limit in bytes per second
4096
4097 iops: int
4098 total I/O operations per second
4099
4100 iops_rd: int
4101 read I/O operations per second
4102
4103 iops_wr: int
4104 write I/O operations per second
4105
4106 bps_max: int (optional)
4107 total throughput limit during bursts, in bytes (Since 1.7)
4108
4109 bps_rd_max: int (optional)
4110 read throughput limit during bursts, in bytes (Since 1.7)
4111
4112 bps_wr_max: int (optional)
4113 write throughput limit during bursts, in bytes (Since 1.7)
4114
4115 iops_max: int (optional)
4116 total I/O operations per second during bursts, in bytes (Since
4117 1.7)
4118
4119 iops_rd_max: int (optional)
4120 read I/O operations per second during bursts, in bytes (Since
4121 1.7)
4122
4123 iops_wr_max: int (optional)
4124 write I/O operations per second during bursts, in bytes (Since
4125 1.7)
4126
4127 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
4132 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
4137 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
4142 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
4147 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
4152 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
4157 iops_size: int (optional)
4158 an I/O size in bytes (Since 1.7)
4159
4160 group: string (optional)
4161 throttle group name (Since 2.4)
4162
4163 Features
4164 deprecated
4165 Member device is deprecated. Use id instead.
4166
4167 Since
4168 1.1
4169
4170 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
4176 Members
4177 iops-total: int (optional)
4178 limit total I/O operations per second
4179
4180 iops-total-max: int (optional)
4181 I/O operations burst
4182
4183 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
4187 iops-read: int (optional)
4188 limit read operations per second
4189
4190 iops-read-max: int (optional)
4191 I/O operations read burst
4192
4193 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
4197 iops-write: int (optional)
4198 limit write operations per second
4199
4200 iops-write-max: int (optional)
4201 I/O operations write burst
4202
4203 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
4207 bps-total: int (optional)
4208 limit total bytes per second
4209
4210 bps-total-max: int (optional)
4211 total bytes burst
4212
4213 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
4217 bps-read: int (optional)
4218 limit read bytes per second
4219
4220 bps-read-max: int (optional)
4221 total bytes read burst
4222
4223 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
4227 bps-write: int (optional)
4228 limit write bytes per second
4229
4230 bps-write-max: int (optional)
4231 total bytes write burst
4232
4233 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
4237 iops-size: int (optional)
4238 when limiting by iops max size of an I/O in bytes
4239
4240 Since
4241 2.11
4242
4243 ThrottleGroupProperties (Object)
4244 Properties for throttle-group objects.
4245
4246 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
4251 Members
4252 limits: ThrottleLimits (optional)
4253 limits to apply for this throttle group
4254
4255 x-iops-total: int (optional)
4256 Not documented
4257
4258 x-iops-total-max: int (optional)
4259 Not documented
4260
4261 x-iops-total-max-length: int (optional)
4262 Not documented
4263
4264 x-iops-read: int (optional)
4265 Not documented
4266
4267 x-iops-read-max: int (optional)
4268 Not documented
4269
4270 x-iops-read-max-length: int (optional)
4271 Not documented
4272
4273 x-iops-write: int (optional)
4274 Not documented
4275
4276 x-iops-write-max: int (optional)
4277 Not documented
4278
4279 x-iops-write-max-length: int (optional)
4280 Not documented
4281
4282 x-bps-total: int (optional)
4283 Not documented
4284
4285 x-bps-total-max: int (optional)
4286 Not documented
4287
4288 x-bps-total-max-length: int (optional)
4289 Not documented
4290
4291 x-bps-read: int (optional)
4292 Not documented
4293
4294 x-bps-read-max: int (optional)
4295 Not documented
4296
4297 x-bps-read-max-length: int (optional)
4298 Not documented
4299
4300 x-bps-write: int (optional)
4301 Not documented
4302
4303 x-bps-write-max: int (optional)
4304 Not documented
4305
4306 x-bps-write-max-length: int (optional)
4307 Not documented
4308
4309 x-iops-size: int (optional)
4310 Not documented
4311
4312 Since
4313 2.11
4314
4315 block-stream (Command)
4316 Copy data from a backing file into a block device.
4317
4318 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
4324 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
4331 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
4340 On successful completion the image file is updated to drop the backing
4341 file and the BLOCK_JOB_COMPLETED event is emitted.
4342
4343 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
4347 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
4352 device: string
4353 the device or node name of the top image
4354
4355 base: string (optional)
4356 the common backing file name. It cannot be set if base-node or
4357 bottom is also set.
4358
4359 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
4363 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
4368 backing-file: string (optional)
4369 The backing file string to write into the top image. This file‐
4370 name is not validated.
4371
4372 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
4377 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
4382 speed: int (optional)
4383 the maximum speed, in bytes per second
4384
4385 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
4390 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
4395 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
4402 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
4408 Returns
4409 • Nothing on success.
4410
4411 • If device does not exist, DeviceNotFound.
4412
4413 Since
4414 1.1
4415
4416 Example
4417 -> { "execute": "block-stream",
4418 "arguments": { "device": "virtio0",
4419 "base": "/tmp/master.qcow2" } }
4420 <- { "return": {} }
4421
4422 block-job-set-speed (Command)
4423 Set maximum speed for a background block operation.
4424
4425 This command can only be issued when there is an active block job.
4426
4427 Throttling can be disabled by setting the speed to 0.
4428
4429 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
4435 speed: int
4436 the maximum speed, in bytes per second, or 0 for unlimited. De‐
4437 faults to 0.
4438
4439 Returns
4440 • Nothing on success
4441
4442 • If no background operation is active on this device, DeviceNotActive
4443
4444 Since
4445 1.1
4446
4447 block-job-cancel (Command)
4448 Stop an active background block operation.
4449
4450 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
4454 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
4458 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
4465 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
4470 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
4476 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
4482 Returns
4483 • Nothing on success
4484
4485 • If no background operation is active on this device, DeviceNotActive
4486
4487 Since
4488 1.1
4489
4490 block-job-pause (Command)
4491 Pause an active background block operation.
4492
4493 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
4497 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
4501 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
4507 Returns
4508 • Nothing on success
4509
4510 • If no background operation is active on this device, DeviceNotActive
4511
4512 Since
4513 1.3
4514
4515 block-job-resume (Command)
4516 Resume an active background block operation.
4517
4518 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
4522 This command also clears the error status of the job.
4523
4524 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
4530 Returns
4531 • Nothing on success
4532
4533 • If no background operation is active on this device, DeviceNotActive
4534
4535 Since
4536 1.3
4537
4538 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
4544 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
4551 A cancelled or paused job cannot be completed.
4552
4553 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
4559 Returns
4560 • Nothing on success
4561
4562 • If no background operation is active on this device, DeviceNotActive
4563
4564 Since
4565 1.3
4566
4567 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
4572 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
4577 Arguments
4578 id: string
4579 The job identifier.
4580
4581 Returns
4582 Nothing on success
4583
4584 Since
4585 2.12
4586
4587 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
4594 Arguments
4595 id: string
4596 The job identifier.
4597
4598 Returns
4599 Nothing on success
4600
4601 Since
4602 2.12
4603
4604 BlockdevDiscardOptions (Enum)
4605 Determines how to handle discard requests.
4606
4607 Values
4608 ignore Ignore the request
4609
4610 unmap Forward as an unmap request
4611
4612 Since
4613 2.9
4614
4615 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
4619 Values
4620 off Disabled (default)
4621
4622 on Enabled
4623
4624 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
4628 Since
4629 2.1
4630
4631 BlockdevAioOptions (Enum)
4632 Selects the AIO backend to handle I/O requests
4633
4634 Values
4635 threads
4636 Use qemu's thread pool
4637
4638 native Use native AIO backend (only Linux and Windows)
4639
4640 io_uring (If: defined(CONFIG_LINUX_IO_URING))
4641 Use linux io_uring (since 5.0)
4642
4643 Since
4644 2.9
4645
4646 BlockdevCacheOptions (Object)
4647 Includes cache-related options for block devices
4648
4649 Members
4650 direct: boolean (optional)
4651 enables use of O_DIRECT (bypass the host page cache; default:
4652 false)
4653
4654 no-flush: boolean (optional)
4655 ignore any flush requests for the device (default: false)
4656
4657 Since
4658 2.9
4659
4660 BlockdevDriver (Enum)
4661 Drivers that are supported in block device operations.
4662
4663 Values
4664 throttle
4665 Since 2.11
4666
4667 nvme Since 2.12
4668
4669 copy-on-read
4670 Since 3.0
4671
4672 blklogwrites
4673 Since 3.0
4674
4675 blkreplay
4676 Since 4.2
4677
4678 compress
4679 Since 5.0
4680
4681 blkdebug
4682 Not documented
4683
4684 blkverify
4685 Not documented
4686
4687 bochs Not documented
4688
4689 cloop Not documented
4690
4691 dmg Not documented
4692
4693 file Not documented
4694
4695 ftp Not documented
4696
4697 ftps Not documented
4698
4699 gluster
4700 Not documented
4701
4702 host_cdrom (If: defined(HAVE_HOST_BLOCK_DEVICE))
4703 Not documented
4704
4705 host_device (If: defined(HAVE_HOST_BLOCK_DEVICE))
4706 Not documented
4707
4708 http Not documented
4709
4710 https Not documented
4711
4712 iscsi Not documented
4713
4714 luks Not documented
4715
4716 nbd Not documented
4717
4718 nfs Not documented
4719
4720 null-aio
4721 Not documented
4722
4723 null-co
4724 Not documented
4725
4726 parallels
4727 Not documented
4728
4729 preallocate
4730 Not documented
4731
4732 qcow Not documented
4733
4734 qcow2 Not documented
4735
4736 qed Not documented
4737
4738 quorum Not documented
4739
4740 raw Not documented
4741
4742 rbd Not documented
4743
4744 replication (If: defined(CONFIG_REPLICATION))
4745 Not documented
4746
4747 ssh Not documented
4748
4749 vdi Not documented
4750
4751 vhdx Not documented
4752
4753 vmdk Not documented
4754
4755 vpc Not documented
4756
4757 vvfat Not documented
4758
4759 Since
4760 2.9
4761
4762 BlockdevOptionsFile (Object)
4763 Driver specific block device options for the file backend.
4764
4765 Members
4766 filename: string
4767 path to the image file
4768
4769 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
4774 aio: BlockdevAioOptions (optional)
4775 AIO backend (default: threads) (since: 2.8)
4776
4777 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
4782 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
4788 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
4793 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
4802 Since
4803 2.9
4804
4805 BlockdevOptionsNull (Object)
4806 Driver specific block device options for the null backend.
4807
4808 Members
4809 size: int (optional)
4810 size of the device in bytes.
4811
4812 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
4816 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
4820 Since
4821 2.9
4822
4823 BlockdevOptionsNVMe (Object)
4824 Driver specific block device options for the NVMe backend.
4825
4826 Members
4827 device: string
4828 PCI controller address of the NVMe device in format hhhh:bb:ss.f
4829 (host:bus:slot.function)
4830
4831 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
4836 Since
4837 2.12
4838
4839 BlockdevOptionsVVFAT (Object)
4840 Driver specific block device options for the vvfat protocol.
4841
4842 Members
4843 dir: string
4844 directory to be exported as FAT image
4845
4846 fat-type: int (optional)
4847 FAT type: 12, 16 or 32
4848
4849 floppy: boolean (optional)
4850 whether to export a floppy image (true) or partitioned hard disk
4851 (false; default)
4852
4853 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
4859 rw: boolean (optional)
4860 whether to allow write operations (default: false)
4861
4862 Since
4863 2.9
4864
4865 BlockdevOptionsGenericFormat (Object)
4866 Driver specific block device options for image format that have no op‐
4867 tion besides their data source.
4868
4869 Members
4870 file: BlockdevRef
4871 reference to or definition of the data source block device
4872
4873 Since
4874 2.9
4875
4876 BlockdevOptionsLUKS (Object)
4877 Driver specific block device options for LUKS.
4878
4879 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
4885 The members of BlockdevOptionsGenericFormat
4886
4887 Since
4888 2.9
4889
4890 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
4894 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
4900 The members of BlockdevOptionsGenericFormat
4901
4902 Since
4903 2.9
4904
4905 Qcow2OverlapCheckMode (Enum)
4906 General overlap check modes.
4907
4908 Values
4909 none Do not perform any checks
4910
4911 constant
4912 Perform only checks which can be done in constant time and with‐
4913 out reading anything from disk
4914
4915 cached Perform only checks which can be done without reading anything
4916 from disk
4917
4918 all Perform all available overlap checks
4919
4920 Since
4921 2.9
4922
4923 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
4928 Members
4929 template: Qcow2OverlapCheckMode (optional)
4930 Specifies a template mode which can be adjusted using the other
4931 flags, defaults to 'cached'
4932
4933 bitmap-directory: boolean (optional)
4934 since 3.0
4935
4936 main-header: boolean (optional)
4937 Not documented
4938
4939 active-l1: boolean (optional)
4940 Not documented
4941
4942 active-l2: boolean (optional)
4943 Not documented
4944
4945 refcount-table: boolean (optional)
4946 Not documented
4947
4948 refcount-block: boolean (optional)
4949 Not documented
4950
4951 snapshot-table: boolean (optional)
4952 Not documented
4953
4954 inactive-l1: boolean (optional)
4955 Not documented
4956
4957 inactive-l2: boolean (optional)
4958 Not documented
4959
4960 Since
4961 2.9
4962
4963 Qcow2OverlapChecks (Alternate)
4964 Specifies which metadata structures should be guarded against unin‐
4965 tended overwriting.
4966
4967 Members
4968 flags: Qcow2OverlapCheckFlags
4969 set of flags for separate specification of each metadata struc‐
4970 ture type
4971
4972 mode: Qcow2OverlapCheckMode
4973 named mode which chooses a specific set of flags
4974
4975 Since
4976 2.9
4977
4978 BlockdevQcowEncryptionFormat (Enum)
4979 Values
4980 aes AES-CBC with plain64 initialization vectors
4981
4982 Since
4983 2.10
4984
4985 BlockdevQcowEncryption (Object)
4986 Members
4987 format: BlockdevQcowEncryptionFormat
4988 Not documented
4989
4990 The members of QCryptoBlockOptionsQCow when format is "aes"
4991
4992 Since
4993 2.10
4994
4995 BlockdevOptionsQcow (Object)
4996 Driver specific block device options for qcow.
4997
4998 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
5003 The members of BlockdevOptionsGenericCOWFormat
5004
5005 Since
5006 2.10
5007
5008 BlockdevQcow2EncryptionFormat (Enum)
5009 Values
5010 aes AES-CBC with plain64 initialization vectors
5011
5012 luks Not documented
5013
5014 Since
5015 2.10
5016
5017 BlockdevQcow2Encryption (Object)
5018 Members
5019 format: BlockdevQcow2EncryptionFormat
5020 Not documented
5021
5022 The members of QCryptoBlockOptionsQCow when format is "aes"
5023
5024 The members of QCryptoBlockOptionsLUKS when format is "luks"
5025
5026 Since
5027 2.10
5028
5029 BlockdevOptionsPreallocate (Object)
5030 Filter driver intended to be inserted between format and protocol node
5031 and do preallocation in protocol node on write.
5032
5033 Members
5034 prealloc-align: int (optional)
5035 on preallocation, align file length to this number, default
5036 1048576 (1M)
5037
5038 prealloc-size: int (optional)
5039 how much to preallocate, default 134217728 (128M)
5040
5041 The members of BlockdevOptionsGenericFormat
5042
5043 Since
5044 6.0
5045
5046 BlockdevOptionsQcow2 (Object)
5047 Driver specific block device options for qcow2.
5048
5049 Members
5050 lazy-refcounts: boolean (optional)
5051 whether to enable the lazy refcounts feature (default is taken
5052 from the image file)
5053
5054 pass-discard-request: boolean (optional)
5055 whether discard requests to the qcow2 device should be forwarded
5056 to the data source
5057
5058 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
5063 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
5067 overlap-check: Qcow2OverlapChecks (optional)
5068 which overlap checks to perform for writes to the image, de‐
5069 faults to 'cached' (since 2.2)
5070
5071 cache-size: int (optional)
5072 the maximum total size of the L2 table and refcount block caches
5073 in bytes (since 2.2)
5074
5075 l2-cache-size: int (optional)
5076 the maximum size of the L2 table cache in bytes (since 2.2)
5077
5078 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
5083 refcount-cache-size: int (optional)
5084 the maximum size of the refcount block cache in bytes (since
5085 2.2)
5086
5087 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
5092 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
5096 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
5102 The members of BlockdevOptionsGenericCOWFormat
5103
5104 Since
5105 2.9
5106
5107 SshHostKeyCheckMode (Enum)
5108 Values
5109 none Don't check the host key at all
5110
5111 hash Compare the host key with a given hash
5112
5113 known_hosts
5114 Check the host key against the known_hosts file
5115
5116 Since
5117 2.12
5118
5119 SshHostKeyCheckHashType (Enum)
5120 Values
5121 md5 The given hash is an md5 hash
5122
5123 sha1 The given hash is an sha1 hash
5124
5125 sha256 The given hash is an sha256 hash
5126
5127 Since
5128 2.12
5129
5130 SshHostKeyHash (Object)
5131 Members
5132 type: SshHostKeyCheckHashType
5133 The hash algorithm used for the hash
5134
5135 hash: string
5136 The expected hash value
5137
5138 Since
5139 2.12
5140
5141 SshHostKeyCheck (Object)
5142 Members
5143 mode: SshHostKeyCheckMode
5144 Not documented
5145
5146 The members of SshHostKeyHash when mode is "hash"
5147
5148 Since
5149 2.12
5150
5151 BlockdevOptionsSsh (Object)
5152 Members
5153 server: InetSocketAddress
5154 host address
5155
5156 path: string
5157 path to the image on the host
5158
5159 user: string (optional)
5160 user as which to connect, defaults to current local user name
5161
5162 host-key-check: SshHostKeyCheck (optional)
5163 Defines how and what to check the host key against (default:
5164 known_hosts)
5165
5166 Since
5167 2.9
5168
5169 BlkdebugEvent (Enum)
5170 Trigger events supported by blkdebug.
5171
5172 Values
5173 l1_shrink_write_table
5174 write zeros to the l1 table to shrink image. (since 2.11)
5175
5176 l1_shrink_free_l2_clusters
5177 discard the l2 tables. (since 2.11)
5178
5179 cor_write
5180 a write due to copy-on-read (since 2.11)
5181
5182 cluster_alloc_space
5183 an allocation of file space for a cluster (since 4.1)
5184
5185 none triggers once at creation of the blkdebug node (since 4.1)
5186
5187 l1_update
5188 Not documented
5189
5190 l1_grow_alloc_table
5191 Not documented
5192
5193 l1_grow_write_table
5194 Not documented
5195
5196 l1_grow_activate_table
5197 Not documented
5198
5199 l2_load
5200 Not documented
5201
5202 l2_update
5203 Not documented
5204
5205 l2_update_compressed
5206 Not documented
5207
5208 l2_alloc_cow_read
5209 Not documented
5210
5211 l2_alloc_write
5212 Not documented
5213
5214 read_aio
5215 Not documented
5216
5217 read_backing_aio
5218 Not documented
5219
5220 read_compressed
5221 Not documented
5222
5223 write_aio
5224 Not documented
5225
5226 write_compressed
5227 Not documented
5228
5229 vmstate_load
5230 Not documented
5231
5232 vmstate_save
5233 Not documented
5234
5235 cow_read
5236 Not documented
5237
5238 cow_write
5239 Not documented
5240
5241 reftable_load
5242 Not documented
5243
5244 reftable_grow
5245 Not documented
5246
5247 reftable_update
5248 Not documented
5249
5250 refblock_load
5251 Not documented
5252
5253 refblock_update
5254 Not documented
5255
5256 refblock_update_part
5257 Not documented
5258
5259 refblock_alloc
5260 Not documented
5261
5262 refblock_alloc_hookup
5263 Not documented
5264
5265 refblock_alloc_write
5266 Not documented
5267
5268 refblock_alloc_write_blocks
5269 Not documented
5270
5271 refblock_alloc_write_table
5272 Not documented
5273
5274 refblock_alloc_switch_table
5275 Not documented
5276
5277 cluster_alloc
5278 Not documented
5279
5280 cluster_alloc_bytes
5281 Not documented
5282
5283 cluster_free
5284 Not documented
5285
5286 flush_to_os
5287 Not documented
5288
5289 flush_to_disk
5290 Not documented
5291
5292 pwritev_rmw_head
5293 Not documented
5294
5295 pwritev_rmw_after_head
5296 Not documented
5297
5298 pwritev_rmw_tail
5299 Not documented
5300
5301 pwritev_rmw_after_tail
5302 Not documented
5303
5304 pwritev
5305 Not documented
5306
5307 pwritev_zero
5308 Not documented
5309
5310 pwritev_done
5311 Not documented
5312
5313 empty_image_prepare
5314 Not documented
5315
5316 Since
5317 2.9
5318
5319 BlkdebugIOType (Enum)
5320 Kinds of I/O that blkdebug can inject errors in.
5321
5322 Values
5323 read .bdrv_co_preadv()
5324
5325 write .bdrv_co_pwritev()
5326
5327 write-zeroes
5328 .bdrv_co_pwrite_zeroes()
5329
5330 discard
5331 .bdrv_co_pdiscard()
5332
5333 flush .bdrv_co_flush_to_disk()
5334
5335 block-status
5336 .bdrv_co_block_status()
5337
5338 Since
5339 4.1
5340
5341 BlkdebugInjectErrorOptions (Object)
5342 Describes a single error injection for blkdebug.
5343
5344 Members
5345 event: BlkdebugEvent
5346 trigger event
5347
5348 state: int (optional)
5349 the state identifier blkdebug needs to be in to actually trigger
5350 the event; defaults to "any"
5351
5352 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
5357 errno: int (optional)
5358 error identifier (errno) to be returned; defaults to EIO
5359
5360 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
5364 once: boolean (optional)
5365 disables further events after this one has been triggered; de‐
5366 faults to false
5367
5368 immediately: boolean (optional)
5369 fail immediately; defaults to false
5370
5371 Since
5372 2.9
5373
5374 BlkdebugSetStateOptions (Object)
5375 Describes a single state-change event for blkdebug.
5376
5377 Members
5378 event: BlkdebugEvent
5379 trigger event
5380
5381 state: int (optional)
5382 the current state identifier blkdebug needs to be in; defaults
5383 to "any"
5384
5385 new_state: int
5386 the state identifier blkdebug is supposed to assume if this
5387 event is triggered
5388
5389 Since
5390 2.9
5391
5392 BlockdevOptionsBlkdebug (Object)
5393 Driver specific block device options for blkdebug.
5394
5395 Members
5396 image: BlockdevRef
5397 underlying raw block device (or image file)
5398
5399 config: string (optional)
5400 filename of the configuration file
5401
5402 align: int (optional)
5403 required alignment for requests in bytes, must be positive power
5404 of 2, or 0 for default
5405
5406 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
5411 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
5417 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
5423 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
5429 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
5435 inject-error: array of BlkdebugInjectErrorOptions (optional)
5436 array of error injection descriptions
5437
5438 set-state: array of BlkdebugSetStateOptions (optional)
5439 array of state-change descriptions
5440
5441 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
5446 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
5451 Since
5452 2.9
5453
5454 BlockdevOptionsBlklogwrites (Object)
5455 Driver specific block device options for blklogwrites.
5456
5457 Members
5458 file: BlockdevRef
5459 block device
5460
5461 log: BlockdevRef
5462 block device used to log writes to file
5463
5464 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
5468 log-append: boolean (optional)
5469 append to an existing log (default: false)
5470
5471 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
5475 Since
5476 3.0
5477
5478 BlockdevOptionsBlkverify (Object)
5479 Driver specific block device options for blkverify.
5480
5481 Members
5482 test: BlockdevRef
5483 block device to be tested
5484
5485 raw: BlockdevRef
5486 raw image used for verification
5487
5488 Since
5489 2.9
5490
5491 BlockdevOptionsBlkreplay (Object)
5492 Driver specific block device options for blkreplay.
5493
5494 Members
5495 image: BlockdevRef
5496 disk image which should be controlled with blkreplay
5497
5498 Since
5499 4.2
5500
5501 QuorumReadPattern (Enum)
5502 An enumeration of quorum read patterns.
5503
5504 Values
5505 quorum read all the children and do a quorum vote on reads
5506
5507 fifo read only from the first child that has not failed
5508
5509 Since
5510 2.9
5511
5512 BlockdevOptionsQuorum (Object)
5513 Driver specific block device options for Quorum
5514
5515 Members
5516 blkverify: boolean (optional)
5517
5518 true if the driver must print content mismatch
5519 set to false by default
5520
5521 children: array of BlockdevRef
5522 the children block devices to use
5523
5524 vote-threshold: int
5525 the vote limit under which a read will fail
5526
5527 rewrite-corrupted: boolean (optional)
5528 rewrite corrupted data when quorum is reached (Since 2.1)
5529
5530 read-pattern: QuorumReadPattern (optional)
5531 choose read pattern and set to quorum by default (Since 2.2)
5532
5533 Since
5534 2.9
5535
5536 BlockdevOptionsGluster (Object)
5537 Driver specific block device options for Gluster
5538
5539 Members
5540 volume: string
5541 name of gluster volume where VM image resides
5542
5543 path: string
5544 absolute path to image file in gluster volume
5545
5546 server: array of SocketAddress
5547 gluster servers description
5548
5549 debug: int (optional)
5550 libgfapi log level (default '4' which is Error) (Since 2.8)
5551
5552 logfile: string (optional)
5553 libgfapi log file (default /dev/stderr) (Since 2.8)
5554
5555 Since
5556 2.9
5557
5558 IscsiTransport (Enum)
5559 An enumeration of libiscsi transport types
5560
5561 Values
5562 tcp Not documented
5563
5564 iser Not documented
5565
5566 Since
5567 2.9
5568
5569 IscsiHeaderDigest (Enum)
5570 An enumeration of header digests supported by libiscsi
5571
5572 Values
5573 crc32c Not documented
5574
5575 none Not documented
5576
5577 crc32c-none
5578 Not documented
5579
5580 none-crc32c
5581 Not documented
5582
5583 Since
5584 2.9
5585
5586 BlockdevOptionsIscsi (Object)
5587 Members
5588 transport: IscsiTransport
5589 The iscsi transport type
5590
5591 portal: string
5592 The address of the iscsi portal
5593
5594 target: string
5595 The target iqn name
5596
5597 lun: int (optional)
5598 LUN to connect to. Defaults to 0.
5599
5600 user: string (optional)
5601 User name to log in with. If omitted, no CHAP authentication is
5602 performed.
5603
5604 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
5608 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
5613 header-digest: IscsiHeaderDigest (optional)
5614 The desired header digest. Defaults to none-crc32c.
5615
5616 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
5621 Since
5622 2.9
5623
5624 RbdAuthMode (Enum)
5625 Values
5626 cephx Not documented
5627
5628 none Not documented
5629
5630 Since
5631 3.0
5632
5633 RbdImageEncryptionFormat (Enum)
5634 Values
5635 luks Not documented
5636
5637 luks2 Not documented
5638
5639 Since
5640 6.1
5641
5642 RbdEncryptionOptionsLUKSBase (Object)
5643 Members
5644 key-secret: string
5645 ID of a QCryptoSecret object providing a passphrase for unlock‐
5646 ing the encryption
5647
5648 Since
5649 6.1
5650
5651 RbdEncryptionCreateOptionsLUKSBase (Object)
5652 Members
5653 cipher-alg: QCryptoCipherAlgorithm (optional)
5654 The encryption algorithm
5655
5656 The members of RbdEncryptionOptionsLUKSBase
5657
5658 Since
5659 6.1
5660
5661 RbdEncryptionOptionsLUKS (Object)
5662 Members
5663 The members of RbdEncryptionOptionsLUKSBase
5664
5665 Since
5666 6.1
5667
5668 RbdEncryptionOptionsLUKS2 (Object)
5669 Members
5670 The members of RbdEncryptionOptionsLUKSBase
5671
5672 Since
5673 6.1
5674
5675 RbdEncryptionCreateOptionsLUKS (Object)
5676 Members
5677 The members of RbdEncryptionCreateOptionsLUKSBase
5678
5679 Since
5680 6.1
5681
5682 RbdEncryptionCreateOptionsLUKS2 (Object)
5683 Members
5684 The members of RbdEncryptionCreateOptionsLUKSBase
5685
5686 Since
5687 6.1
5688
5689 RbdEncryptionOptions (Object)
5690 Members
5691 format: RbdImageEncryptionFormat
5692 Not documented
5693
5694 The members of RbdEncryptionOptionsLUKS when format is "luks"
5695
5696 The members of RbdEncryptionOptionsLUKS2 when format is "luks2"
5697
5698 Since
5699 6.1
5700
5701 RbdEncryptionCreateOptions (Object)
5702 Members
5703 format: RbdImageEncryptionFormat
5704 Not documented
5705
5706 The members of RbdEncryptionCreateOptionsLUKS when format is "luks"
5707
5708 The members of RbdEncryptionCreateOptionsLUKS2 when format is "luks2"
5709
5710 Since
5711 6.1
5712
5713 BlockdevOptionsRbd (Object)
5714 Members
5715 pool: string
5716 Ceph pool name.
5717
5718 namespace: string (optional)
5719 Rados namespace name in the Ceph pool. (Since 5.0)
5720
5721 image: string
5722 Image name in the Ceph pool.
5723
5724 conf: string (optional)
5725 path to Ceph configuration file. Values in the configuration
5726 file will be overridden by options specified via QAPI.
5727
5728 snapshot: string (optional)
5729 Ceph snapshot name.
5730
5731 encrypt: RbdEncryptionOptions (optional)
5732 Image encryption options. (Since 6.1)
5733
5734 user: string (optional)
5735 Ceph id name.
5736
5737 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
5741 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
5746 server: array of InetSocketAddressBase (optional)
5747 Monitor host address and port. This maps to the "mon_host" Ceph
5748 option.
5749
5750 Since
5751 2.9
5752
5753 ReplicationMode (Enum)
5754 An enumeration of replication modes.
5755
5756 Values
5757 primary
5758 Primary mode, the vm's state will be sent to secondary QEMU.
5759
5760 secondary
5761 Secondary mode, receive the vm's state from primary QEMU.
5762
5763 Since
5764 2.9
5765
5766 If
5767 defined(CONFIG_REPLICATION)
5768
5769 BlockdevOptionsReplication (Object)
5770 Driver specific block device options for replication
5771
5772 Members
5773 mode: ReplicationMode
5774 the replication mode
5775
5776 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
5781 The members of BlockdevOptionsGenericFormat
5782
5783 Since
5784 2.9
5785
5786 If
5787 defined(CONFIG_REPLICATION)
5788
5789 NFSTransport (Enum)
5790 An enumeration of NFS transport types
5791
5792 Values
5793 inet TCP transport
5794
5795 Since
5796 2.9
5797
5798 NFSServer (Object)
5799 Captures the address of the socket
5800
5801 Members
5802 type: NFSTransport
5803 transport type used for NFS (only TCP supported)
5804
5805 host: string
5806 host address for NFS server
5807
5808 Since
5809 2.9
5810
5811 BlockdevOptionsNfs (Object)
5812 Driver specific block device option for NFS
5813
5814 Members
5815 server: NFSServer
5816 host address
5817
5818 path: string
5819 path of the image on the host
5820
5821 user: int (optional)
5822 UID value to use when talking to the server (defaults to 65534
5823 on Windows and getuid() on unix)
5824
5825 group: int (optional)
5826 GID value to use when talking to the server (defaults to 65534
5827 on Windows and getgid() in unix)
5828
5829 tcp-syn-count: int (optional)
5830 number of SYNs during the session establishment (defaults to
5831 libnfs default)
5832
5833 readahead-size: int (optional)
5834 set the readahead size in bytes (defaults to libnfs default)
5835
5836 page-cache-size: int (optional)
5837 set the pagecache size in bytes (defaults to libnfs default)
5838
5839 debug: int (optional)
5840 set the NFS debug level (max 2) (defaults to libnfs default)
5841
5842 Since
5843 2.9
5844
5845 BlockdevOptionsCurlBase (Object)
5846 Driver specific block device options shared by all protocols supported
5847 by the curl backend.
5848
5849 Members
5850 url: string
5851 URL of the image file
5852
5853 readahead: int (optional)
5854 Size of the read-ahead cache; must be a multiple of 512 (de‐
5855 faults to 256 kB)
5856
5857 timeout: int (optional)
5858 Timeout for connections, in seconds (defaults to 5)
5859
5860 username: string (optional)
5861 Username for authentication (defaults to none)
5862
5863 password-secret: string (optional)
5864 ID of a QCryptoSecret object providing a password for authenti‐
5865 cation (defaults to no password)
5866
5867 proxy-username: string (optional)
5868 Username for proxy authentication (defaults to none)
5869
5870 proxy-password-secret: string (optional)
5871 ID of a QCryptoSecret object providing a password for proxy au‐
5872 thentication (defaults to no password)
5873
5874 Since
5875 2.9
5876
5877 BlockdevOptionsCurlHttp (Object)
5878 Driver specific block device options for HTTP connections over the curl
5879 backend. URLs must start with "http://".
5880
5881 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
5887 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
5891 The members of BlockdevOptionsCurlBase
5892
5893 Since
5894 2.9
5895
5896 BlockdevOptionsCurlHttps (Object)
5897 Driver specific block device options for HTTPS connections over the
5898 curl backend. URLs must start with "https://".
5899
5900 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
5906 sslverify: boolean (optional)
5907 Whether to verify the SSL certificate's validity (defaults to
5908 true)
5909
5910 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
5914 The members of BlockdevOptionsCurlBase
5915
5916 Since
5917 2.9
5918
5919 BlockdevOptionsCurlFtp (Object)
5920 Driver specific block device options for FTP connections over the curl
5921 backend. URLs must start with "ftp://".
5922
5923 Members
5924 The members of BlockdevOptionsCurlBase
5925
5926 Since
5927 2.9
5928
5929 BlockdevOptionsCurlFtps (Object)
5930 Driver specific block device options for FTPS connections over the curl
5931 backend. URLs must start with "ftps://".
5932
5933 Members
5934 sslverify: boolean (optional)
5935 Whether to verify the SSL certificate's validity (defaults to
5936 true)
5937
5938 The members of BlockdevOptionsCurlBase
5939
5940 Since
5941 2.9
5942
5943 BlockdevOptionsNbd (Object)
5944 Driver specific block device options for NBD.
5945
5946 Members
5947 server: SocketAddress
5948 NBD server address
5949
5950 export: string (optional)
5951 export name
5952
5953 tls-creds: string (optional)
5954 TLS credentials ID
5955
5956 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
5963 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
5971 Since
5972 2.9
5973
5974 BlockdevOptionsRaw (Object)
5975 Driver specific block device options for the raw driver.
5976
5977 Members
5978 offset: int (optional)
5979 position where the block device starts
5980
5981 size: int (optional)
5982 the assumed size of the device
5983
5984 The members of BlockdevOptionsGenericFormat
5985
5986 Since
5987 2.9
5988
5989 BlockdevOptionsThrottle (Object)
5990 Driver specific block device options for the throttle driver
5991
5992 Members
5993 throttle-group: string
5994 the name of the throttle-group object to use. It must already
5995 exist.
5996
5997 file: BlockdevRef
5998 reference to or definition of the data source block device
5999
6000 Since
6001 2.11
6002
6003 BlockdevOptionsCor (Object)
6004 Driver specific block device options for the copy-on-read driver.
6005
6006 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
6014 The members of BlockdevOptionsGenericFormat
6015
6016 Since
6017 6.0
6018
6019 BlockdevOptions (Object)
6020 Options for creating a block device. Many options are available for
6021 all block devices, independent of the block driver:
6022
6023 Members
6024 driver: BlockdevDriver
6025 block driver name
6026
6027 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
6034 discard: BlockdevDiscardOptions (optional)
6035 discard-related options (default: ignore)
6036
6037 cache: BlockdevCacheOptions (optional)
6038 cache-related options
6039
6040 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
6047 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
6054 detect-zeroes: BlockdevDetectZeroesOptions (optional)
6055 detect and optimize zero writes (Since 2.1) (default: off)
6056
6057 force-share: boolean (optional)
6058 force share all permission on added nodes. Requires
6059 read-only=true. (Since 2.10)
6060
6061 The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
6062
6063 The members of BlockdevOptionsBlklogwrites when driver is "blklog‐
6064 writes"
6065
6066 The members of BlockdevOptionsBlkverify when driver is "blkverify"
6067
6068 The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
6069
6070 The members of BlockdevOptionsGenericFormat when driver is "bochs"
6071
6072 The members of BlockdevOptionsGenericFormat when driver is "cloop"
6073
6074 The members of BlockdevOptionsGenericFormat when driver is "compress"
6075
6076 The members of BlockdevOptionsCor when driver is "copy-on-read"
6077
6078 The members of BlockdevOptionsGenericFormat when driver is "dmg"
6079
6080 The members of BlockdevOptionsFile when driver is "file"
6081
6082 The members of BlockdevOptionsCurlFtp when driver is "ftp"
6083
6084 The members of BlockdevOptionsCurlFtps when driver is "ftps"
6085
6086 The members of BlockdevOptionsGluster when driver is "gluster"
6087
6088 The members of BlockdevOptionsFile when driver is "host_cdrom" (If: de‐
6089 fined(HAVE_HOST_BLOCK_DEVICE))
6090
6091 The members of BlockdevOptionsFile when driver is "host_device" (If:
6092 defined(HAVE_HOST_BLOCK_DEVICE))
6093
6094 The members of BlockdevOptionsCurlHttp when driver is "http"
6095
6096 The members of BlockdevOptionsCurlHttps when driver is "https"
6097
6098 The members of BlockdevOptionsIscsi when driver is "iscsi"
6099
6100 The members of BlockdevOptionsLUKS when driver is "luks"
6101
6102 The members of BlockdevOptionsNbd when driver is "nbd"
6103
6104 The members of BlockdevOptionsNfs when driver is "nfs"
6105
6106 The members of BlockdevOptionsNull when driver is "null-aio"
6107
6108 The members of BlockdevOptionsNull when driver is "null-co"
6109
6110 The members of BlockdevOptionsNVMe when driver is "nvme"
6111
6112 The members of BlockdevOptionsGenericFormat when driver is "parallels"
6113
6114 The members of BlockdevOptionsPreallocate when driver is "preallocate"
6115
6116 The members of BlockdevOptionsQcow2 when driver is "qcow2"
6117
6118 The members of BlockdevOptionsQcow when driver is "qcow"
6119
6120 The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
6121
6122 The members of BlockdevOptionsQuorum when driver is "quorum"
6123
6124 The members of BlockdevOptionsRaw when driver is "raw"
6125
6126 The members of BlockdevOptionsRbd when driver is "rbd"
6127
6128 The members of BlockdevOptionsReplication when driver is "replication"
6129 (If: defined(CONFIG_REPLICATION))
6130
6131 The members of BlockdevOptionsSsh when driver is "ssh"
6132
6133 The members of BlockdevOptionsThrottle when driver is "throttle"
6134
6135 The members of BlockdevOptionsGenericFormat when driver is "vdi"
6136
6137 The members of BlockdevOptionsGenericFormat when driver is "vhdx"
6138
6139 The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
6140
6141 The members of BlockdevOptionsGenericFormat when driver is "vpc"
6142
6143 The members of BlockdevOptionsVVFAT when driver is "vvfat"
6144 Remaining options are determined by the block driver.
6145
6146 Since
6147 2.9
6148
6149 BlockdevRef (Alternate)
6150 Reference to a block device.
6151
6152 Members
6153 definition: BlockdevOptions
6154 defines a new block device inline
6155
6156 reference: string
6157 references the ID of an existing block device
6158
6159 Since
6160 2.9
6161
6162 BlockdevRefOrNull (Alternate)
6163 Reference to a block device.
6164
6165 Members
6166 definition: BlockdevOptions
6167 defines a new block device inline
6168
6169 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
6174 null: null
6175 No block device should be referenced (since 2.10)
6176
6177 Since
6178 2.9
6179
6180 blockdev-add (Command)
6181 Creates a new block device.
6182
6183 Arguments
6184 The members of BlockdevOptions
6185
6186 Since
6187 2.9
6188
6189 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
6203 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
6226 <- { "return": {} }
6227
6228 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
6236 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
6243 In the case of options that refer to child nodes, the behavior of this
6244 command depends on the value:
6245
6246 1. A set of options (BlockdevOptions): the child is reopened with
6247 the specified set of options.
6248
6249 2. A reference to the current child: the child is reopened using its
6250 existing set of options.
6251
6252 3. A reference to a different node: the current child is replaced
6253 with the specified one.
6254
6255 4. NULL: the current child (if any) is detached.
6256
6257 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
6260 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
6264 Arguments
6265 options: array of BlockdevOptions
6266 Not documented
6267
6268 Since
6269 6.1
6270
6271 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
6276 Arguments
6277 node-name: string
6278 Name of the graph node to delete.
6279
6280 Since
6281 2.9
6282
6283 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
6296 -> { "execute": "blockdev-del",
6297 "arguments": { "node-name": "node0" }
6298 }
6299 <- { "return": {} }
6300
6301 BlockdevCreateOptionsFile (Object)
6302 Driver specific image creation options for file.
6303
6304 Members
6305 filename: string
6306 Filename for the new image file
6307
6308 size: int
6309 Size of the virtual disk in bytes
6310
6311 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
6316 nocow: boolean (optional)
6317 Turn off copy-on-write (valid only on btrfs; default: off)
6318
6319 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
6323 Since
6324 2.12
6325
6326 BlockdevCreateOptionsGluster (Object)
6327 Driver specific image creation options for gluster.
6328
6329 Members
6330 location: BlockdevOptionsGluster
6331 Where to store the new image file
6332
6333 size: int
6334 Size of the virtual disk in bytes
6335
6336 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
6341 Since
6342 2.12
6343
6344 BlockdevCreateOptionsLUKS (Object)
6345 Driver specific image creation options for LUKS.
6346
6347 Members
6348 file: BlockdevRef
6349 Node to create the image format on
6350
6351 size: int
6352 Size of the virtual disk in bytes
6353
6354 preallocation: PreallocMode (optional)
6355 Preallocation mode for the new image (since: 4.2) (default: off;
6356 allowed values: off, metadata, falloc, full)
6357
6358 The members of QCryptoBlockCreateOptionsLUKS
6359
6360 Since
6361 2.12
6362
6363 BlockdevCreateOptionsNfs (Object)
6364 Driver specific image creation options for NFS.
6365
6366 Members
6367 location: BlockdevOptionsNfs
6368 Where to store the new image file
6369
6370 size: int
6371 Size of the virtual disk in bytes
6372
6373 Since
6374 2.12
6375
6376 BlockdevCreateOptionsParallels (Object)
6377 Driver specific image creation options for parallels.
6378
6379 Members
6380 file: BlockdevRef
6381 Node to create the image format on
6382
6383 size: int
6384 Size of the virtual disk in bytes
6385
6386 cluster-size: int (optional)
6387 Cluster size in bytes (default: 1 MB)
6388
6389 Since
6390 2.12
6391
6392 BlockdevCreateOptionsQcow (Object)
6393 Driver specific image creation options for qcow.
6394
6395 Members
6396 file: BlockdevRef
6397 Node to create the image format on
6398
6399 size: int
6400 Size of the virtual disk in bytes
6401
6402 backing-file: string (optional)
6403 File name of the backing file if a backing file should be used
6404
6405 encrypt: QCryptoBlockCreateOptions (optional)
6406 Encryption options if the image should be encrypted
6407
6408 Since
6409 2.12
6410
6411 BlockdevQcow2Version (Enum)
6412 Values
6413 v2 The original QCOW2 format as introduced in qemu 0.10 (version 2)
6414
6415 v3 The extended QCOW2 format as introduced in qemu 1.1 (version 3)
6416
6417 Since
6418 2.12
6419
6420 Qcow2CompressionType (Enum)
6421 Compression type used in qcow2 image file
6422
6423 Values
6424 zlib zlib compression, see <http://zlib.net/>
6425
6426 zstd (If: defined(CONFIG_ZSTD))
6427 zstd compression, see <http://github.com/facebook/zstd>
6428
6429 Since
6430 5.1
6431
6432 BlockdevCreateOptionsQcow2 (Object)
6433 Driver specific image creation options for qcow2.
6434
6435 Members
6436 file: BlockdevRef
6437 Node to create the image format on
6438
6439 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
6444 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
6449 extended-l2: boolean (optional)
6450 True to make the image have extended L2 entries (default: false;
6451 since 5.2)
6452
6453 size: int
6454 Size of the virtual disk in bytes
6455
6456 version: BlockdevQcow2Version (optional)
6457 Compatibility level (default: v3)
6458
6459 backing-file: string (optional)
6460 File name of the backing file if a backing file should be used
6461
6462 backing-fmt: BlockdevDriver (optional)
6463 Name of the block driver to use for the backing file
6464
6465 encrypt: QCryptoBlockCreateOptions (optional)
6466 Encryption options if the image should be encrypted
6467
6468 cluster-size: int (optional)
6469 qcow2 cluster size in bytes (default: 65536)
6470
6471 preallocation: PreallocMode (optional)
6472 Preallocation mode for the new image (default: off; allowed val‐
6473 ues: off, falloc, full, metadata)
6474
6475 lazy-refcounts: boolean (optional)
6476 True if refcounts may be updated lazily (default: off)
6477
6478 refcount-bits: int (optional)
6479 Width of reference counts in bits (default: 16)
6480
6481 compression-type: Qcow2CompressionType (optional)
6482 The image cluster compression method (default: zlib, since 5.1)
6483
6484 Since
6485 2.12
6486
6487 BlockdevCreateOptionsQed (Object)
6488 Driver specific image creation options for qed.
6489
6490 Members
6491 file: BlockdevRef
6492 Node to create the image format on
6493
6494 size: int
6495 Size of the virtual disk in bytes
6496
6497 backing-file: string (optional)
6498 File name of the backing file if a backing file should be used
6499
6500 backing-fmt: BlockdevDriver (optional)
6501 Name of the block driver to use for the backing file
6502
6503 cluster-size: int (optional)
6504 Cluster size in bytes (default: 65536)
6505
6506 table-size: int (optional)
6507 L1/L2 table size (in clusters)
6508
6509 Since
6510 2.12
6511
6512 BlockdevCreateOptionsRbd (Object)
6513 Driver specific image creation options for rbd/Ceph.
6514
6515 Members
6516 location: BlockdevOptionsRbd
6517 Where to store the new image file. This location cannot point to
6518 a snapshot.
6519
6520 size: int
6521 Size of the virtual disk in bytes
6522
6523 cluster-size: int (optional)
6524 RBD object size
6525
6526 encrypt: RbdEncryptionCreateOptions (optional)
6527 Image encryption options. (Since 6.1)
6528
6529 Since
6530 2.12
6531
6532 BlockdevVmdkSubformat (Enum)
6533 Subformat options for VMDK images
6534
6535 Values
6536 monolithicSparse
6537 Single file image with sparse cluster allocation
6538
6539 monolithicFlat
6540 Single flat data image and a descriptor file
6541
6542 twoGbMaxExtentSparse
6543 Data is split into 2GB (per virtual LBA) sparse extent files, in
6544 addition to a descriptor file
6545
6546 twoGbMaxExtentFlat
6547 Data is split into 2GB (per virtual LBA) flat extent files, in
6548 addition to a descriptor file
6549
6550 streamOptimized
6551 Single file image sparse cluster allocation, optimized for
6552 streaming over network.
6553
6554 Since
6555 4.0
6556
6557 BlockdevVmdkAdapterType (Enum)
6558 Adapter type info for VMDK images
6559
6560 Values
6561 ide Not documented
6562
6563 buslogic
6564 Not documented
6565
6566 lsilogic
6567 Not documented
6568
6569 legacyESX
6570 Not documented
6571
6572 Since
6573 4.0
6574
6575 BlockdevCreateOptionsVmdk (Object)
6576 Driver specific image creation options for VMDK.
6577
6578 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
6584 size: int
6585 Size of the virtual disk in bytes
6586
6587 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
6595 subformat: BlockdevVmdkSubformat (optional)
6596 The subformat of the VMDK image. Default: "monolithicSparse".
6597
6598 backing-file: string (optional)
6599 The path of backing file. Default: no backing file is used.
6600
6601 adapter-type: BlockdevVmdkAdapterType (optional)
6602 The adapter type used to fill in the descriptor. Default: ide.
6603
6604 hwversion: string (optional)
6605 Hardware version. The meaningful options are "4" or "6". De‐
6606 fault: "4".
6607
6608 zeroed-grain: boolean (optional)
6609 Whether to enable zeroed-grain feature for sparse subformats.
6610 Default: false.
6611
6612 Since
6613 4.0
6614
6615 BlockdevCreateOptionsSsh (Object)
6616 Driver specific image creation options for SSH.
6617
6618 Members
6619 location: BlockdevOptionsSsh
6620 Where to store the new image file
6621
6622 size: int
6623 Size of the virtual disk in bytes
6624
6625 Since
6626 2.12
6627
6628 BlockdevCreateOptionsVdi (Object)
6629 Driver specific image creation options for VDI.
6630
6631 Members
6632 file: BlockdevRef
6633 Node to create the image format on
6634
6635 size: int
6636 Size of the virtual disk in bytes
6637
6638 preallocation: PreallocMode (optional)
6639 Preallocation mode for the new image (default: off; allowed val‐
6640 ues: off, metadata)
6641
6642 Since
6643 2.12
6644
6645 BlockdevVhdxSubformat (Enum)
6646 Values
6647 dynamic
6648 Growing image file
6649
6650 fixed Preallocated fixed-size image file
6651
6652 Since
6653 2.12
6654
6655 BlockdevCreateOptionsVhdx (Object)
6656 Driver specific image creation options for vhdx.
6657
6658 Members
6659 file: BlockdevRef
6660 Node to create the image format on
6661
6662 size: int
6663 Size of the virtual disk in bytes
6664
6665 log-size: int (optional)
6666 Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
6667
6668 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
6673 subformat: BlockdevVhdxSubformat (optional)
6674 vhdx subformat (default: dynamic)
6675
6676 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
6681 Since
6682 2.12
6683
6684 BlockdevVpcSubformat (Enum)
6685 Values
6686 dynamic
6687 Growing image file
6688
6689 fixed Preallocated fixed-size image file
6690
6691 Since
6692 2.12
6693
6694 BlockdevCreateOptionsVpc (Object)
6695 Driver specific image creation options for vpc (VHD).
6696
6697 Members
6698 file: BlockdevRef
6699 Node to create the image format on
6700
6701 size: int
6702 Size of the virtual disk in bytes
6703
6704 subformat: BlockdevVpcSubformat (optional)
6705 vhdx subformat (default: dynamic)
6706
6707 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
6711 Since
6712 2.12
6713
6714 BlockdevCreateOptions (Object)
6715 Options for creating an image format on a given node.
6716
6717 Members
6718 driver: BlockdevDriver
6719 block driver to create the image format
6720
6721 The members of BlockdevCreateOptionsFile when driver is "file"
6722
6723 The members of BlockdevCreateOptionsGluster when driver is "gluster"
6724
6725 The members of BlockdevCreateOptionsLUKS when driver is "luks"
6726
6727 The members of BlockdevCreateOptionsNfs when driver is "nfs"
6728
6729 The members of BlockdevCreateOptionsParallels when driver is "paral‐
6730 lels"
6731
6732 The members of BlockdevCreateOptionsQcow when driver is "qcow"
6733
6734 The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
6735
6736 The members of BlockdevCreateOptionsQed when driver is "qed"
6737
6738 The members of BlockdevCreateOptionsRbd when driver is "rbd"
6739
6740 The members of BlockdevCreateOptionsSsh when driver is "ssh"
6741
6742 The members of BlockdevCreateOptionsVdi when driver is "vdi"
6743
6744 The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
6745
6746 The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
6747
6748 The members of BlockdevCreateOptionsVpc when driver is "vpc"
6749
6750 Since
6751 2.12
6752
6753 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
6757 Arguments
6758 job-id: string
6759 Identifier for the newly created job.
6760
6761 options: BlockdevCreateOptions
6762 Options for the image creation.
6763
6764 Since
6765 3.0
6766
6767 BlockdevAmendOptionsLUKS (Object)
6768 Driver specific image amend options for LUKS.
6769
6770 Members
6771 The members of QCryptoBlockAmendOptionsLUKS
6772
6773 Since
6774 5.1
6775
6776 BlockdevAmendOptionsQcow2 (Object)
6777 Driver specific image amend options for qcow2. For now, only encryp‐
6778 tion options can be amended
6779
6780 encrypt Encryption options to be amended
6781
6782 Members
6783 encrypt: QCryptoBlockAmendOptions (optional)
6784 Not documented
6785
6786 Since
6787 5.1
6788
6789 BlockdevAmendOptions (Object)
6790 Options for amending an image format
6791
6792 Members
6793 driver: BlockdevDriver
6794 Block driver of the node to amend.
6795
6796 The members of BlockdevAmendOptionsLUKS when driver is "luks"
6797
6798 The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
6799
6800 Since
6801 5.1
6802
6803 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
6808 Arguments
6809 job-id: string
6810 Identifier for the newly created job.
6811
6812 node-name: string
6813 Name of the block node to work on
6814
6815 options: BlockdevAmendOptions
6816 Options (driver specific)
6817
6818 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
6824 Since
6825 5.1
6826
6827 BlockErrorAction (Enum)
6828 An enumeration of action that has been taken when a DISK I/O occurs
6829
6830 Values
6831 ignore error has been ignored
6832
6833 report error has been reported to the device
6834
6835 stop error caused VM to be stopped
6836
6837 Since
6838 2.1
6839
6840 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
6846 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
6852 node-name: string (optional)
6853 node name (Since: 2.4)
6854
6855 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
6860 offset: int (optional)
6861 if the corruption resulted from an image access, this is the
6862 host's access offset into the image
6863
6864 size: int (optional)
6865 if the corruption resulted from an image access, this is the ac‐
6866 cess size
6867
6868 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
6873 Note
6874 If action is "stop", a STOP event will eventually follow the
6875 BLOCK_IO_ERROR event.
6876
6877 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
6884 Since
6885 1.7
6886
6887 BLOCK_IO_ERROR (Event)
6888 Emitted when a disk I/O error occurs
6889
6890 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
6896 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
6902 operation: IoOperationType
6903 I/O operation
6904
6905 action: BlockErrorAction
6906 action that has been taken
6907
6908 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
6914 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
6919 Note
6920 If action is "stop", a STOP event will eventually follow the
6921 BLOCK_IO_ERROR event
6922
6923 Since
6924 0.13
6925
6926 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
6934 BLOCK_JOB_COMPLETED (Event)
6935 Emitted when a block job has completed
6936
6937 Arguments
6938 type: JobType
6939 job type
6940
6941 device: string
6942 The job identifier. Originally the device name but other values
6943 are allowed since QEMU 2.7
6944
6945 len: int
6946 maximum progress value
6947
6948 offset: int
6949 current progress value. On success this is equal to len. On
6950 failure this is less than len
6951
6952 speed: int
6953 rate limit, bytes per second
6954
6955 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
6961 Since
6962 1.1
6963
6964 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
6971 BLOCK_JOB_CANCELLED (Event)
6972 Emitted when a block job has been cancelled
6973
6974 Arguments
6975 type: JobType
6976 job type
6977
6978 device: string
6979 The job identifier. Originally the device name but other values
6980 are allowed since QEMU 2.7
6981
6982 len: int
6983 maximum progress value
6984
6985 offset: int
6986 current progress value. On success this is equal to len. On
6987 failure this is less than len
6988
6989 speed: int
6990 rate limit, bytes per second
6991
6992 Since
6993 1.1
6994
6995 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
7002 BLOCK_JOB_ERROR (Event)
7003 Emitted when a block job encounters an error
7004
7005 Arguments
7006 device: string
7007 The job identifier. Originally the device name but other values
7008 are allowed since QEMU 2.7
7009
7010 operation: IoOperationType
7011 I/O operation
7012
7013 action: BlockErrorAction
7014 action that has been taken
7015
7016 Since
7017 1.3
7018
7019 Example
7020 <- { "event": "BLOCK_JOB_ERROR",
7021 "data": { "device": "ide0-hd1",
7022 "operation": "write",
7023 "action": "stop" },
7024 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7025
7026 BLOCK_JOB_READY (Event)
7027 Emitted when a block job is ready to complete
7028
7029 Arguments
7030 type: JobType
7031 job type
7032
7033 device: string
7034 The job identifier. Originally the device name but other values
7035 are allowed since QEMU 2.7
7036
7037 len: int
7038 maximum progress value
7039
7040 offset: int
7041 current progress value. On success this is equal to len. On
7042 failure this is less than len
7043
7044 speed: int
7045 rate limit, bytes per second
7046
7047 Note
7048 The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
7049 event
7050
7051 Since
7052 1.3
7053
7054 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
7060 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
7066 Arguments
7067 type: JobType
7068 job type
7069
7070 id: string
7071 The job identifier.
7072
7073 Since
7074 2.12
7075
7076 Example
7077 <- { "event": "BLOCK_JOB_WAITING",
7078 "data": { "device": "drive0", "type": "mirror" },
7079 "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7080
7081 PreallocMode (Enum)
7082 Preallocation mode of QEMU image file
7083
7084 Values
7085 off no preallocation
7086
7087 metadata
7088 preallocate only for metadata
7089
7090 falloc like full preallocation but allocate disk space by posix_fallo‐
7091 cate() rather than writing data.
7092
7093 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
7098 Since
7099 2.2
7100
7101 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
7108 Arguments
7109 node-name: string
7110 graph node name on which the threshold was exceeded.
7111
7112 amount-exceeded: int
7113 amount of data which exceeded the threshold, in bytes.
7114
7115 write-threshold: int
7116 last configured threshold, in bytes.
7117
7118 Since
7119 2.3
7120
7121 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
7127 This is useful to transparently resize thin-provisioned drives without
7128 the guest OS noticing.
7129
7130 Arguments
7131 node-name: string
7132 graph node name on which the threshold must be set.
7133
7134 write-threshold: int
7135 configured threshold for the block device, bytes. Use 0 to dis‐
7136 able the threshold.
7137
7138 Since
7139 2.3
7140
7141 Example
7142 -> { "execute": "block-set-write-threshold",
7143 "arguments": { "node-name": "mydev",
7144 "write-threshold": 17179869184 } }
7145 <- { "return": {} }
7146
7147 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
7153 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
7157 Arguments
7158 parent: string
7159 the id or name of the parent node.
7160
7161 child: string (optional)
7162 the name of a child under the given parent node.
7163
7164 node: string (optional)
7165 the name of the node that will be added.
7166
7167 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
7172 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
7176 Warning: The data in a new quorum child MUST be consistent with that of
7177 the rest of the array.
7178
7179 Since
7180 2.7
7181
7182 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
7196 2. Delete a quorum's node
7197 -> { "execute": "x-blockdev-change",
7198 "arguments": { "parent": "disk1",
7199 "child": "children.1" } }
7200 <- { "return": {} }
7201
7202 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
7206 The node must not be attached to a BlockBackend.
7207
7208 Arguments
7209 node-name: string
7210 the name of the block driver node
7211
7212 iothread: StrOrNull
7213 the name of the IOThread object or null for the main loop
7214
7215 force: boolean (optional)
7216 true if the node and its children should be moved when a Block‐
7217 Backend is already attached
7218
7219 Note
7220 this command is experimental and intended for test cases that need con‐
7221 trol over IOThreads only.
7222
7223 Since
7224 2.12
7225
7226 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
7233 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
7239 QuorumOpType (Enum)
7240 An enumeration of the quorum operation types
7241
7242 Values
7243 read read operation
7244
7245 write write operation
7246
7247 flush flush operation
7248
7249 Since
7250 2.6
7251
7252 QUORUM_FAILURE (Event)
7253 Emitted by the Quorum block driver if it fails to establish a quorum
7254
7255 Arguments
7256 reference: string
7257 device name if defined else node name
7258
7259 sector-num: int
7260 number of the first sector of the failed read operation
7261
7262 sectors-count: int
7263 failed read operation sector count
7264
7265 Note
7266 This event is rate-limited.
7267
7268 Since
7269 2.0
7270
7271 Example
7272 <- { "event": "QUORUM_FAILURE",
7273 "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
7274 "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
7275
7276 QUORUM_REPORT_BAD (Event)
7277 Emitted to report a corruption of a Quorum file
7278
7279 Arguments
7280 type: QuorumOpType
7281 quorum operation type (Since 2.6)
7282
7283 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
7289 node-name: string
7290 the graph node name of the block driver state
7291
7292 sector-num: int
7293 number of the first sector of the failed read operation
7294
7295 sectors-count: int
7296 failed read operation sector count
7297
7298 Note
7299 This event is rate-limited.
7300
7301 Since
7302 2.0
7303
7304 Example
7305 1. Read operation
7306
7307 { "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
7312 2. Flush operation
7313
7314 { "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
7319 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
7325 name: string
7326 the name of the internal snapshot to be created
7327
7328 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
7333 Since
7334 1.7
7335
7336 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
7341 For the arguments, see the documentation of BlockdevSnapshotInternal.
7342
7343 Returns
7344 • nothing on success
7345
7346 • If device is not a valid block device, GenericError
7347
7348 • If any snapshot matching name exists, or name is empty, GenericError
7349
7350 • If the format of the image used does not support it, BlockFormatFea‐
7351 tureNotSupported
7352
7353 Since
7354 1.7
7355
7356 Example
7357 -> { "execute": "blockdev-snapshot-internal-sync",
7358 "arguments": { "device": "ide-hd0",
7359 "name": "snapshot0" }
7360 }
7361 <- { "return": {} }
7362
7363 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
7369 Arguments
7370 device: string
7371 the device name or node-name of a root node to delete the snap‐
7372 shot from
7373
7374 id: string (optional)
7375 optional the snapshot's ID to be deleted
7376
7377 name: string (optional)
7378 optional the snapshot's name to be deleted
7379
7380 Returns
7381 • SnapshotInfo on success
7382
7383 • If device is not a valid block device, GenericError
7384
7385 • If snapshot not found, GenericError
7386
7387 • If the format of the image used does not support it, BlockFormatFea‐
7388 tureNotSupported
7389
7390 • If id and name are both not specified, GenericError
7391
7392 Since
7393 1.7
7394
7395 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
7412 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
7418 Members
7419 addr: SocketAddress
7420 Address on which to listen.
7421
7422 tls-creds: string (optional)
7423 ID of the TLS credentials object (since 2.6).
7424
7425 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
7432 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
7436 Since
7437 4.2
7438
7439 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
7445 Keep this type consistent with the NbdServerOptions type. The only in‐
7446 tended difference is using SocketAddressLegacy instead of SocketAd‐
7447 dress.
7448
7449 Arguments
7450 addr: SocketAddressLegacy
7451 Address on which to listen.
7452
7453 tls-creds: string (optional)
7454 ID of the TLS credentials object (since 2.6).
7455
7456 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
7463 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
7467 Returns
7468 error if the server is already running.
7469
7470 Since
7471 1.3
7472
7473 BlockExportOptionsNbdBase (Object)
7474 An NBD block export (common options shared between nbd-server-add and
7475 the NBD branch of block-export-add).
7476
7477 Members
7478 name: string (optional)
7479 Export name. If unspecified, the device parameter is used as the
7480 export name. (Since 2.12)
7481
7482 description: string (optional)
7483 Free-form description of the export, up to 4096 bytes. (Since
7484 5.0)
7485
7486 Since
7487 5.0
7488
7489 BlockExportOptionsNbd (Object)
7490 An NBD block export (distinct options used in the NBD branch of
7491 block-export-add).
7492
7493 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
7500 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
7506 The members of BlockExportOptionsNbdBase
7507
7508 Since
7509 5.2
7510
7511 BlockExportOptionsVhostUserBlk (Object)
7512 A vhost-user-blk block export.
7513
7514 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
7520 logical-block-size: int (optional)
7521 Logical block size in bytes. Defaults to 512 bytes.
7522
7523 num-queues: int (optional)
7524 Number of request virtqueues. Must be greater than 0. Defaults
7525 to 1.
7526
7527 Since
7528 5.2
7529
7530 FuseExportAllowOther (Enum)
7531 Possible allow_other modes for FUSE exports.
7532
7533 Values
7534 off Do not pass allow_other as a mount option.
7535
7536 on Pass allow_other as a mount option.
7537
7538 auto Try mounting with allow_other first, and if that fails, retry
7539 without allow_other.
7540
7541 Since
7542 6.1
7543
7544 BlockExportOptionsFuse (Object)
7545 Options for exporting a block graph node on some (file) mountpoint as a
7546 raw image.
7547
7548 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
7553 growable: boolean (optional)
7554 Whether writes beyond the EOF should grow the block node accord‐
7555 ingly. (default: false)
7556
7557 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
7568 Since
7569 6.0
7570
7571 If
7572 defined(CONFIG_FUSE)
7573
7574 NbdServerAddOptions (Object)
7575 An NBD block export, per legacy nbd-server-add command.
7576
7577 Members
7578 device: string
7579 The device name or node name of the node to be exported
7580
7581 writable: boolean (optional)
7582 Whether clients should be able to write to the device via the
7583 NBD connection (default false).
7584
7585 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
7591 The members of BlockExportOptionsNbdBase
7592
7593 Since
7594 5.0
7595
7596 nbd-server-add (Command)
7597 Export a block node to QEMU's embedded NBD server.
7598
7599 The export name will be used as the id for the resulting block export.
7600
7601 Arguments
7602 The members of NbdServerAddOptions
7603
7604 Features
7605 deprecated
7606 This command is deprecated. Use block-export-add instead.
7607
7608 Returns
7609 error if the server is not running, or export with the same name al‐
7610 ready exists.
7611
7612 Since
7613 1.3
7614
7615 BlockExportRemoveMode (Enum)
7616 Mode for removing a block export.
7617
7618 Values
7619 safe Remove export if there are no existing connections, fail other‐
7620 wise.
7621
7622 hard Drop all connections immediately and remove export.
7623 Potential additional modes to be added in the future:
7624
7625 hide: Just hide export from new clients, leave existing connections as
7626 is. Remove export after all clients are disconnected.
7627
7628 soft: Hide export from new clients, answer with ESHUTDOWN for all fur‐
7629 ther requests from existing clients.
7630
7631 Since
7632 2.12
7633
7634 nbd-server-remove (Command)
7635 Remove NBD export by name.
7636
7637 Arguments
7638 name: string
7639 Block export id.
7640
7641 mode: BlockExportRemoveMode (optional)
7642 Mode of command operation. See BlockExportRemoveMode descrip‐
7643 tion. Default is 'safe'.
7644
7645 Features
7646 deprecated
7647 This command is deprecated. Use block-export-del instead.
7648
7649 Returns
7650 error if
7651
7652 • the server is not running
7653
7654 • export is not found
7655
7656 • mode is 'safe' and there are existing connections
7657
7658 Since
7659 2.12
7660
7661 nbd-server-stop (Command)
7662 Stop QEMU's embedded NBD server, and unregister all devices previously
7663 added via nbd-server-add.
7664
7665 Since
7666 1.3
7667
7668 BlockExportType (Enum)
7669 An enumeration of block export types
7670
7671 Values
7672 nbd NBD export
7673
7674 vhost-user-blk
7675 vhost-user-blk export (since 5.2)
7676
7677 fuse (If: defined(CONFIG_FUSE))
7678 FUSE export (since: 6.0)
7679
7680 Since
7681 4.2
7682
7683 BlockExportOptions (Object)
7684 Describes a block export, i.e. how single node should be exported on an
7685 external interface.
7686
7687 Members
7688 id: string
7689 A unique identifier for the block export (across all export
7690 types)
7691
7692 node-name: string
7693 The node name of the block node to be exported (since: 5.2)
7694
7695 writable: boolean (optional)
7696 True if clients should be able to write to the export (default
7697 false)
7698
7699 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
7704 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
7709 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
7715 type: BlockExportType
7716 Not documented
7717
7718 The members of BlockExportOptionsNbd when type is "nbd"
7719
7720 The members of BlockExportOptionsVhostUserBlk when type is
7721 "vhost-user-blk"
7722
7723 The members of BlockExportOptionsFuse when type is "fuse" (If: de‐
7724 fined(CONFIG_FUSE))
7725
7726 Since
7727 4.2
7728
7729 block-export-add (Command)
7730 Creates a new block export.
7731
7732 Arguments
7733 The members of BlockExportOptions
7734
7735 Since
7736 5.2
7737
7738 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
7743 Arguments
7744 id: string
7745 Block export id.
7746
7747 mode: BlockExportRemoveMode (optional)
7748 Mode of command operation. See BlockExportRemoveMode descrip‐
7749 tion. Default is 'safe'.
7750
7751 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
7755 Since
7756 5.2
7757
7758 BLOCK_EXPORT_DELETED (Event)
7759 Emitted when a block export is removed and its id can be reused.
7760
7761 Arguments
7762 id: string
7763 Block export id.
7764
7765 Since
7766 5.2
7767
7768 BlockExportInfo (Object)
7769 Information about a single block export.
7770
7771 Members
7772 id: string
7773 The unique identifier for the block export
7774
7775 type: BlockExportType
7776 The block export type
7777
7778 node-name: string
7779 The node name of the block node that is exported
7780
7781 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
7785 Since
7786 5.2
7787
7788 query-block-exports (Command)
7789 Returns
7790 A list of BlockExportInfo describing all block exports
7791
7792 Since
7793 5.2
7794
7796 ChardevInfo (Object)
7797 Information about a character device.
7798
7799 Members
7800 label: string
7801 the label of the character device
7802
7803 filename: string
7804 the filename of the character device
7805
7806 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
7811 Notes
7812 filename is encoded using the QEMU command line character device encod‐
7813 ing. See the QEMU man page for details.
7814
7815 Since
7816 0.14
7817
7818 query-chardev (Command)
7819 Returns information about current character devices.
7820
7821 Returns
7822 a list of ChardevInfo
7823
7824 Since
7825 0.14
7826
7827 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
7849 ChardevBackendInfo (Object)
7850 Information about a character device backend
7851
7852 Members
7853 name: string
7854 The backend name
7855
7856 Since
7857 2.0
7858
7859 query-chardev-backends (Command)
7860 Returns information about character device backends.
7861
7862 Returns
7863 a list of ChardevBackendInfo
7864
7865 Since
7866 2.0
7867
7868 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
7887 DataFormat (Enum)
7888 An enumeration of data format.
7889
7890 Values
7891 utf8 Data is a UTF-8 string (RFC 3629)
7892
7893 base64 Data is Base64 encoded binary (RFC 3548)
7894
7895 Since
7896 1.4
7897
7898 ringbuf-write (Command)
7899 Write to a ring buffer character device.
7900
7901 Arguments
7902 device: string
7903 the ring buffer character device name
7904
7905 data: string
7906 data to write
7907
7908 format: DataFormat (optional)
7909 data encoding (default 'utf8').
7910
7911 • base64: data must be base64 encoded text. Its binary decoding
7912 gets written.
7913
7914 • utf8: data's UTF-8 encoding is written
7915
7916 • data itself is always Unicode regardless of format, like any
7917 other string.
7918
7919 Returns
7920 Nothing on success
7921
7922 Since
7923 1.4
7924
7925 Example
7926 -> { "execute": "ringbuf-write",
7927 "arguments": { "device": "foo",
7928 "data": "abcdefgh",
7929 "format": "utf8" } }
7930 <- { "return": {} }
7931
7932 ringbuf-read (Command)
7933 Read from a ring buffer character device.
7934
7935 Arguments
7936 device: string
7937 the ring buffer character device name
7938
7939 size: int
7940 how many bytes to read at most
7941
7942 format: DataFormat (optional)
7943 data encoding (default 'utf8').
7944
7945 • base64: the data read is returned in base64 encoding.
7946
7947 • 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
7952 • The return value is always Unicode regardless of format, like
7953 any other string.
7954
7955 Returns
7956 data read from the device
7957
7958 Since
7959 1.4
7960
7961 Example
7962 -> { "execute": "ringbuf-read",
7963 "arguments": { "device": "foo",
7964 "size": 1000,
7965 "format": "utf8" } }
7966 <- { "return": "abcdefgh" }
7967
7968 ChardevCommon (Object)
7969 Configuration shared across all chardev backends
7970
7971 Members
7972 logfile: string (optional)
7973 The name of a logfile to save output
7974
7975 logappend: boolean (optional)
7976 true to append instead of truncate (default to false to trun‐
7977 cate)
7978
7979 Since
7980 2.6
7981
7982 ChardevFile (Object)
7983 Configuration info for file chardevs.
7984
7985 Members
7986 in: string (optional)
7987 The name of the input file
7988
7989 out: string
7990 The name of the output file
7991
7992 append: boolean (optional)
7993 Open the file in append mode (default false to truncate) (Since
7994 2.6)
7995
7996 The members of ChardevCommon
7997
7998 Since
7999 1.4
8000
8001 ChardevHostdev (Object)
8002 Configuration info for device and pipe chardevs.
8003
8004 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
8009 The members of ChardevCommon
8010
8011 Since
8012 1.4
8013
8014 ChardevSocket (Object)
8015 Configuration info for (stream) socket chardevs.
8016
8017 Members
8018 addr: SocketAddressLegacy
8019 socket address to listen on (server=true) or connect to
8020 (server=false)
8021
8022 tls-creds: string (optional)
8023 the ID of the TLS credentials object (since 2.6)
8024
8025 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
8032 server: boolean (optional)
8033 create server socket (default: true)
8034
8035 wait: boolean (optional)
8036 wait for incoming connection on server sockets (default: false).
8037 Silently ignored with server: false. This use is deprecated.
8038
8039 nodelay: boolean (optional)
8040 set TCP_NODELAY socket option (default: false)
8041
8042 telnet: boolean (optional)
8043 enable telnet protocol on server sockets (default: false)
8044
8045 tn3270: boolean (optional)
8046 enable tn3270 protocol on server sockets (default: false)
8047 (Since: 2.10)
8048
8049 websocket: boolean (optional)
8050 enable websocket protocol on server sockets (default: false)
8051 (Since: 3.1)
8052
8053 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
8058 The members of ChardevCommon
8059
8060 Since
8061 1.4
8062
8063 ChardevUdp (Object)
8064 Configuration info for datagram socket chardevs.
8065
8066 Members
8067 remote: SocketAddressLegacy
8068 remote address
8069
8070 local: SocketAddressLegacy (optional)
8071 local address
8072
8073 The members of ChardevCommon
8074
8075 Since
8076 1.5
8077
8078 ChardevMux (Object)
8079 Configuration info for mux chardevs.
8080
8081 Members
8082 chardev: string
8083 name of the base chardev.
8084
8085 The members of ChardevCommon
8086
8087 Since
8088 1.5
8089
8090 ChardevStdio (Object)
8091 Configuration info for stdio chardevs.
8092
8093 Members
8094 signal: boolean (optional)
8095 Allow signals (such as SIGINT triggered by ^C) be delivered to
8096 qemu. Default: true.
8097
8098 The members of ChardevCommon
8099
8100 Since
8101 1.5
8102
8103 ChardevSpiceChannel (Object)
8104 Configuration info for spice vm channel chardevs.
8105
8106 Members
8107 type: string
8108 kind of channel (for example vdagent).
8109
8110 The members of ChardevCommon
8111
8112 Since
8113 1.5
8114
8115 If
8116 defined(CONFIG_SPICE)
8117
8118 ChardevSpicePort (Object)
8119 Configuration info for spice port chardevs.
8120
8121 Members
8122 fqdn: string
8123 name of the channel (see docs/spice-port-fqdn.txt)
8124
8125 The members of ChardevCommon
8126
8127 Since
8128 1.5
8129
8130 If
8131 defined(CONFIG_SPICE)
8132
8133 ChardevVC (Object)
8134 Configuration info for virtual console chardevs.
8135
8136 Members
8137 width: int (optional)
8138 console width, in pixels
8139
8140 height: int (optional)
8141 console height, in pixels
8142
8143 cols: int (optional)
8144 console width, in chars
8145
8146 rows: int (optional)
8147 console height, in chars
8148
8149 The members of ChardevCommon
8150
8151 Since
8152 1.5
8153
8154 ChardevRingbuf (Object)
8155 Configuration info for ring buffer chardevs.
8156
8157 Members
8158 size: int (optional)
8159 ring buffer size, must be power of two, default is 65536
8160
8161 The members of ChardevCommon
8162
8163 Since
8164 1.5
8165
8166 ChardevQemuVDAgent (Object)
8167 Configuration info for qemu vdagent implementation.
8168
8169 Members
8170 mouse: boolean (optional)
8171 enable/disable mouse, default is enabled.
8172
8173 clipboard: boolean (optional)
8174 enable/disable clipboard, default is disabled.
8175
8176 The members of ChardevCommon
8177
8178 Since
8179 6.1
8180
8181 If
8182 defined(CONFIG_SPICE_PROTOCOL)
8183
8184 ChardevBackend (Object)
8185 Configuration info for the new chardev backend.
8186
8187 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
8192 data: ChardevFile when type is "file"
8193
8194 data: ChardevHostdev when type is "serial"
8195
8196 data: ChardevHostdev when type is "parallel"
8197
8198 data: ChardevHostdev when type is "pipe"
8199
8200 data: ChardevSocket when type is "socket"
8201
8202 data: ChardevUdp when type is "udp"
8203
8204 data: ChardevCommon when type is "pty"
8205
8206 data: ChardevCommon when type is "null"
8207
8208 data: ChardevMux when type is "mux"
8209
8210 data: ChardevCommon when type is "msmouse"
8211
8212 data: ChardevCommon when type is "wctablet"
8213
8214 data: ChardevCommon when type is "braille"
8215
8216 data: ChardevCommon when type is "testdev"
8217
8218 data: ChardevStdio when type is "stdio"
8219
8220 data: ChardevCommon when type is "console"
8221
8222 data: ChardevSpiceChannel when type is "spicevmc" (If: defined(CON‐
8223 FIG_SPICE))
8224
8225 data: ChardevSpicePort when type is "spiceport" (If: defined(CON‐
8226 FIG_SPICE))
8227
8228 data: ChardevQemuVDAgent when type is "qemu-vdagent" (If: defined(CON‐
8229 FIG_SPICE_PROTOCOL))
8230
8231 data: ChardevVC when type is "vc"
8232
8233 data: ChardevRingbuf when type is "ringbuf"
8234
8235 data: ChardevRingbuf when type is "memory"
8236
8237 Since
8238 1.4 (testdev since 2.2, wctablet since 2.9, vdagent since 6.1)
8239
8240 ChardevReturn (Object)
8241 Return info about the chardev backend just created.
8242
8243 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
8248 Since
8249 1.4
8250
8251 chardev-add (Command)
8252 Add a character device backend
8253
8254 Arguments
8255 id: string
8256 the chardev's ID, must be unique
8257
8258 backend: ChardevBackend
8259 backend type and parameters
8260
8261 Returns
8262 ChardevReturn.
8263
8264 Since
8265 1.4
8266
8267 Example
8268 -> { "execute" : "chardev-add",
8269 "arguments" : { "id" : "foo",
8270 "backend" : { "type" : "null", "data" : {} } } }
8271 <- { "return": {} }
8272
8273 -> { "execute" : "chardev-add",
8274 "arguments" : { "id" : "bar",
8275 "backend" : { "type" : "file",
8276 "data" : { "out" : "/tmp/bar.log" } } } }
8277 <- { "return": {} }
8278
8279 -> { "execute" : "chardev-add",
8280 "arguments" : { "id" : "baz",
8281 "backend" : { "type" : "pty", "data" : {} } } }
8282 <- { "return": { "pty" : "/dev/pty/42" } }
8283
8284 chardev-change (Command)
8285 Change a character device backend
8286
8287 Arguments
8288 id: string
8289 the chardev's ID, must exist
8290
8291 backend: ChardevBackend
8292 new backend type and parameters
8293
8294 Returns
8295 ChardevReturn.
8296
8297 Since
8298 2.10
8299
8300 Example
8301 -> { "execute" : "chardev-change",
8302 "arguments" : { "id" : "baz",
8303 "backend" : { "type" : "pty", "data" : {} } } }
8304 <- { "return": { "pty" : "/dev/pty/42" } }
8305
8306 -> {"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
8322 chardev-remove (Command)
8323 Remove a character device backend
8324
8325 Arguments
8326 id: string
8327 the chardev's ID, must exist and not be in use
8328
8329 Returns
8330 Nothing on success
8331
8332 Since
8333 1.4
8334
8335 Example
8336 -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
8337 <- { "return": {} }
8338
8339 chardev-send-break (Command)
8340 Send a break to a character device
8341
8342 Arguments
8343 id: string
8344 the chardev's ID, must exist
8345
8346 Returns
8347 Nothing on success
8348
8349 Since
8350 2.10
8351
8352 Example
8353 -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
8354 <- { "return": {} }
8355
8356 VSERPORT_CHANGE (Event)
8357 Emitted when the guest opens or closes a virtio-serial port.
8358
8359 Arguments
8360 id: string
8361 device identifier of the virtio-serial port
8362
8363 open: boolean
8364 true if the guest has opened the virtio-serial port
8365
8366 Note
8367 This event is rate-limited.
8368
8369 Since
8370 2.1
8371
8372 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
8381 Arguments:
8382
8383 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
8390 Example
8391 -> { "execute": "qmp_capabilities",
8392 "arguments": { "enable": [ "oob" ] } }
8393 <- { "return": {} }
8394
8395 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
8400 The QMP client needs to explicitly enable QMP capabilities, otherwise
8401 all the QMP capabilities will be turned off by default.
8402
8403 Since
8404 0.13
8405
8406 QMPCapability (Enum)
8407 Enumeration of capabilities to be advertised during initial client con‐
8408 nection, used for agreeing on particular QMP extension behaviors.
8409
8410 Values
8411 oob QMP ability to support out-of-band requests. (Please refer to
8412 qmp-spec.txt for more information on OOB)
8413
8414 Since
8415 2.12
8416
8417 VersionTriple (Object)
8418 A three-part version number.
8419
8420 Members
8421 major: int
8422 The major version number.
8423
8424 minor: int
8425 The minor version number.
8426
8427 micro: int
8428 The micro version number.
8429
8430 Since
8431 2.4
8432
8433 VersionInfo (Object)
8434 A description of QEMU's version.
8435
8436 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
8444 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
8450 Since
8451 0.14
8452
8453 query-version (Command)
8454 Returns the current version of QEMU.
8455
8456 Returns
8457 A VersionInfo object describing the current version of QEMU.
8458
8459 Since
8460 0.14
8461
8462 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
8475 CommandInfo (Object)
8476 Information about a QMP command
8477
8478 Members
8479 name: string
8480 The command name
8481
8482 Since
8483 0.14
8484
8485 query-commands (Command)
8486 Return a list of supported QMP commands by this server
8487
8488 Returns
8489 A list of CommandInfo for all supported commands
8490
8491 Since
8492 0.14
8493
8494 Example
8495 -> { "execute": "query-commands" }
8496 <- {
8497 "return":[
8498 {
8499 "name":"query-balloon"
8500 },
8501 {
8502 "name":"system_powerdown"
8503 }
8504 ]
8505 }
8506
8507 Note
8508 This example has been shortened as the real response is too long.
8509
8510 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
8516 Since
8517 0.14
8518
8519 Example
8520 -> { "execute": "quit" }
8521 <- { "return": {} }
8522
8523 MonitorMode (Enum)
8524 An enumeration of monitor modes.
8525
8526 Values
8527 readline
8528 HMP monitor (human-oriented command line interface)
8529
8530 control
8531 QMP monitor (JSON-based machine interface)
8532
8533 Since
8534 5.0
8535
8536 MonitorOptions (Object)
8537 Options to be used for adding a new monitor.
8538
8539 Members
8540 id: string (optional)
8541 Name of the monitor
8542
8543 mode: MonitorMode (optional)
8544 Selects the monitor mode (default: readline in the system emula‐
8545 tor, control in qemu-storage-daemon)
8546
8547 pretty: boolean (optional)
8548 Enables pretty printing (QMP only)
8549
8550 chardev: string
8551 Name of a character device to expose the monitor on
8552
8553 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
8562 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
8567 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
8576 Returns
8577 array of SchemaInfo, where each element describes an entity in the ABI:
8578 command, event, type, ...
8579
8580 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
8584 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
8589 Since
8590 2.5
8591
8592 SchemaMetaType (Enum)
8593 This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
8594
8595 Values
8596 builtin
8597 a predefined type such as 'int' or 'bool'.
8598
8599 enum an enumeration type
8600
8601 array an array type
8602
8603 object an object type (struct or union)
8604
8605 alternate
8606 an alternate type
8607
8608 command
8609 a QMP command
8610
8611 event a QMP event
8612
8613 Since
8614 2.5
8615
8616 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
8626 meta-type: SchemaMetaType
8627 the entity's meta type, inherited from base.
8628
8629 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
8634 The members of SchemaInfoBuiltin when meta-type is "builtin"
8635
8636 The members of SchemaInfoEnum when meta-type is "enum"
8637
8638 The members of SchemaInfoArray when meta-type is "array"
8639
8640 The members of SchemaInfoObject when meta-type is "object"
8641
8642 The members of SchemaInfoAlternate when meta-type is "alternate"
8643
8644 The members of SchemaInfoCommand when meta-type is "command"
8645
8646 The members of SchemaInfoEvent when meta-type is "event"
8647 Additional members depend on the value of meta-type.
8648
8649 Since
8650 2.5
8651
8652 SchemaInfoBuiltin (Object)
8653 Additional SchemaInfo members for meta-type 'builtin'.
8654
8655 Members
8656 json-type: JSONType
8657 the JSON type used for this type on the wire.
8658
8659 Since
8660 2.5
8661
8662 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
8667 Values
8668 string Not documented
8669
8670 number Not documented
8671
8672 int Not documented
8673
8674 boolean
8675 Not documented
8676
8677 null Not documented
8678
8679 object Not documented
8680
8681 array Not documented
8682
8683 value Not documented
8684
8685 Since
8686 2.5
8687
8688 SchemaInfoEnum (Object)
8689 Additional SchemaInfo members for meta-type 'enum'.
8690
8691 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
8696 Since
8697 2.5
8698
8699 SchemaInfoArray (Object)
8700 Additional SchemaInfo members for meta-type 'array'.
8701
8702 Members
8703 element-type: string
8704 the array type's element type.
8705 Values of this type are JSON array on the wire.
8706
8707 Since
8708 2.5
8709
8710 SchemaInfoObject (Object)
8711 Additional SchemaInfo members for meta-type 'object'.
8712
8713 Members
8714 members: array of SchemaInfoObjectMember
8715 the object type's (non-variant) members, in no particular order.
8716
8717 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
8721 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
8728 Since
8729 2.5
8730
8731 SchemaInfoObjectMember (Object)
8732 An object member.
8733
8734 Members
8735 name: string
8736 the member's name, as defined in the QAPI schema.
8737
8738 type: string
8739 the name of the member's type.
8740
8741 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
8748 features: array of string (optional)
8749 names of features associated with the member, in no particular
8750 order. (since 5.0)
8751
8752 Since
8753 2.5
8754
8755 SchemaInfoObjectVariant (Object)
8756 The variant members for a value of the type tag.
8757
8758 Members
8759 case: string
8760 a value of the type tag.
8761
8762 type: string
8763 the name of the object type that provides the variant members
8764 when the type tag has value case.
8765
8766 Since
8767 2.5
8768
8769 SchemaInfoAlternate (Object)
8770 Additional SchemaInfo members for meta-type 'alternate'.
8771
8772 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
8779 Since
8780 2.5
8781
8782 SchemaInfoAlternateMember (Object)
8783 An alternate member.
8784
8785 Members
8786 type: string
8787 the name of the member's type.
8788
8789 Since
8790 2.5
8791
8792 SchemaInfoCommand (Object)
8793 Additional SchemaInfo members for meta-type 'command'.
8794
8795 Members
8796 arg-type: string
8797 the name of the object type that provides the command's parame‐
8798 ters.
8799
8800 ret-type: string
8801 the name of the command's result type.
8802
8803 allow-oob: boolean (optional)
8804 whether the command allows out-of-band execution, defaults to
8805 false (Since: 2.12)
8806
8807 TODO
8808 success-response (currently irrelevant, because it's QGA, not QMP)
8809
8810 Since
8811 2.5
8812
8813 SchemaInfoEvent (Object)
8814 Additional SchemaInfo members for meta-type 'event'.
8815
8816 Members
8817 arg-type: string
8818 the name of the object type that provides the event's parame‐
8819 ters.
8820
8821 Since
8822 2.5
8823
8825 QAuthZListPolicy (Enum)
8826 The authorization policy result
8827
8828 Values
8829 deny deny access
8830
8831 allow allow access
8832
8833 Since
8834 4.0
8835
8836 QAuthZListFormat (Enum)
8837 The authorization policy match format
8838
8839 Values
8840 exact an exact string match
8841
8842 glob string with ? and * shell wildcard support
8843
8844 Since
8845 4.0
8846
8847 QAuthZListRule (Object)
8848 A single authorization rule.
8849
8850 Members
8851 match: string
8852 a string or glob to match against a user identity
8853
8854 policy: QAuthZListPolicy
8855 the result to return if match evaluates to true
8856
8857 format: QAuthZListFormat (optional)
8858 the format of the match rule (default 'exact')
8859
8860 Since
8861 4.0
8862
8863 AuthZListProperties (Object)
8864 Properties for authz-list objects.
8865
8866 Members
8867 policy: QAuthZListPolicy (optional)
8868 Default policy to apply when no rule matches (default: deny)
8869
8870 rules: array of QAuthZListRule (optional)
8871 Authorization rules based on matching user
8872
8873 Since
8874 4.0
8875
8876 AuthZListFileProperties (Object)
8877 Properties for authz-listfile objects.
8878
8879 Members
8880 filename: string
8881 File name to load the configuration from. The file must contain
8882 valid JSON for AuthZListProperties.
8883
8884 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
8891 Since
8892 4.0
8893
8894 AuthZPAMProperties (Object)
8895 Properties for authz-pam objects.
8896
8897 Members
8898 service: string
8899 PAM service name to use for authorization
8900
8901 Since
8902 4.0
8903
8904 AuthZSimpleProperties (Object)
8905 Properties for authz-simple objects.
8906
8907 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
8914 Since
8915 4.0
8916
8918 ObjectPropertyInfo (Object)
8919 Members
8920 name: string
8921 the name of the property
8922
8923 type: string
8924 the type of the property. This will typically come in one of
8925 four forms:
8926
8927 1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
8928 ble'. These types are mapped to the appropriate JSON type.
8929
8930 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
8934 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
8938 description: string (optional)
8939 if specified, the description of the property.
8940
8941 default-value: value (optional)
8942 the default value, if any (since 5.0)
8943
8944 Since
8945 1.2
8946
8947 qom-list (Command)
8948 This command will list any properties of a object given a path in the
8949 object model.
8950
8951 Arguments
8952 path: string
8953 the path within the object model. See qom-get for a description
8954 of this parameter.
8955
8956 Returns
8957 a list of ObjectPropertyInfo that describe the properties of the ob‐
8958 ject.
8959
8960 Since
8961 1.2
8962
8963 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
8971 qom-get (Command)
8972 This command will get a property from a object model path and return
8973 the value.
8974
8975 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
8980 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
8985 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
8994 property: string
8995 The property name to read
8996
8997 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
9002 Since
9003 1.2
9004
9005 Example
9006 1. Use absolute path
9007
9008 -> { "execute": "qom-get",
9009 "arguments": { "path": "/machine/unattached/device[0]",
9010 "property": "hotplugged" } }
9011 <- { "return": false }
9012
9013 2. Use partial path
9014
9015 -> { "execute": "qom-get",
9016 "arguments": { "path": "unattached/sysbus",
9017 "property": "type" } }
9018 <- { "return": "System" }
9019
9020 qom-set (Command)
9021 This command will set a property from a object model path.
9022
9023 Arguments
9024 path: string
9025 see qom-get for a description of this parameter
9026
9027 property: string
9028 the property name to set
9029
9030 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
9034 Since
9035 1.2
9036
9037 Example
9038 -> { "execute": "qom-set",
9039 "arguments": { "path": "/machine",
9040 "property": "graphics",
9041 "value": false } }
9042 <- { "return": {} }
9043
9044 ObjectTypeInfo (Object)
9045 This structure describes a search result from qom-list-types
9046
9047 Members
9048 name: string
9049 the type name found in the search
9050
9051 abstract: boolean (optional)
9052 the type is abstract and can't be directly instantiated. Omit‐
9053 ted if false. (since 2.10)
9054
9055 parent: string (optional)
9056 Name of parent type, if any (since 2.10)
9057
9058 Since
9059 1.1
9060
9061 qom-list-types (Command)
9062 This command will return a list of types given search parameters
9063
9064 Arguments
9065 implements: string (optional)
9066 if specified, only return types that implement this type name
9067
9068 abstract: boolean (optional)
9069 if true, include abstract types in the results
9070
9071 Returns
9072 a list of ObjectTypeInfo or an empty list if no results are found
9073
9074 Since
9075 1.1
9076
9077 qom-list-properties (Command)
9078 List properties associated with a QOM object.
9079
9080 Arguments
9081 typename: string
9082 the type name of an object
9083
9084 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
9089 Returns
9090 a list of ObjectPropertyInfo describing object properties
9091
9092 Since
9093 2.12
9094
9095 CanHostSocketcanProperties (Object)
9096 Properties for can-host-socketcan objects.
9097
9098 Members
9099 if: string
9100 interface name of the host system CAN bus to connect to
9101
9102 canbus: string
9103 object ID of the can-bus object to connect to the host interface
9104
9105 Since
9106 2.12
9107
9108 ColoCompareProperties (Object)
9109 Properties for colo-compare objects.
9110
9111 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
9116 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
9121 outdev: string
9122 name of the character device backend to use for output
9123
9124 iothread: string
9125 name of the iothread to run in
9126
9127 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
9131 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
9136 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
9140 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
9146 vnet_hdr_support: boolean (optional)
9147 if true, vnet header support is enabled (default: false)
9148
9149 Since
9150 2.8
9151
9152 CryptodevBackendProperties (Object)
9153 Properties for cryptodev-backend and cryptodev-backend-builtin objects.
9154
9155 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
9161 Since
9162 2.8
9163
9164 CryptodevVhostUserProperties (Object)
9165 Properties for cryptodev-vhost-user objects.
9166
9167 Members
9168 chardev: string
9169 the name of a Unix domain socket character device that connects
9170 to the vhost-user server
9171
9172 The members of CryptodevBackendProperties
9173
9174 Since
9175 2.12
9176
9177 DBusVMStateProperties (Object)
9178 Properties for dbus-vmstate objects.
9179
9180 Members
9181 addr: string
9182 the name of the DBus bus to connect to
9183
9184 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
9188 Since
9189 5.0
9190
9191 NetfilterInsert (Enum)
9192 Indicates where to insert a netfilter relative to a given other filter.
9193
9194 Values
9195 before insert before the specified filter
9196
9197 behind insert behind the specified filter
9198
9199 Since
9200 5.0
9201
9202 NetfilterProperties (Object)
9203 Properties for objects of classes derived from netfilter.
9204
9205 Members
9206 netdev: string
9207 id of the network device backend to filter
9208
9209 queue: NetFilterDirection (optional)
9210 indicates which queue(s) to filter (default: all)
9211
9212 status: string (optional)
9213 indicates whether the filter is enabled ("on") or disabled
9214 ("off") (default: "on")
9215
9216 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
9225 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
9230 Since
9231 2.5
9232
9233 FilterBufferProperties (Object)
9234 Properties for filter-buffer objects.
9235
9236 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
9241 The members of NetfilterProperties
9242
9243 Since
9244 2.5
9245
9246 FilterDumpProperties (Object)
9247 Properties for filter-dump objects.
9248
9249 Members
9250 file: string
9251 the filename where the dumped packets should be stored
9252
9253 maxlen: int (optional)
9254 maximum number of bytes in a packet that are stored (default:
9255 65536)
9256
9257 The members of NetfilterProperties
9258
9259 Since
9260 2.5
9261
9262 FilterMirrorProperties (Object)
9263 Properties for filter-mirror objects.
9264
9265 Members
9266 outdev: string
9267 the name of a character device backend to which all incoming
9268 packets are mirrored
9269
9270 vnet_hdr_support: boolean (optional)
9271 if true, vnet header support is enabled (default: false)
9272
9273 The members of NetfilterProperties
9274
9275 Since
9276 2.6
9277
9278 FilterRedirectorProperties (Object)
9279 Properties for filter-redirector objects.
9280
9281 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
9284 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
9289 outdev: string (optional)
9290 the name of a character device backend to which all incoming
9291 packets are redirected
9292
9293 vnet_hdr_support: boolean (optional)
9294 if true, vnet header support is enabled (default: false)
9295
9296 The members of NetfilterProperties
9297
9298 Since
9299 2.6
9300
9301 FilterRewriterProperties (Object)
9302 Properties for filter-rewriter objects.
9303
9304 Members
9305 vnet_hdr_support: boolean (optional)
9306 if true, vnet header support is enabled (default: false)
9307
9308 The members of NetfilterProperties
9309
9310 Since
9311 2.8
9312
9313 InputBarrierProperties (Object)
9314 Properties for input-barrier objects.
9315
9316 Members
9317 name: string
9318 the screen name as declared in the screens section of bar‐
9319 rier.conf
9320
9321 server: string (optional)
9322 hostname of the Barrier server (default: "localhost")
9323
9324 port: string (optional)
9325 TCP port of the Barrier server (default: "24800")
9326
9327 x-origin: string (optional)
9328 x coordinate of the leftmost pixel on the guest screen (default:
9329 "0")
9330
9331 y-origin: string (optional)
9332 y coordinate of the topmost pixel on the guest screen (default:
9333 "0")
9334
9335 width: string (optional)
9336 the width of secondary screen in pixels (default: "1920")
9337
9338 height: string (optional)
9339 the height of secondary screen in pixels (default: "1080")
9340
9341 Since
9342 4.2
9343
9344 InputLinuxProperties (Object)
9345 Properties for input-linux objects.
9346
9347 Members
9348 evdev: string
9349 the path of the host evdev device to use
9350
9351 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
9355 repeat: boolean (optional)
9356 enables auto-repeat events (default: false)
9357
9358 grab-toggle: GrabToggleKeys (optional)
9359 the key or key combination that toggles device grab (default:
9360 ctrl-ctrl)
9361
9362 Since
9363 2.6
9364
9365 IothreadProperties (Object)
9366 Properties for iothread objects.
9367
9368 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
9374 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
9379 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
9384 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
9389 Since
9390 2.0
9391
9392 MemoryBackendProperties (Object)
9393 Properties for objects of classes derived from memory-backend.
9394
9395 Members
9396 merge: boolean (optional)
9397 if true, mark the memory as mergeable (default depends on the
9398 machine type)
9399
9400 dump: boolean (optional)
9401 if true, include the memory in core dumps (default depends on
9402 the machine type)
9403
9404 host-nodes: array of int (optional)
9405 the list of NUMA host nodes to bind the memory to
9406
9407 policy: HostMemPolicy (optional)
9408 the NUMA policy (default: 'default')
9409
9410 prealloc: boolean (optional)
9411 if true, preallocate memory (default: false)
9412
9413 prealloc-threads: int (optional)
9414 number of CPU threads to use for prealloc (default: 1)
9415
9416 share: boolean (optional)
9417 if false, the memory is private to QEMU; if true, it is shared
9418 (default: false)
9419
9420 reserve: boolean (optional)
9421 if true, reserve swap space (or huge pages) if applicable (de‐
9422 fault: true) (since 6.1)
9423
9424 size: int
9425 size of the memory region in bytes
9426
9427 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
9434 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
9441 Since
9442 2.1
9443
9444 MemoryBackendFileProperties (Object)
9445 Properties for memory-backend-file objects.
9446
9447 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
9457 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
9464 mem-path: string
9465 the path to either a shared memory or huge page filesystem mount
9466
9467 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
9472 readonly: boolean (optional)
9473 if true, the backing file is opened read-only; if false, it is
9474 opened read-write. (default: false)
9475
9476 The members of MemoryBackendProperties
9477
9478 Since
9479 2.1
9480
9481 MemoryBackendMemfdProperties (Object)
9482 Properties for memory-backend-memfd objects.
9483
9484 The share boolean option is true by default with memfd.
9485
9486 Members
9487 hugetlb: boolean (optional)
9488 if true, the file to be created resides in the hugetlbfs
9489 filesystem (default: false)
9490
9491 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
9497 seal: boolean (optional)
9498 if true, create a sealed-file, which will block further resizing
9499 of the memory (default: true)
9500
9501 The members of MemoryBackendProperties
9502
9503 Since
9504 2.12
9505
9506 PrManagerHelperProperties (Object)
9507 Properties for pr-manager-helper objects.
9508
9509 Members
9510 path: string
9511 the path to a Unix domain socket for connecting to the external
9512 helper
9513
9514 Since
9515 2.11
9516
9517 QtestProperties (Object)
9518 Properties for qtest objects.
9519
9520 Members
9521 chardev: string
9522 the chardev to be used to receive qtest commands on.
9523
9524 log: string (optional)
9525 the path to a log file
9526
9527 Since
9528 6.0
9529
9530 RemoteObjectProperties (Object)
9531 Properties for x-remote-object objects.
9532
9533 Members
9534 fd: string
9535 file descriptor name previously passed via 'getfd' command
9536
9537 devid: string
9538 the id of the device to be associated with the file descriptor
9539
9540 Since
9541 6.0
9542
9543 RngProperties (Object)
9544 Properties for objects of classes derived from rng.
9545
9546 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
9552 Features
9553 deprecated
9554 Member opened is deprecated. Setting true doesn't make sense,
9555 and false is already the default.
9556
9557 Since
9558 1.3
9559
9560 RngEgdProperties (Object)
9561 Properties for rng-egd objects.
9562
9563 Members
9564 chardev: string
9565 the name of a character device backend that provides the connec‐
9566 tion to the RNG daemon
9567
9568 The members of RngProperties
9569
9570 Since
9571 1.3
9572
9573 RngRandomProperties (Object)
9574 Properties for rng-random objects.
9575
9576 Members
9577 filename: string (optional)
9578 the filename of the device on the host to obtain entropy from
9579 (default: "/dev/urandom")
9580
9581 The members of RngProperties
9582
9583 Since
9584 1.3
9585
9586 SevGuestProperties (Object)
9587 Properties for sev-guest objects.
9588
9589 Members
9590 sev-device: string (optional)
9591 SEV device to use (default: "/dev/sev")
9592
9593 dh-cert-file: string (optional)
9594 guest owners DH certificate (encoded with base64)
9595
9596 session-file: string (optional)
9597 guest owners session parameters (encoded with base64)
9598
9599 policy: int (optional)
9600 SEV policy value (default: 0x1)
9601
9602 handle: int (optional)
9603 SEV firmware handle (default: 0)
9604
9605 cbitpos: int (optional)
9606 C-bit location in page table entry (default: 0)
9607
9608 reduced-phys-bits: int
9609 number of bits in physical addresses that become unavailable
9610 when SEV is enabled
9611
9612 Since
9613 2.12
9614
9615 ObjectType (Enum)
9616 Values
9617 authz-list
9618 Not documented
9619
9620 authz-listfile
9621 Not documented
9622
9623 authz-pam
9624 Not documented
9625
9626 authz-simple
9627 Not documented
9628
9629 can-bus
9630 Not documented
9631
9632 can-host-socketcan
9633 Not documented
9634
9635 colo-compare
9636 Not documented
9637
9638 cryptodev-backend
9639 Not documented
9640
9641 cryptodev-backend-builtin
9642 Not documented
9643
9644 cryptodev-vhost-user (If: defined(CONFIG_VHOST_CRYPTO))
9645 Not documented
9646
9647 dbus-vmstate
9648 Not documented
9649
9650 filter-buffer
9651 Not documented
9652
9653 filter-dump
9654 Not documented
9655
9656 filter-mirror
9657 Not documented
9658
9659 filter-redirector
9660 Not documented
9661
9662 filter-replay
9663 Not documented
9664
9665 filter-rewriter
9666 Not documented
9667
9668 input-barrier
9669 Not documented
9670
9671 input-linux
9672 Not documented
9673
9674 iothread
9675 Not documented
9676
9677 memory-backend-file
9678 Not documented
9679
9680 memory-backend-memfd (If: defined(CONFIG_LINUX))
9681 Not documented
9682
9683 memory-backend-ram
9684 Not documented
9685
9686 pef-guest
9687 Not documented
9688
9689 pr-manager-helper
9690 Not documented
9691
9692 qtest Not documented
9693
9694 rng-builtin
9695 Not documented
9696
9697 rng-egd
9698 Not documented
9699
9700 rng-random
9701 Not documented
9702
9703 secret Not documented
9704
9705 secret_keyring
9706 Not documented
9707
9708 sev-guest
9709 Not documented
9710
9711 s390-pv-guest
9712 Not documented
9713
9714 throttle-group
9715 Not documented
9716
9717 tls-creds-anon
9718 Not documented
9719
9720 tls-creds-psk
9721 Not documented
9722
9723 tls-creds-x509
9724 Not documented
9725
9726 tls-cipher-suites
9727 Not documented
9728
9729 x-remote-object
9730 Not documented
9731
9732 Since
9733 6.0
9734
9735 ObjectOptions (Object)
9736 Describes the options of a user creatable QOM object.
9737
9738 Members
9739 qom-type: ObjectType
9740 the class name for the object to be created
9741
9742 id: string
9743 the name of the new object
9744
9745 The members of AuthZListProperties when qom-type is "authz-list"
9746
9747 The members of AuthZListFileProperties when qom-type is "authz-list‐
9748 file"
9749
9750 The members of AuthZPAMProperties when qom-type is "authz-pam"
9751
9752 The members of AuthZSimpleProperties when qom-type is "authz-simple"
9753
9754 The members of CanHostSocketcanProperties when qom-type is
9755 "can-host-socketcan"
9756
9757 The members of ColoCompareProperties when qom-type is "colo-compare"
9758
9759 The members of CryptodevBackendProperties when qom-type is "cryp‐
9760 todev-backend"
9761
9762 The members of CryptodevBackendProperties when qom-type is "cryp‐
9763 todev-backend-builtin"
9764
9765 The members of CryptodevVhostUserProperties when qom-type is "cryp‐
9766 todev-vhost-user" (If: defined(CONFIG_VHOST_CRYPTO))
9767
9768 The members of DBusVMStateProperties when qom-type is "dbus-vmstate"
9769
9770 The members of FilterBufferProperties when qom-type is "filter-buffer"
9771
9772 The members of FilterDumpProperties when qom-type is "filter-dump"
9773
9774 The members of FilterMirrorProperties when qom-type is "filter-mirror"
9775
9776 The members of FilterRedirectorProperties when qom-type is "fil‐
9777 ter-redirector"
9778
9779 The members of NetfilterProperties when qom-type is "filter-replay"
9780
9781 The members of FilterRewriterProperties when qom-type is "fil‐
9782 ter-rewriter"
9783
9784 The members of InputBarrierProperties when qom-type is "input-barrier"
9785
9786 The members of InputLinuxProperties when qom-type is "input-linux"
9787
9788 The members of IothreadProperties when qom-type is "iothread"
9789
9790 The members of MemoryBackendFileProperties when qom-type is "mem‐
9791 ory-backend-file"
9792
9793 The members of MemoryBackendMemfdProperties when qom-type is "mem‐
9794 ory-backend-memfd" (If: defined(CONFIG_LINUX))
9795
9796 The members of MemoryBackendProperties when qom-type is "memory-back‐
9797 end-ram"
9798
9799 The members of PrManagerHelperProperties when qom-type is "pr-man‐
9800 ager-helper"
9801
9802 The members of QtestProperties when qom-type is "qtest"
9803
9804 The members of RngProperties when qom-type is "rng-builtin"
9805
9806 The members of RngEgdProperties when qom-type is "rng-egd"
9807
9808 The members of RngRandomProperties when qom-type is "rng-random"
9809
9810 The members of SecretProperties when qom-type is "secret"
9811
9812 The members of SecretKeyringProperties when qom-type is "se‐
9813 cret_keyring"
9814
9815 The members of SevGuestProperties when qom-type is "sev-guest"
9816
9817 The members of ThrottleGroupProperties when qom-type is "throt‐
9818 tle-group"
9819
9820 The members of TlsCredsAnonProperties when qom-type is "tls-creds-anon"
9821
9822 The members of TlsCredsPskProperties when qom-type is "tls-creds-psk"
9823
9824 The members of TlsCredsX509Properties when qom-type is "tls-creds-x509"
9825
9826 The members of TlsCredsProperties when qom-type is "tls-cipher-suites"
9827
9828 The members of RemoteObjectProperties when qom-type is "x-remote-ob‐
9829 ject"
9830
9831 Since
9832 6.0
9833
9834 object-add (Command)
9835 Create a QOM object.
9836
9837 Arguments
9838 The members of ObjectOptions
9839
9840 Returns
9841 Nothing on success Error if qom-type is not a valid class name
9842
9843 Since
9844 2.0
9845
9846 Example
9847 -> { "execute": "object-add",
9848 "arguments": { "qom-type": "rng-random", "id": "rng1",
9849 "filename": "/dev/hwrng" } }
9850 <- { "return": {} }
9851
9852 object-del (Command)
9853 Remove a QOM object.
9854
9855 Arguments
9856 id: string
9857 the name of the QOM object to remove
9858
9859 Returns
9860 Nothing on success Error if id is not a valid id for a QOM object
9861
9862 Since
9863 2.0
9864
9865 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
9873 Since
9874 1.6
9875
9876 ActionCompletionMode (Enum)
9877 An enumeration of Transactional completion modes.
9878
9879 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
9886 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
9892 Since
9893 2.5
9894
9895 TransactionAction (Object)
9896 A discriminated record of operations that can be performed with trans‐
9897 action. Action type can be:
9898
9899 • abort: since 1.6
9900
9901 • block-dirty-bitmap-add: since 2.5
9902
9903 • block-dirty-bitmap-remove: since 4.2
9904
9905 • block-dirty-bitmap-clear: since 2.5
9906
9907 • block-dirty-bitmap-enable: since 4.0
9908
9909 • block-dirty-bitmap-disable: since 4.0
9910
9911 • block-dirty-bitmap-merge: since 4.0
9912
9913 • blockdev-backup: since 2.3
9914
9915 • blockdev-snapshot: since 2.5
9916
9917 • blockdev-snapshot-internal-sync: since 1.7
9918
9919 • blockdev-snapshot-sync: since 1.1
9920
9921 • drive-backup: since 1.6
9922
9923 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
9930 data: Abort when type is "abort"
9931
9932 data: BlockDirtyBitmapAdd when type is "block-dirty-bitmap-add"
9933
9934 data: BlockDirtyBitmap when type is "block-dirty-bitmap-remove"
9935
9936 data: BlockDirtyBitmap when type is "block-dirty-bitmap-clear"
9937
9938 data: BlockDirtyBitmap when type is "block-dirty-bitmap-enable"
9939
9940 data: BlockDirtyBitmap when type is "block-dirty-bitmap-disable"
9941
9942 data: BlockDirtyBitmapMerge when type is "block-dirty-bitmap-merge"
9943
9944 data: BlockdevBackup when type is "blockdev-backup"
9945
9946 data: BlockdevSnapshot when type is "blockdev-snapshot"
9947
9948 data: BlockdevSnapshotInternal when type is "blockdev-snapshot-inter‐
9949 nal-sync"
9950
9951 data: BlockdevSnapshotSync when type is "blockdev-snapshot-sync"
9952
9953 data: DriveBackup when type is "drive-backup"
9954
9955 Since
9956 1.1
9957
9958 TransactionProperties (Object)
9959 Optional arguments to modify the behavior of a Transaction.
9960
9961 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
9966 Since
9967 2.5
9968
9969 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
9974 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
9978 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
9985 On failure, the original disks pre-snapshot attempt will be used.
9986
9987 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
9992 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
9996 Arguments
9997 actions: array of TransactionAction
9998 List of TransactionAction; information needed for the respective
9999 operations.
10000
10001 properties: TransactionProperties (optional)
10002 structure of additional options to control the execution of the
10003 transaction. See TransactionProperties for additional detail.
10004
10005 Returns
10006 nothing on success
10007
10008 Errors depend on the operations of the transaction
10009
10010 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
10015 Since
10016 1.1
10017
10018 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
10040
10041
10042
10043
100446.1.0 Nov 08, 2021 QEMU-STORAGE-DAEMON-QMP-REF(7)